turbine-orm 0.32.2 → 0.34.0

package/dist/powql.d.ts

@@ -53,7 +53,6 @@ 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. */
@@ -81,6 +80,13 @@ 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;
     /**
@@ -90,6 +96,44 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     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,17 +164,60 @@ 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;
+    /**
+     * 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. */
+    /** Build + run the flat findMany select; returns raw rows + the serving wire. */
     private runFind;
     findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
     findFirst(args?: FindManyArgs<T>): Promise<T | null>;
@@ -192,8 +279,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;