turbine-orm 0.30.0 → 0.32.0

package/dist/cjs/query/filters.js

@@ -7,9 +7,10 @@
  * and execution rather than filter-shape bookkeeping.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSON_RANGE_OPERATORS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = void 0;
+exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSON_RANGE_OPERATORS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = exports.COLUMN_REF_OPERATORS = void 0;
 exports.isWhereOperator = isWhereOperator;
 exports.isUnmatchedPlainObject = isUnmatchedPlainObject;
+exports.isColumnRef = isColumnRef;
 exports.fingerprintOperatorShape = fingerprintOperatorShape;
 exports.assertBindableEqualsOperand = assertBindableEqualsOperand;
 exports.sortedKeys = sortedKeys;
@@ -24,6 +25,8 @@ exports.validateTextSearchConfig = validateTextSearchConfig;
 exports.isVectorFilter = isVectorFilter;
 exports.isVectorOrderBy = isVectorOrderBy;
 exports.isOrderBySpec = isOrderBySpec;
+exports.isJsonPathOrderBy = isJsonPathOrderBy;
+exports.isRelationPickOrderBy = isRelationPickOrderBy;
 exports.normalizeOrderBy = normalizeOrderBy;
 const errors_js_1 = require("../errors.js");
 const utils_js_1 = require("./utils.js");
