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

1. Call sites never write <T>. If they must, the signature is wrong. Generic definitions are fine.
2. Never write overloads. One signature. Derive the return with inference and conditional types.
3. No as any, as unknown as X, or cast chains. If you need as, the types are usually wrong.
4. as const only to stop widening (e.g. "open" staying "open", not string). Not a habit.
5. Do not annotate function return types. Let TypeScript infer. Do not write : Foo after ).
6. If the function cannot work without a value, that value is required. Do not take T | undefined and return early. Do not accept the property.
7. Pipe types through callers. If A needs B, C that calls A takes B. Do not take a looser type in C and cast inside C.
8. 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 type or interface, 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) not function f(b: string | undefined) { if (typeof b === "string") ... }.
• Arrays stay constrained. arr.map(a => ...) infers a. Do not write arr.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, return X | null. Do not return X | undefined and then x ?? null. Pick null or undefined for 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 if over nested else. For several missing values, one if with ||:

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 a never default (or no default with a union the compiler checks). Do not write a ladder of if / 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 const only when a literal widens (string/number/array) and you need the literal type.
• return x as T only when TypeScript cannot infer a generic return (e.g. JSON.parse into T). Still do not write : T on 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

1. Search the current package and neighbors for an existing type.
2. Write one function signature. Infer from args and from return. No overloads. No call-site <T>. No return annotation.
3. If the body cannot run without a field, that field is required. Do not take it as optional.
4. If this function calls another that needs type B, this function takes B.
5. If extras are a magic boolean, use an options object.
6. If the function is public, write TSDoc (what, args, how to use).

Procedure 2: While editing

1. Do not add banned casts. as const only for widening. Do not add return type annotations.
2. Name long conditions. Early-return to narrow. Switch when there are 3+ branches on one value.
3. Assign loop lists before for. Keep spreads simple. Match null vs undefined to the caller.
4. Direct imports. No new export *.
5. If this file already has this skill’s smells, fix those in this file.

Procedure 3: Throws at a catchable boundary

1. If callers are expected to instanceof a specific error, use a custom class.
2. If the throw is internal only, new Error is enough.

Decision Tree

• Writing/reviewing .ts / .tsx → this skill.
• Test file → not this skill.
• New type → Procedure 1 step 1.
• New function → Procedure 1.
• Optional arg plus typeof / early return because it is missing → Hard gate 6. Make it required, or do not take it.
• as needed → Casts. If not an allowed case, fix the types.
• Helper file home → not this skill.
• debug / logger on config → not this skill.

Red Flags

Signal	What it means	Do instead
fn<Foo>(...) at the call site	Signature does not infer	Change the definition so args carry the type.
function fn(...): A plus two more function fn	Overloads	One signature, conditional return.
function fn(): Order	Return type annotated	Drop : Order. Infer from return.
as unknown as X inside a wrapper to call A	Types not piped	The wrapper takes the same type A takes.
as unknown as X	Types were abandoned	Fix the types.
"open" as const on every string	Habit	Use as const only when the type is otherwise string.
fn(url, true)	Magic boolean	fn(url, { retry: true }).
add({ b: 2 }) for two numbers	Options object overused	add(a, b).
if (a.x === "a" && a.y === 2 || z)	Unnamed condition	const isReady = ... then if (isReady).
b: string | undefined then typeof b === "string"	Runtime used as a type	b: string.
id?: string then if (!id) return because the body needs id	Optional that cannot be optional	Required id: string.
return x ?? null after X | undefined	Nullish mismatch	Return X | null from the start (or undefined if that is the contract).
for (const x of getValues(a))	Work hidden in the header	const values = getValues(a) then for.
arr.map((a: Foo): Bar =>	Types forced on the callback	Constrain arr. Let a infer.
filter that still leaves T | undefined	No predicate	function isDefined<T>(v: T | undefined): v is T.
Spread with === undefined ? null inside	Conversion in the spread	Spread as-is, or one mapper at a boundary.
Three if (status === in a row	Missing exhaustive switch	switch (status) over the union.
export * from './foo'	Barrel	Direct import, or named re-export at package entry.
Public export with no TSDoc	Users cannot read the contract	What it does, args, how to call it.
Custom class for an internal throw	Extra type	throw new Error(...).
Creating packages/shared from this skill	Placement	Not this skill.
Adding debug?: boolean to every config	Old rule	Not this skill.
Fixing casts in a file you did not open	Drive-by	Procedure 2, this file only.

Error Handling

• Generic return cannot infer (parse<T> / JSON.parse): return result as T is the allowed exception. Do not write : T on the function. Do not add as any on the way there.
• No existing type in package/neighbors: write one. Do not invent a parallel name for the same shape in this change.
• Conditional type cannot express the return: still no overloads. Split the function or narrow with a discriminated input. Still no return annotation.
• Callers must catch a specific failure: Procedure 3. Custom class at that boundary. TSDoc names the class.
• Downstream wants null, this function returns undefined: change this function’s return. Do not patch with ?? at every call site.
• User interrupts that a type home is wrong: move it in this same change. Update imports in opened files.

See patterns.md for before/after code.