turbine-orm 0.34.0 → 0.36.0

package/dist/powql.d.ts

@@ -57,8 +57,16 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     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
@@ -92,6 +100,13 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /**
      * 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. */
@@ -160,8 +175,40 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private resolveRelationCondition;
     /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
     private resolveManyToManyCondition;
-    /** Resolve the set of columns to project, honouring `select` / `omit`. */
+    /**
+     * Resolve the set of columns to project, honouring `select` / `omit` and the
+     * query-level `includePii` opt-in. PII-tagged (`defineSchema` `pii: true`)
+     * columns are EXCLUDED from a default (or omit-only) projection unless
+     * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
+     * and returns it regardless. Untagged tables project exactly as before.
+     */
     private projectedColumns;
+    /**
+     * The snake_case names of this table's PII-tagged columns. Empty for a table
+     * with no `pii: true` column, so untagged tables keep their prior projection.
+     */
+    private piiColumnNames;
+    /**
+     * The camelCase field names of this table's PII-tagged columns: the read
+     * policy applied to a write's returned row (create/update/upsert/delete accept
+     * no `includePii`/`select`, so their result always drops PII; you may still
+     * write PII fields freely).
+     *
+     * SPEC LIMITATION (PowQL): the driver contract
+     * (`docs/integrations/powql-for-drivers.md`) exposes `returning` only as a
+     * bare keyword that hands back every column; it accepts NO column list, so
+     * (unlike the SQL engines, which emit an explicit non-PII `RETURNING`/`OUTPUT`
+     * projection) the create/update/delete `returning` paths cannot exclude PII at
+     * the query-language level and must strip it here after the fact. This is the
+     * client-side strip of last resort, not defense-in-depth, for those paths; we
+     * do NOT reverse-engineer an undocumented projection form. The upsert path is
+     * different: it has no `returning` and reselects by PK through the read
+     * projection ({@link projectedColumns}), which already omits PII, so PII never
+     * crosses the wire there. If a future spec revision lets `returning` take a
+     * projection, switch the write paths to emit the non-PII list and this strip
+     * becomes a no-op like {@link parseWriteRow} on the SQL engines.
+     */
+    private stripWritePii;
     /** `{ .c1, .c2, … }` projection clause. */
     private projection;
     /**
@@ -189,6 +236,8 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * 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
@@ -217,13 +266,44 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * 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 + the serving wire. */
+    /**
+     * 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
@@ -234,6 +314,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;
     /**