turbine-orm 0.90.2 → 0.91.0-next.a5cefb1

package/dist/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/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

package/dist/query/writes.js

@@ -828,12 +828,17 @@ export function buildCreateMany(qi, args, overBindLimit = 'refuse', projection)
  * builder (`skipGlobalFilters`), which a concurrent call could change across
  * an await.
  */
-export function planCreateMany(qi, args, projection) {
+export function planCreateMany(qi, args, projection, canSplit = true) {
     const prepared = prepareCreateMany(qi, args, projection);
     if ('deferred' in prepared)
         return { chunks: [prepared.deferred], rowsPerChunk: args.data.length };
     const rows = prepared.rowValues;
-    const size = rowsPerStatement(qi, prepared);
+    const { most, chunk } = statementSizes(qi, prepared);
+    // Rows that cannot be told apart across statements (refused below past one),
+    // and a call whose executor cannot run several statements in one
+    // transaction (`canSplit`), take the fewest statements the engine allows;
+    // the rest are split at the size the engine runs fastest.
+    const size = !canSplit || (prepared.conflict && !prepared.identity) ? most : chunk;
     if (rows.length <= size) {
         return { chunks: [emitCreateMany(qi, prepared, rows, 'allow', true)], rowsPerChunk: size };
     }
@@ -861,12 +866,19 @@ function prepareCreateMany(qi, args, projection) {
     // The data-independent half of onConflict is checked before the empty-data
     // shortcut, so a call is never valid with no rows and invalid with some.
     const conflict = args.onConflict === undefined ? null : resolveConflictPlan(qi, args);
+    const countOnly = isCountOnly(projection);
+    // Before the empty-data shortcut too, so the refusal never depends on the rows.
+    if (countOnly && args.skipDuplicates && qi.dialect.capabilities.skipDuplicatesCountsSkipped) {
+        throw new UnsupportedFeatureError('createMany({ skipDuplicates: true, returning: false })', qi.dialect.name, 'It counts a skipped row as written, so the count would include the rows skipped. Without ' +
+            'returning: false the call writes the same rows and reports no count.');
+    }
     if (args.data.length === 0) {
         return {
             deferred: {
-                sql: `SELECT * FROM ${qt} WHERE false`,
+                // `1 = 0`, not `false`: T-SQL has no boolean literal in a condition.
+                sql: `SELECT * FROM ${qt} WHERE 1 = 0`,
                 params: [],
-                transform: () => [],
+                transform: () => (countOnly ? { count: 0 } : []),
                 tag: `${qi.table}.createMany`,
             },
         };
@@ -895,7 +907,9 @@ function prepareCreateMany(qi, args, projection) {
             deferred: {
                 sql: buildDefaultValuesInsert(qi, args.data.length, args.skipDuplicates, projection),
                 params: [],
-                transform: (result) => result.rows.map((row) => parseWriteRow(qi, row, projection)),
+                transform: (result) => countOnly
+                    ? countOf(result)
+                    : result.rows.map((row) => parseWriteRow(qi, row, projection)),
                 tag: `${qi.table}.createMany`,
             },
         };
@@ -973,32 +987,40 @@ function emitCreateMany(qi, prepared, rowValues, overBindLimit, first) {
     return {
         sql: built.sql,
         params: built.params,
-        transform: (result) => result.rows.map((row) => parseWriteRow(qi, row, projection)),
+        transform: (result) => isCountOnly(projection)
+            ? countOf(result)
+            : result.rows.map((row) => parseWriteRow(qi, row, projection)),
         tag: `${qi.table}.createMany`,
     };
 }
 /**
- * Rows one `createMany` statement may carry: the most that keep its bind
- * parameters within the engine's limit and, on SQL Server, its rows within
- * the 1000 a plain `INSERT ... VALUES` accepts. The parameter cost is measured
- * from one-row and two-row builds, which separates the per-row parameters from
- * the ones bound once per statement (an onConflict update's values); the
- * PostgreSQL UNNEST form binds one array per column, so its rows never run out.
+ * Rows one `createMany` statement may carry. `most`: the most that keep its
+ * bind parameters within the engine's limit and, on SQL Server, its rows
+ * within the 1000 a plain `INSERT ... VALUES` accepts. `chunk`: the same under
+ * the engine's `chunkBindParameters`, the size a call that runs as several
+ * statements is split at. The parameter cost is measured from one-row and
+ * two-row builds, which separates the per-row parameters from the ones bound
+ * once per statement (an onConflict update's values); the PostgreSQL UNNEST
+ * form binds one array per column, so its rows never run out.
  */
-function rowsPerStatement(qi, prepared) {
+function statementSizes(qi, prepared) {
     // An onConflict statement (SQL Server's MERGE) reads its rows as a derived
     // table, which the plain INSERT ... VALUES row cap does not bind.
     const cap = prepared.conflict ? Infinity : qi.dialect.capabilities.maxInsertRows;
-    const limit = maxBindParameters(qi.dialect);
+    const limit = maxBindParameters(qi.dialect) ?? Infinity;
+    // A dialect written before the key existed has none, and splits at its limit.
+    const preferred = qi.dialect.capabilities.chunkBindParameters;
+    const chunkLimit = typeof preferred === 'number' && preferred < limit ? preferred : limit;
     const rows = prepared.rowValues;
-    if (limit === undefined || rows.length < 2)
-        return cap;
+    if (!Number.isFinite(chunkLimit) || rows.length < 2)
+        return { most: cap, chunk: cap };
     const one = emitCreateMany(qi, prepared, rows.slice(0, 1), 'allow', true).params.length;
     const perRow = emitCreateMany(qi, prepared, rows.slice(0, 2), 'allow', true).params.length - one;
     if (perRow <= 0)
-        return cap;
+        return { most: cap, chunk: cap };
     const fixed = Math.max(0, one - perRow);
-    return Math.max(1, Math.min(cap, Math.floor((limit - fixed) / perRow)));
+    const fit = (bound) => Number.isFinite(bound) ? Math.max(1, Math.min(cap, Math.floor((bound - fixed) / perRow))) : cap;
+    return { most: fit(limit), chunk: fit(chunkLimit) };
 }
 const ON_CONFLICT_KEYS = new Set(['target', 'update', 'where', 'ignore']);
 /**
@@ -1359,6 +1381,11 @@ function buildBulkUpsert(qi, conflict, insert, columns, overBindLimit, projectio
         transform: (result) => {
             if (identity)
                 assertEachRowWrittenOnce(qi, conflict, identity, result.rows, first);
+            // COUNT_ONLY: the rows back are the identity columns (or none at all when
+            // the written rows cannot be identified), counted and never returned.
+            if (isCountOnly(projection)) {
+                return (identity ? { count: result.rows.length } : countOf(result));
+            }
             const rows = result.rows.map((row) => parseWriteRow(qi, row, projection));
             if (identity && identity.added.length > 0) {
                 for (const row of rows)
@@ -1989,6 +2016,21 @@ export function piiFields(_qi, meta) {
     }
     return out;
 }
+/**
+ * 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 const COUNT_ONLY = Object.freeze({ columns: Object.freeze([]) });
+/** True for {@link COUNT_ONLY} (or any projection naming no column). */
+export function isCountOnly(projection) {
+    return projection !== undefined && projection.columns.length === 0;
+}
+/** `{ count }` from a write that returned no rows to count: the engine's row count. */
+function countOf(result) {
+    return { count: typeof result.rowCount === 'number' ? result.rowCount : result.rows.length };
+}
 /**
  * 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
@@ -2084,6 +2126,9 @@ export function writeReturningColumns(qi, projection) {
  */
 export function writeReselectSelection(qi, projection) {
     const cols = writeReturningColumns(qi, projection);
+    // COUNT_ONLY: the re-read is counted, not returned, so it reads no column.
+    if (cols !== '*' && cols.length === 0)
+        return '1';
     return cols === '*' ? '*' : cols.join(', ');
 }
 /**

package/dist/sqlite.js

@@ -905,12 +905,16 @@ export const sqliteDialect = {
         // The default SQLITE_MAX_VARIABLE_NUMBER.
         maxBindParameters: 32766,
         maxInsertRows: Number.POSITIVE_INFINITY,
+        // Measured: 40,000 rows insert 70 to 140 times faster in statements of 250
+        // parameters than of 32,766 (named-parameter lookup is a linear search).
+        chunkBindParameters: 250,
         upsertConflictTarget: 'explicit',
         setClauseOrder: 'snapshot',
         reselectLocksRows: false,
         integerDivision: '/',
         updateExpressions: true,
         bulkUpsertAppliesRepeatedKeys: true,
+        skipDuplicatesCountsSkipped: false,
         readOnlyTransactions: false,
         connectionParameters: false,
         backendCancel: false,
@@ -1121,6 +1125,8 @@ export const sqliteDialect = {
             (boolean ? 'Write true or false.' : 'Write a number, or a string holding one, such as "12.5".'));
     },
     buildReturningClause(selection = '*') {
+        if (selection !== '*' && selection.length === 0)
+            return '';
         return ` RETURNING ${selection === '*' ? '*' : selection.join(', ')}`;
     },
     buildInsertStatement(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.90.2",
+  "version": "0.91.0-next.a5cefb1",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",

package/skills/turbine-orm/SKILL.md

@@ -233,6 +233,12 @@ PostgreSQL only. `p` may be an array of fractions, and the result is then an
 array in the same order. The default `method: 'cont'` interpolates and is
 refused on a date column with `TURBINE_E003`; use `method: 'disc'` there.
 
+A `_percentile` key that names no field takes `of`, an expression, and returns
+a number under that key: `scoreGap: { of: expr.sub(col('rindScore'),
+col('aromaScore')), p: 0.5 }`. `expr.secondsBetween(col('a'), col('b'))` is the
+seconds between two timestamp columns, and a date column there is refused with
+`TURBINE_E003`.
+
 ## groupBy and having
 
 `by` lists the grouping columns. The `having` shape is **column first, aggregate
@@ -293,6 +299,8 @@ refused with `TURBINE_E003`, and so is an expression in `create` data.
 target must be the primary key or one whole unique key; any other column list
 is refused with `TURBINE_E003`.
 
+`createMany` with `returning: false` returns `{ count }` instead of the rows.
+
 ## Locking rows
 
 `lock: 'update'` on `findMany`, `findFirst` or `findUnique` locks the rows it