@rwillians/exto 0.1.2 → 0.2.0

package/dist/esm/index.js

@@ -1,6 +1,7 @@
 import * as std from './standard-schema';
 import { ValidationError } from './standard-schema';
-import { camelCase, snakeCase, wrap } from './utils';
+import { raise, snakeCase } from './utils';
+const NUMERIC = ['BIGINT', 'DECIMAL', 'FLOAT', 'INTEGER', 'SEQUENCE'];
 class ColumnBuilder {
     props;
     constructor(props) {
@@ -14,14 +15,15 @@ class ColumnBuilder {
             throw new Error('Only UUID columns can be generated, use t.sequence() for integers');
         return new ColumnBuilder({ ...this.props, generated: true });
     }
-    nullable() {
+    // nullable in the database, and optional on insert
+    optional() {
         if (this.props.primaryKey)
-            throw new Error('Cannot make a primary key column nullable');
-        return new ColumnBuilder({ ...this.props, nullable: true, schema: std.nullable(this.props.schema) });
+            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 a nullable column a primary key');
+            throw new Error('Cannot make an optional column a primary key');
         return new ColumnBuilder({ ...this.props, primaryKey: true });
     }
     unique() {
@@ -29,16 +31,40 @@ class ColumnBuilder {
             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);
+const columnsOfShape = (shape) => Object.fromEntries(Object.entries(shape).map(([key, { props }]) => [key, { ...props, key, name: 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,
+    }),
+};
+// a column of a primitive type, validated by any standard schema
+const defineType = ({ primitive, schema }) => column({ type: primitive, schema });
 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() }),
-    datetime: () => column({ type: 'DATETIME', schema: std.date() }),
     // `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 }),
@@ -49,29 +75,149 @@ const types = {
     }),
     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() }),
-    uuid: () => column({ type: 'UUID', schema: std.uuid() }),
+    timestamp: () => column({ type: 'TIMESTAMP', schema: std.date() }),
+    uuidv7: () => column({ type: 'UUID', schema: std.uuid() }),
+};
+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 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] ?? 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);
+};
+// 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);
 };
-const defineTable = (name, shapeFn) => {
-    const columns = Object.fromEntries(Object
-        .entries(shapeFn(types))
-        .map(([key, { props }]) => [camelCase(key), { ...props, key: camelCase(key), name: snakeCase(camelCase(key)) }]));
-    const aliased = (alias) => ({ name, alias, columns, as: aliased });
-    return aliased(name);
+// ─── 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;
 };
-const columnOf = (table, key) => {
-    const col = table.columns[key];
-    if (!col)
-        throw new Error(`Unknown column "${key}" in table "${table.name}"`);
-    return col;
+// 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('"', '""')}"`;
-const ref = (col, qualifier) => qualifier
-    ? `${quote(qualifier)}.${quote(col.name)}`
-    : quote(col.name);
 class SqlBuilder {
     dialect;
     frags = [];
@@ -99,13 +245,6 @@ class SqlBuilder {
         return { sql: this.frags.join(''), params: this.params };
     }
 }
-const encode = (dialect, col, value) => value === null || value === undefined
-    ? null
-    : dialect.codecs[col.type].encode(value);
-const decode = (dialect, col, value) => value === null || value === undefined
-    ? null
-    : dialect.codecs[col.type].decode(value);
-const decoder = (dialect, cols) => (row) => Object.fromEntries(cols.map(col => [col.key, decode(dialect, col, row[col.key])]));
 const run = async (db, { sql, params }) => {
     db.loggers.forEach(logger => logger.debug(sql, params));
     try {
@@ -116,103 +255,182 @@ const run = async (db, { sql, params }) => {
         throw error;
     }
 };
-// runs a raw statement, e.g. `CREATE EXTENSION` in a migration
+// runs a raw statement, e.g. a data fix in a migration
 const exec = async (db, sql, params = []) => {
     await run(db, { sql, params });
 };
+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'),
+});
+// 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 });
+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
-        ? Object.values(table.columns)
-        : returning.map(key => columnOf(table, key));
+        ? 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(ref(col), ' AS ', quote(col.key)));
+    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(decoder(db.dialect, cols));
+    return rows.map(row => Object.fromEntries(cols.map(col => [col.key, decode(db.dialect, col, row[col.key])])));
 };
