turbine-orm 0.31.0 → 0.32.0

package/dist/cjs/query/filters.js

@@ -26,6 +26,7 @@ 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");
@@ -316,6 +317,33 @@ function isJsonPathOrderBy(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/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 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 GroupByArgs, type HavingClause, type JsonFilter, 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 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/powql.js

@@ -38,6 +38,7 @@ import { randomUUID } from 'node:crypto';
 import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { PowdbFloatParam, powqlColumnType, quotePowqlIdent, rowToEntity } from './powdb.js';
+import { isRelationPickOrderBy } from './query/filters.js';
 import { escapeLike } from './query/utils.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -475,7 +476,22 @@ export class PowqlInterface {
             return '';
         const parts = keys.map(([field, dir]) => {
             if (dir && typeof dir === 'object') {
-                throw new UnsupportedFeatureError('vector / distance ordering', 'PowDB', `field "${field}"`);
+                // Name the actual feature in the refusal — a pick-row ordering
+                // reported as "vector / distance ordering" sends users hunting for
+                // pgvector docs. All object-valued orderings stay E017 on PowDB.
+                const o = dir;
+                const feature = isRelationPickOrderBy(dir)
+                    ? 'relation pick-row ordering'
+                    : 'distance' in o
+                        ? 'vector / distance ordering'
+                        : Array.isArray(o.path)
+                            ? 'JSON-path ordering'
+                            : '_count' in o
+                                ? 'relation _count ordering'
+                                : 'sort' in o || 'nulls' in o
+                                    ? 'NULLS placement / sort-spec ordering'
+                                    : 'object-valued ordering';
+                throw new UnsupportedFeatureError(feature, 'PowDB', `field "${field}"`);
             }
             return `${this.ref(field)} ${dir === 'desc' ? 'desc' : 'asc'}`;
         });
@@ -1119,6 +1135,27 @@ export class PowqlInterface {
     }
     async groupBy(args) {
         return this.withMiddleware('groupBy', args, async () => {
+            // The SQL-only groupBy extensions (DISTINCT ON row source, JSON-path
+            // group keys / aggregate targets) have no PowQL equivalent: refuse
+            // clearly instead of emitting broken PowQL.
+            if (args.distinctOn) {
+                throw new UnsupportedFeatureError('groupBy distinctOn row source', 'PowDB');
+            }
+            for (const entry of args.by) {
+                if (typeof entry !== 'string') {
+                    throw new UnsupportedFeatureError('JSON-path groupBy keys', 'PowDB');
+                }
+            }
+            for (const fn of ['_sum', '_avg', '_min', '_max']) {
+                const spec = args[fn];
+                if (!spec)
+                    continue;
+                for (const value of Object.values(spec)) {
+                    if (value !== undefined && typeof value !== 'boolean') {
+                        throw new UnsupportedFeatureError(`JSON-path ${fn} aggregate targets`, 'PowDB');
+                    }
+                }
+            }
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             const where = this.buildWhere(resolvedWhere, params);

package/dist/query/batched-loader.d.ts

@@ -138,6 +138,18 @@ export declare function neededParentKeyFields(parentMeta: TableMetadata, withCla
  * ({@link ValidationError}) when a named relation is to-one.
  */
 export declare function resolveCountRelations(parentMeta: TableMetadata, countSpec: WithCount): RelationDef[];
+/**
+ * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy —
+ * strategy parity with the join path, which throws this exact E003 at SQL
+ * build time (`pickOrderNestedError` in builder.ts). Without this guard the
+ * loaders would forward `options.orderBy` as the child reader's TOP-LEVEL
+ * findMany orderBy, where the pick shape compiles fine — so the same query
+ * would execute on 'batched' but throw on 'join'. Walks the whole tree up
+ * front so acceptance never depends on which levels have rows — the batched
+ * runners in builder.ts call this BEFORE the base query (a zero-row base
+ * result must still reject, exactly like the join strategy's build-time throw).
+ */
+export declare function rejectNestedPickOrder(withClause: WithClause): void;
 /**
  * Load every relation in `withClause` for `parents` and attach it onto each row
  * in place. Mirrors the join strategy's output shape exactly. Recurses for nested

package/dist/query/batched-loader.js

@@ -48,6 +48,7 @@
  */
 import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { normalizeKeyColumns } from '../schema.js';
+import { isRelationPickOrderBy } from './filters.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
  * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit — it
@@ -177,6 +178,34 @@ export function resolveCountRelations(parentMeta, countSpec) {
 function keyOf(value) {
     return String(value);
 }
+/**
+ * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy —
+ * strategy parity with the join path, which throws this exact E003 at SQL
+ * build time (`pickOrderNestedError` in builder.ts). Without this guard the
+ * loaders would forward `options.orderBy` as the child reader's TOP-LEVEL
+ * findMany orderBy, where the pick shape compiles fine — so the same query
+ * would execute on 'batched' but throw on 'join'. Walks the whole tree up
+ * front so acceptance never depends on which levels have rows — the batched
+ * runners in builder.ts call this BEFORE the base query (a zero-row base
+ * result must still reject, exactly like the join strategy's build-time throw).
+ */
+export function rejectNestedPickOrder(withClause) {
+    for (const spec of Object.values(withClause)) {
+        if (!spec || spec === true)
+            continue;
+        const options = spec;
+        if (options.orderBy) {
+            for (const [key, value] of Object.entries(options.orderBy)) {
+                if (isRelationPickOrderBy(value)) {
+                    throw new ValidationError(`[turbine] Pick-row ordering on relation "${key}" is only supported in a top-level ` +
+                        'findMany orderBy: nested `with` orderBy does not support it.');
+                }
+            }
+        }
+        if (options.with)
+            rejectNestedPickOrder(options.with);
+    }
+}
 /**
  * Load every relation in `withClause` for `parents` and attach it onto each row
  * in place. Mirrors the join strategy's output shape exactly. Recurses for nested
@@ -185,6 +214,10 @@ function keyOf(value) {
 export async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0, path = [ctx.parentMeta.name]) {
     if (depth >= MAX_DEPTH)
         throw new CircularRelationError([...path, '…']);
+    // Scope-rule parity with the join strategy: validate the whole tree BEFORE
+    // the empty-parents early return, so accept/reject never depends on data.
+    if (depth === 0)
+        rejectNestedPickOrder(withClause);
     if (parents.length === 0)
         return;
     // Sibling relations are independent (each writes only its own parent[relName]

package/dist/query/builder.d.ts

@@ -339,6 +339,27 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    /**
+     * Validate a JSON-path target (group key or aggregate target) in groupBy:
+     * the field must resolve to a real json/jsonb column and the path must be a
+     * non-empty array of keys/indexes. Returns the resolved snake_case column.
+     */
+    private resolveJsonPathTarget;
+    /**
+     * Build the `distinctOn` row source for groupBy (PostgreSQL only: other
+     * engines throw {@link UnsupportedFeatureError} E017):
+     *
+     * ```sql
+     * (SELECT DISTINCT ON ("c1") * FROM "table"<WHERE> ORDER BY "c1", <orderBy>) AS "table"
+     * ```
+     *
+     * The wrapper is aliased as the table name so every outer expression (group
+     * keys, aggregates, HAVING, ORDER BY) is byte-identical to the plain path.
+     * `distinctOn.orderBy` is required (it decides which row survives) and
+     * supports plain columns, {@link OrderBySpec} nulls, and JSON-path specs;
+     * JSON paths push their text[] param here, after the WHERE params.
+     */
+    private buildDistinctOnSource;
     /**
      * Build the SQL fragments for a {@link HavingClause}.
      *
@@ -349,6 +370,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * comparison value is pushed onto the shared `params` array and referenced by
      * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
      * interpolation of user values.
+     *
+     * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
+     * exact aggregate expression a JSON-path aggregate emitted in SELECT
+     * (including its already-bound path placeholder), so HAVING on a JSON-path
+     * aggregate alias reuses the same expression instead of resolving the alias
+     * as a column.
      */
     private buildHavingClauses;
     /**
@@ -712,6 +739,46 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * the correlation parent is the relation's alias, not `this.table`.
      */
     private buildRelationOrderBy;
+    /**
+     * Validate a {@link RelationPickOrderBy} entry's scope and shape. Shared by
+     * the SQL-build path ({@link buildRelationPickOrderBy}) and the cache-hit
+     * param-collect mirror ({@link collectRelationPickOrderParams}) so both
+     * always throw identically:
+     *
+     *  - `nested` (inside a relation subquery's orderBy or a pick.orderBy):
+     *    top-level findMany only in this release (E003),
+     *  - manyToMany: not supported (E003 naming the limitation),
+     *  - to-one: order by the target column directly instead (E003),
+     *  - `pick.orderBy` is REQUIRED (deterministic row choice),
+     *  - `by` must be a target column name or a `{ field, path }` JSON-path spec.
+     */
+    private pickOrderNestedError;
+    private validatePickOrderBy;
+    /**
+     * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
+     * that picks ONE related row (`ORDER BY <pick.orderBy> LIMIT 1`, optionally
+     * filtered by `pick.where` and the target's global filter) and surfaces one
+     * value from it (a plain target column or a JSON-path extraction) as the
+     * parent ORDER BY key:
+     *
+     * ```sql
+     * (SELECT ord0."data" #>> $1::text[] FROM "versions" ord0
+     *   WHERE ord0."instance_id" = "instances"."id" AND ord0."is_current" = $2
+     *   ORDER BY ord0."created_at" DESC LIMIT 1) ASC NULLS LAST
+     * ```
+     *
+     * Param-push order (mirrored EXACTLY by
+     * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
+     * target global filter → `pick.where` → `pick.orderBy` JSON paths.
+     */
+    private buildRelationPickOrderBy;
+    /**
+     * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same
+     * validation (a warmed cache can never skip it), then pushes in the same
+     * order: `by` JSON path → target global filter → `pick.where` →
+     * `pick.orderBy` JSON paths.
+     */
+    private collectRelationPickOrderParams;
     /**
      * Compile the ORDER BY terms of a relation `with` clause against the
      * relation's table alias. One unified path for every relation shape
@@ -1009,6 +1076,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Used to detect JSONB/array columns for specialized operators.
      * Uses pre-computed Map for O(1) lookup instead of linear scan.
      */
+    /**
+     * Case-insensitive json/jsonb column-type check. Postgres reports lowercase
+     * udt_names, but SQLite/MySQL introspection surfaces the DECLARED type
+     * (e.g. `JSON`), so every JSON-feature gate compares through this predicate
+     * — build and collect sides alike, keeping the SQL-cache lockstep.
+     */
+    private isJsonColumnType;
     private getColumnPgType;
     /**
      * Get the Postgres base element type for an array column.
@@ -1033,6 +1107,18 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * stays byte-identical to {@link collectJsonFilterParams}.
      */
     private buildJsonFilterClauses;
+    /**
+     * Bind value for a JSON path parameter, encoded per dialect. PostgreSQL's
+     * `#>>` takes a `text[]` (the segments as strings — or `nativeForm` when the
+     * caller has a specific native binding, e.g. JsonFilter's raw path array).
+     * Every other engine's JSON function (`json_extract` / `JSON_EXTRACT` /
+     * `JSON_VALUE`) takes a `'$'`-rooted JSONPath STRING: binding the raw array
+     * would arrive as `'["a"]'` (the driver shims JSON.stringify non-primitive
+     * params) and fail at runtime with the engine's bad-JSON-path error. The
+     * encoded path stays a bound parameter — never spliced into SQL text — so
+     * the build/collect param mirrors stay in lockstep and injection-safe.
+     */
+    private jsonPathParam;
     /**
      * Cast an extracted JSON path text value to a numeric type for range
      * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to