Files and the process all 4 written

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { writeFile, readFile, appendFile, readdir } from "node:fs/promises";

await writeFile("notes.txt", "first line\n");           // creates, or replaces
await appendFile("notes.txt", "second line\n");         // adds to the end

const text = await readFile("notes.txt", "utf8");        // the encoding makes it a string
const raw = await readFile("notes.txt");                 // no encoding: raw bytes

console.log(JSON.stringify(text));
console.log(raw);
console.log(await readdir("."));

check("appendFile added, writeFile replaced", text, "first line\nsecond line\n");
check("without an encoding you get a Buffer of bytes", Buffer.isBuffer(raw), true);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import { mkdir, writeFile, readdir, rename, copyFile, rm } from "node:fs/promises";

await mkdir("reports/2026/q3", { recursive: true });   // makes every missing parent
await writeFile("reports/2026/q3/summary.txt", "up 4%");
await copyFile("reports/2026/q3/summary.txt", "reports/latest.txt");
await rename("reports/latest.txt", "reports/current.txt");

const tree = (await readdir("reports", { recursive: true })).sort();
console.log(tree);

const entries = await readdir("reports", { withFileTypes: true });
for (const e of entries) console.log(e.isDirectory() ? "dir " : "file", e.name);

await rm("reports", { recursive: true, force: true });
const afterRm = await readdir(".");
console.log(afterRm);

check("mkdir made every level, and the copy was renamed",
      tree, ["2026", "2026/q3", "2026/q3/summary.txt", "current.txt"]);
check("rm recursive removed the whole tree", afterRm, ["example.mjs"]);

src/app.mjs

1

src/lib/db.mjs

1

src/lib/util/strings.mjs

1

src/lib/README.md

1

test/app.test.mjs

1

example.mjs

1
2
3
4
5
6
7
8
9import { glob } from "node:fs/promises";

const found = [];
for await (const path of glob("src/**/*.mjs")) found.push(path);

console.log(found.sort());

check("glob matched .mjs files at every depth, and nothing else",
      found.sort(), ["src/app.mjs", "src/lib/db.mjs", "src/lib/util/strings.mjs"]);

present.txt

1here

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27import { readFile, access } from "node:fs/promises";

// The tempting version: two steps, and a gap between them.
async function loadRisky(path) {
  try {
    await access(path);            // does it exist?
  } catch {
    return "(no file)";
  }
  // ...another process could delete it right here...
  return readFile(path, "utf8");
}

// The right version: do the thing, and handle the failure you expect.
async function load(path) {
  try {
    return await readFile(path, "utf8");
  } catch (err) {
    if (err.code === "ENOENT") return "(no file)";
    throw err;
  }
}

console.log(await load("settings.txt"), (await load("present.txt")).trim());

check("a missing file is an expected outcome, not a crash", await load("settings.txt"), "(no file)");
check("and a present one is read", (await load("present.txt")).trim(), "here");

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import { writeFile, readFile, rename } from "node:fs/promises";

const config = { theme: "dark", fontSize: 14, plugins: ["git", "lint"] };

// Write the new contents to a temporary file beside the real one, then rename.
async function saveAtomically(path, text) {
  const temp = `${path}.${process.pid}.tmp`;
  await writeFile(temp, text);
  await rename(temp, path);        // a rename replaces the file in one step
}

await saveAtomically("config.json", JSON.stringify(config, null, 2));
const back = JSON.parse(await readFile("config.json", "utf8"));

console.log(back);

check("the whole file arrived", back, config);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import { open } from "node:fs/promises";

let handle;
{
  await using file = await open("log.txt", "w");   // closed automatically at the end of the block
  handle = file;
  await file.write("started\n");
  await file.write("finished\n");
}

let closedError;
try {
  await handle.write("too late\n");
} catch (err) {
  closedError = err.code;
}

console.log("writing after the block ended:", closedError);

check("using closed the file when the block ended", closedError, "EBADF");

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import { readFileSync, writeFileSync } from "node:fs";
import { readFile } from "node:fs/promises";

