typescript-javascript

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

Aspect	TypeScript	JavaScript
Package Manager	pnpm preferred	pnpm preferred
Module System	ES Modules	ES Modules + // @ts-check
Linting	eslint --max-warnings=0	eslint --max-warnings=0
Formatting	Prettier	Prettier
Types	Strict mode	JSDoc types

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());
}