feat(sql-orm-client): surface through descriptor on ResolvedRelation for M:N relations

Add ResolvedThrough interface and populate through on ResolvedRelation when
the contract relation carries a through object (cardinality N:M). The resolver
reads table, parentColumns, childColumns, and targetColumns directly from the
contract, then derives requiredPayloadColumns by inspecting the junction
table's storage columns: any column that is NOT NULL, has no default, and is
not in parentColumns ∪ childColumns is required payload that the caller must
supply when creating a junction row.

Four resolver unit test cases: simple single-column FK, composite-key junction,
junction with required non-FK payload columns, and junction with only
nullable/defaulted extra columns.

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

Author: tensordreams

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

@@ -196,13 +196,22 @@ export function getCompleteColumnToFieldMap(
   return cached;
 }
 
+interface ResolvedThrough {
+  readonly table: string;
+  readonly parentColumns: readonly string[];
+  readonly childColumns: readonly string[];
+  readonly targetColumns: readonly string[];
+  readonly requiredPayloadColumns: readonly string[];
+}
+
 interface ResolvedRelation {
   readonly to: string;
   readonly cardinality: RelationCardinalityTag | undefined;
   readonly on: {
     readonly localFields: readonly string[];
     readonly targetFields: readonly string[];
   };
+  readonly through?: ResolvedThrough;
 }
 
 export interface ResolvedIncludeRelation {
@@ -244,6 +253,46 @@ export function resolveIncludeRelation(
   };
 }
 
+function resolveThrough(
+  contract: Contract<SqlStorage>,
+  raw:
+    | { table?: unknown; parentColumns?: unknown; childColumns?: unknown; targetColumns?: unknown }
+    | undefined,
+): ResolvedThrough | undefined {
+  if (!raw) return undefined;
+  const { table, parentColumns, childColumns, targetColumns } = raw;
+  if (
+    typeof table !== 'string' ||
+    !Array.isArray(parentColumns) ||
+    !Array.isArray(childColumns) ||
+    !Array.isArray(targetColumns)
+  ) {
+    return undefined;
+  }
+
+  const fkColumnSet = new Set<string>([
+    ...(parentColumns as string[]),
+    ...(childColumns as string[]),
+  ]);
+  const junctionTable = unboundTable(contract, table);
+  const requiredPayloadColumns: string[] = [];
+  if (junctionTable) {
+    for (const [colName, col] of Object.entries(junctionTable.columns)) {
+      if (!fkColumnSet.has(colName) && !col.nullable && col.default === undefined) {
+        requiredPayloadColumns.push(colName);
+      }
+    }
+  }
+
+  return {
+    table,
+    parentColumns: parentColumns as readonly string[],
+    childColumns: childColumns as readonly string[],
+    targetColumns: targetColumns as readonly string[],
+    requiredPayloadColumns,
+  };
+}
+
 const modelRelationsCache = new WeakMap<object, Map<string, Record<string, ResolvedRelation>>>();
 
 export function resolveModelRelations(
@@ -269,6 +318,12 @@ export function resolveModelRelations(
       to?: CrossReference;
       cardinality?: unknown;
       on?: { localFields?: unknown; targetFields?: unknown };
+      through?: {
+        table?: unknown;
+        parentColumns?: unknown;
+        childColumns?: unknown;
+        targetColumns?: unknown;
+      };
     };
     const localFields = rel.on?.localFields;
     const targetFields = rel.on?.targetFields;
@@ -283,13 +338,16 @@ export function resolveModelRelations(
       continue;
     }
 
+    const through = resolveThrough(contract, rel.through);
+
     resolved[name] = {
       to: rel.to.model,
       cardinality: parseRelationCardinality(rel.cardinality),
       on: {
         localFields: localFields as readonly string[],
         targetFields: targetFields as readonly string[],
       },
+      ...(through !== undefined ? { through } : {}),
     };
   }
 

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

@@ -1,9 +1,12 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { describe, expect, it } from 'vitest';
 import {
   assertReturningCapability,
   hasContractCapability,
   isToOneCardinality,
   resolveIncludeRelation,
+  resolveModelRelations,
   resolveModelTableName,
   resolvePolymorphismInfo,
   resolvePrimaryKeyColumn,
@@ -363,3 +366,172 @@ describe('resolvePolymorphismInfo()', () => {
     );
   });
 });
