turbine-orm 0.19.2 → 0.22.0

package/dist/cjs/powql.js

@@ -0,0 +1,903 @@
+"use strict";
+/**
+ * PowqlInterface — Turbine's PowQL query generator (the PowDB analogue of
+ * {@link QueryInterface}). It exposes the same public method surface as the SQL
+ * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL** — a
+ * pipeline language, not SQL — executed through {@link PowdbPool}.
+ *
+ * It is a *parallel* implementation rather than a `Dialect` of the SQL builder:
+ * PowQL's grammar (`T filter <e> order <k> { .col }`) shares no surface with
+ * `SELECT … FROM … WHERE`, so the SQL `Dialect` seam cannot express it. Keeping
+ * it separate also means the four SQL engines are untouched.
+ *
+ * Behavioural deltas from the SQL path, all driven by PowDB's wire reality (see
+ * `docs/strategy/powdb-parity-matrix.md`, every row verified against a live
+ * server):
+ *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
+ *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
+ *     in one round-trip. `upsert` is the lone exception — its statement does not
+ *     accept `returning`, so it reselects the row by PK.
+ *   - The PK is generated client-side (UUID) when the column has a default.
+ *   - `with` (nested relations) degrades to **batched N+1 loaders** — D
+ *     round-trips for depth D, not one query. manyToMany is Phase B.
+ *   - pgvector / JSON / array filters and cursor streaming throw
+ *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PowqlInterface = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("./errors.js");
+const powdb_js_1 = require("./powdb.js");
+const utils_js_1 = require("./query/utils.js");
+const schema_js_1 = require("./schema.js");
+/**
+ * Max parent keys per relation-loader `in (…)` query. A `with` over a large
+ * parent set is split into batches of this size so a single query never exceeds
+ * PowDB's per-statement param / row limits; the batches' children are merged
+ * before grouping. Mirrors the chunking the parity matrix documents.
+ */
+const MAX_RELATION_KEYS = 1000;
+/** Operator keys recognised inside a `WhereOperator` object. */
+const OPERATOR_KEYS = new Set([
+    'equals',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'not',
+    'in',
+    'notIn',
+    'contains',
+    'startsWith',
+    'endsWith',
+    'mode',
+]);
+/** Filters that have no PowDB representation and must throw E017. */
+function rejectUnsupportedFilter(value, field) {
+    if ('distance' in value || 'metric' in value) {
+        throw new errors_js_1.UnsupportedFeatureError('pgvector distance filters', 'PowDB', `field "${field}"`);
+    }
+    if ('path' in value || 'hasKey' in value) {
+        throw new errors_js_1.UnsupportedFeatureError('JSON path/key filters', 'PowDB', `field "${field}"`);
+    }
+    if ('hasEvery' in value || 'hasSome' in value || 'isEmpty' in value) {
+        throw new errors_js_1.UnsupportedFeatureError('array filters', 'PowDB', `field "${field}"`);
+    }
+    if ('search' in value) {
+        throw new errors_js_1.UnsupportedFeatureError('full-text search filters', 'PowDB', `field "${field}"`);
+    }
+}
+/**
+ * The PowQL query interface. Constructed by `turbinePowDB` via the
+ * `queryInterfaceFactory` seam and cast to `QueryInterface<object>` so
+ * `TurbineClient.table()` can return it transparently.
+ */
+class PowqlInterface {
+    pool;
+    table;
+    schema;
+    middlewares;
+    options;
+    meta;
+    defaultLimit;
+    warnOnUnlimited;
+    onQuery;
+    currentAction = 'raw';
+    warnedUnlimited = false;
+    constructor(pool, table, schema, middlewares = [], options = {}) {
+        this.pool = pool;
+        this.table = table;
+        this.schema = schema;
+        this.middlewares = middlewares;
+        this.options = options;
+        const meta = schema.tables[table];
+        if (!meta) {
+            throw new errors_js_1.ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
+        }
+        this.meta = meta;
+        this.defaultLimit = options.defaultLimit;
+        this.warnOnUnlimited = options.warnOnUnlimited !== false;
+        this.onQuery = options._onQuery;
+    }
+    // -------------------------------------------------------------------------
+    // Column / value helpers
+    // -------------------------------------------------------------------------
+    /** Resolve a camelCase field name (or raw snake) to its column metadata. */
+    column(field) {
+        const snake = this.meta.columnMap[field] ?? field;
+        const col = this.meta.columns.find((c) => c.name === snake || c.field === field);
+        if (!col) {
+            throw new errors_js_1.ValidationError(`[turbine] Unknown column "${field}" on table "${this.table}". Known: ${this.meta.columns
+                .map((c) => c.field)
+                .join(', ')}`);
+        }
+        return col;
+    }
+    /** PowQL column reference (`.snake_name`) for a field. */
+    ref(field) {
+        return `.${this.column(field).name}`;
+    }
+    /**
+     * Push a value into the param array and return its `$N` placeholder. When the
+     * value targets a `float` column it is wrapped in {@link PowdbFloatParam} so
+     * the *embedded* literal encoder emits a float-form literal even for an
+     * integer value (PowQL's `42` is an int literal, `42.0` a float). The
+     * networked driver unwraps the marker back to the plain number in
+     * {@link toPowdbParam}, so the wire param is unchanged.
+     */
+    param(value, params, col) {
+        const tagged = col && typeof value === 'number' && this.isFloatCol(col) ? new powdb_js_1.PowdbFloatParam(value) : value;
+        params.push(tagged);
+        return `$${params.length}`;
+    }
+    /**
+     * Render a value for a write *assignment* (`col := …`). Every value — float
+     * columns included — is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
+     * the int→float UPDATE coercion bug (`score := $n` with an integer param now
+     * reads back the integer value, not the raw i64 bits), so the float-literal
+     * inlining workaround Turbine carried for ≤ 0.6.2 is gone. Marks the column as
+     * float-typed for the *embedded* literal encoder (which materializes params
+     * into PowQL text) so an integer-valued float still encodes as a float literal
+     * and coercion stays unambiguous. Non-finite floats are still rejected.
+     */
+    writeRef(value, col, params) {
+        if (typeof value === 'number' && !Number.isFinite(value) && this.isFloatCol(col)) {
+            throw new errors_js_1.ValidationError(`[turbine] Non-finite value for float column "${col.name}" on "${this.table}".`);
+        }
+        return this.param(value, params, col);
+    }
+    isFloatCol(col) {
+        try {
+            return (0, powdb_js_1.powqlColumnType)(col) === 'float';
+        }
+        catch {
+            return false;
+        }
+    }
+    /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
+    alwaysFalse() {
+        const pk = this.meta.primaryKey[0] ?? this.meta.columns[0]?.name;
+        return `(.${pk} is null and .${pk} is not null)`;
+    }
+    // -------------------------------------------------------------------------
+    // WHERE builder
+    // -------------------------------------------------------------------------
+    /**
+     * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
+     * value as a positional `$N` param. Returns `''` when there are no conditions.
+     */
+    buildWhere(where, params) {
+        if (!where)
+            return '';
+        const parts = [];
+        for (const [key, value] of Object.entries(where)) {
+            if (value === undefined)
+                continue;
+            if (key === 'AND') {
+                const sub = value.map((w) => this.buildWhere(w, params)).filter(Boolean);
+                if (sub.length)
+                    parts.push(`(${sub.join(' and ')})`);
+            }
+            else if (key === 'OR') {
+                const sub = value.map((w) => this.buildWhere(w, params)).filter(Boolean);
+                if (sub.length)
+                    parts.push(`(${sub.join(' or ')})`);
+            }
+            else if (key === 'NOT') {
+                const sub = this.buildWhere(value, params);
+                if (sub)
+                    parts.push(`not (${sub})`);
+            }
+            else if (this.meta.relations[key]) {
+                parts.push(this.buildRelationFilter(this.meta.relations[key], value, params));
+            }
+            else {
+                parts.push(this.buildFieldCondition(key, value, params));
+            }
+        }
+        return parts.join(' and ');
+    }
+    /** Build a single `field: value | operator` condition. */
+    buildFieldCondition(field, value, params) {
+        const ref = this.ref(field);
+        if (value === null)
+            return `${ref} is null`;
+        if (value instanceof Date || typeof value !== 'object') {
+            return `${ref} = ${this.param(value, params)}`;
+        }
+        const op = value;
+        rejectUnsupportedFilter(op, field);
+        if (!Object.keys(op).some((k) => OPERATOR_KEYS.has(k))) {
+            // A bare object that is not an operator set — equality by value.
+            return `${ref} = ${this.param(value, params)}`;
+        }
+        const insensitive = op.mode === 'insensitive';
+        const lhs = insensitive ? `lower(${ref})` : ref;
+        const conds = [];
+        for (const [opName, opVal] of Object.entries(op)) {
+            if (opVal === undefined || opName === 'mode')
+                continue;
+            switch (opName) {
+                case 'equals':
+                    conds.push(opVal === null ? `${ref} is null` : `${lhs} = ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'not':
+                    conds.push(opVal === null ? `${ref} is not null` : `not (${lhs} = ${this.bind(opVal, params, insensitive)})`);
+                    break;
+                case 'gt':
+                    conds.push(`${lhs} > ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'gte':
+                    conds.push(`${lhs} >= ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'lt':
+                    conds.push(`${lhs} < ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'lte':
+                    conds.push(`${lhs} <= ${this.bind(opVal, params, insensitive)}`);
+                    break;
+                case 'in':
+                    conds.push(this.buildInList(lhs, opVal, params, insensitive, false));
+                    break;
+                case 'notIn':
+                    conds.push(this.buildInList(lhs, opVal, params, insensitive, true));
+                    break;
+                case 'contains':
+                    conds.push(`${lhs} like ${this.bindLike(`%${(0, utils_js_1.escapeLike)(String(opVal))}%`, params, insensitive)}`);
+                    break;
+                case 'startsWith':
+                    conds.push(`${lhs} like ${this.bindLike(`${(0, utils_js_1.escapeLike)(String(opVal))}%`, params, insensitive)}`);
+                    break;
+                case 'endsWith':
+                    conds.push(`${lhs} like ${this.bindLike(`%${(0, utils_js_1.escapeLike)(String(opVal))}`, params, insensitive)}`);
+                    break;
+                default:
+                    throw new errors_js_1.ValidationError(`[turbine] Unsupported operator "${opName}" on PowDB.`);
+            }
+        }
+        return conds.length > 1 ? `(${conds.join(' and ')})` : (conds[0] ?? this.alwaysFalse());
+    }
+    /** Bind a value, lowercasing for case-insensitive comparisons. */
+    bind(value, params, insensitive) {
+        const ph = this.param(value, params);
+        return insensitive ? `lower(${ph})` : ph;
+    }
+    /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
+    bindLike(pattern, params, insensitive) {
+        const ph = this.param(pattern, params);
+        return insensitive ? `lower(${ph})` : ph;
+    }
+    /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
+    buildInList(lhs, values, params, insensitive, negate) {
+        if (!Array.isArray(values) || values.length === 0) {
+            // `in []` matches nothing; `not in []` matches everything.
+            return negate ? '(1 = 1)' : this.alwaysFalse();
+        }
+        const items = values.map((v) => this.bind(v, params, insensitive)).join(', ');
+        return `${lhs} ${negate ? 'not in' : 'in'} (${items})`;
+    }
+    /**
+     * Relation filter (`some`/`none`/`every`) via the verified IN-subquery form
+     * `Outer filter .localKey in (Target filter <e> { .targetKey })`. `exists`
+     * correlation is unreliable on PowDB, so it is never used.
+     */
+    buildRelationFilter(rel, filter, params) {
+        if (rel.type === 'manyToMany') {
+            throw new errors_js_1.UnsupportedFeatureError('manyToMany relation filters', 'PowDB', `relation "${rel.name}" — junction-table relation filters are Phase B`);
+        }
+        const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+        const rk = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+        if (fk.length > 1 || rk.length > 1) {
+            throw new errors_js_1.UnsupportedFeatureError('composite-key relation filters', 'PowDB', `relation "${rel.name}" uses a composite key`);
+        }
+        // hasMany/hasOne: outer.referenceKey ∈ target.foreignKey.
+        // belongsTo:      outer.foreignKey  ∈ target.referenceKey.
+        const localKey = rel.type === 'belongsTo' ? fk[0] : rk[0];
+        const targetKey = rel.type === 'belongsTo' ? rk[0] : fk[0];
+        const targetMeta = this.schema.tables[rel.to];
+        if (!targetMeta)
+            throw new errors_js_1.ValidationError(`[turbine] Relation "${rel.name}" targets unknown table "${rel.to}".`);
+        const sub = (whereObj, negateInner) => {
+            const innerQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+            const inner = innerQi.buildWhere(whereObj, params);
+            const filterClause = inner ? ` filter ${negateInner ? `not (${inner})` : inner}` : '';
+            return `${rel.to}${filterClause} { .${targetKey} }`;
+        };
+        if (filter.some)
+            return `.${localKey} in (${sub(filter.some, false)})`;
+        if (filter.none)
+            return `.${localKey} not in (${sub(filter.none, false)})`;
+        if (filter.every) {
+            // Parents with no child failing the predicate.
+            return `.${localKey} not in (${sub(filter.every, true)})`;
+        }
+        return this.alwaysFalse();
+    }
+    // -------------------------------------------------------------------------
+    // Projection / order
+    // -------------------------------------------------------------------------
+    /** Resolve the set of columns to project, honouring `select` / `omit`. */
+    projectedColumns(select, omit) {
+        let cols = this.meta.columns.map((c) => c.name);
+        if (select && Object.keys(select).length) {
+            const picked = new Set(Object.entries(select)
+                .filter(([, v]) => v)
+                .map(([k]) => this.column(k).name));
+            // Always keep the PK so reselect / relation stitching has a key to work with.
+            for (const pk of this.meta.primaryKey)
+                picked.add(pk);
+            cols = cols.filter((c) => picked.has(c));
+        }
+        if (omit && Object.keys(omit).length) {
+            const dropped = new Set(Object.entries(omit)
+                .filter(([, v]) => v)
+                .map(([k]) => this.column(k).name));
+            cols = cols.filter((c) => !dropped.has(c));
+        }
+        return cols;
+    }
+    /** `{ .c1, .c2, … }` projection clause. */
+    projection(cols) {
+        return `{ ${cols.map((c) => `.${c}`).join(', ')} }`;
+    }
+    /** `order .c1 asc, .c2 desc` clause (empty string when no orderBy). */
+    buildOrder(orderBy) {
+        if (!orderBy)
+            return '';
+        const keys = Object.entries(orderBy).filter(([, dir]) => dir !== undefined);
+        if (!keys.length)
+            return '';
+        const parts = keys.map(([field, dir]) => {
+            if (dir && typeof dir === 'object') {
+                throw new errors_js_1.UnsupportedFeatureError('vector / distance ordering', 'PowDB', `field "${field}"`);
+            }
+            return `${this.ref(field)} ${dir === 'desc' ? 'desc' : 'asc'}`;
+        });
+        return ` order ${parts.join(', ')}`;
+    }
+    // -------------------------------------------------------------------------
+    // Execution plumbing
+    // -------------------------------------------------------------------------
+    /** Run PowQL with optional timeout, emitting a query event either way. */
+    async exec(powql, params, timeout) {
+        const start = performance.now();
+        const run = this.pool.query(powql, params);
+        try {
+            const result = timeout
+                ? await Promise.race([
+                    run,
+                    new Promise((_, reject) => setTimeout(() => reject(new errors_js_1.TimeoutError(timeout)), timeout)),
+                ])
+                : await run;
+            this.emit(powql, params, performance.now() - start, result.rowCount ?? result.rows.length);
+            return result;
+        }
+        catch (err) {
+            this.emit(powql, params, performance.now() - start, 0, err);
+            throw err;
+        }
+    }
+    emit(sql, params, duration, rows, error) {
+        if (!this.onQuery)
+            return;
+        try {
+            this.onQuery({
+                sql,
+                params,
+                duration,
+                model: this.table,
+                action: this.currentAction,
+                rows,
+                timestamp: new Date(),
+                error,
+            });
+        }
+        catch {
+            /* listener errors never crash a query */
+        }
+    }
+    /** Run a method body through the middleware chain (mirrors QueryInterface). */
+    async withMiddleware(action, args, executor) {
+        this.currentAction = action;
+        if (this.middlewares.length === 0)
+            return executor();
+        let index = 0;
+        const next = async (p) => {
+            if (index < this.middlewares.length)
+                return this.middlewares[index++](p, next);
+            return executor();
+        };
+        return next({ model: this.table, action, args: { ...args } });
+    }
+    /** Map raw rows to typed entities. */
+    shape(rows) {
+        return rows.map((r) => (0, powdb_js_1.rowToEntity)(r, this.meta));
+    }
+    // -------------------------------------------------------------------------
+    // Reads
+    // -------------------------------------------------------------------------
+    async findMany(args = {}) {
+        return this.withMiddleware('findMany', args, async () => {
+            const rows = await this.runFind(args);
+            const entities = this.shape(rows);
+            if (args.with)
+                await this.loadRelations(entities, args.with, args.timeout);
+            return entities;
+        });
+    }
+    /** Build + run the flat findMany select; returns raw rows. */
+    async runFind(args) {
+        if (args.cursor) {
+            throw new errors_js_1.UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
+        }
+        const params = [];
+        const where = this.buildWhere(args.where, params);
+        const cols = this.projectedColumns(args.select, args.omit);
+        const distinct = args.distinct?.length ? ' distinct' : '';
+        const filter = where ? ` filter ${where}` : '';
+        const order = this.buildOrder(args.orderBy);
+        const limit = args.limit ?? args.take ?? this.defaultLimit;
+        if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
+            this.warnedUnlimited = true;
+            console.warn(`[turbine] findMany on "${this.table}" has no limit — this scans the whole table.`);
+        }
+        const limitClause = limit !== undefined ? ` limit ${this.param(limit, params)}` : '';
+        const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
+        const powql = `${this.table}${distinct}${filter}${order}${limitClause}${offsetClause} ${this.projection(cols)}`;
+        const { rows } = await this.exec(powql, params, args.timeout);
+        return rows;
+    }
+    async findUnique(args) {
+        return this.withMiddleware('findUnique', args, async () => {
+            const rows = await this.runFind({ ...args, limit: 1 });
+            if (!rows.length)
+                return null;
+            const entities = this.shape(rows);
+            if (args.with)
+                await this.loadRelations(entities, args.with, args.timeout);
+            return entities[0];
+        });
+    }
+    async findFirst(args = {}) {
+        return this.withMiddleware('findFirst', args, async () => {
+            const rows = await this.runFind({ ...args, limit: 1 });
+            if (!rows.length)
+                return null;
+            const entities = this.shape(rows);
+            if (args.with)
+                await this.loadRelations(entities, args.with, args.timeout);
+            return entities[0];
+        });
+    }
+    async findUniqueOrThrow(args) {
+        const row = await this.findUnique(args);
+        if (!row)
+            throw new errors_js_1.NotFoundError({ table: this.table, where: args.where });
+        return row;
+    }
+    async findFirstOrThrow(args = {}) {
+        const row = await this.findFirst(args);
+        if (!row)
+            throw new errors_js_1.NotFoundError({ table: this.table, where: (args.where ?? {}) });
+        return row;
+    }
+    // -------------------------------------------------------------------------
+    // Nested relations — batched N+1 loaders (hasMany / hasOne / belongsTo)
+    // -------------------------------------------------------------------------
+    /** Load each requested relation for `parents` and attach it onto each row. */
+    async loadRelations(parents, withClause, timeout, depth = 0) {
+        if (depth >= 10) {
+            throw new errors_js_1.ValidationError(`[turbine] Nested 'with' on PowDB exceeded depth 10 (relation cycle?).`);
+        }
+        if (!parents.length)
+            return;
+        for (const [relName, opt] of Object.entries(withClause)) {
+            if (!opt)
+                continue;
+            const rel = this.meta.relations[relName];
+            if (!rel)
+                throw new errors_js_1.ValidationError(`[turbine] Unknown relation "${relName}" on "${this.table}".`);
+            if (rel.type === 'manyToMany') {
+                throw new errors_js_1.UnsupportedFeatureError('manyToMany nested reads', 'PowDB', `relation "${relName}" — junction loading is Phase B`);
+            }
+            const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+            const rk = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+            if (fk.length > 1 || rk.length > 1) {
+                throw new errors_js_1.UnsupportedFeatureError('composite-key nested reads', 'PowDB', `relation "${relName}"`);
+            }
+            const options = (opt === true ? {} : opt);
+            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+            const targetMeta = this.schema.tables[rel.to];
+            // Local key on the parent, remote key on the target child.
+            const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
+            const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
+            const parentKeyField = this.meta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
+            const childKeyField = targetMeta.reverseColumnMap[childKeyCol] ?? childKeyCol;
+            const keys = [
+                ...new Set(parents.map((p) => p[parentKeyField]).filter((k) => k != null)),
+            ];
+            const childByKey = new Map();
+            // Chunk the key set so a single `in (…)` never exceeds PowDB's
+            // per-statement param / row limits; merge each chunk's children.
+            for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS) {
+                const chunk = keys.slice(i, i + MAX_RELATION_KEYS);
+                const childWhere = {
+                    ...options.where,
+                    [childKeyField]: { in: chunk },
+                };
+                const children = (await targetQi.findMany({
+                    ...options,
+                    where: childWhere,
+                    with: options.with,
+                    timeout: options.timeout ?? timeout,
+                }));
+                for (const child of children) {
+                    const k = child[childKeyField];
+                    const bucket = childByKey.get(k);
+                    if (bucket)
+                        bucket.push(child);
+                    else
+                        childByKey.set(k, [child]);
+                }
+            }
+            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+            for (const parent of parents) {
+                const k = parent[parentKeyField];
+                const matches = childByKey.get(k) ?? [];
+                parent[relName] = single ? (matches[0] ?? null) : matches;
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Writes (reselect — PowDB has no RETURNING)
+    // -------------------------------------------------------------------------
+    /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
+    scalarData(data) {
+        const out = [];
+        for (const [field, value] of Object.entries(data)) {
+            if (value === undefined)
+                continue;
+            if (this.meta.relations[field]) {
+                throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" in write data — Phase B`);
+            }
+            out.push({ col: this.column(field), value });
+        }
+        return out;
+    }
+    /** Fill in a client-generated UUID for a defaulted PK that wasn't supplied. */
+    applyPkDefault(data) {
+        const out = { ...data };
+        for (const pk of this.meta.primaryKey) {
+            const field = this.meta.reverseColumnMap[pk] ?? pk;
+            const col = this.meta.columns.find((c) => c.name === pk);
+            if (out[field] == null && col?.hasDefault && col.tsType.replace(/\s*\|\s*null$/, '').trim() === 'string') {
+                out[field] = (0, node_crypto_1.randomUUID)();
+            }
+        }
+        return out;
+    }
+    async create(args) {
+        return this.withMiddleware('create', args, async () => {
+            const data = this.applyPkDefault(args.data);
+            const assigns = this.scalarData(data);
+            const params = [];
+            const body = assigns.map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`).join(', ');
+            // `returning` surfaces the inserted row (all columns, schema order) in one round-trip.
+            const { rows } = await this.exec(`insert ${this.table} { ${body} } returning`, params, args.timeout);
+            const row = rows.length ? this.shape(rows)[0] : null;
+            if (!row)
+                throw new errors_js_1.NotFoundError({ table: this.table, where: data });
+            return row;
+        });
+    }
+    async createMany(args) {
+        return this.withMiddleware('createMany', args, async () => {
+            const inputs = args.data.map((d) => this.applyPkDefault(d));
+            if (!inputs.length)
+                return [];
+            const params = [];
+            const tuples = inputs.map((d) => {
+                const assigns = this.scalarData(d);
+                return `{ ${assigns.map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`).join(', ')} }`;
+            });
+            // Multi-row insert with `returning` hands back every inserted row in one round-trip.
+            const { rows } = await this.exec(`insert ${this.table} ${tuples.join(', ')} returning`, params, args.timeout);
+            return this.shape(rows);
+        });
+    }
+    async update(args) {
+        return this.withMiddleware('update', args, async () => {
+            const params = [];
+            const where = this.buildWhere(args.where, params);
+            this.assertCompiledWhere(where, false, 'update');
+            const setClause = this.buildUpdateAssignments(args.data, params);
+            // `returning` hands back the post-update row(s); take the first (single-row contract).
+            const { rows } = await this.exec(`${this.table} filter ${where} update { ${setClause} } returning`, params, args.timeout);
+            const row = rows.length ? this.shape(rows)[0] : null;
+            if (!row)
+                throw new errors_js_1.NotFoundError({ table: this.table, where: args.where });
+            return row;
+        });
+    }
+    async updateMany(args) {
+        return this.withMiddleware('updateMany', args, async () => {
+            const params = [];
+            const where = this.buildWhere(args.where, params);
+            this.assertCompiledWhere(where, args.allowFullTableScan, 'updateMany');
+            const setClause = this.buildUpdateAssignments(args.data, params);
+            const filter = where ? ` filter ${where}` : '';
+            const { rowCount } = await this.exec(`${this.table}${filter} update { ${setClause} }`, params, args.timeout);
+            return { count: rowCount };
+        });
+    }
+    /** Compile `data` into PowQL update assignments, including atomic operators. */
+    buildUpdateAssignments(data, params) {
+        const parts = [];
+        for (const [field, value] of Object.entries(data)) {
+            if (value === undefined)
+                continue;
+            if (this.meta.relations[field]) {
+                throw new errors_js_1.UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — Phase B`);
+            }
+            const colMeta = this.column(field);
+            const ref = this.ref(field);
+            const col = colMeta.name;
+            if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
+                const opObj = value;
+                if ('set' in opObj)
+                    parts.push(`${col} := ${this.writeRef(opObj.set, colMeta, params)}`);
+                else if ('increment' in opObj)
+                    parts.push(`${col} := ${ref} + ${this.writeRef(opObj.increment, colMeta, params)}`);
+                else if ('decrement' in opObj)
+                    parts.push(`${col} := ${ref} - ${this.writeRef(opObj.decrement, colMeta, params)}`);
+                else if ('multiply' in opObj)
+                    parts.push(`${col} := ${ref} * ${this.writeRef(opObj.multiply, colMeta, params)}`);
+                else if ('divide' in opObj)
+                    parts.push(`${col} := ${ref} / ${this.writeRef(opObj.divide, colMeta, params)}`);
+                else
+                    throw new errors_js_1.ValidationError(`[turbine] Unsupported update operator on "${field}".`);
+            }
+            else {
+                parts.push(`${col} := ${this.writeRef(value, colMeta, params)}`);
+            }
+        }
+        if (!parts.length)
+            throw new errors_js_1.ValidationError(`[turbine] update on "${this.table}" has no fields to set.`);
+        return parts.join(', ');
+    }
+    async delete(args) {
+        return this.withMiddleware('delete', args, async () => {
+            const params = [];
+            const where = this.buildWhere(args.where, params);
+            this.assertCompiledWhere(where, false, 'delete');
+            // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
+            const { rows } = await this.exec(`${this.table} filter ${where} delete returning`, params, args.timeout);
+            const row = rows.length ? this.shape(rows)[0] : null;
+            if (!row)
+                throw new errors_js_1.NotFoundError({ table: this.table, where: args.where });
+            return row;
+        });
+    }
+    async deleteMany(args) {
+        return this.withMiddleware('deleteMany', args, async () => {
+            const params = [];
+            const where = this.buildWhere(args.where, params);
+            this.assertCompiledWhere(where, args.allowFullTableScan, 'deleteMany');
+            const filter = where ? ` filter ${where}` : '';
+            const { rowCount } = await this.exec(`${this.table}${filter} delete`, params, args.timeout);
+            return { count: rowCount };
+        });
+    }
+    async upsert(args) {
+        return this.withMiddleware('upsert', args, async () => {
+            const createData = this.applyPkDefault(args.create);
+            const pkCol = this.meta.primaryKey[0];
+            if (!pkCol || this.meta.primaryKey.length !== 1) {
+                throw new errors_js_1.UnsupportedFeatureError('composite-key upsert', 'PowDB', `table "${this.table}"`);
+            }
+            const params = [];
+            const createBody = this.scalarData(createData)
+                .map((a) => `${a.col.name} := ${this.writeRef(a.value, a.col, params)}`)
+                .join(', ');
+            const updateBody = this.buildUpdateAssignments(args.update, params);
+            // PowDB 0.7.0's `upsert` statement does NOT accept a trailing `returning`
+            // (verified: "unexpected trailing token … 'returning'"), because it is one
+            // atomic insert-or-update, not two branches. So upsert alone keeps the
+            // reselect-by-PK fetch; create/update/delete all use `returning`.
+            await this.exec(`upsert ${this.table} on .${pkCol} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout);
+            const pkField = this.meta.reverseColumnMap[pkCol] ?? pkCol;
+            const row = await this.reselectByPk(createData[pkField], args.timeout);
+            if (!row)
+                throw new errors_js_1.NotFoundError({ table: this.table, where: createData });
+            return row;
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Aggregates
+    // -------------------------------------------------------------------------
+    async count(args = {}) {
+        return this.withMiddleware('count', (args ?? {}), async () => {
+            const params = [];
+            const where = this.buildWhere(args.where, params);
+            const filter = where ? ` filter ${where}` : '';
+            const { rows } = await this.exec(`count(${this.table}${filter})`, params, args.timeout);
+            return Number((rows[0]?.value ?? rows[0]?.count ?? 0));
+        });
+    }
+    async aggregate(args) {
+        return this.withMiddleware('aggregate', args, async () => {
+            // One scalar query per aggregate — PowDB's bare-projection aggregate is broken.
+            const result = {};
+            const filterParams = [];
+            const where = this.buildWhere(args.where, filterParams);
+            const filter = where ? ` filter ${where}` : '';
+            const scalar = async (expr) => {
+                const params = [...filterParams];
+                const { rows } = await this.exec(expr, params, args.timeout);
+                const v = rows[0]?.value;
+                return v == null || v === 'null' ? null : Number(v);
+            };
+            if (args._count) {
+                if (args._count === true) {
+                    result._count = (await scalar(`count(${this.table}${filter})`)) ?? 0;
+                }
+                else {
+                    const counts = {};
+                    for (const field of Object.keys(args._count).filter((f) => args._count[f])) {
+                        counts[field] = (await scalar(`count(${this.table}${filter} { ${this.ref(field)} })`)) ?? 0;
+                    }
+                    result._count = counts;
+                }
+            }
+            for (const fn of ['_sum', '_avg', '_min', '_max']) {
+                const spec = args[fn];
+                if (!spec)
+                    continue;
+                const acc = {};
+                for (const field of Object.keys(spec).filter((f) => spec[f])) {
+                    const powfn = fn.slice(1); // sum/avg/min/max
+                    acc[field] = await scalar(`${powfn}(${this.table}${filter} { ${this.ref(field)} })`);
+                }
+                result[fn] = acc;
+            }
+            return result;
+        });
+    }
+    async groupBy(args) {
+        return this.withMiddleware('groupBy', args, async () => {
+            const params = [];
+            const where = this.buildWhere(args.where, params);
+            const filter = where ? ` filter ${where}` : '';
+            const groupKeys = args.by.map((f) => this.ref(f));
+            // Safe aliases — PowQL rejects reserved-word aliases (e.g. `count:`).
+            const aliasMap = [];
+            let n = 0;
+            const proj = args.by.map((f) => this.ref(f));
+            if (args._count) {
+                aliasMap.push({ alias: `agg_${n++}`, fn: 'count', field: null, outKey: '_count' });
+            }
+            for (const fn of ['_sum', '_avg', '_min', '_max']) {
+                const spec = args[fn];
+                if (!spec)
+                    continue;
+                for (const field of Object.keys(spec).filter((f) => spec[f])) {
+                    aliasMap.push({ alias: `agg_${n++}`, fn: fn.slice(1), field, outKey: `${fn}:${field}` });
+                }
+            }
+            for (const a of aliasMap) {
+                proj.push(`${a.alias}: ${a.fn}(${a.field ? this.ref(a.field) : `.${this.meta.primaryKey[0]}`})`);
+            }
+            const having = this.buildHaving(args.having, params);
+            const order = this.buildOrder(args.orderBy);
+            const powql = `${this.table}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
+            const { rows } = await this.exec(powql, params, args.timeout);
+            // Reshape: group keys → camel fields + coerced; aggregates → nested {_sum:{field}}.
+            return rows.map((raw) => {
+                const out = {};
+                for (const f of args.by) {
+                    const col = this.column(f);
+                    out[f] =
+                        typeof raw[col.name] === 'string' ? coerceScalar(raw[col.name], col.tsType) : raw[col.name];
+                }
+                for (const a of aliasMap) {
+                    const val = raw[a.alias];
+                    const num = val == null || val === 'null' ? null : Number(val);
+                    if (a.outKey === '_count')
+                        out._count = num ?? 0;
+                    else {
+                        const [bucket, field] = a.outKey.split(':');
+                        out[bucket] ??= {};
+                        out[bucket][field] = num;
+                    }
+                }
+                return out;
+            });
+        });
+    }
+    /** `having <expr>` over group aggregates (count/sum/avg/min/max). */
+    buildHaving(having, params) {
+        if (!having)
+            return '';
+        const conds = [];
+        const cmp = (expr, filter) => {
+            if (typeof filter === 'number')
+                return `${expr} = ${this.param(filter, params)}`;
+            const f = filter;
+            const ops = { equals: '=', gt: '>', gte: '>=', lt: '<', lte: '<=', not: '!=' };
+            return Object.entries(f)
+                .filter(([k]) => ops[k])
+                .map(([k, v]) => `${expr} ${ops[k]} ${this.param(v, params)}`)
+                .join(' and ');
+        };
+        for (const [key, spec] of Object.entries(having)) {
+            if (spec == null)
+                continue;
+            if (key === '_count') {
+                conds.push(cmp(`count(.${this.meta.primaryKey[0]})`, spec));
+            }
+            else {
+                for (const [fn, filter] of Object.entries(spec)) {
+                    if (filter == null)
+                        continue;
+                    conds.push(cmp(`${fn.slice(1)}(${this.ref(key)})`, filter));
+                }
+            }
+        }
+        return conds.length ? ` having ${conds.join(' and ')}` : '';
+    }
+    // -------------------------------------------------------------------------
+    // Streaming / unsupported
+    // -------------------------------------------------------------------------
+    // biome-ignore lint/correctness/useYield: intentionally throws before yielding — PowDB has no server cursor.
+    async *findManyStream() {
+        throw new errors_js_1.UnsupportedFeatureError('cursor streaming (findManyStream)', 'PowDB', 'PowDB has no server-side cursor; page with findMany({ limit, offset }) instead');
+    }
+    // -------------------------------------------------------------------------
+    // Reselect helper (upsert only — PowDB's upsert has no `returning`)
+    // -------------------------------------------------------------------------
+    /** Reselect a single row by its single-column primary key value. */
+    async reselectByPk(pkValue, timeout) {
+        const pkField = this.meta.reverseColumnMap[this.meta.primaryKey[0]] ?? this.meta.primaryKey[0];
+        const rows = await this.runFind({
+            where: { [pkField]: pkValue },
+            limit: 1,
+            timeout,
+        });
+        return rows.length ? this.shape(rows)[0] : null;
+    }
+    /**
+     * Empty-where guard — blocks accidental whole-table writes. Mirrors the SQL
+     * path's `assertMutationHasPredicate` (query/builder.ts): it gates on the
+     * *compiled* PowQL filter fragment, NOT the shape of the `where` object. A
+     * `where` whose conditions all evaporate during compilation — `{}`,
+     * `{ id: undefined }`, `{ OR: [] }`, `{ AND: [] }`, `{ NOT: {} }`,
+     * `{ OR: [{ f: undefined }] }` — compiles to the empty string and is refused,
+     * because emitting a filter-less write would hit every row.
+     */
+    assertCompiledWhere(compiledWhere, allow, action) {
+        if (allow === true)
+            return;
+        if (compiledWhere.length > 0)
+            return;
+        throw new errors_js_1.ValidationError(`[turbine] ${action} on "${this.table}" refused: the \`where\` clause is empty. ` +
+            `Pass \`allowFullTableScan: true\` to opt in, or check that your filter values are defined.`);
+    }
+}
+exports.PowqlInterface = PowqlInterface;
+/** Coerce a group-key scalar string by the column's TS type (numbers/bools). */
+function coerceScalar(raw, tsType) {
+    const ts = tsType.replace(/\s*\|\s*null$/i, '').trim();
+    if (raw === 'null')
+        return null;
+    if (ts === 'number' || ts === 'bigint') {
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : raw;
+    }
+    if (ts === 'boolean')
+        return raw === 'true';
+    if (ts === 'Date')
+        return new Date(Number(raw) / 1000);
+    return raw;
+}