feat(sql-orm-client): M:N correlated read-through-junction include

Add many-to-many include support via a single correlated subquery that
joins the child table to the junction on junction.childColumns = child.targetColumns
and correlates to the parent via WHERE junction.parentColumns = parent.parentLocalColumns.
Composite keys AND across all column pairs. No LATERAL joins.

- IncludeExpr gains `through?: IncludeThroughDescriptor` carrying junction table
  name, parentColumns, childColumns, targetColumns, and parentLocalColumns.
- `resolveIncludeRelation` in collection-contract.ts surfaces `through` from the
  contract relation when present, resolving field names to column names for the
  parent local columns.
- `Collection.include()` propagates `through` into IncludeExpr via spread.
- `buildManyToManyJunctionArtifacts` in query-plan-select.ts builds the JOIN ON
  expression (BinaryExpr or AndExpr over child column pairs) and the correlated
  WHERE (BinaryExpr or AndExpr over parent column pairs), producing a non-lateral
  inner JoinAst to the junction table.
- `buildIncludeChildRowsSelect` detects `include.through` and uses the M:N
  artifacts instead of the FK equality WHERE; `buildDistinctNonLeafChildRowsSelect`
  receives and applies the same junction joins.
- `dispatchWithIncludes` in collection-dispatch.ts forces all `through.parentLocalColumns`
  (not just `localColumn`) into the parent SELECT augmentation for composite M:N keys.
- `buildManyToManyContract` test helper and M:N unit tests covering single-column
  and composite-key junction shapes, plus a FK path non-regression test.

Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>

Author: tensordreams

packages/3-extensions/sql-orm-client/src/collection-contract.ts

@@ -6,7 +6,7 @@ import {
 } from '@prisma-next/contract/types';
 import type { SqlStorage, StorageTable } from '@prisma-next/sql-contract/types';
 import { castAs } from '@prisma-next/utils/casts';