-const expr = Object.assign((key, op, value) => ({ key, op, value }), {
-    and: (exprs) => ({ group: 'AND', exprs }),
-    or: (exprs) => ({ group: 'OR', exprs }),
-});
-const toCondition = (table, node) => 'group' in node
-    ? { group: node.group, conditions: node.exprs.map(expr => toCondition(table, expr)) }
-    : { col: columnOf(table, node.key), op: node.op, value: node.value };
-const renderCondition = (b, qualifier) => (condition) => {
-    if ('group' in condition) {
-        const { group, conditions } = condition;
-        if (conditions.length === 0)
-            return b.push(group === 'AND' ? '1 = 1' : '1 = 0');
-        return b.push('(').join(conditions, ` ${group} `, renderCondition(b, qualifier)).push(')');
-    }
-    const { col, op, value } = condition;
-    if (op === 'is' || op === 'is not')
-        return b.push(ref(col, qualifier), ' ', op.toUpperCase(), ' NULL');
-    if (op !== 'in' && op !== 'not in')
-        return b.push(ref(col, qualifier), ' ', op.toUpperCase(), ' ').param(encode(b.dialect, col, value));
-    const values = value;
-    if (values.length === 0)
-        return b.push(op === 'in' ? '1 = 0' : '1 = 1');
-    return b
-        .push(ref(col, qualifier), ' ', op.toUpperCase(), ' (')
-        .join(values, ', ', v => b.param(encode(b.dialect, col, v)))
-        .push(')');
-};
-const renderWhere = (b, conditions, qualifier) => conditions.length === 0
-    ? b
-    : b.push(' WHERE ').join(conditions, ' AND ', renderCondition(b, qualifier));
 const parseChanges = (table, { set = {}, inc = {}, replace = [] }) => {
-    const updatable = Object.values(table.columns).filter(col => !col.generated && !col.primaryKey);
-    const numeric = updatable.filter(col => ['BIGINT', 'DECIMAL', 'FLOAT', 'INTEGER'].includes(col.type));
-    const sets = std.parseOrThrow(std.strictObject(Object.fromEntries(updatable.map(col => [col.key, std.optional(col.schema)]))), set);
-    const incs = std.parseOrThrow(std.strictObject(Object.fromEntries(numeric.map(col => [col.key, std.optional(std.number())]))), inc);
-    const replaced = replace.map(key => {
-        const col = updatable.find(col => col.key === key);
-        if (!col)
-            throw new Error(`Cannot replace "${key}": it's not an updatable field of "${table.name}"`);
-        return col;
+    const updatable = Object.fromEntries(columnsOf(table).filter(col => !col.generated && !col.primaryKey).map(col => [col.key, col]));
+    const updatableColumn = (key) => updatable[key] ?? 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 ValidationError([{ path: [key], message: 'must be a finite number' }]);
+        return { col, op: 'inc', value: by };
     });
     return [
-        ...Object.entries(sets).filter(([, value]) => value !== undefined).map(([key, value]) => ({ col: columnOf(table, key), op: 'set', value })),
-        ...Object.entries(incs).filter(([, value]) => value !== undefined).map(([key, value]) => ({ col: columnOf(table, key), op: 'inc', value })),
-        ...replaced.map(col => ({ col, op: 'replace' })),
+        ...Object.entries(sets).map(([key, value]) => ({ col: updatableColumn(key), op: 'set', value })),
+        ...incs,
+        ...replace.map(key => ({ col: updatableColumn(key), op: 'replace' })),
     ];
 };
-// on conflict, `qualifier` tells the row's current value apart from EXCLUDED's
+// `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(ref(col), ' = EXCLUDED.', quote(col.name));
+        return b.push(quote(col.name), ' = EXCLUDED.', quote(col.name));
     if (op === 'inc')
