Typescript Language

TypeScript Language Patterns

Priority: P0 (Critical)

Implementation Guidelines

• Type annotations: Explicit params and return types; infer locals.
• Interfaces vs types: interface for object shapes and APIs; type for unions, intersections, and aliases.
• Strict mode: Use strict: true. Null safety: optional chaining ?. and nullish coalescing ??.
• Enums: Prefer literal unions or as const; avoid runtime enum.
• Generics: Use for reusable, type-safe code.
• Type guards: Use typeof, instanceof, or user-defined type predicates.
• Utility types: Use Partial, Pick, Omit, Record and custom utilities as needed.
• Immutability: Prefer readonly arrays/objects; use const assertions as const and satisfies.
• Template literal types: Use for patterns like on${Capitalize}.
• Discriminated unions: Use a literal kind (or similar) property to discriminate.
• Advanced: Mapped, conditional, and indexed access types when appropriate.
• Access: Default public; use private/protected or #private when needed.
• Branded types: Use for nominal typing, e.g. string & { __brand: 'Id' }.

Anti-Patterns

• No any: Use unknown or specific types; never any.
• No Function: Use concrete signatures, e.g. () => void.
• No runtime enum: Use union types or as const to avoid runtime cost.
• No non-null assertion !: Use proper narrowing instead.
• No lint disables: Do not use eslint-disable or ts-ignore; fix issues properly.

Testing Patterns

• Mock types: Use jest.Mocked or as unknown as T; never any.
• Enums: Use enum values (e.g. AppointmentStatus.UPCOMING) not string literals where the type is an enum.
• DTOs: Ensure test data includes all required fields expected by DTOs.
• Repository mocks: Mock every repository method used by the code under test (findOne, create, save, findAndCount, createQueryBuilder, etc.).

Common Test Issues

| Problem | Solution | | --------------------------------- | ------------------------------------------------------------------------------------------ | | Service method name mismatch | Check implementation and mock the methods actually called. | | Error message mismatch | Use exact messages from shared constants (e.g. ErrorMessages). | | Mock missing required properties | Provide full mocks or use as unknown as Type for complex cases. | | CurrentUser incomplete in mocks | Include all required fields (id, email, subscriptionTier, createdAt, updatedAt). | | Auth/guard mocks failing | Provide complete service mocks (e.g. logger, userRepository) or cast via unknown. | | Wrong controller params | Match decorators (e.g. @CurrentUserDecorator()) and pass the correct types. |

Quick Reference

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

// satisfies: validate shape and infer
const cfg = { port: 3000 } satisfies Record;

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

Additional Resources

For advanced type patterns and utility types, see [reference.md](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: cuonglph11
• Source: cuonglph11/mini-chris
• License: MIT

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