typescript-best-practices

Files (5)

• SKILL.md
• openai.yaml · agents/
• boundary-discipline.md · references/
• patterns.md · references/
• type-system-discipline.md · references/

SKILL.md (first lines)

# TypeScript best practices

Use TypeScript's type system to encode domain invariants. Read
[type-system discipline](references/type-system-discipline.md) when modeling
domain states or reviewing unsafe types. When the code accepts external data or
mixes business logic with I/O, also read
[boundary discipline](references/boundary-discipline.md).

| 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 creation.                                                                                                      |
| 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`. `any` disables type checking everywhere it touches.                                                                                                                                |
| 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   | Validate where data crosses in; trust domain types inside. Follow [boundary discipline](references/boundary-discipline.md).                                                                                    |
| 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`.

From waynegibson/poly-agent-harness, MIT.

More from waynegibson/poly-agent-harness