-        return b.push(ref(col), ' = ', ref(col, qualifier), ' + ').param(value);
-    return b.push(ref(col), ' = ').param(encode(b.dialect, col, value));
+        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 CLIENT_GENERATORS = {
+const GENERATORS = {
     UUID: () => Bun.randomUUIDv7(),
 };
+const generate = (col) => (GENERATORS[col.type] ?? 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;
-const resolveInsertValue = (col, row) => {
-    if (col.generated) {
-        const generate = CLIENT_GENERATORS[col.type];
-        if (!generate)
-            throw new Error(`Cannot generate a value for column "${col.name}" client-side`);
-        return generate();
-    }
-    if (row[col.key] !== undefined)
-        return row[col.key];
-    if ('default' in col)
-        return typeof col.default === 'function' ? col.default() : col.default;
-    if (col.nullable)
-        return null;
-    return undefined;
-};
 class InsertBuilder {
     table;
     rows;
@@ -221,27 +439,24 @@ class InsertBuilder {
         this.rows = rows;
     }
     values(rows) {
-        return new InsertBuilder(this.table, [...this.rows, ...wrap(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 cols = Object.values(this.table.columns);
-        const insertable = cols.filter(col => !col.generated || isGeneratedByClient(db.dialect, col));
-        const schema = std.array(std.strictObject(Object.fromEntries(insertable.map(col => [col.key, col.schema]))));
-        const rows = std.parseOrThrow(schema, this.rows.map(row => ({
-            ...row,
-            ...Object.fromEntries(insertable.map(col => [col.key, resolveInsertValue(col, row)])),
-        })));
+        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(this.table.name), ' (', insertable.map(col => quote(col.name)).join(', '), ') VALUES ');
+            .push('INSERT INTO ', quote(table[NAME]), ' (', cols.map(col => quote(col.name)).join(', '), ') VALUES ');
         b.join(rows, ', ', row => b
             .push('(')
-            .join(insertable, ', ', col => b.param(encode(db.dialect, col, row[col.key])))
+            .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, this.table, returning);
+        return await runReturning(db, b, table, returning);
     }
     renderConflict(b, conflict) {
         if (conflict.do === 'throw')
@@ -254,96 +469,122 @@ class InsertBuilder {
         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);
+        return renderAssignments(b.push(' DO UPDATE SET '), assignments, this.table[NAME]);
     }
 }
 const into = (table) => new InsertBuilder(table);
-// `S` holds the selected fields, every field unless `select` says otherwise
+const count = (value, name) => Number.isSafeInteger(value) && value >= 0
+    ? value
+    : 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(keys) {
-        return new QueryBuilder({ ...this.query, select: keys });
+    select(projection) {
+        const fields = Object.entries(projection).map(([key, value]) => isOperand(value)
+            ? [key, assertInScope(this.query.scope, value[NODE])]
+            : 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] : { key: args[0], op: args[1], value: args[2] };
-        return new QueryBuilder({ ...this.query, where: [...this.query.where, toCondition(this.query.table, node)] });
-    }
-    orderBy(keys) {
-        const orderBy = keys.map(key => typeof key === 'string'
-            ? [columnOf(this.query.table, key), 'ASC']
-            : [columnOf(this.query.table, key[0]), key[1]]);
+        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: n });
+        return new QueryBuilder({ ...this.query, limit: count(n, 'limit') });
     }
     offset(n) {
-        return new QueryBuilder({ ...this.query, offset: n });
+        return new QueryBuilder({ ...this.query, offset: count(n, 'offset') });
     }
     async all(db) {
-        const { table, select } = this.query;
-        const cols = select
-            ? select.map(key => columnOf(table, key))
-            : Object.values(table.columns);
-        const rows = await run(db, this.renderSelect(new SqlBuilder(db.dialect), cols).build());
-        return rows.map(decoder(db.dialect, cols));
+        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);
+        const rows = await this.top().select({}).all(db);
         return rows.length > 0;
     }
-    // counts the rows `select` would return: as a subquery, limit and offset
-    // still apply, and postgres doesn't take ORDER BY next to a bare COUNT(*)
+    // 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());
-        // postgres returns COUNT(*) as a bigint
         return Number(row['count']);
     }
     async update(db, { returning = true, ...changes }) {
-        this.assertUnbounded('update');
+        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 = new SqlBuilder(db.dialect).push('UPDATE ', quote(table.name), ' SET ');
-        renderAssignments(b, assignments);
+        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.assertUnbounded('delete');
+        this.assertPlain('delete');
         const { table, where } = this.query;
-        const b = new SqlBuilder(db.dialect).push('DELETE FROM ', quote(table.name));
+        const b = renderTable(new SqlBuilder(db.dialect).push('DELETE FROM '), table);
         renderWhere(b, where);
         return await runReturning(db, b, table, returning);
     }
-    renderSelect(b, cols) {
-        const { table, where, orderBy, limit, offset } = this.query;
+    // 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 (cols.length === 0)
+        if (fields.length === 0)
             b.push('1');
         else
-            b.join(cols, ', ', col => b.push(ref(col, table.alias), ' AS ', quote(col.key)));
-        b.push(' FROM ', quote(table.name), ' AS ', quote(table.alias));
-        renderWhere(b, where, table.alias);
+            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, ', ', ([col, dir]) => b.push(ref(col, table.alias), ' ', dir));
+            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 ').param(limit ?? Number.MAX_SAFE_INTEGER);
+            b.push(` LIMIT ${limit ?? Number.MAX_SAFE_INTEGER}`);
         if (offset !== undefined)
-            b.push(' OFFSET ').param(offset);
+            b.push(` OFFSET ${offset}`);
         return b;
     }
     // keeps a `limit(0)`, which can never match
