@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/environments.js

@@ -0,0 +1,140 @@
+// The environments a user can pick: those from the shared config file plus their local
+// connections, as one list. No Ink in here; screens reach it through Services.
+import { resolveEnvironment } from './config/resolve-environment.js';
+import { resolveValue, ResolveError } from './config/resolvers/index.js';
+import { refKinds, } from './config/schema.js';
+// A literal is shown as written; anything looked up elsewhere only by where it comes from.
+const display = (value) => {
+    if (typeof value !== 'object')
+        return String(value);
+    const kind = refKinds.find((k) => k in value);
+    return `‹${kind ?? '?'}›`;
+};
+export const sharedKey = (name) => `shared:${name}`;
+export const localKey = (id) => `local:${id}`;
+/** The red mark beside an environment's name, if it has one. */
+export const badgeOf = (entry) => entry.protected ? 'PROTECTED' : undefined;
+/** The colour a tier is shown in, so the riskier ones stand out. */
+export const tierColor = {
+    production: 'red',
+    reference: 'yellow',
+    demo: 'magenta',
+    development: 'green',
+    local: 'gray',
+};
+/** Marks a protected environment. */
+export const shield = '⛨';
+export const addressOf = (entry) => `${entry.user}@${entry.host}:${entry.port}/${entry.database}`;
+/** Shared environments by name, then local connections by name. May throw if the store fails. */
+export function listEnvironments(services) {
+    const shared = (services.config?.environments ?? []).map((config) => ({
+        key: sharedKey(config.name),
+        source: 'shared',
+        name: config.name,
+        tier: config.tier,
+        protected: config.protected,
+        readOnly: config.readOnly,
+        seeder: config.seeder,
+        designer: config.designer,
+        tlsMode: config.tls.mode,
+        user: display(config.username),
+        host: display(config.host),
+        port: display(config.port),
+        database: display(config.database),
+        config,
+    }));
+    const local = services.store.list().map((connection) => ({
+        key: localKey(connection.id),
+        source: 'local',
+        name: connection.name,
+        // Local connections are the user's own, so they never get production guards.
+        tier: 'local',
+        protected: false,
+        readOnly: false,
+        seeder: true,
+        designer: true,
+        tlsMode: connection.ssl ? 'require' : 'disable',
+        user: connection.username,
+        host: connection.host,
+        port: String(connection.port),
+        database: connection.database,
+        connection,
+    }));
+    return [...shared, ...local];
+}
+/** Looks up and validates everything needed to connect; may prompt, and may throw a ResolveError. */
+export async function resolveEntry(entry, services, 
+// `interactive: false` fails instead of asking, unless the answer is already known.
+options = {}) {
+    const { config, connection } = entry;
+    if (config) {
+        if (!services.config)
+            throw new Error('No shared config is loaded');
+        return resolveEnvironment(config, {
+            interactive: options.interactive ?? true,
+            registry: services.resolvers,
+            signal: options.signal,
+        });
+    }
+    if (!connection)
+        throw new Error(`Environment ${entry.name} has no connection details`);
+    return {
+        name: connection.name,
+        tier: 'local',
+        protected: false,
+        readOnly: false,
+        host: connection.host,
+        port: connection.port,
+        database: connection.database,
+        username: connection.username,
+        password: connection.password,
+        schema: connection.schema,
+        tls: { mode: connection.ssl ? 'require' : 'disable' },
+    };
+}
+/**
+ * The environment a command names: a shared one of that name, else a local connection of that name
+ * in any letter case. A shared environment wins when both have it.
+ */
+export function findEnvironment(services, name) {
+    const entries = listEnvironments(services);
+    return (entries.find((entry) => entry.source === 'shared' && entry.name === name) ??
+        entries.find((entry) => entry.source === 'local' && entry.name.toLowerCase() === name.toLowerCase()));
+}
+/** Drops the answers typed for an environment, so the next attempt asks again (after a wrong password, say). */
+export function forgetAnswers(entry, services) {
+    services.resolvers.get('prompt')?.forget(entry.name);
+}
+const vaultValues = (config) => [
+    ['host', config.host],
+    ['port', config.port],
+    ['database', config.database],
+    ['schema', config.schema],
+    ['username', config.username],
+    ['password', config.password],
+    ['tls.ca', config.tls.ca],
+    ['tls.cert', config.tls.cert],
+    ['tls.key', config.tls.key],
+    ['tls.keyPassphrase', config.tls.keyPassphrase],
+].filter((pair) => typeof pair[1] === 'object' && 'vault' in pair[1]);
+/**
+ * Whether Vault lets this user read the secrets an environment refers to. Only `source: vault` values
+ * are read (a read changes nothing in Vault); issuing credentials or a certificate is left to the
+ * moment of connecting. Any other failure, such as Vault being unreachable, is not a refusal and
+ * counts as readable: connecting reports it.
+ */
+export async function credentialsReadable(entry, services, signal) {
+    const { config } = entry;
+    if (!config || !services.config)
+        return true;
+    for (const [field, value] of vaultValues(config)) {
+        try {
+            await resolveValue(value, { envName: config.name, field, configDir: config.dir, interactive: false, signal }, services.resolvers);
+        }
+        catch (error) {
+            if (error instanceof ResolveError && error.denied)
+                return false;
+        }
+    }
+    return true;
+}

