turbine-orm 0.90.2 → 0.91.0

package/dist/cjs/query/builder.js

@@ -3048,7 +3048,24 @@ 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 errors_js_1.ValidationError(`createMany on "${this.table}": returning must be true or false, received ${typeof returning}.`);
+        }
+        if (args.select !== undefined || args.omit !== undefined) {
+            throw new errors_js_1.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);
@@ -4441,13 +4458,17 @@ 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
@@ -4463,13 +4484,18 @@ 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.');
             };
@@ -4759,17 +4785,6 @@ 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 () => {
@@ -4778,9 +4793,6 @@ 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));
@@ -4789,9 +4801,6 @@ 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/cjs/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/cjs/query/expr.js

@@ -32,6 +32,7 @@ exports.plainExprShapeMessage = plainExprShapeMessage;
 exports.exprNotAllowedMessage = exprNotAllowedMessage;
 exports.assertExprTarget = assertExprTarget;
 exports.compileSetExpr = compileSetExpr;
+exports.compileReadExpr = compileReadExpr;
 exports.resolveExcludedFromCreate = resolveExcludedFromCreate;
 const errors_js_1 = require("../errors.js");
 const column_ref_js_1 = require("./column-ref.js");
@@ -55,6 +56,7 @@ const EXPR_KINDS = new Set([
     'case',
     'now',
     'excluded',
+    'secondsBetween',
 ]);
 /** Operand count bounds for coalesce / greatest / least. */
 const MIN_VARIADIC = 2;
