typescript-coding

TypeScript Coding

Match the project's existing conventions. When uncertain, read 2-3 existing files to infer the local style. Check tsconfig.json for strict mode, target, module, and moduleResolution settings. Check package.json for runtime (Node.js, Deno, Bun) and dependency versions. These defaults apply only when the project has no established convention.

Never rules

These are unconditional. They prevent bugs and vulnerabilities regardless of project style.

• Never use any — contagious type erasure that disables all downstream checking. Use unknown and narrow with type guards, or use generics with constraints.
• Never use @ts-ignore — permanently suppresses errors with no feedback when conditions change. Use @ts-expect-error with a justification comment; it fails the build when the suppressed error disappears.
• Never use as type assertions on external data — zero runtime validation; the program continues with corrupted state until it crashes far from the source. Validate at system boundaries with Zod safeParse or equivalent runtime validators.
• Never use ! non-null assertion without proof — tells TypeScript a value is not null without any runtime check. Use nullish coalescing (??), optional chaining (?.), or explicit if checks.
• Never leave a Promise floating — unhandled rejections cause silent failures or process termination. Always await, chain .catch(), or prefix with void and add an error handler.
• Never mutate function parameters — objects and arrays are passed by reference; mutation silently corrupts the caller's data. Spread or structuredClone() before mutating. Mark parameters readonly.
• Never use delete on typed objects — violates the type contract, creating objects that no longer match their type. Destructure to omit properties (const { removed, ...rest } = obj). For arrays, use splice() or filter().
• Never use export * in barrel files — re-exported names collide silently across modules, and IDE navigation and refactoring degrade (go-to-definition lands on the barrel, renames miss consumers). Use explicit named re-exports.
• Never omit type on type-only imports — retains unnecessary import statements in compiled output, bloats bundles, and breaks isolated transpilers. Use import type { } or inline type qualifiers. Enable verbatimModuleSyntax.
• Never use enum — emits runtime IIFE code, introduces nominal typing friction, and numeric enums silently accept any number. Use as const objects with derived union types.
• Never trust array index access without noUncheckedIndexedAccess — TypeScript types items[0] as T even when the array could be empty. Enable noUncheckedIndexedAccess: true in tsconfig.
• Never skip exhaustiveness checks in switch/union handling — adding a new union member silently falls through without a compile error. Add a default case that assigns to never: const _exhaustive: never = value.
• Never use JSON.parse() without runtime validation at system boundaries — returns any, and assigning to a typed variable provides zero runtime guarantees. Validate with Zod safeParse or equivalent.