tablewalk 0.0.1

package/dist/client/deeplink.js

@@ -0,0 +1,270 @@
+/**
+ * Deep links: the pure half.
+ *
+ * No DOM and no state, so it can be tested directly. The stateful half —
+ * reading `window.location`, deciding when to write it — lives in url.js.
+ *
+ * The design decision that matters: **the trail goes in the URL, not just the
+ * current position.** A link to a row you reached by walking should arrive
+ * with the walk intact, so whoever you send it to can go back the way you
+ * came. That is the tool's whole idea, and a link that dropped it would hand
+ * them a dead end.
+ *
+ * The hash is used rather than the path because tablewalk serves a static
+ * client from a small server with no router. A path-based URL would need the
+ * server to know every route; a hash never reaches it.
+ *
+ * Compactness matters, because these get pasted into chat. A table view is
+ * its query text, already short and human-readable; a row is its key:
+ *
+ *   /demo/customer/~4/invoice%20customer_id%20=%204/~1004
+ */
+
+/** A table view. Mirrors core.js — kept here so this module imports nothing. */
+/* The tabs a table view can be on — see the tab strip in table.js. A segment
+   ends in one of these or it does not end in a tab at all. */
+const TABS = new Set(['rows', 'ddl', 'diagram']);
+
+/**
+ * A query, safe to put after a `!` separator.
+ *
+ * `encodeURIComponent` leaves `!` alone — it is an unreserved character — so
+ * a query containing `!=` wrote a second separator into its own segment.
+ */
+function encodeQuery(query) {
+  return encodeURIComponent(query).replace(/!/g, '%21');
+}
+
+/**
+ * A key, as it appears in a link.
+ *
+ * Single-column keys — nearly all of them — are just the value, so the common
+ * case stays readable; composite keys name their columns, because position
+ * alone would not survive a column being added.
+ *
+ * Shared by rows and pages so the two cannot spell the same key differently.
+ */
+function keyBody(key) {
+  const columns = Object.keys(key);
+  return columns.length === 1
+    ? String(key[columns[0]])
+    : columns.map((c) => `${c}=${key[c]}`).join(',');
+}
+
+function tableView(tableId, query, tab) {
+  return { kind: 'table', table: tableId, query: query ?? tableId, tab: tab ?? 'rows' };
+}
+
+/**
+ * Serialise a connection id and a stack into a hash.
+ *
+ * `pageToken` turns a page's id into the text a link should carry — its name,
+ * where that names it unambiguously. Passed in rather than imported: this
+ * module deliberately depends on nothing, which is what lets the link format
+ * be tested without a browser, and the page list it would need to consult
+ * lives three modules away. The default writes the id, which is what every
+ * link did before and still resolves.
+ */
+export function hashFor(connectionId, stack, { pageToken = (id) => id } = {}) {
+  const parts = [encodeURIComponent(connectionId ?? '')];
+  stack.forEach((entry, index) => {
+    if (entry.kind === 'page') {
+      /* `@page-id` for the page, and the root — when one has been chosen —
+         written exactly as a row's key is, so the two agree about composite
+         keys instead of inventing a second spelling for them. A page with no
+         root is a link to the front door, which is a real place to send
+         someone: "open the customer page and pick one". */
+      /* `rootBody` is the unresolved form a link arrives with, and it is
+         written back when the key has not been resolved yet. Boot renders —
+         and stamps the hash — before the page has looked up which column a
+         bare key belongs to, so without this the first paint dropped the root
+         out of the address bar and the reader lost it by reloading. */
+      const body = entry.key ? keyBody(entry.key) : (entry.rootBody ?? '');
+      /* The open tab rides with the page rather than after the key: a key is
+         arbitrary text and may contain a `!`, while a page token is a slug or
+         an id and never does. "Look at the parts tab" is a thing people send
+         each other, and a link that always lands on the first tab loses the
+         point of sending it. */
+      const tab = entry.tab ? `!${encodeURIComponent(entry.tab)}` : '';
+      parts.push(`@${encodeURIComponent(pageToken(entry.pageId))}${tab}${body ? `~${encodeURIComponent(body)}` : ''}`);
+      return;
+    }
+    if (entry.kind === 'table' || entry.kind === 'breakdown') {
+      /* A breakdown carries no tab — it has none — and is otherwise the same
+         segment as a table query, because it is the same language. Which kind
+         it comes back as is decided by `isBreakdown` in `fromHash`. */
+      const tab = entry.kind === 'table' && entry.tab && entry.tab !== 'rows' ? `!${entry.tab}` : '';
+      parts.push(encodeQuery(entry.query) + tab);
+    } else {
+      /* A row is `~` plus its key. Single-column keys — nearly all of them —
+         are just the value, so the common case stays readable; composite keys
+         name their columns because position alone would not survive a schema
+         change.
+
+         The table is named whenever it differs from the entry before, which
+         is exactly what following a foreign key from one row to another does.
+         Without it `work_order/~8/~636` claims 636 is a work_order when it is
+         a customer, and the link restores the wrong row — or no row. */
+      const body = keyBody(entry.key);
+      const previous = stack[index - 1];
+      const prefix = previous && previous.table === entry.table ? '' : `${entry.table}:`;
+      /* And which related table is open, if one is — the record view's rail
+         is a tablist, and "look at its notes" is as worth linking to on a
+         record as it is on a page. `!` is escaped inside the key for the
+         same reason the query encoder escapes it: it is an unreserved
+         character that `encodeURIComponent` leaves alone, so a value
+         containing one would otherwise write a second separator. */
+      const tab = entry.tab ? `!${encodeURIComponent(entry.tab)}` : '';
+      parts.push(`~${encodeQuery(prefix + body)}${tab}`);
+    }
+  });
+  return `/${parts.join('/')}`;
+}
+
+/**
+ * The connection a hash names, without parsing the rest of it.
+ *
+ * Needed because parsing the trail requires the *right* schema: a link into
+ * another database mentions tables the current one has never heard of, so
+ * every row segment fails to resolve and is dropped. The connection has to be
+ * switched before the rest can be read.
+ */
+/**
+ * Take the leading `/` off a link — or the leading `#/` off one written
+ * before these were paths.
+ *
+ * Both spellings are read for as long as it costs one regex to do so. A link
+ * is the thing people paste into a ticket and come back to a year later, and
+ * the day the old ones stop resolving should not be the day this changed.
+ */
+function stripPrefix(link) {
+  return String(link ?? '').replace(/^#/, '').replace(/^\//, '');
+}
+
+export function connectionFromHash(hash) {
+  const raw = stripPrefix(hash);
+  if (!raw) return null;
+  const first = raw.split('/').filter(Boolean)[0];
+  return first ? decodeURIComponent(first) : null;
+}
+
+/**
+ * Parse a hash into a stack. Returns null when there is nothing to restore.
+ *
+ * Rows need the table they belong to, which is the entry before them — so a
+ * row segment that opens the trail is dropped rather than guessed at.
+ */
+export function fromHash(hash, findTableById, options = {}) {
+  /* Read off `options` rather than destructured with a default in the
+     signature: `check-client-imports` cannot see a parameter list once a
+     default inside it has parentheses of its own, and reads every name in it
+     as undefined. The tool is right that this file must import nothing, so it
+     is the signature that gives way. */
+  const isBreakdown = options.isBreakdown ?? (() => false);
+  const raw = stripPrefix(hash);
+  if (!raw) return null;
+  const segments = raw.split('/').filter(Boolean);
+  if (!segments.length) return null;
+
+  const connection = decodeURIComponent(segments[0]);
+  const stack = [];
+
+  for (const segment of segments.slice(1)) {
+    if (segment.startsWith('@')) {
+      /* A page, and its root if the link has one. The base table is not in
+         the link: a page names it, and putting it in the URL as well would be
+         a second copy to disagree with the config file the day someone
+         re-points a page at another table. It is filled in when the page
+         loads. */
+      const [head, keyPart] = segment.slice(1).split('~');
+      /* Page first, then the tab: split on the first `!`, which a page token
+         cannot contain and a tab name is encoded past. */
+      const bang = head.indexOf('!');
+      const pageId = decodeURIComponent(bang === -1 ? head : head.slice(0, bang));
+      const tab = bang === -1 ? undefined : decodeURIComponent(head.slice(bang + 1)) || undefined;
+      if (!pageId) continue;
+      const body = keyPart === undefined ? undefined : decodeURIComponent(keyPart);
+      /* Carried as text, not resolved here. A single-column key is written as
+         a bare value, and turning `1181` back into `{ id: 1181 }` needs the
+         page's base table — which the link deliberately does not name, since
+         the page already does and two copies would disagree the day someone
+         re-points it. The page resolves it when it knows its own base. */
+      stack.push({ kind: 'page', pageId, table: undefined, rootBody: body, label: body, tab });
+      continue;
+    }
+    if (segment.startsWith('~')) {
+      const rest = segment.slice(1);
+      const bang = rest.indexOf('!');
+      const tab = bang === -1 ? undefined : decodeURIComponent(rest.slice(bang + 1)) || undefined;
+      let body = decodeURIComponent(bang === -1 ? rest : rest.slice(0, bang));
+      /* An explicit `table:` prefix wins. It is only written when the table
+         changed, so its absence means "same as the entry before". The colon
+         is found from the left and only counts before any `=`, so a composite
+         key like `a=1,b=2` is never mistaken for a table prefix. */
+      let tableId = null;
+      const colon = body.indexOf(':');
+      if (colon > 0 && (body.indexOf('=') === -1 || colon < body.indexOf('='))) {
+        /* Only if it actually names a table. A key value can contain a colon
+           — a time like `12:30`, a URN, a namespaced id — and treating that
+           as a table prefix would drop the row entirely. Checking against the
+           schema makes the ambiguity decidable instead of guessed. */
+        const candidate = body.slice(0, colon);
+        if (findTableById(candidate)) {
+          tableId = candidate;
+          body = body.slice(colon + 1);
+        }
+      }
+      const previous = stack[stack.length - 1];
+      if (!tableId && !previous) continue; // a row with no table means nothing
+      const resolvedId = tableId ?? previous.table;
+      const table = findTableById(resolvedId);
+      if (!table) continue;
+      const key = {};
+      if (body.includes('=')) {
+        for (const pair of body.split(',')) {
+          const [column, ...rest] = pair.split('=');
+          key[column] = rest.join('=');
+        }
+      } else {
+        const pk = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+        if (!pk.length) continue;
+        key[pk[0]] = body;
+      }
+      stack.push({ kind: 'row', table: table.id, key, label: labelFor(body), tab });
+      continue;
+    }
+    /* Only a real tab name ends a segment.
+    
+       `lastIndexOf('!')` alone read the `!` of `!=` as the separator, so
+       `invoice total != 0` came back as `invoice total ` with a tab of
+       `%3D 0` — the condition silently gone, and a shared "unpaid invoices"
+       link showing every invoice. Encoding fixes it going forward; checking
+       the suffix against the tabs that exist also rescues every link already
+       written and every one this app did not write. */
+    const bang = segment.lastIndexOf('!');
+    const suffix = bang > 0 ? segment.slice(bang + 1) : '';
+    const hasTab = TABS.has(suffix);
+    const tab = hasTab ? suffix : 'rows';
+    const query = decodeURIComponent(hasTab ? segment.slice(0, bang) : segment);
+    const name = query.trim().split(/\s+/)[0];
+    const table = findTableById(name);
+    /* A breakdown is written into the link exactly as a table query is — it is
+       the same language and the same text — so which kind it is on the way back
+       is read off the text itself. The rule is supplied rather than imported:
+       this module deliberately depends on nothing, which is what lets the link
+       format be tested without a browser, and it is the same arrangement
+       `pageToken` uses on the way out. */
+    stack.push(isBreakdown(query)
+      ? { kind: 'breakdown', table: table ? table.id : name, query }
+      : tableView(table ? table.id : name, query, tab));
+  }
+
+  return { connection, stack };
+}
+
+function labelFor(body) {
+  // The real label needs the row, which has not been fetched yet. The key is
+  // a truthful placeholder and gets replaced by resolveLabels below.
+  return body.length > 24 ? `${body.slice(0, 23)}…` : body;
+}
+

package/dist/client/delete.js

@@ -0,0 +1,144 @@
+/**
+ * Deleting a row, having first said what that would do.
+ *
+ * This is the one destructive action in tablewalk, and it is also the one place
+ * the tool has a genuine advantage over every other database client — not
+ * through cleverness, but because of what it already knows. It counts what
+ * points at a row in order to draw the Related panel; the same counts answer
+ * "what breaks if this goes" *before* the delete rather than as a constraint
+ * violation afterwards.
+ *
+ * The count alone is not the answer, which is the part most tools would get
+ * wrong if they tried. Three rows pointing at this one means three rows
+ * deleted under `cascade`, three rows left holding a null under `set null`, and
+ * a delete that simply fails under `restrict`. Three outcomes behind one
+ * number. So the dialog leads with the *rule*, and a rule the adapter could not
+ * determine says so rather than being quietly rendered as harmless.
+ */
+import { api, el, go, state, toast } from './core.js';
+
+/** How a rule reads to someone deciding whether to press the button. */
+const CONSEQUENCE = {
+  cascade: { tone: 'bad', says: (n, t) => `${n} in ${t} will be deleted too` },
+  'set null': { tone: 'warn', says: (n, t) => `${n} in ${t} will be kept, with the reference emptied` },
+  'set default': { tone: 'warn', says: (n, t) => `${n} in ${t} will be kept, with the reference reset` },
+  restrict: { tone: 'stop', says: (n, t) => `${n} in ${t} will block this — the database will refuse it` },
+  'no action': { tone: 'stop', says: (n, t) => `${n} in ${t} will block this — the database will refuse it` },
+};
+
+const rows = (n) => `${n.toLocaleString()} row${n === 1 ? '' : 's'}`;
+
+/**
+ * Whether this connection will accept a delete at all.
+ *
+ * Asked of the server's own answer rather than inferred: `writable` is on the
+ * connection list precisely so the interface does not offer a button the server
+ * would refuse.
+ */
+export function canDelete(table) {
+  if (!state.canWrite || !table || table.isView) return false;
+  return Boolean(state.connections?.find((c) => c.id === state.activeConnection)?.writable);
+}
+
+export function deleteButton(table, key, label) {
+  if (!canDelete(table)) return null;
+  return el('button', {
+    type: 'button',
+    class: 'ghost record-delete',
+    title: `Delete this ${table.name} row`,
+    text: 'Delete…',
+    onclick: () => void confirmDelete(table, key, label),
+  });
+}
+
+async function confirmDelete(table, key, label) {
+  let report;
+  try {
+    report = await api('/api/delete', { table: table.id, key });
+  } catch (err) {
+    toast(err.message, 'error');
+    return;
+  }
+
+  const impact = report.impact ?? [];
+  const blocked = impact.some((i) => i.onDelete === 'restrict' || i.onDelete === 'no action');
+
+  const dialog = el('dialog', { class: 'confirm delete-confirm' }, [
+    el('h2', { text: `Delete ${table.name} ${label}?` }),
+    impact.length
+      ? el('div', {}, [
+          el('p', { text: 'This row is referenced. Here is what the database will do:' }),
+          el('ul', { class: 'delete-impact' }, impact.map((i) => {
+            const rule = CONSEQUENCE[i.onDelete];
+            return el('li', { class: `impact-${rule?.tone ?? 'unknown'}` }, [
+              el('span', { class: 'impact-what' }, [
+                document.createTextNode(
+                  i.count < 0
+                    ? `${i.table} could not be counted`
+                    : rule
+                      ? rule.says(rows(i.count), i.table)
+                      : `${rows(i.count)} in ${i.table} — this constraint's rule is unknown`,
+                ),
+              ]),
+              el('span', { class: 'impact-rule', text: i.onDelete ? `on delete ${i.onDelete}` : 'rule unknown' }),
+            ]);
+          })),
+          /* Said plainly rather than left to be inferred from the list. A
+             cascade that itself cascades is not counted here, and implying a
+             total that stopped one level down would be worse than saying so. */
+          impact.some((i) => i.onDelete === 'cascade')
+            ? el('p', {
+                class: 'delete-note',
+                text: 'Cascades are counted one level deep. Rows deleted by a cascade may take their own children with them.',
+              })
+            : null,
+        ].filter(Boolean))
+      : el('p', { text: 'Nothing points at this row, so nothing else is affected.' }),
+
+    blocked
+      ? el('p', {
+          class: 'delete-blocked',
+          text: 'The database will refuse this while those references exist. You can try anyway — its answer is the authority, not ours.',
+        })
+      : null,
+
+    el('div', { class: 'confirm-actions' }, [
+      el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => dialog.close() }),
+      el('button', {
+        type: 'button',
+        class: 'danger',
+        text: blocked ? 'Try anyway' : 'Delete',
+        onclick: () => { dialog.close(); void doDelete(table, key, label); },
+      }),
+    ]),
+  ].filter(Boolean));
+
+  document.body.append(dialog);
+  dialog.addEventListener('close', () => dialog.remove());
+  dialog.showModal();
+}
+
+async function doDelete(table, key, label) {
+  let result;
+  try {
+    result = await api('/api/delete', { table: table.id, key, confirm: true });
+  } catch (err) {
+    toast(err.message, 'error');
+    return;
+  }
+
+  if (!result.deleted) {
+    /* The database's own words. A constraint violation names the constraint,
+       which is more use than any paraphrase — and re-deriving the judgement
+       here would be a second implementation of a rule the database already
+       enforces. */
+    toast(result.errors?.[0]?.message ?? 'The row was not deleted.', 'error');
+    return;
+  }
+
+  toast(`Deleted ${table.name} ${label}.`, 'ok');
+  /* Back to the table, not to the record that no longer exists. Staying would
+     re-fetch a row that is gone and report it as missing, which reads as a
+     failure rather than as the thing that was just asked for. */
+  go({ kind: 'table', table: table.id, query: table.id, tab: 'rows' }, 'reset');
+}