@@ -352,14 +593,21 @@ class QueryBuilder {
     }
     // UPDATE/DELETE ... ORDER BY/LIMIT isn't portable, so refuse it rather than
     // silently affecting more rows than the query suggests
-    assertUnbounded(operation) {
-        const { orderBy, limit, offset } = this.query;
-        if (orderBy.length > 0 || limit !== undefined || offset !== undefined) {
-            throw new Error(`Cannot ${operation} with orderBy, limit or offset`);
+    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, where: [], orderBy: [] });
+const from = (table) => new QueryBuilder({
+    table,
+    scope: new Map([[table[ALIAS], table]]),
+    joins: [],
+    where: [],
+    groupBy: [],
+    orderBy: [],
+});
 // ─── ddl ─────────────────────────────────────────────────────────────────────
 const renderColumnDefinition = (dialect, col) => [
     quote(col.name),
@@ -372,16 +620,16 @@ const renderColumnDefinition = (dialect, col) => [
 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(', ')})`;
+        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 = Object.values(table.columns).map(col => renderColumnDefinition(db.dialect, col));
-            const sql = `CREATE TABLE ${ifNotExists ? 'IF NOT EXISTS ' : ''}${quote(table.name)} (${cols.join(', ')})`;
+            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: [] });
         },
     }),
@@ -389,20 +637,27 @@ const create = {
     uniqueIndex: (table, keys, options = {}) => createIndex(table, keys, { ...options, unique: true }),
 };
 // ─── migrations ──────────────────────────────────────────────────────────────
-const schemaMigrations = defineTable('schema_migrations', t => ({
-    id: t.string().primaryKey(),
-    migratedAt: t.datetime(),
-}));
+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 applied = new Set((await from(schemaMigrations).select(['id']).all(db)).map(row => row.id));
+    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 into(schemaMigrations).values({ id, migratedAt: new Date() }).insert(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())],
+            });
         });
     }
 };
-export { ValidationError, column, create, defineMigrations, defineTable as table, exec, expr, from, into, types as t, };
+export { ValidationError, column, create, defineMigrations, defineTable as table, defineType, embedded, exec, expr, f, from, into, parse, types as t, };