@prisma-next/sql-orm-client 0.10.0-dev.9 → 0.11.0

package/package.json

@@ -1,32 +1,31 @@
 {
   "name": "@prisma-next/sql-orm-client",
-  "version": "0.10.0-dev.9",
+  "version": "0.11.0",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "ORM client for Prisma Next — fluent, type-safe model collections",
   "dependencies": {
-    "@prisma-next/contract": "0.10.0-dev.9",
-    "@prisma-next/framework-components": "0.10.0-dev.9",
-    "@prisma-next/operations": "0.10.0-dev.9",
-    "@prisma-next/sql-contract": "0.10.0-dev.9",
-    "@prisma-next/sql-operations": "0.10.0-dev.9",
-    "@prisma-next/sql-relational-core": "0.10.0-dev.9",
-    "@prisma-next/sql-runtime": "0.10.0-dev.9",
-    "@prisma-next/utils": "0.10.0-dev.9"
+    "@prisma-next/contract": "0.11.0",
+    "@prisma-next/framework-components": "0.11.0",
+    "@prisma-next/operations": "0.11.0",
+    "@prisma-next/sql-contract": "0.11.0",
+    "@prisma-next/sql-operations": "0.11.0",
+    "@prisma-next/sql-relational-core": "0.11.0",
+    "@prisma-next/sql-runtime": "0.11.0",
+    "@prisma-next/utils": "0.11.0"
   },
   "devDependencies": {
-    "@prisma-next/adapter-postgres": "0.10.0-dev.9",
-    "@prisma-next/driver-postgres": "0.10.0-dev.9",
-    "@prisma-next/cli": "0.10.0-dev.9",
-    "@prisma-next/extension-pgvector": "0.10.0-dev.9",
-    "@prisma-next/family-sql": "0.10.0-dev.9",
-    "@prisma-next/ids": "0.10.0-dev.9",
-    "@prisma-next/sql-contract-ts": "0.10.0-dev.9",
-    "@prisma-next/target-postgres": "0.10.0-dev.9",
-    "@prisma-next/test-utils": "0.10.0-dev.9",
-    "@prisma-next/tsconfig": "0.10.0-dev.9",
-    "@prisma-next/tsdown": "0.10.0-dev.9",
+    "@prisma-next/adapter-postgres": "0.11.0",
+    "@prisma-next/cli": "0.11.0",
+    "@prisma-next/driver-postgres": "0.11.0",
+    "@prisma-next/family-sql": "0.11.0",
+    "@prisma-next/ids": "0.11.0",
+    "@prisma-next/sql-contract-ts": "0.11.0",
+    "@prisma-next/target-postgres": "0.11.0",
+    "@prisma-next/test-utils": "0.11.0",
+    "@prisma-next/tsconfig": "0.11.0",
+    "@prisma-next/tsdown": "0.11.0",
     "@types/pg": "8.20.0",
     "pg": "8.20.0",
     "tsdown": "0.22.0",
@@ -52,7 +51,7 @@
   },
   "scripts": {
     "build": "tsdown",
-    "emit": "node ../../1-framework/3-tooling/cli/dist/cli.js contract emit --config test/fixtures/prisma-next.config.ts",
+    "emit": "cd ../../../test/integration && node ../../packages/1-framework/3-tooling/cli/dist/cli.js contract emit --config test/sql-orm-client/fixtures/prisma-next.config.ts && cp test/sql-orm-client/fixtures/generated/contract.json test/sql-orm-client/fixtures/generated/contract.d.ts ../../packages/3-extensions/sql-orm-client/test/fixtures/generated/ && cd ../../packages/3-extensions/sql-orm-client && node scripts/strip-pgvector-fixture.mjs test/fixtures/generated/contract.d.ts",
     "emit:check": "pnpm emit && git diff --exit-code test/fixtures/generated/",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",

package/src/collection-dispatch.ts

@@ -31,6 +31,10 @@ import {
 } from './collection-runtime';
 import { executeQueryPlan } from './execute-query-plan';
 import { selectIncludeStrategy } from './include-strategy';
+import {
+  hasNonLeafIncludeWithDistinct,
+  hasScalarOrCombineIncludeDescriptors,
+} from './include-tree-predicates';
 import {
   compileRelationSelect,
   compileSelect,
@@ -77,9 +81,23 @@ function dispatchWithIncludeStrategy<Row>(options: {
 }): AsyncIterableResult<Row> {
   const strategy = selectIncludeStrategy(options.contract);
 
+  // Nested row includes (depth >= 2) are emitted recursively by the
+  // lateral / correlated builders — they no longer force a fallback to
+  // multi-query (TML-2594). Scalar (`count`/`sum`/...) and `combine()`
+  // descriptors still do, until TML-2595 lands the matching lowering;
+  // the recursive scan below catches them at any depth so a nested
+  // `count()` inside a row include doesn't accidentally hit the
+  // throw in `compileSelectWithIncludeStrategy`.
+  //
+  // `distinct()` on a non-leaf include is also forced through multi-query:
+  // under the single-query strategies the child SELECT carries nested
+  // JSON aggregate columns, and `SELECT DISTINCT` over those fails on
+  // Postgres (`json` has no equality operator). The multi-query stitcher
+  // applies distinct to scalar-only child rows before grandchildren are
+  // joined, which is the semantically correct behavior we preserve.
   if (
-    hasNestedIncludes(options.state.includes) ||
-    hasComplexIncludeDescriptors(options.state.includes)
+    hasScalarOrCombineIncludeDescriptors(options.state.includes) ||
+    hasNonLeafIncludeWithDistinct(options.state.includes)
   ) {
     return dispatchWithMultiQueryIncludes<Row>(options);
   }
@@ -144,18 +162,10 @@ function dispatchWithSingleQueryIncludes<Row>(options: {
 
       for (const parent of parentRows) {
         for (const include of state.includes) {
-          if (include.scalar || include.combine) {
-            throw new Error(
-              'single-query include strategy does not support scalar include selectors or combine()',
-            );
-          }
-          const rawChildren = parseIncludedRows(parent.raw[include.relationName]);
-          const mappedChildren = rawChildren.map((childRow) =>
-            mapStorageRowToModelFields(contract, include.relatedModelName, childRow),
-          );
-          parent.mapped[include.relationName] = coerceSingleQueryIncludeResult(
-            mappedChildren,
-            include.cardinality,
+          parent.mapped[include.relationName] = decodeIncludePayload(
+            contract,
+            include,
+            parent.raw[include.relationName],
           );
         }
 
@@ -372,8 +382,22 @@ async function resolveRowsByParent(
   state: CollectionState,
   parentJoinValues: readonly unknown[],
 ): Promise<Map<unknown, Record<string, unknown>[]>> {
+  // Multi-query stitching reads `child.raw[grandchildInclude.localColumn]`
+  // for every immediate include in `state.includes` to bucket children by
+  // join value. A user-supplied `.select(...)` on the child that omits any
+  // of those join columns would silently yield `undefined` for the join
+  // value, producing empty nested arrays at depth >= 2. Force every
+  // direct nested include's `localColumn` into the child's selected set
+  // alongside `include.targetColumn` so the stitcher always sees a
+  // defined join value. The next level of recursion (when grandchild
+  // stitching itself dispatches through `resolveRowsByParent`) repeats
+  // this same augmentation for its own children.
+  const nestedJoinColumns = state.includes.map((nested) => nested.localColumn);
+  const requiredChildColumns = Array.from(
+    new Set<string>([include.targetColumn, ...nestedJoinColumns]),
+  );
   const { selectedForQuery: childSelectedForQuery, hiddenColumns: hiddenChildColumns } =
-    augmentSelectionForJoinColumns(state.selectedFields, [include.targetColumn]);
+    augmentSelectionForJoinColumns(state.selectedFields, requiredChildColumns);
 
   const childCompiled = compileRelationSelect(
     contract,
@@ -471,12 +495,44 @@ function uniqueValues(values: unknown[]): unknown[] {
   return [...new Set(values)];
 }
 
-function hasNestedIncludes(includes: readonly IncludeExpr[]): boolean {
-  return includes.some((include) => include.nested.includes.length > 0);
-}
-
-function hasComplexIncludeDescriptors(includes: readonly IncludeExpr[]): boolean {
-  return includes.some((include) => include.scalar !== undefined || include.combine !== undefined);
+/**
+ * Decode a single-query include payload from a parent row's raw cell
+ * into the model-shaped value that downstream consumers see. Recurses
+ * through `include.nested.includes` so depth-2+ trees — emitted by the
+ * recursive lateral / correlated builders — are decoded symmetrically.
+ *
+ * The shape produced by the SQL side is one JSON column per top-level
+ * include; values nested inside that JSON are already-parsed JS values
+ * after the outer `JSON.parse`, so `parseIncludedRows` recognises both
+ * the string (top-level) and array (nested) forms.
+ */
+function decodeIncludePayload(
+  contract: Contract<SqlStorage>,
+  include: IncludeExpr,
+  raw: unknown,
+): Record<string, unknown>[] | Record<string, unknown> | null {
+  const rawChildren = parseIncludedRows(raw);
+  const mappedChildren = rawChildren.map((childRow) => {
+    const mapped = mapStorageRowToModelFields(contract, include.relatedModelName, childRow);
+    for (const nestedInclude of include.nested.includes) {
+      // Defence in depth: the dispatch gate filters scalar/combine at
+      // any depth via `hasScalarOrCombineIncludeDescriptors`. This branch
+      // is unreachable in production but documents the contract the
+      // recursion relies on.
+      if (nestedInclude.scalar || nestedInclude.combine) {
+        throw new Error(
+          'single-query include strategy does not support nested scalar include selectors or combine()',
+        );
+      }
+      mapped[nestedInclude.relationName] = decodeIncludePayload(
+        contract,
+        nestedInclude,
+        mapped[nestedInclude.relationName],
+      );
+    }
+    return mapped;
+  });
+  return coerceSingleQueryIncludeResult(mappedChildren, include.cardinality);
 }
 
 function assignEmptyIncludeResult(parentRows: RowEnvelope[], include: IncludeExpr): void {

package/src/exports/index.ts

@@ -1,6 +1,7 @@
 export { Collection } from '../collection';
 export { all, and, not, or } from '../filters';
 export { GroupedCollection } from '../grouped-collection';
+export { createModelAccessor } from '../model-accessor';
 export type { OrmOptions } from '../orm';
 export { orm } from '../orm';
 export type {
@@ -17,6 +18,7 @@ export type {
   DefaultModelRow,
   IncludeExpr,
   ModelAccessor,
+  NumericFieldNames,
   RelatedModelName,
   RelationFilterAccessor,
   RelationMutator,

package/src/include-tree-predicates.ts

@@ -0,0 +1,50 @@
+import type { IncludeExpr } from './types';
+
+/**
+ * Recursive predicate: does any include in the tree carry a
+ * non-leaf `distinct()` — i.e. `nested.distinct` set on an include
+ * whose `nested.includes` is non-empty?
+ *
+ * Such shapes cannot be lowered into the lateral / correlated
+ * single-query strategies: the child SELECT would emit
+ * `SELECT DISTINCT <scalars>, json_agg(<nested>) FROM ...`, and
+ * Postgres rejects equality on `json`. The dispatch path routes
+ * these to multi-query (which applies distinct to scalar-only rows
+ * before grandchildren stitch in JS); the planner rejects them at
+ * the boundary.
+ *
+ * `distinctOn` is intentionally not included: Postgres only
+ * compares the `ON (...)` expressions for equality, so a hashable
+ * key column plus json projections is well-defined.
+ */
+export function hasNonLeafIncludeWithDistinct(includes: readonly IncludeExpr[]): boolean {
+  return includes.some(
+    (include) =>
+      (include.nested.distinct !== undefined &&
+        include.nested.distinct.length > 0 &&
+        include.nested.includes.length > 0) ||
+      hasNonLeafIncludeWithDistinct(include.nested.includes),
+  );
+}
+
+/**
+ * Recursive predicate: does any include in the tree carry a scalar
+ * selector (`count` / `sum` / ...) or a `combine()` descriptor?
+ *
+ * Such shapes cannot be lowered into the lateral / correlated
+ * single-query strategies (TML-2595). The dispatch path uses this
+ * to gate the whole tree to multi-query at any depth; the planner
+ * (`compileSelectWithIncludeStrategy`) uses the same predicate to
+ * fail fast at the boundary rather than build a malformed plan.
+ * Without the recursion, a depth-2+ row include containing a
+ * depth-3 `count()` would fall through to the planner and hit its
+ * explicit `throw` instead of routing to multi-query.
+ */
+export function hasScalarOrCombineIncludeDescriptors(includes: readonly IncludeExpr[]): boolean {
+  return includes.some(
+    (include) =>
+      include.scalar !== undefined ||
+      include.combine !== undefined ||
+      hasScalarOrCombineIncludeDescriptors(include.nested.includes),
+  );
+}

package/src/query-plan-mutations.ts

@@ -239,7 +239,7 @@ export function compileUpsertReturning(
       ).doNothing();
 
   const ast = InsertAst.into(TableSource.named(tableName))
-    .withValues(createAssignments.assignments)
+    .withRows([createAssignments.assignments])
     .withOnConflict(onConflict)
     .withReturning(buildReturningColumns(contract, tableName, returningColumns));
 

package/src/query-plan-select.ts

@@ -29,6 +29,10 @@ import {
   resolvePolymorphismInfo,
   resolvePrimaryKeyColumn,
 } from './collection-contract';
+import {
+  hasNonLeafIncludeWithDistinct,
+  hasScalarOrCombineIncludeDescriptors,
+} from './include-tree-predicates';
 import { buildOrmQueryPlan, deriveParamsFromAst, resolveTableColumns } from './query-plan-meta';
 import type { CollectionState, IncludeExpr } from './types';
 import { bindWhereExpr } from './where-binding';
@@ -210,10 +214,54 @@ function buildIncludeOrderArtifacts(
   };
 }
 
+/**
+ * Recursively build the join + projection artifacts for the nested
+ * includes attached to a child SELECT. Used by
+ * `buildIncludeChildRowsSelect` to wire depth-2+ aggregates into the
+ * inner SELECT at each level.
+ *
+ * Under the `lateral` strategy each nested include contributes one
+ * LEFT JOIN LATERAL plus one projection item that references the
+ * lateral alias. Under the `correlated` strategy each nested include
+ * contributes a single projection item whose expression is a
+ * correlated subquery; no joins are produced. The two cases are
+ * symmetric, which is why both paths share `buildIncludeChildRowsSelect`.
+ */
+function buildNestedIncludeArtifacts(
+  contract: Contract<SqlStorage>,
+  parentTableRef: string,
+  includes: readonly IncludeExpr[],
+  strategy: 'lateral' | 'correlated',
+): {
+  readonly joins: ReadonlyArray<JoinAst>;
+  readonly projections: ReadonlyArray<ProjectionItem>;
+} {
+  if (includes.length === 0) {
+    return { joins: [], projections: [] };
+  }
+
+  const joins: JoinAst[] = [];
+  const projections: ProjectionItem[] = [];
+
+  for (const nested of includes) {
+    if (strategy === 'lateral') {
+      const artifact = buildLateralIncludeArtifacts(contract, parentTableRef, nested);
+      joins.push(artifact.join);
+      projections.push(artifact.projection);
+      continue;
+    }
+    const artifact = buildCorrelatedIncludeProjection(contract, parentTableRef, nested);
+    projections.push(artifact.projection);
+  }
+
+  return { joins, projections };
+}
+
 function buildIncludeChildRowsSelect(
   contract: Contract<SqlStorage>,
   parentTableName: string,
   include: IncludeExpr,
+  strategy: 'lateral' | 'correlated',
 ): {
   readonly childRows: SelectAst;
   readonly childProjection: ReadonlyArray<ProjectionItem>;
@@ -225,16 +273,28 @@ function buildIncludeChildRowsSelect(
     include.relatedTableName === parentTableName ? `${include.relationName}__child` : undefined;
   const childTableRef = childTableAlias ?? include.relatedTableName;
   const rowsAlias = `${include.relationName}__rows`;
-  const childProjection = buildProjection(
+  const scalarProjection = buildProjection(
     contract,
     include.relatedTableName,
     childState.selectedFields,
     childTableRef,
   );
+  // Self-relations rename the inner table source via `childTableAlias`,
+  // so any ColumnRef the user-supplied `orderBy` carries against the
+  // original `include.relatedTableName` is no longer in scope inside the
+  // child SELECT. Remap before lowering to the hidden order projection
+  // — mirrors the `filterTableName` remap `buildStateWhere` applies to
+  // the where clauses just below.
+  const remappedChildOrderBy =
+    childTableAlias && childState.orderBy
+      ? childState.orderBy.map((item) =>
+          item.rewrite(createTableRefRemapper(include.relatedTableName, childTableRef)),
+        )
+      : childState.orderBy;
   const { childOrderBy, hiddenOrderProjection, aggregateOrderBy } = buildIncludeOrderArtifacts(
     include.relationName,
     rowsAlias,
-    childState.orderBy,
+    remappedChildOrderBy,
   );
   const childWhere = buildStateWhere(contract, childTableRef, childState, {
     filterTableName: include.relatedTableName,
@@ -245,8 +305,30 @@ function buildIncludeChildRowsSelect(
   );
   const whereExpr = childWhere ? AndExpr.of([joinExpr, childWhere]) : joinExpr;
 
+  // Recurse: each nested include produces either a LATERAL JOIN (under
+  // `lateral`) or a correlated subquery projection (under `correlated`).
+  // The nested aggregates are attached to *this* child SELECT, so they
+  // correlate against `childTableRef` — which may itself be an alias if
+  // the relation is self-referential.
+  const { joins: nestedJoins, projections: nestedProjections } = buildNestedIncludeArtifacts(
+    contract,
+    childTableRef,
+    childState.includes,
+    strategy,
+  );
+
+  // `childProjection` is the set of items that survive into the parent's
+  // JSON object — the scalar columns plus any nested-include aggregate
+  // columns. The hidden order-by projection is separate and is dropped
+  // before assembling the parent's json_object_expr.
+  const childProjection: ReadonlyArray<ProjectionItem> = [
+    ...scalarProjection,
+    ...nestedProjections,
+  ];
+
   let childRows = SelectAst.from(TableSource.named(include.relatedTableName, childTableAlias))
     .withProjection([...childProjection, ...hiddenOrderProjection])
+    .withJoins(nestedJoins)
     .withWhere(whereExpr);
 
   if (childOrderBy) {
@@ -286,6 +368,7 @@ function buildLateralIncludeArtifacts(
     contract,
     parentTableName,
     include,
+    'lateral',
   );
   const lateralAlias = `${include.relationName}_lateral`;
   const jsonObjectExpr = JsonObjectExpr.fromEntries(
@@ -323,6 +406,7 @@ function buildCorrelatedIncludeProjection(
     contract,
     parentTableName,
     include,
+    'correlated',
   );
   const jsonObjectExpr = JsonObjectExpr.fromEntries(
     childProjection.map((item) =>
@@ -483,14 +567,24 @@ export function compileSelectWithIncludeStrategy(
   strategy: 'lateral' | 'correlated',
   modelName?: string,
 ): SqlQueryPlan<Record<string, unknown>> {
-  if (
-    state.includes.some((include) => include.scalar !== undefined || include.combine !== undefined)
-  ) {
+  if (hasScalarOrCombineIncludeDescriptors(state.includes)) {
     throw new Error(
       'single-query include strategy does not support scalar include selectors or combine()',
     );
   }
 
+  // Same recursive shape as the scalar/combine gate above. A non-leaf
+  // `distinct()` cannot be lowered into the single-query strategies:
+  // the child SELECT would emit `SELECT DISTINCT <scalars>, json_agg(...)`,
+  // and Postgres rejects equality on `json`. The dispatch path routes
+  // these to multi-query; direct planner callers (tests, rich-plan
+  // consumers) fail fast here instead of building an invalid plan.
+  if (hasNonLeafIncludeWithDistinct(state.includes)) {
+    throw new Error(
+      'single-query include strategy does not support distinct() on a non-leaf include',
+    );
+  }
+
   const includeJoins: JoinAst[] = [];
   const includeProjection: ProjectionItem[] = [];
   const topLevelWhere = buildStateWhere(contract, tableName, state);