@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/explorer/graph.js

@@ -0,0 +1,679 @@
+// A graph of rows: some rows of a table, and the rows linked to them through foreign keys.
+import { createHash } from 'node:crypto';
+import { quoteIdentifier } from '../db/identifiers.js';
+import { listColumns, qualified, tableLabel } from './catalog.js';
+import { primaryKeyOf } from './edit.js';
+import { buildWhere } from './filter.js';
+import { DEFAULT_COUNT_CAP, foreignKeyId, listForeignKeys, } from './references.js';
+import { withStatementTimeout } from './timeout.js';
+export class GraphError extends Error {
+}
+export const DEFAULT_GRAPH_LIMITS = {
+    maxStart: 50,
+    maxNodes: 300,
+    perKey: 20,
+    timeoutMs: 5000,
+    countCap: DEFAULT_COUNT_CAP,
+};
+export const MAX_GRAPH_DEPTH = 3;
+/** The id of a row: its schema, table and primary key values (or a hash of the row without one). */
+export function nodeId(table, key) {
+    return JSON.stringify([table.schema, table.name, key]);
+}
+const isNodeId = (id) => id.startsWith('[');
+/** The table and primary key values an id was made of; null when it is not one for a primary key. */
+export function parseNodeId(id) {
+    try {
+        const [schema, name, key] = JSON.parse(id);
+        if (typeof schema !== 'string' || typeof name !== 'string')
+            return null;
+        if (!Array.isArray(key) || key.some((value) => typeof value !== 'string'))
+            return null;
+        return { table: { schema, name }, key: key };
+    }
+    catch {
+        return null;
+    }
+}
+/** The label of a row unless another is picked: its key's values, joined when the key is composite. */
+export function keyLabel(key) {
+    const label = Object.values(key)
+        .map((value) => value ?? 'NULL')
+        .join(', ');
+    return label.length > 60 ? `${label.slice(0, 59)}…` : label;
+}
+const tupleKey = (values) => JSON.stringify(values);
+const chunksOf = (items, size) => Array.from({ length: Math.ceil(items.length / size) }, (_, i) => items.slice(i * size, (i + 1) * size));
+// Tuples are looked up this many at a time, which keeps the parameters of a statement few.
+const BATCH = 200;
+const edgeId = (key, from, to) => `edge:${tableLabel(key.from)}.${key.name}|${from}|${to}`;
+// Hidden tables that a path may go through.
+const MAX_HIDDEN = 3;
+const stepEnd = (step) => (step.forward ? step.key.to : step.key.from);
+const stepStart = (step) => (step.forward ? step.key.fromColumns : step.key.toColumns);
+const stepTarget = (step) => (step.forward ? step.key.toColumns : step.key.fromColumns);
+class Walk {
+    session;
+    limits;
+    direction;
+    nodes = new Map();
+    edges = new Map();
+    more = [];
+    truncated = false;
+    seen;
+    hidden;
+    skipped;
+    seenNodes;
+    columns = new Map();
+    keys = new Map();
+    constructor(session, limits, drawn, direction, hide = [], skip = []) {
+        this.session = session;
+        this.limits = limits;
+        this.direction = direction;
+        this.skipped = new Set(skip);
+        this.hidden = new Set(hide.map(tableLabel));
+        this.seen = new Set(drawn);
+        this.seenNodes = drawn.filter(isNodeId).length;
+    }
+    columnsOf(table) {
+        const label = tableLabel(table);
+        let found = this.columns.get(label);
+        if (!found)
+            this.columns.set(label, (found = listColumns(this.session, table)));
+        return found;
+    }
+    foreignKeysOf(table) {
+        const label = tableLabel(table);
+        let found = this.keys.get(label);
+        if (!found) {
+            // Keys that are skipped are not there as far as the walk can tell.
+            found = listForeignKeys(this.session, table).then(({ outgoing, incoming }) => ({
+                outgoing: outgoing.filter((key) => !this.skipped.has(foreignKeyId(key))),
+                incoming: incoming.filter((key) => !this.skipped.has(foreignKeyId(key))),
+            }));
+            this.keys.set(label, found);
+        }
+        return found;
+    }
+    get full() {
+        return this.seenNodes + this.nodes.size >= this.limits.maxNodes;
+    }
+    /** The node of a row. `fresh` is set when it is new to the graph; null when there is no room. */
+    async nodeFor(table, row, reachedBy, distance, start = false) {
+        const columns = await this.columnsOf(table);
+        const primary = primaryKeyOf(columns);
+        const key = {};
+        let id;
+        if (primary.length > 0) {
+            for (const name of primary)
+                key[name] = row[name] ?? null;
+            id = nodeId(table, primary.map((name) => row[name] ?? ''));
+        }
+        else {
+            // Rows cannot be told apart by key, so the whole row is part of the id.
+            for (const name of reachedBy)
+                key[name] = row[name] ?? null;
+            const hash = createHash('sha1').update(JSON.stringify(row)).digest('hex').slice(0, 12);
+            id = nodeId(table, `~${hash}`);
+        }
+        const known = this.nodes.get(id);
+        if (known)
+            return { node: known, id, fresh: false };
+        if (this.seen.has(id))
+            return { node: null, id, fresh: false };
+        if (this.full) {
+            this.truncated = true;
+            return { node: null, id, fresh: false };
+        }
+        const node = {
+            id,
+            table,
+            key,
+            label: keyLabel(key),
+            row,
+            distance,
+            start,
+            expandable: primary.length > 0,
+        };
+        this.nodes.set(id, node);
+        return { node, id, fresh: true };
+    }
+    addEdge(key, from, to) {
+        const id = edgeId(key, from, to);
+        if (this.seen.has(id) || this.edges.has(id))
+            return;
+        this.edges.set(id, {
+            id,
+            from,
+            to,
+            constraint: key.name,
+            fromColumns: key.fromColumns,
+            toColumns: key.toColumns,
+        });
+    }
+    /** A link between the rows at the two ends of a path through hidden tables; it has no direction. */
+    addViaEdge(via, a, b) {
+        const [from, to] = a <= b ? [a, b] : [b, a];
+        const name = via.map(tableLabel).join(' › ');
+        const id = `edge:via ${name}|${from}|${to}`;
+        if (this.seen.has(id) || this.edges.has(id))
+            return;
+        this.edges.set(id, {
+            id,
+            from,
+            to,
+            constraint: `via ${name}`,
+            fromColumns: [],
+            toColumns: [],
+            via,
+        });
+    }
+    isHidden(table) {
+        return this.hidden.has(tableLabel(table));
+    }
+    paths = new Map();
+    /**
+     * The shortest ways from a table to each table that is drawn, through one or more hidden tables, found
+     * by walking the foreign keys (which are only metadata). Tables that a key leads to directly are not
+     * reached this way. Keys that tie for the shortest way to a table are all kept.
+     */
+    pathsFrom(origin) {
+        const label = tableLabel(origin);
+        let found = this.paths.get(label);
+        if (!found)
+            this.paths.set(label, (found = this.findPaths(origin)));
+        return found;
+    }
+    async findPaths(origin) {
+        const out = [];
+        const shortest = new Map();
+        // Tables reached by one key are not also reached the long way.
+        const direct = new Set();
+        let level = [
+            { table: origin, steps: [], via: [] },
+        ];
+        for (let depth = 0; depth <= MAX_HIDDEN && level.length > 0; depth++) {
+            const next = [];
+            for (const { table, steps, via } of level) {
+                const { outgoing, incoming } = await this.foreignKeysOf(table);
+                const last = steps[steps.length - 1];
+                const options = [
+                    ...outgoing.map((key) => ({ key, forward: true })),
+                    ...incoming.map((key) => ({ key, forward: false })),
+                ];
+                for (const step of options) {
+                    // The key just used leads back to where it came from.
+                    if (last && foreignKeyId(last.key) === foreignKeyId(step.key))
+                        continue;
+                    const to = stepEnd(step);
+                    if (this.isHidden(to)) {
+                        if (via.some((t) => tableLabel(t) === tableLabel(to)) ||
+                            tableLabel(to) === tableLabel(origin)) {
+                            continue;
+                        }
+                        next.push({ table: to, steps: [...steps, step], via: [...via, to] });
+                        continue;
+                    }
+                    const end = tableLabel(to);
+                    if (steps.length === 0) {
+                        direct.add(end);
+                        continue;
+                    }
+                    const length = steps.length + 1;
+                    if (direct.has(end) || (shortest.has(end) && shortest.get(end) < length))
+                        continue;
+                    shortest.set(end, length);
+                    out.push({ steps: [...steps, step], via, end: to });
+                }
+            }
+            level = next;
+        }
+        return out.filter((path) => !direct.has(tableLabel(path.end)));
+    }
+    /**
+     * The rows at the end of a path from each node, linked to it. One statement joins the tables in
+     * between and gives the distinct pairs of key values at the two ends; the rows at the end are then
+     * fetched as they are for a direct key. At most `perKey` are linked to a node.
+     */
+    async through(path, nodes) {
+        const [first, last] = [path.steps[0], path.steps[path.steps.length - 1]];
+        const originColumns = stepStart(first);
+        const wanted = new Map();
+        for (const node of nodes) {
+            const values = originColumns.map((name) => node.row[name] ?? null);
+            if (values.some((value) => value === null))
+                continue;
+            const tuple = tupleKey(values);
+            const entry = wanted.get(tuple) ?? { values, nodes: [] };
+            entry.nodes.push(node);
+            wanted.set(tuple, entry);
+        }
+        // t1 .. t(n-1) are the hidden tables, joined along the keys in between. When the last key is
+        // followed against its direction, many rows of the end table share its values, so the end table is
+        // joined as well and its rows are told apart by their primary keys.
+        const endPrimary = primaryKeyOf(await this.columnsOf(path.end));
+        const joinEnd = !last.forward && endPrimary.length > 0;
+        const alias = (i) => `t${i}`;
+        const columns = (i, names) => names.map((name) => `${alias(i)}.${quoteIdentifier(name)}`);
+        const chain = [...path.steps.slice(0, -1).map(stepEnd), ...(joinEnd ? [path.end] : [])];
+        let from = `${qualified(chain[0])} ${alias(1)}`;
+        for (let i = 1; i < chain.length; i++) {
+            const step = path.steps[i];
+            const [here, there] = step.forward
+                ? [step.key.fromColumns, step.key.toColumns]
+                : [step.key.toColumns, step.key.fromColumns];
+            const on = columns(i, here).map((c, k) => `${c} = ${columns(i + 1, there)[k]}`);
+            from += ` JOIN ${qualified(chain[i])} ${alias(i + 1)} ON ${on.join(' AND ')}`;
+        }
+        const lookupColumns = columns(1, stepTarget(first));
+        const endSource = joinEnd
+            ? columns(chain.length, endPrimary)
+            : columns(chain.length, stepStart(last));
+        const endColumns = joinEnd ? endPrimary : stepTarget(last);
+        const originAlias = lookupColumns.map((c, i) => `${c} AS "__o${i}"`);
+        const endAlias = endSource.map((c, i) => `${c} AS "__e${i}"`);
+        const partition = lookupColumns.map((_, i) => `"__o${i}"`).join(', ');
+        const order = endSource.map((_, i) => `"__e${i}"`).join(', ');
+        const created = [];
+        for (const batch of chunksOf([...wanted.values()], BATCH)) {
+            const params = [];
+            const marks = batch.map((entry) => {
+                const group = entry.values.map((value) => {
+                    params.push(value ?? '');
+                    return `$${params.length}`;
+                });
+                return lookupColumns.length === 1 ? group[0] : `(${group.join(', ')})`;
+            });
+            const left = lookupColumns.length === 1 ? lookupColumns[0] : `(${lookupColumns.join(', ')})`;
+            const pairs = await this.query(`SELECT * FROM (
+					SELECT d.*, row_number() OVER (PARTITION BY ${partition} ORDER BY ${order}) AS "__rn",
+						count(*) OVER (PARTITION BY ${partition}) AS "__n"
+					FROM (SELECT DISTINCT ${[...originAlias, ...endAlias].join(', ')} FROM ${from}
+						WHERE ${left} IN (${marks.join(', ')}) AND ${endSource.map((c) => `${c} IS NOT NULL`).join(' AND ')}) d
+				) found WHERE "__rn" <= ${this.limits.perKey}`, params);
+            const ends = new Map();
+            for (const pair of pairs) {
+                const origin = wanted.get(tupleKey(originColumns.map((_, i) => pair[`__o${i}`] ?? null)));
+                if (!origin)
+                    continue;
+                if (Number(pair.__n) > this.limits.perKey)
+                    this.truncated = true;
+                const values = endColumns.map((_, i) => pair[`__e${i}`] ?? null);
+                const tuple = tupleKey(values);
+                const entry = ends.get(tuple) ?? { values, links: [] };
+                entry.links.push(...origin.nodes);
+                ends.set(tuple, entry);
+            }
+            for (const group of chunksOf([...ends.values()], BATCH)) {
+                const rows = await this.fetch(path.end, endColumns, group.map((entry) => entry.values), this.limits.maxNodes);
+                for (const row of rows) {
+                    const entry = ends.get(tupleKey(endColumns.map((name) => row[name] ?? null)));
+                    if (!entry)
+                        continue;
+                    for (const origin of entry.links) {
+                        const { node, id, fresh } = await this.nodeFor(path.end, row, endColumns, origin.distance + 1);
+                        if (!node && !this.seen.has(id))
+                            continue;
+                        if (fresh && node)
+                            created.push(node);
+                        this.addViaEdge(path.via, origin.id, id);
+                    }
+                }
+            }
+        }
+        return created;
+    }
+    /** Follows the keys of the nodes for `levels` steps, giving the rows found the next distance. */
+    async follow(frontier, levels) {
+        let current = frontier;
+        for (let level = 0; level < levels && current.length > 0; level++) {
+            const next = [];
+            const byTable = new Map();
+            for (const node of current) {
+                const label = tableLabel(node.table);
+                byTable.set(label, [...(byTable.get(label) ?? []), node]);
+            }
+            for (const nodes of byTable.values()) {
+                const table = nodes[0].table;
+                const { outgoing, incoming } = await this.foreignKeysOf(table);
+                // Keys that lead to a hidden table are followed through it, below.
+                if (this.direction !== 'in') {
+                    for (const key of outgoing.filter((k) => !this.isHidden(k.to))) {
+                        next.push(...(await this.outgoing(key, nodes)));
+                    }
+                }
+                if (this.direction !== 'out') {
+                    for (const key of incoming.filter((k) => !this.isHidden(k.from))) {
+                        next.push(...(await this.incoming(key, nodes, 0)));
+                    }
+                }
+                if (this.hidden.size > 0) {
+                    for (const path of await this.pathsFrom(table)) {
+                        const forward = path.steps[0].forward;
+                        if ((forward && this.direction === 'in') || (!forward && this.direction === 'out'))
+                            continue;
+                        next.push(...(await this.through(path, nodes)));
+                    }
+                }
+            }
+            current = next;
+        }
+    }
+    /** Fetches the row each node's key points at. */
+    async outgoing(key, nodes) {
+        const wanted = new Map();
+        for (const node of nodes) {
+            const values = key.fromColumns.map((name) => node.row[name] ?? null);
+            // A null never points at anything.
+            if (values.some((value) => value === null))
+                continue;
+            const tuple = tupleKey(values);
+            const entry = wanted.get(tuple) ?? { values, nodes: [] };
+            entry.nodes.push(node);
+            wanted.set(tuple, entry);
+        }
+        const created = [];
+        for (const batch of chunksOf([...wanted.values()], BATCH)) {
+            const rows = await this.fetch(key.to, key.toColumns, batch.map((entry) => entry.values), this.limits.maxNodes);
+            for (const row of rows) {
+                const parents = wanted.get(tupleKey(key.toColumns.map((name) => row[name] ?? null)));
+                if (!parents)
+                    continue;
+                for (const parent of parents.nodes) {
+                    const { node, id, fresh } = await this.nodeFor(key.to, row, key.toColumns, parent.distance + 1);
+                    if (!node && !this.seen.has(id))
+                        continue;
+                    if (fresh && node)
+                        created.push(node);
+                    this.addEdge(key, parent.id, id);
+                }
+            }
+        }
+        return created;
+    }
+    /** Fetches the rows that point at each node through the key, a page of them for each. */
+    async incoming(key, nodes, skip) {
+        const wanted = new Map();
+        for (const node of nodes) {
+            const values = key.toColumns.map((name) => node.row[name] ?? null);
+            if (values.some((value) => value === null))
+                continue;
+            const tuple = tupleKey(values);
+            const entry = wanted.get(tuple) ?? { values, nodes: [] };
+            entry.nodes.push(node);
+            wanted.set(tuple, entry);
+        }
+        const fromColumns = await this.columnsOf(key.from);
+        const order = primaryKeyOf(fromColumns).map(quoteIdentifier).join(', ') || 'ctid';
+        const created = [];
+        const handled = new Map();
+        const totals = new Map();
+        for (const batch of chunksOf([...wanted.values()], BATCH)) {
+            const partition = key.fromColumns.map(quoteIdentifier).join(', ');
+            const { sql, params } = lookup(key.from, key.fromColumns, batch.map((entry) => entry.values), `, row_number() OVER (PARTITION BY ${partition} ORDER BY ${order}) AS "__rn",
+					count(*) OVER (PARTITION BY ${partition}) AS "__n"`);
+            const rows = await this.query(`SELECT * FROM (${sql}) AS found WHERE "__rn" > ${skip} AND "__rn" <= ${skip + this.limits.perKey}
+				ORDER BY "__rn"`, params);
+            for (const row of rows) {
+                const tuple = tupleKey(key.fromColumns.map((name) => row[name] ?? null));
+                const parents = wanted.get(tuple);
+                if (!parents)
+                    continue;
+                totals.set(tuple, Number(row.__n));
+                delete row.__rn;
+                delete row.__n;
+                for (const parent of parents.nodes) {
+                    const { node, id, fresh } = await this.nodeFor(key.from, row, key.fromColumns, parent.distance + 1);
+                    if (!node && !this.seen.has(id))
+                        continue;
+                    if (fresh && node)
+                        created.push(node);
+                    this.addEdge(key, id, parent.id);
+                    handled.set(tuple, (handled.get(tuple) ?? 0) + 1);
+                }
+            }
+        }
+        for (const [tuple, total] of totals) {
+            const shown = skip + (handled.get(tuple) ?? 0);
+            if (total <= shown)
+                continue;
+            for (const parent of wanted.get(tuple).nodes) {
+                this.more.push({
+                    node: parent.id,
+                    constraint: key.name,
+                    table: key.from,
+                    shown,
+                    count: Math.min(total, this.limits.countCap),
+                    capped: total > this.limits.countCap,
+                });
+            }
+        }
+        return created;
+    }
+    async query(sql, params) {
+        try {
+            const result = await this.session.run(sql, params, {
+                maxRows: this.limits.maxNodes * 2 + 1000,
+            });
+            return result.rows.map((cells) => {
+                const row = {};
+                result.columns.forEach((column, i) => (row[column.name] = cells[i] ?? null));
+                return row;
+            });
+        }
+        catch (error) {
+            if (error?.code === '57014') {
+                throw new GraphError(`took longer than ${this.limits.timeoutMs / 1000}s`);
+            }
+            throw error;
+        }
+    }
+    /** The rows of `table` whose `columns` have one of the value tuples. */
+    async fetch(table, columns, tuples, limit) {
+        const { sql, params } = lookup(table, columns, tuples);
+        return this.query(`${sql} LIMIT ${Math.max(Math.floor(limit), 1)}`, params);
+    }
+}
+/** `SELECT *, <extra> FROM t WHERE (a, b) IN (($1, $2), ...)`; the values are bound as text. */
+function lookup(table, columns, tuples, extra = '') {
+    const params = [];
+    const names = columns.map(quoteIdentifier);
+    const marks = tuples.map((tuple) => {
+        const group = tuple.map((value) => {
+            params.push(value ?? '');
+            return `$${params.length}`;
+        });
+        return columns.length === 1 ? group[0] : `(${group.join(', ')})`;
+    });
+    const left = columns.length === 1 ? names[0] : `(${names.join(', ')})`;
+    return {
+        sql: `SELECT *${extra} FROM ${qualified(table)} WHERE ${left} IN (${marks.join(', ')})`,
+        params,
+    };
+}
+const finish = (walk, moreStart) => ({
+    nodes: [...walk.nodes.values()],
+    edges: [...walk.edges.values()],
+    more: walk.more,
+    moreStart,
+    truncated: walk.truncated,
+});
+/** The rows the filters find, and the rows linked to them through foreign keys, `depth` steps out. */
+export async function buildGraph(session, request) {
+    const { table, limits } = request;
+    return withStatementTimeout(session, limits.timeoutMs, async () => {
+        // The rows the graph starts from are drawn even if their table is hidden.
+        const hide = (request.hide ?? []).filter((t) => tableLabel(t) !== tableLabel(table));
+        const walk = new Walk(session, limits, [], request.direction, hide, request.skipKeys);
+        const columns = await walk.columnsOf(table);
+        if (columns.length === 0)
+            throw new GraphError(`no table ${tableLabel(table)}`);
+        const primary = primaryKeyOf(columns);
+        const order = primary.map(quoteIdentifier).join(', ');
+        const wanted = Math.min(limits.maxStart, limits.maxNodes);
+        let from;
+        if (request.keys && request.keys.length > 0) {
+            if (primary.length === 0) {
+                throw new GraphError(`${tableLabel(table)} has no primary key to pick its rows by`);
+            }
+            if (request.keys.some((values) => values.length !== primary.length)) {
+                throw new GraphError(`each row is picked by ${primary.join(', ')}`);
+            }
+            from = lookup(table, primary, request.keys.map((values) => [...values]));
+        }
+        else {
+            const where = buildWhere(columns, request.filters);
+            from = { sql: `SELECT * FROM ${qualified(table)}${where.sql}`, params: where.params };
+        }
+        const rows = await walk.query(`${from.sql}${order ? ` ORDER BY ${order}` : ''} LIMIT ${wanted + 1}`, from.params);
+        const start = [];
+        for (const row of rows.slice(0, wanted)) {
+            const { node } = await walk.nodeFor(table, row, [], 0, true);
+            if (node)
+                start.push(node);
+        }
+        await walk.follow(start, request.depth);
+        return finish(walk, rows.length > wanted);
+    });
+}
+/**
+ * What is new when a node is opened: the rows linked to it, and the edges to them. The ids already
+ * drawn are left out of the result, but still count towards the node limit.
+ */
+export async function expandNode(session, request) {
+    const parsed = parseNodeId(request.node);
+    if (!parsed)
+        throw new GraphError('that node cannot be expanded');
+    const { table } = parsed;
+    const { limits } = request;
+    return withStatementTimeout(session, limits.timeoutMs, async () => {
+        const walk = new Walk(session, limits, request.drawn, request.direction, request.hide, request.skipKeys);
+        const columns = await walk.columnsOf(table);
+        const primary = primaryKeyOf(columns);
+        if (primary.length === 0 || primary.length !== parsed.key.length) {
+            throw new GraphError(`${tableLabel(table)} has no primary key, so its rows cannot be expanded`);
+        }
+        const [row] = await walk.fetch(table, primary, [parsed.key], 1);
+        if (!row)
+            throw new GraphError('that row is gone');
+        // The node itself is drawn already; it is only the place the walk starts from.
+        const self = {
+            id: request.node,
+            table,
+            key: Object.fromEntries(primary.map((name) => [name, row[name] ?? null])),
+            label: '',
+            row,
+            distance: request.distance,
+            start: false,
+            expandable: true,
+        };
+        if (request.key !== undefined) {
+            const { incoming } = await listForeignKeys(session, table);
+            const key = incoming.find((candidate) => candidate.name === request.key);
+            if (!key)
+                throw new GraphError(`no key "${request.key}" points at ${tableLabel(table)}`);
+            await walk.incoming(key, [self], request.skip);
+        }
+        else {
+            await walk.follow([self], request.depth);
+        }
+        return finish(walk, false);
+    });
+}
+const integer = (value, name, min, max, fallback) => {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
+        throw new GraphError(`${name} must be a whole number from ${min} to ${max}`);
+    }
+    return value;
+};
+const parseDirection = (value) => {
+    if (value === undefined || value === null)
+        return 'both';
+    if (value === 'out' || value === 'in' || value === 'both')
+        return value;
+    throw new GraphError('direction is out, in or both');
+};
+function parseLimits(body) {
+    const defaults = DEFAULT_GRAPH_LIMITS;
+    return {
+        maxStart: integer(body.maxStart, 'maxStart', 1, 200, defaults.maxStart),
+        maxNodes: integer(body.maxNodes, 'maxNodes', 1, 1000, defaults.maxNodes),
+        perKey: integer(body.perKey, 'perKey', 1, 100, defaults.perKey),
+        timeoutMs: defaults.timeoutMs,
+        countCap: defaults.countCap,
+    };
+}
+function parseSkipKeys(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) ||
+        value.length > 5000 ||
+        value.some((entry) => typeof entry !== 'string')) {
+        throw new GraphError('skipKeys is a list of foreign key ids');
+    }
+    return value;
+}
+function parseHide(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) ||
+        value.length > 500 ||
+        value.some((entry) => typeof entry?.schema !== 'string' ||
+            typeof entry.name !== 'string')) {
+        throw new GraphError('hide is a list of {"schema", "name"}');
+    }
+    return value.map(({ schema, name }) => ({ schema, name }));
+}
+/** Reads a request to start a graph; `filters` are parsed by the caller (`parseFilters`). */
+export function parseGraphRequest(body, filters) {
+    const entry = body;
+    if (typeof entry?.schema !== 'string' || typeof entry.table !== 'string') {
+        throw new GraphError('send {"schema", "table", "filters"?, "depth"?, "direction"?}');
+    }
+    const keys = entry.keys ?? [];
+    if (!Array.isArray(keys) ||
+        keys.length > 1000 ||
+        keys.some((values) => !Array.isArray(values) ||
+            values.length === 0 ||
+            values.some((value) => typeof value !== 'string'))) {
+        throw new GraphError('keys is a list of lists of primary key values');
+    }
+    return {
+        table: { schema: entry.schema, name: entry.table },
+        filters,
+        ...(keys.length > 0 ? { keys: keys } : {}),
+        depth: integer(entry.depth, 'depth', 0, MAX_GRAPH_DEPTH, 1),
+        direction: parseDirection(entry.direction),
+        limits: parseLimits(entry),
+        hide: parseHide(entry.hide),
+        skipKeys: parseSkipKeys(entry.skipKeys),
+    };
+}
+/** Reads a request to expand a node. */
+export function parseExpandRequest(body) {
+    const entry = body;
+    if (typeof entry?.node !== 'string') {
+        throw new GraphError('send {"node", "drawn"?, "depth"?, "direction"?, "key"?, "skip"?}');
+    }
+    const drawn = entry.drawn ?? [];
+    if (!Array.isArray(drawn) || drawn.some((id) => typeof id !== 'string')) {
+        throw new GraphError('drawn is a list of ids');
+    }
+    if (entry.key !== undefined && typeof entry.key !== 'string') {
+        throw new GraphError('key is the name of a foreign key');
+    }
+    return {
+        node: entry.node,
+        drawn: drawn,
+        depth: integer(entry.depth, 'depth', 1, MAX_GRAPH_DEPTH, 1),
+        direction: parseDirection(entry.direction),
+        distance: integer(entry.distance, 'distance', 0, 1000, 0),
+        ...(entry.key === undefined ? {} : { key: entry.key }),
+        skip: integer(entry.skip, 'skip', 0, 1_000_000, 0),
+        limits: parseLimits(entry),
+        hide: parseHide(entry.hide),
+        skipKeys: parseSkipKeys(entry.skipKeys),
+    };
+}