typescript-best-practices
Sixteen type-safety rules for writing and reviewing TypeScript, with do and don't examples in references/patterns.md. Use whenever you open or edit a .ts or .tsx file, or on /typescript-best-practices.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- typescript-best-practices
- description
- Sixteen type-safety rules for writing and reviewing TypeScript, with do and don't examples in references/patterns.md. Use whenever you open or edit a .ts or .tsx file, or on /typescript-best-practices.
- disable-model-invocation
- true
02 资源文件 1
- 参考文档references/patterns.md7.2 KB
03 SKILL.md 正文
typescript-best-practices
Read principle-type-system-discipline (../principle-type-system-discipline/SKILL.md) first. These rules apply it to TypeScript. references/patterns.md has a short code example for each rule, numbered to match.
If your agent supports path-scoped skills, attach this one to **/*.ts and **/*.tsx. Otherwise the router or the user loads it when TypeScript is in play. For other languages, use principle-type-system-discipline and principle-boundary-discipline (../principle-boundary-discipline/SKILL.md) directly.
Before you write anything, find the repo's existing conventions: its schema library, its logger, the name it uses for union tags, and the shape of its brand marker. Follow them over the examples in the reference.
Modeling
- Tagged unions for variants. Model alternative states as a union of object types that share one literal tag field. A boolean flag plus optional fields lets contradictory combinations exist (
loading: truewith anerrorset). Use one tag name across the codebase. - Branded primitives. Intersect a primitive with a readonly brand property so an
InvoiceIdcannot be passed where aCustomerIdis expected. Mint the brand only through a type guard that validates (value is InvoiceId) and a parse function that wraps the guard and throws on failure. Never brand withas. Check once where the value enters; downstream code trusts the brand. - Make illegal values unconstructible. Prefer a shape that cannot hold a bad value to a runtime check:
[T, ...T[]]for a non-empty list,Array<[K, V]>for paired data, a start plus a duration instead of start and end with an ordering invariant in a comment. Provide helpers for derived views (the computed end time). Brand the duration only if some unrelated number could be passed in its place. - Use the simplest type that keeps every operation total. A plain array is fine while every operation on it works for empty input (a sum of nothing is zero). Strengthen to non-empty only where the weak type forces a lie: a
!, an index cast, or an "unreachable" throw. Or widen the return type to includeundefined. Provide a guard so a plain array can be checked once and then carried as non-empty.
Untrusted data
- External data is
unknown, neverany. RPC payloads, parsed JSON,postMessageevents, IPC, files, environment variables, and database rows all arrive asunknownand get narrowed before use.anyturns off the checker exactly where an attacker controls the input. - Schemas before hand-written guards. Check whether the codebase uses a runtime validation library and already defines a schema for this data. Define one schema and infer the static type from it. Use the non-throwing parse call when bad input is an expected outcome (a user form), and the throwing one when it is a bug. Never add a validation library for one guard. If the static type already exists, annotate the schema with it so the compiler rejects a schema that checks less than the type promises.
- No
asexcept after validation. When you remove an assertion, find out why inference failed: add a missing discriminant, narrow a source typed asRecord<string, unknown>, parse at the untyped boundary with the owning schema, or, if the fact truly cannot be expressed, use a brand orsatisfies. - Narrow in this order, best first: switch on the tag; an
incheck;typeoforinstanceof; a custom guard; an assertion after validation. - Guards must check what they claim. A guard that lies is worse than
asbecause its name promises safety. Name guardsisXorhasX. Prefer tag narrowing when a tag exists. - Exhaustive switches. In the
defaultbranch of a switch over a union, assign the value to a local typednever. Adding a variant then fails to compile at every switch that forgot it. Return that local in value-returning switches; mark it used withvoidin statement switches. satisfiesoverasfor literals. It checks conformance and keeps the literal types.- Parse once at the boundary. Data crossing into the system is parsed once into a named domain type. A loose record type never travels past that parse. Wire formats tolerate unknown fields so older code can read newer messages. Persisted JSON is a versioned blob parsed inside
try/catch. Inner functions do not re-validate. Seeprinciple-boundary-discipline. - Derive types from generated sources. When types already come from protobuf, OpenAPI, GraphQL, or database migrations, build on them with
Pick,Omit,Partial, andtypeof. A hand-written duplicate interface drifts the first time the source changes.
Calls, tests, and telemetry
- One object parameter over several positional ones. Swapped positional arguments of the same type compile without complaint; named fields do not. Exempt hot paths (per-frame rendering, tokenizers, parsers, tight loops) where the allocation shows up in a profile.
- Run real code in tests. Do not mock what can run on a dev machine. Use the test framework's own facilities, including its checks for leaked handles and undisposed resources. Check UI behavior in a real running build. Keep mocks for dependencies that cannot run locally. See the
tddskill (../tdd/SKILL.md). - Structured telemetry. Log through the project's structured logger with enough fields that an id alone lets someone debug the case. No bare
console.login shipped code. Never log secrets, tokens, or full request bodies that may contain them.
Done when
No any touches external data, every as follows a validation, no guard lies, every switch over a union is exhaustive, and boundary data is parsed once into a domain type.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.