TypeScript

const data = JSON.parse(body) as User;     // unchecked: the compiler trusts you

const parsed = UserSchema.safeParse(JSON.parse(body));   // zod: checked at runtime
if (!parsed.success) throw new BadRequest(parsed.error.message);
const user: User = parsed.data;            // the type now matches reality

function isUser(v: unknown): v is User {
  return typeof v === 'object' && v !== null
    && 'id' in v && typeof v.id === 'number';   // `in` narrows v to have `id`
}

function handle(input: string | number | null) {
  if (input === null) return;              // null excluded below
  if (typeof input === 'string') return input.toUpperCase();
  return input.toFixed(2);                 // number
}

type Result =
  | { status: 'ok'; data: User }
  | { status: 'error'; message: string };

function render(r: Result) {
  switch (r.status) {
    case 'ok': return r.data.name;
    case 'error': return r.message;
    default: { const _never: never = r; return _never; }   // breaks when a variant is added
  }
}

function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
  return Object.fromEntries(keys.map(k => [k, obj[k]])) as Pick<T, K>;
}

async function retry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  let last: unknown;
  for (let i = 0; i < attempts; i++) {
    try { return await fn(); } catch (e) { last = e; await sleep(2 ** i * 100); }
  }
  throw last;
}

type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };
type Handler<E extends string> = `on${Capitalize<E>}`;        // template literal type
type Unwrap<T> = T extends Promise<infer U> ? U : T;          // conditional type with infer

{
  "compilerOptions": {
    "target": "es2023",
    "module": "nodenext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "types": ["node"],
    "sourceMap": true,
    "declaration": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

node src/script.ts        # strips types, does not type-check

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

const [a, b] = await Promise.all([fetchA(), fetchB()]);          // rejects on the first failure
const results = await Promise.allSettled([fetchA(), fetchB()]);  // never rejects; inspect each status
const first = await Promise.race([work(), timeout(5000)]);       // first to settle wins

const res = await fetch(url, { signal: AbortSignal.timeout(5000) });   // aborts after 5 s

try { await work(); }
catch (e) {
  if (e instanceof Error) log.error(e.message, { stack: e.stack });
  else log.error('non-Error thrown', { value: String(e) });
}

// type for unions, functions and computed types; interface for object contracts others extend
type Method = 'GET' | 'POST';
interface Store { get(id: string): Promise<User | undefined>; }

// Branded types stop identifiers of the same primitive shape being swapped
type UserId = string & { readonly __brand: 'UserId' };
const asUserId = (s: string): UserId => s as UserId;

// readonly parameters document and enforce no mutation
function sum(values: readonly number[]): number { return values.reduce((a, b) => a + b, 0); }

// as const plus an indexed type replaces an enum
const ROLES = ['admin', 'user'] as const;
type Role = (typeof ROLES)[number];    // 'admin' | 'user'

const routes = { home: '/', user: '/u/:id' } satisfies Record<string, string>;
routes.user;   // string: the key is known. Annotating `: Record<string, string>` would lose the keys

const port = Number(process.env.PORT ?? 8080);
if (!Number.isInteger(port)) throw new Error('PORT must be an integer');

type Config = { host: string; port: number; tls?: { cert: string } };

type Overrides = Partial<Config>;                                  // merge over defaults
type Strict = Required<Pick<Config, 'tls'>> & Omit<Config, 'tls'>; // tls now mandatory
type Handlers = Record<Method, (req: Request) => Promise<Response>>;
type Ok<T> = Extract<T, { status: 'ok' }>;                         // pull one variant from a union

function withDefaults<T>(value: T, fallback: NoInfer<T>): T { return value ?? fallback; }   // T comes from value only

type KeysOfType<T, V> = { [K in keyof T]-?: T[K] extends V ? K : never }[keyof T];   // -? removes optionality
type StringKeys = KeysOfType<Config, string>;                     // 'host'

{
  "name": "@example/lib",
  "type": "module",
  "exports": {
    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "./package.json": "./package.json"
  },
  "files": ["dist"],
  "engines": { "node": ">=22.12" }
}

import fs from 'node:fs/promises';              // default import of a CJS module: the module.exports object
import { readFile } from 'node:fs/promises';    // named imports work for Node built-ins and most CJS via cjs-module-lexer
import data from './data.json' with { type: 'json' };   // import attributes are mandatory for JSON in ESM
const require = createRequire(import.meta.url); // when a CJS-only dependency needs require()
const here = import.meta.dirname;               // Node 20.11+; replaces path.dirname(fileURLToPath(import.meta.url))

#!/usr/bin/env node
import { parseArgs } from 'node:util';
import { readFile, writeFile, glob } from 'node:fs/promises';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const { values, positionals } = parseArgs({
  options: { 'dry-run': { type: 'boolean', default: false }, out: { type: 'string', short: 'o' } },
  allowPositionals: true,
});

const run = promisify(execFile);
const { stdout } = await run('kubectl', ['get', 'pods', '-o', 'json'], { timeout: 30_000 });   // no shell, no injection
const pods = JSON.parse(stdout) as unknown;

for await (const file of glob('config/**/*.yaml')) {              // Node 22+: async iterator, no dependency
  if (!values['dry-run']) await writeFile(file, await transform(await readFile(file, 'utf8')));
}

process.exitCode = 0;                                              // set the code and let the loop drain, rather than process.exit()

node --env-file=.env src/script.ts          # load variables without dotenv (Node 20.6+)
node --watch src/server.ts                  # restart on change
node --test --experimental-strip-types      # older 22.x without default stripping
node --import ./register.ts src/main.ts     # preload hooks or instrumentation
NODE_OPTIONS='--enable-source-maps' node dist/main.js   # stack traces point at .ts lines

import * as z from 'zod';

const Env = z.object({
  PORT: z.coerce.number().int().min(1).max(65535).default(8080),   // coerce: "8080" from the environment
  DATABASE_URL: z.url(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  ADMIN_EMAIL: z.email().optional(),
});
export type Env = z.infer<typeof Env>;

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error(z.prettifyError(parsed.error));                    // one line per problem, with the path
  process.exit(1);
}
export const env = parsed.data;

const Event = z.discriminatedUnion('type', [
  z.object({ type: z.literal('created'), id: z.uuid(), at: z.iso.datetime() }),
  z.object({ type: z.literal('deleted'), id: z.uuid() }),
]);

const Page = z.object({ items: z.array(Event), next: z.string().nullable() });
const Duration = z.string().regex(/^\d+(ms|s|m)$/).transform(parseDuration);   // output type differs from input
type DurationIn = z.input<typeof Duration>;                          // string
type DurationOut = z.output<typeof Duration>;                        // number

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    include: ['src/**/*.test.ts'],
    environment: 'node',
    restoreMocks: true,                       // reset vi.fn state between tests
    testTimeout: 10_000,
    coverage: {
      provider: 'v8',
      include: ['src/**'],
      thresholds: { lines: 80, functions: 80, branches: 70 },   // fail the run under these
    },
    typecheck: { enabled: true, include: ['src/**/*.test-d.ts'] },   // expectTypeOf assertions via tsc
  },
});

