@rwillians/exto 0.1.1 → 0.2.0

package/dist/cjs/index.js

@@ -0,0 +1,712 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.t = exports.parse = exports.into = exports.from = exports.f = exports.expr = exports.exec = exports.embedded = exports.defineType = exports.table = exports.defineMigrations = exports.create = exports.column = exports.ValidationError = void 0;
+const std = __importStar(require("./standard-schema"));
+const standard_schema_1 = require("./standard-schema");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return standard_schema_1.ValidationError; } });
+const utils_1 = require("./utils");
+const NUMERIC = ['BIGINT', 'DECIMAL', 'FLOAT', 'INTEGER', 'SEQUENCE'];
+class ColumnBuilder {
+    props;
+    constructor(props) {
+        this.props = props;
+    }
+    default(value) {
+        return new ColumnBuilder({ ...this.props, default: value });
+    }
+    generated() {
+        if (this.props.type !== 'UUID')
+            throw new Error('Only UUID columns can be generated, use t.sequence() for integers');
+        return new ColumnBuilder({ ...this.props, generated: true });
+    }
+    // nullable in the database, and optional on insert
+    optional() {
+        if (this.props.primaryKey)
+            throw new Error('Cannot make a primary key column optional');
+        return new ColumnBuilder({ ...this.props, nullable: true });
+    }
+    primaryKey() {
+        if (this.props.nullable)
+            throw new Error('Cannot make an optional column a primary key');
+        return new ColumnBuilder({ ...this.props, primaryKey: true });
+    }
+    unique() {
+        if (this.props.primaryKey)
+            throw new Error('Primary key columns are already unique');
+        return new ColumnBuilder({ ...this.props, unique: true });
+    }
+    unsigned() {
+        return new ColumnBuilder({ ...this.props, schema: std.integer({ min: 0 }) });
+    }
+}
+const column = (props) => new ColumnBuilder(props);
+exports.column = column;
+const columnsOfShape = (shape) => Object.fromEntries(Object.entries(shape).map(([key, { props }]) => [key, { ...props, key, name: (0, utils_1.snakeCase)(key) }]));
+// embedded fields keep their keys as they are inside the JSON document
+const fieldsOfShape = (shape) => Object.fromEntries(Object.entries(shape).map(([key, { props }]) => [key, { ...props, key, name: key }]));
+// validation happens field by field (see `check`), so the schema of an
+// embedded column is only there for its types
+const typed = () => std.optional(std.string());
+const embedded = {
+    one: (shape) => column({
+        type: 'JSON',
+        schema: typed(),
+        fields: fieldsOfShape(shape),
+    }),
+    many: (shape) => column({
+        type: 'JSON',
+        schema: typed(),
+        fields: fieldsOfShape(shape),
+        many: true,
+    }),
+};
+exports.embedded = embedded;
+// a column of a primitive type, validated by any standard schema
+const defineType = ({ primitive, schema }) => column({ type: primitive, schema });
+exports.defineType = defineType;
+const types = {
+    bigint: () => column({ type: 'BIGINT', schema: std.bigint() }),
+    binary: () => column({ type: 'BINARY', schema: std.instanceOf(Uint8Array) }),
+    boolean: () => column({ type: 'BOOLEAN', schema: std.boolean() }),
+    // case-insensitive text; postgres needs `CREATE EXTENSION citext` for it
+    citext: () => column({ type: 'CITEXT', schema: std.string() }),
+    // a calendar date, as a `YYYY-MM-DD` string
+    date: () => column({ type: 'DATE', schema: std.isoDate() }),
+    // `precision` and `scale` only shape postgres' NUMERIC; values are still
+    // numbers, so they're as exact as a double
+    decimal: (options) => column({ type: 'DECIMAL', schema: std.number(), ...options }),
+    enum: (values) => column({
+        type: 'STRING',
+        schema: std.enumOf(values),
+        length: Math.max(...values.map(value => value.length)),
+    }),
+    float: () => column({ type: 'FLOAT', schema: std.number() }),
+    integer: () => column({ type: 'INTEGER', schema: std.integer() }),
+    // any JSON document, validated by the given standard schema
+    json: (schema) => column({ type: 'JSON', schema }),
+    record: () => column({ type: 'JSON', schema: std.record() }),
+    // an integer the database generates, counting up
+    sequence: () => column({ type: 'SEQUENCE', schema: std.integer(), generated: true }),
+    string: ({ size = 255 } = {}) => column({ type: 'STRING', schema: std.string({ max: size }), length: size }),
+    text: () => column({ type: 'TEXT', schema: std.string() }),
+    timestamp: () => column({ type: 'TIMESTAMP', schema: std.date() }),
+    uuidv7: () => column({ type: 'UUID', schema: std.uuid() }),
+};
+exports.t = types;
+const isPlainObject = (value) => typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+const defaultOf = (col) => typeof col.default === 'function'
+    ? col.default()
+    : structuredClone(col.default);
+// validates a column's value, filling in its defaults (embedded fields'
+// included), and collects every issue rather than stopping at the first
+const check = (col, value, path, issues) => {
+    if (value === undefined && 'default' in col)
+        value = defaultOf(col);
+    if (value === undefined && col.nullable)
+        value = null;
+    if (value === undefined)
+        return void issues.push({ path, message: 'is required' });
+    if (value === null)
+        return col.nullable ? null : void issues.push({ path, message: 'must not be null' });
+    if (col.fields && col.many)
+        return Array.isArray(value)
+            ? value.map((item, i) => checkObject(col.fields, item, [...path, i], issues))
+            : void issues.push({ path, message: 'must be an array' });
+    if (col.fields)
+        return checkObject(col.fields, value, path, issues);
+    const parsed = std.parse(col.schema, value);
+    if (parsed.issues)
+        return void issues.push(...parsed.issues.map(issue => ({ ...issue, path: [...path, ...(issue.path ?? [])] })));
+    return parsed.value;
+};
+// `partial` leaves missing keys out, rather than filling them in
+const checkObject = (cols, value, path, issues, { partial = false } = {}) => {
+    if (!isPlainObject(value))
+        return void issues.push({ path, message: 'must be an object' });
+    for (const key of Object.keys(value)) {
+        if (!Object.hasOwn(cols, key))
+            issues.push({ path: [...path, key], message: 'unknown field' });
+    }
+    const checked = {};
+    for (const col of Object.values(cols)) {
+        if (partial && value[col.key] === undefined)
+            continue;
+        checked[col.key] = check(col, value[col.key], [...path, col.key], issues);
+    }
+    return checked;
+};
+const validate = (cols, value, options = {}) => {
+    const issues = [];
+    const checked = checkObject(cols, value, [], issues, options);
+    if (issues.length > 0)
+        throw new standard_schema_1.ValidationError(issues);
+    return checked;
+};
+// ─── tables ──────────────────────────────────────────────────────────────────
+const NAME = Symbol('exto.name');
+const ALIAS = Symbol('exto.alias');
+const NODE = Symbol('exto.node');
+const isOperand = (value) => typeof value === 'object' && value !== null && NODE in value;
+const operand = (node) => ({ [NODE]: node });
+const refOf = (alias, col, path = []) => {
+    const leaf = path.at(-1) ?? col;
+    const nested = leaf.fields && !leaf.many
+        ? Object.values(leaf.fields).map(field => [field.key, refOf(alias, col, [...path, field])])
+        : [];
+    return Object.assign(operand({ kind: 'ref', alias, col, path }), Object.fromEntries(nested));
+};
+// a table is shaped like its columns: each enumerable property references a
+// column under the table's alias, which is its name unless `as` says
+// otherwise. The name and alias are symbols and `as` is non-enumerable, so
+// spreading a table copies only its column references
+const tableOf = (name, alias, columns) => Object.defineProperties(Object.fromEntries(columns.map(col => [col.key, refOf(alias, col)])), {
+    [NAME]: { value: name },
+    [ALIAS]: { value: alias },
+    as: { value: (alias) => tableOf(name, alias, columns) },
+});
+const columnsOf = (table) => Object.values(table).map(ref => ref[NODE].col);
+const columnsByKey = (table) => Object.fromEntries(columnsOf(table).map(col => [col.key, col]));
+const columnOf = (table, key) => columnsByKey(table)[key] ?? (0, utils_1.raise)(`Unknown column "${key}" in table "${table[NAME]}"`);
+// `as` aliases the table
+const RESERVED = ['as'];
+const defineTable = (name, shape) => {
+    const columns = Object.values(columnsOfShape(shape));
+    const reserved = columns.find(col => RESERVED.includes(col.key));
+    if (reserved)
+        throw new Error(`"${reserved.key}" is reserved, it can't be a column of table "${name}"`);
+    return tableOf(name, name, columns);
+};
+exports.table = defineTable;
+// validates a row to be inserted into the table, filling in its defaults
+const parse = (table, input) => {
+    const insertable = Object.fromEntries(columnsOf(table).filter(col => !col.generated).map(col => [col.key, col]));
+    return validate(insertable, input);
+};
+exports.parse = parse;
+// ─── encoding ────────────────────────────────────────────────────────────────
+// inside JSON documents, timestamps are ISO 8601 strings, bigints are
+// strings of digits and binaries are base64 strings
+const toJson = (col, value) => {
+    if (value === null || value === undefined)
+        return null;
+    if (col.fields && col.many)
+        return value.map(item => toJson({ ...col, many: undefined }, item));
+    if (col.fields)
+        return Object.fromEntries(Object.values(col.fields).map(field => [field.key, toJson(field, value[field.key])]));
+    if (col.type === 'TIMESTAMP')
+        return value.toISOString();
+    if (col.type === 'BIGINT')
+        return String(value);
+    if (col.type === 'BINARY')
+        return Buffer.from(value).toString('base64');
+    return value;
+};
+// databases may read JSON numbers as bigints and booleans as numbers
+const fromJson = (col, value) => {
+    if (value === null || value === undefined)
+        return null;
+    if (col.fields && col.many)
+        return value.map(item => fromJson({ ...col, many: undefined }, item));
+    if (col.fields)
+        return Object.fromEntries(Object.values(col.fields).map(field => [field.key, fromJson(field, value[field.key])]));
+    if (col.type === 'TIMESTAMP')
+        return new Date(value);
+    if (col.type === 'BIGINT')
+        return BigInt(value);
+    if (col.type === 'BINARY')
+        return new Uint8Array(Buffer.from(value, 'base64'));
+    if (NUMERIC.includes(col.type))
+        return Number(value);
+    if (col.type === 'BOOLEAN')
+        return value === true || value === 1 || value === 1n;
+    return value;
+};
+const encode = (dialect, col, value) => value === null || value === undefined
+    ? null
+    : dialect.codecs[col.type].encode(col.type === 'JSON' ? toJson(col, value) : value);
+const decode = (dialect, col, value) => value === null || value === undefined
+    ? null
+    : col.type === 'JSON' ? fromJson(col, dialect.codecs.JSON.decode(value)) : dialect.codecs[col.type].decode(value);
+const quote = (ident) => `"${ident.replaceAll('"', '""')}"`;
+class SqlBuilder {
+    dialect;
+    frags = [];
+    params = [];
+    constructor(dialect) {
+        this.dialect = dialect;
+    }
+    push(...frags) {
+        this.frags.push(...frags);
+        return this;
+    }
+    param(value) {
+        this.params.push(value);
+        return this.push(this.dialect.placeholder(this.params.length));
+    }
+    join(items, separator, fn) {
+        items.forEach((item, i) => {
+            if (i > 0)
+                this.push(separator);
+            fn(item);
+        });
+        return this;
+    }
+    build() {
+        return { sql: this.frags.join(''), params: this.params };
+    }
+}
+const run = async (db, { sql, params }) => {
+    db.loggers.forEach(logger => logger.debug(sql, params));
+    try {
+        return await db.execute(sql, params);
+    }
+    catch (error) {
+        db.loggers.forEach(logger => logger.error(sql, params, error));
+        throw error;
+    }
+};
+// runs a raw statement, e.g. a data fix in a migration
+const exec = async (db, sql, params = []) => {
+    await run(db, { sql, params });
+};
+exports.exec = exec;
+const renderTable = (b, table) => table[ALIAS] === table[NAME]
+    ? b.push(quote(table[NAME]))
+    : b.push(quote(table[NAME]), ' AS ', quote(table[ALIAS]));
+const renderNode = (b, node) => {
+    switch (node.kind) {
+        case 'ref': {
+            const sql = `${quote(node.alias)}.${quote(node.col.name)}`;
+            if (node.path.length === 0)
+                return b.push(sql);
+            return b.push(b.dialect.json(sql, node.path.map(field => field.name), node.path.at(-1).type));
+        }
+        case 'compare': {
+            const { lhs, op, rhs } = node;
+            renderNode(b, lhs).push(' ', op.toUpperCase(), ' ');
+            if (op === 'is' || op === 'is not')
+                return b.push('NULL');
+            if (rhs.kind === 'value')
+                return b.param(encodeFor(b.dialect, lhs, rhs.value));
+            return renderNode(b, rhs);
+        }
+        case 'group': {
+            const { op, nodes } = node;
+            if (nodes.length === 0)
+                return b.push(op === 'AND' ? '1 = 1' : '1 = 0');
+            return b.push('(').join(nodes, ` ${op} `, node => renderNode(b, node)).push(')');
+        }
+        case 'fragment':
+            node.strings.forEach((str, i) => {
+                b.push(str);
+                if (i >= node.values.length)
+                    return;
+                const value = node.values[i];
+                if (isOperand(value))
+                    renderNode(b, value[NODE]);
+                else
+                    b.param(value);
+            });
+            return b;
+        case 'call':
+            return node.fn === 'SUM'
+                ? renderNode(b.push('COALESCE(SUM('), node.arg).push('), 0)')
+                : renderNode(b.push('COUNT('), node.arg).push(')');
+    }
+};
+// values compared with a column are encoded the way the column stores them
+const encodeFor = (dialect, node, value) => {
+    if (node.kind !== 'ref')
+        return value;
+    if (node.path.length === 0)
+        return encode(dialect, node.col, value);
+    const leaf = node.path.at(-1);
+    return leaf.type === 'JSON' ? dialect.codecs.JSON.encode(toJson(leaf, value)) : toJson(leaf, value);
+};
+const decodeFor = (dialect, node) => (value) => {
+    if (node.kind === 'call')
+        return Number(value ?? 0);
+    if (node.kind !== 'ref')
+        return typeof value === 'bigint' ? Number(value) : value;
+    if (node.path.length === 0)
+        return decode(dialect, node.col, value);
+    const leaf = node.path.at(-1);
+    if (value === null || value === undefined)
+        return null;
+    return fromJson(leaf, leaf.type === 'JSON' ? dialect.codecs.JSON.decode(value) : value);
+};
+const compare = (lhs, op, rhs) => ({
+    kind: 'compare',
+    lhs: lhs[NODE],
+    op,
+    rhs: isOperand(rhs) ? rhs[NODE] : { kind: 'value', value: rhs },
+});
+const exprOf = (lhs, op, rhs) => operand(compare(lhs, op, rhs));
+const group = (op) => (exprs) => operand({ kind: 'group', op, nodes: exprs.map(expr => expr[NODE]) });
+const call = (fn) => (arg) => operand({ kind: 'call', fn, arg: arg[NODE] });
+// aggregates: a sum of no rows is 0, rather than SQL's null
+const expr = Object.assign(exprOf, {
+    and: group('AND'),
+    or: group('OR'),
+    count: call('COUNT'),
+    sum: call('SUM'),
+});
+exports.expr = expr;
+// a fragment of raw SQL: interpolated operands are rendered in place, and
+// any other value is passed as a parameter
+const f = (strings, ...values) => operand({ kind: 'fragment', strings: [...strings], values });
+exports.f = f;
+const assertInScope = (scope, node) => {
+    switch (node.kind) {
+        case 'ref': {
+            const table = scope.get(node.alias);
+            if (!table || !columnsOf(table).includes(node.col))
+                throw new Error(`"${node.alias}.${node.col.key}" isn't part of the query`);
+            break;
+        }
+        case 'compare':
+            assertInScope(scope, node.lhs);
+            if (node.rhs.kind !== 'value')
+                assertInScope(scope, node.rhs);
+            break;
+        case 'group':
+            node.nodes.forEach(node => assertInScope(scope, node));
+            break;
+        case 'fragment':
+            node.values.filter(isOperand).forEach(value => assertInScope(scope, value[NODE]));
+            break;
+        case 'call':
+            assertInScope(scope, node.arg);
+            break;
+    }
+    return node;
+};
+const renderWhere = (b, where) => where.length === 0
+    ? b
+    : b.push(' WHERE ').join(where, ' AND ', node => renderNode(b, node));
+const returnedColumn = (table, item) => {
+    if (typeof item === 'string')
+        return columnOf(table, item);
+    const node = item[NODE];
+    const owned = node.kind === 'ref' && node.path.length === 0 && node.alias === table[ALIAS] && columnsOf(table).includes(node.col);
+    if (!owned)
+        throw new Error(`Only columns of "${table[ALIAS]}" can be returned`);
+    return node.col;
+};
+const runReturning = async (db, b, table, returning) => {
+    if (returning === false) {
+        await run(db, b.build());
+        return undefined;
+    }
+    const cols = returning === true
+        ? columnsOf(table)
+        : returning.map(item => returnedColumn(table, item));
+    // an empty RETURNING isn't valid SQL, but it still takes one to know how
+    // many rows were affected
+    if (cols.length === 0) {
+        const rows = await run(db, b.push(' RETURNING 1').build());
+        return rows.map(() => ({}));
+    }
+    b.push(' RETURNING ').join(cols, ', ', col => b.push(quote(col.name), ' AS ', quote(col.key)));
+    const rows = await run(db, b.build());
+    return rows.map(row => Object.fromEntries(cols.map(col => [col.key, decode(db.dialect, col, row[col.key])])));
+};
+const parseChanges = (table, { set = {}, inc = {}, replace = [] }) => {
+    const updatable = Object.fromEntries(columnsOf(table).filter(col => !col.generated && !col.primaryKey).map(col => [col.key, col]));
+    const updatableColumn = (key) => updatable[key] ?? (0, utils_1.raise)(`"${key}" isn't an updatable column of "${table[NAME]}"`);
+    const sets = validate(updatable, set, { partial: true });
+    const incs = Object.entries(inc).filter(([, by]) => by !== undefined).map(([key, by]) => {
+        const col = updatableColumn(key);
+        if (!NUMERIC.includes(col.type))
+            throw new Error(`"${key}" isn't a numeric column of "${table[NAME]}"`);
+        if (!Number.isFinite(by))
+            throw new standard_schema_1.ValidationError([{ path: [key], message: 'must be a finite number' }]);
+        return { col, op: 'inc', value: by };
+    });
+    return [
+        ...Object.entries(sets).map(([key, value]) => ({ col: updatableColumn(key), op: 'set', value })),
+        ...incs,
+        ...replace.map(key => ({ col: updatableColumn(key), op: 'replace' })),
+    ];
+};
+// `qualifier` tells the row's current value apart from EXCLUDED's, on conflict
+const renderAssignments = (b, assignments, qualifier) => b
+    .join(assignments, ', ', ({ col, op, value }) => {
+    if (op === 'replace')
+        return b.push(quote(col.name), ' = EXCLUDED.', quote(col.name));
+    if (op === 'inc')
+        return b.push(quote(col.name), ' = ', quote(qualifier), '.', quote(col.name), ' + ').param(value);
+    return b.push(quote(col.name), ' = ').param(encode(b.dialect, col, value));
+});
+const GENERATORS = {
+    UUID: () => Bun.randomUUIDv7(),
+};
+const generate = (col) => (GENERATORS[col.type] ?? (0, utils_1.raise)(`Cannot generate a value for column "${col.name}"`))();
+// columns the database generates are left out of inserts
+const isGeneratedByClient = (dialect, col) => col.generated === true && dialect.generated(col) === undefined;
+class InsertBuilder {
+    table;
+    rows;
+    constructor(table, rows = []) {
+        this.table = table;
+        this.rows = rows;
+    }
+    values(rows) {
+        return new InsertBuilder(this.table, [...this.rows, ...(Array.isArray(rows) ? rows : [rows])]);
+    }
+    async insert(db, { returning = true, conflict } = {}) {
+        if (this.rows.length === 0)
+            return returning === false ? undefined : [];
+        const { table } = this;
+        const cols = columnsOf(table).filter(col => !col.generated || isGeneratedByClient(db.dialect, col));
+        const insertable = Object.fromEntries(cols.filter(col => !col.generated).map(col => [col.key, col]));
+        const rows = this.rows.map(row => validate(insertable, row));
+        const b = new SqlBuilder(db.dialect)
+            .push('INSERT INTO ', quote(table[NAME]), ' (', cols.map(col => quote(col.name)).join(', '), ') VALUES ');
+        b.join(rows, ', ', row => b
+            .push('(')
+            .join(cols, ', ', col => b.param(encode(db.dialect, col, col.generated ? generate(col) : row[col.key])))
+            .push(')'));
+        if (conflict)
+            this.renderConflict(b, conflict);
+        return await runReturning(db, b, table, returning);
+    }
+    renderConflict(b, conflict) {
+        if (conflict.do === 'throw')
+            return b;
+        b.push(' ON CONFLICT');
+        if (conflict.on.length > 0)
+            b.push(' (', conflict.on.map(key => quote(columnOf(this.table, key).name)).join(', '), ')');
+        if (conflict.do === 'nothing')
+            return b.push(' DO NOTHING');
+        const assignments = parseChanges(this.table, conflict.do);
+        if (assignments.length === 0)
+            throw new Error('Nothing to update on conflict: `set`, `inc` and `replace` are empty');
+        return renderAssignments(b.push(' DO UPDATE SET '), assignments, this.table[NAME]);
+    }
+}
+const into = (table) => new InsertBuilder(table);
+exports.into = into;
+const count = (value, name) => Number.isSafeInteger(value) && value >= 0
+    ? value
+    : (0, utils_1.raise)(`${name} must be a non-negative integer, got ${value}`);
+// `T` is the queried table, `A` the aliases in scope, `N` those of them whose
+// rows may be missing (left joined), and `R` the row the query reads: a whole
+// row of `T` unless `select` says otherwise
+class QueryBuilder {
+    query;
+    constructor(query) {
+        this.query = query;
+    }
+    select(projection) {
+        const fields = Object.entries(projection).map(([key, value]) => isOperand(value)
+            ? [key, assertInScope(this.query.scope, value[NODE])]
+            : (0, utils_1.raise)(`"${key}" must be a column reference or an expression`));
+        return new QueryBuilder({ ...this.query, select: fields });
+    }
+    where(...args) {
+        const node = args.length === 1 ? args[0][NODE] : compare(...args);
+        return new QueryBuilder({ ...this.query, where: [...this.query.where, assertInScope(this.query.scope, node)] });
+    }
+    // the joined table's columns read as null for rows it has no match for
+    leftJoin(table, on) {
+        const alias = table[ALIAS];
+        if (this.query.scope.has(alias))
+            throw new Error(`"${alias}" is already part of the query, join it under another alias`);
+        const scope = new Map(this.query.scope).set(alias, table);
+        const joins = [...this.query.joins, { table, on: assertInScope(scope, on[NODE]) }];
+        return new QueryBuilder({ ...this.query, scope, joins });
+    }
+    groupBy(operands) {
+        const groupBy = operands.map(item => assertInScope(this.query.scope, item[NODE]));
+        return new QueryBuilder({ ...this.query, groupBy: [...this.query.groupBy, ...groupBy] });
+    }
+    orderBy(operands) {
+        const orderBy = operands.map(item => Array.isArray(item)
+            ? [assertInScope(this.query.scope, item[0][NODE]), item[1]]
+            : [assertInScope(this.query.scope, item[NODE]), 'ASC']);
+        return new QueryBuilder({ ...this.query, orderBy: [...this.query.orderBy, ...orderBy] });
+    }
+    limit(n) {
+        return new QueryBuilder({ ...this.query, limit: count(n, 'limit') });
+    }
+    offset(n) {
+        return new QueryBuilder({ ...this.query, offset: count(n, 'offset') });
+    }
+    async all(db) {
+        const fields = this.fields();
+        const rows = await run(db, this.renderSelect(new SqlBuilder(db.dialect), fields).build());
+        const decoders = fields.map(([key, node]) => [key, decodeFor(db.dialect, node)]);
+        return rows.map(row => Object.fromEntries(decoders.map(([key, decode]) => [key, decode(row[key])])));
+    }
+    async one(db) {
+        const [row] = await this.top().all(db);
+        return row ?? null;
+    }
+    async exists(db) {
+        const rows = await this.top().select({}).all(db);
+        return rows.length > 0;
+    }
+    // counts the rows `all` would return: as a subquery, limit and offset still
+    // apply, and postgres doesn't take ORDER BY next to a bare COUNT(*)
+    async count(db) {
+        const b = new SqlBuilder(db.dialect).push('SELECT COUNT(*) AS "count" FROM (');
+        const [row] = await run(db, this.renderSelect(b, []).push(') AS "q"').build());
+        return Number(row['count']);
+    }
+    async update(db, { returning = true, ...changes }) {
+        this.assertPlain('update');
+        const { table, where } = this.query;
+        const assignments = parseChanges(table, changes);
+        if (assignments.length === 0)
+            throw new Error('Nothing to update: both `set` and `inc` are empty');
+        const b = renderTable(new SqlBuilder(db.dialect).push('UPDATE '), table).push(' SET ');
+        renderAssignments(b, assignments, table[ALIAS]);
+        renderWhere(b, where);
+        return await runReturning(db, b, table, returning);
+    }
+    async delete(db, { returning = false } = {}) {
+        this.assertPlain('delete');
+        const { table, where } = this.query;
+        const b = renderTable(new SqlBuilder(db.dialect).push('DELETE FROM '), table);
+        renderWhere(b, where);
+        return await runReturning(db, b, table, returning);
+    }
+    // every column of the queried table, unless `select` says otherwise
+    fields() {
+        const { table, select } = this.query;
+        return select ?? columnsOf(table).map(col => [col.key, { kind: 'ref', alias: table[ALIAS], col, path: [] }]);
+    }
+    renderSelect(b, fields) {
+        const { table, joins, where, groupBy, orderBy, limit, offset } = this.query;
+        b.push('SELECT ');
+        // an empty select list isn't valid SQL, but each matching row still needs
+        // an (empty) object
+        if (fields.length === 0)
+            b.push('1');
+        else
+            b.join(fields, ', ', ([key, node]) => renderNode(b, node).push(' AS ', quote(key)));
+        renderTable(b.push(' FROM '), table);
+        joins.forEach(join => renderNode(renderTable(b.push(' LEFT JOIN '), join.table).push(' ON '), join.on));
+        renderWhere(b, where);
+        if (groupBy.length > 0)
+            b.push(' GROUP BY ').join(groupBy, ', ', node => renderNode(b, node));
+        if (orderBy.length > 0)
+            b.push(' ORDER BY ').join(orderBy, ', ', ([node, dir]) => renderNode(b, node).push(' ', dir));
+        // sqlite requires LIMIT whenever there's an OFFSET, and there's no "no
+        // limit" value both sqlite and postgres accept other than a huge number
+        if (limit !== undefined || offset !== undefined)
+            b.push(` LIMIT ${limit ?? Number.MAX_SAFE_INTEGER}`);
+        if (offset !== undefined)
+            b.push(` OFFSET ${offset}`);
+        return b;
+    }
+    // keeps a `limit(0)`, which can never match
+    top() {
+        return this.limit(Math.min(this.query.limit ?? 1, 1));
+    }
+    // UPDATE/DELETE ... ORDER BY/LIMIT isn't portable, so refuse it rather than
+    // silently affecting more rows than the query suggests
+    assertPlain(operation) {
+        const { joins, select, groupBy, orderBy, limit, offset } = this.query;
+        if (joins.length > 0 || select || groupBy.length > 0 || orderBy.length > 0 || limit !== undefined || offset !== undefined) {
+            throw new Error(`Cannot ${operation} with leftJoin, select, groupBy, orderBy, limit or offset`);
+        }
+    }
+}
+const from = (table) => new QueryBuilder({
+    table,
+    scope: new Map([[table[ALIAS], table]]),
+    joins: [],
+    where: [],
+    groupBy: [],
+    orderBy: [],
+});
+exports.from = from;
+// ─── ddl ─────────────────────────────────────────────────────────────────────
+const renderColumnDefinition = (dialect, col) => [
+    quote(col.name),
+    dialect.type(col),
+    col.primaryKey && 'PRIMARY KEY',
+    col.generated && dialect.generated(col),
+    !col.nullable && 'NOT NULL',
+    col.unique && 'UNIQUE',
+].filter(Boolean).join(' ');
+const createIndex = (table, keys, { ifNotExists = false, name, unique = false, } = {}) => ({
+    onto: async (db) => {
+        const cols = keys.map(key => columnOf(table, key).name);
+        const index = name ?? `${table[NAME]}_${cols.join('_')}_index`;
+        const sql = `CREATE ${unique ? 'UNIQUE ' : ''}INDEX ${ifNotExists ? 'IF NOT EXISTS ' : ''}${quote(index)} ON ${quote(table[NAME])} (${cols.map(quote).join(', ')})`;
+        await run(db, { sql, params: [] });
+    },
+});
+const create = {
+    table: (table, { ifNotExists = false } = {}) => ({
+        onto: async (db) => {
+            const cols = columnsOf(table).map(col => renderColumnDefinition(db.dialect, col));
+            const sql = `CREATE TABLE ${ifNotExists ? 'IF NOT EXISTS ' : ''}${quote(table[NAME])} (${cols.join(', ')})`;
+            await run(db, { sql, params: [] });
+        },
+    }),
+    index: createIndex,
+    uniqueIndex: (table, keys, options = {}) => createIndex(table, keys, { ...options, unique: true }),
+};
+exports.create = create;
+// ─── migrations ──────────────────────────────────────────────────────────────
+const schemaMigrations = defineTable('schema_migrations', {
+    id: types.string().primaryKey(),
+    timestamp: types.timestamp(),
+});
+// applies the pending migrations in the order of their ids, each in a
+// transaction of its own, tracking the applied ones in `schema_migrations`
+const defineMigrations = (migrations) => async (db) => {
+    await create.table(schemaMigrations, { ifNotExists: true }).onto(db);
+    const { dialect } = db;
+    const rows = await run(db, { sql: 'SELECT "id" FROM "schema_migrations"', params: [] });
+    const applied = new Set(rows.map(row => row['id']));
+    for (const id of Object.keys(migrations).sort()) {
+        if (applied.has(id))
+            continue;
+        await db.transaction(async (tx) => {
+            await migrations[id](tx);
+            await run(tx, {
+                sql: `INSERT INTO "schema_migrations" ("id", "timestamp") VALUES (${dialect.placeholder(1)}, ${dialect.placeholder(2)})`,
+                params: [id, encode(dialect, columnOf(schemaMigrations, 'timestamp'), new Date())],
+            });
+        });
+    }
+};
+exports.defineMigrations = defineMigrations;