tablewalk 0.0.1

package/dist/client/clauses.js

@@ -0,0 +1,390 @@
+/**
+ * The parts of a query, as things you can take off.
+ *
+ * The query bar is the source of truth, which is a good design and leaves one
+ * gap: undoing part of what you built means editing the text by hand. Having
+ * clicked a column header to sort and a filter menu to narrow, going back to
+ * "the same thing but unsorted" meant finding `sort contract_id` in a line of
+ * text and deleting exactly it — the interface could write the language but
+ * not un-write it.
+ *
+ * So the clauses are shown as chips and removing one rewrites the text. The
+ * text stays authoritative; this is a second way to edit it, not a second
+ * place to keep it.
+ *
+ * The split is by keyword, which the grammar makes safe: a query is a table,
+ * then conditions, then any of `show`, `sort`/`order by` and `limit` in that
+ * order. Only the trailing keywords are looked for, so a *value* containing
+ * the word "limit" cannot be mistaken for the clause — the boundary is found
+ * from the right, and only outside quotes.
+ */
+
+/** Trailing clause keywords, longest first so `order by` wins over `order`. */
+const TAIL = [
+  { key: 'limit', pattern: /\blimit\b/i },
+  { key: 'sort', pattern: /\b(?:sort|order\s+by)\b/i },
+  { key: 'show', pattern: /\bshow\b/i },
+];
+
+/**
+ * Positions of characters that are inside a quoted value.
+ *
+ * `status = "sort code"` contains the word `sort` and does not contain a sort
+ * clause. Scanning for quotes first is what keeps the two apart.
+ */
+function quotedSpans(text) {
+  const spans = [];
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\') { i += 1; continue; }
+      if (c === quote) { spans.push([start, i]); quote = null; }
+    } else if (c === '"' || c === "'") {
+      quote = c;
+      start = i;
+    }
+  }
+  if (quote) spans.push([start, text.length]);
+  return spans;
+}
+
+const inside = (spans, at) => spans.some(([a, b]) => at > a && at < b);
+
+/**
+ * A copy of the query with the contents of quoted values replaced by spaces.
+ *
+ * Mirrors `maskQuotedValues` in src/shared/query.ts — same trick, same reason.
+ * Same length as the input and the quote characters left in place, so an index
+ * into this string is an index into the original.
+ *
+ * Anything that scans a query for keywords needs this. Scanning raw text turns
+ * a value into syntax: `name contains "show me"` was cut at the value's own
+ * word and the filter came back holding `"sort name show id, name` — a string
+ * assembled out of the query's own punctuation.
+ */
+export function maskQuoted(text) {
+  let out = '';
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === '\\' && i + 1 < text.length) {
+        out += '  ';
+        i += 1;
+        continue;
+      }
+      out += ch === quote ? ((quote = null), ch) : ' ';
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      out += ch;
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/**
+ * Break a query into its table, filter and trailing clauses.
+ *
+ * @returns {{table: string, filter: string, show?: string, sort?: string, limit?: string}}
+ */
+export function splitQuery(text) {
+  const query = String(text ?? '').trim();
+  const spans = quotedSpans(query);
+
+  const firstSpace = query.search(/\s/);
+  const table = firstSpace < 0 ? query : query.slice(0, firstSpace);
+  let rest = firstSpace < 0 ? '' : query.slice(firstSpace + 1);
+  let offset = firstSpace + 1;
+
+  const parts = { table, filter: '' };
+
+  /* Boundaries are found first, then sorted by *position* — not peeled off in
+     grammar order.
+
+     Peeling assumed the clauses arrive in the order the grammar lists them. The
+     parser does not require that, and `customer limit 5 sort name` is a query
+     someone will type. Peeling `limit` first took everything from `limit` to
+     the end, so the sort clause was swallowed into it: the chip read "5 sort
+     name" and removing the limit removed the sort with it.
+
+     The last occurrence of each keyword wins, because a clause word can appear
+     earlier as an unquoted value; quoted ones are excluded outright. */
+  const marks = [];
+  for (const { key, pattern } of TAIL) {
+    let at = -1;
+    let from = 0;
+    for (;;) {
+      const found = rest.slice(from).search(pattern);
+      if (found < 0) break;
+      const absolute = from + found;
+      if (!inside(spans, offset + absolute)) at = absolute;
+      from = absolute + 1;
+    }
+    if (at >= 0) marks.push({ key, at });
+  }
+  marks.sort((a, b) => a.at - b.at);
+
+  marks.forEach(({ key, at }, i) => {
+    const until = marks[i + 1]?.at ?? rest.length;
+    parts[key] = rest.slice(at, until).trim();
+  });
+  if (marks.length) rest = rest.slice(0, marks[0].at);
+
+  parts.filter = rest.trim();
+  return parts;
+}
+
+/**
+ * The row count the query itself asks for, if any. A number, or null.
+ *
+ * Read rather than parsed properly, because the client has no parser — the
+ * language lives on the server. Reading it *here*, off the same split as the
+ * chips, is what makes it right for a limit that is not the last thing typed:
+ * the table view matched `limit N` anchored at the end of the string, which
+ * found nothing at all in `customer limit 40000 sort name`, so the page size
+ * went out instead and forty thousand rows came back as twenty — the same lie
+ * that anchoring was supposed to have fixed, in the clause order nobody tried.
+ * It lived beside its caller in the browser, where nothing could test it.
+ *
+ * The split also settles what a *value* containing the word means, which no
+ * regex here could: `name = "limit 5"` is a name.
+ *
+ * `limit = 5`, on a table with a column called `limit`, is a filter — no
+ * number follows the keyword, so this hands back nothing and the caller falls
+ * back to the page size, which is what being wrong has always cost.
+ */
+export function explicitLimit(query) {
+  const match = splitQuery(query).limit?.match(/^limit\s+(\d+)\b/i);
+  if (!match) return null;
+  const n = Number(match[1]);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/** Rebuild a query from its parts, dropping the empty ones. */
+export function joinQuery(parts) {
+  return [parts.table, parts.filter, parts.show, parts.sort, parts.limit]
+    .filter((p) => p && String(p).trim())
+    .join(' ')
+    .trim();
+}
+
+/**
+ * The query with one clause removed.
+ *
+ * @param {string} text
+ * @param {'filter'|'show'|'sort'|'limit'} clause
+ */
+export function withoutClause(text, clause) {
+  const parts = splitQuery(text);
+  delete parts[clause];
+  if (clause === 'filter') parts.filter = '';
+  return joinQuery(parts);
+}
+
+/** Clauses present in a query, as {key, label, text} — for rendering chips. */
+export function activeClauses(text) {
+  const parts = splitQuery(text);
+  const out = [];
+  /* One chip per condition rather than one for the whole filter. A query built
+     from three narrowings should be undoable one narrowing at a time — the
+     interface wrote them separately, so it should be able to take them off
+     separately. */
+  splitConditions(parts.filter).forEach((condition, i) => {
+    out.push({ key: 'filter', index: i, label: i === 0 ? 'where' : 'and', text: condition });
+  });
+  if (parts.show) out.push({ key: 'show', label: 'showing', text: parts.show.replace(/^show\s+/i, '') });
+  if (parts.sort) out.push({ key: 'sort', label: 'sorted by', text: parts.sort.replace(/^(?:sort|order\s+by)\s+/i, '') });
+  if (parts.limit) out.push({ key: 'limit', label: 'limit', text: parts.limit.replace(/^limit\s+/i, '') });
+  return out;
+}
+
+/**
+ * Split a filter into the conditions joined by top-level `and`.
+ *
+ * Top-level is the important word. `active = true and (priority = 1 or
+ * priority = 2)` is two conditions, not three: the bracketed group is one
+ * thing you either want or do not, and splitting inside it would produce
+ * chips that cannot be removed independently without changing what the query
+ * means. Depth and quoting are both tracked, so `name = "a and b"` is one
+ * condition whose value happens to contain the word.
+ *
+ * `or` is never split on. A filter that is `a or b` comes back as a single
+ * condition, which is right — removing half of an `or` is not a smaller
+ * filter, it is a different one.
+ */
+export function splitConditions(filter) {
+  const text = String(filter ?? '').trim();
+  if (!text) return [];
+
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  /* Set when a `between` is open and its `and` has not been seen yet.
+
+     `between 2026-08-17 and 2026-08-27` contains an `and` that joins a range
+     rather than two conditions. Without this the filter bar drew it as two
+     chips — `WHERE hired_on between 2026-08-17` and `AND 2026-08-27` — and
+     dismissing either produced `hired_on between 2026-08-17`, which is not a
+     condition and came back as an error. One range, cut in half by the thing
+     that was only supposed to be listing it.
+
+     `splitTopLevel` in shared/query.ts has tracked this since `between`
+     shipped. This copy did not, which is the whole hazard of a mirror: each
+     side looks right on its own. */
+  let pendingBetween = false;
+
+  const wordAt = (word, i) => new RegExp(`^${word}\\b`, 'i').test(text.slice(i))
+    && (i === 0 || /[\s)]/.test(text[i - 1]));
+
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\') { i += 1; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '(') { depth += 1; continue; }
+    if (c === ')') { depth = Math.max(0, depth - 1); continue; }
+    if (depth > 0) continue;
+
+    if ((c === 'b' || c === 'B') && wordAt('between', i)) {
+      pendingBetween = true;
+      continue;
+    }
+
+    // A word boundary on both sides, so a column called `and_then` survives.
+    if ((c === 'a' || c === 'A') && wordAt('and', i)) {
+      // The first top-level `and` after a `between` belongs to it.
+      if (pendingBetween) {
+        pendingBetween = false;
+        i += 2;
+        continue;
+      }
+      parts.push(text.slice(start, i).trim());
+      i += 3;
+      start = i;
+    }
+  }
+  parts.push(text.slice(start).trim());
+
+  /* A split that yields one piece is not a split.
+     
+     `last_name contains and` — where the value *is* the keyword — splits at
+     that `and` into `last_name contains` and nothing. Dropping the empty half
+     and keeping the first left a chip with its value chopped off, which is a
+     misdescription of the filter and a dismiss button wired to the wrong
+     text.
+
+     `splitTopLevel` in shared/query.ts survives this by accident of shape: it
+     drops empty parts, finds fewer than two left, and falls through to
+     treating the whole term as one condition — which is why the server reads
+     `LIKE '%and%'` where the browser read a truncated condition. Same rule
+     here, deliberately: if the keyword did not actually stand between two
+     conditions, it belonged to the one. */
+  const kept = parts.filter(Boolean);
+  if (kept.length > 1) return kept;
+  return text ? [text] : [];
+}
+
+/** The query with one condition of its filter removed, by index. */
+export function withoutCondition(text, index) {
+  const parts = splitQuery(text);
+  const conditions = splitConditions(parts.filter);
+  conditions.splice(index, 1);
+  parts.filter = conditions.join(' and ');
+  return joinQuery(parts);
+}
+
+/**
+ * The sort clause's fields, split on commas, keyword already removed.
+ *
+ * `sort a, b desc` is two fields, not one field called "a, b desc". Splitting
+ * here rather than at each caller is what keeps the multi-field case from
+ * being everyone's separate problem.
+ */
+function sortFields(query) {
+  const body = splitQuery(query).sort?.replace(/^(?:sort|order\s+by)\s+/i, '').trim();
+  if (!body) return [];
+  return body.split(',').map((part) => {
+    const [column, ...rest] = part.trim().split(/\s+/);
+    return { column, direction: /^desc$/i.test(rest[0] ?? '') ? 'desc' : 'asc' };
+  });
+}
+
+/**
+ * Which way a query sorts by a column, or null if it does not.
+ *
+ * Answered by splitting rather than by matching, because the caller's column
+ * name goes into the comparison and a reference hop contains characters a
+ * regex reads as instructions: `invoice_id+line_no.sku` interpolated into a
+ * pattern means "one or more `d`, then any character" — a question about a
+ * different column entirely.
+ */
+export function sortDirection(query, column) {
+  return sortFields(query).find((f) => f.column === column)?.direction ?? null;
+}
+
+/**
+ * The query you get by clicking a column header.
+ *
+ * Cycles ascending → descending → ascending on the column already sorted by,
+ * and replaces the clause otherwise. An explicit `direction` skips the cycle:
+ * it means "write down what is already happening", which is what adopting the
+ * default order does, and toggling it would flip the very thing being adopted.
+ *
+ * "Already sorted by this" means this column and nothing else. A click on one
+ * header of a multi-field sort replaces the whole clause rather than toggling
+ * one field of it — reversing one column of `sort a, b` is not something a
+ * single click can express, and guessing would be worse than starting fresh.
+ */
+/**
+ * Add a column to the sort rather than replacing it.
+ *
+ * `sort a, b desc` is expressible in the language and was reachable only by
+ * typing it: every header click replaced the whole clause, so a two-column
+ * sort could not be built by clicking. "Sort by title, then by hire date" is
+ * an ordinary thing to want of a table.
+ *
+ * A column already in the clause has its direction changed **in place** rather
+ * than being moved to the end. Sort order is precedence, and silently
+ * re-prioritising the column somebody was only reversing would change the
+ * answer in a way nothing on screen explains.
+ */
+export function addSort(query, column, direction) {
+  const parts = splitQuery(query);
+  const fields = sortFields(query);
+  const desc = direction === 'desc';
+
+  const at = fields.findIndex((f) => f.column === column);
+  if (at === -1) fields.push({ column, direction: desc ? 'desc' : 'asc' });
+  else fields[at] = { column, direction: desc ? 'desc' : 'asc' };
+
+  parts.sort = `sort ${fields.map((f) => `${f.column}${f.direction === 'desc' ? ' desc' : ''}`).join(', ')}`;
+  return joinQuery(parts);
+}
+
+/** How many columns the query sorts by — the menu asks, to word itself. */
+export function sortCount(query) {
+  return sortFields(query).length;
+}
+
+export function nextSort(query, column, direction) {
+  const parts = splitQuery(query);
+  const fields = sortFields(query);
+  const onlyThis = fields.length === 1 && fields[0].column === column;
+
+  const desc = direction
+    ? direction === 'desc'
+    : onlyThis && fields[0].direction === 'asc';
+
+  parts.sort = `sort ${column}${desc ? ' desc' : ''}`;
+  return joinQuery(parts);
+}

