feat(sql-orm-client): M:N relation filters via junction EXISTS

tensordreams · tensordreams · commit 96049950b5bf · 2026-06-05T14:41:46.000+02:00
Add some/every/none filter support for many-to-many relations, generating
correlated EXISTS/NOT EXISTS subqueries that join through the junction table.

Both correlation sides are correctly threaded:
- junction→target: JOIN junction ON junction.childColumns = target.targetColumns
- junction→parent: WHERE junction.parentColumns = parent.{localFields→columns}
  (parent anchor columns resolved via resolveFieldToColumn, mirroring slice-1
  read path in buildManyToManyJunctionArtifacts)

Shapes:
- some  → EXISTS(SELECT 1 FROM target JOIN junction ON &lt;j→t&gt; WHERE &lt;j→parent&gt; [AND pred])
- none  → NOT EXISTS(… [AND pred])
- every → NOT EXISTS(… AND NOT(pred)); vacuously true (AndExpr.true()) when no pred

Composite keys are AND-ed across all column pairs via buildPairedColumnExprs.
A hasThrough type guard narrows ResolvedModelRelation at the dispatch site,
keeping the narrowed type in buildManyToManyExistsExpr explicit without bare casts.

Unit tests cover single-key and composite-key junction shapes for all three
modes, plus AND-ed predicate variants and the vacuous-true edge case.
FK relation filter tests are unaffected.

Signed-off-by: Alexey Orlenko's AI Agent &lt;robot@aqrln.net&gt;
diff --git a/packages/3-extensions/sql-orm-client/src/model-accessor.ts b/packages/3-extensions/sql-orm-client/src/model-accessor.ts
@@ -8,6 +8,7 @@ import {
   type CodecRef,
   ColumnRef,
   ExistsExpr,
+  JoinAst,
   ProjectionItem,
   SelectAst,
 } from '@prisma-next/sql-relational-core/ast';
@@ -30,6 +31,13 @@ import {
 } from './types';
 
 type ResolvedModelRelation = ReturnType<typeof resolveModelRelations>[string];
+type ResolvedModelRelationWithThrough = ResolvedModelRelation & {
+  through: NonNullable<ResolvedModelRelation['through']>;
+};
+
+function hasThrough(relation: ResolvedModelRelation): relation is ResolvedModelRelationWithThrough {
+  return relation.through !== undefined;
+}
 
 type RelationPredicateInput<TContract extends Contract<SqlStorage>, ModelName extends string> =
   | ((model: ModelAccessor<TContract, ModelName>) => AnyExpression)
