turbine-orm 0.33.0 → 0.35.0

package/dist/powql.d.ts

@@ -53,13 +53,20 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
     private readonly onQuery?;
-    private currentAction;
     private warnedUnlimited;
     constructor(pool: PowdbPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /** Resolve a camelCase field name (or raw snake) to its column metadata. */
     private column;
-    /** PowQL column reference (`.snake_name`) for a field. */
+    /**
+     * PowQL column reference for a field. Unqualified it is a dotted field
+     * reference (`.snake_name`), which bypasses keyword lookup. When an `alias`
+     * is supplied (the F2 join path) it is qualified (`alias.snake_name`) and the
+     * column name is backtick-quoted if it is a reserved word (a qualified
+     * `p.order` does NOT bypass keyword lookup, unlike the dotted `.order`).
+     */
     private ref;
+    /** Render a raw column name as a PowQL reference, qualified with `alias` when given. */
+    private colRefName;
     /**
      * Push a value into the param array and return its `$N` placeholder. When the
      * value targets a `float` column it is wrapped in {@link PowdbFloatParam} so
@@ -81,15 +88,67 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private writeRef;
     private isFloatCol;
+    /**
+     * The bound pool's {@link PowdbCapabilities}. Falls back to the trusted-caller
+     * default (all feature gates on, `nativeRaw` off) when a directly-constructed
+     * pool did not carry them, matching {@link PowdbPool}'s own constructor
+     * default so a hand-built test pool never crashes the version gates.
+     */
+    private get capabilities();
     /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
     private alwaysFalse;
     /**
      * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
      * value as a positional `$N` param. Returns `''` when there are no conditions.
+     *
+     * When `alias` is supplied (the F2 native-join path) every field reference is
+     * qualified with it (`.col` → `alias.col`, JSON path bases too); params bind
+     * exactly as in the unqualified path. The caller only ever passes an alias for
+     * an already-RESOLVED where (relation filters pre-resolved to literal in-lists
+     * by {@link resolveRelationFilters}): the relation-key branch below still
+     * throws, so an unresolved relation filter can never leak into a join.
      */
     private buildWhere;
     /** Build a single `field: value | operator` condition. */
     private buildFieldCondition;
+    /**
+     * PowQL JSON path expression `.col->$a->$b…`, binding EVERY path segment as a
+     * positional param (a string segment as a `str` token, an integer index as an
+     * `int` token). `->` binds tighter than every operator, so no parens are
+     * needed around the path in a comparison. Segments are bound (never inlined)
+     * to keep {@link materializePowql}'s `$N`-scan invariant intact: a segment
+     * that literally contained `$1` would otherwise be rewritten. Shared by the
+     * F1 where-filter path and the F2 orderBy / groupBy path emitters.
+     *
+     * A digit-only STRING segment (`'0'`) binds as an `int` array index, matching
+     * the SQL engines: `JsonFilter.path` is typed `string[]`, so an array index
+     * can only be expressed as a digit string, and the SQL builder converts it the
+     * same way (`/^\d+$/ → [n]`, query/builder.ts). Without this, PowDB's typed
+     * `->` treats `'0'` as a string KEY and silently matches nothing on an array
+     * (a wrong result, not an error). Same object-key-`'0'` caveat SQL accepts: a
+     * json object whose key is literally `"0"` is addressed as an array index.
+     */
+    private jsonPathExpr;
+    /**
+     * Compile a {@link JsonFilter} on a json document column into a PowQL filter
+     * (≥ 0.12). Operators PowQL cannot express EXACTLY throw a per-operator E017
+     * (never a wrong result): containment (`contains`, and `equals` without a
+     * `path`) has no PowQL operator. The mapped shapes:
+     *   - `{ path, equals: v }`  → `P = $n` (typed: string→str, bool→bool,
+     *      integral number→int, fractional→float; NOT stringified)
+     *   - `{ path, equals: null }` → `P is null` (matches JSON null AND a missing
+     *      key, a deliberate divergence from the PG driver, documented on
+     *      {@link JsonFilter})
+     *   - `{ path, gt|gte|lt|lte: v }` → `P > $n` … (range ops require `path`; the
+     *      engine coerces int/float numerically)
+     *   - `{ hasKey: k }` → `json_type(.col->$n) is not null` (top-level key test,
+     *      ignoring `path`, mirroring PG `col ? key`; includes keys holding JSON
+     *      null)
+     * A bare `{ path }` with no operators compiles to zero clauses (byte-parity
+     * with SQL), so a mutation whose only `where` is a bare `{ path }` is refused
+     * by the empty-where guard.
+     */
+    private buildJsonPathCondition;
     /** Bind a value, lowercasing for case-insensitive comparisons. */
     private bind;
     /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
@@ -120,23 +179,99 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private projectedColumns;
     /** `{ .c1, .c2, … }` projection clause. */
     private projection;
-    /** `order .c1 asc, .c2 desc` clause (empty string when no orderBy). */
+    /**
+     * `order .c1 asc, .c2 desc` clause (empty string when no orderBy). Supports,
+     * besides a plain direction:
+     *   - {@link JsonPathOrderBy} on a json column (≥ 0.12): `{ data: { path: […],
+     *     type?, direction? } }` → `order .data->$n asc` (or
+     *     `cast(.data->$n, "float")` for `type: 'numeric'`);
+     *   - {@link OrderBySpec} `{ sort, nulls }`: `nulls: 'last'` is accepted as a
+     *     no-op (PowDB is always nulls-last), `nulls: 'first'` throws E017.
+     *
+     * PowDB orders missing / JSON-null keys LAST in BOTH directions (an engine
+     * contract): for identical cross-engine results pass `nulls: 'last'`
+     * explicitly on Postgres, which defaults nulls-first for `desc`.
+     */
     private buildOrder;
-    /** Run PowQL with optional timeout, emitting a query event either way. */
+    /** Compile one {@link JsonPathOrderBy} entry to `order .col->$n asc` (+ optional numeric cast). */
+    private buildJsonPathOrder;
+    /**
+     * Run PowQL with optional timeout, emitting a query event either way. The
+     * `action` is passed PER CALL (never read from shared instance state) so the
+     * retry-eligibility and the emitted event action stay correct even when a
+     * concurrent operation runs on the same cached interface: a WRITE statement
+     * carries a write action and can therefore never be mistaken for a replayable
+     * read. Read statements pass a read-shaped action from {@link POWQL_READ_ACTIONS}.
+     */
     private exec;
+    /** Build the E018 refusal for a write / `begin` on a read-only pool. */
+    private readOnlyError;
+    /**
+     * Execute one statement, with the opt-in single stale-frame READ replay. When
+     * `retryStaleReads` is on and a first-statement READ fails with the stale-wire
+     * {@link isStaleFramePowdbError} ConnectionError (a socket idle-gap "received
+     * unexpected frame" that the client cannot recover), the statement is retried
+     * exactly once on a fresh pooled connection (the broken one was destroyed).
+     * The replay is refused for writes (an ambiguous mutation reply is unsafe to
+     * replay) and inside a transaction (a mid-tx statement cannot move connection),
+     * so only the read-shaped actions in {@link POWQL_READ_ACTIONS}, outside a
+     * `_txScoped` interface, are eligible. `action` is a per-call argument (never
+     * `this`-state), so a concurrent op flipping instance fields cannot turn a
+     * write into a retryable read.
+     */
+    private execOnce;
+    /** Is `err` a replayable stale-frame failure for THIS (per-call) read-shaped, non-tx action? */
+    private shouldRetryStaleRead;
     private emit;
     /** Run a method body through the middleware chain (mirrors QueryInterface). */
     private withMiddleware;
-    /** Map raw rows to typed entities. */
+    /** Map raw rows to typed entities. `native` is the wire that ACTUALLY served
+     * this result (threaded from {@link execOnce}, not the pool-level capability),
+     * so cells that arrived pre-typed over `queryNativeRaw` (F3) skip the legacy
+     * string coercion (a genuine str `"null"` stays `"null"` instead of collapsing
+     * to null) while a per-call legacy fallback on a native-capable pool still
+     * coerces its string cells correctly. Defaults to the pool capability for the
+     * rare caller with no per-result flag (hand-built test pools). */
     private shape;
     findMany(args?: FindManyArgs<T>): Promise<T[]>;
-    /** Build + run the flat findMany select; returns raw rows. */
+    /**
+     * Compile the flat findMany select into PowQL (no execution), pushing values
+     * into `params`. Returns the query plus the RESOLVED where (relation filters
+     * already collapsed to literal in-lists) so the F2 join path can re-emit the
+     * exact parent predicate alias-qualified, and so {@link explain} can wrap it.
+     */
+    private buildFind;
+    /** Build + run the flat findMany select; returns raw rows, the serving wire, and the resolved where. */
     private runFind;
+    /**
+     * Diagnostic surface: compile the same PowQL {@link findMany} would run for
+     * `args` (no cache) and return the engine's plan as one string per line.
+     *
+     * Runs as a READ (`explain <query>`), so it is safe on a read-only pool and
+     * eligible for the stale-read replay. The line content is engine-owned and is
+     * NOT covered by semver (match plan node names / tree shape, never exact
+     * bytes; mirrors PowDB's own `explain` contract).
+     *
+     * Does NOT run through the middleware chain: plan text is a diagnostic, not
+     * entity rows, and `QueryInterface.explain` deliberately bypasses middleware
+     * too, so both engines agree.
+     */
+    explain(args?: FindManyArgs<T>): Promise<string[]>;
     findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
     findFirst(args?: FindManyArgs<T>): Promise<T | null>;
     findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
     findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
-    /** Load each requested relation for `parents` and attach it onto each row. */
+    /**
+     * Load each requested relation for `parents` and attach it onto each row.
+     *
+     * `parent` is supplied ONLY by the top-level {@link findMany} (its args +
+     * resolved where). When the effective `relationLoadStrategy` resolves to an
+     * explicit `'join'` and the pool advertises `serverJoins`, an eligible
+     * top-level relation is loaded with a native PowQL join instead of the keyed
+     * loaders (F2); everything else (nested `with` levels, ineligible shapes, and
+     * the default `'batched'` strategy) keeps the loaders. Output is byte-equal
+     * either way (the join reuses the same stitch / shape helpers).
+     */
     private loadRelations;
     /**
      * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
@@ -147,6 +282,88 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * (composite junction keys would need PowQL tuple-`in`, which it lacks).
      */
     private loadManyToMany;
+    /**
+     * Resolve the effective relation-load strategy: the per-query arg wins, then
+     * the client config, then the PowDB default of `'batched'` (the keyed
+     * loaders). PowDB deliberately does NOT inherit the SQL-side implicit `'join'`
+     * default (that would silently flip every existing PowDB user onto brand-new
+     * join generation). Only a value the user actually set to `'join'` activates it.
+     */
+    private resolveStrategy;
+    /**
+     * Per-relation eligibility for the join path (checked before the serverJoins
+     * capability). Any `false` here is a SILENT fallback to the keyed loaders (it
+     * is never an error), so an off-page or nested-`with` shape still returns
+     * correct rows:
+     *   - the parent query must not be paged (`limit`/`offset`/`take`, including the
+     *     configured `defaultLimit`): a parent-filter join under a page would scan
+     *     children of off-page parents, where the loaders are strictly better;
+     *   - the relation must not request a nested `with` (its subtree stays on the
+     *     loaders this round) or a `distinct`;
+     *   - single-column relation keys only (a composite key falls to the loader,
+     *     which throws the same E017 as today);
+     *   - the PARENT-SIDE correlation column must be a single-column PK or unique
+     *     column, or the INNER join would re-emit one child copy per matching
+     *     parent row (a non-unique correlation key produces duplicate children the
+     *     loader never would). For hasMany/hasOne/m2m that column is the relation's
+     *     `referenceKey` on THIS (fetched) table; for belongsTo it is the
+     *     `referenceKey` on the TARGET table (the join's non-fetched side);
+     *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
+     *     stitch can't be reproduced by the 3-table join deterministically);
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
+     *     does a to-many relation `limit`/`offset` when the parent set spills past
+     *     one loader chunk (the loader limits per chunk, the join once globally).
+     */
+    private joinEligible;
+    /**
+     * True when `col` is a single-column unique key of `tableMeta`: the sole
+     * primary-key column, a single-column entry in `uniqueColumns` (where a
+     * per-column `unique: true` and an introspected single-column unique constraint
+     * both land), or a single-column unique index. Used by {@link joinEligible} to
+     * keep the INNER-join path off relations whose parent-side correlation column
+     * can repeat (which would duplicate children).
+     */
+    private isSingleColumnUnique;
+    /** Dispatch one eligible relation to the correct native-join loader. */
+    private loadRelationViaJoin;
+    /**
+     * manyToMany via chained joins: the target (alias `t`) → junction (alias `j`)
+     * → the already-fetched side (alias `p`), correlating `__tpk` from the
+     * junction's source key. Always a list, stitched exactly like the loader.
+     */
+    private loadManyToManyViaJoin;
+    /**
+     * The target column list to project through the join (honouring select/omit),
+     * with a loud guard: a real column named `__tpk` would collide with the
+     * reserved correlation alias, so refuse rather than silently mis-stitch.
+     */
+    private joinChildCols;
+    /**
+     * `{ __tpk: <tpkExpr>, <col>: <childAlias>.<col>, … }`. Each child column is
+     * ALIASED to its bare name (a bare qualified ref `c.col` would come back named
+     * `c.col`, not `col`) so the stitched rows shape identically to a flat select.
+     */
+    private joinProjection;
+    /**
+     * `filter <parentWhere qualified p> [and <relationWhere qualified childAlias>]`.
+     * The parent where is the ALREADY-RESOLVED predicate (relation filters collapsed
+     * to literal in-lists before the base query ran); the relation where is resolved
+     * on the target the same way before qualifying, so a nested relation filter in
+     * the relation `where` never reaches the join unresolved. Params bind in order.
+     */
+    private joinFilter;
+    /** Group join rows by their (normalized) `__tpk`, stripping it and shaping each child. */
+    private bucketByTpk;
+    /**
+     * Normalize a correlation key to a stable string map key so a parent's key
+     * value (a shaped entity field) and a child row's `__tpk` cell match across
+     * wires and column types. A `Date` maps to microseconds
+     * (`getTime()` ms times 1000), because a datetime correlation cell arrives as
+     * raw micros (bigint on the native wire, a micros string on the legacy wire),
+     * never as ms. bigint / number / string all stringify to the same digits, so
+     * an int key matches whether it came back typed or as text.
+     */
+    private joinKey;
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
     private scalarData;
     /**
@@ -192,8 +409,28 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     count(args?: CountArgs<T>): Promise<number>;
     aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
-    /** `having <expr>` over group aggregates (count/sum/avg/min/max). */
+    /** Validate a JSON-path target (group key / aggregate target): non-empty array of keys/indexes. */
+    private assertJsonPath;
+    /**
+     * `having <expr>` over group aggregates. `_count` compares `count(*)` (parity
+     * with the projection); a per-field aggregate re-emits its inner expression
+     * (from `aggInner` when the field is a requested aggregate, so a JSON-path
+     * aggregate reuses its bound placeholders, else `.field` for a plain column).
+     */
     private buildHaving;
+    /**
+     * Compile a groupBy `orderBy` into a PowQL `order` body over the group RESULT
+     * columns (by-fields, JSON group-key aliases, and requested aggregates). PowQL
+     * cannot re-emit an aggregate EXPRESSION in `order` (engine error), but CAN
+     * order by a projection alias on a grouped query (probed), so each key maps to
+     * its projected alias (`.agg_N` / `.gk_N` / `.col`). Semantics and error
+     * surface mirror the SQL `buildGroupByOrderBy` (0.32.2 R3-1): an aggregate not
+     * requested in this call, or an unknown by-key, throws E003 listing the valid
+     * keys. `nulls: 'first'` stays E017 (PowDB has no NULLS placement grammar).
+     */
+    private buildGroupOrder;
+    /** Resolve a groupBy order direction, refusing `nulls: 'first'` (E017); `nulls: 'last'` is a no-op. */
+    private groupOrderDir;
     findManyStream(): AsyncGenerator<T>;
     /** Reselect a single row by its single-column primary key value. */
     private reselectByPk;