Build: a notes CLI that stores JSON on disk

// A file-safe name from a title: small letters and digits, words joined by -.
export function slugify(title) {
  return title.toLowerCase();
}

// True only for a name that slugify could have made, such as buy-milk.
export function isSlug(text) {
  return text !== '';
}

console.log(slugify('  Buy Milk!  '), isSlug('../main'));

import {test} from 'node:test';
import assert from 'node:assert/strict';
import {isSlug, slugify} from './main.js';

test('"  Buy Milk!  " becomes buy-milk', () => {
  assert.equal(slugify('  Buy Milk!  '), 'buy-milk', `slugify returned ${JSON.stringify(slugify('  Buy Milk!  '))}`);
});

test('runs of other characters become one -', () => {
  assert.equal(slugify('Ideas: 2026 -- draft'), 'ideas-2026-draft', `slugify returned ${JSON.stringify(slugify('Ideas: 2026 -- draft'))}`);
});

test('a title without letters or digits throws an Error naming it', () => {
  assert.throws(() => slugify('!!!'), {message: /!!!/}, 'slugify("!!!") should throw an Error whose message contains !!!');
});

test('isSlug accepts slugs only', () => {
  for (const text of ['buy-milk', '2026', 'a1-b2']) assert.equal(isSlug(text), true, `isSlug(${JSON.stringify(text)}) should be true`);
  for (const text of ['../main', 'Buy-Milk', 'a--b', '-a', 'a-', '', 'a b']) assert.equal(isSlug(text), false, `isSlug(${JSON.stringify(text)}) should be false`);
});

{
  "type": "module"
}

// Checks a value read from a note file; returns {title, body} or throws.
export function validateNote(value) {
  return value;
}

console.log(validateNote({title: 'Buy milk', body: 'two litres', colour: 'red'}));

import {test} from 'node:test';
import assert from 'node:assert/strict';
import {validateNote} from './main.js';

test('a good note comes back with title and body only', () => {
  const got = validateNote({title: 'Buy milk', body: 'two litres', colour: 'red'});
  assert.deepEqual(got, {title: 'Buy milk', body: 'two litres'}, `validateNote returned ${JSON.stringify(got)}`);
});

test('an empty body is fine', () => {
  const got = validateNote({title: 'Call Ada', body: ''});
  assert.deepEqual(got, {title: 'Call Ada', body: ''}, `validateNote returned ${JSON.stringify(got)}`);
});

test('null, an array and a string are not notes', () => {
  for (const value of [null, [], 'Buy milk']) assert.throws(() => validateNote(value), Error, `validateNote(${JSON.stringify(value)}) should throw`);
});

test('a missing or empty title throws', () => {
  for (const value of [{body: 'x'}, {title: '', body: 'x'}, {title: '   ', body: 'x'}, {title: 42, body: 'x'}]) {
    assert.throws(() => validateNote(value), Error, `validateNote(${JSON.stringify(value)}) should throw`);
  }
});

test('a body that is not a string throws', () => {
  assert.throws(() => validateNote({title: 'Buy milk'}), Error, 'validateNote without a body should throw');
  assert.throws(() => validateNote({title: 'Buy milk', body: 2}), Error, 'validateNote with body 2 should throw');
});

{
  "type": "module"
}

// The output of list: one line per note, sorted by slug or newest first.
export function formatListing(records, by = 'name') {
  return records.map((r) => r.slug).join('\n');
}

const records = [
  {slug: 'call-ada', title: 'Call Ada', size: 49, mtimeMs: 200},
  {slug: 'buy-milk', title: 'Buy milk', size: 50, mtimeMs: 100}
];
console.log(formatListing(records));

import {test} from 'node:test';
import assert from 'node:assert/strict';
import {formatListing} from './main.js';

const records = [
  {slug: 'call-ada', title: 'Call Ada', size: 49, mtimeMs: 200},
  {slug: 'buy-milk', title: 'Buy milk', size: 50, mtimeMs: 100}
];

test('sorted by slug, one line per note', () => {
  const got = formatListing(records);
  assert.equal(got, 'buy-milk  Buy milk  (50 bytes)\ncall-ada  Call Ada  (49 bytes)\n', `formatListing returned ${JSON.stringify(got)}`);
});

test('newest first with "newest"', () => {
  const got = formatListing(records, 'newest');
  assert.equal(got, 'call-ada  Call Ada  (49 bytes)\nbuy-milk  Buy milk  (50 bytes)\n', `formatListing returned ${JSON.stringify(got)}`);
});

test('no records give no notes yet', () => {
  assert.equal(formatListing([]), 'no notes yet\n', `formatListing([]) returned ${JSON.stringify(formatListing([]))}`);
});

test('the array passed in keeps its order', () => {
  const copy = [...records];
  formatListing(copy);
  assert.deepEqual(copy, records, 'formatListing changed the order of the array it was given');
});

{
  "type": "module"
}

import {mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile} from 'node:fs/promises';
import {join} from 'node:path';
import {parseArgs} from 'node:util';
import {formatListing, isSlug, slugify, validateNote} from './notes.js';

const USAGE = 'Usage: node main.js <save|list|show|delete|clear> [title or slug] [--body <text>] [--newest] [--dir <folder>]';

async function loadNote(dir, slug) {
  return validateNote(JSON.parse(await readFile(join(dir, slug + '.json'), 'utf8')));
}

async function deleteNote(dir, slug) {
  await rm(join(dir, slug + '.json'));
}

