turbine-orm 0.90.2 → 0.91.0-next.32b6789

package/dist/query/aggregates.js

@@ -10,6 +10,7 @@
  */
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
+import { compileReadExpr } from './expr.js';
 import { assertEqualityOperand, dedupeColumnList, isJsonPathOrderBy, isUnmatchedPlainObject, isVectorOrderBy, isWhereOperator, normalizeOrderBy, orderByEntries, setOwn, } from './filters.js';
 import { assertOrderDirection, resolveSkipGlobalFilters, resolveUnsafeFlag } from './types.js';
 import { isTemporalInfinity, ownLookup, parseDbDate, resolveColumnName, suggestKey, warnRedundantSortTerm, } from './utils.js';
@@ -281,7 +282,7 @@ export function buildGroupBy(qi, args) {
     buildAggregates('_avg', 'AVG', args._avg);
     buildAggregates('_min', 'MIN', args._min);
     buildAggregates('_max', 'MAX', args._max);
-    const percentiles = planPercentiles(qi, args._percentile, params, includePii, 'groupBy', claimResultKey);
+    const percentiles = planPercentiles(qi, args._percentile, params, includePii, 'groupBy', claimResultKey, (key) => key === '_count' || usedResultKeys.has(key));
     selectExprs.push(...percentiles.map((plan) => plan.expr));
     let sql = `SELECT ${selectExprs.join(', ')} FROM ${fromSql} GROUP BY ${groupExprs.join(', ')}`;
     // HAVING, filter whole groups by their aggregate values.
@@ -1026,7 +1027,7 @@ const PERCENTILE_HINT = {
     mssql: 'Percentile aggregates are not available on SQL Server in this release: PERCENTILE_CONT is a window ' +
         'function there, not an aggregate.',
 };
-const PERCENTILE_SPEC_KEYS = ['p', 'method'];
+const PERCENTILE_SPEC_KEYS = ['p', 'method', 'of'];
 const PERCENTILE_METHODS = ['cont', 'disc'];
 const PERCENTILE_NOT_ORDERABLE = 'ordering or filtering groups by _percentile is not supported yet.';
 /**
@@ -1041,8 +1042,14 @@ const PERCENTILE_NOT_ORDERABLE = 'ordering or filtering groups by _percentile is
  * form), a JSON-path target, and two keys naming one column. Both methods need
  * `includePii: UNSAFE` on a PII column: `disc` returns a stored cell, and so
  * does `cont` at p = 0 or 1 or over a one-row group.
+ *
+ * A key with `of` names an expression's result (see `PercentileExprSpec`): it
+ * must not name a field, the expression compiles through `compileReadExpr`,
+ * it is ordered as `float8`, and its SQL alias is `_percentile_of_<n>`, so the
+ * caller's name never reaches the SQL. Every PII column it reads as a value
+ * needs `includePii: UNSAFE`, as a column percentile does.
  */
-function planPercentiles(qi, spec, params, includePii, operation, claimResultKey) {
+function planPercentiles(qi, spec, params, includePii, operation, claimResultKey, resultKeyTaken) {
     if (spec === undefined)
         return [];
     const where = `${operation} _percentile on table "${qi.table}"`;
@@ -1058,6 +1065,16 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
     const meta = qi.schema.tables[qi.table];
     const plans = [];
     const aliases = new Set();
+    // Column aliases are `_percentile_<column>`; an expression's is the first
+    // free `_percentile_of_<n>`, chosen after every column alias is known so a
+    // column named `of_0` keeps its own.
+    const columnAliases = new Set();
+    for (const [key] of entries) {
+        const column = resolveColumnName(qi.tableMeta, key);
+        if (column !== undefined)
+            columnAliases.add(`_percentile_${column}`);
+    }
+    let exprCount = 0;
     for (const [key, entry] of entries) {
         const label = `${where}, field "${key}"`;
         if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
@@ -1072,7 +1089,7 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
                 throw new ValidationError(`${label}: unknown key "${k}".${hint ? ` Did you mean "${hint}"?` : ''} Expected { p, method? }.`);
             }
         }
-        const { p, method = 'cont' } = entry;
+        const { p, method = 'cont', of } = entry;
         if (!PERCENTILE_METHODS.includes(method)) {
             throw new ValidationError(`${label}: method must be 'cont' or 'disc', received ${describeValue(method)}.`);
         }
@@ -1085,6 +1102,10 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
         else {
             assertFraction(p, label);
         }
+        if (of !== undefined) {
+            plans.push(planExpressionPercentile(qi, key, of, p, method, params, includePii, operation, label, aliases, columnAliases, exprCount++, claimResultKey, resultKeyTaken));
+            continue;
+        }
         const col = qi.toColumn(key);
         if (method === 'cont' && qi.tableMeta.dateColumns.has(col)) {
             throw new ValidationError(`${label}: method 'cont' interpolates and needs a numeric or interval column, and "${col}" is a ` +
@@ -1114,6 +1135,51 @@ function planPercentiles(qi, spec, params, includePii, operation, claimResultKey
     }
     return plans;
 }
+/** One `_percentile` entry over an expression (`of`); see {@link planPercentiles}. */
+function planExpressionPercentile(qi, key, of, p, method, params, includePii, operation, label, aliases, columnAliases, index, claimResultKey, resultKeyTaken) {
+    const column = resolveColumnName(qi.tableMeta, key);
+    if (column !== undefined) {
+        throw new ValidationError(`${label}: "${key}" is a field of the table, and \`of\` names an expression. Give the expression a name ` +
+            `that is not a field (the name is only its result's key), or drop \`of\` for the percentile of "${key}".`);
+    }
+    const compiled = compileReadExpr({
+        qi,
+        name: key,
+        operation: `${operation} _percentile`,
+        bind: (value, cls) => {
+            params.push(value);
+            return `${qi.p(params.length)}::${cls === 'int' ? 'int8' : 'numeric'}`;
+        },
+        predicate: (when) => {
+            const sql = whereMod.buildWhereClause(qi, when, params);
+            if (sql === null)
+                throw new ValidationError(`${label}: an expr.case() arm's when compiles to no predicate.`);
+            return sql;
+        },
+    }, of);
+    const meta = qi.schema.tables[qi.table];
+    for (const col of compiled.values) {
+        const field = qi.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
+        assertAggregatePiiOptIn(qi.table, meta, field, col, `${operation} _percentile "${key}"`, includePii);
+    }
+    // The caller's key never names the alias, so it skips every name already
+    // taken, a groupBy key included, rather than collide with one.
+    let n = index;
+    const taken = (alias) => aliases.has(alias) || columnAliases.has(alias) || resultKeyTaken?.(alias) === true;
+    while (taken(`_percentile_of_${n}`))
+        n++;
+    const alias = `_percentile_of_${n}`;
+    aliases.add(alias);
+    claimResultKey?.(alias, `_percentile "${key}"`);
+    params.push(Array.isArray(p) ? [...p] : p);
+    const fractions = `${qi.p(params.length)}::float8${Array.isArray(p) ? '[]' : ''}`;
+    return {
+        expr: `percentile_${method}(${fractions}) WITHIN GROUP (ORDER BY (${compiled.sql})::float8) AS ${qi.q(alias)}`,
+        alias,
+        field: key,
+        col: null,
+    };
+}
 function assertFraction(value, label) {
     if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1)
         return;
@@ -1155,6 +1221,10 @@ function readPercentiles(qi, plans, row) {
 function percentileElement(qi, col, value) {
     if (value === null || value === undefined)
         return null;
+    // An expression is ordered as float8, which the driver reads as a number
+    // (a supplied pool's own parser may hand back text).
+    if (col === null)
+        return typeof value === 'string' ? Number(value) : value;
     if (typeof value === 'string' && isInt8Type(whereMod.getColumnPgType(qi, col))) {
         const n = Number(value);
         return Number.isSafeInteger(n) ? n : value;

package/dist/query/builder.d.ts

@@ -12,7 +12,7 @@
  */
 import type { PgCompatPool } from '../pg-types.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResultOf, CountArgs, CreateArgs, CreateManyArgs, DefaultInputTypes, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TableInputTypes, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
+import type { AggregateArgs, AggregateResultOf, CountArgs, CreateArgs, CreateManyArgs, CreateManyResult, DefaultInputTypes, DeleteArgs, DeleteManyArgs, FieldPercentiles, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, PercentileKeysChecked, QueryResult, TableInputTypes, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 /**
  * Marginal cost of keeping a to-one relation on the JOIN plan, per parent row.
  *
@@ -1180,7 +1180,12 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
      * writes.ts because relations.ts imports writes.ts.
      */
     private resolveWriteProjection;
-    buildCreateMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateManyArgs<T, M['createMany'], S, O>): DeferredQuery<FieldResult<T, S, O>[]>;
+    buildCreateMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined, C extends boolean | undefined = undefined>(args: CreateManyArgs<T, M['createMany'], S, O, C>): DeferredQuery<CreateManyResult<FieldResult<T, S, O>, C>>;
+    /**
+     * `createMany`'s projection: the caller's `select` / `omit`, or
+     * {@link writesMod.COUNT_ONLY} for `returning: false`, which takes neither.
+     */
+    private createManyProjection;
     buildUpdate<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O, M['update']>): DeferredQuery<FieldResult<T, S, O>>;
     buildDelete<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: DeleteArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
     buildUpsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O, M['whereUnique'], M['createMany'], M['updateMany']>): DeferredQuery<FieldResult<T, S, O>>;
@@ -1416,7 +1421,7 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
     findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O, M['whereUnique']>): Promise<QueryResult<T, R, W, S, O>>;
     buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O, M['whereUnique']>): DeferredQuery<QueryResult<T, R, W, S, O>>;
     create<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, R, S, O, M['create']>): Promise<FieldResult<T, S, O>>;
-    createMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateManyArgs<T, M['createMany'], S, O>): Promise<FieldResult<T, S, O>[]>;
+    createMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined, C extends boolean | undefined = undefined>(args: CreateManyArgs<T, M['createMany'], S, O, C>): Promise<CreateManyResult<FieldResult<T, S, O>, C>>;
     update<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O, M['update']>): Promise<FieldResult<T, S, O>>;
     private nestedCreate;
     private nestedUpdate;