import { describe, it, expect, vi, beforeEach } from 'vitest';

vi.mock('./client.ts', () => ({ fetchUser: vi.fn() }));            // hoisted; must be at module top level
import { fetchUser } from './client.ts';
import { greet } from './greet.ts';

describe('greet', () => {
  beforeEach(() => { vi.mocked(fetchUser).mockResolvedValue({ name: 'Ann' }); });

  it.each([
    ['ann', 'Hello, Ann'],
    ['bob', 'Hello, Bob'],
  ])('greets %s', async (id, expected) => {
    await expect(greet(id)).resolves.toBe(expected);
  });

  it('retries after a delay', async () => {
    vi.useFakeTimers();
    const p = retry(() => Promise.reject(new Error('x')), 2);
    await vi.advanceTimersByTimeAsync(1_000);                       // flush the setTimeout without waiting
    await expect(p).rejects.toThrow('x');
    vi.useRealTimers();
  });

  it('matches the rendered output', () => {
    expect(render(input)).toMatchSnapshot();                        // stored under __snapshots__/; update with -u
  });
});

npx vitest                                   # watch mode locally
npx vitest run --reporter=dot                # CI: single run
npx vitest run --coverage                    # v8 coverage with the configured thresholds
npx vitest run src/parse.test.ts -t 'empty'  # one file, tests matching a name
npx vitest run --changed origin/main         # tests affected by files changed since main
npx vitest run --update                      # accept changed snapshots (review the diff first)
npx vitest --ui                              # browser UI with module graph and console output

# Type-check in CI with plain output
npx tsc --noEmit --pretty false

# Count implicit any errors before turning on noImplicitAny
npx tsc --noEmit --noImplicitAny 2>&1 | grep -c 'implicitly has an'

# Record a trace to find slow types (open in https://ui.perfetto.dev or chrome://tracing)
npx tsc --noEmit --generateTrace trace-out

# Generate types from a JSON sample
npx quicktype --lang ts --src sample.json --just-types

# Unused files, exports and dependencies
npx knip

# Circular imports
npx madge --circular --extensions ts src

# Bundle size of the built output in bytes
npx esbuild src/index.ts --bundle --minify --platform=node | wc -c

# Which package.json condition Node will use for an import
node -p "import.meta.resolve('@example/lib')" --input-type=module

# Outdated dependencies with the type of bump
npm outdated

# Check published package contents before publishing
npm pack --dry-run

# Verify a package's exports and types resolve under every module system
npx @arethetypeswrong/cli --pack .

export async function retry<T>(
  fn: (signal?: AbortSignal) => Promise<T>,
  { attempts = 5, baseMs = 200, maxMs = 10_000, signal, isRetryable = () => true }:
    { attempts?: number; baseMs?: number; maxMs?: number; signal?: AbortSignal; isRetryable?: (e: unknown) => boolean } = {},
): Promise<T> {
  for (let i = 0; ; i++) {
    try { return await fn(signal); }
    catch (e) {
      if (i + 1 >= attempts || !isRetryable(e)) throw e;
      const delay = Math.min(maxMs, baseMs * 2 ** i) * (0.5 + Math.random());
      await new Promise<void>((resolve, reject) => {
        const t = setTimeout(resolve, delay);
        signal?.addEventListener('abort', () => { clearTimeout(t); reject(signal.reason); }, { once: true });
      });
    }
  }
}

