turbine-orm 0.51.0 → 0.52.0

package/dist/cjs/powql.d.ts

@@ -38,6 +38,18 @@ import { type PowdbPool } from './powdb.js';
 import type { MiddlewareFn, QueryInterfaceOptions } from './query/index.js';
 import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindUniqueArgs, GroupByArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './query/types.js';
 import { type SchemaMetadata } from './schema.js';
+/**
+ * Max values one `in` / `notIn` on a PowDB-native `datetime` column may carry.
+ *
+ * Such a list is never sent as a list: it is expanded into an equality chain
+ * (see {@link PowqlInterface.buildDatetimeInList}), and PowQL spends one level
+ * of its 64-level nesting budget per chain term. Measured on the 0.20.0 addon:
+ * 63 terms parse at the top level, 61 one level deep, whatever else the
+ * predicate contains. 32 leaves room for the surrounding filter, and is also the
+ * key-chunk size the relation loaders use for a datetime correlation column, so
+ * a loader can never build a chain the engine will reject.
+ */
+export declare const MAX_POWQL_DATETIME_TERMS = 32;
 /**
  * The PowQL query interface. Constructed by `turbinePowDB` via the
  * `queryInterfaceFactory` seam and cast to `QueryInterface<object>` so
@@ -95,6 +107,25 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * default so a hand-built test pool never crashes the version gates.
      */
     private get capabilities();
+    /**
+     * The `limit` a query actually emits: the explicit `limit`, Prisma's `take`
+     * alias, then the client-level `defaultLimit`. Shared by {@link buildFind} and
+     * the {@link findMany} zero short-circuit so the two can never disagree about
+     * which limit is in force.
+     */
+    private effectiveLimit;
+    /**
+     * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
+     * casts both with `as usize` at execution, so below engine 0.20 a negative
+     * limit wrapped to `usize::MAX` and silently returned EVERY row, the opposite
+     * of what the caller asked for; 0.20 refuses it. Validating client-side makes
+     * the refusal identical on every engine version and names the argument.
+     *
+     * `limit: 0` is legal and means "no rows" (SQL `LIMIT 0`). It is not emitted:
+     * callers short-circuit it, because PowDB's projection fast path returned ONE
+     * row for `limit 0` below 0.20.
+     */
+    private assertPagination;
     /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     private alwaysFalse;
     /**
@@ -109,6 +140,37 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * throws, so an unresolved relation filter can never leak into a join.
      */
     private buildWhere;
+    /**
+     * Gate a predicate on a PowDB-native `datetime` column. Turbine binds a JS
+     * `Date` as an integer count of microseconds, and PowDB writes a timestamp
+     * literal as a plain integer, so every such predicate is a `DateTime` vs `Int`
+     * comparison. Below engine 0.20 that pairing was unhandled and fell back to
+     * comparing TYPE TAGS, so `>` matched every non-null row, `=` and `<` matched
+     * none, and the answer additionally changed with the column's access path
+     * (indexed vs scanned). 0.20 compares microseconds and every binary operator
+     * (`=`, `!=`, `<`, `<=`, `>`, `>=`) is correct.
+     *
+     * ONE gate covers the whole family, whatever spelling the caller used. `in` /
+     * `not in` are included because their still-broken LIST form is never emitted:
+     * {@link buildInList} expands a datetime list into the equality chain the
+     * engine does answer correctly, which is the same binary comparison this flag
+     * governs. So on >= 0.20 every path is served (direct predicates, relation
+     * filters, the batched loaders, nested projections, native joins, and the
+     * findUnique / update / delete / upsert by-key paths), and below 0.20 every
+     * path that compares against a literal is refused with one message, which
+     * names the read paths that do not.
+     *
+     * `is null` / `is not null` are never gated: they compare no literal and are
+     * correct on every version. Ordering, grouping and `min`/`max` are likewise
+     * unaffected (they compare datetimes against each other, never against an int),
+     * as are nested-projection and join correlations, which are column-to-column.
+     *
+     * Only PowDB's native `datetime` type is affected. Turbine's own DDL emits
+     * `int` epoch micros for a `Date` column, so a Turbine-provisioned database
+     * never reaches this: the exposed shape is a table created outside Turbine and
+     * read through `introspectPowdbDatabase`, or hand-written metadata.
+     */
+    private assertDatetimePredicateSupported;
     /** Build a single `field: value | operator` condition. */
     private buildFieldCondition;
     /**
@@ -153,8 +215,60 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private bind;
     /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
     private bindLike;
-    /** `lhs [not] in ($1, $2, …)`, empty list collapses to a constant. */
+    /**
+     * `lhs [not] in ($1, $2, …)`, empty list collapses to a constant.
+     *
+     * A PowDB-native `datetime` column takes the expanded form instead (see
+     * {@link buildDatetimeInList}): its `in` list is still broken upstream at 0.20.
+     */
     private buildInList;
