Node.js

[tools]
node = "24"
bun = "1.4"
pnpm = "12"

import type { Server } from "node:http";   // type-only
import { createServer } from "node:http";
import { greet, type Greeting } from "./greet.ts";
 
const server: Server = createServer((_req, res) => {
  const g: Greeting = greet("node");
  res.end(g.text);
});
server.listen(3000);

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true
  }
}

import { readFile } from "node:fs/promises";
import { createRequire } from "node:module";
import { join } from "node:path";
 
const here = import.meta.dirname;        // like __dirname
const self = import.meta.filename;       // like __filename
const cfgPath = join(here, "config.json");
const cfg = JSON.parse(await readFile(cfgPath, "utf8"));
 
// JSON import with an import attribute
import pkg from "./package.json" with { type: "json" };
 
// CommonJS-only package from ESM
const require = createRequire(import.meta.url);
const legacy = require("./legacy.cjs") as { run(): void };
 
const url = import.meta.resolve("./greet.ts"); // file:// URL
console.log(self, cfg, pkg, legacy, url);

{
  "name": "@acme/api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "imports": {
    "#src/*": "./src/*",
    "#config": "./src/config.ts"
  },
  "exports": {
    ".": "./dist/index.js",
    "./package.json": "./package.json"
  },
  "engines": { "node": ">=24" },
  "devEngines": {
    "runtime": { "name": "node", "version": "^24.11.0" },
    "packageManager": { "name": "pnpm", "version": "^12" }
  },
  "scripts": {
    "dev": "node --watch --env-file=.env src/main.ts",
    "start": "node dist/main.js",
    "test": "node --test",
    "typecheck": "tsc --noEmit"
  }
}

import { parseEnv } from "node:util";
 
process.loadEnvFile(".env.local"); // set vars are kept,
process.loadEnvFile();             // so specific first
                                   // (throws if missing)
const parsed = parseEnv("A=1\nB=two"); // { A, B }
 
const port = Number(process.env.PORT ?? 3000);
const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) throw new Error("DATABASE_URL is required");
 
process.argv;         // [execPath, script, ...args]
process.exitCode = 1; // exit code when the loop drains
console.log(parsed, port);

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      DATABASE_URL?: string;
      NODE_ENV?: "development" | "production" | "test";
    }
  }
}
export {};

import assert from "node:assert/strict";
import { afterEach, describe, it, mock } from "node:test";
import { sum } from "./sum.ts";
 
describe("sum", () => {
  afterEach(() => mock.restoreAll());
 
  it("adds", () => {
    assert.equal(sum(1, 2), 3);
    assert.deepEqual({ a: [1] }, { a: [1] });
  });
 
  it("rejects", async () => {
    await assert.rejects(
      Promise.reject(new TypeError("bad")),
      TypeError,
    );
  });
 
  it("mocks", (t) => {
    const fn = t.mock.fn((n: number) => n * 2);
    fn(2);
    assert.equal(fn.mock.callCount(), 1);
    assert.deepEqual(fn.mock.calls[0]?.arguments, [2]);
    t.mock.method(Math, "random", () => 0.5);
    assert.equal(Math.random(), 0.5);
  });
 
  it("fake timers", (t) => {
    t.mock.timers.enable({ apis: ["setTimeout", "Date"] });
    let fired = false;
    setTimeout(() => (fired = true), 1_000);
    t.mock.timers.tick(1_000);
    assert.ok(fired);
  });
 
  it("snapshot", (t) => {
    t.assert.snapshot({ theme: "dark" });
  });
 
  it.todo("edge cases");
  it.skip("flaky on CI", () => {});
});

import { EventEmitter, on, once } from "node:events";
 
type Events = {
  job: [id: string, ms: number];   // listener args tuple
  error: [err: Error];
};
 
const bus = new EventEmitter<Events>();
bus.on("job", (id, ms) => console.log(id, ms)); // typed
bus.once("error", (err) => console.error(err.message));
 
const next = once(bus, "job");      // promise of next args
bus.emit("job", "a1", 120);
const [id, ms] = await next;
 
const ac = new AbortController();
setTimeout(() => bus.emit("job", "b2", 5), 10);
setTimeout(() => ac.abort(), 100);
try {
  const jobs = on(bus, "job", { signal: ac.signal });
  for await (const [jobId] of jobs) console.log(jobId);
} catch (err) {
  if ((err as Error).name !== "AbortError") throw err;
}
console.log(id, ms);

import { createReadStream, createWriteStream }
  from "node:fs";
import { Readable, Transform } from "node:stream";
import { pipeline } from "node:stream/promises";
import { createGzip } from "node:zlib";
 
await pipeline(                         // handles errors
  createReadStream("access.log"),       // and backpressure
  createGzip(),
  createWriteStream("access.log.gz"),
);
 
const upper = new Transform({
  transform(chunk: Buffer, _enc, cb) {
    cb(null, chunk.toString().toUpperCase());
  },
});
await pipeline(Readable.from(["a", "b"]), upper,
  process.stdout);
 
const res = await fetch("https://example.com/big.zip");
if (!res.ok || !res.body) {
  throw new Error(`HTTP ${res.status}`);
}
await pipeline(res.body, createWriteStream("big.zip"));

process.on("uncaughtException", (err, origin) => {
  console.error(`fatal (${origin})`, err);
  process.exit(1);           // state unknown: don't continue
});
 
process.on("unhandledRejection", (reason) => {
  console.error("unhandled rejection", reason);
  process.exit(1);           // a listener disables the crash
});
 
