Shipping it all 2 written

../slugger/package.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "name": "slugger",
  "version": "1.0.0",
  "description": "Turn titles into URL slugs",
  "type": "module",
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "default": "./src/index.js"
    }
  },
  "engines": { "node": ">=22" },
  "license": "MIT"
}

../slugger/README.md

1
2
3# slugger

Turn titles into URL slugs.

../slugger/src/index.js

1
2
3
4
5import { clean } from "./internal.js";

export function slugify(title) {
  return clean(title).replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
}

../slugger/src/internal.js

1
2// Not part of the public API: free to change in any release.
export const clean = (text) => text.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "");

../slugger/types/index.d.ts

1
2/** Turn a title into a URL slug: "Crème Brûlée" -> "creme-brulee". */
export declare function slugify(title: string): string;

../slugger/test/slugify.test.js

1
2
3
4
5import { test } from "node:test";
import assert from "node:assert/strict";
import { slugify } from "../src/index.js";

test("slugify", () => assert.equal(slugify("Crème Brûlée"), "creme-brulee"));

../slugger/TODO.txt

1rename internal.js before 2.0

../slugger/.env

1NPM_TOKEN=pretend-token-do-not-publish

../slugger/package.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "name": "slugger",
  "version": "1.0.0",
  "description": "Turn titles into URL slugs",
  "type": "module",
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "default": "./src/index.js"
    }
  },
  "files": ["src", "types"],
  "engines": { "node": ">=22" },
  "license": "MIT"
}

../slugger/README.md

1
2
3# slugger

Turn titles into URL slugs.

../slugger/src/index.js

1
2
3
4
5import { clean } from "./internal.js";

export function slugify(title) {
  return clean(title).replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
}

../slugger/src/internal.js

1
2// Not part of the public API: free to change in any release.
export const clean = (text) => text.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "");

../slugger/types/index.d.ts

1
2/** Turn a title into a URL slug: "Crème Brûlée" -> "creme-brulee". */
export declare function slugify(title: string): string;

../slugger/test/slugify.test.js

1
2
3
4
5import { test } from "node:test";
import assert from "node:assert/strict";
import { slugify } from "../src/index.js";

test("slugify", () => assert.equal(slugify("Crème Brûlée"), "creme-brulee"));

../slugger/TODO.txt

1rename internal.js before 2.0

../slugger/.env

1NPM_TOKEN=pretend-token-do-not-publish

package.json

1{ "name": "app", "version": "1.0.0", "private": true }

main.mjs

1
2
3import { slugify } from "slugger";

console.log(slugify("Crème Brûlée & Friends"));

deep.mjs

1
2
3import { clean } from "slugger/src/internal.js";

console.log(clean("Café"));

legacy.cjs

1
2
3
4// A CommonJS project using the ES-module-only package.
const { slugify } = require("slugger");

console.log("from require:", slugify("Hello, CommonJS"));

../slugger/package.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "name": "slugger",
  "version": "1.0.0",
  "description": "Turn titles into URL slugs",
  "type": "module",
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "default": "./src/index.js"
    }
  },
  "files": ["src", "types"],
  "engines": { "node": ">=22" },
  "license": "MIT"
}

../slugger/README.md

1
2
3# slugger

Turn titles into URL slugs.

../slugger/src/index.js

1
2
3
4
5import { clean } from "./internal.js";

export function slugify(title) {
  return clean(title).replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
}

../slugger/src/internal.js

1
2// Not part of the public API: free to change in any release.
export const clean = (text) => text.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "");

../slugger/types/index.d.ts

1
2/** Turn a title into a URL slug: "Crème Brûlée" -> "creme-brulee". */
export declare function slugify(title: string): string;

../slugger/test/slugify.test.js

1
2
3
4
5import { test } from "node:test";
import assert from "node:assert/strict";
import { slugify } from "../src/index.js";

test("slugify", () => assert.equal(slugify("Crème Brûlée"), "creme-brulee"));

../slugger/TODO.txt

1rename internal.js before 2.0

../slugger/.env

1NPM_TOKEN=pretend-token-do-not-publish

hello.js

1
2const name = process.argv[2] ?? "world";
console.log(`Hello, ${name}, from a single executable`);

sea-config.json

1{ "main": "hello.js", "output": "hello" }

package.json

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "name": "tally",
  "version": "1.0.0",
  "description": "Add up your expenses from CSV files",
  "type": "module",
  "bin": { "tally": "./src/cli.js" },
  "files": ["src"],
  "scripts": {
    "test": "node --test"
  },
  "engines": { "node": ">=24" },
  "license": "MIT"
}

expenses.csv

1
2
3
4
5
6
7
8
9
10
11date,category,description,amount
2026-08-02,Food,Groceries,54.20
2026-08-05,transport,Train to Leeds,38.50
2026-08-11,food,"Dinner, with Ada",42.00
2026-08-19,rent,August rent,950.00
2026-09-01,rent,September rent,950.00
2026-09-03,food,Groceries,61.75
2026-09-09,transport,Bus pass,abc
2026-09-14,fun,"Cinema ""Metropolis"" tickets",19.00
2026-09-31,food,Lunch,8.40
2026-09-22,transport,Taxi,16.80

