hjemmesidekongen/typescript-modern

typescript-modern

Patterns beyond standard generics and narrowing — TS 5.4+ features, branded types, module augmentation, and type-level testing.

TS 5.4–5.7 Features

Inferred type predicates (5.5): Filter functions returning x !== null auto-narrow without is guards. NoInfer<T> (5.4): Blocks a parameter from contributing to inference. Use on fallback params: create<T>(value: T, fallback: NoInfer<T>). Const type parameters (5.0+): <const T> infers literal types without as const at call sites. Use for config factories. Isolated declarations (5.5): --isolatedDeclarations requires explicit return types on exports. Parallel .d.ts emit for monorepo packages.

Branded Types

Prevent domain confusion (UserId vs OrderId are both strings, but swapping is a bug):

type Brand<T, B> = T & { readonly __brand: B };
type UserId = Brand<string, 'UserId'>;
const toUserId = (s: string) => s as UserId;  // single controlled cast point

Brand at creation, accept branded types in signatures. One as cast at the entry point is acceptable.

Module Augmentation

Extend third-party types with declare module in .d.ts files under types/. Only extend, never override — if you need to change a field type, patch the library instead.

Type-Level Testing

// @ts-expect-error as assertion: next line must error or test fails. expectTypeOf (vitest) / expectType (tsd) for positive assertions. Run both in CI.

Key Rules

• Model state as what is true, not flags. Discriminated union > optional fields.
• satisfies preserves narrowest inference while constraining. Pair with as const.
• unknown for untrusted input. any only at seams you intend to replace.
• as is a compiler promise — if wrong, runtime crashes. Prefer narrowing or satisfies.

See references/process.md for conditional types, mapped types, infer, tsconfig options, and anti-patterns.