@@ -1477,10 +1482,18 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
      * {@link GroupByResult}). Grouping by a JSON-path key yields a runtime alias
      * that cannot be typed, so those columns are not projected onto the row type.
      */
-    groupBy<A extends GroupByArgs<T, R>>(args: A): Promise<GroupByResult<T, A>[]>;
-    buildGroupBy<A extends GroupByArgs<T, R>>(args: A): DeferredQuery<GroupByResult<T, A>[]>;
-    buildAggregate<A extends AggregateArgs<T, R>>(args: A): DeferredQuery<AggregateResultOf<T, A>>;
-    aggregate<A extends AggregateArgs<T, R>>(args: A): Promise<AggregateResultOf<T, A>>;
+    groupBy<A extends GroupByArgs<T, R>>(args: A & PercentileKeysChecked<T, A>): Promise<GroupByResult<T, A>[]>;
+    /** Args of a generic type: field percentiles only (see {@link FieldPercentiles}). */
+    groupBy<A extends Omit<GroupByArgs<T, R>, '_percentile'> & FieldPercentiles<T>>(args: A): Promise<GroupByResult<T, A>[]>;
+    buildGroupBy<A extends GroupByArgs<T, R>>(args: A & PercentileKeysChecked<T, A>): DeferredQuery<GroupByResult<T, A>[]>;
+    /** Args of a generic type: field percentiles only (see {@link FieldPercentiles}). */
+    buildGroupBy<A extends Omit<GroupByArgs<T, R>, '_percentile'> & FieldPercentiles<T>>(args: A): DeferredQuery<GroupByResult<T, A>[]>;
+    buildAggregate<A extends AggregateArgs<T, R>>(args: A & PercentileKeysChecked<T, A>): DeferredQuery<AggregateResultOf<T, A>>;
+    /** Args of a generic type: field percentiles only (see {@link FieldPercentiles}). */
+    buildAggregate<A extends Omit<AggregateArgs<T, R>, '_percentile'> & FieldPercentiles<T>>(args: A): DeferredQuery<AggregateResultOf<T, A>>;
+    aggregate<A extends AggregateArgs<T, R>>(args: A & PercentileKeysChecked<T, A>): Promise<AggregateResultOf<T, A>>;
+    /** Args of a generic type: field percentiles only (see {@link FieldPercentiles}). */
+    aggregate<A extends Omit<AggregateArgs<T, R>, '_percentile'> & FieldPercentiles<T>>(args: A): Promise<AggregateResultOf<T, A>>;
     private resolveColumns;
     withFingerprint(withClause: WithClause | undefined, table?: string, depth?: number): string;
     private collectWithParams;

