TypeScript

Writes, reviews, and debugs type-safe TypeScript: type errors, narrowing, generics, tsconfig strictness, and declaration files. Use when a build hits type errors ("not assignable", "possibly undefined", "excessively deep", "cannot find module"), when eliminating any or unchecked as casts, designing generics or discriminated unions, writing .d.ts files or typing untyped npm packages, configuring tsconfig or module resolution, fixing ESM/CJS import crashes ("ERR_REQUIRE_ESM", "x is not a function"), validating API or JSON data at runtime, migrating JavaScript to TypeScript or upgrading the TypeScript version, or when tsc or the editor gets slow or runs out of memory.

User preferences and memory live in ~/Clawic/data/typescript/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/typescript/ or ~/clawic/typescript/), move it to ~/Clawic/data/typescript/.

When To Use

• Decoding type errors: "not assignable" walls, narrowing failures, inference surprises, errors that appear only in CI
• Designing types for an API surface: generics, discriminated unions, utility types, branded types
• tsconfig decisions: strict flags, module resolution, target/lib, monorepo project references, JS-to-TS migration order
• Writing or fixing declaration files (.d.ts, module augmentation, publishing types)
• Code that compiles green but fails at runtime — ESM/CJS interop crashes, unvalidated external data — or tsc/editor slowness
• Not for runtime JavaScript semantics (closures, event loop, coercion) — that is the javascript skill

Quick Reference

Situation	Play
Value of unknown shape (API, JSON.parse, catch)	unknown + narrow before use; never any
Config/lookup object losing literal types	satisfies (TS >=4.9), not a type annotation
Union variant not narrowing	Add a literal discriminant field + exhaustive never check
40-line "not assignable" error	Read the deepest Types of property ... are incompatible line first — root cause is at the bottom; full decoder → errors.md
Cryptic diagnostic (TS2589, TS2742, "no overload matches"), error only in CI	errors.md
Generic won't infer / variance confusion / overload design	generics.md
Partial/Omit/Record behaving oddly	utility-types.md
Untyped npm package, globals, augmentation, publishing types	declarations.md
JS conversion, strict-flag rollout, as debt, TS version upgrade	migration.md
target/module/paths choices, monorepo, project references	tsconfig.md
Green compile, runtime crash (x is not a function, ERR_REQUIRE_ESM)	modules.md
External data crossing a trust boundary	Validate at runtime at the boundary; static types only downstream → boundaries.md
tsc slow, editor lag, compiler out of memory	performance.md
Anything else typed	Default: full strict, infer locals, annotate exports

Depth on demand: errors.md diagnostic decoding · generics.md inference, variance, conditional types, overloads · utility-types.md built-in type traps · declarations.md .d.ts, augmentation, publishing · migration.md JS-to-TS, strictness ratchets, TS upgrades · tsconfig.md compiler configuration · modules.md ESM/CJS interop · boundaries.md runtime validation · performance.md compile and editor speed.

Core Rules

1. Full strict or you are reviewing half the code. Every flag off is a bug class the checker won't report. Greenfield: strict: true day one plus noUncheckedIndexedAccess (TS >=4.1). Legacy: stage flags with a ratchet (migration.md).
2. unknown in, typed out. Data you didn't construct (network, JSON, env, storage) enters as unknown and gets validated once at the boundary (boundaries.md); past that point no any and no re-checking.
3. Annotate exports, infer locals. Annotated parameters and return on every exported function put errors at the boundary that caused them, not at 30 call sites downstream; inference inside bodies keeps the noise down.
4. Make illegal states unrepresentable. n independent optional fields admit 2^n combinations: { data?: T; error?: E } is 4 states of which 2 are illegal. A discriminated union with one variant per legal state encodes exactly the truth.
5. Every as carries a proof. A cast overrides the checker — attach the runtime guard that makes it true, or a one-line comment saying why it cannot be wrong. An unexplained cast is a deferred bug report.
6. Exhaustive by construction. Every switch over a union ends in default: x satisfies never (TS >=4.9) — adding a variant then becomes a compile error at every site that must handle it, which is the entire point of the union.
7. Errors read bottom-up. The first lines of a long diagnostic are wrappers; the root cause is the deepest Types of property ... are incompatible line (errors.md).

Stop Using any

