TypeScript & JavaScript Development

Mandatory gates are owned by the JavaScript and TypeScript rule (${HANDBOOK_ROOT}/rules/225-javascript-typescript.mdc). This skill and its references own procedures and examples.

Guiding Principles

1. Type Safety: Leverage strict mode, avoid any, use discriminated unions
2. Explicit Over Implicit: Prefer explicit types for clarity and maintainability
3. Modern Defaults: ESM, const/let, async/await, optional chaining
4. Security First: Never use eval, sanitize HTML, validate inputs

Quick Reference

Non-Negotiables

NN-1: Validate at trust boundaries

Static types do not validate runtime data. Treat HTTP bodies, responses, webhooks, queue messages, localStorage/sessionStorage, environment variables, CLI args, and JSON files as unknown until validated with Zod or an explicit type guard.

Reject:

• JSON.parse(raw) as T
• await response.json() as T
• unchecked property access on remote JSON
• as any or double assertions (value as unknown as T)

NN-2: Fetch/API calls require timeout + status check + schema validation

Every service/network fetch must include a timeout, check response.ok, and validate the JSON shape before returning typed data.

import { z } from 'zod';

async function fetchJson<T>(
  url: string,
  schema: z.ZodType<T>,
  options: RequestInit = {},
): Promise<T> {
  const response = await fetch(url, {
    ...options,
    signal: options.signal ?? AbortSignal.timeout(5_000),
    headers: { Accept: 'application/json', ...options.headers },
  });
  if (!response.ok) {
    throw new Error(`request failed: HTTP ${response.status}`);
  }
  return schema.parse(await response.json());
}

NN-3: Production servers are hardened by default

Node/Express/Fastify services need bounded request bodies, explicit CORS, security headers, request IDs, structured logging, generic 5xx responses, and graceful shutdown. Do not use direct app.listen(...) examples for production services without retaining and closing the server.

Use the observability skill (${HANDBOOK_ROOT}/skills/observability/SKILL.md) for event schemas, redaction, metric cardinality, trace propagation, SLOs, alerts, and telemetry pipelines. Keep runtime-specific logger and OpenTelemetry integration in this skill.

NN-4: Package manager and runtime are pinned

Declare packageManager and Node engine policy in package.json; CI uses Corepack and the declared package manager.

Production applications normally use the newest supported active LTS Node.js line accepted by the deployment target. Pin the exact package manager and tested CI runtime, commit one native lockfile, and test compiler upgrades. Follow the dependency and toolchain currency workflow (${HANDBOOK_ROOT}/skills/core-engineering/references/dependency-and-toolchain-currency.md).

{
  "packageManager": "pnpm@10.0.0",
  "engines": { "node": ">=22" }
}

NN-5: Exported APIs have explicit type and documentation contracts

• Production JavaScript uses // @ts-check and precise JSDoc types for exported parameters, return values, callbacks, generics, and shared object shapes.
• TypeScript exported functions and public methods use explicit parameter and return types. Keep type inference for obvious local variables.
• Add TSDoc or JSDoc when callers need behavior, error, ownership, blocking, side-effect, constraint, or lifecycle information that the signature cannot express.
• Use @param, @returns, @throws, @remarks, and examples only when they add contract information.
• Do not add comments that merely repeat names or types.
• Static types and documentation never replace runtime validation at trust boundaries.

Critical Patterns

// 1. Use strict equality
if (value === 0) { }        // ✅ GOOD
if (value == 0) { }         // ❌ BAD

// 2. Handle Promise rejections
fetchData().catch(err => console.error(err));  // ✅ GOOD

// 3. Optional chaining and nullish coalescing
const name = user?.profile?.name ?? 'Guest';  // ✅ GOOD

// 4. Use Set/Map for lookups
const seen = new Set();     // ✅ GOOD (O(1))
const seen = [];            // ❌ BAD (O(n))

// 5. Never use eval or new Function
eval(userInput);            // ❌ NEVER DO THIS

// 6. Sanitize HTML
element.textContent = userInput;  // ✅ GOOD
element.innerHTML = userInput;    // ❌ BAD (XSS)

TypeScript Configuration

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": false
  }
}

Avoid any - Use Proper Types

// ❌ BAD - Loses all type safety
function processData(data: any): any {
  return data.value;
}

// ✅ GOOD - Generic type
function processData<T>(data: T): T {
  return data;
}

// ✅ GOOD - Unknown for truly unknown types
function processData(data: unknown): string {
  if (typeof data === 'object' && data !== null && 'value' in data) {
    return String((data as { value: unknown }).value);
  }
  throw new Error('Invalid data');
}

Discriminated Unions

type SuccessResponse = {
  status: 'success';
  data: { id: string; name: string };
};

type ErrorResponse = {
  status: 'error';
  error: { code: number; message: string };
};

type ApiResponse = SuccessResponse | ErrorResponse;

function handleResponse(response: ApiResponse): void {
  if (response.status === 'success') {
    console.log(response.data.id);  // Type-safe
  } else {
    console.log(response.error.message);  // Type-safe
  }
}

Utility Types

interface User {
  id: string;
  name: string;
  email: string;
  password: string;
}

type UserUpdate = Partial<User>;           // All optional
type UserCredentials = Pick<User, 'email' | 'password'>;
type UserPublic = Omit<User, 'password'>;  // Exclude password
type RequiredUser = Required<User>;        // All required
type ReadonlyUser = Readonly<User>;        // Immutable

Async Patterns

// Parallel execution
const [users, products] = await Promise.all([
  fetchUsers(),
  fetchProducts()
]);

// Handle partial failures
const results = await Promise.allSettled([
  fetchUsers(),
  fetchProducts()
]);

results.forEach(result => {
  if (result.status === 'fulfilled') {
    console.log(result.value);
  } else {
    console.error(result.reason);
  }
});

Security Rules (Mandatory)

• Never use eval, new Function, or unsanitized innerHTML
• Use textContent for DOM insertion
• Validate and sanitize all external inputs
• Do not log secrets/tokens/PII
• Use parameterized queries; no string-built queries
• Enforce HTTPS; secure cookies (HttpOnly, SameSite)

Naming Conventions

Detailed References

• TypeScript Patterns: See TypeScript patterns (${HANDBOOK_ROOT}/skills/typescript-javascript/references/typescript-patterns.md) for advanced types, generics, and mapped types
• JavaScript Patterns: See JavaScript patterns (${HANDBOOK_ROOT}/skills/typescript-javascript/references/javascript-patterns.md) for JSDoc, ESM, and performance