// One file per note: <dir>/<slug>.json, replaced in one step.
async function saveNote(dir, note) {
  const slug = slugify(note.title);
  await writeFile(join(dir, slug + '.json'), JSON.stringify(note));
  return slug;
}

// A record for every *.json file in dir; a missing dir means no notes yet.
async function listNotes(dir) {
  return [];
}

// Deletes every note, then the folder itself if nothing else is left in it.
async function clearNotes(dir) {}

// What to print, and the exit code: 0 = done, 1 = a note problem, 2 = wrong usage.
async function run(args) {
  let values, positionals;
  try {
    ({values, positionals} = parseArgs({
      args,
      options: {
        body: {type: 'string', default: ''},
        dir: {type: 'string', default: join(import.meta.dirname, 'notes')},
        newest: {type: 'boolean'}
      },
      allowPositionals: true
    }));
  } catch (error) {
    return {out: '', err: error.message + '\n' + USAGE + '\n', code: 2};
  }
  const [command, name, ...rest] = positionals;
  const named = name !== undefined && rest.length === 0;
  const {dir} = values;
  try {
    if (command === 'save' && named) return {out: 'saved ' + (await saveNote(dir, {title: name, body: values.body})) + '\n', err: '', code: 0};
    if (command === 'list' && name === undefined) return {out: formatListing(await listNotes(dir), values.newest ? 'newest' : 'name'), err: '', code: 0};
    if (command === 'clear' && name === undefined) {
      await clearNotes(dir);
      return {out: 'cleared\n', err: '', code: 0};
    }
    if ((command === 'show' || command === 'delete') && named) {
      if (!isSlug(name)) return {out: '', err: 'not a note name: ' + name + '\n', code: 2};
      if (command === 'delete') {
        await deleteNote(dir, name);
        return {out: 'deleted ' + name + '\n', err: '', code: 0};
      }
      const note = await loadNote(dir, name);
      return {out: note.title + '\n\n' + note.body + '\n', err: '', code: 0};
    }
  } catch (error) {
    if (error.code === 'ENOENT') return {out: '', err: 'no note: ' + name + '\n', code: 1};
    return {out: '', err: 'error: ' + error.message + '\n', code: 1};
  }
  return {out: '', err: USAGE + '\n', code: 2};
}

// The only lines that touch the real process.
const {out, err, code} = await run(process.argv.slice(2));
process.stdout.write(out);
process.stderr.write(err);
process.exitCode = code;

import {test} from 'node:test';
import assert from 'node:assert/strict';
import {runMain} from './learnrun.js';

// A folder of its own for this test run, inside the exercise folder.
const dir = 'test-notes-' + Date.now() + '-' + Math.floor(Math.random() * 1e6);
const notes = async (...args) => runMain({args: [...args, '--dir', dir]});

test('list before any save prints no notes yet', async () => {
  const got = await notes('list');
  assert.equal(got, 'no notes yet\n', `list printed ${JSON.stringify(got)}`);
});

test('save creates the folder and prints saved buy-milk', async () => {
  const got = await notes('save', 'Buy milk', '--body', 'two litres');
  assert.equal(got, 'saved buy-milk\n', `save printed ${JSON.stringify(got)}`);
});

test('list shows the note with the size of its indented JSON', async () => {
  const got = await notes('list');
  assert.equal(got, 'buy-milk  Buy milk  (50 bytes)\n', `list printed ${JSON.stringify(got)}`);
});

test('a second note: list is sorted by slug', async () => {
  await notes('save', 'Call Ada', '--body', 'ring back');
  const got = await notes('list');
  assert.equal(got, 'buy-milk  Buy milk  (50 bytes)\ncall-ada  Call Ada  (49 bytes)\n', `list printed ${JSON.stringify(got)}`);
});

test('saving the same slug again replaces the note', async () => {
  await notes('save', 'buy  MILK', '--body', 'one litre');
  const got = (await notes('list')).split('\n')[0];
  assert.equal(got, 'buy-milk  buy  MILK  (50 bytes)', `the first line of list was ${JSON.stringify(got)}`);
  const shown = await notes('show', 'buy-milk');
  assert.equal(shown, 'buy  MILK\n\none litre\n', `show printed ${JSON.stringify(shown)}`);
});

test('clear removes every note', async () => {
  const cleared = await notes('clear');
  assert.equal(cleared, 'cleared\n', `clear printed ${JSON.stringify(cleared)}`);
  const got = await notes('list');
  assert.equal(got, 'no notes yet\n', `after clear, list printed ${JSON.stringify(got)}`);
});

// Pure functions: no fs, no process, so they run anywhere.

// A file-safe name from a title: small letters and digits, words joined by -.
export function slugify(title) {
  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
  if (slug === '') throw new Error('the title "' + title + '" has no letters or digits');
  return slug;
}

// True only for a name that slugify could have made, such as buy-milk.
export function isSlug(text) {
  return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(text);
}

// Checks a value read from a note file; returns {title, body} or throws.
export function validateNote(value) {
  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('a note must be an object');
  if (typeof value.title !== 'string' || value.title.trim() === '') throw new Error('a note needs a title');
  if (typeof value.body !== 'string') throw new Error('the body of a note must be text');
  return {title: value.title, body: value.body};
}

// The output of list: one line per note, sorted by slug or newest first.
export function formatListing(records, by = 'name') {
  if (records.length === 0) return 'no notes yet\n';
  const order = by === 'newest' ? (a, b) => b.mtimeMs - a.mtimeMs : (a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0);
  return [...records].sort(order).map((r) => r.slug + '  ' + r.title + '  (' + r.size + ' bytes)').join('\n') + '\n';
}

{
  "type": "module"
}