-import type { RelationCardinalityTag } from './types';
+import type { IncludeThroughDescriptor, RelationCardinalityTag } from './types';
 
 type ModelStorageFields = Record<string, { column?: string }>;
 type ModelEntry = {
@@ -221,6 +221,7 @@ export interface ResolvedIncludeRelation {
   readonly targetColumn: string;
   readonly localColumn: string;
   readonly cardinality: RelationCardinalityTag | undefined;
+  readonly through?: IncludeThroughDescriptor;
 }
 
 export function resolveIncludeRelation(
@@ -245,12 +246,27 @@ export function resolveIncludeRelation(
   const localColumn = resolveFieldToColumn(contract, modelName, localField);
   const targetColumn = resolveFieldToColumn(contract, relation.to, targetField);
 
+  let through: IncludeThroughDescriptor | undefined;
+  if (relation.through !== undefined) {
+    const parentLocalColumns = relation.on.localFields.map((field) =>
+      resolveFieldToColumn(contract, modelName, field),
+    );
+    through = {
+      table: relation.through.table,
+      parentColumns: relation.through.parentColumns,
+      childColumns: relation.through.childColumns,
+      targetColumns: relation.through.targetColumns,
+      parentLocalColumns,
+    };
+  }
+
   return {
     relatedModelName: relation.to,
     relatedTableName,
     targetColumn,
     localColumn,
     cardinality: relation.cardinality,
+    ...(through !== undefined ? { through } : {}),
   };
 }
 

packages/3-extensions/sql-orm-client/src/collection-dispatch.ts

@@ -91,7 +91,9 @@ function dispatchWithIncludes<Row>(options: {
   const generator = async function* (): AsyncGenerator<Row, void, unknown> {
     const { scope, release } = await acquireRuntimeScope(runtime);
     try {
-      const parentJoinColumns = state.includes.map((include) => include.localColumn);
+      const parentJoinColumns = state.includes.flatMap((include) =>
+        include.through !== undefined ? include.through.parentLocalColumns : [include.localColumn],
+      );
       const { selectedForQuery: parentSelectedForQuery, hiddenColumns: hiddenParentColumns } =
         augmentSelectionForJoinColumns(state.selectedFields, parentJoinColumns);
       const compiled = compileSelectWithIncludes(

packages/3-extensions/sql-orm-client/src/collection.ts

@@ -481,6 +481,7 @@ export class Collection<
       targetColumn: relation.targetColumn,
       localColumn: relation.localColumn,
       cardinality: relation.cardinality,
+      ...(relation.through !== undefined ? { through: relation.through } : {}),
       nested: nestedState,
       scalar: scalarSelector,
       combine: combineBranches,

packages/3-extensions/sql-orm-client/src/query-plan-select.ts

@@ -288,6 +288,53 @@ function buildNestedIncludeProjections(
   );
 }
 
+/**
+ * Build the correlated WHERE and junction JOIN artifacts for a many-to-many
+ * include. The resulting WHERE correlates the junction to the parent rows
+ * (AND-ed across all column pairs for composite keys). The junction JOIN
+ * connects child rows to the junction via the child columns.
+ */
+function buildManyToManyJunctionArtifacts(
+  parentTableName: string,
+  childTableRef: string,
+  through: NonNullable<IncludeExpr['through']>,
+): {
+  readonly whereExpr: AnyExpression;
+  readonly junctionJoin: JoinAst;
+} {
+  const {
+    table: junctionTable,
+    parentColumns,
+    childColumns,
+    targetColumns,
+    parentLocalColumns,
+  } = through;
+
+  const joinOnPairs = childColumns.map((junctionCol, i) =>
+    BinaryExpr.eq(
+      ColumnRef.of(junctionTable, junctionCol),
+      ColumnRef.of(childTableRef, targetColumns[i] ?? junctionCol),
+    ),
+  );
+  const joinOn: AnyExpression =
+    joinOnPairs.length === 1 ? (joinOnPairs[0] as AnyExpression) : AndExpr.of(joinOnPairs);
+
+  const correlationPairs = parentColumns.map((junctionCol, i) =>
+    BinaryExpr.eq(
+      ColumnRef.of(junctionTable, junctionCol),
+      ColumnRef.of(parentTableName, parentLocalColumns[i] ?? junctionCol),
+    ),
+  );
+  const whereExpr: AnyExpression =
+    correlationPairs.length === 1
+      ? (correlationPairs[0] as AnyExpression)
+      : AndExpr.of(correlationPairs);
+
+  const junctionJoin = JoinAst.inner(TableSource.named(junctionTable), joinOn, false);
+
+  return { whereExpr, junctionJoin };
+}
+
 function buildIncludeChildRowsSelect(
   contract: Contract<SqlStorage>,
   parentTableName: string,
@@ -323,11 +370,25 @@ function buildIncludeChildRowsSelect(
   const childWhere = buildStateWhere(contract, childTableRef, childState, {
     filterTableName: include.relatedTableName,
   });
-  const joinExpr = BinaryExpr.eq(
-    ColumnRef.of(childTableRef, include.targetColumn),
-    ColumnRef.of(parentTableName, include.localColumn),
-  );
-  const whereExpr = childWhere ? AndExpr.of([joinExpr, childWhere]) : joinExpr;
+
+  let whereExpr: AnyExpression;
+  let junctionJoins: JoinAst[] = [];
+
+  if (include.through !== undefined) {
+    const artifacts = buildManyToManyJunctionArtifacts(
+      parentTableName,
+      childTableRef,
+      include.through,
+    );
+    whereExpr = childWhere ? AndExpr.of([artifacts.whereExpr, childWhere]) : artifacts.whereExpr;
+    junctionJoins = [artifacts.junctionJoin];
+  } else {
+    const joinExpr = BinaryExpr.eq(
+      ColumnRef.of(childTableRef, include.targetColumn),
+      ColumnRef.of(parentTableName, include.localColumn),
+    );
+    whereExpr = childWhere ? AndExpr.of([joinExpr, childWhere]) : joinExpr;
+  }
 
   // `distinct()` on a non-leaf include cannot be lowered as
   // `SELECT DISTINCT <scalars>, json_agg(<grandchild>) FROM ...`:
@@ -355,6 +416,7 @@ function buildIncludeChildRowsSelect(
       hiddenOrderProjection,
       aggregateOrderBy,
       whereExpr,
+      junctionJoins,
     });
   }
 
@@ -388,6 +450,10 @@ function buildIncludeChildRowsSelect(
     .withProjection([...childProjection, ...hiddenOrderProjection])
     .withWhere(whereExpr);
 
+  if (junctionJoins.length > 0) {
+    childRows = childRows.withJoins(junctionJoins);
+  }
+
   if (childState.distinctOn && childState.distinctOn.length > 0) {
     childRows = childRows.withDistinctOn(
       childState.distinctOn.map((column) => ColumnRef.of(childTableRef, column)),
@@ -450,6 +516,7 @@ function buildDistinctNonLeafChildRowsSelect(options: {
   readonly hiddenOrderProjection: ReadonlyArray<ProjectionItem>;
   readonly aggregateOrderBy: ReadonlyArray<OrderByItem> | undefined;
   readonly whereExpr: AnyExpression;
+  readonly junctionJoins: ReadonlyArray<JoinAst>;
 }): {
   readonly childRows: SelectAst;
   readonly childProjection: ReadonlyArray<ProjectionItem>;
@@ -466,6 +533,7 @@ function buildDistinctNonLeafChildRowsSelect(options: {
     hiddenOrderProjection,
     aggregateOrderBy,
     whereExpr,
+    junctionJoins,
   } = options;
   const childState = include.nested;
 
@@ -507,9 +575,12 @@ function buildDistinctNonLeafChildRowsSelect(options: {
     selectedForQuery,
     childTableRef,
   );
-  const baseInner = SelectAst.from(TableSource.named(include.relatedTableName, childTableAlias))
+  let baseInner = SelectAst.from(TableSource.named(include.relatedTableName, childTableAlias))
     .withProjection([...innerScalarProjection, ...hiddenOrderProjection])
     .withWhere(whereExpr);
+  if (junctionJoins.length > 0) {
+    baseInner = baseInner.withJoins(junctionJoins);
+  }
 
   // `childState.distinct` is non-empty by the `isDistinctNonLeaf` guard
   // at the only caller (`buildIncludeChildRowsSelect`); assert here so

packages/3-extensions/sql-orm-client/src/types.ts

@@ -50,13 +50,26 @@ export interface IncludeCombine<ResultShape extends Record<string, unknown>>
   readonly branches: Readonly<Record<string, IncludeCombineBranch>>;
 }
 
+export interface IncludeThroughDescriptor {
+  readonly table: string;
+  /** FK columns in the junction table that point to the parent. */
+  readonly parentColumns: readonly string[];
+  /** FK columns in the junction table that point to the target (child). */
+  readonly childColumns: readonly string[];
+  /** PK columns in the target table that the junction's childColumns reference. */
+  readonly targetColumns: readonly string[];
+  /** Resolved column names in the parent table that junction.parentColumns reference. */
+  readonly parentLocalColumns: readonly string[];
+}
+
 export interface IncludeExpr {
   readonly relationName: string;
   readonly relatedModelName: string;
   readonly relatedTableName: string;
   readonly targetColumn: string;
   readonly localColumn: string;
   readonly cardinality: RelationCardinalityTag | undefined;
+  readonly through?: IncludeThroughDescriptor;
   readonly nested: CollectionState;
   readonly scalar: IncludeScalar<unknown> | undefined;
   readonly combine: Readonly<Record<string, IncludeCombineBranch>> | undefined;

packages/3-extensions/sql-orm-client/test/helpers.ts

@@ -288,6 +288,146 @@ export function buildStiPolyContract(): TestContract {
   return raw as TestContract;
 }
 
+type RawColumn = { nativeType: string; codecId: string; nullable: boolean; default?: unknown };
+
+/**
+ * Builds a minimal M:N contract with Parent ↔ Child via a junction table.
+ * Used by unit tests that assert the correlated subquery shape for M:N includes.
+ *
+ * `localFields` defaults to `['id']` (single-column parent PK). For composite-key parents,
+ * pass `localFields: ['tenant_id', 'id']` — each entry resolves positionally to the
+ * corresponding junction `parentColumns` entry.
+ */
+export function buildManyToManyContract(opts: {
+  junctionTable: string;
+  parentColumns: string[];
+  childColumns: string[];
+  targetColumns: string[];
+  localFields?: string[];
+  extraColumns?: Record<string, RawColumn>;
+}): FrameworkContract<SqlStorage> {
+  const {
+    junctionTable,
+    parentColumns,
+    childColumns,
+    targetColumns,
+    localFields = ['id'],
+    extraColumns = {},
+  } = opts;
+
+  const junctionStorageColumns: Record<string, RawColumn> = {};
+  for (const col of parentColumns) {
+    junctionStorageColumns[col] = { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false };
+  }
+  for (const col of childColumns) {
+    junctionStorageColumns[col] = { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false };
+  }
+  for (const [name, col] of Object.entries(extraColumns)) {
+    junctionStorageColumns[name] = col;
+  }
+
+  const parentStorageColumns: Record<string, RawColumn> = {};
+  for (const col of localFields) {
+    parentStorageColumns[col] = { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false };
+  }
+
+  const parentStorageFields: Record<string, { column: string }> = {};
+  for (const col of localFields) {
+    parentStorageFields[col] = { column: col };
+  }
+
+  const parentFields: Record<
+    string,
+    { nullable: boolean; type: { kind: string; codecId: string } }
+  > = {};
+  for (const col of localFields) {
+    parentFields[col] = { nullable: false, type: { kind: 'scalar', codecId: 'pg/int4@1' } };
+  }
+
+  return {
+    domain: {
+      namespaces: {
+        public: {
+          id: 'public',
+          models: {
+            Parent: {
+              fields: parentFields,
+              relations: {
+                children: {
+                  to: { model: 'Child', namespace: 'public' },
+                  cardinality: 'N:M',
+                  on: { localFields, targetFields: targetColumns },
+                  through: {
+                    table: junctionTable,
+                    parentColumns,
+                    childColumns,
+                    targetColumns,
+                  },
+                },
+              },
+              storage: { table: 'parents', fields: parentStorageFields },
+            },
+            Child: {
+              fields: Object.fromEntries(
+                targetColumns.map((col) => [
+                  col,
+                  { nullable: false, type: { kind: 'scalar', codecId: 'pg/int4@1' } },
+                ]),
+              ),
+              relations: {},
+              storage: {
+                table: 'children',
+                fields: Object.fromEntries(targetColumns.map((col) => [col, { column: col }])),
+              },
+            },
+            Junction: {
+              fields: {},
+              relations: {},
+              storage: { table: junctionTable, fields: {} },
+            },
+          },
+        },
+      },
+    },
+    storage: {
+      namespaces: {
+        public: {
+          id: 'public',
+          tables: {
+            parents: {
+              columns: parentStorageColumns,
+              primaryKey: { columns: localFields },
+              uniques: [],
+              indexes: [],
+              foreignKeys: [],
+            },
+            children: {
+              columns: Object.fromEntries(
+                targetColumns.map((col) => [
+                  col,
+                  { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false },
+                ]),
+              ),
+              primaryKey: { columns: targetColumns },
+              uniques: [],
+              indexes: [],
+              foreignKeys: [],
+            },
+            [junctionTable]: {
+              columns: junctionStorageColumns,
+              primaryKey: { columns: [...parentColumns, ...childColumns] },
+              uniques: [],
+              indexes: [],
+              foreignKeys: [],
+            },
+          },
+        },
+      },
+    },
+    capabilities: {},
+  } as unknown as FrameworkContract<SqlStorage>;
+}
+
 export function createMockRuntime(): MockRuntime {
   const executions: MockExecution[] = [];
   let nextResult: Record<string, unknown>[][] = [];