tablewalk 0.0.1

package/dist/server/journal.js

@@ -0,0 +1,173 @@
+/** Enough to walk back a mistake, not a session. Matches the browser's depth. */
+const DEPTH = 50;
+/* Per connection: a write on staging is not undoable on production, and a
+   single stack would offer exactly that. */
+const journals = new Map();
+let nextId = 1;
+const entriesFor = (connection) => {
+    if (!journals.has(connection))
+        journals.set(connection, []);
+    return journals.get(connection);
+};
+/** Record a write that landed. Returns the entry, mostly for tests. */
+export function recordWrite(connection, entry) {
+    const full = {
+        id: nextId++,
+        connection,
+        at: new Date().toISOString(),
+        ...entry,
+    };
+    const list = entriesFor(connection);
+    list.push(full);
+    if (list.length > DEPTH)
+        list.shift();
+    return full;
+}
+/** The most recent first, which is the order anyone asks about them in. */
+export function history(connection, limit = 10) {
+    return [...entriesFor(connection)].reverse().slice(0, Math.max(1, limit));
+}
+/** The newest write that could still be undone, if there is one. */
+export function lastRevertible(connection) {
+    return [...entriesFor(connection)].reverse().find((e) => e.revertible);
+}
+export function forget(connection, id) {
+    const list = entriesFor(connection);
+    const at = list.findIndex((e) => e.id === id);
+    if (at !== -1)
+        list.splice(at, 1);
+}
+/** Testing seam: a fresh process is the normal state, and tests want it too. */
+export function clearJournal(connection) {
+    if (connection === undefined)
+        journals.clear();
+    else
+        journals.delete(connection);
+}
+const keyFilter = (key) => ({
+    groups: [Object.entries(key).map(([column, value]) => ({
+            column,
+            op: '=',
+            value: value,
+        }))],
+});
+/** The row as it stands now, or undefined if it is gone. */
+async function currentRow(adapter, table, key) {
+    const result = await adapter.query({ table, filter: keyFilter(key), limit: 1, offset: 0 });
+    return result.rows[0];
+}
+/* Compared as strings, because a value that went through the database and came
+   back may be a different JavaScript type than the one that went in — SQLite
+   hands back an integer for a boolean, and a driver may widen a numeric. The
+   question is "is this still the value we wrote", not "is this the same
+   object". */
+const same = (a, b) => a === b || (a ?? null) === (b ?? null) || String(a ?? '') === String(b ?? '');
+/**
+ * Undo one recorded write.
+ *
+ * Every step is checked against the database before anything is written, and
+ * the whole revert is refused if any of them has moved on. Half an undo is
+ * worse than none: it leaves the row in a state neither the write nor the
+ * revert intended, and nothing recorded that it happened.
+ */
+export async function revert(adapter, connection, entry) {
+    if (!entry.revertible) {
+        return { reverted: false, entry, errors: [entry.reason ?? 'That write cannot be undone.'] };
+    }
+    if (!adapter.update || !adapter.insert || !adapter.remove) {
+        return { reverted: false, entry, errors: ['This connection cannot write in this build.'] };
+    }
+    /* An insert is undone by removing what it added, and a delete by putting it
+       back — so a graph's steps are reversed, children before parents or the
+       other way round depending on which it was. The order a graph went in is
+       the order it must come out of, backwards. */
+    const steps = entry.kind === 'insert_graph' || entry.kind === 'delete_graph'
+        ? [...entry.steps].reverse()
+        : entry.steps;
+    const undoing = entry.kind === 'insert' || entry.kind === 'insert_graph'
+        ? 'remove'
+        : entry.kind === 'delete' || entry.kind === 'delete_graph'
+            ? 'restore'
+            : 'put back';
+    /* Checked first, all of it, before anything is written. */
+    const problems = [];
+    for (const step of steps) {
+        if (!step.key) {
+            problems.push(`A ${step.table} row in this write has no key, so it cannot be found again.`);
+            continue;
+        }
+        const row = await currentRow(adapter, step.table, step.key);
+        if (undoing === 'restore') {
+            /* The row was deleted; putting it back is only honest if nothing has
+               taken its key since. */
+            if (row)
+                problems.push(`${step.table} ${describe(step.key)} exists again, so restoring it would overwrite something.`);
+            continue;
+        }
+        if (!row) {
+            problems.push(`${step.table} ${describe(step.key)} is gone, so there is nothing to undo.`);
+            continue;
+        }
+        const moved = Object.entries(step.after ?? {}).filter(([column, value]) => !same(row[column], value));
+        if (moved.length) {
+            problems.push(`${step.table} ${describe(step.key)} has changed since — "${moved[0][0]}" is no longer what this write left. `
+                + 'Undoing would overwrite that.');
+        }
+    }
+    if (problems.length)
+        return { reverted: false, entry, errors: problems };
+    const done = [];
+    try {
+        for (const step of steps) {
+            if (undoing === 'remove') {
+                await adapter.remove({ table: step.table, key: step.key });
+                done.push({ table: step.table, key: step.key, action: 'removed' });
+            }
+            else if (undoing === 'restore') {
+                await adapter.insert({
+                    table: step.table,
+                    values: (step.before ?? {}),
+                });
+                done.push({ table: step.table, key: step.key, action: 'restored' });
+            }
+            else {
+                await adapter.update({
+                    table: step.table,
+                    key: step.key,
+                    values: (step.before ?? {}),
+                });
+                done.push({ table: step.table, key: step.key, action: 'put back' });
+            }
+        }
+    }
+    catch (err) {
+        /* Reported with what had already been done rather than swallowed: a
+           partial revert is a fact about the database, and hiding it would leave
+           someone to discover it later without knowing why. */
+        return {
+            reverted: false,
+            entry,
+            steps: done,
+            errors: [`${err.message}${done.length ? ` — ${done.length} step(s) had already been undone.` : ''}`],
+        };
+    }
+    forget(connection, entry.id);
+    return { reverted: true, entry, steps: done };
+}
+const describe = (key) => {
+    const parts = Object.entries(key);
+    return parts.length === 1 ? String(parts[0][1]) : parts.map(([c, v]) => `${c}=${v}`).join(',');
+};
+/** A sentence for the history, in the words someone would use about it. */
+export function summarise(kind, steps, detail) {
+    const table = steps[0]?.table ?? 'something';
+    const n = steps.length;
+    switch (kind) {
+        case 'update': return `Updated ${table} ${steps[0]?.key ? describe(steps[0].key) : ''}`.trim();
+        case 'insert': return `Inserted into ${table}`;
+        case 'delete': return `Deleted ${table} ${steps[0]?.key ? describe(steps[0].key) : ''}`.trim();
+        case 'insert_graph': return `Inserted ${n} row${n === 1 ? '' : 's'} as one graph`;
+        case 'delete_graph': return `Deleted ${n} row${n === 1 ? '' : 's'} as one graph`;
+        default: return detail ? `Ran SQL: ${detail}` : 'Ran a SQL write';
+    }
+}

