@rebasepro/server-postgres 0.10.1-canary.d8d45b2 → 0.10.1-canary.ed78a2c

package/src/services/RelationService.ts

@@ -1,8 +1,9 @@
 import { and, eq, inArray, or, sql, SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { DrizzleClient } from "../interfaces";
-import { CollectionConfig, FilterValues, Relation } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
+import { hasForeignKeyOnTarget, isManyToMany, type ResolvedVia } from "@rebasepro/types";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
     getCollectionByPath,
@@ -15,6 +16,7 @@ import {
 import { parseDataFromServer } from "../data-transformer";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { logger } from "@rebasepro/server";
+import type { NestedPathHop } from "./nested-path";
 
 /**
  * Typed wrapper for Drizzle dynamic query innerJoin.
@@ -180,7 +182,7 @@ export class RelationService {
     async fetchEntitiesUsingJoins<M extends Record<string, unknown>>(
         parentCollection: CollectionConfig,
         parentId: string | number,
-        relation: Relation,
+        relation: ResolvedRelation,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
             orderBy?: string;
@@ -205,7 +207,7 @@ export class RelationService {
         const parentIdCol = parentTable[parentIdInfo.fieldName as keyof typeof parentTable] as AnyPgColumn;
 
         // Handle join path relations
-        if (relation.joinPath && relation.joinPath.length > 0) {
+        if (relation.kind === "via") {
             let query = this.db.select().from(parentTable).$dynamic();
             let currentTable = parentTable;
 
@@ -333,6 +335,24 @@ export class RelationService {
             throw new Error(`Relation '${relationKey}' not found in collection '${parentCollectionPath}'. Available relations: [${available}]`);
         }
 
+        return this.countRelatedRows(parentCollection, parentId, relation, []);
+    }
+
+    /**
+     * Count the target rows a parent reaches through `relation`, narrowed by
+     * `additionalFilters` (conditions on the target table).
+     *
+     * Shared by the public count and by {@link isRelated}, so "how many children
+     * does this parent have" and "is this row one of them" are answered by the
+     * same join — a membership test that reconstructed the join separately would
+     * be free to disagree with the listing it is supposed to gate.
+     */
+    private async countRelatedRows(
+        parentCollection: CollectionConfig,
+        parentId: string | number,
+        relation: ResolvedRelation,
+        additionalFilters: SQL[]
+    ): Promise<number> {
         const targetCollection = relation.target();
         const targetTable = getTableForCollection(targetCollection, this.registry);
         const targetPks = requirePrimaryKeys(targetCollection, this.registry);
@@ -350,9 +370,6 @@ export class RelationService {
         // Start count with distinct to avoid duplicates from junction tables
         let query = this.db.select({ count: sql<number>`count(distinct ${targetIdField})` }).from(targetTable).$dynamic();
 
-        // Build additional filter conditions
-        const additionalFilters: SQL[] = [];
-
         // Use unified count query builder from DrizzleConditionBuilder
         query = DrizzleConditionBuilder.buildRelationCountQuery(
             query,
@@ -370,6 +387,75 @@ export class RelationService {
         return Number(result[0]?.count || 0);
     }
 
+    /**
+     * Whether `targetId` is actually reachable from the parent named in `hop`.
+     *
+     * A nested address like `authors/1/posts/43` used to resolve to the target
+     * collection and then match on the primary key alone, so the parent segment
+     * decided nothing: the row came back, and was updated or deleted, whoever it
+     * belonged to. Reads, updates and deletes now all gate on this.
+     */
+    async isRelated(hop: NestedPathHop, targetId: string | number): Promise<boolean> {
+        const targetTable = getTableForCollection(hop.targetCollection, this.registry);
+        const targetPks = requirePrimaryKeys(hop.targetCollection, this.registry);
+        const parsedTargetId = parseIdValues(targetId, targetPks);
+
+        const identity: SQL[] = targetPks.map(pk => {
+            const column = targetTable[pk.fieldName as keyof typeof targetTable] as AnyPgColumn;
+            if (!column) {
+                throw new Error(`ID field '${pk.fieldName}' not found in table for collection '${hop.targetCollection.slug}'`);
+            }
+            return eq(column, parsedTargetId[pk.fieldName]);
+        });
+
+        return (await this.countRelatedRows(hop.parentCollection, hop.parentId, hop.relation, identity)) > 0;
+    }
+
+    /**
+     * Remove the junction row linking a parent to `targetId`, leaving the target
+     * row itself alone.
+     *
+     * This is what `DELETE authors/1/tags/5` has to mean for a many-to-many: the
+     * target is shared, so deleting the row would remove the tag from every other
+     * post that uses it. It used to do exactly that — resolve the path to the
+     * `tags` table and delete by primary key.
+     */
+    async unlinkRelatedEntity(
+        tx: DrizzleClient,
+        hop: NestedPathHop,
+        targetId: string | number
+    ): Promise<void> {
+        if (!isManyToMany(hop.relation)) {
+            throw new Error(`Relation '${hop.relationKey}' has no junction table to unlink through`);
+        }
+        const through = hop.relation.through;
+
+        const junctionTable = this.registry.getTable(through.table);
+        if (!junctionTable) {
+            throw new Error(`Junction table not found: ${through.table}`);
+        }
+
+        const sourceJunctionColumn = junctionTable[through.sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
+        const targetJunctionColumn = junctionTable[through.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
+
+        if (!sourceJunctionColumn || !targetJunctionColumn) {
+            throw new Error(`Junction columns not found for relation '${hop.relationKey}' on table '${through.table}'`);
+        }
+
+        const parentPks = requirePrimaryKeys(hop.parentCollection, this.registry);
+        const parsedParentId = parseIdValues(hop.parentId, parentPks)[parentPks[0].fieldName];
+
+        const targetPks = requirePrimaryKeys(hop.targetCollection, this.registry);
+        const parsedTargetId = parseIdValues(targetId, targetPks)[targetPks[0].fieldName];
+
+        await tx.delete(junctionTable).where(and(
+            eq(sourceJunctionColumn, parsedParentId),
+            eq(targetJunctionColumn, parsedTargetId)
+        ));
+
+        logger.info(`Unlinked '${hop.relationKey}' ${parsedTargetId} from ${hop.parentCollection.slug} ${parsedParentId}`);
+    }
+
     /**
      * Batch fetch related rows for multiple parent rows to avoid N+1 queries
      */
@@ -377,7 +463,7 @@ export class RelationService {
         parentCollectionPath: string,
         parentIds: (string | number)[],
         _relationKey: string,
-        relation: Relation
+        relation: ResolvedRelation
     ): Promise<Map<string, RelatedRow<Record<string, unknown>>>> {
         if (parentIds.length === 0) return new Map();
 
@@ -398,7 +484,7 @@ export class RelationService {
         const parsedParentIds = parentIds.map(id => parseIdValues(id, parentPks)[parentIdInfo.fieldName]);
 
         // Handle join path relations with batching
-        if (relation.joinPath && relation.joinPath.length > 0) {
+        if (relation.kind === "via") {
             let query = this.db.select().from(parentTable).$dynamic();
             let currentTable = parentTable;
 
@@ -457,7 +543,7 @@ export class RelationService {
         //   1. Fetch FK values from the parent table in a single query
         //   2. Query the target table with unique FK values
         //   3. Map results back to parent rows via their FK values
-        if (relation.direction === "owning" && relation.localKey) {
+        if (relation.kind === "belongsTo") {
             this.assertSingleKeyAddressable(parentCollection, parentPks, relation.localKey);
             const localKeyCol = parentTable[relation.localKey as keyof typeof parentTable] as AnyPgColumn;
             if (!localKeyCol) {
@@ -521,7 +607,7 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
         );
         let query = this.db.select().from(targetTable).$dynamic();
 
@@ -554,11 +640,13 @@ export class RelationService {
             // Determine the parent ID this result belongs to based on the relation type
             let parentId: string | number | undefined;
 
-            if (relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+            // The parent's key is on the target row, in the relation's own
+            // column. There used to be a second branch here that guessed the
+            // column by appending `_id` to `inverseRelationName`, reached only
+            // when the foreign key had not been resolved — which cannot happen
+            // now that resolution fills it in.
+            if (hasForeignKeyOnTarget(relation)) {
                 parentId = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
-            } else if (relation.direction === "inverse" && relation.cardinality === "one" && relation.inverseRelationName) {
-                const inferredForeignKeyName = `${relation.inverseRelationName}_id`;
-                parentId = targetRow[inferredForeignKeyName] as string | number | undefined;
             }
 
             if (parentId !== undefined && parentIdSet.has(String(parentId))) {
@@ -578,7 +666,7 @@ export class RelationService {
         parentCollectionPath: string,
         parentIds: (string | number)[],
         _relationKey: string,
-        relation: Relation
+        relation: ResolvedRelation
     ): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>> {
         if (parentIds.length === 0) return new Map();
 
@@ -598,7 +686,7 @@ export class RelationService {
         const parsedParentIds = parentIds.map(id => parseIdValues(id, parentPks)[parentIdInfo.fieldName]);
 
         // Handle join path relations (many-to-many through junction tables)
-        if (relation.joinPath && relation.joinPath.length > 0) {
+        if (relation.kind === "via") {
             let query = this.db.select().from(parentTable).$dynamic();
             let currentTable = parentTable;
 
@@ -640,7 +728,7 @@ export class RelationService {
         // Handle many-to-many owning relations with junction table (relation.through)
         // This is the standard path for posts→tags style relations where
         // sanitizeRelation populated the `through` config.
-        if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
+        if (relation.kind === "manyToMany") {
             // The junction names its parent with one column, so the same
             // single-key limit applies as for a direct foreign key.
             this.assertSingleKeyAddressable(parentCollection, parentPks, `${relation.through.table}.${relation.through.sourceColumn}`);
@@ -690,7 +778,7 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
         );
         let query = this.db.select().from(targetTable).$dynamic();
 
@@ -720,16 +808,10 @@ export class RelationService {
 
             let parentId: string | number | undefined;
 
-            if (relation.through && relation.direction === "inverse") {
-                // Inverse many-to-many via junction table: the junction's targetColumn
-                // references the parent (since from the inverse perspective, source/target are swapped).
-                const junctionData = (row[relation.through.table] || row) as Record<string, unknown>;
-                parentId = junctionData[relation.through.targetColumn] as string | number | undefined;
-            } else if (relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+            // Junction-backed relations returned earlier in this method, so
+            // what reaches here names the parent with a column on the target.
+            if (hasForeignKeyOnTarget(relation)) {
                 parentId = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
-            } else if (relation.direction === "inverse" && relation.inverseRelationName) {
-                const inferredForeignKeyName = `${relation.inverseRelationName}_id`;
-                parentId = targetRow[inferredForeignKeyName] as string | number | undefined;
             }
 
             if (parentId !== undefined && parentIdSet.has(String(parentId))) {
@@ -762,7 +844,7 @@ export class RelationService {
             const targetCollection = relation.target();
 
             // Use joinPath if available
-            if (relation.joinPath && relation.joinPath.length > 0) {
+            if (relation.kind === "via") {
                 const parentTableName = getTableName(collection);
                 const targetTableName = getTableName(targetCollection);
 
@@ -828,7 +910,7 @@ export class RelationService {
                         await tx.insert(junctionTable).values(newLinks);
                     }
                 }
-            } else if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
+            } else if (relation.kind === "manyToMany") {
                 // Handle many-to-many relations with junction table using 'through' property
                 const junctionTable = this.registry.getTable(relation.through.table);
                 if (!junctionTable) {
@@ -866,11 +948,7 @@ export class RelationService {
                         await tx.insert(junctionTable).values(newLinks);
                     }
                 }
-            } else if (relation.through && relation.cardinality === "many" && relation.direction === "inverse") {
-                // Inverse M2M relations should be saved from the owning side.
-                // The owning collection manages the junction table rows.
-                logger.warn(`[updateRelationsUsingJoins] Inverse M2M relation '${key}' in collection '${collection.slug}' should be saved from the owning side. Skipping.`);
-            } else if (relation.cardinality === "many" && relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+            } else if (relation.cardinality === "many" && hasForeignKeyOnTarget(relation)) {
                 // Handle one-to-many (inverse) by updating target FK to point to parent
                 const targetTable = getTableForCollection(targetCollection, this.registry);
                 const targetPks = requirePrimaryKeys(targetCollection, this.registry);
@@ -923,7 +1001,7 @@ export class RelationService {
         sourceEntityId: string | number,
         inverseRelationUpdates: Array<{
             relationKey: string;
-            relation: Relation;
+            relation: ResolvedRelation;
             newValue: unknown;
         }>
     ) {
@@ -938,8 +1016,7 @@ export class RelationService {
                 const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
                 const sourceIdInfo = sourcePks[0];
 
-                // Handle inverse relations with joinPath
-                if (relation.direction === "inverse" && relation.joinPath && relation.joinPath.length > 0) {
+                if (relation.kind === "via") {
                     await this.updateInverseJoinPathRelation(
                         tx,
                         sourceCollection,
@@ -951,42 +1028,31 @@ export class RelationService {
                     continue;
                 }
 
-                // Check if this is a many-to-many inverse relation
-                if (relation.cardinality === "many" && relation.direction === "inverse") {
-                    const targetCollectionRelations = resolveCollectionRelations(targetCollection);
-                    let junctionInfo: { table: string; sourceColumn: string; targetColumn: string } | null = null;
-
-                    for (const [relationKey, targetRelation] of Object.entries(targetCollectionRelations)) {
-                        if (targetRelation.cardinality === "many" &&
-                            targetRelation.direction === "owning" &&
-                            targetRelation.through &&
-                            (targetRelation.relationName === relation.inverseRelationName || relationKey === relation.inverseRelationName)) {
-                            junctionInfo = {
-                                table: targetRelation.through.table,
-                                sourceColumn: targetRelation.through.targetColumn,
-                                targetColumn: targetRelation.through.sourceColumn
-                            };
-                            break;
+                // A many-to-many names its own junction. This used to walk the
+                // *target's* relations looking for an owning side whose
+                // `relationName` matched `inverseRelationName`, and swap its
+                // source/target columns — a search that silently did nothing
+                // when the far side was declared differently than expected.
+                if (isManyToMany(relation)) {
+                    await this.updateManyToManyInverseRelation(
+                        tx,
+                        sourceCollection,
+                        sourceEntityId,
+                        targetCollection,
+                        relation,
+                        newValue,
+                        {
+                            table: relation.through.table,
+                            sourceColumn: relation.through.sourceColumn,
+                            targetColumn: relation.through.targetColumn
                         }
-                    }
-
-                    if (junctionInfo) {
-                        await this.updateManyToManyInverseRelation(
-                            tx,
-                            sourceCollection,
-                            sourceEntityId,
-                            targetCollection,
-                            relation,
-                            newValue,
-                            junctionInfo
-                        );
-                        continue;
-                    }
+                    );
+                    continue;
                 }
 
-                // Handle simple inverse relations
-                if (!relation.foreignKeyOnTarget) {
-                    logger.warn(`Inverse relation '${relation.relationName}' is missing foreignKeyOnTarget property. Skipping.`);
+                // What is left names the parent with a column on the target.
+                if (!hasForeignKeyOnTarget(relation)) {
+                    logger.warn(`Relation '${relation.relationName}' has no column on the target to write. Skipping.`);
                     continue;
                 }
 
@@ -1035,14 +1101,10 @@ export class RelationService {
         sourceCollection: CollectionConfig,
         sourceEntityId: string | number,
         targetCollection: CollectionConfig,
-        relation: Relation,
+        relation: ResolvedVia,
         newValue: unknown
     ) {
         try {
-            if (!relation.joinPath || relation.joinPath.length === 0) {
-                logger.warn(`Inverse relation '${relation.relationName}' missing joinPath`);
-                return;
-            }
 
             const sourceTableName = getTableName(sourceCollection);
             const targetTableName = getTableName(targetCollection);
@@ -1145,7 +1207,7 @@ export class RelationService {
         sourceCollection: CollectionConfig,
         sourceEntityId: string | number,
         targetCollection: CollectionConfig,
-        relation: Relation,
+        relation: ResolvedRelation,
         newValue: unknown,
         junctionInfo: { table: string; sourceColumn: string; targetColumn: string }
     ) {
@@ -1203,7 +1265,9 @@ export class RelationService {
         parentId: string | number,
         updates: Array<{
             relationKey: string;
-            relation: Relation;
+            // Only a `via` relation has a join path to write through, and the
+            // caller only collects those.
+            relation: ResolvedVia;
             newTargetId: string | number | null;
         }>
     ) {
@@ -1281,7 +1345,7 @@ export class RelationService {
      */
     resolveJoinPathWriteMapping(
         parentCollection: CollectionConfig,
-        relation: Relation
+        relation: ResolvedVia
     ): { targetFKColName: string; parentSourceColName: string } {
         if (!relation.joinPath || relation.joinPath.length === 0) {
             throw new Error("resolveJoinPathWriteMapping requires a joinPath relation");
@@ -1320,7 +1384,10 @@ parentSourceColName };
         junctionTableInfo: {
             parentCollection: CollectionConfig;
             parentId: string | number;
-            relation: Relation;
+            // Only a junction-backed relation has a link to write, and the
+            // caller only builds this for one — stated here so the body needs
+            // no narrowing.
+            relation: ResolvedManyToMany;
             relationKey: string;
         }
     ) {
@@ -1328,14 +1395,14 @@ parentSourceColName };
         const targetCollection = relation.target();
 
         try {
-            const junctionTable = this.registry.getTable(relation.through!.table);
+            const junctionTable = this.registry.getTable(relation.through.table);
             if (!junctionTable) {
-                logger.warn(`Junction table '${relation.through!.table}' not found for relation '${relationKey}'`);
+                logger.warn(`Junction table '${relation.through.table}' not found for relation '${relationKey}'`);
                 return;
             }
 
-            const sourceJunctionColumn = junctionTable[relation.through!.sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
-            const targetJunctionColumn = junctionTable[relation.through!.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
+            const sourceJunctionColumn = junctionTable[relation.through.sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
+            const targetJunctionColumn = junctionTable[relation.through.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
 
             if (!sourceJunctionColumn || !targetJunctionColumn) {
                 logger.warn(`Junction columns not found for relation '${relationKey}'`);
@@ -1348,15 +1415,19 @@ parentSourceColName };
             const parsedNewEntityIdObj = parseIdValues(newEntityId, targetPks);
             const parsedNewEntityId = parsedNewEntityIdObj[targetIdInfo.fieldName];
 
-            // Create the junction table entry linking parent to the new row
+            // Create the junction table entry linking parent to the target row.
             const junctionData = {
                 [sourceJunctionColumn.name]: parentId,
                 [targetJunctionColumn.name]: parsedNewEntityId
             };
 
-            await tx.insert(junctionTable).values(junctionData);
+            // Idempotent: a link either exists or it does not, so asking for one
+            // twice is not an error. This is what lets `PUT parent/id/child/childId`
+            // mean "this row belongs to this parent's set" — the only way to
+            // attach an *existing* row, which previously had none.
+            await tx.insert(junctionTable).values(junctionData).onConflictDoNothing();
 
-            logger.info(`Created junction table entry for many-to-many relation '${relationKey}': ${JSON.stringify(junctionData)}`);
+            logger.info(`Linked '${relationKey}' ${parsedNewEntityId} to ${parentId}`);
         } catch (error) {
             logger.error(`Failed to create junction table entry for relation '${relationKey}'`, { error: error });
             throw error;

package/src/services/cdc/junction-tables.ts

@@ -0,0 +1,91 @@
+import { CollectionConfig, ResolvedRelation, isManyToMany } from "@rebasepro/types";
+import { resolveCollectionRelations } from "@rebasepro/common";
+
+import { PostgresCollectionRegistry } from "../../collections/PostgresCollectionRegistry";
+
+/**
+ * One end of a many-to-many, as seen from the junction table.
+ *
+ * A junction table is not a collection, so nothing in the registry maps it to
+ * one — which is why a change to it was invisible to change capture. But its
+ * rows are exactly the contents of a parent's child list, so a write to it is a
+ * change to `<parentSlug>/<sourceId>/<relationKey>` and to nothing else.
+ */
+export interface JunctionLink {
+    schema: string;
+    /** The junction table itself, e.g. `posts_tags`. */
+    table: string;
+    /** The collection whose relation this is, e.g. `posts`. */
+    parentCollection: CollectionConfig;
+    /** The relation's key — the path segment a child list is addressed by. */
+    relationKey: string;
+    /** Junction column holding the parent's id. */
+    sourceColumn: string;
+    /** Junction column holding the target's id. */
+    targetColumn: string;
+}
+
+/**
+ * Every junction table reachable from a registered collection, once per
+ * relation that uses it.
+ *
+ * A junction is listed once per *direction* when both sides declare it, because
+ * each direction addresses a different child list: `posts/1/tags` and
+ * `tags/t/posts` both change when one link is written.
+ */
+export function collectJunctionLinks(registry: PostgresCollectionRegistry): JunctionLink[] {
+    const links: JunctionLink[] = [];
+    const seen = new Set<string>();
+
+    for (const collection of registry.getCollections()) {
+        let relations: Record<string, ResolvedRelation>;
+        try {
+            relations = resolveCollectionRelations(collection);
+        } catch {
+            // A collection whose relations cannot be resolved (an unresolvable
+            // target, typically mid-migration) simply contributes none.
+            continue;
+        }
+
+        for (const [relationKey, relation] of Object.entries(relations)) {
+            if (!isManyToMany(relation)) continue;
+            const through = relation.through;
+
+            // Same relation registered under both its canonical name and the
+            // declaring property key would otherwise notify the same path twice.
+            const key = `${collection.slug}::${relationKey}::${through.table}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+
+            links.push({
+                schema: (collection as { schema?: string }).schema ?? "public",
+                table: through.table,
+                parentCollection: collection,
+                relationKey,
+                sourceColumn: through.sourceColumn,
+                targetColumn: through.targetColumn
+            });
+        }
+    }
+
+    return links;
+}
+
+/**
+ * Index {@link collectJunctionLinks} by table, under both the qualified and the
+ * bare name — a change event carries whatever the trigger reports, and a
+ * collection need not declare a schema.
+ */
+export function buildJunctionLinkMap(registry: PostgresCollectionRegistry): Map<string, JunctionLink[]> {
+    const map = new Map<string, JunctionLink[]>();
+
+    for (const link of collectJunctionLinks(registry)) {
+        for (const key of [`${link.schema}.${link.table}`, link.table]) {
+            const existing = map.get(key);
+            if (existing) existing.push(link);
+            else map.set(key, [link]);
+        }
+    }
+
+    return map;
+}