tablewalk 0.0.1

package/dist/client/export.js

@@ -0,0 +1,456 @@
+/**
+ * Export the result you are looking at, as CSV or JSON.
+ *
+ * The serialisers at the top are pure — columns and rows in, a string out —
+ * because CSV is the part of this feature that is easy to get subtly wrong
+ * and the only way to know it is right is to test it without a browser. The
+ * DOM half below is a thin wrapper over them.
+ *
+ * The rule the format has to hold up to: a spreadsheet reading the file back
+ * must see exactly the values the grid showed, including the distinction
+ * between a null and an empty string, which every naive `join(',')` loses.
+ */
+import { api, disclosure, el, findTable, loadJson, pageSize, saveJson, state, toast } from './core.js';
+import { maskQuoted } from './clauses.js';
+import { copyPosition, positionOf } from './handoff.js';
+
+/* Mirrors MAX_LIMIT in src/adapters/adapter.ts. The server clamps to it
+   regardless, so this is only here to keep the button honest about how many
+   rows "all matching" can actually mean. */
+export const EXPORT_MAX_ROWS = 100_000;
+
+/* RFC 4180 §2.6: a field containing a comma, a quote or a line break must be
+   quoted. CR and LF are listed separately because a lone CR inside a value is
+   just as capable of splitting a record as a full CRLF. */
+const NEEDS_QUOTES = /[",\r\n]/;
+
+/* Excel, Sheets and LibreOffice all treat a cell beginning with one of these
+   as a formula to evaluate rather than text to show — so a value like
+   `=HYPERLINK(...)` or `@SUM(A1)` out of a database column becomes code the
+   moment someone opens the file. Prefixing a single quote is the standard
+   mitigation: spreadsheets show the rest as literal text.
+   Tab and CR are included because they are skipped before the parse, which
+   makes `\t=cmd` a formula too. */
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+
+/* ...but `-5` and `+1.5e3` are numbers, not formulas, and prefixing them
+   would corrupt every negative amount in the export to buy nothing. Only a
+   leading sign that is *not* part of a plain number is dangerous. */
+const PLAIN_NUMBER = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+
+const CRLF = '\r\n';
+
+/**
+ * One CSV field.
+ *
+ * null and undefined emit nothing at all, while an empty string emits `""`.
+ * That asymmetry is the whole point: `a,,b` and `a,"",b` are different
+ * documents, and collapsing them means an export cannot tell you whether a
+ * column was never set or set to blank — often the exact question the export
+ * was taken to answer.
+ */
+export function csvField(value) {
+  if (value === null || value === undefined) return '';
+  // A JSON/JSONB column arrives as a parsed object; `String(obj)` would write
+  // "[object Object]" into every row of it.
+  const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+  const safe = FORMULA_LEAD.test(text) && !PLAIN_NUMBER.test(text) ? `'${text}` : text;
+  if (safe === '' || NEEDS_QUOTES.test(safe)) return `"${safe.replace(/"/g, '""')}"`;
+  return safe;
+}
+
+/** A CSV document: a header row of column names, then one row per record. */
+export function toCsv(columns, rows) {
+  const lines = [columns.map(csvField).join(',')];
+  for (const row of rows ?? []) lines.push(columns.map((name) => csvField(row?.[name])).join(','));
+  // CRLF, per RFC 4180, and a trailing one so the file ends on a record
+  // boundary rather than mid-line.
+  return lines.join(CRLF) + CRLF;
+}
+
+/**
+ * A JSON document: an array of objects, in the column order on screen.
+ *
+ * Rebuilt from `columns` rather than emitted as-is so the shape matches the
+ * CSV exactly — including a key whose value is missing, which `JSON.stringify`
+ * would silently drop and leave the two formats disagreeing about the row.
+ */
+export function toJson(columns, rows) {
+  const shaped = (rows ?? []).map((row) => {
+    const out = {};
+    for (const name of columns) out[name] = row?.[name] ?? null;
+    return out;
+  });
+  return `${JSON.stringify(shaped, null, 2)}\n`;
+}
+
+/**
+ * Put the selected columns into a query, replacing any `show` clause it has.
+ *
+ * The language is parsed on the server and nowhere else, so the only way for
+ * the client to ask for different columns is to edit the text — the same
+ * trick the sortable headers use. Replacing rather than appending is the part
+ * that matters: the parser concatenates repeated clauses with `and`, so a
+ * second `show` would arrive as one column named "b and c" and the export
+ * would fail with a column error instead of exporting anything.
+ *
+ * An empty list means "every column", which is what no `show` clause means.
+ */
+export function withColumns(query, names) {
+  const marks = clauseMarks(query);
+  let out = '';
+  let cut = 0;
+  marks.forEach((mark, i) => {
+    if (mark.word !== 'show' && mark.word !== 'select') return;
+    out += query.slice(cut, mark.start);
+    cut = i + 1 < marks.length ? marks[i + 1].start : query.length;
+  });
+  const base = `${out}${query.slice(cut)}`.trim();
+  return names.length ? `${base} show ${names.join(', ')}` : base;
+}
+
+/* Mirrors CLAUSE_RE in src/shared/query.ts. Two copies of a rule is a cost,
+   but the alternative is a build step to share one — and the client is a
+   static file on purpose. */
+const CLAUSE_RE = /\b(filter|where|show|select|sort|order\s+by|limit)\b/gi;
+
+/* ...including the rule that makes a clause word a column name instead. A
+   table with a column called `show` is unusual but `show = 3` is a filter,
+   and cutting from there would silently drop the rest of the query. */
+const FOLLOWED_BY_OPERATOR =
+  /^\s*(?:=|!=|>=|<=|>|<|\bis\b|\bcontains\b|\bstartswith\b|\bendswith\b|\bin\b|\bnot\s+in\b)/i;
+
+function clauseMarks(text) {
+  /* Scanned with quoted values blanked out, and the offsets used against the
+     real text — the same masking the parser does, for the same reason. Without
+     it `name contains "show me"` was cut at the value's own word, and the
+     rewritten query came back with a filter holding `"sort name show id, name`:
+     a string assembled out of the query's punctuation, exported as though it
+     were what the user asked for. */
+  const scannable = maskQuoted(text);
+  const marks = [];
+  CLAUSE_RE.lastIndex = 0;
+  let m;
+  while ((m = CLAUSE_RE.exec(scannable))) {
+    if (FOLLOWED_BY_OPERATOR.test(scannable.slice(CLAUSE_RE.lastIndex))) continue;
+    marks.push({ word: m[1].toLowerCase().replace(/\s+/g, ' '), start: m.index });
+  }
+  return marks;
+}
+
+/**
+ * The chosen columns, in the order the table declares them.
+ *
+ * Not the order they were ticked in: two exports of the same table a week
+ * apart should differ only where the data differs, and a column list that
+ * depends on which checkbox someone clicked first makes every diff noise.
+ * A name the table does not declare keeps its relative position at the end,
+ * which is where a computed column from a view lands.
+ */
+export function orderColumns(selected, declared) {
+  const rank = new Map(declared.map((name, i) => [name, i]));
+  return [...new Set(selected)].sort(
+    (a, b) => (rank.get(a) ?? Number.MAX_SAFE_INTEGER) - (rank.get(b) ?? Number.MAX_SAFE_INTEGER),
+  );
+}
+
+const sameList = (a, b) => a.length === b.length && a.every((name, i) => name === b[i]);
+
+/* ---------- which columns ---------- */
+
+const COLUMN_KEY = 'tablewalk.export-columns.v1';
+
+/* Per connection as well as per table: `orders` on staging and `orders` on
+   production are not the same table, and neither are their useful columns. */
+const scope = () => state.activeConnection ?? 'default';
+
+/* Survives a re-render within the session even when nothing can be persisted,
+   which is the case in private mode and with site data blocked. */
+const chosen = new Map();
+
+function rememberColumns(tableId, names) {
+  chosen.set(`${scope()}::${tableId}`, names);
+  // loadJson/saveJson swallow a throwing or full localStorage: a column
+  // preference that cannot be saved is not a reason to fail the export.
+  const all = loadJson(COLUMN_KEY, {}) ?? {};
+  all[scope()] = { ...(all[scope()] ?? {}), [tableId]: names };
+  saveJson(COLUMN_KEY, all);
+}
+
+/** Column names of the table as the catalog declares them, or [] if unknown. */
+function declaredColumns(tableId) {
+  if (!state.schema) return [];
+  return (findTable(tableId)?.columns ?? []).map((c) => c.name);
+}
+
+/**
+ * What to export, before anyone opens the chooser: last time's selection if
+ * there is one, otherwise exactly what is on screen — which already respects
+ * a `show` clause in the query.
+ */
+function selectionFor(tableId, displayed, declared) {
+  const key = `${scope()}::${tableId}`;
+  const remembered = chosen.get(key) ?? loadJson(COLUMN_KEY, {})?.[scope()]?.[tableId];
+  const known = new Set([...declared, ...displayed]);
+  // A remembered column that no longer exists is dropped rather than sent:
+  // the query would fail on it, and the export would fail with it.
+  const valid = Array.isArray(remembered) ? remembered.filter((n) => known.has(n)) : [];
+  return orderColumns(valid.length ? valid : displayed, declared);
+}
+
+/** `customer-2026-08-22.csv` — the table and the day, which is what you look for later. */
+export function exportFilename(table, extension, now = new Date()) {
+  const stem = String(table ?? 'export').replace(/[^\w.-]+/g, '_');
+  return `${stem}-${now.toISOString().slice(0, 10)}.${extension}`;
+}
+
+export function download(filename, text, mime) {
+  /* A UTF-8 CSV with no BOM opens in Excel as the local codepage, which turns
+     every accented name into mojibake. The BOM is the one thing that makes it
+     read the file as UTF-8, and other tools skip it. */
+  const body = mime === 'text/csv' ? `\ufeff${text}` : text;
+  const url = URL.createObjectURL(new Blob([body], { type: `${mime};charset=utf-8` }));
+  const link = el('a', { href: url, download: filename });
+  document.body.append(link);
+  link.click();
+  link.remove();
+  /* Revoked, or the blob is held for the life of the page — but not until the
+     next tick: revoking in the same task can cancel the download that click
+     just started. */
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+function save(kind, table, columns, rows) {
+  if (kind === 'csv') download(exportFilename(table, 'csv'), toCsv(columns, rows), 'text/csv');
+  else download(exportFilename(table, 'json'), toJson(columns, rows), 'application/json');
+  toast(`Exported ${rows.length.toLocaleString()} row${rows.length === 1 ? '' : 's'}.`);
+}
+
+/**
+ * The Export control for the result header.
+ *
+ * Both scopes are offered with their row count spelled out, because the
+ * default page is 20 rows and a file called `invoice-2026-08-22.csv` gives no
+ * hint that the other 49,980 rows were left behind. Whoever opens it a week
+ * later cannot tell either.
+ */
+export function exportControl(entry, data) {
+  const displayed = data.columns ?? [];
+  const declared = declaredColumns(data.table);
+  const pageRows = data.rows ?? [];
+  const total = data.total ?? pageRows.length;
+  const capped = Math.min(total, EXPORT_MAX_ROWS);
+  let selected = selectionFor(data.table, displayed, declared);
+
+  const menu = el('div', { class: 'export-menu' });
+  const wrap = disclosure(el('details', { class: 'export' }, [
+    el('summary', { class: 'export-summary', title: 'Download this result' }, 'Export'),
+    menu,
+  ]));
+
+  const start = (button, kind, all) =>
+    void deliver(button, wrap, kind, all, entry, data, selected, declared, capped);
+
+  function fill() {
+    const pageLabel = `this page (${pageRows.length.toLocaleString()} row${pageRows.length === 1 ? '' : 's'})`;
+    const allLabel = `all matching rows (${capped.toLocaleString()})`;
+    menu.replaceChildren();
+
+    menu.append(el('div', { class: 'export-group' }, el('button', {
+      type: 'button',
+      class: 'export-item export-columns-item',
+      onclick: () => chooseColumns(data.table, displayed, declared, selected, (picked) => {
+        selected = picked;
+        rememberColumns(data.table, picked);
+        fill();
+      }),
+    }, [
+      el('span', { text: 'Choose columns…' }),
+      el('span', {
+        class: 'export-count',
+        text: declared.length ? `${selected.length} of ${declared.length}` : `${selected.length}`,
+      }),
+    ])));
+
+    for (const [kind, name] of [['csv', 'CSV'], ['json', 'JSON']]) {
+      menu.append(el('div', { class: 'export-group' }, [
+        el('span', { class: 'export-kind', text: name }),
+        el('button', {
+          type: 'button',
+          class: 'export-item',
+          text: pageLabel,
+          onclick: (e) => start(e.currentTarget, kind, false),
+        }),
+        // Only worth offering when it would actually differ from the page.
+        total > pageRows.length
+          ? el('button', {
+              type: 'button',
+              class: 'export-item',
+              text: allLabel,
+              onclick: (e) => start(e.currentTarget, kind, true),
+            })
+          : null,
+      ]));
+    }
+
+    /* Not a file, but the same question: take this away with you. An agent
+       is the other place a result goes. */
+    menu.append(el('div', { class: 'export-group' }, [
+      el('span', { class: 'export-kind', text: 'Agent' }),
+      el('button', {
+        type: 'button',
+        class: 'export-item',
+        text: 'Copy this position',
+        title: 'The query, the shape and how to run it over MCP — not the rows',
+        onclick: () => {
+          wrap.open = false;
+          void copyPosition(
+            positionOf(state, entry, { columns: displayed, shown: pageRows.length, total }),
+            toast,
+          );
+        },
+      }),
+    ]));
+
+    if (total > EXPORT_MAX_ROWS) {
+      menu.append(el('p', {
+        class: 'export-note',
+        text: `Capped at ${EXPORT_MAX_ROWS.toLocaleString()} rows — the same ceiling every read in this tool has. Narrow the query to export the rest.`,
+      }));
+    }
+  }
+
+  fill();
+  return wrap;
+}
+
+/**
+ * Fetch if the file would differ from what is on screen, then write it.
+ *
+ * The re-fetch is the whole reason the chooser is safe to offer. Picking
+ * columns out of the rows already in hand would quietly export blanks for any
+ * column the query never selected — and "all matching rows" would export the
+ * columns that happened to be on screen, which is the failure this feature
+ * would otherwise introduce.
+ */
+async function deliver(button, wrap, kind, all, entry, data, selected, declared, capped) {
+  const onScreen = sameList(selected, data.columns ?? []);
+  let rows = data.rows ?? [];
+
+  if (all || !onScreen) {
+    const label = button.textContent;
+    button.disabled = true;
+    button.textContent = 'Fetching…';
+    try {
+      /* "All" is one bounded re-run rather than pages stitched together:
+         pages walked separately can duplicate or skip rows across the seam if
+         anything writes to the table in between. A full selection asks with
+         no `show` clause at all, which is the same query the grid ran. */
+      const q = withColumns(entry.query, sameList(selected, declared) ? [] : selected);
+      const fresh = await api('/api/run', {
+        q,
+        limit: all ? capped : pageSize(),
+        offset: all ? 0 : state.page * pageSize(),
+      });
+      if (!fresh.columns) {
+        throw new Error(fresh.errors?.[0]?.message ?? 'That query no longer returns rows.');
+      }
+      rows = fresh.rows ?? [];
+    } catch (err) {
+      toast(err.message, 'error');
+      return;
+    } finally {
+      button.disabled = false;
+      button.textContent = label;
+    }
+  }
+
+  wrap.open = false;
+  // `selected` rather than what came back, so the file follows the declared
+  // order whatever order the database returned.
+  save(kind, data.table, selected, rows);
+}
+
+/**
+ * The column chooser.
+ *
+ * A checklist rather than a multi-select: every column is visible at once
+ * with its type and its keys, which is the information the choice actually
+ * turns on — a `sys_id`-shaped key column and a display name are told apart
+ * by their type far more often than by their name.
+ */
+function chooseColumns(tableId, displayed, declared, selected, onDone) {
+  const table = state.schema ? findTable(tableId) : null;
+  // A view whose columns the catalog does not carry still has the ones on
+  // screen, so the chooser degrades to those rather than opening empty.
+  const columns = table?.columns?.length
+    ? table.columns
+    : declared.concat(displayed.filter((n) => !declared.includes(n))).map((name) => ({ name }));
+  const ticked = new Set(selected);
+
+  const count = el('span', { class: 'col-count' });
+  const list = el('div', { class: 'col-list' });
+  const boxes = new Map();
+
+  const refresh = () => {
+    const ticks = [...boxes.values()].filter((box) => box.checked).length;
+    count.textContent = `${ticks} of ${columns.length} selected`;
+  };
+
+  for (const column of columns) {
+    const box = el('input', { type: 'checkbox', checked: ticked.has(column.name), onchange: refresh });
+    boxes.set(column.name, box);
+    list.append(el('label', { class: 'col-row' }, [
+      box,
+      el('span', { class: 'col-name', text: column.name }),
+      // The same markers the result grid puts on its headers, so the two
+      // read as one vocabulary rather than two.
+      column.primaryKey ? el('span', { class: 'pk', text: ' key' }) : null,
+      column.references ? el('span', { class: 'fk', text: ' →' }) : null,
+      el('span', { class: 'col-type', text: column.type ?? '' }),
+      displayed.includes(column.name) ? null : el('span', { class: 'col-extra', text: 'not shown' }),
+    ]));
+  }
+  refresh();
+
+  const setAll = (names) => {
+    for (const [name, box] of boxes) box.checked = names.includes(name);
+    refresh();
+  };
+
+  const dialog = el('dialog', { class: 'confirm cols' }, [
+    el('h2', { text: 'Columns to export' }),
+    el('p', {
+      text: 'Ticked columns are written in the order the table declares them. Choosing a column that is not on screen re-runs the query to fetch it.',
+    }),
+    el('div', { class: 'col-actions' }, [
+      el('button', { type: 'button', class: 'ghost', text: 'All', onclick: () => setAll(columns.map((c) => c.name)) }),
+      el('button', { type: 'button', class: 'ghost', text: 'None', onclick: () => setAll([]) }),
+      el('button', { type: 'button', class: 'ghost', text: 'As displayed', onclick: () => setAll(displayed) }),
+      count,
+    ]),
+    list,
+    el('p', { class: 'confirm-params', text: 'Remembered for this table on this connection.' }),
+    el('div', { class: 'confirm-actions' }, [
+      el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => dialog.close() }),
+      el('button', {
+        type: 'button',
+        text: 'Use these columns',
+        onclick: () => {
+          const picked = [...boxes].filter(([, box]) => box.checked).map(([name]) => name);
+          // A file of nothing but row separators is not an export. Refusing
+          // here is kinder than writing it and letting them find out.
+          if (!picked.length) {
+            toast('Pick at least one column to export.', 'error');
+            return;
+          }
+          dialog.close();
+          onDone(orderColumns(picked, declared));
+        },
+      }),
+    ]),
+  ]);
+  dialog.addEventListener('close', () => dialog.remove());
+  document.body.append(dialog);
+  dialog.showModal();
+}