@@ -56,17 +59,48 @@ function isUnmatchedPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+exports.COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte']);
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+function isColumnRef(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === 'col' && typeof value.col === 'string';
+}
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
  * param pushed), so null-ness is part of the shape — without it a cache entry
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
  */
 function fingerprintOperatorShape(value) {
     const obj = value;
     const opKeys = Object.keys(obj)
         .filter((k) => k !== 'mode')
-        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .map((k) => {
+        const v = obj[k];
+        if ((k === 'equals' || k === 'not') && v === null)
+            return `${k}:null`;
+        if (exports.COLUMN_REF_OPERATORS.has(k) && isColumnRef(v))
+            return `${k}:col(${JSON.stringify(v.col)})`;
+        return k;
+    })
         .sort();
     const modeStr = value.mode === 'insensitive' ? ':i' : '';
     return `op(${opKeys.join(',')}${modeStr})`;
@@ -269,6 +303,47 @@ function isVectorOrderBy(value) {
 function isOrderBySpec(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
 }
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+function isJsonPathOrderBy(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if ('distance' in value || 'sort' in value)
+        return false;
+    return Array.isArray(value.path);
+}
+/**
+ * Check if an orderBy value is a pick-row relation ordering:
+ * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
+ * required — `pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * relation whose target has real columns literally named `pick` and `by`
+ * (whose values are direction strings or `{ sort, nulls }` specs, never an
+ * object with `orderBy`) still falls through to column ordering. `distance`
+ * (vector), `sort` (OrderBySpec), and a top-level array `path` (JSON-path
+ * ordering) are excluded up front.
+ */
+function isRelationPickOrderBy(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if ('distance' in value || 'sort' in value || Array.isArray(value.path))
+        return false;
+    const v = value;
+    if (!('pick' in v) || !('by' in v))
+        return false;
+    if (typeof v.pick !== 'object' || v.pick === null || Array.isArray(v.pick) || !('orderBy' in v.pick))
+        return false;
+    for (const key of Object.keys(v)) {
+        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls')
+            return false;
+    }
+    return true;
+}
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/client.d.ts

@@ -68,6 +68,19 @@ export interface PgCompatPoolClient {
      * sequential.
      */
     readonly supportsPipelining?: boolean;
+    /**
+     * Optional engine seam: scope a transaction's user callback to its own
+     * async subtree. When present, `TurbineClient.transaction` / `$transaction`
+     * invoke the callback as `wrapTransactionCallback(() => fn(tx))` instead of
+     * `fn(tx)` directly. Single-writer engines (PowDB) implement it with
+     * `AsyncLocalStorage.run()` to plant their re-entrancy marker so that it
+     * exists ONLY inside the callback's async subtree: a transaction opened
+     * from inside the callback is detected as re-entrant (typed E017), while
+     * the CALLER's context stays unmarked, so same-tick sibling transactions
+     * queue FIFO instead of being falsely flagged. Absent on pg and every other
+     * engine, in which case the callback runs unwrapped (zero behavior change).
+     */
+    wrapTransactionCallback?<R>(fn: () => Promise<R>): Promise<R>;
 }
 /**
  * Minimal pg-compatible pool. Pass any driver that satisfies this interface

package/dist/client.js

@@ -775,7 +775,12 @@ export class TurbineClient {
         try {
             await client.query(this.dialect.beginStatement());
             began = true;
-            const result = await fn(client);
+            // Engine seam: single-writer engines scope their transaction re-entrancy
+            // marker to the callback's async subtree (see
+            // PgCompatPoolClient.wrapTransactionCallback). Absent everywhere else.
+            const wrap = client.wrapTransactionCallback;
+            // `.call` erases the generic, so the callback's Promise<T> is re-asserted.
+            const result = wrap ? (await wrap.call(client, () => fn(client))) : await fn(client);
             await client.query(this.dialect.commitStatement());
             return result;
         }
@@ -868,6 +873,12 @@ export class TurbineClient {
                 }
             }
             let result;
+            // Engine seam: when the checked-out connection exposes
+            // wrapTransactionCallback (single-writer engines such as PowDB), run the user
+            // callback through it so the engine can scope its re-entrancy marker to
+            // the callback's async subtree. All other drivers: plain fn(tx).
+            const wrap = client.wrapTransactionCallback;
+            const runCallback = () => (wrap ? wrap.call(client, () => fn(tx)) : fn(tx));
             if (timeout) {
                 // Race between the function and a timeout. If the timeout fires we
                 // need to actually abort the in-flight query — otherwise the backend
@@ -889,14 +900,14 @@ export class TurbineClient {
                     }, timeout);
                 });
                 try {
-                    result = await Promise.race([fn(tx), timeoutPromise]);
+                    result = await Promise.race([runCallback(), timeoutPromise]);
                 }
                 finally {
                     clearTimeout(timer);
                 }
             }
             else {
-                result = await fn(tx);
+                result = await runCallback();
             }
             await client.query(this.dialect.commitStatement());
             if (this.logging) {

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';

package/dist/mssql.js

@@ -745,11 +745,32 @@ function buildForJsonSubquery(dialect, ctx) {
         if (hasOrder) {
             const orderBy = orderEntries
                 .map(([k, dir]) => {
-                const col = camelToSnake(k);
+                // FOR JSON nested ordering supports plain directions and { sort }
+                // specs only. Object shapes the core builder compiles with params
+                // (JSON-path / vector / relation ordering) must throw here: the
+                // shared param-collect mirror is gated on the native path, so a
+                // silently-ignored object would desync SQL text from params.
+                let rawDir = dir;
+                if (typeof dir === 'object' && dir !== null) {
+                    const sortValue = dir.sort;
+                    if (typeof sortValue !== 'string') {
+                        throw new ValidationError(`[turbine] Nested orderBy on "${k}" (table "${targetTable}"): only plain directions and ` +
+                            `{ sort } specs are supported inside a relation orderBy on SQL Server.`);
+                    }
+                    if (dir.nulls !== undefined) {
+                        throw new UnsupportedFeatureError('NULLS FIRST/LAST ordering', 'sqlserver', 'Explicit nulls placement in orderBy is only available on PostgreSQL and SQLite.');
+                    }
+                    rawDir = sortValue;
+                }
+                // columnMap-first resolution (camelToSnake fallback): matches the
+                // core builder's nested orderBy path so camelCase-named DB columns
+                // resolve on SQL Server too.
+                const col = targetMeta.columnMap[k] ?? camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
+                    throw new ValidationError(`[turbine] Unknown field "${k}" in orderBy on table "${targetTable}". ` +
+                        `Known fields: ${Object.keys(targetMeta.columnMap).join(', ') || '(none)'}.`);
                 }
-                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const safeDir = String(rawDir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${a}.${q(col)} ${safeDir}`;
             })
                 .join(', ');

package/dist/powdb.d.ts

@@ -120,6 +120,18 @@ interface PowdbClientPool {
     withClient<T>(fn: (c: PowdbClient) => Promise<T>): Promise<T>;
     close(): Promise<void>;
 }
+interface PowdbModule {
+    Client: {
+        connect(opts: PowdbConnOptions): Promise<PowdbClient>;
+    };
+    Pool: new (opts: PowdbConnOptions & {
+        max?: number;
+    }) => PowdbClientPool;
+    isPowDBError?(err: unknown): err is {
+        code: string;
+        message: string;
+    };
+}
 /** Connection options for {@link turbinePowDB} — host/port, not a connection string. */
 export interface PowdbConnOptions {
     host: string;
@@ -260,8 +272,22 @@ export declare class PowdbPool implements PgCompatPool {
     private readonly txGate;
     /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
     private poolHold;
+    /**
+     * Clients currently checked out via {@link connect}. The driver pool's
+     * `close()` only closes IDLE clients (checked-out ones are documented as the
+     * caller's responsibility), so {@link end} destroys these explicitly;
+     * otherwise a `disconnect()` racing an unreleased connection would leave a
+     * live socket holding the process open until the server's idle timeout.
+     */
+    private readonly checkedOut;
     constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam, options?: PowdbPoolOptions);
     query(text: QueryArg, values?: unknown[]): Promise<any>;
+    /**
+     * Typed guard mirroring {@link PowdbEmbeddedPool}: after `end()` the driver
+     * pool throws a raw `Error('pool closed')` that {@link wrapPowdbError}
+     * cannot classify — surface the same ConnectionError on both transports.
+     */
+    private assertOpen;
     connect(): Promise<PgCompatPoolClient>;
     end(): Promise<void>;
 }
@@ -361,6 +387,13 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * E017 — queueing that shape would deadlock.
      */
     transactionQueueTimeoutMs?: number;
+    /**
+     * Driver-module injection for the networked target forms (URL / host+port):
+     * bypasses the dynamic `import('@zvndev/powdb-client')` and uses this object
+     * as the driver module instead. Intended for tests (a fake pool that counts
+     * connections) and advanced embedding; everyday callers never set it.
+     */
+    powdbClientModule?: PowdbModule;
 }
 /**
  * Selects the **embedded** transport — an in-process `@zvndev/powdb-embedded`