package/dist/query/builder.js

@@ -3010,7 +3010,24 @@ export class QueryInterface {
     }
     buildCreateMany(args) {
         args = this.normalizeArgs(args);
-        return writesMod.buildCreateMany(this.ctx, args, 'refuse', this.resolveWriteProjection(args));
+        return writesMod.buildCreateMany(this.ctx, args, 'refuse', this.createManyProjection(args));
+    }
+    /**
+     * `createMany`'s projection: the caller's `select` / `omit`, or
+     * {@link writesMod.COUNT_ONLY} for `returning: false`, which takes neither.
+     */
+    createManyProjection(args) {
+        const { returning } = args;
+        if (returning === undefined || returning === true)
+            return this.resolveWriteProjection(args);
+        if (returning !== false) {
+            throw new ValidationError(`createMany on "${this.table}": returning must be true or false, received ${typeof returning}.`);
+        }
+        if (args.select !== undefined || args.omit !== undefined) {
+            throw new ValidationError(`createMany on "${this.table}": returning: false returns { count } and no rows, so it takes no ` +
+                `\`${args.select !== undefined ? 'select' : 'omit'}\`. Drop one of them.`);
+        }
+        return writesMod.COUNT_ONLY;
     }
     buildUpdate(args) {
         args = this.normalizeArgs(args);
@@ -4403,13 +4420,17 @@ export class QueryInterface {
     async createMany(args) {
         args = this.normalizeArgs(args);
         return this.executeWithMiddleware('createMany', args, async () => {
-            const projection = this.resolveWriteProjection(args);
+            const projection = this.createManyProjection(args);
+            const countOnly = writesMod.isCountOnly(projection);
             const base = args;
             // One statement when the rows fit the engine's per-statement limits,
             // else chunks that do, all in one transaction so the rows land together
             // or not at all. (`buildCreateMany`, one statement for a pipeline,
             // refuses instead.)
-            const { chunks, rowsPerChunk } = writesMod.planCreateMany(this.ctx, base, projection);
+            // Splitting a call that fits one statement needs a transaction, which a
+            // pool without connect() cannot open outside one.
+            const canSplit = this.txScoped || typeof this.pool.connect === 'function';
+            const { chunks, rowsPerChunk } = writesMod.planCreateMany(this.ctx, base, projection, canSplit);
             const run = async () => {
                 // An engine that applies two rows whose onConflict keys are equal only
                 // under the column's collation (SQLite's NOCASE) as an insert and an
@@ -4425,13 +4446,18 @@ export class QueryInterface {
                 const reselects = this.dialect.resultStrategy === 'reselect';
                 return this.inOneTransaction(async (exec) => {
                     const rows = [];
+                    let count = 0;
                     for (const chunk of chunks) {
                         const result = reselects && chunk.reselect
                             ? await chunk.reselect(exec)
                             : await exec(chunk.sql, chunk.params, chunk.preparedName);
-                        rows.push(...chunk.transform(result));
+                        const out = chunk.transform(result);
+                        if (countOnly)
+                            count += out.count;
+                        else
+                            rows.push(...out);
                     }
-                    return rows;
+                    return (countOnly ? { count } : rows);
                 }, args.timeout, `createMany of ${base.data.length} rows`, `Insert at most ${rowsPerChunk} rows per call, which fits one statement, or pass a pool that can check ` +
                     'out a connection.');
             };
@@ -4721,17 +4747,6 @@ export class QueryInterface {
             preparedName: entry.name,
         };
     }
-    // -------------------------------------------------------------------------
-    // groupBy (with aggregate functions)
-    // -------------------------------------------------------------------------
-    /**
-     * Group rows and compute per-group aggregates (Prisma-style). The result row
-     * type is INFERRED from the args: each `by` field carries its entity field
-     * type, `_count` is always a number, and each requested `_sum` / `_avg` /
-     * `_min` / `_max` block maps its fields to properly typed values (see
-     * {@link GroupByResult}). Grouping by a JSON-path key yields a runtime alias
-     * that cannot be typed, so those columns are not projected onto the row type.
-     */
     async groupBy(args) {
         args = this.normalizeArgs(args);
         return this.executeWithMiddleware('groupBy', args, async () => {
@@ -4740,9 +4755,6 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
-    // ---------------------------------------------------------------------------
-    // Aggregate / groupBy compilation (extracted to aggregates.ts).
-    // ---------------------------------------------------------------------------
     buildGroupBy(args) {
         const normalized = this.normalizeArgs(args);
         return this.withPreparedName(() => aggMod.buildGroupBy(this.ctx, normalized));
@@ -4751,9 +4763,6 @@ export class QueryInterface {
         const normalized = this.normalizeArgs(args);
         return this.withPreparedName(() => aggMod.buildAggregate(this.ctx, normalized));
     }
-    // -------------------------------------------------------------------------
-    // aggregate, standalone aggregation without groupBy
-    // -------------------------------------------------------------------------
     async aggregate(args) {
         args = this.normalizeArgs(args);
         return this.executeWithMiddleware('aggregate', args, async () => {

package/dist/query/expr.d.ts

@@ -124,6 +124,19 @@ export declare const expr: Readonly<{
      * value). Refused anywhere else.
      */
     excluded<F extends string>(field: F): ExcludedRef<F>;
+    /**
+     * The seconds from `from` to `to`, two timestamp columns of the row:
+     * `to - from`, fractional, negative when `to` is earlier, NULL when either is.
+     * Both columns must be timestamptz, or both zone-less timestamp. Accepted in
+     * `_percentile`'s `of` (PostgreSQL); refused in update data in this release.
+     *
+     * ```ts
+     * await db.jobs.aggregate({
+     *   _percentile: { wait: { of: expr.secondsBetween(col('requestedAt'), col('readyAt')), p: [0.5, 0.95] } },
+     * });
+     * ```
+     */
+    secondsBetween(from: ColumnRef, to: ColumnRef): SqlExpr<number>;
 }>;
 /** True only for a node built by {@link expr} (any loaded copy of the package). */
 export declare function isSqlExpr(value: unknown): value is SqlExpr;
@@ -167,6 +180,12 @@ export interface ExprCompileEnv {
     readonly insertColumns?: ReadonlySet<string> | undefined;
     /** Compile a `case` arm's predicate (already pruned and validated) against the target row. */
     predicate(when: Record<string, unknown>): string;
+    /**
+     * The expression is READ by a query (`_percentile`'s `of`), not assigned:
+     * there is no target column, `targetKey` is the result's name, and
+     * `expr.secondsBetween` is accepted while `expr.now` is not.
+     */
+    readonly read?: true | undefined;
 }
 /** One compiled expression. */
 export interface CompiledSetExpr {
@@ -197,6 +216,34 @@ export interface CompiledSetExpr {
  * cache key does not capture.
  */
 export declare function compileSetExpr(env: ExprCompileEnv, value: SqlExpr | ColumnRef): CompiledSetExpr;
+/** What {@link compileReadExpr} needs from its caller (the aggregate module). */
+export interface ReadExprEnv {
+    readonly qi: BuilderCtx;
+    /** The result's name, for messages. */
+    readonly name: string;
+    /** For messages: `aggregate _percentile`, `groupBy _percentile`. */
+    readonly operation: string;
+    /** Bind one number, bigint or null and return its placeholder, cast to its class's type. */
+    bind(value: number | bigint | null, cls: 'int' | 'dec'): string;
+    /** Compile a `case` arm's predicate (already pruned and validated) against the row. */
+    predicate(when: Record<string, unknown>): string;
+}
+/** One compiled read expression. */
+export interface CompiledReadExpr {
+    readonly sql: string;
+    /** Value-free shape, as {@link CompiledSetExpr.fingerprint}. */
+    readonly fingerprint: string;
+    /** Columns the expression reads as a value (columns only a case arm's `when` reads are not). */
+    readonly values: ReadonlySet<string>;
+}
+/**
+ * Compile a numeric expression a query READS (`_percentile`'s `of`): the walk
+ * {@link compileSetExpr} runs, with no target column. Bound values must be
+ * numbers or bigints and are cast by their own class, the result must be
+ * numeric, and `col()` alone is refused because a field key already says it.
+ * Not gated on `updateExpressions`: the caller's own engine check applies.
+ */
+export declare function compileReadExpr(read: ReadExprEnv, value: unknown): CompiledReadExpr;
 /**
  * Rewrite every `expr.excluded(f)` in a single-row upsert's `update` to the
  * value `create` supplies for `f`. The incoming row of a one-row upsert IS

package/dist/query/expr.js

@@ -44,6 +44,7 @@ const EXPR_KINDS = new Set([
     'case',
     'now',
     'excluded',
+    'secondsBetween',
 ]);
 /** Operand count bounds for coalesce / greatest / least. */
 const MIN_VARIADIC = 2;
@@ -161,6 +162,20 @@ function caseNode(arms, otherwise) {
         assertOperand('case', arms.length, otherwise);
     return makeNode('case', frozen, otherwise === undefined ? undefined : { else: otherwise });
 }
+function secondsBetweenNode(from, to) {
+    [from, to].forEach((operand, i) => {
+        if (isColumnRef(operand))
+            return;
+        const at = `expr.secondsBetween(): operand ${i + 1}`;
+        if (isPlainColumnRefShape(operand)) {
+            const name = JSON.stringify(operand.col);
+            throw new ValidationError(`${at} is a plain { col: ${name} } object, not a column reference. Build one with col(${name}).`);
+        }
+        throw new ValidationError(`${at} is ${operand === undefined ? 'undefined' : describeOperand(operand)}. Both operands are col() of a ` +
+            'timestamp column of the row.');
+    });
+    return makeNode('secondsBetween', [from, to]);
+}
 /**
  * Builders for SQL expressions in update data. Each returns a frozen, branded
  * node; the SQL is generated per engine when the update compiles.
@@ -246,6 +261,21 @@ export const expr = Object.freeze({
         Object.defineProperty(node, EXCLUDED_REF, { value: true, enumerable: false });
         return Object.freeze(node);
     },
+    /**
+     * The seconds from `from` to `to`, two timestamp columns of the row:
+     * `to - from`, fractional, negative when `to` is earlier, NULL when either is.
+     * Both columns must be timestamptz, or both zone-less timestamp. Accepted in
+     * `_percentile`'s `of` (PostgreSQL); refused in update data in this release.
+     *
+     * ```ts
+     * await db.jobs.aggregate({
+     *   _percentile: { wait: { of: expr.secondsBetween(col('requestedAt'), col('readyAt')), p: [0.5, 0.95] } },
+     * });
+     * ```
+     */
+    secondsBetween(from, to) {
+        return secondsBetweenNode(from, to);
+    },
 });
 /** True only for a node built by {@link expr} (any loaded copy of the package). */
 export function isSqlExpr(value) {
@@ -437,6 +467,12 @@ function isBareStructuredCopy(qi, column, value) {
     const type = columnType(qi, column);
     return source !== undefined && type !== undefined && columnType(qi, source) === type;
 }
+/** Where an expression sits, for messages. */
+function site(env) {
+    return env.read
+        ? `${env.operation} "${env.targetKey}" on "${env.qi.table}"`
+        : `${env.operation} data on "${env.qi.table}.${env.targetKey}"`;
+}
 /**
  * Compile one expression (or `col()` reference) assigned to `env.targetKey`.
  * The single traversal: SQL, params (through `env.bind`, in emission order)
@@ -457,7 +493,7 @@ export function compileSetExpr(env, value) {
     const { qi } = env;
     assertEngine(qi);
     const column = assertExprTarget(qi, env.targetKey, value, env.operation);
-    const state = { env, targetType: columnType(qi, column), reads: new Set() };
+    const state = { env, targetType: columnType(qi, column), reads: new Set(), values: new Set() };
     const part = walkOperand(state, value, false, 0);
     if (part.cls === 'dec' && numClassOfType(state.targetType) === 'int') {
         const what = isColumnRef(value) ? `col(${JSON.stringify(value.col)})` : `expr.${value.kind}()`;
@@ -469,6 +505,48 @@ export function compileSetExpr(env, value) {
     }
     return { sql: part.sql, fingerprint: part.fp, reads: state.reads };
 }
+/**
+ * Compile a numeric expression a query READS (`_percentile`'s `of`): the walk
+ * {@link compileSetExpr} runs, with no target column. Bound values must be
+ * numbers or bigints and are cast by their own class, the result must be
+ * numeric, and `col()` alone is refused because a field key already says it.
+ * Not gated on `updateExpressions`: the caller's own engine check applies.
+ */
+export function compileReadExpr(read, value) {
+    const { qi, name, operation } = read;
+    const at = `${operation} "${name}" on "${qi.table}"`;
+    if (isColumnRef(value)) {
+        throw new ValidationError(`${at}: \`of\` is col(${JSON.stringify(value.col)}) alone. Use the field as the key instead: ` +
+            `{ ${JSON.stringify(value.col)}: { p } }.`);
+    }
+    if (!isSqlExpr(value)) {
+        throw new ValidationError(`${at}: \`of\` is ${value === undefined ? 'undefined' : describeOperand(value)}. Build it with expr ` +
+            "(import { col, expr } from 'turbine-orm'); a plain object is never an expression.");
+    }
+    const env = {
+        qi,
+        targetKey: name,
+        operation,
+        read: true,
+        bind: (leaf, arithmetic) => {
+            if (leaf !== null && typeof leaf !== 'number' && typeof leaf !== 'bigint') {
+                throw new ValidationError(`${at}: a bound value is ${leaf instanceof Date ? 'a Date' : leaf instanceof Uint8Array ? 'a Uint8Array' : `a ${typeof leaf}`}. ` +
+                    'An expression a query reads binds numbers and bigints only.');
+            }
+            const integer = (arithmetic ?? numClassOfValue(leaf)) !== 'dec' && (typeof leaf !== 'number' || Number.isSafeInteger(leaf));
+            return read.bind(leaf, integer ? 'int' : 'dec');
+        },
+        column: (column) => qi.q(column),
+        predicate: (when) => read.predicate(when),
+    };
+    const state = { env, targetType: undefined, reads: new Set(), values: new Set() };
+    const part = walkOperand(state, value, false, 0);
+    if (part.cls === 'other' || part.cls === 'null') {
+        throw new ValidationError(`${at}: \`of\` is ${part.cls === 'null' ? 'NULL for every row' : 'not numeric (it reads a non-numeric column)'}. ` +
+            'A percentile orders numbers: numeric columns, bound numbers, and expr.secondsBetween() of two timestamps.');
+    }
+    return { sql: part.sql, fingerprint: part.fp, values: state.values };
+}
 function assertEngine(qi) {
     if (qi.dialect.capabilities.updateExpressions)
         return;
@@ -481,6 +559,7 @@ function walkOperand(state, value, inArithmetic, depth) {
     if (isColumnRef(value)) {
         const column = resolveOperandColumn(state, value.col, 'col', inArithmetic);
         state.reads.add(column);
+        state.values.add(column);
         return { sql: state.env.column(column), fp: `c:${column}`, cls: numClassOfType(columnType(state.env.qi, column)) };
     }
     if (isSqlExpr(value))
@@ -492,7 +571,7 @@ function walkOperand(state, value, inArithmetic, depth) {
     // greatest, least or a case arm (`expr.add(expr.coalesce('x', 1), 2)`).
     if (inArithmetic &&
         (typeof value === 'string' || typeof value === 'boolean' || value instanceof Date || value instanceof Uint8Array)) {
-        throw new ValidationError(`An arithmetic operand in ${state.env.operation} data on "${state.env.qi.table}.${state.env.targetKey}" is a ` +
+        throw new ValidationError(`An arithmetic operand in ${site(state.env)} is a ` +
             `${value instanceof Date ? 'Date' : value instanceof Uint8Array ? 'Uint8Array' : typeof value}. ` +
             'Arithmetic takes numbers, bigints, col() of a numeric column, or numeric expressions.');
     }
@@ -509,7 +588,7 @@ function resolveOperandColumn(state, field, how, inArithmetic) {
     const call = how === 'col' ? `col(${JSON.stringify(field)})` : `expr.excluded(${JSON.stringify(field)})`;
     const column = resolveColumnName(qi.tableMeta, field);
     if (column === undefined) {
-        throw new ValidationError(`${call} in ${state.env.operation} data on "${qi.table}" names no column. ` +
+        throw new ValidationError(`${call} in ${site(state.env)} names no column. ` +
             `Known fields: ${Object.keys(qi.tableMeta.columnMap).join(', ') || '(none)'}.`);
     }
     const cls = columnClass(columnType(qi, column));
@@ -569,6 +648,9 @@ function walkNode(state, node, inArithmetic, depth) {
         case 'case':
             return walkCase(state, node, inArithmetic, depth);
         case 'now': {
+            if (env.read) {
+                throw new ValidationError(`expr.now() in ${site(env)}: an expression a query reads takes the row's columns and bound numbers only.`);
+            }
             if (inArithmetic) {
                 throw new ValidationError('expr.now() cannot be an arithmetic operand: date arithmetic is not supported.');
             }
@@ -592,6 +674,8 @@ function walkNode(state, node, inArithmetic, depth) {
             }
             return { sql: env.excluded(column), fp: `x:${column}`, cls: numClassOfType(columnType(qi, column)) };
         }
+        case 'secondsBetween':
+            return walkSecondsBetween(state, node);
         default:
             throw new ValidationError(`Unknown expression kind "${String(node.kind)}".`);
     }
@@ -623,6 +707,47 @@ function walkCase(state, node, inArithmetic, depth) {
         cls: combineClasses(classes),
     };
 }
+/**
+ * `expr.secondsBetween(from, to)`: `EXTRACT(EPOCH FROM (to - from))`, the
+ * PostgreSQL spelling. It is read only by `_percentile`, which only an engine
+ * with `supportsPercentileAggregates` runs, and that SQL (`percentile_cont ...
+ * WITHIN GROUP`) is PostgreSQL's too. Both columns must have one temporal
+ * kind: subtracting a timestamptz from a zone-less timestamp converts through
+ * the session time zone.
+ */
+function walkSecondsBetween(state, node) {
+    const { env } = state;
+    const { qi } = env;
+    if (!env.read) {
+        throw new ValidationError(`expr.secondsBetween() in ${site(env)}: it is accepted in _percentile's \`of\` in this release, not in ` +
+            'update data. Compute the value in JavaScript and write it as a plain value.');
+    }
+    const kinds = [];
+    const columns = node.args.map((arg) => {
+        const field = arg.col;
+        const column = resolveOperandColumn(state, field, 'col', false);
+        const type = columnType(qi, column);
+        const kind = temporalKind(type);
+        if (kind !== 'tz' && kind !== 'timestamp') {
+            throw new ValidationError(`expr.secondsBetween() in ${site(env)}: col(${JSON.stringify(field)}) is ${type === undefined ? 'a column of unknown type' : `a ${type} column`}. ` +
+                'Both operands must be timestamp (or both timestamptz) columns.');
+        }
+        kinds.push(kind);
+        state.reads.add(column);
+        state.values.add(column);
+        return column;
+    });
+    if (kinds[0] !== kinds[1]) {
+        throw new ValidationError(`expr.secondsBetween() in ${site(env)} mixes a timestamptz column with a zone-less timestamp column, ` +
+            'whose difference depends on the session time zone. Use two columns of one kind.');
+    }
+    const [from, to] = columns;
+    return {
+        sql: `EXTRACT(EPOCH FROM (${env.column(to)} - ${env.column(from)}))`,
+        fp: `secs(${from},${to})`,
+        cls: 'dec',
+    };
+}
 /**
  * Prune and validate one arm's `when`: `undefined` keys drop out (the C1 rule
  * for every `where` position), an arm left with no predicate is refused, and

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonEncoding, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderBySpec, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationOrderBy, RelationOrderByChain, RelationPickBy, RelationPickOrderBy, ResolvedSkipGlobalFilters, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, CreateManyCount, CreateManyResult, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonEncoding, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderBySpec, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationOrderBy, RelationOrderByChain, RelationPickBy, RelationPickOrderBy, ResolvedSkipGlobalFilters, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export { col } from './column-ref.js';

package/dist/query/option-surface.js

@@ -136,6 +136,9 @@ export const CREATE_MANY_OPTIONS = {
     onConflict: 'internal',
     select: 'internal',
     omit: 'internal',
+    // Compat's createMany already resolves to Prisma's { count } and sets this
+    // itself; a caller-supplied value would change the shape it relies on.
+    returning: 'internal',
     timeout: 'native',
     skipGlobalFilters: 'native',
 };