Typescript Rules

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 singletons.

Immutability

• Use readonly on interface properties by default.
• Use Readonly<T>, ReadonlyArray<T> for function parameters.
• Use Object.freeze() only for runtime safety in config objects.
• Prefer spread/map/filter over mutating methods (push, splice).

Type Guards

• Use is return type for custom type guards: (x: unknown): x is User.
• Use in operator for discriminating object shapes.
• Prefer satisfies over as for type validation without casting.
• Use assertion functions (asserts x is T) for preconditions.

TypeScript Security