writeFileSync("big.txt", "x".repeat(20_000_000));   // 20 MB

let ticks = 0;
const ticker = setInterval(() => ticks++, 1);

let t = performance.now();
readFileSync("big.txt");
const syncMs = performance.now() - t;
const ticksDuringSync = ticks;

t = performance.now();
await readFile("big.txt");
const asyncMs = performance.now() - t;
const ticksDuringAsync = ticks - ticksDuringSync;
clearInterval(ticker);

console.log(`readFileSync: ${syncMs.toFixed(1)} ms, timer ran ${ticksDuringSync} times`);
console.log(`readFile:     ${asyncMs.toFixed(1)} ms, timer ran ${ticksDuringAsync} times`);

check("nothing else could run during the sync read", ticksDuringSync, 0);
check("while other work kept running during the async one", ticksDuringAsync > 0, true);
check("and the sync read was the faster of the two", syncMs < asyncMs, true);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14import path from "node:path";

const file = path.join("reports", "2026", "..", "2025", "q3.csv");

console.log(file);
console.log(path.dirname(file), path.basename(file), path.extname(file));
console.log(path.basename(file, ".csv"));
console.log(path.parse(file));
console.log(path.resolve("reports", "q3.csv"));        // made absolute, from the current folder
console.log(path.relative("/app/src/lib", "/app/assets/logo.png"));

check("join cleans up .. segments", file, "reports/2025/q3.csv");
check("extname includes the dot", path.extname(file), ".csv");
check("relative gives the way from one to the other", path.relative("/a/b/c", "/a/d"), "../../d");

example.mjs

1
2
3
4
5
6
7
8import path from "node:path";

console.log("posix:", path.posix.join("C:", "Users", "ada", "notes.txt"));
console.log("win32:", path.win32.join("C:", "Users", "ada", "notes.txt"));
console.log("this machine uses:", JSON.stringify(path.sep));

check("the same call, Windows rules", path.win32.join("a", "b"), "a\\b");
check("and POSIX rules", path.posix.join("a", "b"), "a/b");

example.mjs

1
2
3
4
5
6
7
8
9import { fileURLToPath, pathToFileURL } from "node:url";

const url = pathToFileURL("/app/My Documents/café.txt");

console.log(url.href);
console.log(fileURLToPath(url));

check("spaces and accents are encoded in a URL", url.href, "file:///app/My%20Documents/caf%C3%A9.txt");
check("and decoded back to a path", fileURLToPath(url), "/app/My Documents/café.txt");

example.mjs

1
2
3
4
5
6
7
8
9
10const words = ["hello", "héllo", "👍"];

for (const w of words) {
  const bytes = Buffer.from(w, "utf8");
  console.log(w.padEnd(6), "length", w.length, " bytes", bytes.length, " ", bytes);
}

check("an accented letter is 2 bytes in UTF-8", Buffer.byteLength("é"), 2);
check("an emoji is 4", Buffer.byteLength("👍"), 4);
check("so length is not size", "héllo".length === Buffer.byteLength("héllo"), false);

example.mjs

1
2
3
4
5
6
7
8
9
10const bytes = Buffer.from("café", "utf8");

console.log("as UTF-8:  ", bytes.toString("utf8"));
console.log("as latin1: ", bytes.toString("latin1"), "<- the right bytes, read with the wrong encoding");
console.log("as hex:    ", bytes.toString("hex"));
console.log("as base64: ", bytes.toString("base64"));
console.log(Buffer.from("Y2Fmw6k=", "base64").toString("utf8"));

check("decoding with the wrong encoding garbles it", bytes.toString("latin1"), "café");
check("base64 round-trips", Buffer.from(bytes.toString("base64"), "base64").equals(bytes), true);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17const bytes = Buffer.from("café au lait", "utf8");

// Split after the fourth byte: in the middle of é, which is two bytes.
const chunks = [bytes.subarray(0, 4), bytes.subarray(4)];
console.log(chunks);

// Decoding each chunk separately breaks the character.
const naive = chunks.map((c) => c.toString("utf8")).join("");
console.log("each chunk decoded alone:", naive);

