Typescript Language

TypeScript Language Patterns

Priority: P0 (CRITICAL)

Implementation Guidelines

• Type Annotations: Explicit params/returns. Infer locals.
• Interfaces vs Types: interface for APIs (supports declaration merging). type for unions, intersection types, mapped/conditional types.
• Strict Mode: strict: true. Null Safety: ?. and ?? — Use narrowing instead. Avoid non-null assertion (!) operator.
• Enums: Literal unions or as const. No runtime enum.
• Generics: Reusable, type-safe code.
• Type Guards: typeof, instanceof, predicates.
• Utility Types: Partial, Pick, Omit, Record.
• Immutability: readonly arrays/objects. Const Assertions: as const, satisfies.
• Template Literals: on${Capitalize}.
• Discriminated Unions: Literal kind property to narrow type safely. Switch on discriminant.
• Advanced: Mapped, Conditional, Indexed types.
• Access: Default public. Use private/protected or #private.
• Branded Types: string & { __brand: 'Id' }.

Anti-Patterns

• NEVER use any: Use unknown or specific interface instead.
• No Function: Use signature () => void.
• No enum: Runtime cost.
• No !: Avoid non-null assertion (!). Use narrowing (typeof, instanceof, if-checks).
• No Lint Disable: Fix root cause; never suppress.

Testing

• Mocking: Use jest.Mocked or as unknown as T.
• Checklist: Check method existence, match error constants, satisfy required properties.
• References: See [references/TESTING.md](references/TESTING.md) for common issues/solutions.

Code

// Branded Type
type UserId = string & { __brand: 'Id' };

// Satisfies (Validate + Infer)
const cfg = { port: 3000 } satisfies Record;

// Discriminated Union
type Result = { kind: 'ok'; data: T } | { kind: 'err'; error: Error };

Verification

After any type change that crosses module boundaries or involves generics, unions, conditional types, or branded types: call getDiagnostics (typescript-lsp MCP tool) to confirm no type errors before finalizing.

References

For advanced type patterns and utility types: See [references/REFERENCE.md](references/REFERENCE.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HoangNguyen0403
• Source: HoangNguyen0403/agent-skills-standard
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/agent-skills-standard

Install and usage instructions live in the source repository linked above.