contexture typescript.instructions.md

typescript rules

Auto-loaded by Copilot when editing files matching **/*.{ts,tsx}. Generated from architectural-rules/typescript/ — do not hand-edit.

TypeScript async

Never leave a promise floating — await it, return it, or explicitly void it. An unawaited promise drops its rejection on the floor (unhandled rejection) and breaks ordering assumptions. Prefer async/await over .then() chains for sequential work — flatter, debuggable, and error handling is one try/catch instead of scattered .catch(). Type async returns as Promise<T> explicitly on public APIs. Let the caller see the contract without inferring it. Do not pass an async callback where a synchronous one is expected (Array.forEach, most event handlers) — the returned promise is ignored and errors vanish. Use for...of with await, or Promise.all(map(...)).

Why: floating promises and async-callback-in-forEach are the two patterns that silently swallow async errors in TS — they look correct and fail invisibly. Source: TypeScript Handbook, typescript-eslint rules.

TypeScript modules

Prefer named exports over default exports. Named exports are refactor-safe (rename propagates), discoverable by autocomplete, and avoid the "default-export sprawl" where every file's main thing is anonymously default. Use configured path aliases (@/domain/...) instead of deep relative chains (../../../..). Relative-depth churn on every move is friction the bundler can erase. No circular module dependencies. They cause undefined-at-import-time bugs that depend on evaluation order. Break the cycle by extracting the shared piece. Use import type { X } for type-only imports — it is erased at compile time and prevents accidental runtime coupling / side-effect imports.

Why: default exports defeat rename-refactoring and circular deps produce order-dependent undefined that reproduces only sometimes — both are structural, not stylistic. Source: TypeScript Handbook, Google TypeScript Style Guide.