• any is viral both directions: it silences errors on reads AND poisons everything it's assigned to. unknown only blocks reads until you narrow — same flexibility, none of the spread
• catch (e) is unknown under strict since TS 4.4 (useUnknownInCatchVariables) — check e instanceof Error before .message
• Every remaining cast (as) gets either a runtime guard above it or a one-line comment saying why it's safe (rule 5)
• Ratchet, don't boil the ocean: count anys (typescript-eslint no-explicit-any + no-unsafe-*), record the baseline, fail CI when the count rises

Inference & Widening

Widening:

• let x = "hello" is string; const x = "hello" is "hello" — mutability drives widening
• Object and array literals widen their members even under const: const cfg = { mode: "dark" } has mode: string — as const freezes the whole tree (readonly + literals)
• Literal arguments: primitives infer as literals, objects/arrays widen — <const T> type parameters (TS >=5.0) preserve them at the call site
• Function return types widen too — annotate the return when a caller needs the literal

Inference limits:

• Inference flows from arguments to parameters, not through intermediate generics — when a nested generic fails, name the intermediate type and split into two steps
• No partial type argument inference: fn<T, U> with one explicit argument turns off inference for the rest — use the curried two-call pattern make<T>()(config) to fix one and infer the other
• NoInfer<T> (TS >=5.4) excludes a position from inference: declare function set<T>(vals: T[], initial: NoInfer<T>): void — without it, a wrong initial widens T instead of erroring
• Callback parameters get contextual types only when the expected signature is known — assigning the function to a typed variable or parameter is what enables (x) => without annotation

Discriminated Unions & Narrowing

Modeling with unions:

• Add a literal kind field to each variant — narrowing and exhaustive switches come free (rules 4 and 6)
• Discriminant must be a literal type — a field typed string discriminates nothing; as const the source values

Narrowing failures:

• filter(Boolean) doesn't narrow in any TS version — write .filter((x): x is T => Boolean(x)). TS >=5.5 infers predicates from simple lambdas, so .filter(x => x != null) narrows there; below 5.5 it doesn't
• Narrowing dies inside callbacks: after if (x), arr.map(() => x.foo) re-errors because TS assumes x may be reassigned — copy to a const before the callback
• typeof x === "object" includes null — check x !== null in the same condition
• Object.keys(obj) returns string[], not keyof typeof obj — intentional: structural types can carry extra keys. Cast only when you own the object literal
• Array.isArray() on unknown narrows to any[] — element type needs its own check
• in narrows unions only when the property appears in exactly one branch; on unlisted properties it narrows since TS 4.9
• Destructured discriminants (const { kind } = action; if (kind === ...)) narrow only in TS >=4.6 — on older versions switch on action.kind directly

satisfies vs Annotation vs Cast

Three tools, three guarantees — pick by what you need to keep:

• const x: T = v — checks AND widens to T: literal info gone, excess properties rejected
• const x = v satisfies T (TS >=4.9) — checks compatibility, keeps the inferred narrow type: the default for config/route/theme objects
• v as T — checks nothing beyond rough overlap; "hello" as number fails but {} as User compiles. It's an assertion, not a conversion

Strict Null Handling

• ?? vs ||: port || 3000 turns a legitimate 0 into 3000; port ?? 3000 only replaces null/undefined. Same for "" in string options
• Optional chaining ?. produces undefined, never null — APIs contracted to null need an explicit ?? null
• Non-null ! is a cast in disguise — prefer early return or narrowing; each ! is a runtime crash candidate the compiler can no longer see

Strictness Beyond strict

strict: true is not the strictest configuration. Flags it does NOT include:

• noUncheckedIndexedAccess (TS >=4.1) — arr[i] and record[key] become T | undefined. Catches the most common real crash (indexing off the end); enable on greenfield day one, on legacy expect a large error wave and stage it
• exactOptionalPropertyTypes (TS >=4.4) — distinguishes "absent" from "explicitly undefined"; breaks code that assigns undefined to optional props
• noPropertyAccessFromIndexSignature, noImplicitOverride — cheap to adopt, low churn
• verbatimModuleSyntax (TS >=5.0) — forces import type for type-only imports; the modern replacement for isolatedModules import hygiene (modules.md)

Everything else about compiler configuration — target/lib, module × moduleResolution, paths, monorepos — lives in tsconfig.md; import/export mechanics and transpile-only compatibility in modules.md.