package/dist/client/columns.js

@@ -0,0 +1,98 @@
+/**
+ * How a column should be drawn.
+ *
+ * Decided per column, once per result set, from the declared type *and* the
+ * values actually on the page. Type alone is not enough: SQLite has no
+ * boolean, so a flag column arrives as INTEGER and would otherwise render as
+ * a column of 1s and 0s. Values alone are not enough either — a page where
+ * every quantity happens to be 0 or 1 is not a column of checkboxes.
+ *
+ * The rule throughout: formatting may never hide the stored value. Anything
+ * reformatted carries the raw value in its title, because in a database tool
+ * the difference between `5000` and `5,000` is sometimes the whole question.
+ */
+
+import { columnKind } from './core.js';
+
+/** Columns whose name says "flag" loudly enough to trust 0/1 as a boolean. */
+const FLAG_NAME = /^(is|has|can|should|was)_|_(flag|enabled|disabled)$|^(active|enabled|disabled|deleted|archived|verified|published|visible|locked|hidden|default|primary|required|readonly)$/i;
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}([ T]\d{2}:\d{2}(:\d{2})?)?/;
+
+/**
+ * Below this many rows, sorting any column is cheap enough to offer freely.
+ *
+ * `ESTIMATE_ABOVE` from adapters/adapter.ts, which is where this codebase
+ * already draws the line between "counting is free" and "counting is a scan
+ * worth avoiding". A sort is the same kind of work as a count, so it belongs
+ * on the same side of the same line rather than getting a second threshold to
+ * disagree with the first.
+ */
+export const SORT_SCAN_BELOW = 50_000;
+
+/**
+ * May the header offer to sort this column?
+ *
+ * A header click is a one-click action with no visible cost, and on an
+ * unindexed column of a large table it is a full scan and a sort of
+ * everything to show twenty rows. So the offer is made when an index leads on
+ * the column — or when the table is small enough that the scan costs nothing
+ * anybody would notice.
+ *
+ * That second clause is the whole point. The rule used to be the first alone,
+ * which is right on a table of millions and far too careful on one of a
+ * hundred and seventy: `employee.last_name` had no index, so there was no way
+ * to sort by it from the interface at all.
+ *
+ * `approxRows` unknown is not treated as small. A table nobody could count is
+ * not one to assume is cheap.
+ *
+ * Pure, and exported, so the rule can be tested directly rather than through a
+ * browser — no fixture in this repo has fifty thousand rows in it, so the
+ * large-table half is otherwise a branch nothing ever exercises.
+ */
+export function sortableFromHeader(table) {
+  if (!table) return false;
+  return table.approxRows != null && table.approxRows < SORT_SCAN_BELOW;
+}
+
+export function planColumn(meta, name, rows) {
+  const values = rows.map((r) => r[name]).filter((v) => v !== null && v !== undefined);
+  const declared = columnKind(meta?.type);
+  const plan = { align: 'left', kind: declared, mono: false };
+
+  const allNumeric = values.length > 0 && values.every((v) => typeof v === 'number');
+
+  // Boolean: declared as one, or an integer flag column whose name says so.
+  if (declared === 'boolean' || (allNumeric && FLAG_NAME.test(name) && values.every((v) => v === 0 || v === 1))) {
+    return { ...plan, kind: 'boolean', align: 'center' };
+  }
+
+  if (declared === 'number' || allNumeric) {
+    /* Keys and references are identifiers that happen to be numeric. Grouping
+       them turns invoice 1001 into "1,001", which reads as a quantity and is
+       not what the value means. */
+    const identifier = Boolean(meta?.primaryKey || meta?.references);
+    const decimals = identifier ? 0 : Math.max(0, ...values.map(countDecimals));
+    const group = !identifier && values.some((v) => Math.abs(Number(v)) >= 10000);
+    return { ...plan, kind: 'number', align: 'right', decimals, group, identifier };
+  }
+
+  if (declared === 'date' || (values.length && values.every((v) => typeof v === 'string' && ISO_DATE.test(v)))) {
+    // A column of timestamps all at midnight is a date column wearing a
+    // timestamp's clothes; showing ` 00:00:00` on every row is pure noise.
+    const anyTime = values.some((v) => /[ T]\d{2}:\d{2}/.test(String(v)) && !/[ T]00:00:00(\.0+)?$/.test(String(v)));
+    return { ...plan, kind: 'date', mono: true, showTime: anyTime };
+  }
+
+  /* Short, uniform text — codes, statuses, currencies — reads better in a
+     narrow monospace column than stretched across a wide proportional one. */
+  const longest = Math.max(0, ...values.map((v) => String(v).length));
+  return { ...plan, kind: 'text', mono: longest <= 12 && values.length > 0 };
+}
+
+export function countDecimals(value) {
+  const text = String(value);
+  const dot = text.indexOf('.');
+  return dot === -1 ? 0 : Math.min(6, text.length - dot - 1);
+}