// A decoder that remembers an incomplete character between chunks.
const decoder = new TextDecoder("utf-8");
const careful = chunks.map((c) => decoder.decode(c, { stream: true })).join("") + decoder.decode();
console.log("decoded as a stream:     ", careful);

check("naive decoding produced replacement characters", naive.includes("\uFFFD"), true);
check("streaming decoding did not", careful, "café au lait");

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { createHash } from "node:crypto";
import { readFile, writeFile } from "node:fs/promises";

// A one-pixel PNG, written from base64 so the panel can show every byte of it.
const base64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
await writeFile("pixel.png", Buffer.from(base64, "base64"));

const png = await readFile("pixel.png");
console.log("file size:", png.length, "bytes");
console.log("first 8 bytes:", png.subarray(0, 8));
console.log("is it a PNG?", png.subarray(1, 4).toString("ascii"));
console.log("sha256:", createHash("sha256").update(png).digest("hex").slice(0, 16) + "...");

const header = Buffer.alloc(4);
header.writeUInt32BE(1024);
console.log("1024 as four big-endian bytes:", header);

check("the PNG signature", [...png.subarray(0, 4)], [0x89, 0x50, 0x4e, 0x47]);
check("reading the number back", header.readUInt32BE(), 1024);

example.mjs

1
2
3
4
5
6
7import { basename } from "node:path";

console.log(basename(process.argv[0]), "<- the node program");
console.log(basename(process.argv[1]), "<- your file");
console.log(process.argv.slice(2), "<- everything you typed after it");

check("arguments are the words after the file name", process.argv.slice(2), ["report.csv", "--limit", "10", "two words"]);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import { parseArgs } from "node:util";

const { values, positionals } = parseArgs({
  args: process.argv.slice(2),
  options: {
    limit:   { type: "string", short: "n", default: "20" },
    verbose: { type: "boolean", short: "v" },
  },
  allowPositionals: true,
});

console.log(values, positionals);
const limit = Number(values.limit);

check("flags were parsed, with a short form", values.verbose, true);
check("values arrive as strings, so convert them", limit, 5);
check("everything else is a positional argument", positionals, ["sales.csv"]);

example.mjs

1
2
3
4
5
6
7
8
9
10import { parseArgs } from "node:util";

try {
  parseArgs({ args: process.argv.slice(2), options: { limit: { type: "string" } } });
} catch (err) {
  console.error(`usage error: ${err.message}`);
  process.exitCode = 2;
}

check("an unknown flag is rejected, not ignored", process.exitCode, 2);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const port = process.env.PORT;
const debug = process.env.DEBUG;
const missing = process.env.NOT_SET;

console.log({ port, debug, missing });
console.log(typeof port, "<- always a string");

if (debug) console.log("debug is on?! DEBUG was", JSON.stringify(debug));

const debugOn = process.env.DEBUG === "true";
const portNumber = Number(process.env.PORT ?? 3000);

check("an unset variable is undefined", missing, undefined);
check("the string 'false' is truthy", Boolean(debug), true);
check("so compare against the exact string", debugOn, false);
check("and convert numbers yourself", portNumber, 4000);

sales.csv

1
2
3
4region,amount
north,10
south,20
east,30

example.mjs

1
2
3
4
5
6
7
8
9
10const chunks = [];
for await (const chunk of process.stdin) chunks.push(chunk);

const lines = Buffer.concat(chunks).toString("utf8").trim().split("\n");
const total = lines.slice(1).reduce((sum, line) => sum + Number(line.split(",")[1]), 0);

console.log(`${lines.length - 1} rows, total ${total}`);

check("read every line from standard input", lines.length, 4);
check("and added up the second column", total, 60);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15const log = [];

process.on("SIGTERM", () => {
  log.push("received SIGTERM: finishing the current job, then stopping");
  clearInterval(work);
});
process.on("exit", (code) => {
  console.log(log.join("\n"));
  console.log("exiting with code", code);
  check("the handler ran before the process ended", log.length, 1);
});