@@ -233,6 +241,17 @@ function buildExistsExpr<TContract extends Contract<SqlStorage>>(
     readonly predicate: RelationPredicateInput<TContract, string> | undefined;
   },
 ): AnyExpression {
+  if (hasThrough(relation)) {
+    return buildManyToManyExistsExpr(
+      context,
+      parentModelName,
+      parentTableName,
+      relatedTableName,
+      relation,
+      options,
+    );
+  }
+
   const joinWhere = buildJoinWhere(
     context.contract,
     parentModelName,
@@ -270,6 +289,89 @@ function buildExistsExpr<TContract extends Contract<SqlStorage>>(
   return existsNot ? ExistsExpr.notExists(subquery) : ExistsExpr.exists(subquery);
 }
 
+function buildManyToManyExistsExpr<TContract extends Contract<SqlStorage>>(
+  context: ExecutionContext<TContract>,
+  parentModelName: string,
+  parentTableName: string,
+  relatedTableName: string,
+  relation: ResolvedModelRelationWithThrough,
+  options: {
+    readonly mode: 'some' | 'every' | 'none';
+    readonly predicate: RelationPredicateInput<TContract, string> | undefined;
+  },
+): AnyExpression {
+  const { through } = relation;
+  const junctionTable = through.table;
+
+  const junctionJoinOn = buildPairedColumnExprs(
+    junctionTable,
+    through.childColumns,
+    relatedTableName,
+    through.targetColumns,
+  );
+
+  const parentLocalColumns = relation.on.localFields.map((field) =>
+    resolveFieldToColumn(context.contract, parentModelName, field),
+  );
+  const junctionCorrelation = buildPairedColumnExprs(
+    junctionTable,
+    through.parentColumns,
+    parentTableName,
+    parentLocalColumns,
+  );
+
+  const childWhere = toRelationWhereExpr(context, relation.to, options.predicate);
+
+  let subqueryWhere: AnyExpression = junctionCorrelation;
+  let existsNot = false;
+
+  if (options.mode === 'every') {
+    if (!childWhere) {
+      return AndExpr.true();
+    }
+    existsNot = true;
+    subqueryWhere = and(junctionCorrelation, not(childWhere));
+  } else if (options.mode === 'none') {
+    existsNot = true;
+    if (childWhere) {
+      subqueryWhere = and(junctionCorrelation, childWhere);
+    }
+  } else if (childWhere) {
+    subqueryWhere = and(junctionCorrelation, childWhere);
+  }
+
+  const firstTargetCol = through.targetColumns[0] ?? 'id';
+  const subquery = SelectAst.from(TableSource.named(relatedTableName))
+    .withJoins([JoinAst.inner(TableSource.named(junctionTable), junctionJoinOn)])
+    .withProjection([ProjectionItem.of('_exists', ColumnRef.of(relatedTableName, firstTargetCol))])
+    .withWhere(subqueryWhere);
+
+  return existsNot ? ExistsExpr.notExists(subquery) : ExistsExpr.exists(subquery);
+}
+
+function buildPairedColumnExprs(
+  leftTable: string,
+  leftColumns: readonly string[],
+  rightTable: string,
+  rightColumns: readonly string[],
+): AnyExpression {
+  const count = Math.min(leftColumns.length, rightColumns.length);
+  if (count === 0) {
+    throw new Error('Relation metadata is missing join columns');
+  }
+  const exprs: AnyExpression[] = [];
+  for (let i = 0; i < count; i++) {
+    const left = leftColumns[i];
+    const right = rightColumns[i];
+    if (!left || !right) continue;
+    exprs.push(BinaryExpr.eq(ColumnRef.of(leftTable, left), ColumnRef.of(rightTable, right)));
+  }
+  if (exprs.length === 1 && exprs[0]) {
+    return exprs[0];
+  }
+  return and(...exprs);
+}
+
 function toRelationWhereExpr<TContract extends Contract<SqlStorage>>(
   context: ExecutionContext<TContract>,
   relatedModelName: string,
diff --git a/packages/3-extensions/sql-orm-client/test/model-accessor.test.ts b/packages/3-extensions/sql-orm-client/test/model-accessor.test.ts
@@ -5,6 +5,7 @@ import {
   BinaryExpr,
   ColumnRef,
   ExistsExpr,
+  JoinAst,
   ListExpression,
   NotExpr,
   NullCheckExpr,
@@ -17,7 +18,12 @@ import {
 } from '@prisma-next/sql-relational-core/ast';
 import { describe, expect, it } from 'vitest';
 import { createModelAccessor } from '../src/model-accessor';
-import { getTestContext, getTestContract, withPatchedDomainModels } from './helpers';
+import {
+  buildManyToManyContract,
+  getTestContext,
+  getTestContract,
+  withPatchedDomainModels,
+} from './helpers';
 import { unboundTables } from './unbound-tables';
 
 describe('createModelAccessor', () => {
@@ -479,6 +485,180 @@ describe('createModelAccessor', () => {
     });
   });
 
+  describe('M:N relation filters via junction', () => {
+    it('some() emits EXISTS through junction (single-key)', () => {
+      const contract = buildManyToManyContract({
+        junctionTable: 'parent_children',
+        parentColumns: ['parent_id'],
+        childColumns: ['child_id'],
+        targetColumns: ['id'],
+      });
+      const accessor = createModelAccessor(
+        { ...getTestContext(), contract } as never,
+        'Parent',
+      ) as unknown as Record<string, { some: (pred?: unknown) => unknown }>;
+
+      const expr = accessor['children']!.some() as ExistsExpr;
+
+      expect(expr.notExists).toBe(false);
+      expect(expr.subquery.from).toEqual(TableSource.named('children'));
+      expect(expr.subquery.joins).toEqual([
+        JoinAst.inner(
+          TableSource.named('parent_children'),
+          BinaryExpr.eq(
+            ColumnRef.of('parent_children', 'child_id'),
+            ColumnRef.of('children', 'id'),
+          ),
+        ),
+      ]);
+      expect(expr.subquery.where).toEqual(
+        BinaryExpr.eq(ColumnRef.of('parent_children', 'parent_id'), ColumnRef.of('parents', 'id')),
+      );
+    });
+
+    it('some(pred) AND-s junction correlation with predicate', () => {
+      const contract = buildManyToManyContract({
+        junctionTable: 'parent_children',
+        parentColumns: ['parent_id'],
+        childColumns: ['child_id'],
+        targetColumns: ['id'],
+      });
+      const accessor = createModelAccessor(
+        { ...getTestContext(), contract } as never,
+        'Parent',
+      ) as unknown as Record<string, { some: (pred: (c: unknown) => unknown) => unknown }>;
+
+      const expr = accessor['children']!.some((c: unknown) =>
+        (c as Record<string, { eq: (v: unknown) => unknown }>)['id']!.eq(42),
+      ) as ExistsExpr;
+
+      expect(expr.notExists).toBe(false);
+      expect(expr.subquery.where).toEqual(
+        AndExpr.of([
+          BinaryExpr.eq(
+            ColumnRef.of('parent_children', 'parent_id'),
+            ColumnRef.of('parents', 'id'),
+          ),
+          BinaryExpr.eq(
+            ColumnRef.of('children', 'id'),
+            ParamRef.of(42, { codec: { codecId: 'pg/int4@1' } }),
+          ),
+        ]),
+      );
+    });
+
+    it('none() emits NOT EXISTS through junction', () => {
+      const contract = buildManyToManyContract({
+        junctionTable: 'parent_children',
+        parentColumns: ['parent_id'],
+        childColumns: ['child_id'],
+        targetColumns: ['id'],
+      });
+      const accessor = createModelAccessor(
+        { ...getTestContext(), contract } as never,
+        'Parent',
+      ) as unknown as Record<string, { none: (pred?: unknown) => unknown }>;
+
+      const expr = accessor['children']!.none() as ExistsExpr;
+      expect(expr.notExists).toBe(true);
+      expect(expr.subquery.where).toEqual(
+        BinaryExpr.eq(ColumnRef.of('parent_children', 'parent_id'), ColumnRef.of('parents', 'id')),
+      );
+    });
+
+    it('every(pred) emits NOT EXISTS(… AND NOT(pred)) through junction', () => {
+      const contract = buildManyToManyContract({
+        junctionTable: 'parent_children',
+        parentColumns: ['parent_id'],
+        childColumns: ['child_id'],
+        targetColumns: ['id'],
+      });
+      const accessor = createModelAccessor(
+        { ...getTestContext(), contract } as never,
+        'Parent',
+      ) as unknown as Record<string, { every: (pred: (c: unknown) => unknown) => unknown }>;
+
+      const expr = accessor['children']!.every((c: unknown) =>
+        (c as Record<string, { eq: (v: unknown) => unknown }>)['id']!.eq(99),
+      ) as ExistsExpr;
+
+      expect(expr.notExists).toBe(true);
+      expect(expr.subquery.where).toEqual(
+        AndExpr.of([
+          BinaryExpr.eq(
+            ColumnRef.of('parent_children', 'parent_id'),
+            ColumnRef.of('parents', 'id'),
+          ),
+          new NotExpr(
+            BinaryExpr.eq(
+              ColumnRef.of('children', 'id'),
+              ParamRef.of(99, { codec: { codecId: 'pg/int4@1' } }),
+            ),
+          ),
+        ]),
+      );
+    });
+
+    it('every({}) is vacuously true for M:N relations', () => {
+      const contract = buildManyToManyContract({
+        junctionTable: 'parent_children',
+        parentColumns: ['parent_id'],
+        childColumns: ['child_id'],
+        targetColumns: ['id'],
+      });
+      const accessor = createModelAccessor(
+        { ...getTestContext(), contract } as never,
+        'Parent',
+      ) as unknown as Record<string, { every: (pred: unknown) => unknown }>;
+
+      expect(accessor['children']!.every({})).toEqual(AndExpr.true());
+    });
+
+    it('some() emits EXISTS with composite-key AND-ed junction join', () => {
+      const contract = buildManyToManyContract({
+        junctionTable: 'parent_children',
+        parentColumns: ['tenant_id', 'parent_id'],
+        childColumns: ['tenant_id', 'child_id'],
+        targetColumns: ['tenant_id', 'id'],
+        localFields: ['tenant_id', 'id'],
+      });
+      const accessor = createModelAccessor(
+        { ...getTestContext(), contract } as never,
+        'Parent',
+      ) as unknown as Record<string, { some: () => unknown }>;
+
+      const expr = accessor['children']!.some() as ExistsExpr;
+
+      expect(expr.subquery.joins).toEqual([
+        JoinAst.inner(
+          TableSource.named('parent_children'),
+          AndExpr.of([
+            BinaryExpr.eq(
+              ColumnRef.of('parent_children', 'tenant_id'),
+              ColumnRef.of('children', 'tenant_id'),
+            ),
+            BinaryExpr.eq(
+              ColumnRef.of('parent_children', 'child_id'),
+              ColumnRef.of('children', 'id'),
+            ),
+          ]),
+        ),
+      ]);
+      expect(expr.subquery.where).toEqual(
+        AndExpr.of([
+          BinaryExpr.eq(
+            ColumnRef.of('parent_children', 'tenant_id'),
+            ColumnRef.of('parents', 'tenant_id'),
+          ),
+          BinaryExpr.eq(
+            ColumnRef.of('parent_children', 'parent_id'),
+            ColumnRef.of('parents', 'id'),
+          ),
+        ]),
+      );
+    });
+  });
+
   describe('extension operations', () => {
     it('attaches trait-targeted op only when codec traits are a superset of required traits', () => {
       const queryOperations = createSqlOperationRegistry();