+
+describe('resolveModelRelations() through descriptor', () => {
+  type RawColumn = { nativeType: string; codecId: string; nullable: boolean; default?: unknown };
+
+  function buildManyToManyContract(opts: {
+    junctionTable: string;
+    parentColumns: string[];
+    childColumns: string[];
+    targetColumns: string[];
+    extraColumns?: Record<string, RawColumn>;
+  }): Contract<SqlStorage> {
+    const { junctionTable, parentColumns, childColumns, targetColumns, 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;
+    }
+
+    return {
+      domain: {
+        namespaces: {
+          public: {
+            id: 'public',
+            models: {
+              Parent: {
+                fields: { id: { nullable: false, type: { kind: 'scalar', codecId: 'pg/int4@1' } } },
+                relations: {
+                  children: {
+                    to: { model: 'Child', namespace: 'public' },
+                    cardinality: 'N:M',
+                    on: { localFields: ['id'], targetFields: targetColumns },
+                    through: {
+                      table: junctionTable,
+                      parentColumns,
+                      childColumns,
+                      targetColumns,
+                    },
+                  },
+                },
+                storage: { table: 'parents', fields: { id: { column: 'id' } } },
+              },
+              Child: {
+                fields: { id: { nullable: false, type: { kind: 'scalar', codecId: 'pg/int4@1' } } },
+                relations: {},
+                storage: { table: 'children', fields: { id: { column: 'id' } } },
+              },
+              Junction: {
+                fields: {},
+                relations: {},
+                storage: { table: junctionTable, fields: {} },
+              },
+            },
+          },
+        },
+      },
+      storage: {
+        namespaces: {
+          public: {
+            id: 'public',
+            tables: {
+              parents: {
+                columns: { id: { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false } },
+                primaryKey: { columns: ['id'] },
+                uniques: [],
+                indexes: [],
+                foreignKeys: [],
+              },
+              children: {
+                columns: { id: { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false } },
+                primaryKey: { columns: ['id'] },
+                uniques: [],
+                indexes: [],
+                foreignKeys: [],
+              },
+              [junctionTable]: {
+                columns: junctionStorageColumns,
+                primaryKey: { columns: [...parentColumns, ...childColumns] },
+                uniques: [],
+                indexes: [],
+                foreignKeys: [],
+              },
+            },
+          },
+        },
+      },
+      capabilities: {},
+    } as unknown as Contract<SqlStorage>;
+  }
+
+  it('populates through descriptor for a simple single-column M:N relation', () => {
+    const contract = buildManyToManyContract({
+      junctionTable: 'parent_child',
+      parentColumns: ['parent_id'],
+      childColumns: ['child_id'],
+      targetColumns: ['id'],
+    });
+
+    const relations = resolveModelRelations(contract, 'Parent');
+    expect(relations['children']?.through).toEqual({
+      table: 'parent_child',
+      parentColumns: ['parent_id'],
+      childColumns: ['child_id'],
+      targetColumns: ['id'],
+      requiredPayloadColumns: [],
+    });
+  });
+
+  it('populates through descriptor for a composite-key M:N junction', () => {
+    const contract = buildManyToManyContract({
+      junctionTable: 'parent_child',
+      parentColumns: ['tenant_id', 'parent_id'],
+      childColumns: ['tenant_id', 'child_id'],
+      targetColumns: ['tenant_id', 'id'],
+    });
+
+    const relations = resolveModelRelations(contract, 'Parent');
+    const through = relations['children']?.through;
+    expect(through?.parentColumns).toEqual(['tenant_id', 'parent_id']);
+    expect(through?.childColumns).toEqual(['tenant_id', 'child_id']);
+    expect(through?.targetColumns).toEqual(['tenant_id', 'id']);
+    expect(through?.requiredPayloadColumns).toEqual([]);
+  });
+
+  it('includes NOT-NULL no-default non-FK columns in requiredPayloadColumns', () => {
+    const contract = buildManyToManyContract({
+      junctionTable: 'parent_child',
+      parentColumns: ['parent_id'],
+      childColumns: ['child_id'],
+      targetColumns: ['id'],
+      extraColumns: {
+        assigned_at: { nativeType: 'timestamptz', codecId: 'pg/timestamptz@1', nullable: false },
+        role: { nativeType: 'text', codecId: 'pg/text@1', nullable: false },
+      },
+    });
+
+    const relations = resolveModelRelations(contract, 'Parent');
+    expect(relations['children']?.through?.requiredPayloadColumns).toEqual(
+      expect.arrayContaining(['assigned_at', 'role']),
+    );
+    expect(relations['children']?.through?.requiredPayloadColumns).toHaveLength(2);
+  });
+
+  it('excludes nullable and defaulted non-FK columns from requiredPayloadColumns', () => {
+    const contract = buildManyToManyContract({
+      junctionTable: 'parent_child',
+      parentColumns: ['parent_id'],
+      childColumns: ['child_id'],
+      targetColumns: ['id'],
+      extraColumns: {
+        note: { nativeType: 'text', codecId: 'pg/text@1', nullable: true },
+        created_at: {
+          nativeType: 'timestamptz',
+          codecId: 'pg/timestamptz@1',
+          nullable: false,
+          default: { kind: 'expression', sql: 'now()' },
+        },
+      },
+    });
+
+    const relations = resolveModelRelations(contract, 'Parent');
+    expect(relations['children']?.through?.requiredPayloadColumns).toEqual([]);
+  });
+});