script-reuse

Write the one-off script, and write it right

A one-off script is the normal answer to a one-off question. Write it. Nothing here is meant to talk you out of that. Two things are governed instead:

• do not write the second copy of a part that already exists;
• do not ship a script that quietly produces a wrong number — the number gets quoted long after the script is deleted.

The parts shelf is the other half of the offer: if a ready-made piece fits — percentiles, mapConcurrent, atomic JSON writes, the control-plane API — import it instead of re-deriving it. That is a shortcut, not a requirement. A script with its own three-line helper is fine as long as it is the first copy.

What makes it right

In the order these bite:

1. One command line, no editing. Inputs come from flags, not from constants you edit before each run. node:util already has parseArgs; do not write one.
2. Refuse to run on missing input. Missing flag, missing file, empty dataset → throw. A run over zero rows must not print a number.
3. Assert something about the result. Counts add up, values are finite, parts sum to the whole. One if (...) throw is enough; it is the only thing that separates "measured" from "ran".
4. Say what you measured in the output. The script is throwaway, its output is not. Write the input path, row count, and timestamp next to the number, so the number can still be interpreted after the script is deleted.
5. Fail loudly and non-zero. Never catch {}, never process.exit(0) after a failure, never ?? 0 to paper over a missing value on a measurement path.

import { readFileSync } from "node:fs";
import { parseArgs } from "node:util";

import { writeJsonAtomic } from "../tools/parts/fs.ts";
import { mean } from "../tools/parts/stats.ts";

const { values } = parseArgs({
  options: { input: { type: "string" }, out: { type: "string" } },
});
if (!values.input || !values.out) throw new Error("usage: --input <file> --out <file>");

const rows = JSON.parse(readFileSync(values.input, "utf8")) as number[];
if (rows.length === 0) throw new Error(`${values.input} has no rows`);
if (!rows.every(Number.isFinite)) throw new Error(`${values.input} has a non-finite value`);

writeJsonAtomic(values.out, {
  input: values.input,
  rows: rows.length,
  measuredAt: new Date().toISOString(),
  mean: mean(rows),
});