lamina typescript.instructions.md

TypeScript Coding Guidelines & Modern Features (v5.0 - v5.8)

When writing TypeScript code, prioritize using modern features and best practices introduced in recent versions (up to 5.8).

Global Themes Across 5.x

1. Standard decorators are here; legacy decorators are legacy. New TC39-compliant decorators landed in 5.0 and were extended in 5.2 (metadata). Old experimentalDecorators-style behavior is still supported but should be treated as legacy.

2. Type system is more precise and less noisy. Major work went into narrowing, control flow analysis, error messages, and new helpers like NoInfer, inferred predicates, and better undefined/never/uninitialized checks.

3. Module / runtime interop has been modernized. Options like --moduleResolution bundler, --module nodenext/node18, --rewriteRelativeImportExtensions, --erasableSyntaxOnly, and --verbatimModuleSyntax are about playing nicely with ESM, Node 18+/22+, direct TypeScript execution, and bundlers.

4. The standard library keeps tracking modern JS. Support for new ES features (iterator helpers, Object.groupBy/Map.groupBy, new Set/ES2024 APIs) shows up as type declarations and sometimes extra checks (regex syntax checking, etc.).

When generating or refactoring code, prefer these newer idioms, and avoid patterns that conflict with updated checks.

Modern Features to Utilize

Type System & Inference

• const Type Parameters (5.0): Use const type parameters for more precise literal inference.

  declare function names<const T extends string[]>(...names: T): void;
  

• @satisfies Operator (5.0): Use satisfies to validate types without widening them.
• Inferred Type Predicates (5.5): Allow TypeScript to infer type predicates for functions that filter arrays or check types, reducing the need for explicit is return types.
• NoInfer Utility (5.4): Use NoInfer<T> to block inference for specific type arguments when you want them to be determined by other arguments.
• Narrowing:
  • Switch(true) (5.3): Utilize narrowing in switch(true) blocks.
  • Boolean Comparisons (5.3): Rely on narrowing from direct boolean comparisons.
  • Closures (5.4): Trust preserved narrowing in closures when variables aren't modified after the check.
  • Constant Indexed Access (5.5): Use constant indices to narrow object/array properties.