process.on("exit", (code) => {
  // sync only: no timers, no promises
  console.log(`exiting with ${code}`);
});

import { monitorEventLoopDelay, performance }
  from "node:perf_hooks";
import { enableCompileCache } from "node:module";
 
enableCompileCache();                 // faster next start
 
const t0 = performance.now();
performance.mark("load:start");
await new Promise((r) => setTimeout(r, 50));
performance.measure("load", "load:start");
console.log(`${(performance.now() - t0).toFixed(1)} ms`);
 
const h = monitorEventLoopDelay({ resolution: 10 });
h.enable();
setTimeout(() => {
  h.disable();
  console.log("p99 lag ms", h.percentile(99) / 1e6);
}, 1_000);
 
const { rss, heapUsed } = process.memoryUsage();
console.log(rss, heapUsed, process.cpuUsage());

node --permission \
  --allow-fs-read=./ \
  --allow-fs-write=./tmp/ \
  --allow-child-process \
  app.js
# denied calls throw ERR_ACCESS_DENIED
node --permission-audit app.js   # log only, don't block

if (process.permission?.has("fs.write", "/etc")) {
  console.log("can write /etc");
}
try {
  const { writeFileSync } = await import("node:fs");
  writeFileSync("/etc/x", "nope");
} catch (err) {
  // ERR_ACCESS_DENIED under --permission
  console.error((err as NodeJS.ErrnoException).code);
}

import { createServer } from "node:http";
import { once } from "node:events";
 
const server = createServer((req, res) => {
  res.setHeader("content-type", "application/json");
  res.end(JSON.stringify({ path: req.url }));
});
server.listen(Number(process.env.PORT ?? 3000));
await once(server, "listening");
 
let closing = false;
async function shutdown(signal: NodeJS.Signals) {
  if (closing) return;
  closing = true;
  console.log(`${signal}: draining`);
  setTimeout(() => process.exit(1), 10_000).unref();
  server.close();                  // stop accepting
  server.closeIdleConnections();   // drop keep-alives
  await once(server, "close");     // in-flight finished
  // await db.end(); await queue.close(); ...
  process.exit(0);
}
for (const sig of ["SIGINT", "SIGTERM"] as const) {
  process.once(sig, () => void shutdown(sig));
}

import { execFile } from "node:child_process";
import { availableParallelism } from "node:os";
import { promisify } from "node:util";
 
const exec = promisify(execFile);
export async function runAll(
  cmds: [string, ...string[]][],
  limit = availableParallelism(),
): Promise<string[]> {
  const out: string[] = [];
  let next = 0;
  const worker = async () => {
    while (next < cmds.length) {
      const i = next++;
      const [file, ...args] = cmds[i]!;
      const r = await exec(file, args, { timeout: 60_000 });
      out[i] = r.stdout;
    }
  };
  const n = Math.min(limit, cmds.length);
  await Promise.all(Array.from({ length: n }, worker));
  return out;
}
 
await runAll([["node", "-v"], ["git", "--version"]]);

import { once } from "node:events";
import { availableParallelism } from "node:os";
import { Worker } from "node:worker_threads";
 
export function createPool(size = availableParallelism()) {
  const all = Array.from({ length: size }, () =>
    new Worker(new URL("./worker.ts", import.meta.url)));
  const idle = [...all];
  const waiting: ((w: Worker) => void)[] = [];
  async function run<T>(input: unknown): Promise<T> {
    const w = idle.pop() ??
      (await new Promise<Worker>((r) => waiting.push(r)));
    w.postMessage(input);
    const reply = once(w, "message"); // rejects on "error"
    const [result] = await reply.finally(() => {
      const next = waiting.shift();
      if (next) next(w);
      else idle.push(w);
    });
    return result as T;
  }
  const close = () =>
    Promise.all(all.map((w) => w.terminate()));
  return { run, close };
}

import { parentPort } from "node:worker_threads";
 
const fib = (n: number): number =>
  n < 2 ? n : fib(n - 1) + fib(n - 2);
parentPort?.on("message", (n: number) => {
  parentPort?.postMessage(fib(n));
});

#!/usr/bin/env node
import { parseArgs } from "node:util";
 
const { values, positionals } = parseArgs({
  args: process.argv.slice(2),
  allowPositionals: true,
  options: {
    out: { type: "string", short: "o", default: "dist" },
    watch: { type: "boolean", short: "w", default: false },
    tag: { type: "string", multiple: true },
    help: { type: "boolean", short: "h" },
  },
});
// values: { out: string; watch: boolean;
//           tag?: string[]; help?: boolean }
 
if (values.help || positionals.length === 0) {
  console.log("usage: build [-w] [-o dir] [--tag t] FILE");
  process.exit(values.help ? 0 : 1);
}
console.log(positionals, values.out, values.tag ?? []);

import { createInterface } from "node:readline";
import { text } from "node:stream/consumers";
 
// whole input: cat data.json | node read.ts --all
if (process.argv[2] === "--all") {
  const data = JSON.parse(await text(process.stdin));
  console.log(Object.keys(data));
} else {
  // line by line, constant memory: tail -f app.log | ...
  const rl = createInterface({
    input: process.stdin,
    crlfDelay: Infinity,          // treat \r\n as one break
  });
  let n = 0;
  for await (const line of rl) {
    if (line.includes("ERROR")) n++;
  }
  console.log(`${n} error lines`);
}