typescript-standards
Use when writing, reviewing, or architecting TypeScript in app or library code. Don't use for test-only files, docs, CSS, or helper placement (that is a different search).
AlemTuzlak · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add AlemTuzlak/skills --skill typescript-standards技能说明
name: typescript-standards description: Use when writing, reviewing, or architecting TypeScript in app or library code. Don't use for test-only files, docs, CSS, or helper placement (that is a different search).
TypeScript Standards
Public APIs must feel like JavaScript. Callers write JS. You hide the type work. App or library does not change this.
This skill does not decide where a helper file lives. It does not add debug flags. It does not load other skills.
When To Use
Load when writing or reviewing TypeScript (.ts, .tsx). App code and library code both use these rules.
Skip test-only files, docs, and CSS.
Hard Gates
- Call sites never write
<T>. If they must, the signature is wrong. Generic definitions are fine. - Never write overloads. One signature. Derive the return with inference and conditional types.
- No
as any,as unknown as X, or cast chains. If you needas, the types are usually wrong. as constonly to stop widening (e.g."open"staying"open", notstring). Not a habit.- Do not annotate function return types. Let TypeScript infer. Do not write
: Fooafter). - If the function cannot work without a value, that value is required. Do not take
T | undefinedand return early. Do not accept the property. - Pipe types through callers. If
AneedsB,Cthat callsAtakesB. Do not take a looser type inCand cast insideC. - Fix this skill’s smells only in the file you already opened. Do not tour the folder.
Inference
Design signatures so TypeScript infers from arguments and returned values.
createStore({ count: 0 })
not
createStore<{ count: number }>({ count: 0 })
Do not write the return type on the function. Infer it from return.
Types
- Before a new
typeorinterface, search the current package and neighbors. Use or extend the one that is the same shape. Do not grep the whole monorepo for a one-file type. - One signature. Conditional types when the return depends on the input. No overload list.
- Constrain with types, not with runtime
typeof/ extra unions.function f(b: string)notfunction f(b: string | undefined) { if (typeof b === "string") ... }. - Arrays stay constrained.
arr.map(a => ...)infersa. Do not writearr.map((a: Foo): Bar => ...). filter/ narrow with a type predicate:(value): value is X. Do not leave the array as a loose union after a filter that is meant to narrow.- Do not loosen types “just in case.” If the code cannot run without a field, that field is required on the argument.
Functions
- First arg is the required value (URL, input, id).
- Extra flags go in an options object when a lone boolean is unclear (
fn(url, true)) or when there is more than one extra.add(a, b)stays two values. - Options/setup must still work if pulled into a helper. If extraction breaks types or behavior, fix the signature. Do not extract every options object by default.
- Return the type the caller needs, including nullish. If the next function wants
X | null, returnX | null. Do not returnX | undefinedand thenx ?? null. Picknullorundefinedfor that path and keep it. - Name complex conditions:
const isOpenGold = order.status === "open" && order.tier === "gold"
if (isOpenGold) { /* ... */ }
Do not dump a long && / || chain into if (...).
- Early return to narrow. Prefer an early
ifover nestedelse. For several missing values, oneifwith||:
if (a === null || a === undefined || b === null) return
Then use a and b as defined. Do not write if (a !== null || a !== undefined) (that check is always true).
- Three or more branches on the same value: exhaustive
switch. Use aneverdefault (or no default with a union the compiler checks). Do not write a ladder ofif/else if. - Loops: assign the list first, then iterate.
const values = getValues(input)
for (const value of values) { /* ... */ }
Do not call getValues in the for header.
- Spreads stay flat.
{ ...a, b: { ...c } }. Do not convert fields in the spread (c.x === undefined ? null : c). If every call site converts format A to format B, the data model failed. Convert once at a boundary, or change the types so both sides match. - Public functions (package entry, exported SDK, what users call) get TSDoc: what it does, the arguments, how to call it. Do not annotate the return type in the signature. You can describe the result in the comment.
Casts
Banned: as any, as unknown as X, double casts, (x as any).code.
Allowed:
as constonly when a literal widens (string/number/array) and you need the literal type.return x as Tonly when TypeScript cannot infer a generic return (e.g.JSON.parseintoT). Still do not write: Ton the function.
Errors
Custom Error subclasses only at a boundary callers catch (exported function, SDK, route handler). Internal helpers can throw new Error(...). Document on that boundary (TSDoc) what can throw and which class to catch.
Barrels
No export *. Inside the repo, import from the real file. The package public entry (index.ts behind exports) can re-export named symbols only.
Procedures
Procedure 1: Before a new type or signature
- Search the current package and neighbors for an existing type.
- Write one function signature. Infer from args and from
return. No overloads. No call-site<T>. No return annotation. - If the body cannot run without a field, that field is required. Do not take it as optional.
- If this function calls another that needs type
B, this function takesB. - If extras are a magic boolean, use an options object.
- If the function is public, write TSDoc (what, args, how to use).
Procedure 2: While editing
- Do not add banned casts.
as constonly for widening. Do not add return type annota