@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/explorer/ddl.js

@@ -0,0 +1,502 @@
+// Turns the design of a table into the statements that create it. Pure: nothing here talks to a
+// database. Every identifier is quoted; expressions (defaults, checks, index predicates) are SQL the
+// designer typed, and are shown to them before anything runs.
+import { quoteIdentifier } from '../db/identifiers.js';
+export class DdlError extends Error {
+}
+export const BUILTIN_TYPES = [
+    { name: 'smallint' },
+    { name: 'integer' },
+    { name: 'bigint' },
+    { name: 'numeric', sized: 'numeric' },
+    { name: 'real' },
+    { name: 'double precision' },
+    { name: 'money' },
+    { name: 'boolean' },
+    { name: 'text' },
+    { name: 'varchar', sized: 'length' },
+    { name: 'char', sized: 'length' },
+    { name: 'citext' },
+    { name: 'bytea' },
+    { name: 'uuid' },
+    { name: 'date' },
+    { name: 'time', sized: 'precision' },
+    { name: 'timetz', sized: 'precision' },
+    { name: 'timestamp', sized: 'precision' },
+    { name: 'timestamptz', sized: 'precision' },
+    { name: 'interval', sized: 'precision' },
+    { name: 'json' },
+    { name: 'jsonb' },
+    { name: 'xml' },
+    { name: 'inet' },
+    { name: 'cidr' },
+    { name: 'macaddr' },
+    { name: 'bit', sized: 'length' },
+    { name: 'varbit', sized: 'length' },
+    { name: 'tsvector' },
+    { name: 'tsquery' },
+    { name: 'point' },
+    { name: 'int4range' },
+    { name: 'int8range' },
+    { name: 'numrange' },
+    { name: 'daterange' },
+    { name: 'tsrange' },
+    { name: 'tstzrange' },
+];
+/** Defaults the form offers besides a free expression. */
+export const DEFAULT_PRESETS = [
+    'now()',
+    'current_timestamp',
+    'current_date',
+    'gen_random_uuid()',
+    'true',
+    'false',
+    "''",
+    '0',
+    "'{}'::jsonb",
+    "'[]'::jsonb",
+];
+export const literal = (text) => {
+    if (text.includes('\0'))
+        throw new DdlError('Text cannot hold a null character');
+    return `'${text.replaceAll("'", "''")}'`;
+};
+const quoteAll = (names) => names.map((name) => quoteIdentifier(name)).join(', ');
+export const expression = (sql, what) => {
+    const trimmed = sql.trim();
+    if (!trimmed)
+        throw new DdlError(`${what} is empty`);
+    return trimmed;
+};
+function integer(value, what, min) {
+    if (!Number.isInteger(value) || value < min)
+        throw new DdlError(`${what} must be a whole number`);
+    return value;
+}
+/** A type as written in SQL: `varchar(20)`, `numeric(10, 2)`, `"app"."mood"[]`. */
+export function typeSql(type) {
+    let sql;
+    if (type.schema !== undefined) {
+        sql = `${quoteIdentifier(type.schema)}.${quoteIdentifier(type.name)}`;
+    }
+    else {
+        const builtin = BUILTIN_TYPES.find((candidate) => candidate.name === type.name);
+        if (!builtin)
+            throw new DdlError(`Unknown type "${type.name}"`);
+        sql = builtin.name;
+        if (builtin.sized === 'length' && type.length !== undefined) {
+            sql += `(${integer(type.length, 'A length', 1)})`;
+        }
+        else if (builtin.sized === 'precision' && type.length !== undefined) {
+            sql += `(${integer(type.length, 'A precision', 0)})`;
+        }
+        else if (builtin.sized === 'numeric' && type.precision !== undefined) {
+            const precision = integer(type.precision, 'A precision', 1);
+            sql +=
+                type.scale === undefined
+                    ? `(${precision})`
+                    : `(${precision}, ${integer(type.scale, 'A scale', 0)})`;
+        }
+    }
+    return sql + '[]'.repeat(type.array ? integer(type.array, 'Array dimensions', 0) : 0);
+}
+const POSTGRES_NAME_LIMIT = 63;
+const clip = (name, suffix) => name.length + suffix.length <= POSTGRES_NAME_LIMIT
+    ? name + suffix
+    : name.slice(0, POSTGRES_NAME_LIMIT - suffix.length) + suffix;
+/** The name Postgres would give a constraint: `orders_customer_id_fkey`. */
+export function suggestConstraintName(table, constraint) {
+    switch (constraint.kind) {
+        case 'primary':
+            return clip(table, '_pkey');
+        case 'unique':
+            return clip(`${table}_${constraint.columns.join('_')}`, '_key');
+        case 'foreign':
+            return clip(`${table}_${constraint.columns.join('_')}`, '_fkey');
+        case 'check':
+            return clip(table, '_check');
+    }
+}
+/** The name Postgres would give an index: `orders_customer_id_idx`. */
+export function suggestIndexName(table, index) {
+    const names = index.items.map((item) => ('column' in item ? item.column : 'expr'));
+    return clip(`${table}_${names.join('_')}`, '_idx');
+}
+function checkNames(what, names) {
+    const seen = new Set();
+    for (const name of names) {
+        if (name === undefined)
+            continue;
+        if (!name)
+            throw new DdlError(`A ${what} name is empty`);
+        if (seen.has(name))
+            throw new DdlError(`Two ${what}s are named "${name}"`);
+        seen.add(name);
+    }
+}
+export function columnSql(column) {
+    const parts = [quoteIdentifier(column.name), typeSql(column.type)];
+    const defaultSql = column.default?.trim();
+    if (column.generated !== undefined) {
+        if (defaultSql || column.identity) {
+            throw new DdlError(`Column "${column.name}" is generated, so has no default or identity`);
+        }
+        parts.push(`GENERATED ALWAYS AS (${expression(column.generated, 'A generated expression')}) STORED`);
+    }
+    else if (column.identity) {
+        if (defaultSql) {
+            throw new DdlError(`Column "${column.name}" is an identity, so has no default`);
+        }
+        parts.push(`GENERATED ${column.identity === 'always' ? 'ALWAYS' : 'BY DEFAULT'} AS IDENTITY`);
+    }
+    else if (defaultSql) {
+        parts.push(`DEFAULT ${defaultSql}`);
+    }
+    if (column.notNull)
+        parts.push('NOT NULL');
+    return parts.join(' ');
+}
+export function constraintSql(constraint, options, columns) {
+    const own = (names) => {
+        if (names.length === 0)
+            throw new DdlError(`A ${constraint.kind} constraint needs a column`);
+        for (const name of names) {
+            if (!columns.has(name))
+                throw new DdlError(`There is no column "${name}" to constrain`);
+        }
+        if (new Set(names).size !== names.length) {
+            throw new DdlError(`A ${constraint.kind} constraint lists a column twice`);
+        }
+    };
+    const named = constraint.name === undefined ? '' : `CONSTRAINT ${quoteIdentifier(constraint.name)} `;
+    switch (constraint.kind) {
+        case 'primary':
+            own(constraint.columns);
+            return `${named}PRIMARY KEY (${quoteAll(constraint.columns)})`;
+        case 'unique': {
+            own(constraint.columns);
+            if (constraint.nullsNotDistinct && (options.serverMajor ?? 15) < 15) {
+                throw new DdlError('NULLS NOT DISTINCT needs PostgreSQL 15 or later');
+            }
+            const nulls = constraint.nullsNotDistinct ? ' NULLS NOT DISTINCT' : '';
+            return `${named}UNIQUE${nulls} (${quoteAll(constraint.columns)})`;
+        }
+        case 'check':
+            return `${named}CHECK (${expression(constraint.expression, 'A check')})`;
+        case 'foreign': {
+            own(constraint.columns);
+            const target = constraint.references;
+            if (target.columns.length !== constraint.columns.length) {
+                throw new DdlError('A foreign key needs as many referenced columns as columns');
+            }
+            let sql = `${named}FOREIGN KEY (${quoteAll(constraint.columns)}) REFERENCES `;
+            sql += `${quoteIdentifier(target.schema)}.${quoteIdentifier(target.table)} (${quoteAll(target.columns)})`;
+            if (constraint.matchFull)
+                sql += ' MATCH FULL';
+            if (constraint.onDelete)
+                sql += ` ON DELETE ${constraint.onDelete.toUpperCase()}`;
+            if (constraint.onUpdate)
+                sql += ` ON UPDATE ${constraint.onUpdate.toUpperCase()}`;
+            if (constraint.initiallyDeferred && !constraint.deferrable) {
+                throw new DdlError('A foreign key can only start deferred if it is deferrable');
+            }
+            if (constraint.deferrable) {
+                sql += ' DEFERRABLE' + (constraint.initiallyDeferred ? ' INITIALLY DEFERRED' : '');
+            }
+            return sql;
+        }
+    }
+}
+export function indexSql(table, index, columns) {
+    const method = index.method ?? 'btree';
+    if (index.items.length === 0)
+        throw new DdlError('An index needs a column or an expression');
+    if (index.unique && method !== 'btree') {
+        throw new DdlError(`A ${method} index cannot be unique`);
+    }
+    if (index.include?.length && method !== 'btree' && method !== 'gist') {
+        throw new DdlError(`A ${method} index cannot have INCLUDE columns`);
+    }
+    const items = index.items.map((item) => {
+        let sql;
+        if ('column' in item) {
+            if (!columns.has(item.column))
+                throw new DdlError(`There is no column "${item.column}" to index`);
+            sql = quoteIdentifier(item.column);
+        }
+        else {
+            sql = `(${expression(item.expression, 'An index expression')})`;
+        }
+        return item.descending ? `${sql} DESC` : sql;
+    });
+    for (const name of index.include ?? []) {
+        if (!columns.has(name))
+            throw new DdlError(`There is no column "${name}" to include`);
+    }
+    let sql = `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX `;
+    if (index.name !== undefined)
+        sql += `${quoteIdentifier(index.name)} `;
+    sql += `ON ${quoteIdentifier(table.schema)}.${quoteIdentifier(table.name)}`;
+    sql += ` USING ${method} (${items.join(', ')})`;
+    if (index.include?.length)
+        sql += ` INCLUDE (${quoteAll(index.include)})`;
+    if (index.where?.trim())
+        sql += ` WHERE ${index.where.trim()}`;
+    return sql;
+}
+function build(table, options, 
+// Tables of the same design that come later, whose foreign keys cannot be inline yet.
+later) {
+    if (!table.schema)
+        throw new DdlError('The table needs a schema');
+    if (!table.name)
+        throw new DdlError('The table needs a name');
+    if (table.columns.length === 0)
+        throw new DdlError('The table needs a column');
+    checkNames('column', table.columns.map((column) => column.name));
+    for (const column of table.columns) {
+        if (!column.name)
+            throw new DdlError('A column needs a name');
+    }
+    const columns = new Set(table.columns.map((column) => column.name));
+    const constraints = table.constraints ?? [];
+    checkNames('constraint', constraints.map((constraint) => constraint.name));
+    checkNames('index', (table.indexes ?? []).map((index) => index.name));
+    if (constraints.filter((constraint) => constraint.kind === 'primary').length > 1) {
+        throw new DdlError('A table has only one primary key');
+    }
+    if (table.partition) {
+        if (table.unlogged)
+            throw new DdlError('A partitioned table cannot be unlogged');
+        const key = table.partition.column;
+        if (!columns.has(key))
+            throw new DdlError(`There is no column "${key}" to partition by`);
+        for (const constraint of constraints) {
+            if ((constraint.kind === 'primary' || constraint.kind === 'unique') &&
+                !constraint.columns.includes(key)) {
+                throw new DdlError(`A ${constraint.kind === 'primary' ? 'primary key' : 'unique constraint'} of a partitioned table must include "${key}"`);
+            }
+        }
+    }
+    const qualifiedName = `${quoteIdentifier(table.schema)}.${quoteIdentifier(table.name)}`;
+    const inline = [];
+    const alters = [];
+    for (const constraint of constraints) {
+        const sql = constraintSql(constraint, options, columns);
+        const target = constraint.kind === 'foreign' ? constraint.references : null;
+        const targetKey = target ? `${target.schema}.${target.table}` : '';
+        if (target && later.has(targetKey)) {
+            alters.push(`ALTER TABLE ${qualifiedName} ADD ${sql}`);
+        }
+        else {
+            inline.push(sql);
+        }
+    }
+    let create = `CREATE ${table.unlogged ? 'UNLOGGED ' : ''}TABLE ${qualifiedName} (\n`;
+    create += [...table.columns.map(columnSql), ...inline].map((line) => `  ${line}`).join(',\n');
+    create += '\n)';
+    if (table.partition) {
+        create += ` PARTITION BY ${table.partition.method.toUpperCase()} (${quoteIdentifier(table.partition.column)})`;
+    }
+    const rest = [];
+    for (const index of table.indexes ?? [])
+        rest.push(indexSql(table, index, columns));
+    if (table.comment)
+        rest.push(`COMMENT ON TABLE ${qualifiedName} IS ${literal(table.comment)}`);
+    for (const column of table.columns) {
+        if (column.comment) {
+            rest.push(`COMMENT ON COLUMN ${qualifiedName}.${quoteIdentifier(column.name)} IS ${literal(column.comment)}`);
+        }
+    }
+    return { create, alters, rest };
+}
+/** The statements that create one table: the table, then its indexes and comments. */
+export function buildDdl(table, options = {}) {
+    const built = build(table, options, new Set());
+    return [built.create, ...built.rest];
+}
+/**
+ * The statements that create several tables, in the order given. A foreign key to a table that
+ * comes later is added with `ALTER TABLE` once every table exists, so any order works.
+ */
+export function buildDdlMany(tables, options = {}) {
+    const keys = tables.map((table) => `${table.schema}.${table.name}`);
+    if (new Set(keys).size !== keys.length)
+        throw new DdlError('Two tables have the same name');
+    const creates = [];
+    const later = [];
+    const rest = [];
+    tables.forEach((table, at) => {
+        const ahead = new Set(keys.slice(at + 1));
+        const built = build(table, options, ahead);
+        creates.push(built.create);
+        later.push(...built.alters);
+        rest.push(...built.rest);
+    });
+    return [...creates, ...later, ...rest];
+}
+// --- Reading a design from JSON -----------------------------------------------------------------
+const ACTIONS = [
+    'no action',
+    'restrict',
+    'cascade',
+    'set null',
+    'set default',
+];
+const METHODS = ['btree', 'hash', 'gin', 'gist', 'brin'];
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function object(value, what) {
+    if (!isObject(value))
+        throw new DdlError(`${what} must be an object`);
+    return value;
+}
+function text(value, what) {
+    if (typeof value !== 'string')
+        throw new DdlError(`${what} must be text`);
+    return value;
+}
+const optionalText = (value, what) => value === undefined || value === null ? undefined : text(value, what);
+const optionalFlag = (value, what) => {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new DdlError(`${what} must be true or false`);
+    return value || undefined;
+};
+const optionalNumber = (value, what) => {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number')
+        throw new DdlError(`${what} must be a number`);
+    return value;
+};
+function list(value, what) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new DdlError(`${what} must be a list`);
+    return value;
+}
+const names = (value, what) => list(value, what).map((name) => text(name, what));
+function oneOf(value, allowed, what) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new DdlError(`${what} must be one of ${allowed.join(', ')}`);
+    }
+    return value;
+}
+function parseType(value) {
+    const raw = object(value, 'A column type');
+    const schema = optionalText(raw.schema, 'A type schema');
+    return {
+        name: text(raw.name, 'A type name'),
+        ...(schema ? { schema } : {}),
+        ...pick('length', optionalNumber(raw.length, 'A length')),
+        ...pick('precision', optionalNumber(raw.precision, 'A precision')),
+        ...pick('scale', optionalNumber(raw.scale, 'A scale')),
+        ...pick('array', optionalNumber(raw.array, 'Array dimensions')),
+    };
+}
+const pick = (key, value) => (value === undefined ? {} : { [key]: value });
+function parseColumn(value) {
+    const raw = object(value, 'A column');
+    return {
+        ...pick('id', optionalText(raw.id, 'An id')),
+        name: text(raw.name, 'A column name'),
+        type: parseType(raw.type),
+        ...pick('notNull', optionalFlag(raw.notNull, 'notNull')),
+        ...pick('default', optionalText(raw.default, 'A default')),
+        ...pick('identity', oneOf(raw.identity, ['always', 'by default'], 'identity')),
+        ...pick('generated', optionalText(raw.generated, 'A generated expression')),
+        ...pick('comment', optionalText(raw.comment, 'A comment')),
+    };
+}
+function parseConstraint(value) {
+    const raw = object(value, 'A constraint');
+    const name = optionalText(raw.name, 'A constraint name');
+    const named = { ...(name ? { name } : {}), ...pick('id', optionalText(raw.id, 'An id')) };
+    switch (raw.kind) {
+        case 'primary':
+            return { kind: 'primary', ...named, columns: names(raw.columns, 'A column name') };
+        case 'unique':
+            return {
+                kind: 'unique',
+                ...named,
+                columns: names(raw.columns, 'A column name'),
+                ...pick('nullsNotDistinct', optionalFlag(raw.nullsNotDistinct, 'nullsNotDistinct')),
+            };
+        case 'check':
+            return { kind: 'check', ...named, expression: text(raw.expression, 'A check expression') };
+        case 'foreign': {
+            const target = object(raw.references, 'A foreign key target');
+            return {
+                kind: 'foreign',
+                ...named,
+                columns: names(raw.columns, 'A column name'),
+                references: {
+                    schema: text(target.schema, 'A target schema'),
+                    table: text(target.table, 'A target table'),
+                    columns: names(target.columns, 'A target column'),
+                },
+                ...pick('onDelete', oneOf(raw.onDelete, ACTIONS, 'onDelete')),
+                ...pick('onUpdate', oneOf(raw.onUpdate, ACTIONS, 'onUpdate')),
+                ...pick('matchFull', optionalFlag(raw.matchFull, 'matchFull')),
+                ...pick('deferrable', optionalFlag(raw.deferrable, 'deferrable')),
+                ...pick('initiallyDeferred', optionalFlag(raw.initiallyDeferred, 'initiallyDeferred')),
+            };
+        }
+        default:
+            throw new DdlError('A constraint is primary, unique, check or foreign');
+    }
+}
+function parseIndex(value) {
+    const raw = object(value, 'An index');
+    const name = optionalText(raw.name, 'An index name');
+    const items = list(raw.items, 'An index item list').map((item) => {
+        const entry = object(item, 'An index item');
+        const descending = optionalFlag(entry.descending, 'descending');
+        if (typeof entry.column === 'string') {
+            return { column: entry.column, ...(descending ? { descending } : {}) };
+        }
+        return {
+            expression: text(entry.expression, 'An index expression'),
+            ...(descending ? { descending } : {}),
+        };
+    });
+    const include = names(raw.include, 'An include column');
+    return {
+        ...pick('id', optionalText(raw.id, 'An id')),
+        ...(name ? { name } : {}),
+        ...pick('unique', optionalFlag(raw.unique, 'unique')),
+        ...pick('method', oneOf(raw.method, METHODS, 'method')),
+        items,
+        ...(include.length > 0 ? { include } : {}),
+        ...pick('where', optionalText(raw.where, 'A WHERE')),
+    };
+}
+/**
+ * Reads a design sent as JSON, refusing anything that is not one: the builder puts names in quotes,
+ * but a few words (the actions, the index method) are written as they are, so they are checked here.
+ */
+export function parseTableDesign(value) {
+    const raw = object(value, 'A design');
+    let partition;
+    if (raw.partition !== undefined && raw.partition !== null) {
+        const entry = object(raw.partition, 'The partitioning');
+        const method = oneOf(entry.method, ['range', 'list', 'hash'], 'The partition method');
+        if (!method)
+            throw new DdlError('The partition method must be one of range, list, hash');
+        partition = { method, column: text(entry.column, 'The partition column') };
+    }
+    return {
+        schema: text(raw.schema, 'The schema'),
+        name: text(raw.name, 'The table name'),
+        columns: list(raw.columns, 'The columns').map(parseColumn),
+        constraints: list(raw.constraints, 'The constraints').map(parseConstraint),
+        indexes: list(raw.indexes, 'The indexes').map(parseIndex),
+        ...pick('unlogged', optionalFlag(raw.unlogged, 'unlogged')),
+        ...pick('comment', optionalText(raw.comment, 'The comment')),
+        ...(partition ? { partition } : {}),
+    };
+}