package/dist/explorer/alter.js

@@ -0,0 +1,493 @@
+// Turns the difference between a table as it is and as it was edited into ALTER statements. Pure:
+// rows of the two designs are matched by id, so a renamed column is a RENAME and not a drop and an
+// add. Each statement carries what the page needs to warn about it and to offer a safer way.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { columnSql, constraintSql, DdlError, indexSql, literal, suggestConstraintName, typeSql, } from './ddl.js';
+export class AlterError extends DdlError {
+}
+/** A table with more rows than this gets a warning where a statement has to read all of them. */
+export const BIG_TABLE_ROWS = 10_000;
+const same = (a, b) => (a ?? '').trim() === (b ?? '').trim();
+function rowId(kind, row) {
+    const id = row.id ?? (row.name ? `name:${row.name}` : undefined);
+    if (id === undefined)
+        throw new AlterError(`A ${kind} has neither an id nor a name`);
+    return id;
+}
+const rows = (estimate) => estimate === null || estimate === undefined
+    ? 'a table never analyzed, so of unknown size'
+    : `about ${estimate.toLocaleString('en-US')} rows`;
+const big = (estimate) => estimate === null || estimate === undefined || estimate >= BIG_TABLE_ROWS;
+const qualified = (table) => `${quoteIdentifier(table.schema)}.${quoteIdentifier(table.name)}`;
+/** Whether changing a column from one type to the other has to rewrite every row. */
+export function rewritesTable(from, to) {
+    if (typeSql(from) === typeSql(to))
+        return false;
+    if (from.schema !== undefined || to.schema !== undefined)
+        return true;
+    if ((from.array ?? 0) !== (to.array ?? 0))
+        return true;
+    // A longer or no limit on varchar, and varchar to text, leave the stored values as they are.
+    if (from.name === 'varchar' && to.name === 'text')
+        return false;
+    if (from.name === 'varchar' && to.name === 'varchar') {
+        return to.length !== undefined && (from.length === undefined || to.length < from.length);
+    }
+    if (from.name === 'numeric' && to.name === 'numeric') {
+        const wider = from.precision !== undefined &&
+            (to.precision === undefined ||
+                (to.precision >= from.precision && (to.scale ?? 0) === (from.scale ?? 0)));
+        return !wider && !(from.precision === undefined && to.precision === undefined);
+    }
+    return true;
+}
+function resolve(design) {
+    const columns = new Map();
+    const names = new Map();
+    for (const column of design.columns) {
+        const id = rowId('column', column);
+        if (columns.has(id))
+            throw new AlterError(`Two columns share the id "${id}"`);
+        columns.set(id, column);
+        names.set(column.name, id);
+    }
+    return { columns, names };
+}
+/** A constraint's meaning with columns as ids, so a rename of a column does not change it. */
+function constraintShape(design, resolved, constraint) {
+    const ids = (columns) => columns.map((name) => resolved.names.get(name) ?? name);
+    switch (constraint.kind) {
+        case 'primary':
+            return { kind: 'primary', columns: ids(constraint.columns) };
+        case 'unique':
+            return {
+                kind: 'unique',
+                columns: ids(constraint.columns),
+                nulls: !!constraint.nullsNotDistinct,
+            };
+        case 'check':
+            return { kind: 'check', expression: constraint.expression.trim() };
+        case 'foreign': {
+            const target = constraint.references;
+            const self = target.schema === design.schema && target.table === design.name;
+            return {
+                kind: 'foreign',
+                columns: ids(constraint.columns),
+                target: self ? 'self' : `${target.schema}.${target.table}`,
+                targetColumns: self ? ids(target.columns) : target.columns,
+                onDelete: constraint.onDelete ?? 'no action',
+                onUpdate: constraint.onUpdate ?? 'no action',
+                full: !!constraint.matchFull,
+                deferrable: !!constraint.deferrable,
+                deferred: !!constraint.initiallyDeferred,
+            };
+        }
+    }
+}
+function indexShape(resolved, index) {
+    return {
+        unique: !!index.unique,
+        method: index.method ?? 'btree',
+        items: index.items.map((item) => [
+            'column' in item ? (resolved.names.get(item.column) ?? item.column) : item.expression.trim(),
+            'column' in item,
+            !!item.descending,
+        ]),
+        include: (index.include ?? []).map((name) => resolved.names.get(name) ?? name),
+        where: (index.where ?? '').trim(),
+    };
+}
+const shapeKey = (shape) => JSON.stringify(shape);
+function checkUnique(what, ids) {
+    if (new Set(ids).size !== ids.length)
+        throw new AlterError(`Two ${what}s share an id`);
+}
+/**
+ * The statements that change `before` into `after`, in an order that works: what goes first, then
+ * columns, constraints and indexes, then the table itself (so every statement but the last names the
+ * table as it is now). The first statement sets `lock_timeout`; the caller adds it.
+ */
+export function diffDesigns(before, after, options = {}) {
+    const old = resolve(before);
+    const next = resolve(after);
+    if (!after.schema)
+        throw new AlterError('The table needs a schema');
+    if (!after.name)
+        throw new AlterError('The table needs a name');
+    if (after.columns.length === 0)
+        throw new AlterError('The table needs a column');
+    for (const column of after.columns) {
+        if (!column.name)
+            throw new AlterError('A column needs a name');
+    }
+    const partitionId = (design, resolved) => design.partition ? resolved.names.get(design.partition.column) : undefined;
+    if (before.partition?.method !== after.partition?.method ||
+        partitionId(before, old) !== partitionId(after, next)) {
+        throw new AlterError('How a table is partitioned cannot be changed: make a new table');
+    }
+    const serverMajor = options.serverMajor ?? 99;
+    const table = qualified(before);
+    const estimate = options.estimatedRows;
+    const out = [];
+    const chosen = (list, key) => !!list?.includes(key);
+    const add = (statement) => out.push({ warnings: [], offers: [], ...statement });
+    const afterConstraints = (after.constraints ?? []).map((c) => ({
+        row: c,
+        id: rowId('constraint', c),
+    }));
+    const beforeConstraints = (before.constraints ?? []).map((c) => ({
+        row: c,
+        id: rowId('constraint', c),
+    }));
+    const afterIndexes = (after.indexes ?? []).map((i) => ({ row: i, id: rowId('index', i) }));
+    const beforeIndexes = (before.indexes ?? []).map((i) => ({ row: i, id: rowId('index', i) }));
+    checkUnique('constraint', afterConstraints.map((c) => c.id));
+    checkUnique('index', afterIndexes.map((i) => i.id));
+    // --- What changed, constraints and indexes
+    const dropConstraints = [];
+    const addConstraints = [];
+    const renameConstraints = [];
+    for (const was of beforeConstraints) {
+        const is = afterConstraints.find((c) => c.id === was.id);
+        if (!is) {
+            dropConstraints.push(was);
+            continue;
+        }
+        const wasShape = shapeKey(constraintShape(before, old, was.row));
+        const isShape = shapeKey(constraintShape(after, next, is.row));
+        if (wasShape !== isShape) {
+            dropConstraints.push(was);
+            addConstraints.push(is);
+        }
+        else if (is.row.name && was.row.name !== is.row.name) {
+            renameConstraints.push({ from: was.row.name ?? '', to: is.row.name, id: was.id });
+        }
+    }
+    for (const is of afterConstraints) {
+        if (!beforeConstraints.some((c) => c.id === is.id))
+            addConstraints.push(is);
+    }
+    const dropIndexes = [];
+    const addIndexes = [];
+    const renameIndexes = [];
+    for (const was of beforeIndexes) {
+        const is = afterIndexes.find((i) => i.id === was.id);
+        if (!is) {
+            dropIndexes.push(was);
+            continue;
+        }
+        if (shapeKey(indexShape(old, was.row)) !== shapeKey(indexShape(next, is.row))) {
+            dropIndexes.push(was);
+            addIndexes.push(is);
+        }
+        else if (is.row.name && was.row.name !== is.row.name) {
+            renameIndexes.push({ from: was.row.name ?? '', to: is.row.name, id: was.id });
+        }
+    }
+    for (const is of afterIndexes) {
+        if (!beforeIndexes.some((i) => i.id === is.id))
+            addIndexes.push(is);
+    }
+    // --- 1. Drop constraints and indexes that go or change
+    for (const { row, id } of dropConstraints) {
+        if (!row.name)
+            throw new AlterError('A constraint to drop has no name');
+        const key = `drop-constraint:${id}`;
+        add({
+            key,
+            sql: `ALTER TABLE ${table} DROP CONSTRAINT ${quoteIdentifier(row.name)}${chosen(options.cascade, key) ? ' CASCADE' : ''}`,
+            drop: { kind: 'constraint', schema: before.schema, name: before.name, detail: row.name },
+            offers: ['cascade'],
+        });
+    }
+    for (const { row, id } of dropIndexes) {
+        if (!row.name)
+            throw new AlterError('An index to drop has no name');
+        const key = `drop-index:${id}`;
+        add({
+            key,
+            sql: `DROP INDEX ${quoteIdentifier(before.schema)}.${quoteIdentifier(row.name)}${chosen(options.cascade, key) ? ' CASCADE' : ''}`,
+            drop: { kind: 'index', schema: before.schema, name: row.name },
+            offers: ['cascade'],
+        });
+    }
+    // --- 2. Drop columns
+    for (const [id, column] of old.columns) {
+        if (next.columns.has(id))
+            continue;
+        const key = `drop-column:${id}`;
+        add({
+            key,
+            sql: `ALTER TABLE ${table} DROP COLUMN ${quoteIdentifier(column.name)}${chosen(options.cascade, key) ? ' CASCADE' : ''}`,
+            drop: { kind: 'column', schema: before.schema, name: before.name, detail: column.name },
+            offers: ['cascade'],
+        });
+    }
+    // --- 3. Rename columns
+    for (const [id, column] of old.columns) {
+        const edited = next.columns.get(id);
+        if (edited && edited.name !== column.name) {
+            add({
+                key: `rename-column:${id}`,
+                sql: `ALTER TABLE ${table} RENAME COLUMN ${quoteIdentifier(column.name)} TO ${quoteIdentifier(edited.name)}`,
+            });
+        }
+    }
+    // --- 4. Add columns
+    const tableBefore = { schema: before.schema, name: before.name };
+    for (const [id, column] of next.columns) {
+        if (old.columns.has(id))
+            continue;
+        const warnings = [];
+        if (column.notNull &&
+            !column.default &&
+            !column.identity &&
+            !column.generated &&
+            big(estimate)) {
+            warnings.push(`NOT NULL without a default fails if the table has any rows (${rows(estimate)}).`);
+        }
+        if ((column.default || column.generated || column.identity) && big(estimate)) {
+            warnings.push(`A default that is not constant, or a generated column, rewrites the table (${rows(estimate)}) while it holds a lock.`);
+        }
+        add({
+            key: `add-column:${id}`,
+            sql: `ALTER TABLE ${table} ADD COLUMN ${columnSql(column)}`,
+            warnings,
+        });
+    }
+    // --- 5. Change columns that stay
+    for (const [id, was] of old.columns) {
+        const is = next.columns.get(id);
+        if (!is)
+            continue;
+        const column = `ALTER TABLE ${table} ALTER COLUMN ${quoteIdentifier(is.name)}`;
+        const wasGenerated = was.generated !== undefined;
+        const isGenerated = is.generated !== undefined;
+        if (!wasGenerated && isGenerated) {
+            throw new AlterError(`"${is.name}" cannot become a generated column in place: add a new column and drop this one`);
+        }
+        if (was.identity && !is.identity) {
+            add({ key: `identity:${id}`, sql: `${column} DROP IDENTITY` });
+        }
+        if (wasGenerated && !isGenerated) {
+            add({ key: `generated:${id}`, sql: `${column} DROP EXPRESSION` });
+        }
+        else if (wasGenerated && isGenerated && !same(was.generated, is.generated)) {
+            if (serverMajor < 17) {
+                throw new AlterError(`Changing the expression of "${is.name}" needs PostgreSQL 17 or later`);
+            }
+            add({
+                key: `generated:${id}`,
+                sql: `${column} SET EXPRESSION AS (${is.generated.trim()})`,
+                warnings: big(estimate) ? [`Recomputes every row (${rows(estimate)}).`] : [],
+            });
+        }
+        if (typeSql(was.type) !== typeSql(is.type)) {
+            const using = options.using?.[id]?.trim();
+            add({
+                key: `type:${id}`,
+                sql: `${column} TYPE ${typeSql(is.type)}${using ? ` USING ${using}` : ''}`,
+                warnings: rewritesTable(was.type, is.type)
+                    ? [
+                        `Changing the type rewrites the table (${rows(estimate)}), holding a lock that blocks reads and writes meanwhile.`,
+                    ]
+                    : [],
+                offers: ['using'],
+            });
+        }
+        if (!isGenerated && !is.identity && !same(was.default, is.default)) {
+            add({
+                key: `default:${id}`,
+                sql: is.default?.trim()
+                    ? `${column} SET DEFAULT ${is.default.trim()}`
+                    : `${column} DROP DEFAULT`,
+            });
+        }
+        if (!!was.notNull !== !!is.notNull) {
+            add({
+                key: `not-null:${id}`,
+                sql: `${column} ${is.notNull ? 'SET' : 'DROP'} NOT NULL`,
+                warnings: is.notNull && big(estimate)
+                    ? [`Checks every row for nulls (${rows(estimate)}) while holding a lock.`]
+                    : [],
+            });
+        }
+        if (is.identity && was.identity !== is.identity) {
+            const kind = is.identity === 'always' ? 'ALWAYS' : 'BY DEFAULT';
+            add({
+                key: `identity:${id}`,
+                sql: was.identity
+                    ? `${column} SET GENERATED ${kind}`
+                    : `${column} ADD GENERATED ${kind} AS IDENTITY`,
+            });
+        }
+    }
+    // --- 6. Rename constraints and indexes that otherwise stay
+    for (const { from, to, id } of renameConstraints) {
+        add({
+            key: `rename-constraint:${id}`,
+            sql: `ALTER TABLE ${table} RENAME CONSTRAINT ${quoteIdentifier(from)} TO ${quoteIdentifier(to)}`,
+        });
+    }
+    for (const { from, to, id } of renameIndexes) {
+        add({
+            key: `rename-index:${id}`,
+            sql: `ALTER INDEX ${quoteIdentifier(before.schema)}.${quoteIdentifier(from)} RENAME TO ${quoteIdentifier(to)}`,
+        });
+    }
+    // --- 7. Add constraints
+    const stub = { ...after, ...tableBefore };
+    const columnNames = new Set(after.columns.map((column) => column.name));
+    for (const { row, id } of addConstraints) {
+        const key = `add-constraint:${id}`;
+        const checked = row.kind === 'foreign' || row.kind === 'check';
+        const notValid = checked && chosen(options.notValid, key);
+        // The table is renamed last, so a key to itself still names the table as it is now.
+        const aimed = row.kind === 'foreign' &&
+            row.references.schema === after.schema &&
+            row.references.table === after.name
+            ? {
+                ...row,
+                references: {
+                    ...row.references,
+                    ...tableBefore,
+                    table: before.name,
+                    schema: before.schema,
+                },
+            }
+            : row;
+        const name = notValid ? (row.name ?? suggestConstraintName(before.name, row)) : row.name;
+        const withName = name === undefined ? aimed : { ...aimed, name };
+        const sql = `ALTER TABLE ${table} ADD ${constraintSql(withName, { serverMajor: options.serverMajor }, columnNames)}${notValid ? ' NOT VALID' : ''}`;
+        const warnings = [];
+        const offers = [];
+        if (checked) {
+            if (big(estimate) && !notValid) {
+                warnings.push(`Checks every existing row (${rows(estimate)}) while holding a lock: it can be added NOT VALID and validated afterwards.`);
+            }
+            offers.push('notValid');
+        }
+        else if (big(estimate)) {
+            warnings.push(`Builds an index over the table (${rows(estimate)}), blocking writes meanwhile.`);
+        }
+        add({ key, sql, warnings, offers });
+        if (notValid) {
+            add({
+                key: `${key}:validate`,
+                sql: `ALTER TABLE ${table} VALIDATE CONSTRAINT ${quoteIdentifier(name)}`,
+            });
+        }
+    }
+    // --- 8. Create indexes
+    for (const { row, id } of addIndexes) {
+        const key = `add-index:${id}`;
+        const concurrent = !after.partition && chosen(options.concurrently, key);
+        let sql = indexSql(stub, row, columnNames);
+        if (concurrent)
+            sql = sql.replace(/^CREATE (UNIQUE )?INDEX /, 'CREATE $1INDEX CONCURRENTLY ');
+        add({
+            key,
+            sql,
+            concurrent,
+            warnings: big(estimate) && !concurrent
+                ? [`Builds an index over the table (${rows(estimate)}), blocking writes meanwhile.`]
+                : [],
+            offers: after.partition ? [] : ['concurrently'],
+        });
+    }
+    // --- 9. Comments
+    const comment = (target, text) => `COMMENT ON ${target} IS ${text ? literal(text) : 'NULL'}`;
+    if (!same(before.comment, after.comment)) {
+        add({ key: 'comment:table', sql: comment(`TABLE ${table}`, after.comment) });
+    }
+    for (const [id, is] of next.columns) {
+        const was = old.columns.get(id);
+        if (!same(was?.comment, is.comment)) {
+            add({
+                key: `comment:${id}`,
+                sql: comment(`COLUMN ${table}.${quoteIdentifier(is.name)}`, is.comment),
+            });
+        }
+    }
+    // --- 10. The table itself
+    if (!!before.unlogged !== !!after.unlogged) {
+        add({
+            key: 'logged',
+            sql: `ALTER TABLE ${table} SET ${after.unlogged ? 'UNLOGGED' : 'LOGGED'}`,
+            warnings: [`Rewrites the table (${rows(estimate)}) while holding a lock.`],
+        });
+    }
+    let current = { ...tableBefore };
+    if (after.schema !== before.schema) {
+        add({
+            key: 'schema',
+            sql: `ALTER TABLE ${qualified(current)} SET SCHEMA ${quoteIdentifier(after.schema)}`,
+            warnings: ['Code and views that name the table by its old schema stop finding it.'],
+        });
+        current = { schema: after.schema, name: current.name };
+    }
+    if (after.name !== before.name) {
+        add({
+            key: 'rename',
+            sql: `ALTER TABLE ${qualified(current)} RENAME TO ${quoteIdentifier(after.name)}`,
+            warnings: ['Code and views that use the old name stop finding the table.'],
+        });
+    }
+    return out;
+}
+/** `DROP TABLE`, as a statement of its own. */
+export function dropTableStatement(table, cascade) {
+    return {
+        key: 'drop-table',
+        sql: `DROP TABLE ${qualified(table)}${cascade ? ' CASCADE' : ''}`,
+        drop: { kind: 'table', schema: table.schema, name: table.name },
+        warnings: [],
+        offers: ['cascade'],
+    };
+}
+/** The statements that run in the transaction, with `lock_timeout` first, and those that run apart. */
+export function splitPlan(statements, lockTimeoutMs) {
+    if (!Number.isInteger(lockTimeoutMs) || lockTimeoutMs < 0) {
+        throw new AlterError('The lock timeout is a number of milliseconds');
+    }
+    const transactional = statements.filter((statement) => !statement.concurrent).map((s) => s.sql);
+    return {
+        transactional: transactional.length > 0
+            ? [`SET LOCAL lock_timeout = '${lockTimeoutMs}ms'`, ...transactional]
+            : [],
+        concurrent: statements.filter((statement) => statement.concurrent).map((s) => s.sql),
+    };
+}
+const stringList = (value, what) => {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new AlterError(`${what} must be a list of text`);
+    }
+    return value;
+};
+/** Reads the options sent with an edit, refusing anything that is not what they should be. */
+export function parseAlterOptions(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new AlterError('options must be an object');
+    const raw = value;
+    const using = {};
+    if (raw.using !== undefined && raw.using !== null) {
+        if (typeof raw.using !== 'object' || Array.isArray(raw.using)) {
+            throw new AlterError('using must be an object');
+        }
+        for (const [id, text] of Object.entries(raw.using)) {
+            if (typeof text !== 'string')
+                throw new AlterError('A USING expression must be text');
+            using[id] = text;
+        }
+    }
+    return {
+        using,
+        notValid: stringList(raw.notValid, 'notValid'),
+        concurrently: stringList(raw.concurrently, 'concurrently'),
+        cascade: stringList(raw.cascade, 'cascade'),
+    };
+}