const work = setInterval(() => {}, 1000);    // stands in for a server that never stops by itself

setTimeout(() => process.kill(process.pid, "SIGTERM"), 20);   // what "stop" sends

data/a.csv

1

data/b.csv

1

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13import { execFile } from "node:child_process";
import { promisify } from "node:util";

const run = promisify(execFile);

const { stdout } = await run("ls", ["-1", "data"]);
console.log(stdout.trim().split("\n"));

const node = await run(process.execPath, ["-p", "6 * 7"]);   // Node itself, as a child
console.log("the child node printed:", node.stdout.trim());

check("ls listed the folder", stdout.trim().split("\n"), ["a.csv", "b.csv"]);
check("and a child node process computed 42", node.stdout.trim(), "42");

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { execFile } from "node:child_process";
import { promisify } from "node:util";

const run = promisify(execFile);

async function attempt(file, args) {
  try {
    await run(file, args);
    return "succeeded";
  } catch (err) {
    return `failed: code ${err.code}${err.stderr ? `, stderr "${err.stderr.trim()}"` : ""}`;
  }
}

console.log(await attempt("sh", ["-c", "echo 'disk full' >&2; exit 3"]));
console.log(await attempt("no-such-program", []));

check("a non-zero exit becomes a rejection carrying the code", await attempt("sh", ["-c", "exit 3"]), "failed: code 3");
check("a missing program is ENOENT", await attempt("no-such-program", []), "failed: code ENOENT");

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import { exec, execFile } from "node:child_process";
import { promisify } from "node:util";

const shell = promisify(exec);
const direct = promisify(execFile);

// A "filename" typed by a user. The ; ends one command and starts another.
const userInput = "report.txt; echo INJECTED: this command was never meant to run";

const viaShell = await shell(`echo processing ${userInput}`);
const viaFile = await direct("echo", ["processing", userInput]);

console.log("exec (a shell):");
console.log(viaShell.stdout.trim());
console.log();
console.log("execFile (no shell):");
console.log(viaFile.stdout.trim());

check("through a shell, the user's text ran as a second command",
      viaShell.stdout.trim().split("\n").at(-1), "INJECTED: this command was never meant to run");
check("without one, it was just an argument", viaFile.stdout.trim().split("\n").length, 1);

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import { spawn } from "node:child_process";

const child = spawn(process.execPath, ["-e", `
  let n = 0;
  const t = setInterval(() => {
    console.log("progress", ++n * 25 + "%");
    if (n === 4) clearInterval(t);
  }, 10);
`]);

const seen = [];
child.stdout.on("data", (chunk) => {
  for (const line of chunk.toString().trim().split("\n")) {
    seen.push(line);
    console.log("parent received:", line);
  }
});

child.on("close", (code) => {
  console.log("child exited with", code);
  check("each line arrived while the child was still running", seen.length, 4);
  check("and it exited cleanly", code, 0);
});

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import { execFile } from "node:child_process";
import { promisify } from "node:util";

const run = promisify(execFile);

const started = performance.now();
let outcome;
try {
  await run("sleep", ["5"], { timeout: 50 });
  outcome = "finished";
} catch (err) {
  outcome = `killed by ${err.signal} after ${Math.round(performance.now() - started)} ms`;
}

console.log(outcome);

check("the timeout killed it", outcome.startsWith("killed by SIGTERM"), true);

worker.mjs

1
2
3process.on("message", ({ task, n }) => {
  if (task === "square") process.send({ n, result: n * n, pid: process.pid });
});

example.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { fork } from "node:child_process";

const worker = fork("worker.mjs");
const answers = [];

worker.on("message", (msg) => {
  answers.push(msg);
  console.log("parent got:", { n: msg.n, result: msg.result });
  if (answers.length === 2) worker.disconnect();
});

worker.send({ task: "square", n: 7 });
worker.send({ task: "square", n: 12 });

worker.on("exit", () => {
  check("the child answered both messages", answers.map((a) => a.result), [49, 144]);
  check("from its own process", answers[0].pid !== process.pid, true);
});