@@ -172,6 +174,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 ((0, column_ref_js_1.isColumnRef)(operand))
+            return;
+        const at = `expr.secondsBetween(): operand ${i + 1}`;
+        if ((0, column_ref_js_1.isPlainColumnRefShape)(operand)) {
+            const name = JSON.stringify(operand.col);
+            throw new errors_js_1.ValidationError(`${at} is a plain { col: ${name} } object, not a column reference. Build one with col(${name}).`);
+        }
+        throw new errors_js_1.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.
@@ -257,6 +273,21 @@ exports.expr = Object.freeze({
         Object.defineProperty(node, exports.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). */
 function isSqlExpr(value) {
@@ -448,6 +479,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)
@@ -468,7 +505,7 @@ 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 = (0, column_ref_js_1.isColumnRef)(value) ? `col(${JSON.stringify(value.col)})` : `expr.${value.kind}()`;
@@ -480,6 +517,48 @@ 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.
+ */
+function compileReadExpr(read, value) {
+    const { qi, name, operation } = read;
+    const at = `${operation} "${name}" on "${qi.table}"`;
+    if ((0, column_ref_js_1.isColumnRef)(value)) {
+        throw new errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.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;
@@ -492,6 +571,7 @@ function walkOperand(state, value, inArithmetic, depth) {
     if ((0, column_ref_js_1.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))
@@ -503,7 +583,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 errors_js_1.ValidationError(`An arithmetic operand in ${state.env.operation} data on "${state.env.qi.table}.${state.env.targetKey}" is a ` +
+        throw new errors_js_1.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.');
     }
@@ -520,7 +600,7 @@ function resolveOperandColumn(state, field, how, inArithmetic) {
     const call = how === 'col' ? `col(${JSON.stringify(field)})` : `expr.excluded(${JSON.stringify(field)})`;
     const column = (0, utils_js_1.resolveColumnName)(qi.tableMeta, field);
     if (column === undefined) {
-        throw new errors_js_1.ValidationError(`${call} in ${state.env.operation} data on "${qi.table}" names no column. ` +
+        throw new errors_js_1.ValidationError(`${call} in ${site(state.env)} names no column. ` +
             `Known fields: ${Object.keys(qi.tableMeta.columnMap).join(', ') || '(none)'}.`);
     }
     const cls = columnClass(columnType(qi, column));
@@ -580,6 +660,9 @@ function walkNode(state, node, inArithmetic, depth) {
         case 'case':
             return walkCase(state, node, inArithmetic, depth);
         case 'now': {
+            if (env.read) {
+                throw new errors_js_1.ValidationError(`expr.now() in ${site(env)}: an expression a query reads takes the row's columns and bound numbers only.`);
+            }
             if (inArithmetic) {
                 throw new errors_js_1.ValidationError('expr.now() cannot be an arithmetic operand: date arithmetic is not supported.');
             }
@@ -603,6 +686,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 errors_js_1.ValidationError(`Unknown expression kind "${String(node.kind)}".`);
     }
@@ -634,6 +719,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 errors_js_1.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 errors_js_1.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 errors_js_1.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/cjs/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/cjs/query/option-surface.js

@@ -142,6 +142,9 @@ exports.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',
 };

package/dist/cjs/query/types.d.ts

@@ -1034,7 +1034,7 @@ export interface CreateArgs<T, R extends object = {}, S extends Record<string, b
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number | undefined;
 }
-export interface CreateManyArgs<T, D = OptionalInput<T>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
+export interface CreateManyArgs<T, D = OptionalInput<T>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined, C extends boolean | undefined = true | undefined> {
     /** The rows. A generated client passes its `XCreate` as `D`. */
     data: D[];
     /** Skip rows that conflict on ANY unique constraint (ON CONFLICT DO NOTHING). */
@@ -1052,6 +1052,22 @@ export interface CreateManyArgs<T, D = OptionalInput<T>, S extends Record<string
     select?: FlagsArg<T, S>;
     /** Return the written rows without these fields. Same rules as `select`. */
     omit?: FlagsArg<T, O>;
+    /**
+     * `false` resolves to `{ count }`, the number of rows written, instead of the
+     * rows. A plain insert then sends no `RETURNING` / `OUTPUT` at all; an
+     * `onConflict` call returns only the key columns it needs to refuse two input
+     * rows that write one table row. The count is the number of rows the call
+     * would otherwise have returned: inserted plus updated, never a row
+     * `skipDuplicates` or `ignore` skipped. Cannot be combined with `select` or
+     * `omit` (E003). On MySQL, `skipDuplicates` with `false` is E017: a skipped
+     * row there counts as written.
+     *
+     * Typed by `C`, which defaults to the rows form, so args typed ahead of the
+     * call (`const args: CreateManyArgs<User> = ...`) still resolve to rows.
+     * Pass `false` as `C` to type count-only args ahead of the call, or
+     * `boolean` for a flag known only at run time (the result is then either).
+     */
+    returning?: C;
     /**
      * Opt out of configured {@link GlobalFilters} on the conflict-UPDATE of
      * `onConflict` (inserts are never filtered). See {@link SkipGlobalFilters}.
@@ -1060,6 +1076,16 @@ export interface CreateManyArgs<T, D = OptionalInput<T>, S extends Record<string
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number | undefined;
 }
+/** What `createMany({ returning: false })` resolves to. */
+export interface CreateManyCount {
+    /** Rows written: inserted plus updated. */
+    count: number;
+}
+/**
+ * `createMany`'s result for a `returning` flag `C`: the rows for `true` or no
+ * flag, `{ count }` for `false`, either for a `boolean` known only at run time.
+ */
+export type CreateManyResult<Row, C> = [C] extends [false] ? CreateManyCount : [C] extends [true | undefined] ? Row[] : Row[] | CreateManyCount;
 /**
  * The columns of the primary key, or of one non-partial unique constraint or
  * index, in any order. A `createMany` conflict target.
@@ -1098,7 +1124,7 @@ export type ConflictUpdateData<T> = {
     [K in keyof T]?: T[K] | UpdateOperatorInput<T[K]> | SqlExpr<T[K]> | ColumnRef | ExcludedRef | undefined;
 };
 /** The node kinds an update expression is built from (see {@link SqlExpr}). */
-export type SqlExprKind = 'add' | 'sub' | 'mul' | 'div' | 'coalesce' | 'greatest' | 'least' | 'case' | 'now' | 'excluded';
+export type SqlExprKind = 'add' | 'sub' | 'mul' | 'div' | 'coalesce' | 'greatest' | 'least' | 'case' | 'now' | 'excluded' | 'secondsBetween';
 /** Carries the phantom result type of a {@link SqlExpr}. Type-level only. */
 declare const SQL_EXPR_RESULT: unique symbol;
 /**
@@ -1622,8 +1648,11 @@ export interface GroupByArgs<T, R extends object = {}> {
     _min?: GroupByAggregateSpec<T> | undefined;
     /** Maximum value of fields (or JSON paths) in each group */
     _max?: GroupByAggregateSpec<T> | undefined;
-    /** Percentiles of fields in each group (PostgreSQL only). See {@link PercentileSpec}. */
-    _percentile?: Partial<Record<keyof T & string, PercentileSpec>> | undefined;
+    /**
+     * Percentiles of fields, or of expressions, in each group (PostgreSQL only).
+     * See {@link PercentileSpec} and {@link PercentileExprSpec}.
+     */
+    _percentile?: PercentileArgs<T> | undefined;
     /** Filter whole groups by their aggregate values (SQL HAVING). JSON-path aggregates key by their alias. */
     having?: HavingClause<T> | undefined;
     /**
@@ -1769,9 +1798,19 @@ export interface AggregateArgs<T, R extends object = {}> {
      * s._percentile.statusCode; // number | null
      * ```
      *
-     * See {@link PercentileSpec}.
+     * A key that names no field computes the percentile of an expression,
+     * given as `of`:
+     *
+     * ```ts
+     * const s = await db.jobs.aggregate({
+     *   _percentile: { wait: { of: expr.secondsBetween(col('requestedAt'), col('readyAt')), p: 0.95 } },
+     * });
+     * s._percentile.wait; // number | null, in seconds
+     * ```
+     *
+     * See {@link PercentileSpec} and {@link PercentileExprSpec}.
      */
-    _percentile?: Partial<Record<keyof T & string, PercentileSpec>> | undefined;
+    _percentile?: PercentileArgs<T> | undefined;
     /**
      * Opt in to aggregating PII-tagged (`defineSchema` `pii: true`) columns.
      * `_min` / `_max` / `_percentile` return a STORED VALUE (or one that equals a
@@ -1836,11 +1875,72 @@ export type AggregateResultOf<T, A> = AggregateCountPart<A> & GroupBySumAvgPart<
 export interface PercentileSpec {
     p: number | readonly number[];
     method?: PercentileMethod | undefined;
+    /** Only on a key that names no field: see {@link PercentileExprSpec}. */
+    of?: undefined;
+}
+/**
+ * One `_percentile` entry over an expression, under a key that names no field
+ * (the key is only the result's name and never reaches the SQL).
+ *
+ * - `of`: a numeric expression over the row's own columns, built with
+ *   {@link expr}: arithmetic (`expr.add` / `sub` / `mul` / `div`),
+ *   `expr.coalesce` / `greatest` / `least` / `case`, and
+ *   `expr.secondsBetween(col('a'), col('b'))` for the seconds from one
+ *   timestamp column to another. Bound values must be numbers or bigints.
+ *   `col('x')` alone is refused: use the field key `x` instead.
+ * - `p` and `method` as in {@link PercentileSpec}. The expression is ordered as
+ *   double precision, so the result is a `number` for both methods (an integer
+ *   beyond 2^53 loses exactness).
+ *
+ * Every column the expression reads as a value needs `includePii: UNSAFE`
+ * when it is PII-tagged; columns read only by an `expr.case` arm's `when` do
+ * not. Over zero rows the result is `null`.
+ */
+export interface PercentileExprSpec {
+    of: SqlExpr<number | bigint | string>;
+    p: number | readonly number[];
+    method?: PercentileMethod | undefined;
 }
+/**
+ * The `_percentile` argument: field keys take a {@link PercentileSpec}; any
+ * other key names an expression's result and takes a {@link PercentileExprSpec}.
+ * On an untyped table (`keyof T` is `string`) any key takes either: the
+ * `string` key is dropped from the field half, which would otherwise narrow
+ * every key to a field spec.
+ */
+export type PercentileArgs<T> = {
+    [K in keyof T & string as string extends K ? never : K]?: PercentileSpec | undefined;
+} & {
+    [name: string]: PercentileSpec | PercentileExprSpec | undefined;
+};
+/**
+ * `_percentile` naming fields only. `aggregate` / `groupBy` take args of this
+ * shape when their type is generic, where {@link PercentileKeysChecked} cannot
+ * read the keys, so a wrapper generic over its args still compiles.
+ */
+export type FieldPercentiles<T> = {
+    _percentile?: {
+        [K in keyof T & string]?: PercentileSpec | undefined;
+    } | undefined;
+};
+/**
+ * Applied to `aggregate` / `groupBy` arguments: every `_percentile` key that
+ * names no field must carry `of`, so a misspelled field name is a compile
+ * error rather than an expression percentile with no expression.
+ */
+export type PercentileKeysChecked<T, A> = A extends {
+    _percentile: infer S;
+} ? [S] extends [object] ? {
+    _percentile: {
+        [K in keyof S]: K extends keyof T ? S[K] : PercentileExprSpec | undefined;
+    };
+} : unknown : unknown;
 /** `'cont'` interpolates (`percentile_cont`); `'disc'` returns a stored value (`percentile_disc`). */
 export type PercentileMethod = 'cont' | 'disc';
 /** One percentile value: the column's own type for `disc`; for `cont` a number, or an interval as the column reads. */
-type PercentileScalar<T, K, Spec> = K extends keyof T ? Spec extends {
+type PercentileScalar<T, K, Spec> = Spec extends {
+    of: object;
+} ? number : K extends keyof T ? Spec extends {
     method: 'disc';
 } ? NonNullable<T[K]> : [NonNullable<T[K]>] extends [number] ? number : number | NonNullable<T[K]> : unknown;
 /** A scalar `p` yields one value, an array `p` yields an array, `null` over zero rows. */

package/dist/cjs/query/writes.d.ts

@@ -91,7 +91,7 @@ export declare function buildCreateMany<T extends object>(qi: BuilderCtx, args:
  * builder (`skipGlobalFilters`), which a concurrent call could change across
  * an await.
  */
-export declare function planCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>, projection?: WriteProjection): {
+export declare function planCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>, projection?: WriteProjection, canSplit?: boolean): {
     chunks: DeferredQuery<T[]>[];
     rowsPerChunk: number;
 };
@@ -192,9 +192,21 @@ export declare function piiFields(_qi: BuilderCtx, meta: TableMetadata): string[
  * 34,500/s with `RETURNING *`.
  */
 export interface WriteProjection {
-    /** Unquoted column names, in table order. Never empty. */
+    /**
+     * Unquoted column names, in table order. Empty only for {@link COUNT_ONLY}:
+     * a caller's projection always names at least one column.
+     */
     readonly columns: readonly string[];
 }
+/**
+ * The projection of `createMany({ returning: false })`: no column. A plain
+ * insert then sends no RETURNING / OUTPUT and reports its row count; an
+ * onConflict call returns only its identity columns (see
+ * {@link conflictIdentity}), which the count is taken from.
+ */
+export declare const COUNT_ONLY: WriteProjection;
+/** True for {@link COUNT_ONLY} (or any projection naming no column). */
+export declare function isCountOnly(projection: WriteProjection | undefined): boolean;
 /**
  * The write-SQL cache segment for a projection. EMPTY for the default shape, so
  * every existing key is byte-identical; a projected statement differs only in