notes: pure db.json helpers, node-tested

The parsing, sorting and transforms the notes page needs, kept free of any
file or process so node can test them.

Ids and files stay strings: notes.sh writes them with jq --arg and looks a
note up with select(.id == $i), so a number would stop the CLI finding a
note the page wrote. sorted() copies rather than reorders, and an entry
whose file is missing or non-numeric sorts last and formats as blank
instead of NaN.

2 files changed, 183 insertions, 0 deletions

diff --git a/desktop/modules/notes/Notes.js b/desktop/modules/notes/Notes.js
new file mode 100644
index 0000000..76c8f95
--- /dev/null
+++ b/desktop/modules/notes/Notes.js
@@ -0,0 +1,113 @@
+.pragma library
+
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// Pure helpers for the notes module, tested by test_notes.js under node.
+// Everything here is a value in and a value out: no file, no process.
+
+function titleOf(note) {
+    return (note && typeof note.title === "string") ? note.title : "";
+}
+
+function notesOf(db) {
+    return (db && Array.isArray(db.notes)) ? db.notes : [];
+}
+
+// db.json, whole. Anything that is not an object carrying a notes array reads
+// as an empty store, so a truncated or hand-edited file shows "no notes"
+// rather than failing to load the page.
+function parse(text) {
+    let v = null;
+    try { v = JSON.parse(text); } catch (e) { v = null; }
+    if (!v || typeof v !== "object" || Array.isArray(v) || !Array.isArray(v.notes))
+        return { notes: [] };
+    return v;
+}
+
+// Pretty, 2-space, trailing newline. notes.sh reads db.json through jq, which
+// does not care about the layout.
+function stringify(db) {
+    return JSON.stringify(db, null, 2) + "\n";
+}
+
+// Notes newest first. `file` is epoch seconds held as a string; a missing or
+// non-numeric one is unusable and goes last, in input order. A copy: the
+// caller's array is never reordered.
+function sorted(notes) {
+    const usable = [], unusable = [];
+    for (const n of (notes || [])) {
+        const t = Number(n && n.file);
+        (isFinite(t) && t > 0 ? usable : unusable).push(n);
+    }
+    usable.sort((a, b) => Number(b.file) - Number(a.file));
+    return usable.concat(unusable);
+}
+
+// "dd/mm/yyyy hh:mm" in local time from an epoch-seconds string, "" for
+// anything unusable, so a row with no date shows blank rather than NaN.
+function formatDate(file) {
+    const t = Number(file);
+    if (!isFinite(t) || t <= 0) return "";
+    const d = new Date(t * 1000);
+    const p = n => String(n).padStart(2, "0");
+    return p(d.getDate()) + "/" + p(d.getMonth() + 1) + "/" + d.getFullYear()
+        + " " + p(d.getHours()) + ":" + p(d.getMinutes());
+}
+
+// The next id: the highest numeric id plus one, as a string. notes.sh stores
+// ids as strings and looks a note up with `select(.id == $i)`, comparing
+// string to string, so a number here would stop the CLI finding a note the
+// page wrote.
+function nextId(notes) {
+    let max = 0;
+    for (const n of (notes || [])) {
+        const i = parseInt(n && n.id, 10);
+        if (isFinite(i) && i > max) max = i;
+    }
+    return String(max + 1);
+}
+
+// Title substring, case-insensitive; an empty query keeps all.
+function filter(notes, query) {
+    const q = String(query === undefined || query === null ? "" : query).trim().toLowerCase();
+    if (q === "") return notes || [];
+    return (notes || []).filter(n => titleOf(n).toLowerCase().indexOf(q) >= 0);
+}
+
+// A new db with a note appended. title and file are stored as strings; the id
+// comes from nextId. Every other key carries through and the input is not
+// mutated.
+function addNote(db, title, file) {
+    const notes = notesOf(db);
+    const entry = { id: nextId(notes), title: String(title === undefined ? "" : title),
+                    file: String(file === undefined ? "" : file) };
+    return Object.assign({}, db, { notes: notes.concat([entry]) });
+}
+
+// A new db with one note's title replaced. An id that is not there leaves the
+// notes untouched.
+function updateNote(db, id, title) {
+    const notes = notesOf(db).map(n =>
+        n.id === id ? Object.assign({}, n, { title: String(title === undefined ? "" : title) }) : n);
+    return Object.assign({}, db, { notes: notes });
+}
+
+// A new db without the note this id names.
+function removeNote(db, id) {
+    return Object.assign({}, db, { notes: notesOf(db).filter(n => n.id !== id) });
+}
+
+// A new db with git.lastpull set, as a string, the way notes.sh's gitsync
+// writes it. It is what notes.sh -l reads to decide whether to pull again.
+function setLastpull(db, now) {
+    return Object.assign({}, db, { git: Object.assign({}, db.git, { lastpull: String(now) }) });
+}
diff --git a/desktop/modules/notes/test_notes.js b/desktop/modules/notes/test_notes.js
new file mode 100644
index 0000000..955369c
--- /dev/null
+++ b/desktop/modules/notes/test_notes.js
@@ -0,0 +1,70 @@
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// Run: node desktop/modules/notes/test_notes.js
+// Notes.js is a QML library, so its .pragma line is stripped before node
+// evaluates it, as test_clip.js does for Clip.js.
+
+const fs = require("fs");
+const assert = require("assert");
+
+const src = fs.readFileSync(__dirname + "/Notes.js", "utf8")
+    .replace(/^\.pragma library$/m, "");
+const N = new Function(src + "\nreturn { parse, stringify, sorted, formatDate, nextId,"
+    + " filter, addNote, updateNote, removeNote, setLastpull };")();
+
+const db = {
+    params: { version: "0.4git", dbversion: "0.4git_1" },
+    git: { lastpull: "1700000000" },
+    notes: [
+        { id: "1", title: "a", file: "999" },
+        { id: "2", title: "b", file: "1000" },
+        { id: "3", title: "c", file: "300" },
+    ],
+};
+
+// numeric, not lexicographic: 1000 > 999 > 300
+assert.deepStrictEqual(N.sorted(db.notes).map(n => n.id), ["2", "1", "3"]);
+assert.strictEqual(db.notes[0].id, "1");                 // input not reordered
+
+// a missing or non-numeric file sorts last, input order, and formats as ""
+const bad = [{ id: "1", title: "x" }, { id: "2", title: "y", file: "abc" },
+             { id: "3", title: "z", file: "10" }];
+assert.deepStrictEqual(N.sorted(bad).map(n => n.id), ["3", "1", "2"]);
+assert.strictEqual(N.formatDate(undefined), "");
+assert.strictEqual(N.formatDate("abc"), "");
+assert.match(N.formatDate("1000"), /^\d{2}\/\d{2}\/\d{4} \d{2}:\d{2}$/);
+
+assert.strictEqual(N.nextId(db.notes), "4");
+assert.strictEqual(N.nextId([]), "1");
+
+// the whole object round-trips; params and git are kept
+assert.deepStrictEqual(N.parse(N.stringify(db)), db);
+assert.deepStrictEqual(N.parse("not json"), { notes: [] });
+assert.deepStrictEqual(N.parse('{"a":1}'), { notes: [] });
+
+// pure transforms preserve everything else and do not mutate
+const added = N.addNote(db, "T", "1750");
+assert.strictEqual(added.notes.length, 4);
+assert.deepStrictEqual(added.notes[3], { id: "4", title: "T", file: "1750" });
+assert.strictEqual(db.notes.length, 3);
+assert.deepStrictEqual(added.params, db.params);
+assert.deepStrictEqual(added.git, db.git);
+assert.deepStrictEqual(N.removeNote(added, "4"), db);
+assert.strictEqual(N.updateNote(db, "2", "Renamed").notes[1].title, "Renamed");
+assert.deepStrictEqual(N.updateNote(db, "99", "x"), db);
+assert.strictEqual(N.setLastpull(db, 1234).git.lastpull, "1234");
+assert.strictEqual(db.git.lastpull, "1700000000");
+
+assert.deepStrictEqual(N.filter(db.notes, "  A ").map(n => n.id), ["1"]);
+assert.strictEqual(N.filter(db.notes, "").length, 3);
+
+console.log("test_notes: ok");