typescript-idioms
Learn TypeScript's type system as your specification: enable strict mode, use type guards over casts, and validate all external data with Zod. This skill covers discriminated unions for state machines, immutability patterns, null safety, and the critical rule that all HTTP calls route through a centralized client for consistent auth and error handling.
TypeScript Idioms teaches strict mode, type narrowing, and runtime validation patterns to make invalid states unrepresentable.
AI-generated summary based on this skill's SKILL.md
Install
irahardianto/awesome-agv/typescript-idioms · repository language: JavaScript
git clone https://github.com/irahardianto/awesome-agv
cp -r awesome-agv/.agents/skills/typescript-idioms ~/.claude/skills/typescript-idiomsnpx skillfed install irahardianto/awesome-agv/typescript-idiomsFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What are typescript strict mode best practices?
typescript-idioms teaches that strict mode is your specification layer. Enable `strict: true` in tsconfig.json to enforce non-null checks, explicit `any` rejection, and sound property initialization. Use type guards (`typeof`, `instanceof`, custom predicates) instead of non-null assertions. Validate all external data—especially API responses—with Zod at boundaries. This prevents runtime surprises by catching type errors at compile time.
How do you implement runtime validation at API boundaries using Zod?
typescript-idioms emphasizes that all HTTP calls must route through a centralized client for consistent auth and error handling. At that boundary, use Zod schemas to parse and validate responses before your code consumes them. Define a schema matching your API contract, call `.parse()` or `.safeParse()`, and reject invalid data. This ensures type safety isn't just a compile-time illusion—runtime data is verified before it enters your type system.
What is the difference between unknown vs any in typescript?
typescript-idioms stresses that `unknown` is the type-safe alternative to `any`. Both accept any value, but `unknown` requires you to narrow the type before use—via type guards, `typeof` checks, or custom predicates—forcing explicit validation. `any` bypasses all checks and defeats the type system. Use `unknown` for external data, function parameters you can't predict, and error objects. Reserve `any` only for legacy code or unavoidable third-party gaps.
How do you build type-safe state machines with discriminated unions?
typescript-idioms teaches discriminated unions as the pattern for state machines. Define a union of state types, each with a literal `type` or `status` field that differs. TypeScript's type narrowing then automatically refines the union when you check that discriminant. For example, `type State = { type: 'idle' } | { type: 'loading'; request: Promise<Data> } | { type: 'error'; message: string }`. This makes illegal state transitions impossible at compile time.
What role do readonly and immutability patterns play in typescript?
typescript-idioms advocates readonly to encode immutability in your types. Mark object properties and array types as `readonly` to prevent accidental mutations and signal intent. Use `as const` assertions on literals to infer the narrowest possible types. Immutability reduces bugs, makes concurrent code safer, and pairs well with functional patterns. Combined with strict mode and type guards, readonly enforces a discipline that catches mutation errors before runtime.
How should you configure ESLint and Vitest for typescript production code?
typescript-idioms covers tooling integration: configure ESLint with `@typescript-eslint/parser` and `@typescript-eslint/recommended` rules to catch common mistakes. Enable Vitest with TypeScript support and mock external dependencies consistently. Use type checking in your CI pipeline alongside tests. This layered approach—linting, type checking, unit tests, and centralized HTTP clients—catches errors early and ensures your production code stays type-safe and maintainable.
SKILL.md
rendered from the published skill — quoted content, verbatim
TypeScript Idioms and Patterns
Core Philosophy
TypeScript's type system is your documentation, your test, and your specification — all at once. Make the type system encode the invariants of your domain so that invalid states are unrepresentable. Lean into the compiler.
> Scope: This file covers TypeScript-specific type system and language idioms. For framework-specific patterns, see the respective idiom skill (Vue, React, Angular, Next.js, Hono). For file layout, see references/project-structure.md in this skill. For quality commands, see code-idioms-and-conventions.md. For logging library, see @.agents/skills/logging-implementation/SKILL.md.
Strict Mode — Non-Negotiable
Always enable strict mode in tsconfig.json:
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true
}
}
These flags catch the majority of runtime errors at compile time. Never disable them on a per-file basis
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 2 files
.agents/skills/typescript-idioms/SKILL.md
.agents/skills/typescript-idioms/references/project-structure.md