src/csv.js

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
27
28
29
30
31
32
33
34
35
36
37
38
39// Split one line of CSV into fields. Handles "quoted, fields" and "" inside quotes.
export function parseCsvLine(line) {
  const fields = [];
  let field = "";
  let quoted = false;
  for (let i = 0; i < line.length; i++) {
    const char = line[i];
    if (quoted) {
      if (char === '"' && line[i + 1] === '"') { field += '"'; i++; }
      else if (char === '"') quoted = false;
      else field += char;
    } else if (char === '"') quoted = true;
    else if (char === ",") { fields.push(field); field = ""; }
    else field += char;
  }
  if (quoted) throw new SyntaxError("a quoted field is never closed");
  fields.push(field);
  return fields;
}

// Date.parse accepts "2026-09-31" and quietly means 1 October, so check the round trip.
function isRealDate(text) {
  if (!/^\d{4}-\d{2}-\d{2}$/.test(text) || Number.isNaN(Date.parse(text))) return false;
  return new Date(text).toISOString().slice(0, 10) === text;
}

// Turn the fields of one expense line into a checked record, or throw saying why not.
export function toExpense([date, category, description, amount, ...extra]) {
  if (extra.length > 0 || amount === undefined) throw new Error("expected 4 fields: date,category,description,amount");
  if (!isRealDate(date)) throw new Error(`"${date}" is not a date like 2026-09-30`);
  if (!/^\d+(\.\d{1,2})?$/.test(amount)) throw new Error(`"${amount}" is not an amount like 12.50`);
  if (category.trim() === "") throw new Error("the category is empty");
  return {
    date,
    category: category.trim().toLowerCase(),
    description: description.trim(),
    pence: Math.round(Number(amount) * 100),
  };
}

src/store.js

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
27
28
29
30
31
32
33
34
35
36
37import { DatabaseSync } from "node:sqlite";

export function openStore(file) {
  const db = new DatabaseSync(file);
  db.exec(`
    CREATE TABLE IF NOT EXISTS expenses (
      id          INTEGER PRIMARY KEY,
      date        TEXT    NOT NULL,
      category    TEXT    NOT NULL,
      description TEXT    NOT NULL,
      pence       INTEGER NOT NULL CHECK (pence >= 0)
    ) STRICT
  `);
  const insert = db.prepare("INSERT INTO expenses (date, category, description, pence) VALUES (?, ?, ?, ?)");

  return {
    // All or nothing: a crash halfway through leaves no half-imported file.
    add(expenses) {
      db.exec("BEGIN");
      try {
        for (const e of expenses) insert.run(e.date, e.category, e.description, e.pence);
        db.exec("COMMIT");
      } catch (err) {
        db.exec("ROLLBACK");
        throw err;
      }
    },
    totals(by) {
      const group = by === "month" ? "substr(date, 1, 7)" : "category";   // never user text
      return db.prepare(`
        SELECT ${group} AS name, count(*) AS count, sum(pence) AS pence
        FROM expenses GROUP BY name ORDER BY pence DESC, name
      `).all().map((row) => ({ ...row }));
    },
    close: () => db.close(),
  };
}

src/cli.js

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93#!/usr/bin/env node
import { parseArgs } from "node:util";
import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";
import { parseCsvLine, toExpense } from "./csv.js";
import { openStore } from "./store.js";

const HELP = `usage: tally <command> [options]

commands:
  import <file.csv>        add the expenses in a CSV file
  report [--by category]   totals by category (the default) or by month

options:
  --db <file>              the database to use (default: tally.db)
  -h, --help               show this help`;

class UsageError extends Error {}

const pounds = (pence) => (pence / 100).toFixed(2).padStart(10);

async function importFile(store, file) {
  const good = [];
  const problems = [];
  let lineNumber = 0;
  const lines = createInterface({ input: createReadStream(file), crlfDelay: Infinity });
  for await (const line of lines) {
    lineNumber++;
    if (lineNumber === 1 || line.trim() === "") continue;          // the header, and blank lines
    try {
      good.push(toExpense(parseCsvLine(line)));
    } catch (err) {
      problems.push(`line ${lineNumber}: ${err.message}`);
    }
  }
  store.add(good);
  console.log(`imported ${good.length} expenses from ${file}`);
  for (const problem of problems) console.error(`skipped ${problem}`);
  return problems.length === 0 ? 0 : 1;
}

function report(store, by) {
  const rows = store.totals(by);
  let total = 0;
  for (const row of rows) {
    console.log(`${row.name.padEnd(12)} ${String(row.count).padStart(3)} ${pounds(row.pence)}`);
    total += row.pence;
  }
  console.log(`${"total".padEnd(12)} ${" ".repeat(3)} ${pounds(total)}`);
  return 0;
}

