typescript-writing-code（TypeScript writing 代码）

TypeScript Writing Code

Quick reference for writing production-quality TypeScript code. Each section summarizes the key rules — reference files provide full examples and edge cases.

Strict TypeScript Configuration

This project enforces maximum type safety through tsconfig.base.json. Zero any tolerance — no exceptions.

Key Flags

• strict: true — Enables all strict type-checking options as a group.
• noImplicitAny: true — Every value must have an explicit or inferable type. No implicit any.
• strictNullChecks: true — null and undefined are distinct types. Must be handled explicitly.
• noUncheckedIndexedAccess: true — Array/object index access returns T | undefined. Always check before using.
• noUnusedLocals: true — Unused variables are compile errors, not warnings.
• noUnusedParameters: true — Unused function parameters are compile errors.
• noImplicitReturns: true — Every code path in a function must return a value.
• isolatedModules: true — Required for Vite/esbuild compatibility. Prevents features that need full-program analysis.

Zero any Policy

// ❌ Wrong — using `any`
function parse(data: any): User {
  return data as User;
}

// ✅ Correct — using `unknown` with narrowing
function parse(data: unknown): User {
  if (!isUser(data)) {
    throw new Error("Invalid user data");
  }
  return data;
}

Safe Indexed Access

With noUncheckedIndexedAccess, array and record access returns T | undefined:

const items = ["a", "b", "c"];
const first = items[0]; // string | undefined — must check

if (first !== undefined) {
  console.log(first.toUpperCase()); // safe
}

const map: Record<string, number> = { a: 1 };
const value = map["b"]; // number | undefined — must check

Catch Blocks

Always type catch variables as unknown:

try {
  await fetchData();
} catch (error: unknown) {
  if (error instanceof Error) {
    console.error(error.message);
  }
  throw error;
}

See references/strict-config.md for the full tsconfig.base.json, flag explanations, and anti-patterns.

Type Safety Patterns

Use TypeScript's type system to catch bugs at compile time, not runtime.

Type Guards

// typeof guard
function formatValue(value: string | number): string {
  if (typeof value === "string") {
    return value.toUpperCase();
  }
  return value.toFixed(2);
}

// Custom type guard with `is` predicate
function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "email" in value
  );
}

Discriminated Unions

Tag union members with a literal type field. Use exhaustive switch for safety:

type Result<T> =
  | { kind: "success"; data: T }
  | { kind: "error"; error: string };

function handle<T>(result: Result<T>): void {
  switch (result.kind) {
    case "success":
      console.log(result.data);
      break;
    case "error":
      console.error(result.error);
      break;
    default: {
      const _exhaustive: never = result;
      throw new Error(`Unhandled case: ${_exhaustive}`);
    }
  }
}

Branded Types

Use branded types for nominal typing when primitive types are too loose:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function createUserId(id: string): UserId {
  return id as UserId;
}

function getUser(id: UserId): User { /* ... */ }

// getUser(orderId) — compile error, even though both are strings

See references/type-safety.md for generics, utility types, assertion functions, and anti-patterns.

ESM Module Patterns

This project uses ESM ("type": "module") throughout. All packages set "type": "module" in package.json.

Import Rules

• Named exports preferred — Default exports make refactoring harder and tree-shaking less predictable.
• import type for types — Biome enforces useImportType and useExportType. Type-only imports are erased at runtime.
• node: prefix for built-ins — Always use node:path, node:fs, node:crypto.

// ✅ Correct
import { useState, useEffect } from "react";
import type { ReactNode } from "react";
import path from "node:path";

// ❌ Wrong — missing type keyword
import { ReactNode } from "react"; // Biome error: useImportType

Barrel Files

Use barrel files (index.ts) for clean public APIs, but keep them thin:

// components/index.ts
export { Button } from "./Button";
export { Input } from "./Input";
export type { ButtonProps, InputProps } from "./types";

Dynamic Imports

Use dynamic import() for code splitting in routes and heavy modules:

const AdminPanel = lazy(() => import("./pages/AdminPanel"));

See references/esm-modules.md for build output, circular dependency detection, and package.json exports.

Error Handling

Handle errors explicitly. Use result types for expected failures, exceptions for unexpected ones.

Result Type Pattern

type Result<T, E = string> =
  | { ok: true; data: T }
  | { ok: false; error: E };

function createSuccess<T>(data: T): Result<T, never> {
  return { ok: true, data };
}

function createError<E>(error: E): Result<never, E> {
  return { ok: false, error };
}

Discriminated Union Errors

type ApiError =
  | { kind: "not_found"; resource: string }
  | { kind: "validation"; fields: Record<string, string> }
  | { kind: "unauthorized" };

function handleApiError(error: ApiError): string {
  switch (error.kind) {
    case "not_found":
      return `${error.resource} not found`;
    case "validation":
      return Object.values(error.fields).join(", ");
    case "unauthorized":
      return "Please sign in";
  }
}

Try-Catch Rules

// ✅ Correct — catch unknown, narrow, add context
try {
  await api.createUser(data);
} catch (error: unknown) {
  if (error instanceof ApiError) {
    throw new Error(`Failed to create user: ${error.message}`);
  }
  throw error; // Re-throw unexpected errors
}

// ❌ Wrong — catch any, swallow error
try {
  await api.createUser(data);
} catch (e: any) {
  console.log(e.message); // unsafe access
}

See references/error-handling.md for async patterns, retry logic, and when to throw vs return errors.

Biome (Linter & Formatter)

This project uses Biome (v2.3.11) for both linting and formatting. It replaces ESLint and Prettier entirely.

Key Rules

Formatter Settings

• Double quotes, semicolons always, trailing commas
• 2-space indent, 100-character line width
• Organize imports automatically

Commands

# Check (lint + format check)
biome check .

# Fix (lint fix + format)
biome check --write .

# CI mode (fails on any issue)
biome ci .

Critical Rule

Never add biome-ignore comments. Fix the underlying issue instead of suppressing it. This is a hard project rule — no exceptions.

See references/biome.md for the full biome.json config, VS Code integration, and common fix patterns.

Naming Conventions & Code Quality

Naming Rules

Code Quality Rules

• Zero warnings policy — Treat warnings as errors. Fix them, don't ignore them.
• No @ts-ignore — Use @ts-expect-error with a comment explaining why, only as a last resort.
• No type assertions as escape hatches — as unknown as T is a code smell. Refactor instead.
• Prefer const assertions — Use as const for literal types instead of explicit type annotations.
• JSDoc for exports — Document exported functions and types with JSDoc. Focus on the "why", not the "what".

/**
 * Encrypts PII fields before database storage.
 * Uses AES-256-GCM with a per-record IV for uniqueness.
 */
export function encryptField(plaintext: string, key: Buffer): EncryptedField {
  // ...
}

Post-Change Verification (MANDATORY)

After every TypeScript code change, run this 4-step verification. No exceptions.

The 4 Steps

# 1. Type-check
pnpm run type-check
# or per-app: pnpm --filter patient type-check

# 2. Lint
pnpm run lint
# or per-app: pnpm --filter patient lint

# 3. Format
pnpm run format
# or per-app: pnpm --filter patient format

# 4. Test
pnpm run test
# or per-app: pnpm --filter patient test

One-Command Verification

# Run all checks for a specific app
pnpm --filter patient validate

Rules

• All 4 steps must pass before considering a change complete.
• Fix issues immediately — Don't defer lint warnings or type errors.
• Never suppress to pass — No @ts-ignore, no biome-ignore, no any casts.

See references/post-change-protocol.md for the full verification workflow, common failures, and troubleshooting.

Reference Files