tablewalk 0.0.1

package/dist/shared/schema.js

@@ -0,0 +1,377 @@
+/**
+ * The schema model every adapter produces, and the whole reason this tool
+ * can exist for more than one database.
+ *
+ * Most database clients treat a schema as a list of tables. The interesting
+ * structure is the edges: which column points at which table, and — the part
+ * almost nothing surfaces well — which columns elsewhere point back at the row
+ * you are looking at. Answering that second question is what turns a database
+ * from a list into something you can walk.
+ *
+ * Relational databases hand you both directions for free. `information_schema`
+ * knows every foreign key, so the reverse map is a filter over a list you
+ * already have. Adapters do the dialect-specific reading; everything above
+ * this file works on the model below and never learns which database it is.
+ */
+/**
+ * A dialect's spelling of an `ON DELETE` action, normalised.
+ *
+ * Each engine words these differently — SQLite and MySQL in prose, Postgres as
+ * a single character — and the difference is not interesting upstream. Shared
+ * so the three adapters cannot drift on a value the delete dialog reads
+ * literally.
+ *
+ * Unrecognised returns undefined rather than a default: "the adapter did not
+ * report it" and "the constraint says NO ACTION" lead to different advice, and
+ * conflating them presents an unknown as harmless.
+ */
+export function deleteRuleOf(raw) {
+    switch (String(raw ?? '').trim().toUpperCase()) {
+        // Postgres stores confdeltype as one character.
+        case 'C':
+        case 'CASCADE': return 'cascade';
+        case 'N':
+        case 'SET NULL': return 'set null';
+        case 'D':
+        case 'SET DEFAULT': return 'set default';
+        case 'R':
+        case 'RESTRICT': return 'restrict';
+        case 'A':
+        case 'NO ACTION': return 'no action';
+        default: return undefined;
+    }
+}
+/* ---------- derived views over the model ---------- */
+/**
+ * Columns elsewhere that point at this table — the "what refers to me"
+ * question. Deliberately derived rather than stored, so it cannot drift from
+ * the foreign key list it is computed from.
+ */
+export function referencesTo(schema, tableId) {
+    return schema.foreignKeys.filter((fk) => fk.to.table === tableId);
+}
+/** Columns on this table that point elsewhere. */
+export function referencesFrom(schema, tableId) {
+    return schema.foreignKeys.filter((fk) => fk.from.table === tableId);
+}
+export function findTable(schema, tableId) {
+    return schema.tables.find((t) => t.id === tableId);
+}
+/**
+ * A table by its id, or by a bare name when only one table has it.
+ *
+ * A table's id is qualified where the engine qualifies things — `public.customer`
+ * on Postgres, `shop.invoice` on MySQL — and nobody types that when there is
+ * only one `customer`. Ambiguity is left unresolved rather than guessed: two
+ * schemas with a `customer` each is exactly when picking one silently writes
+ * to the wrong database.
+ */
+export function tableNamed(schema, asked) {
+    const exact = findTable(schema, asked);
+    if (exact)
+        return exact;
+    const matches = schema.tables.filter((t) => t.name === asked);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/**
+ * Whether a column should be treated as a date for *presentation* — offering
+ * relative-date filters, rendering without a midnight time.
+ *
+ * Kept separate from `columnKind`, which feeds value coercion and must stay
+ * strictly declaration-based: guessing wrong there would change what gets
+ * written to the database. Guessing wrong here only offers a filter that does
+ * not match, which the user sees immediately.
+ *
+ * The fallback exists because plenty of real schemas store dates in TEXT —
+ * SQLite has no date type at all, so `opened_on TEXT` is idiomatic rather
+ * than sloppy, and refusing to offer `last 30 days` on it would make the best
+ * part of the language unavailable exactly where it is most needed.
+ */
+const DATE_NAME = /(^|_)(date|time|datetime|timestamp)(_|$)|_(at|on)$|^(created|updated|modified|deleted)(_|$)/i;
+export function looksLikeDate(column) {
+    if (columnKind(column.type) === 'date')
+        return true;
+    // Only text columns get the name-based benefit of the doubt; a number named
+    // `updated_at` is an epoch and comparing it to a timestamp string is wrong.
+    return columnKind(column.type) === 'text' && DATE_NAME.test(column.name);
+}
+/**
+ * The column a row is best identified by in a list or a breadcrumb.
+ *
+ * A primary key is correct and unreadable — nobody recognises a row by its
+ * UUID. Prefer a human-meaningful column when the table has one, and say so
+ * by returning the primary key only as a fallback.
+ */
+/* Order matters and is not arbitrary. Name-family columns come first because
+   `title` on a table that also has `first_name` is a job title, not a label —
+   ranking it higher labels every row in a staff list "Account Executive". */
+const LABEL_CANDIDATES = [
+    'name',
+    'full_name',
+    'display_name',
+    'first_name',
+    'username',
+    'title',
+    'label',
+    'subject',
+    'number',
+    'email',
+    'slug',
+    'code',
+];
+export function labelColumn(table) {
+    const byName = LABEL_CANDIDATES.find((c) => table.columns.some((col) => col.name === c));
+    if (byName)
+        return byName;
+    /* A date is never a good label. Two rows created the same day are
+       indistinguishable, and "2025-03-14" tells you nothing about *which*
+       invoice you are looking at — the key at least identifies it. Before the
+       demo declared proper date types this quietly labelled every invoice by
+       its date, which looked plausible and was useless. */
+    /* Nor is a column with a vocabulary. `status` is a text column and reads
+       like one, but a name has to identify a row: labelling six hundred
+       invoices "issued" is worse than labelling them by their key, because it
+       looks like a name and distinguishes nothing. */
+    const firstText = table.columns.find((c) => !c.primaryKey && /char|text|varchar|string/i.test(c.type)
+        && !looksLikeDate(c) && !c.allowed?.length);
+    return firstText?.name ?? table.columns.find((c) => c.primaryKey)?.name;
+}
+/** Primary key columns, in declaration order. */
+export function primaryKey(table) {
+    return table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+}
+/* Tables that hold identities rather than things: the party-model pattern,
+   where a person's name lives on `party` or `person` and everything else —
+   employee, contact, supplier — points at it. Named the way labelColumn's
+   candidates are, because the schema does not record "this link is 1:1" and
+   the name is the signal actually present. */
+const IDENTITY_TABLE = /(^|_)(party|parties|person|persons|people|user|users|profile|profiles|identity|identities)$/i;
+/**
+ * Where a row's name lives, as a view path.
+ *
+ * `labelColumn` answers "which of this table's own columns reads best", and
+ * for a well-normalised table the honest answer is none of them: employee
+ * carries `party_id`, and the name is `party.display_name`, one table away.
+ * So when a table's best label is its own key, the question is asked one
+ * forward hop further before giving up — a tool whose whole idea is walking
+ * references should not call a person "30" when the walk it teaches would
+ * have found the name.
+ *
+ * The hop is taken only across a link that is plausibly one-to-one: a
+ * reference that *is* the whole primary key (the subtype pattern —
+ * `person.party_id PRIMARY KEY REFERENCES party` — one-to-one by
+ * construction), or a reference into an identity table. Not any reference
+ * with a name on the other end: `invoice.customer_id` reaches a perfectly
+ * good name that is not the invoice's — forty invoices share it, and a trail
+ * of rows all called "Dry Creek Vineyards" identifies nothing.
+ *
+ * A table with a real label of its own keeps it, so nothing changes where
+ * things already read well. Self-references are skipped: the manager's name
+ * is not this row's name.
+ */
+export function labelPath(schema, table) {
+    const own = labelColumn(table);
+    const key = primaryKey(table);
+    if (own && !key.includes(own))
+        return own;
+    for (const column of table.columns) {
+        const ref = column.references;
+        if (!ref || ref.table === table.id)
+            continue;
+        const oneToOne = key.length === 1 && key[0] === column.name;
+        const target = findTable(schema, ref.table);
+        if (!target)
+            continue;
+        if (!oneToOne && !IDENTITY_TABLE.test(target.name))
+            continue;
+        const theirs = labelColumn(target);
+        if (!theirs || primaryKey(target).includes(theirs))
+            continue;
+        return `${column.name}.${theirs}`;
+    }
+    return own;
+}
+/* Columns that record when a row was last touched, then when it came into
+   existence. Ordered by how well each answers "what has been happening here",
+   which is the question a table you have just opened is usually being asked. */
+const TOUCHED_NAME = /^(sys_)?(updated|modified|changed|last_updated)(_at|_on|_date)?$/i;
+const CREATED_NAME = /^(sys_)?(created|inserted|added|opened|raised|issued|ordered|received|signed_up|joined)(_at|_on|_date)?$/i;
+/**
+ * The order a table's rows are shown in when the query does not say.
+ *
+ * There has to be one, and not for taste: `LIMIT`/`OFFSET` without `ORDER BY`
+ * has no defined order in either SQLite or Postgres, so paging through an
+ * unordered table can repeat a row on page two and never show another. The
+ * database is free to hand back rows in whatever order it finds them, and
+ * Postgres in particular will change its mind after an UPDATE moves a row.
+ * A default order is what makes "Next" mean what it appears to mean.
+ *
+ * Given that it must exist, it may as well be useful. In order of preference:
+ *
+ *   1. When the row was last touched, newest first — *if the column is
+ *      indexed*. On a table with an indexed `updated_at`, "what changed
+ *      recently" is what people open it to see, and the database can answer it
+ *      by walking the index backwards.
+ *   2. When it was created, newest first, under the same condition.
+ *   3. A single numeric primary key, descending. On an autoincrement key that
+ *      is the same "newest first" by proxy.
+ *   4. Any other primary key, ascending. A text key sorts alphabetically —
+ *      `country` starting at ZW rather than AU would be perverse — and a
+ *      composite key ascending groups its children under their parent, which
+ *      is how `invoice_line` wants to be read.
+ *   5. The label column, then the first column: neither is meaningful, but
+ *      both are deterministic, which is the part that matters.
+ *
+ * The index condition is the one rule here that is not about taste. A default
+ * that nobody asked for must not be a default that costs anything: `ORDER BY
+ * updated_at DESC LIMIT 20` on an unindexed column is a full scan and a sort
+ * of the whole table to return twenty rows, and it would happen on every table
+ * you clicked. The primary key is always indexed, which is why it is the
+ * fallback rather than merely one option among several.
+ *
+ * A table whose adapter does not report indexes at all gets the key, not a
+ * guess — `indexed` is undefined rather than empty in that case precisely so
+ * the two can be told apart.
+ */
+export function defaultOrder(table) {
+    const indexed = new Set(table.indexed ?? []);
+    const named = (test) => table.columns.find((c) => test.test(c.name) &&
+        (looksLikeDate(c) || columnKind(c.type) === 'number') &&
+        indexed.has(c.name));
+    const touched = named(TOUCHED_NAME) ?? named(CREATED_NAME);
+    if (touched)
+        return withKey(table, [{ column: touched.name, direction: 'desc' }]);
+    const key = primaryKey(table);
+    if (key.length === 1) {
+        const column = table.columns.find((c) => c.name === key[0]);
+        return [{ column: key[0], direction: columnKind(column.type) === 'number' ? 'desc' : 'asc' }];
+    }
+    if (key.length > 1)
+        return key.map((column) => ({ column, direction: 'asc' }));
+    const label = labelColumn(table);
+    const fallback = label ?? table.columns[0]?.name;
+    return fallback ? [{ column: fallback, direction: 'asc' }] : [];
+}
+/**
+ * Make an order total by appending the primary key.
+ *
+ * Sorting by `status` leaves every row with the same status in an undefined
+ * order relative to its neighbours — which is the paging bug again, one level
+ * down: page one and page two disagree about which of two equal rows comes
+ * first, so one is shown twice and one not at all. Appending the key breaks
+ * every remaining tie the same way each time.
+ *
+ * A table with no primary key cannot be made stable this way, and is left
+ * alone rather than given a guess.
+ */
+export function withKey(table, order) {
+    const chosen = new Set(order.map((o) => o.column));
+    const key = primaryKey(table).filter((c) => !chosen.has(c));
+    return [...order, ...key.map((column) => ({ column, direction: 'asc' }))];
+}
+/**
+ * The order to actually run with, and whether the caller asked for it.
+ *
+ * `implicit` is reported rather than hidden: the grid shows which column it
+ * sorted by, so a default order is something the reader can see and disagree
+ * with rather than a silent rearrangement of their data.
+ */
+export function resolveOrder(table, requested) {
+    if (requested?.length)
+        return { order: withKey(table, requested), implicit: false };
+    return { order: defaultOrder(table), implicit: true };
+}
+/**
+ * Reconstruct a table's DDL from the catalog.
+ *
+ * This is a *reconstruction*, and callers must say so. It is built from what
+ * introspection captured — columns, types, nullability, defaults, keys — and
+ * therefore omits anything the model does not carry: indexes, check
+ * constraints, triggers, partitioning, storage parameters. Presenting it as
+ * the definitive `CREATE TABLE` would be a lie that bites the first time
+ * someone copies it into a migration.
+ *
+ * An adapter that can produce the database's own stored DDL should do so
+ * instead; `SqliteAdapter` does, because `sqlite_master` keeps the original
+ * statement text verbatim.
+ */
+export function renderDDL(schema, tableId) {
+    const table = findTable(schema, tableId);
+    if (!table)
+        return `-- No table called "${tableId}".`;
+    const quote = (id) => `"${id.replace(/"/g, '""')}"`;
+    /* A qualified name is two identifiers, not one containing a dot. Quoting
+       `app.invoice_line` whole produces a table literally named "app.invoice_line",
+       which is valid SQL for something that does not exist — the worst kind of
+       wrong output, because it looks right until you run it. */
+    const qualified = (id) => {
+        const table = findTable(schema, id);
+        return table?.schema ? `${quote(table.schema)}.${quote(table.name)}` : quote(id);
+    };
+    const width = Math.max(...table.columns.map((c) => c.name.length), 0);
+    const lines = table.columns.map((col) => {
+        const parts = [quote(col.name).padEnd(width + 2), col.type.toUpperCase()];
+        if (!col.nullable)
+            parts.push('NOT NULL');
+        if (col.default !== undefined)
+            parts.push(`DEFAULT ${col.default}`);
+        return `  ${parts.join(' ')}`;
+    });
+    const pk = primaryKey(table);
+    if (pk.length)
+        lines.push(`  PRIMARY KEY (${pk.map(quote).join(', ')})`);
+    for (const fk of referencesFrom(schema, tableId)) {
+        lines.push(`  CONSTRAINT ${quote(fk.name)} FOREIGN KEY (${fk.from.columns.map(quote).join(', ')}) ` +
+            `REFERENCES ${qualified(fk.to.table)} (${fk.to.columns.map(quote).join(', ')})`);
+    }
+    const header = table.isView
+        ? `-- ${tableId} is a view. Its defining query was not captured;\n-- the columns below are what it returns.\nCREATE VIEW ${qualified(tableId)} (`
+        : `CREATE TABLE ${qualified(tableId)} (`;
+    const body = `${header}\n${lines.join(',\n')}\n);`;
+    return table.comment ? `-- ${table.comment}\n${body}` : body;
+}
+export function columnKind(type) {
+    const t = (type ?? '').toLowerCase();
+    if (/bool/.test(t))
+        return 'boolean';
+    if (/int|serial|numeric|decimal|real|double|float|money/.test(t))
+        return 'number';
+    if (/date|time/.test(t))
+        return 'date';
+    if (/char|text|uuid|json|enum|clob/.test(t))
+        return 'text';
+    return 'other';
+}
+/**
+ * Turn a value on its way *into* the database into the right JavaScript type
+ * for its column.
+ *
+ * Everything typed into a text input arrives as a string, including "17901"
+ * for a REAL column. SQLite's type affinity usually rescues that, but not
+ * always — a column with BLOB affinity stores the characters — and Postgres
+ * rejects it outright. Either way the stored value should be a number because
+ * the column says so, not because the driver was forgiving.
+ *
+ * Unparseable input is passed through unchanged rather than coerced to NaN or
+ * 0. Letting the database reject "abc" for an integer column gives the user a
+ * real error; silently storing 0 gives them a wrong number.
+ */
+export function coerceForColumn(declaredType, value) {
+    if (value === null || typeof value !== 'string')
+        return value;
+    const kind = columnKind(declaredType);
+    if (kind === 'number') {
+        if (value.trim() === '')
+            return null;
+        const n = Number(value);
+        return Number.isFinite(n) ? n : value;
+    }
+    if (kind === 'boolean') {
+        if (/^(true|yes|1|t)$/i.test(value))
+            return true;
+        if (/^(false|no|0|f)$/i.test(value))
+            return false;
+        return value;
+    }
+    return value;
+}

package/dist/shared/sqlsaved.js

@@ -0,0 +1,67 @@
+/**
+ * Saved SQL statements, as a config file section.
+ *
+ * The same idea as the `views` section beside it, for the same reason: a
+ * statement you retype every morning is a statement that should have a name,
+ * and a *team's* statements belong in a file they can commit rather than in
+ * one person's browser. `tablewalk.json` is already the place a repository says
+ * "these are the databases this project talks to"; this lets it also say "and
+ * these are the questions people ask of them".
+ *
+ * The stored form is the text, never anything compiled. It stays readable in
+ * the editor, it survives the schema changing underneath it — at worst as a
+ * visible error you can fix rather than a silently wrong answer — and it can be
+ * reviewed in a pull request by someone who knows SQL and nothing about
+ * tablewalk.
+ */
+/**
+ * Read the `queries` section of a config file.
+ *
+ * Errors name the file, the position *and* the statement's name where there is
+ * one, because a config file is something a person wrote by hand and "queries
+ * is not an array" sends them to search a file they may not have written.
+ *
+ * A duplicate name is refused rather than resolved. Two statements called
+ * "Daily totals" that do different things is a worse outcome than a startup
+ * error, and silently keeping the last one is the worst of the three.
+ */
+export function parseQueriesConfig(raw, where) {
+    const queries = raw?.queries;
+    if (queries === undefined)
+        return [];
+    if (!Array.isArray(queries))
+        throw new Error(`${where}: "queries" must be an array.`);
+    const seen = new Set();
+    return queries.map((entry, i) => {
+        const at = `${where}: query ${i + 1}`;
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error(`${at} is not an object.`);
+        }
+        const q = entry;
+        if (typeof q.name !== 'string' || !q.name.trim())
+            throw new Error(`${at} has no "name".`);
+        const name = q.name.trim();
+        if (seen.has(name)) {
+            throw new Error(`${where}: two queries are called "${name}". Names have to be distinct.`);
+        }
+        seen.add(name);
+        if (typeof q.sql !== 'string' || !q.sql.trim()) {
+            throw new Error(`${at} ("${name}") has no "sql".`);
+        }
+        return {
+            name,
+            sql: q.sql.trim(),
+            description: typeof q.description === 'string' && q.description.trim()
+                ? q.description.trim()
+                : undefined,
+            connection: typeof q.connection === 'string' && q.connection.trim()
+                ? q.connection.trim()
+                : undefined,
+            source: 'config',
+        };
+    });
+}
+/** The saved statements that apply to one connection, by id or by name. */
+export function queriesFor(all, connectionId, connectionName) {
+    return all.filter((q) => !q.connection || q.connection === connectionId || q.connection === connectionName);
+}