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

## Input Validation
- Validate ALL request data with Zod/Valibot at API boundary.
- Use `.strip()` / `.strict()` to reject unexpected fields.
- Validate URL params and query strings, not just request bodies.
- Never pass raw user input to `eval()`, `Function()`, or template literals in SQL.

## XSS Prevention
- Use framework auto-escaping (React JSX, Angular templates).
- Never use `dangerouslySetInnerHTML` without DOMPurify sanitization.
- Sanitize user content before storing, not just before rendering.
- Set CSP headers: `default-src 'self'; script-src 'self'`.

## Authentication
- Use `httpOnly`, `secure`, `sameSite: 'strict'` for auth cookies.
- Implement CSRF protection for cookie-based auth (double-submit or token).
- Use short-lived JWTs (15min) with refresh token rotation.
- Validate JWT signature, expiration, issuer, and audience on every request.

## SQL / NoSQL Injection
- Use parameterized queries with Drizzle/Prisma/TypeORM. Never concatenate.
- For raw queries, use tagged template literals: `sql\`SELECT * FROM users WHERE id = ${id}\``.
- Validate and cast IDs to expected types (UUID, integer) before queries.
- Use ORM query builders for dynamic filters.

## Dependency Security
- Run `npm audit` in CI. Fail on high/critical vulnerabilities.
- Use `npm audit signatures` to verify package provenance.
- Pin exact versions with lockfile. Review lockfile changes in PRs.
- Avoid packages with postinstall scripts unless trusted.

## Secrets
- Use `process.env` with Zod validation for env vars.
- Never import `.env` files in production -- use platform env injection.
- Never log `req.headers.authorization` or session tokens.
- Use `crypto.timingSafeEqual()` for comparing secrets.

## Server Hardening
- Set security headers: HSTS, X-Content-Type-Options, X-Frame-Options.
- Use `helmet` middleware in Express, built-in security in Fastify.
- Implement rate limiting on all endpoints (`express-rate-limit`, `@fastify/rate-limit`).
- Disable `X-Powered-By` header. Do not expose server technology.

## File Uploads
- Validate file type by magic bytes, not just extension or MIME type.
- Set maximum file size limits on the server.
- Store uploads outside the web root. Serve through a proxy with CDN.
- Generate random filenames. Never use user-provided filenames for storage.

# TypeScript Testing

## Framework
- Use Vitest for new projects (faster, native ESM, TypeScript-first).
- Use Jest only for existing projects already using it.
- Use Playwright for E2E browser testing.
- Use Supertest or built-in fetch for API integration tests.

## File Naming
- Test files: `*.test.ts` or `*.spec.ts` colocated with source.
- Test utilities: `tests/helpers/` or `tests/utils/`.
- Fixtures: `tests/fixtures/` with typed factory functions.

## Structure
- Use `describe` for grouping by function/class/feature.
- Use `it` with behavior descriptions: `it('returns 404 when user not found')`.
- Avoid deeply nested `describe` blocks (max 2 levels).
- Use `beforeEach` for setup, avoid `beforeAll` for mutable state.

## Type-Safe Mocking
- Use `vi.fn()` with type parameters: `vi.fn<[string], Promise<User>>()`.
- Use `vi.mock()` for module-level mocking.
- Prefer dependency injection over module mocking for testability.
- Use `vi.spyOn()` for partial mocks on existing objects.

## React/Component Testing
- Use React Testing Library. Query by role, label, text -- not test IDs.
- Use `userEvent` over `fireEvent` for realistic user interactions.
- Test behavior and rendered output, not component internals.
- Use `renderHook` for testing custom hooks in isolation.

## Assertions
- Use `expect().toBe()` for primitives, `expect().toEqual()` for objects.
- Use `expect().toMatchInlineSnapshot()` for complex output verification.
- Avoid `toBeTruthy/toBeFalsy` -- use specific matchers.
- Use `expect().rejects.toThrow()` for async error testing.

## Async Testing
- Always `await` async operations. Never use `done` callback.
- Use `vi.useFakeTimers()` for timer-dependent code.
- Use `waitFor` from Testing Library for async DOM updates.

## Performance
- Run tests in parallel (Vitest default). Isolate state to enable this.
- Use `vi.mock()` for heavy dependencies (DB, network) in unit tests.
- Keep unit test suite under 30 seconds.