package/dist/server/layouts.js

@@ -0,0 +1,128 @@
+/**
+ * Record layouts, on disk.
+ *
+ * A layout is bound to a table and applies to every record of it, which makes
+ * it the longest-lived thing tablewalk holds: a query is asked once, a filter
+ * tab lasts a session, but "this is how a work order is laid out" is a
+ * decision made once and relied on afterwards. Keeping it in localStorage
+ * meant it lived exactly as long as the browser profile that made it — a
+ * different browser, a cleared site setting, or a second machine and the
+ * work was gone with no way to get it back.
+ *
+ * So layouts are stored server-side, in a file the user can read, diff, copy
+ * between machines and check into a repo if they want to share them. Two
+ * things follow from that choice and are deliberate:
+ *
+ *   - The file holds *only* layouts. It is written by the app, so it must not
+ *     be a file the user also hand-maintains; connections stay in
+ *     tablewalk.json, which the app never writes.
+ *   - Layouts are keyed by connection id and then table id, because the same
+ *     table name means different things on different databases and a layout
+ *     built for one should not quietly apply to another.
+ *
+ * Unlike credentials there is no secret here, so there is no permission
+ * discipline to enforce — a layout is a preference, and a readable file is
+ * the point rather than a risk.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function layoutsPath() {
+    const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(xdg, 'tablewalk', 'layouts.json');
+}
+/**
+ * Saved pages live in a sibling file with the same shape — connection id,
+ * then page id. The same shape because it earns the same machinery: pages
+ * were the one piece of built work that lived only in localStorage, so a
+ * page assembled in one browser was invisible to every other, while the
+ * record layout beside it travelled. Same store, same guarantees.
+ */
+export function pagesPath() {
+    const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(xdg, 'tablewalk', 'pages.json');
+}
+/**
+ * Read every stored layout.
+ *
+ * A missing file is the normal case — most connections have never had a
+ * layout saved — and an unreadable one falls back to empty rather than
+ * refusing to serve the page. A record with its derived layout is a working
+ * page; a record that will not render because a preferences file has a stray
+ * comma in it is not.
+ */
+export async function readLayouts(path = layoutsPath()) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        /* No file, or an unparseable one. Either way there are no layouts. */
+    }
+    return {};
+}
+/** Every layout for one connection. */
+export async function layoutsFor(connection, path = layoutsPath()) {
+    return (await readLayouts(path))[connection] ?? {};
+}
+/**
+ * Store or remove one table's layout.
+ *
+ * Read-modify-write on the whole file rather than a patch, because the file
+ * is small and the alternative is a format that supports partial updates —
+ * complexity bought with nothing. Passing `null` removes the entry, which is
+ * what "Reset to default" means: not an empty layout, but no layout, so the
+ * derived one takes over again.
+ */
+/**
+ * One write at a time.
+ *
+ * Saving a layout is read-the-whole-file, change one key, write the whole file
+ * back. Two saves that overlap both read the same file, and the second write
+ * lands on top of the first — so a layout saved in one tab disappeared when a
+ * layout was saved in another, with nothing to say it had. The window is
+ * small and the loss is silent, which is the combination that makes it a bug
+ * report nobody can reproduce.
+ *
+ * A promise chain rather than a lock: each write waits for the one before it,
+ * so the read that decides what to write always sees the previous write's
+ * result.
+ *
+ * One chain *per file*, not one per process. The race is two writes to the
+ * same file, and a single chain also made every unrelated file wait — layouts
+ * behind pages, this connection's behind another's, and a write that is slow
+ * or stuck on one path holding up every path. The invariant is about a file,
+ * so the queue is about a file.
+ */
+const writing = new Map();
+export function writeLayout(connection, table, layout, path = layoutsPath()) {
+    /* Chained off the previous write to *this file* whether it succeeded or
+       not: one failed save must not stop every later one, which is what
+       chaining off a rejected promise would do. */
+    const queued = (writing.get(path) ?? Promise.resolve())
+        .catch(() => { })
+        .then(() => writeLayoutNow(connection, table, layout, path));
+    writing.set(path, queued);
+    /* Cleared when it is the last write to that path, so a long-lived process
+       does not accumulate an entry per file it has ever written. */
+    void queued.catch(() => { }).then(() => {
+        if (writing.get(path) === queued)
+            writing.delete(path);
+    });
+    return queued;
+}
+async function writeLayoutNow(connection, table, layout, path) {
+    const all = await readLayouts(path);
+    const forConnection = { ...(all[connection] ?? {}) };
+    if (layout)
+        forConnection[table] = layout;
+    else
+        delete forConnection[table];
+    if (Object.keys(forConnection).length)
+        all[connection] = forConnection;
+    else
+        delete all[connection];
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(all, null, 2)}\n`);
+}