typescript-advanced-patterns

TypeScript Advanced Patterns Best Practices

Type-level programming, library-author idioms, and feature-implementation patterns that go beyond surface uses of TypeScript 5.x. Contains 40 rules across 5 categories, prioritised by impact on consumer codebases.

When to Apply

Reference these guidelines when:

• Designing a public library or DSL surface (fluent builders, event emitters, route parsers, query builders, schema-derived clients)
• Writing type-level algorithms (recursive conditionals, accumulator pattern, key remapping, variadic tuples, type-level string/number ops, type-level tests)
• Using TS 5.x features in non-trivial ways (Stage 3 decorators, using composition, const T for overload disambiguation, NoInfer for anchor-vs-constrained parameters, variance annotations, the bivariance hole)
• Encoding workflow state, transitions, and capabilities at the type level so illegal states and missing checks are compile errors
• Integrating with the declaration & module system (module augmentation, declaration merging, ambient asset modules, library type publishing via exports/typesVersions)

Boundary with neighbouring skills

Skill	Don't reach for this skill if you need…
typescript (curated)	Compiler performance / tsconfig tuning
typescript-refactor	General refactoring patterns and modern-TS surface basics
ts-google	Google-style code style decisions
clean-code-ts-react	Clean-code principles (naming, function shape, abstraction)
effect-ts / opencode-ts	Effect library-specific patterns

If a rule in this skill overlaps with one in typescript-refactor or .curated/typescript, the rule's Scope delta section names what this skill adds beyond the simpler version.

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Library Author / DSL Patterns	CRITICAL	dsl-	8
2	Type-level Programming	HIGH	tlp-	10
3	Modern Features at Depth	HIGH	mod-	8
4	Feature Implementation Patterns	MEDIUM-HIGH	impl-	8
5	Declaration & Module System	MEDIUM	decl-	6

Quick Reference

1. Library Author / DSL Patterns (CRITICAL)

• dsl-fluent-builder-phantom-state — Enforce builder call order with phantom state types
• dsl-typed-event-emitter — Build typed event emitters with mapped event maps
• dsl-type-safe-object-paths — Type object path access with dot-notation inference
• dsl-route-param-inference — Infer route parameters from path patterns
• dsl-schema-first-inference — Derive static types from runtime schemas
• dsl-type-safe-query-builder — Encode query shape in the builder's return type
• dsl-narrow-api-surface — Export only the API surface, not internal helpers
• dsl-overloads-vs-conditional-returns — Choose overloads over conditional return types

2. Type-level Programming (HIGH)

• tlp-recursive-conditional-types — Use recursive conditional types for structural transformations
• tlp-tail-recursion-accumulator — Use tail-recursion accumulator pattern to bypass the 50-step limit
• tlp-infer-extends-constraints — Constrain infer with extends for validated extraction
• tlp-key-remapping-as — Remap keys with as clauses in mapped types
• tlp-variadic-tuple-types — Use variadic tuples for position-aware type algorithms
• tlp-type-level-string-algorithms — Build type-level string algorithms with recursive template literals
• tlp-distributive-conditional-control — Control distribution with the [T] extends [U] tuple trick
• tlp-type-level-tests — Test types with Equal, Expect, and @ts-expect-error
• tlp-template-literal-pattern-matching — Match structured strings with infer in template literals
• tlp-hkt-emulation — Emulate higher-kinded types with interface dictionaries

3. Modern Features at Depth (HIGH)

• mod-stage-3-decorators — Use Stage 3 decorators with decorator context for metaprogramming
• mod-using-disposal-ordering — Compose using resources with explicit disposal ordering
• mod-const-type-params-overloads — Use const T to preserve literals through overloaded APIs
• mod-noinfer-overload-disambiguation — Use NoInfer<T> to disambiguate overloaded function signatures
• mod-variance-debugging — Debug variance errors with in/out annotations
• mod-method-vs-property-bivariance — Prefer property syntax over method syntax to avoid bivariance holes
• mod-phantom-capability-tracking — Track capabilities at the type level with phantom brands
• mod-satisfies-branded-config — Combine satisfies with branded types for validated configuration

4. Feature Implementation Patterns (MEDIUM-HIGH)

• impl-tagged-result-type — Model operation outcomes as Ok<T> | Err<E> tagged unions
• impl-state-discriminated-union — Model workflow state as a discriminated union of state records
• impl-finite-state-machine — Encode FSM transitions in function signatures
• impl-schema-derived-api-client — Derive client argument and return types from endpoint schemas
• impl-type-safe-form-builder — Drive form-field inference from a single schema definition
• impl-phantom-feature-flags — Gate feature-dependent code with phantom capability types
• impl-assert-never-exhaustive — Use assertNever to force exhaustive handling of union variants
• impl-env-config-loader — Validate environment configuration at boundary with schema inference

5. Declaration & Module System (MEDIUM)

• decl-module-augmentation — Augment third-party module types without patching source
• decl-declaration-merging — Merge interface, namespace, and class declarations to extend APIs
• decl-ambient-asset-modules — Declare ambient modules for non-TypeScript asset imports
• decl-global-augmentation-discipline — Scope global type augmentation to avoid conflicts
• decl-exports-and-types-versions — Ship library types with exports and typesVersions maps
• decl-authoring-d-ts-for-js — Author .d.ts files for plain JavaScript libraries

How to Use

Read individual reference files for detailed explanations, code examples, and "when NOT to apply" guidance:

• Section definitions — Category structure and impact levels
• Rule template — Template for adding new rules

Rules cross-link via [[other-rule-slug]]; follow them when a related pattern is referenced.

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information