turbine-orm 0.30.0 → 0.31.0

package/dist/powql.js

@@ -949,7 +949,13 @@ export class PowqlInterface {
             const { TransactionClient } = await import('./client.js');
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
             const ctx = { schema: this.schema, tx: tx };
-            const result = await fn(ctx);
+            // Plant the single-writer re-entrancy marker for the implicit tx's
+            // subtree (same seam TurbineClient.$transaction uses) — user code that
+            // fires db.$transaction from inside (e.g. $use middleware around a
+            // nested-write child op) must fast-fail E017, not queue into deadlock.
+            const wrap = client
+                .wrapTransactionCallback;
+            const result = await (wrap ? wrap(() => fn(ctx)) : fn(ctx));
             await client.query(d?.commitStatement?.() ?? 'commit');
             return result;
         }

package/dist/query/builder.d.ts

@@ -436,7 +436,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private collectRelationFilterParams;
     private collectRelFilterParams;
-    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
+    /**
+     * Collect params from operator clauses. Mirrors buildOperatorClauses:
+     * {@link ColumnRef} values compile into the SQL text, so they push NOTHING -
+     * but they re-run the same validation (unknown ref / insensitive mode) so a
+     * warmed cache can never skip a check the build path enforces.
+     */
     private collectOperatorParams;
     /**
      * Collect params from JSON filter. Mirrors buildJsonFilterClauses exactly:
@@ -448,10 +453,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
     private collectArrayFilterParams;
     /**
-     * Collect params for an orderBy clause. Only vector KNN ordering pushes a
-     * param (the `$n::vector` query vector); plain direction ordering is
-     * parameterless. Mirrors buildOrderBy's push order exactly so the cached-SQL
-     * param re-collection stays in lockstep.
+     * Collect params for an orderBy clause. Vector KNN ordering pushes the
+     * `$n::vector` query vector and JSON-path ordering pushes its text[] path;
+     * plain direction ordering is parameterless. Mirrors buildOrderBy's push
+     * order exactly so the cached-SQL param re-collection stays in lockstep.
      */
     private collectOrderByParams;
     /**
@@ -611,9 +616,28 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * differently-shaped wheres would share one cached SQL string.
      */
     private fingerprintAliasWhere;
+    /**
+     * Validate a `{ col }` column reference against its table and return the
+     * resolved snake_case column name. Shared by the SQL-build path
+     * ({@link buildOperatorClauses}) and the cache-hit param-collect path
+     * (`collectOperatorParams`) so both always throw identically: a warmed
+     * cache can never skip the check.
+     */
+    private resolveColumnRef;
+    /**
+     * Compile a `{ col }` reference to its quoted, prefix-matched SQL identifier.
+     * NO param is bound: the referenced column is part of the SQL text (and of
+     * the where fingerprint, see {@link fingerprintOperatorShape}).
+     */
+    private columnRefSql;
     /**
      * Build SQL clauses for a single operator object on a column.
      * Each operator key becomes its own clause, all ANDed together.
+     *
+     * `equals`/`not`/`gt`/`gte`/`lt`/`lte` also accept a {@link ColumnRef}
+     * (`{ col: 'otherField' }`) which compiles to a column-to-column comparison
+     * against `refCtx`: no param bound, so `collectOperatorParams` mirrors by
+     * pushing nothing and the referenced name lives in the fingerprint.
      */
     private buildOperatorClauses;
     /**
@@ -647,6 +671,33 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
      */
     private nullsSuffix;
+    /**
+     * Resolve an orderBy key to its snake_case column via the table's columnMap
+     * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
+     * where path uses. Shared by top-level JSON-path ordering and every nested
+     * relation orderBy path so nested orderBy accepts exactly what top-level
+     * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
+     * camelCase-named DB columns like "sortOrder").
+     */
+    private resolveOrderByColumn;
+    /**
+     * Validate a {@link JsonPathOrderBy} entry: column must exist AND be
+     * json/jsonb, path must be a non-empty array of keys/indexes: and return
+     * the resolved column. Shared by the SQL-build path
+     * ({@link buildJsonPathOrderEntry}) and the cache-hit param-collect mirrors
+     * so both always throw identically.
+     */
+    private validateJsonPathOrderBy;
+    /**
+     * Compile one {@link JsonPathOrderBy} entry:
+     * `("col" #>> $n::text[])::numeric ASC`: the numeric cast only with
+     * `type: 'numeric'` (default is text comparison), the extraction routed
+     * through the dialect's JSON hook exactly like the JSON where-filters, the
+     * path bound as ONE text[] param (mirrored by the order-param collectors).
+     * `prefix` scopes the column (`''` top-level, `t0.` inside a relation
+     * subquery).
+     */
+    private buildJsonPathOrderEntry;
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed
      * key is `_count`, which becomes a correlated `COUNT(*)` subquery. For a
@@ -655,8 +706,37 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *
      * Validation: relation must exist (E005); to-many only allows `_count`, and
      * to-one only allows real target columns (E003).
+     *
+     * `ctx` generalizes the term beyond the root table: inside a relation
+     * subquery's orderBy the relations live on the TARGET table's metadata and
+     * the correlation parent is the relation's alias, not `this.table`.
      */
     private buildRelationOrderBy;
+    /**
+     * Compile the ORDER BY terms of a relation `with` clause against the
+     * relation's table alias. One unified path for every relation shape
+     * (hasMany / manyToMany / belongsTo / hasOne) supporting exactly what the
+     * top-level orderBy accepts at this level:
+     *
+     *  - scalar columns via columnMap resolution (camelToSnake fallback) with
+     *    {@link OrderBySpec} nulls placement,
+     *  - {@link JsonPathOrderBy} entries (path bound as one text[] param),
+     *  - relation ordering on the TARGET's relations (`_count` for to-many, a
+     *    target column for to-one), correlated to the relation alias,
+     *  - vector KNN ordering stays top-level-only (E003, same as before).
+     *
+     * Param pushes (JSON paths, relation-order global filters) MUST be mirrored,
+     * in the same order, by {@link collectRelationOrderParams}.
+     */
+    private buildRelationOrderClause;
+    /**
+     * Param-collect mirror of {@link buildRelationOrderClause}: JSON-path
+     * entries push their path (one text[] param each); relation-order entries
+     * mirror {@link collectOrderByParams}' relation branch (count / to-one
+     * global-filter params); scalar entries push nothing but re-run the same
+     * column validation so a warmed cache can never skip it.
+     */
+    private collectRelationOrderParams;
     /**
      * Build a correlated `(SELECT COUNT(*) …)` scalar subquery for a to-many
      * relation, correlated to `parentRef`. hasMany counts child rows via the FK;