Where To Annotate

• Default: annotate exported function signatures (parameters AND return), infer everything inside bodies (rule 3)
• Explicit return types on the public surface also unlock isolatedDeclarations (TS >=5.5) and faster declaration emit
• A type parameter must relate at least two positions (two params, or param and return). Used once, it's decoration — replace with unknown or the concrete type
• Slow type checking has structural causes and a measurement workflow — performance.md

Output Gates

Before emitting TypeScript, verify:

• No any introduced, explicit or implicit — unknown where the shape is genuinely open?
• Exported functions annotated, parameters and return?
• Every as has a runtime guard above it or a justifying comment?
• Every switch over a union ends in an exhaustiveness check?
• External data validated at runtime before its first typed use?
• No ! where narrowing or ?? would prove it?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/typescript/config.yaml.

Variable	Type	Default	Effect
runtime_target	node | browser | bun | deno | isomorphic	node	Drives module/moduleResolution and lib advice in tsconfig.md and import-extension rules in modules.md
project_kind	app | library	app	Library flips guidance to declaration emit, exports-map types, and wider TS-version support; app defaults to skipLibCheck and bundler resolution
compile_pipeline	tsc | transpile-only	transpile-only	transpile-only (esbuild, swc, Babel, bundlers) enforces the single-file-safe subset: no const enum, isolatedModules rules apply (modules.md); tsc lifts those bans
validation_library	zod | valibot | arktype | ajv | none	none	Names the schema library used in boundary-validation examples (boundaries.md); none keeps guidance library-neutral
ts_version	text (e.g. "5.4")	latest	Gates every TS >=X.Y-marked recommendation in this skill: below the mark, the pre-version workaround is offered instead (e.g. below 4.9 an annotation replaces satisfies)

Preference areas to record as the user reveals them:

• conventions — interface vs type default, type naming style, banned features (enums, namespaces, decorators), type-only import style
• strictness posture — which beyond-strict flags to push proactively, cast tolerance, error-suppression policy
• tooling — package manager, typescript-eslint strictness, monorepo layout (project references vs single config), type-test tooling
• output format — quick fix vs explained fix, whether to show before/after diffs

Traps

Trap	Why it fails	Do instead
enum	The one TS feature with runtime emit; const enum breaks under transpile-only compilers	as const object + keyof typeof (modules.md)
Function or {} as a type	Function accepts any callable and calls return any; {} accepts everything except null/undefined	Exact signature (a: A) => R; Record<string, unknown> for bags
Trusting excess property checks as validation	They fire only on fresh object literals — a value passed through a variable skips them	Runtime validation at boundaries (boundaries.md)
// @ts-ignore	Keeps suppressing after the error is fixed, hiding the next one	// @ts-expect-error (TS >=3.9) — errors itself once stale
! to silence strictNullChecks	Each one is an invisible cast and a crash candidate	Narrow, early-return, or ??; sanctioned only for framework-assigned class fields (migration.md)
[key: string]: any to quiet index errors	Poisons every access on the object with any	Precise keys, Record<K, V>, or a Map; noUncheckedIndexedAccess (TS >=4.1) keeps even honest signatures honest

Where Experts Disagree

• interface vs type. Default: interface for object shapes (merges for augmentation, caches relationships for faster checking), type for unions, functions, tuples, and mapped/conditional results. An existing codebase convention beats either.
• Explicit return types everywhere vs boundary-only. Boundary-only is the default (rule 3). The everywhere school wins on published libraries and under isolatedDeclarations (TS >=5.5), where emit requires them anyway.
• Runtime validation depth. Edges-only is the default — validating internally recomputes what the checker already proved. The schema-first school (schema as source of truth, static types inferred from it) wins when one shape crosses many boundaries (boundaries.md).

Related Skills

More Clawic skills, get them at https://clawic.com/skills/typescript (install if the user confirms):

• javascript — runtime semantics: coercion, closures, event loop
• react — typing components, hooks, and props in practice
• nodejs — Node runtime, packaging, and ESM/CJS beyond the type layer
• deno — TypeScript-native runtime without a build step

Feedback

• If useful, star it: https://clawic.com/skills/typescript
• Latest version: https://clawic.com/skills/typescript

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/typescript.