async function main(argv) {
  const { values, positionals } = parseArgs({
    args: argv,
    allowPositionals: true,
    options: {
      db: { type: "string", default: "tally.db" },
      by: { type: "string", default: "category" },
      help: { type: "boolean", short: "h" },
    },
  });
  const [command, ...rest] = positionals;
  if (values.help || command === undefined) {
    console.log(HELP);
    return values.help ? 0 : 2;
  }
  if (command === "import" && rest.length !== 1) throw new UsageError("import needs exactly one file");
  if (command !== "import" && command !== "report") throw new UsageError(`unknown command "${command}"`);
  if (values.by !== "category" && values.by !== "month") throw new UsageError(`--by must be category or month, not "${values.by}"`);

  // Every mistake in the command line is reported above, before anything is opened or written.
  const store = openStore(values.db);
  try {
    return command === "import" ? await importFile(store, rest[0]) : report(store, values.by);
  } finally {
    store.close();
  }
}

try {
  process.exitCode = await main(process.argv.slice(2));
} catch (err) {
  if (err instanceof UsageError || err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
    console.error(`tally: ${err.message}\n(run "tally --help" for usage)`);
    process.exitCode = 2;
  } else if (err.code === "ENOENT") {
    console.error(`tally: cannot read ${err.path}: no such file`);
    process.exitCode = 1;
  } else {
    throw err;
  }
}

test/csv.test.js

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
27
28
29
30
31
32
33
34
35import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { parseCsvLine, toExpense } from "../src/csv.js";

describe("parseCsvLine", () => {
  it("splits on commas", () => {
    assert.deepEqual(parseCsvLine("a,b,c"), ["a", "b", "c"]);
  });
  it("keeps commas inside quotes", () => {
    assert.deepEqual(parseCsvLine('2026-08-11,food,"Dinner, with Ada",42.00'), ["2026-08-11", "food", "Dinner, with Ada", "42.00"]);
  });
  it('reads "" inside quotes as one quote', () => {
    assert.deepEqual(parseCsvLine('"say ""hi"""'), ['say "hi"']);
  });
  it("refuses a quote that is never closed", () => {
    assert.throws(() => parseCsvLine('a,"b'), SyntaxError);
  });
});

describe("toExpense", () => {
  it("converts pounds to whole pence", () => {
    assert.equal(toExpense(["2026-09-03", "Food", "Groceries", "61.75"]).pence, 6175);
  });
  it("lower-cases the category", () => {
    assert.equal(toExpense(["2026-09-03", " Food ", "x", "1"]).category, "food");
  });
  it("refuses 31 September, which Date.parse would accept", () => {
    assert.throws(() => toExpense(["2026-09-31", "food", "x", "1"]), /not a date/);
  });
  it("refuses an amount that is not money", () => {
    for (const amount of ["abc", "-5", "1.234", ""]) {
      assert.throws(() => toExpense(["2026-09-03", "food", "x", amount]), /not an amount/, amount);
    }
  });
});

test/cli.test.js

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51import { describe, it, beforeEach, afterEach } from "node:test";
import assert from "node:assert/strict";
import { execFile } from "node:child_process";
import { mkdtemp, writeFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";

const CLI = fileURLToPath(new URL("../src/cli.js", import.meta.url));

// Run the real command, as a user would, and collect everything about how it ended.
function tally(args, cwd) {
  return new Promise((resolve) => {
    execFile(process.execPath, [CLI, ...args], { cwd }, (err, stdout, stderr) => {
      resolve({ code: err ? err.code : 0, stdout, stderr });
    });
  });
}

describe("the tally command", () => {
  let dir;
  beforeEach(async () => { dir = await mkdtemp(join(tmpdir(), "tally-")); });   // a fresh folder, and database, per test
  afterEach(() => rm(dir, { recursive: true, force: true }));

  it("imports a file and reports totals by category", async () => {
    await writeFile(join(dir, "in.csv"), "date,category,description,amount\n2026-09-01,rent,Rent,950.00\n2026-09-03,food,Groceries,61.75\n2026-09-04,food,Lunch,8.25\n");
    assert.equal((await tally(["import", "in.csv"], dir)).code, 0);

    const { code, stdout } = await tally(["report"], dir);
    assert.equal(code, 0);
    assert.deepEqual(stdout.trim().split("\n").map((line) => line.split(/\s+/)), [
      ["rent", "1", "950.00"],
      ["food", "2", "70.00"],
      ["total", "1020.00"],
    ]);
  });

  it("skips bad lines, says which, and exits 1", async () => {
    await writeFile(join(dir, "in.csv"), "date,category,description,amount\n2026-09-03,food,Groceries,61.75\n2026-09-09,transport,Bus,abc\n");
    const { code, stdout, stderr } = await tally(["import", "in.csv"], dir);
    assert.equal(code, 1);
    assert.match(stdout, /imported 1 expenses/);
    assert.match(stderr, /line 3: "abc" is not an amount/);
  });

  it("exits 2 for a usage mistake", async () => {
    const { code, stderr } = await tally(["report", "--by", "colour"], dir);
    assert.equal(code, 2);
    assert.match(stderr, /--by must be category or month/);
  });
});

../books/package.json

1{ "name": "books", "version": "1.0.0", "private": true }

../books/september.csv

1
2
3
4date,category,description,amount
2026-09-02,food,Groceries,48.10
2026-09-05,books,"Node, from zero",24.99
2026-09-12,food,Market,17.35