+    /**
+     * `in` / `not in` on a PowDB-native `datetime` column, expanded into the
+     * equality chain the engine answers correctly:
+     *
+     *   `in`     → `(.ts = $1 or .ts = $2 …)`
+     *   `notIn`  → `(.ts != $1 and .ts != $2 … and .ts is not null)`
+     *
+     * PowQL's LIST form compares a datetime column against integer timestamp
+     * literals by TYPE TAG as of engine 0.20 (the 0.20 timestamp fix covered the
+     * binary operators only): measured on the 0.20.0 addon, `filter .ts in
+     * (<micros>, …)` matches nothing and `not in` matches everything, while the
+     * identical lists against an `int` control column answer correctly. The
+     * expanded chain uses the operators 0.20 DID fix, so it answers correctly and
+     * matches the int control exactly.
+     *
+     * This is what keeps the relation family coherent: relation filters and the
+     * batched loaders both compile to a key `in` list, so without the rewrite the
+     * same relation was refused through one strategy and served through another
+     * (nested projections and joins correlate column to column and never emit a
+     * list at all).
+     *
+     * The cost is the chain's width. PowQL bounds the SHAPE of the predicate tree,
+     * and a flat `or` / `and` chain spends one level per term against the same
+     * 64-level budget as nested parens (measured on 0.20: 63 terms at the top
+     * level, 61 one level deep), so the expansion is capped at
+     * {@link MAX_POWQL_DATETIME_TERMS} with headroom for whatever predicate it
+     * sits inside. The loaders chunk their key lists to that cap, so only a
+     * caller-written list (or a relation filter matching very many distinct
+     * timestamps) can exceed it, and that raises a typed E017 saying so rather
+     * than an engine parse failure.
+     */
+    private buildDatetimeInList;
+    /**
+     * A literal `ref in (…)` clause for the hand-built key lists the relation
+     * loaders emit (they bypass {@link buildWhere}). Routes a PowDB-native
+     * `datetime` key column through the same equality-chain expansion the
+     * where-builder uses, so a datetime junction / correlation key behaves
+     * identically however the statement was assembled.
+     */
+    private inClause;
+    /**
+     * Key-chunk size for a relation loader. A PowDB-native `datetime` correlation
+     * column's `in` list is expanded into an equality chain, which PowQL's nesting
+     * budget bounds, so those keys chunk at {@link MAX_POWQL_DATETIME_TERMS}
+     * (more, smaller round-trips) instead of {@link MAX_RELATION_KEYS}.
+     */
+    private keyChunkSize;
     /**
      * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause
      * into a plain scalar `in`/`notIn` condition on the **local key**, by running
@@ -421,6 +535,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      *   - m2m (the block takes exactly one child table; the junction-order
      *     stitch has no nested equivalent), and composite relation keys;
      *   - a to-one relation carrying `limit`/`offset` (the loaders' semantics);
+     *   - a relation `limit` of exactly 0 (a nested block would emit `limit 0`,
+     *     which PowDB's projection fast path answered with ONE row below engine
+     *     0.20; the loader path resolves it client-side and is correct on every
+     *     version). A NEGATIVE relation limit is refused outright, not fallen back;
      *   - `distinct` inside the relation options (no nested grammar for it);
      *   - a projected child column whose tsType is `bigint` or `Uint8Array`
      *     (values ride a JSON array, which cannot carry them losslessly);
@@ -520,6 +638,27 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private get qt();
     create(args: CreateArgs<T>): Promise<T>;
+    /**
+     * Refuse a `createMany` whose rows do not all name the SAME fields.
+     *
+     * PowQL could express it: a multi-row insert carries one `{ col := … }` tuple
+     * per row, each with its own column list, so a ragged call inserts every
+     * value. The SQL engines cannot, their single statement takes its column list
+     * from the first row, so a field only a later row names is dropped and a field
+     * only the first row names is written as NULL over that column's default. They
+     * refuse it (ValidationError, query/writes.ts), and PowDB matching that
+     * refusal is what makes the call portable: a shape accepted here and rejected
+     * by every other engine turns a PowDB-to-Postgres move into a hard error found
+     * in production rather than at the first run.
+     *
+     * Runs AFTER `applyPkDefault`, on the rows as they will actually be written:
+     * a defaulted string PK is filled in on every row, so `[{}, { name }]` is
+     * refused for the missing `name`, not for the PK the client supplied itself.
+     * Rows that all name the same fields (the overwhelmingly common shape,
+     * including N rows of pure defaults) cost one `Object.keys` pass and emit
+     * byte-identical PowQL.
+     */
+    private assertUniformCreateManyRows;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     update(args: UpdateArgs<T>): Promise<T>;
     updateMany(args: UpdateManyArgs<T>): Promise<{
@@ -547,6 +686,27 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private upsertComposite;
     count(args?: CountArgs<T>): Promise<number>;
+    /**
+     * Gate ONE field of a per-field `_count`.
+     *
+     * `_count: { col: true }` compiles to `count(T { .col })`, which counts
+     * NON-NULL values of the column (SQL's `COUNT(col)`) only from engine 0.20 on.
+     * Below 0.20 both PowDB frontends ignored the projection and returned the ROW
+     * count.
+     *
+     * That divergence only EXISTS on a nullable column: where the column is NOT
+     * NULL the row count and the non-null count are the same number, so the
+     * pre-0.20 answer was already the right one and the query keeps working. The
+     * gate is therefore per-column, not per-call: refusing the whole feature would
+     * take a correct, working call away from every user on the engine line Turbine
+     * shipped against and hand them nothing.
+     *
+     * Nullability comes from the column metadata (`introspectPowdbDatabase` reads
+     * PowDB's `required` modifier; `defineSchema` declares it). Metadata that
+     * claims NOT NULL for a column the live catalog lets be null would count rows
+     * instead of values below 0.20, the same drift any stale-metadata query has.
+     */
+    private assertProjectedCountSupported;
     aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     /** Validate a JSON-path target (group key / aggregate target): non-empty array of keys/indexes. */