# Typescript Best Practices

> TypeScript best practices. Use when reading or editing any .ts or .tsx file.

- Skill: `asymmetric-al/typescript-best-practices` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx get-skill add asymmetric-al/typescript-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asymmetric-al/typescript-best-practices/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: asymmetric-al (https://skillmd.com/u/asymmetric-al)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/asymmetric-al/typescript-best-practices

---


# TypeScript best practices

Apply the **type-system-discipline** principle skill first.

| Rule                  | Summary                                                                                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Discriminated unions  | Model variants with a `kind` literal discriminant so impossible states can't be represented. No optional-field bags.                                                                                           |
| Branded types         | Brand primitives with `& { readonly __brand: "X" }` so they can't be mixed up. Validate once at the boundary.                                                                                                  |
| Constructive modeling | Build the shape so the illegal value can't be constructed. `[T, ...T[]]` for non-empty, `[T, T][]` for even length, `start` plus `duration` for a range. Not a runtime guard, not a wish for refinement types. |
| Simplest total type   | Keep `T[]` while every operation on it stays total. Strengthen to `NonEmpty<T>` only where the loose type forces `!`, a cast, or a "should never happen" throw.                                                |
| `unknown` over `any`  | External data is `unknown`.                                                                                                                                                                                    |
| Schemas before guards | Before hand-writing a property-by-property type guard, use the repository's runtime schema library and infer the type from the schema, such as `z.infer`.                                                      |
| No `as` casts         | Every `as` is a runtime crash waiting. Cast only after validation.                                                                                                                                             |
| Narrowing hierarchy   | Discriminant switch > `in` operator > `typeof`/`instanceof` > user-defined type guard > `as`.                                                                                                                  |
| Type guards           | Must verify the claim. A lying guard is worse than `as` because the bug hides behind a name that says it's safe. Name them `isX` or `hasX`.                                                                    |
| Exhaustiveness        | Inline `const _exhaustive: never = x;` in default arms so the compiler errors when a new variant is added.                                                                                                     |
| `satisfies` over `as` | Validates the value without widening literal types.                                                                                                                                                            |
| Boundary validation   | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. See the **boundary-discipline** principle skill.                   |
| Schema-derived types  | Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface.                                                                                                         |
| Object args           | Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers).                                                                                |
| Real tests            | Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally.                                  |
| Structured telemetry  | Prefer structured logger diagnostics with enough context to debug from an id. No `console.log` in shipped code.                                                                                                |

Examples: `references/patterns.md`.

<!-- CORE-OVERLAY-START -->

## This repository (Asymmetric-al/core)

Vendored from [p3-stack](https://github.com/uzairansaruzi/p3-stack) (MIT) at commit `09909eb`. Provenance is in `references/upstream.md`. On conflict, the current user request, root `AGENTS.md`, the nearest nested `AGENTS.md`, and the matching `docs/ai/rules/*` rulebook win over this skill.

- Explicit invocation only: use it when the user invokes `/typescript-best-practices` (Claude Code, Cursor, T3 Code) or `$typescript-best-practices` (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.
- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.
- Core's `tsconfig` files, ESLint configuration, and `docs/ai/rules/typescript-future-proofing.md` win on conflict. Do not change compiler settings, lint rules, or dependencies because of this skill.

Edit this canonical copy in `docs/ai/skills/typescript-best-practices/`, then run `bun run skills:sync` and `bun run skills:verify`.

<!-- CORE-OVERLAY-END -->

