typescript-engineering

TypeScript Engineering

Produce TypeScript that is explicit at boundaries, narrow in surface area, and strict enough that refactors fail fast. Prefer inference inside small scopes, explicit types at module boundaries, runtime validation for external data, and simple control flow over clever type tricks.

Workflow

1. Identify the boundary. Library: optimize for stable public types, portability, and narrow exports. Application: optimize for operability, runtime validation, and maintainable module boundaries.
2. Model data before behavior. Prefer discriminated unions, branded/domain types, and small interfaces over optional-field soup.
3. Decide where trust begins. Treat network, env, file, CLI, and user input as unknown until validated.
4. Keep types and implementation aligned. Prefer deriving types from values and functions over duplicating parallel definitions.
5. Use async intentionally. Model failure and cancellation explicitly; avoid floating promises and hidden concurrency.
6. Verify before finalizing. Run the project’s formatter, linter, type checker, and tests. Treat type errors as design feedback.

Load References By Need

Need	Reference
Project shape, tsconfig, modules, exports, tooling	references/workflow.md
Boundary validation, error handling, async and promises	references/runtime-and-errors.md
API design, unions, narrowing, generics, utility types	references/types-and-api-design.md
React/TSX state, props, hooks, and event typing	references/react-and-tsx.md
Testing, mocks, fixtures, snapshots, review checklist	references/testing-and-quality.md
Performance, allocation, iteration, and common footguns	references/performance-and-footguns.md

Default Standards

• Enable strict mode and keep it on.
• Prefer unknown over any at trust boundaries.
• Validate external data at runtime before treating it as domain data.
• Prefer discriminated unions over boolean mode flags and optional-field matrices.
• Keep exports intentional. Avoid giant barrel files that hide ownership and increase coupling.
• Return typed domain values from core logic; isolate framework types at the edges.
• Use Promise<void> and await intentionally. Do not leave floating promises.
• Prefer stable, readable types over maximally clever conditional-type machinery.