turbine-orm 0.25.0 → 0.27.0

package/dist/query/builder.d.ts

@@ -13,7 +13,7 @@
 import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, QueryResult, RelationLoadStrategy, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 /**
  * Runs a SQL statement and resolves its raw result. Passed to a
  * {@link DeferredQuery.reselect} plan so it can run the write and the follow-up
@@ -94,6 +94,26 @@ export interface QueryInterfaceOptions {
     sqlCache?: boolean;
     /** SQL dialect implementation. Defaults to PostgreSQL. */
     dialect?: Dialect;
+    /**
+     * Interpret offset-less timestamp strings (Postgres `timestamp` without
+     * time zone, and the JSON emitted by nested-relation subqueries) as UTC.
+     * This is the Prisma/Rails/Django convention and makes results independent
+     * of the server's local time zone. Default: `true`. Set `false` to restore
+     * the pre-0.26 behavior (JS local-time interpretation).
+     */
+    utcTimestamps?: boolean;
+    /**
+     * Client-level default relation-loading strategy for `with` clauses. Per-query
+     * `relationLoadStrategy` args override this; both default to `'join'`.
+     */
+    relationLoadStrategy?: RelationLoadStrategy;
+    /**
+     * How nested-relation subqueries encode each row's JSON: `'object'` (default,
+     * `json_build_object`) or `'positional'` (`json_build_array`, key-less — see
+     * {@link Dialect.buildJsonArray}). Positional is Postgres-only in v1; a
+     * `with` clause on any other dialect throws `UnsupportedFeatureError` (E017).
+     */
+    jsonEncoding?: 'object' | 'positional';
     /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
     _txScoped?: boolean;
     /** @internal Callback from TurbineClient for query event emission. */
@@ -117,9 +137,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
+    private readonly utcTimestamps;
     private readonly preparedStatementsEnabled;
     private readonly sqlCacheEnabled;
     private readonly dialect;
+    /** Client-level default relation-loading strategy ('join' unless configured). */
+    private readonly relationLoadStrategy;
+    /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
+    private readonly jsonEncoding;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
      * the user is not spammed once per row. Per-instance state — each
@@ -204,6 +229,34 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private inClause;
     /** The single bound parameter for an `IN` list (PG: the array; SQLite: a JSON string). */
     private inParam;
+    /**
+     * Resolve the effective relation-loading strategy for a query: the per-query
+     * arg wins, then the client-level default, then `'join'`. Only meaningful when
+     * a `with` clause is present; the callers gate on that.
+     */
+    private resolveLoadStrategy;
+    /**
+     * Build the {@link RelationLoadContext} the batched loader needs, closing over
+     * this interface's pool/dialect/executor. Child readers are constructed on the
+     * SAME pool (so they join an active transaction) with `defaultLimit` cleared
+     * and unlimited-warnings silenced — a relation load must fetch every matching
+     * child, and the per-relation `limit` is applied client-side by the loader.
+     */
+    private batchedContext;
+    /**
+     * Run a findMany with the batched strategy: execute the base query WITHOUT
+     * relation subqueries (all other clauses intact), then load each relation via
+     * one flat follow-up query and stitch client-side. Parent stitch keys the
+     * caller's `select`/`omit` excluded are added for the base query and stripped
+     * from the returned rows, so the shape matches the join strategy exactly.
+     */
+    private runFindManyBatched;
+    /**
+     * Build the base findMany args for a batched run: drop `with`, and ensure every
+     * parent correlation key needed for stitching is projected (returning the list
+     * of keys that must be stripped from the output afterwards).
+     */
+    private prepareBatchedBase;
     /**
      * Return cache hit/miss statistics for this QueryInterface instance.
      * Useful for monitoring and benchmarking.
@@ -275,6 +328,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private executeWithMiddleware;
     findUnique<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>): Promise<QueryResult<T, R, W, S, O> | null>;
+    /**
+     * Batched-strategy findUnique: fetch the single base row without relation
+     * subqueries (adding any parent stitch keys the projection excluded), then load
+     * its relations via one follow-up query each and stitch. Mirrors the join
+     * strategy's shape for the one row.
+     */
+    private runFindUniqueBatched;
     buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
     findMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>[]>;
     /**
@@ -582,10 +642,67 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * memoized per table. Used so nested relation rows (camelCase keys) coerce
      * dates the same way top-level rows do.
      */
+    /**
+     * Prisma-compat: a plain object on a to-one relation key —
+     * `where: { vendor: { name: { contains: 'x' } } }` — is an implicit `is`
+     * filter. Normalize it to `{ is: obj }` so all downstream handling (SQL,
+     * params, fingerprint) sees one canonical shape. To-many relations still
+     * require an explicit `some`/`every`/`none` (a bare object there is
+     * ambiguous and was never valid in Prisma either).
+     */
+    private normalizeRelationFilter;
     private getCamelDateFields;
     private parseRow;
     /** Parse a row that may contain JSON nested relation columns */
     private parseNestedRow;
+    /**
+     * Resolve the emitted column list for a relation, honoring `select` / `omit`.
+     * Shared by {@link buildRelationSubquery} (json order) and
+     * {@link buildRelationShape} (decode key order) so they can never diverge.
+     */
+    private resolveTargetColumns;
+    /**
+     * Render a single relation row's JSON: a keyed object (`'object'`) or a
+     * positional array (`'positional'`). The array drops the keys but keeps the
+     * exact expression order, so {@link RelationShape.keys} maps positions back.
+     */
+    private buildJsonRow;
+    /**
+     * Build the top-level relation shapes for a `with` clause, mirroring
+     * {@link buildSelectWithRelations}: same relation iteration order, same
+     * per-relation column resolution, same nested recursion.
+     */
+    private buildRelationShapes;
+    /**
+     * Recursively describe one relation's positional layout: the camelCase key
+     * order (scalar columns first, then nested relation slots in the same order
+     * {@link buildRelationSubquery} appends them), the nested sub-shapes, and the
+     * cardinality (single object for belongsTo/hasOne, array for the rest).
+     */
+    private buildRelationShape;
+    /**
+     * Build the row parser for a `with` clause. In object mode this is just
+     * {@link parseNestedRow}. In positional mode it decodes each relation's
+     * positional arrays into the object form first (shapes built once, not per
+     * row), then delegates to parseNestedRow for date/snake-camel coercion.
+     */
+    private makeNestedParser;
+    /**
+     * Return a shallow copy of a top-level row with each relation column decoded
+     * from its positional array(s) into the object representation. Only relation
+     * columns are positional — base scalar columns stay object-keyed — so the
+     * result is exactly what the object encoding would have handed parseNestedRow.
+     */
+    private decodePositionalRelations;
+    /**
+     * Decode one relation's positional JSON value. `json_agg` returns the value as
+     * a JSON string at the top level (JSON.parse once); nested relation slots are
+     * already-parsed arrays. A `'many'` value is an array of positional arrays; a
+     * `'one'` value is a single positional array or null.
+     */
+    private decodePositionalValue;
+    /** Map one positional array back to a keyed object using the shape's key order. */
+    private decodePositionalObject;
     /**
      * Build a SELECT clause that includes both base columns and nested relation subqueries.
      *