export async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
  const results: R[] = new Array(items.length);
  let next = 0;
  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
    while (next < items.length) {
      const i = next++;                                  // single-threaded: no race on the index
      results[i] = await fn(items[i]!);
    }
  }));
  return results;
}

export async function getJson<S extends z.ZodType>(url: string, schema: S, timeoutMs = 10_000): Promise<z.output<S>> {
  const res = await fetch(url, {
    headers: { accept: 'application/json', authorization: `Bearer ${process.env.API_TOKEN}` },
    signal: AbortSignal.timeout(timeoutMs),              // TimeoutError DOMException when exceeded
  });
  if (!res.ok) throw new Error(`GET ${url}: ${res.status} ${res.statusText}`);
  return schema.parse(await res.json());
}

const signal = AbortSignal.any([callerSignal, AbortSignal.timeout(5_000)]);

const Config = z.object({
  port: z.coerce.number().int().default(8080),
  databaseUrl: z.url(),
  shutdownGraceMs: z.coerce.number().default(15_000),
});
export const config = Config.parse({
  port: process.env.PORT,
  databaseUrl: process.env.DATABASE_URL,
  shutdownGraceMs: process.env.SHUTDOWN_GRACE_MS,
});                                                      // throws ZodError before anything starts listening

import { createServer } from 'node:http';

const server = createServer(handler).listen(config.port);

function shutdown(sig: string) {
  console.error(JSON.stringify({ level: 'info', msg: 'shutting down', sig }));
  server.close(() => { process.exitCode = 0; });         // resolves when the last keep-alive connection ends
  server.closeIdleConnections();
  setTimeout(() => { server.closeAllConnections(); process.exit(1); }, config.shutdownGraceMs).unref();
}
process.once('SIGTERM', () => shutdown('SIGTERM'));
process.once('SIGINT', () => shutdown('SIGINT'));

import pino from 'pino';

export const log = pino({ level: process.env.LOG_LEVEL ?? 'info', redact: ['req.headers.authorization'] });

const reqLog = log.child({ requestId: crypto.randomUUID(), path: req.url });
reqLog.info({ status: 200, ms: Date.now() - start }, 'handled');
reqLog.error({ err }, 'upstream failed');                // err key is serialised with stack and cause

export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });

function parsePort(s: string): Result<number, 'not-a-number' | 'out-of-range'> {
  const n = Number(s);
  if (!Number.isInteger(n)) return err('not-a-number');
  if (n < 1 || n > 65535) return err('out-of-range');
  return ok(n);
}

export function assertNever(x: never, message = 'unexpected value'): never {
  throw new Error(`${message}: ${JSON.stringify(x)}`);
}

type Events = { connected: [addr: string]; error: [err: Error]; closed: [] };

class Emitter<E extends Record<string, unknown[]>> {
  #handlers: { [K in keyof E]?: Set<(...args: E[K]) => void> } = {};
  on<K extends keyof E>(name: K, fn: (...args: E[K]) => void): () => void {
    (this.#handlers[name] ??= new Set()).add(fn);
    return () => this.#handlers[name]?.delete(fn);
  }
  emit<K extends keyof E>(name: K, ...args: E[K]): void { this.#handlers[name]?.forEach(fn => fn(...args)); }
}
const bus = new Emitter<Events>();
bus.on('connected', addr => addr.toUpperCase());         // addr: string

import { createReadStream } from 'node:fs';
import readline from 'node:readline';

const rl = readline.createInterface({ input: createReadStream(path), crlfDelay: Infinity });
for await (const line of rl) {
  if (line.startsWith('#')) continue;
  handle(line);
}

import { writeFile, rename } from 'node:fs/promises';

export async function writeAtomic(path: string, data: string): Promise<void> {
  const tmp = `${path}.${process.pid}.tmp`;
  await writeFile(tmp, data, { encoding: 'utf8', flag: 'wx' });   // wx: fail if the temp file exists
  await rename(tmp, path);                                        // atomic on the same filesystem
}

const cases: Array<{ input: string; want: number } | { input: string; error: string }> = [
  { input: '8080', want: 8080 },
  { input: '0', error: 'out-of-range' },
  { input: 'x', error: 'not-a-number' },
];

it.each(cases)('parsePort($input)', c => {
  const r = parsePort(c.input);
  if ('want' in c) expect(r).toEqual({ ok: true, value: c.want });
  else expect(r).toEqual({ ok: false, error: c.error });
});

export function debounce<A extends unknown[]>(fn: (...args: A) => void, ms: number) {
  let t: ReturnType<typeof setTimeout> | undefined;
  const wrapped = (...args: A) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
  wrapped.cancel = () => clearTimeout(t);
  return wrapped;
}