tablewalk 0.0.1

package/dist/shared/viewtext.js

@@ -0,0 +1,273 @@
+/**
+ * A view, written down.
+ *
+ * The composer builds views by clicking, and a view built by clicking is UI
+ * state: it can be saved and loaded, and that is all. Everything else in
+ * tablewalk holds that the *query text* is the single source of truth — it is
+ * why filters compose into the bar, why sorting edits the query, why a link
+ * carries the whole walk. A view that cannot be written down cannot be
+ * hand-edited, diffed in a config file, pasted into a conversation, or
+ * explained to someone who does not have the UI open.
+ *
+ * So a view has a text form, and it is the same language:
+ *
+ *   work_order
+ *     show reference, total_cost, customer_id.name as customer
+ *     count work_order_part via work_order_id as parts
+ *     sum work_order_part.quantity via work_order_id as units
+ *     where customer_id.country_code = AU and total_cost > 500
+ *     sort total_cost desc
+ *     limit 20
+ *
+ * Only two things here are new: the base table on the front, and the
+ * aggregate clauses. Paths, conditions, sort and limit are parsed by
+ * `parseViewQuery`, which the composer's filter box already uses — one
+ * grammar, not two that drift.
+ *
+ * Aggregates name the child table and the foreign key column rather than the
+ * constraint, because a constraint name is a database artefact nobody reads
+ * (`work_order_part_work_order_id_fkey`) and `work_order_part via
+ * work_order_id` says the same thing in words that appear in the schema. The
+ * pair is unambiguous: two foreign keys from one child to one parent must sit
+ * on different columns.
+ */
+import { backrefsTo, parseViewQuery, tableAtPrefix, } from './view.js';
+import { findTable } from './schema.js';
+const AGGREGATE_FNS = ['count', 'sum', 'min', 'max', 'avg'];
+export function viewToText(view, nameConstraint) {
+    const lines = [view.base];
+    if (view.columns.length) {
+        const shown = view.columns.map((c) => (c.alias && c.alias !== c.path ? `${c.path} as ${c.alias}` : c.path));
+        lines.push(`  show ${shown.join(', ')}`);
+    }
+    for (const aggregate of view.aggregates ?? []) {
+        lines.push(`  ${aggregateToText(aggregate, nameConstraint)}`);
+    }
+    const where = filterToText(view);
+    if (where)
+        lines.push(`  where ${where}`);
+    if (view.orderBy?.length) {
+        const parts = view.orderBy.map((o) => (o.direction === 'desc' ? `${o.path} desc` : o.path));
+        lines.push(`  sort ${parts.join(', ')}`);
+    }
+    if (view.limit !== undefined)
+        lines.push(`  limit ${view.limit}`);
+    return lines.join('\n');
+}
+function aggregateToText(aggregate, nameConstraint) {
+    /* `via` on the model is a constraint name; the text form names the child
+       table and its foreign key column instead. The name is recoverable from
+       the pair, and the pair is what a person can read.
+  
+       With no way to resolve it, the constraint name is emitted as-is rather
+       than a table and column being invented — wrong-but-readable is worse
+       than opaque-but-true. */
+    const [table, column] = nameConstraint?.(aggregate.via) ?? [aggregate.via, ''];
+    const target = aggregate.fn === 'count' || !aggregate.column ? table : `${table}.${aggregate.column}`;
+    const on = aggregate.on ? ` on ${aggregate.on}` : '';
+    const alias = aggregate.alias ? ` as ${aggregate.alias}` : '';
+    return `${aggregate.fn} ${target} via ${column}${on}${alias}`;
+}
+/** A namer backed by a schema: the form callers with a connection should use. */
+export function constraintNamer(schema, view) {
+    return (via) => {
+        /* An aggregate can hang off a path, not just the base, so every prefix
+           the view mentions is a candidate parent. */
+        const prefixes = new Set(['', ...(view.aggregates ?? []).map((a) => a.on ?? '')]);
+        for (const prefix of prefixes) {
+            const parent = tableAtPrefix(schema, view.base, prefix);
+            if (!parent)
+                continue;
+            const hit = backrefsTo(schema, parent.id).find((b) => b.fk.name === via);
+            if (hit)
+                return [hit.fk.from.table, hit.fk.from.columns[0]];
+        }
+        return undefined;
+    };
+}
+/** Render with a schema, so aggregates name real tables and columns. */
+export function viewToTextWithSchema(schema, view) {
+    return viewToText(view, constraintNamer(schema, view));
+}
+function filterToText(view) {
+    const groups = view.filter?.groups ?? [];
+    if (!groups.length)
+        return '';
+    const rendered = groups.map((group) => group.map(conditionToText).join(' and '));
+    // A single group needs no parentheses; several are OR-ed and each is
+    // bracketed, matching how the parser reads them back.
+    return rendered.length === 1 ? rendered[0] : rendered.map((g) => `(${g})`).join(' or ');
+}
+function conditionToText(condition) {
+    const { path, op, value } = condition;
+    switch (op) {
+        case 'isNull':
+            return `${path} is empty`;
+        case 'isNotNull':
+            return `${path} is not empty`;
+        case 'contains':
+            return `${path} contains ${quote(value)}`;
+        case 'startsWith':
+            return `${path} startswith ${quote(value)}`;
+        case 'endsWith':
+            return `${path} endswith ${quote(value)}`;
+        case 'in': {
+            const list = Array.isArray(value) ? value : [value];
+            return `${path} in (${list.map(quote).join(', ')})`;
+        }
+        default:
+            return `${path} ${op} ${quote(value)}`;
+    }
+}
+/** Quote only when the grammar needs it, so the common case stays readable. */
+function quote(value) {
+    if (value === null || value === undefined)
+        return '""';
+    const text = String(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return text;
+    return /^[\w.-]+$/.test(text) ? text : `"${text.replace(/"/g, '')}"`;
+}
+/* ---------- reading ---------- */
+/**
+ * An aggregate clause: `count work_order_part via work_order_id as parts`.
+ *
+ * The function word is only treated as a clause when it is followed by
+ * something-then-`via`. A table with a column called `count` or `sum` is not
+ * unusual, and eating the word would turn `sum = 3` into a broken aggregate
+ * rather than a filter.
+ */
+const AGGREGATE_RE = new RegExp(String.raw `\b(${AGGREGATE_FNS.join('|')})\s+([\w.$]+)\s+via\s+([\w$]+)` +
+    String.raw `(?:\s+on\s+([\w.$]+))?(?:\s+as\s+([\w$]+))?`, 'gi');
+/**
+ * Parse a written view.
+ *
+ * The base table and the aggregates are handled here; everything else is
+ * handed to `parseViewQuery`, which the composer's filter box already uses.
+ * Two parsers for one language is how a language starts disagreeing with
+ * itself.
+ */
+export function textToView(schema, text, options = {}) {
+    const errors = [];
+    const body = String(text ?? '').trim();
+    if (!body)
+        return { errors: [{ message: 'Start with a table name.' }] };
+    const baseName = body.split(/\s+/)[0];
+    const base = findTable(schema, baseName) ?? schema.tables.find((t) => t.name === baseName);
+    if (!base) {
+        return { errors: [{ message: `No table called "${baseName}" in this database.`, at: 0 }] };
+    }
+    const rest = body.slice(baseName.length);
+    /* Aggregates are lifted out before the rest is parsed, because
+       `parseViewQuery` knows nothing about them and would read `count` as the
+       start of a condition. */
+    const aggregates = [];
+    const remainder = rest.replace(AGGREGATE_RE, (_match, fn, target, viaColumn, on, alias) => {
+        /* `app.invoice_line` is one qualified table; `work_order_part.quantity`
+           is a table and a column; `app.invoice_line.quantity` is both. A dot
+           cannot tell them apart, so the schema does: if the whole target names a
+           table there is no column, otherwise the last dot separates them.
+    
+           Splitting on the first dot — the obvious implementation — turned
+           `app.invoice_line` into table `app`, and the error it produced named a
+           table that does not exist. Postgres schemas are the common case for
+           this, which is exactly why it survived until the compiler was pointed
+           at a real one. */
+        const targetText = String(target);
+        const namesTable = (id) => Boolean(findTable(schema, id)) || schema.tables.some((t) => t.name === id);
+        let childTable = targetText;
+        let childColumn;
+        if (!namesTable(targetText)) {
+            const lastDot = targetText.lastIndexOf('.');
+            if (lastDot > 0) {
+                childTable = targetText.slice(0, lastDot);
+                childColumn = targetText.slice(lastDot + 1);
+            }
+        }
+        const parent = tableAtPrefix(schema, base.id, on ?? '');
+        if (!parent) {
+            errors.push({ message: `"${on}" is not a reference path on ${base.name}.` });
+            return '';
+        }
+        const backref = backrefsTo(schema, parent.id).find((b) => b.fk.from.table === childTable && b.fk.from.columns.includes(String(viaColumn)));
+        if (!backref) {
+            errors.push({
+                message: `Nothing in ${childTable}.${viaColumn} points at ${parent.name}. ` +
+                    `Try: ${describeBackrefs(schema, parent.id)}`,
+            });
+            return '';
+        }
+        if (fn !== 'count' && !childColumn) {
+            errors.push({ message: `${fn} needs a column, e.g. ${fn} ${childTable}.amount via ${viaColumn}` });
+            return '';
+        }
+        if (childColumn) {
+            const childTableMeta = findTable(schema, backref.fk.from.table);
+            if (childTableMeta && !childTableMeta.columns.some((c) => c.name === childColumn)) {
+                errors.push({ message: `"${childColumn}" is not a column on ${childTable}.` });
+                return '';
+            }
+        }
+        aggregates.push({
+            fn: fn.toLowerCase(),
+            via: backref.fk.name,
+            on: on || undefined,
+            column: childColumn,
+            alias: alias || undefined,
+        });
+        return '';
+    });
+    /* Aliases are lifted out of the `show` clause before it is parsed.
+       `parseViewQuery` validates each entry as a path, and
+       `customer_id.name as customer` is not one — the alias is presentation,
+       not addressing, and only this layer knows about it. */
+    const { text: withoutAliases, aliases } = stripAliases(remainder);
+    const parsed = parseViewQuery(schema, base.id, withoutAliases, options.now, {
+        /* So `sort invoices desc` parses after `… as invoices` — the alias joins
+           the synthetic table for the sort clause, and only the sort clause. */
+        aggregateAliases: aggregates.map((a) => a.alias ?? '').filter(Boolean),
+    });
+    errors.push(...parsed.errors);
+    const view = {
+        id: options.id ?? 'text',
+        name: options.name ?? '',
+        base: base.id,
+        columns: parsed.columns.map((path) => {
+            const alias = aliases.get(path);
+            return alias ? { path, alias } : { path };
+        }),
+        aggregates: aggregates.length ? aggregates : undefined,
+        filter: parsed.filter.groups.length ? parsed.filter : undefined,
+        orderBy: parsed.orderBy.length ? parsed.orderBy : undefined,
+        limit: parsed.limit,
+    };
+    return { view, errors };
+}
+/**
+ * Remove ` as <alias>` from every entry of a `show` clause, returning the
+ * cleaned text and a path → alias map.
+ *
+ * Only the show clause: `as` means something else nowhere in this grammar
+ * today, but rewriting the whole string would break the moment it does.
+ */
+function stripAliases(text) {
+    const aliases = new Map();
+    const cleaned = text.replace(/\b(show|select)\s+([^]*?)(?=\s+\b(?:where|filter|sort|order\s+by|limit)\b|$)/i, (_match, keyword, list) => {
+        const entries = list.split(',').map((entry) => {
+            const aliased = entry.trim().match(/^(.*?)\s+as\s+([\w$]+)$/i);
+            if (!aliased)
+                return entry.trim();
+            aliases.set(aliased[1].trim(), aliased[2]);
+            return aliased[1].trim();
+        });
+        return `${keyword} ${entries.join(', ')}`;
+    });
+    return { text: cleaned, aliases };
+}
+/** A short list of what *would* have worked, for the error to name. */
+function describeBackrefs(schema, parentId) {
+    const options = backrefsTo(schema, parentId)
+        .slice(0, 3)
+        .map((b) => `${b.fk.from.table} via ${b.fk.from.columns[0]}`);
+    return options.length ? options.join(', ') : 'nothing points at this table';
+}

package/dist/shared/vocabulary.js

@@ -0,0 +1,164 @@
+/**
+ * The values a column is allowed to hold, when the database says so.
+ *
+ * A column called `status` typed `text` tells you nothing. A `CHECK (status
+ * IN ('draft','open','paid'))` tells you everything — the states the system
+ * has, which is often the single most useful fact about a table and the one
+ * an agent is most likely to guess wrong. Guessing produces `status =
+ * 'OPEN'`, which returns no rows and looks like an empty table rather than a
+ * spelling mistake.
+ *
+ * Every dialect writes the same constraint differently, so the parsing lives
+ * here and the adapters bring their own constraint text. This is deliberately
+ * a *recogniser*, not a SQL expression parser: it understands the handful of
+ * shapes that mean "one of these" and returns nothing for anything else. A
+ * partial understanding of `CHECK (total > 0 AND status IN (...))` would be
+ * worse than none, because the vocabulary it reported would be presented as
+ * the whole rule.
+ */
+/** A quoted or bare identifier, as any dialect might write the column. */
+function sameColumn(written, column) {
+    const bare = written.trim().replace(/^["`[]|["`\]]$/g, '');
+    return bare.toLowerCase() === column.toLowerCase();
+}
+/** `'a'`, `'it''s'`, `'a'::text` — the string literals inside a list. */
+function literals(list) {
+    const values = [];
+    const pattern = /'((?:[^']|'')*)'(?:::[A-Za-z_" ]+(?:\[\])?)?\s*(,|$)/gy;
+    pattern.lastIndex = 0;
+    let rest = list.trim();
+    let at = 0;
+    while (at < rest.length) {
+        pattern.lastIndex = at;
+        const m = pattern.exec(rest);
+        if (!m)
+            return undefined;
+        values.push(m[1].replace(/''/g, "'"));
+        at = pattern.lastIndex;
+        while (rest[at] === ' ')
+            at += 1;
+    }
+    return values.length ? values : undefined;
+}
+/**
+ * Remove `::type` casts, which Postgres sprays through every stored
+ * expression — `(status)::text = ANY ((ARRAY['a'::character varying])::text[])`
+ * is `status = ANY (ARRAY['a'])` with six casts in it. Quoted strings are
+ * stepped over, so a value that happens to contain `::` survives.
+ */
+function stripCasts(text) {
+    let out = '';
+    let quoted = null;
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        if (quoted) {
+            out += ch;
+            if (ch === quoted)
+                quoted = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            quoted = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === ':' && text[i + 1] === ':') {
+            i += 2;
+            while (i < text.length && /[A-Za-z0-9_ "]/.test(text[i]))
+                i += 1;
+            if (text[i] === '[' && text[i + 1] === ']')
+                i += 1;
+            else
+                i -= 1;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * The vocabulary a single CHECK expression pins for one column.
+ *
+ * Handles the two shapes that mean the same thing:
+ *   `status IN ('a','b')`                                      — every dialect
+ *   `((status)::text = ANY ((ARRAY['a'::text, 'b'::text])))`   — what Postgres
+ *                                                                stores instead
+ */
+export function checkVocabulary(expression, column) {
+    const text = stripCasts(expression).trim();
+    /* Postgres rewrites `IN` to `= ANY (ARRAY[...])` before storing it, so the
+       constraint you wrote is never the constraint you read back. */
+    const any = /^[(\s]*([^\s()]+)[)\s]*=\s*ANY\s*[(\s]*ARRAY\s*\[(.*)\][\s)]*$/is.exec(text);
+    if (any && sameColumn(any[1], column))
+        return literals(any[2]);
+    const list = /^[(\s]*([^\s()]+)\s+IN\s*\((.*)\)[\s)]*$/is.exec(text);
+    if (list && sameColumn(list[1], column))
+        return literals(list[2]);
+    return undefined;
+}
+/**
+ * The vocabulary written into a column's type, as MySQL does it:
+ * `enum('draft','open')`, `set('a','b')`.
+ */
+export function typeVocabulary(type) {
+    const m = /^\s*(?:enum|set)\s*\((.*)\)\s*$/is.exec(type);
+    return m ? literals(m[1]) : undefined;
+}
+/**
+ * Every CHECK clause in a `CREATE TABLE` statement, for dialects that keep
+ * the statement rather than the constraints — SQLite.
+ *
+ * Scanned with a depth counter rather than a regex because a check body
+ * contains parentheses of its own, and matching to the first `)` truncates
+ * `CHECK (status IN ('a','b'))` to `status IN ('a'`.
+ */
+export function checksIn(ddl) {
+    const found = [];
+    const pattern = /\bCHECK\s*\(/gi;
+    let match;
+    while ((match = pattern.exec(ddl))) {
+        let depth = 1;
+        let i = match.index + match[0].length;
+        let quoted = null;
+        const start = i;
+        for (; i < ddl.length && depth > 0; i += 1) {
+            const ch = ddl[i];
+            if (quoted) {
+                if (ch === quoted)
+                    quoted = null;
+                continue;
+            }
+            if (ch === "'" || ch === '"')
+                quoted = ch;
+            else if (ch === '(')
+                depth += 1;
+            else if (ch === ')')
+                depth -= 1;
+        }
+        if (depth === 0)
+            found.push(ddl.slice(start, i - 1));
+        pattern.lastIndex = i;
+    }
+    return found;
+}
+/**
+ * The allowed values for each column of a table, read out of its DDL.
+ *
+ * Column-level (`status TEXT CHECK (status IN (...))`) and table-level
+ * (`CHECK (status IN (...))`) checks are the same text by the time they get
+ * here, which is why this asks each check about each column rather than
+ * trying to work out which column a check was attached to.
+ */
+export function vocabularyFromDDL(ddl, columns) {
+    const found = new Map();
+    for (const check of checksIn(ddl)) {
+        for (const column of columns) {
+            if (found.has(column))
+                continue;
+            const values = checkVocabulary(check, column);
+            if (values)
+                found.set(column, values);
+        }
+    }
+    return found;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "tablewalk",
+  "version": "0.0.1",
+  "description": "Follow the data. A database browser built around the walk: a foreign key is a place you can go.",
+  "license": "MIT",
+  "author": "Baljinder Randhawa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rbaljinder/tablewalk.git"
+  },
+  "homepage": "https://github.com/rbaljinder/tablewalk#readme",
+  "bugs": {
+    "url": "https://github.com/rbaljinder/tablewalk/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "tablewalk": "dist/server/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "database",
+    "sqlite",
+    "postgres",
+    "schema",
+    "browser",
+    "cli"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/server/index.ts",
+    "start": "tsx src/server/index.ts",
+    "test": "tsc --noEmit && node test/check-client-imports.mjs && node test/check-client-types.mjs && tsx --test --test-timeout=120000 test/run.ts 'test/*.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R src/client/. dist/client/ && test -f dist/client/index.html",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test",
+    "demo": "tsx test/make-demo-db.ts .demo/demo.db --scale 3000 && tsx src/server/index.ts --db .demo/demo.db --open",
+    "e2e": "playwright test",
+    "seed:live": "tsx test/seed-live.ts"
+  },
+  "optionalDependencies": {
+    "mysql2": "^3.23.4",
+    "pg": "^8.23.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.23.12",
+    "typescript": "^5.7.3"
+  }
+}