/typescript-rules

name: typescript-rules
description: "TypeScript/JavaScript coding rules: style, patterns, security, testing. Triggers: .ts, .tsx, .js, .jsx, package.json, tsconfig.json, React, Next.js, Vue, Vite, Vitest, Jest, ESLint."
effort: medium
user-invocable: false
allowed-tools: Read

TypeScript/JavaScript Rules

These rules come from `app/rules/typescript/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in TypeScript/JavaScript. Apply them when writing or reviewing TypeScript/JavaScript code.

TypeScript Coding Style

Strict Mode

• Always use `strict: true` in tsconfig.json.
• Never use `any` -- use `unknown` + type guards instead.
• Prefer `interface` over `type` for object shapes (extendable).
• Use `as const` for literal types and readonly tuples.

Naming

• PascalCase: types, interfaces, enums, classes, components.
• camelCase: variables, functions, methods, properties.
• UPPER_SNAKE: constants, env vars.
• Prefix interfaces with `I` only if project convention requires it.

Functions

• Prefer arrow functions for callbacks and inline.
• Use `function` declarations for hoisted, named functions.
• Max 3 parameters -- use options object beyond that.
• Always type return values for public/exported functions.

Imports

• Group: node builtins, external, internal, relative.
• Use `type` imports: `import type { Foo } from './foo'`.
• No barrel exports unless at package boundary.
• Prefer named exports over default exports.

Types

• Use discriminated unions over class hierarchies for state.
• Use `readonly` for arrays and objects that should not be mutated.
• Use `satisfies` operator to validate types without widening.
• Prefer `unknown` over `any` at API boundaries.
• Use template literal types for string patterns.

Avoid

• `enum` -- use `as const` objects or union types.
• `namespace` -- use ES modules.
• `private` keyword -- use `#` private fields.
• Non-null assertion `!` -- use proper type narrowing.
• `as` type casting -- use type guards and narrowing.

Configuration

• Enable `noUncheckedIndexedAccess` for safer array/object access.
• Enable `exactOptionalPropertyTypes` to distinguish `undefined` from missing.
• Use `moduleResolution: "bundler"` for modern projects.
• Set `isolatedModules: true` for bundler compatibility.

TypeScript Frameworks

React

• Use function components exclusively. No class components.
• Colocate state with the component that owns it. Lift only when needed.
• Use `useCallback` and `useMemo` only when profiling shows a need.
• Use `React.lazy()` + Suspense for code-splitting routes.
• Avoid prop drilling past 2 levels -- use Context or state management.

Next.js (App Router)

• Default to Server Components. Add `"use client"` only when needed.
• Use Server Actions for mutations. Never expose internal APIs to client.
• Use `loading.tsx` and `error.tsx` for streaming and error boundaries.
• Fetch data in Server Components, not in useEffect on client.
• Use `revalidatePath` / `revalidateTag` for cache invalidation.

Express / Fastify / Hono

• Use layered architecture: route -> controller -> service -> repository.
• Validate request body/params/query with Zod middleware.
• Centralize error handling in a single error middleware.
• Use async route handlers with proper error forwarding.
• Return consistent response shapes: `{ data }` or `{ error }`.

State Management

• Use Zustand or Jotai for client state. Redux only for complex existing apps.
• Use TanStack Query (React Query) for server state.
• Separate server state (fetched data) from client state (UI state).
• Never duplicate server data in client state stores.

ORM / Database

• Use Drizzle for new projects (SQL-like, type-safe, lightweight).
• Use Prisma for rapid prototyping (schema-first, great DX).
• Always use migrations. Never modify schema manually in production.
• Use transactions for multi-table operations.

Node.js Runtime

• Use `node:` prefix for built-in modules: `import { readFile } from 'node:fs/promises'`.
• Prefer `fetch` (built-in since Node 18) over axios/node-fetch.
• Use `structuredClone()` for deep cloning.
• Set `"type": "module"` in package.json for ESM.

Monorepo

• Use Turborepo or Nx for monorepo orchestration.
• Share types via internal packages, not copy-paste.
• Use workspace protocols: `"@org/shared": "workspace:*"`.

TypeScript Patterns

Error Handling

• Use Result type pattern: `{ success: true; data: T } | { success: false; error: E }`.
• Use Zod `.safeParse()` for validation -- returns typed result, never throws.
• Create domain-specific error classes extending `Error` with error codes.
• Centralize error handling in middleware, not in each handler.
• Never catch errors silently. Log or rethrow with context.

Discriminated Unions

• Use discriminated unions for state machines and polymorphic data.
• Always include a `type` or `kind` literal field as discriminant.
• Use `switch` with exhaustive checking (`never` in default) on unions.
• Prefer unions over optional fields for mutually exclusive states.

Async Patterns

• Use `async/await` everywhere. Never use raw `.then()` chains.
• Use `Promise.all()` for independent concurrent operations.
• Use `Promise.allSettled()` when some failures are acceptable.
• Implement cancellation with `AbortController` for long operations.
• Wrap callbacks in Promises at the boundary, then use async/await.

Validation

• Validate at API boundaries with Zod, Valibot, or ArkType.
• Derive TypeScript types from schemas: `z.infer<typeof Schema>`.
• Never trust runtime data to match TypeScript types without validation.
• Use branded types for domain primitives: `UserId`, `Email`, `Slug`.

Dependency Injection

• Use constructor injection for services and repositories.
• Accept interfaces, not concrete classes, in constructors.
• Use factory functions for creating configured instances.
• Avoid service locator pattern and global singleto