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

package/dist/services/FetchService.d.ts

@@ -5,6 +5,7 @@ import type { VectorSearchParams } from "@rebasepro/types";
 import { RelationService } from "./RelationService";
 import { DrizzleClient } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import { type NestedPathHop } from "./nested-path";
 /**
  * Service for handling all row read operations.
  * Handles fetching, searching, counting, and filtering rows.
@@ -65,6 +66,22 @@ export declare class FetchService {
      * Extract cursor pagination conditions from startAfter options.
      */
     private buildCursorConditions;
+    /**
+     * Compile "rows reachable from this parent" into a `WHERE` condition on the
+     * target table, so a nested listing can run as an ordinary collection query.
+     */
+    private buildRelationScope;
+    /**
+     * Whether `id` is actually reachable at `collectionPath`.
+     *
+     * Trivially true for a root path. For a nested one it is a real question:
+     * the path resolves to the target collection, and matching on the primary
+     * key alone made the parent segment decorative — `authors/1/posts/43`
+     * returned post 43 whoever wrote it, and the REST layer's delete then
+     * deleted it. A row that is not under this parent is reported as absent,
+     * which is what a caller addressing it through the parent should see.
+     */
+    private isAddressableUnder;
     /**
      * Fetch a single row by ID
      */
@@ -83,6 +100,8 @@ export declare class FetchService {
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
         logical?: LogicalCondition;
+        /** Narrow to the rows reachable from a parent through a relation. */
+        relatedTo?: NestedPathHop;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Fallback path used when db.query is unavailable.
@@ -118,10 +137,6 @@ export declare class FetchService {
         limit?: number;
         databaseId?: string;
     }): Promise<Record<string, unknown>[]>;
-    /**
-     * Fetch collection from multi-segment path
-     */
-    private fetchCollectionFromPath;
     /**
      * Count rows in a collection
      */
@@ -130,10 +145,6 @@ export declare class FetchService {
         searchString?: string;
         databaseId?: string;
     }): Promise<number>;
-    /**
-     * Count rows from multi-segment path
-     */
-    private countEntitiesFromPath;
     /**
      * Check if a field value is unique
      */
@@ -160,6 +171,8 @@ export declare class FetchService {
         searchString?: string;
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
+        /** Narrow to the rows reachable from a parent through a relation. */
+        relatedTo?: NestedPathHop;
     }, include?: string[]): Promise<Record<string, unknown>[]>;
     /**
      * Fetch a single row with optional relation includes for REST API.

package/dist/services/PersistService.d.ts

@@ -38,6 +38,18 @@ export declare class PersistService {
      * Delete all rows from a collection
      */
     deleteAll(collectionPath: string, _databaseId?: string): Promise<void>;
+    /**
+     * The column on the *target* table that records the parent, for a create
+     * under a nested one-to-many path.
+     *
+     * Returns `undefined` when the link is not a column at all (a multi-hop
+     * `joinPath`), so the caller writes the row without stamping anything.
+     *
+     * `relation.localKey` is deliberately not consulted: it names a column on
+     * the *source* table. Falling back to it here — which is what this used to
+     * do, and first — stamped the parent's own foreign key onto the child row.
+     */
+    private resolveParentForeignKeyColumn;
     /**
      * Save an row (create or update)
      *

package/dist/services/RelationService.d.ts

@@ -1,6 +1,8 @@
 import { DrizzleClient } from "../interfaces";
-import { CollectionConfig, FilterValues, Relation } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany } from "@rebasepro/types";
+import { type ResolvedVia } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import type { NestedPathHop } from "./nested-path";
 /**
  * Service for handling all relation-related operations.
  * Handles fetching, updating, and managing row relations.
@@ -69,7 +71,7 @@ export declare class RelationService {
     /**
      * Fetch rows using join paths for complex relations
      */
-    fetchEntitiesUsingJoins<M extends Record<string, unknown>>(parentCollection: CollectionConfig, parentId: string | number, relation: Relation, options?: {
+    fetchEntitiesUsingJoins<M extends Record<string, unknown>>(parentCollection: CollectionConfig, parentId: string | number, relation: ResolvedRelation, options?: {
         filter?: FilterValues<Extract<keyof M, string>>;
         orderBy?: string;
         order?: "desc" | "asc";
@@ -85,16 +87,45 @@ export declare class RelationService {
         filter?: FilterValues<Extract<keyof M, string>>;
         databaseId?: string;
     }): Promise<number>;
+    /**
+     * 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 countRelatedRows;
+    /**
+     * 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.
+     */
+    isRelated(hop: NestedPathHop, targetId: string | number): Promise<boolean>;
+    /**
+     * 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.
+     */
+    unlinkRelatedEntity(tx: DrizzleClient, hop: NestedPathHop, targetId: string | number): Promise<void>;
     /**
      * Batch fetch related rows for multiple parent rows to avoid N+1 queries
      */
-    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: Relation): Promise<Map<string, RelatedRow<Record<string, unknown>>>>;
+    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation): Promise<Map<string, RelatedRow<Record<string, unknown>>>>;
     /**
      * Batch fetch many-cardinality related rows for multiple parent rows.
      * Returns a Map<parentId, RelatedRow[]> instead of Map<parentId, RelatedRow>.
      * Uses a single SQL query with IN clause to avoid N+1.
      */
-    batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: Relation): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
+    batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
     /**
      * Update many-to-many and junction relations
      */
@@ -104,7 +135,7 @@ export declare class RelationService {
      */
     updateInverseRelations(tx: DrizzleClient, sourceCollection: CollectionConfig, sourceEntityId: string | number, inverseRelationUpdates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedRelation;
         newValue: unknown;
     }>): Promise<void>;
     /**
@@ -120,13 +151,13 @@ export declare class RelationService {
      */
     updateJoinPathOneToOneRelations(tx: DrizzleClient, parentCollection: CollectionConfig, parentId: string | number, updates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedVia;
         newTargetId: string | number | null;
     }>): Promise<void>;
     /**
      * Resolve joinPath write mapping for one-to-one relations
      */
-    resolveJoinPathWriteMapping(parentCollection: CollectionConfig, relation: Relation): {
+    resolveJoinPathWriteMapping(parentCollection: CollectionConfig, relation: ResolvedVia): {
         targetFKColName: string;
         parentSourceColName: string;
     };
@@ -136,7 +167,7 @@ export declare class RelationService {
     handleJunctionTableCreation(tx: DrizzleClient, newEntityId: string | number, junctionTableInfo: {
         parentCollection: CollectionConfig;
         parentId: string | number;
-        relation: Relation;
+        relation: ResolvedManyToMany;
         relationKey: string;
     }): Promise<void>;
 }

package/dist/services/cdc/junction-tables.d.ts

@@ -0,0 +1,38 @@
+import { CollectionConfig } from "@rebasepro/types";
+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 declare function collectJunctionLinks(registry: PostgresCollectionRegistry): JunctionLink[];
+/**
+ * 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 declare function buildJunctionLinkMap(registry: PostgresCollectionRegistry): Map<string, JunctionLink[]>;

package/dist/services/nested-path.d.ts

@@ -0,0 +1,59 @@
+import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * The last hop of a nested collection path, e.g. `authors/1/posts`.
+ *
+ * The walk that produces this was written out four separate times — in
+ * `FetchService.fetchCollectionFromPath`, `FetchService.countEntitiesFromPath`,
+ * `PersistService.save` and `CollectionRegistry.getCollectionByPath` — and had
+ * drifted, so the read path and the write path did not agree on which relation
+ * a path named. It lives here once now.
+ */
+export interface NestedPathHop {
+    /** The collection the final relation is declared on (e.g. `authors`). */
+    parentCollection: CollectionConfig;
+    /** The parent's id as it appeared in the path, unparsed. */
+    parentId: string;
+    /** The path segment that named the relation (e.g. `posts`). */
+    relationKey: string;
+    relation: ResolvedRelation;
+    /** `relation.target()`, resolved once. */
+    targetCollection: CollectionConfig;
+}
+/**
+ * True when `path` addresses rows through a relation rather than a root
+ * collection.
+ *
+ * Any separator at all counts — a root collection slug never contains one — so
+ * a malformed path like `collection/id` is a *broken* nested path and gets
+ * reported as one by {@link resolveNestedPath}, rather than being looked up as
+ * a root collection whose slug happens to contain a slash.
+ */
+export declare function isNestedPath(path: string): boolean;
+export declare function splitPathSegments(path: string): string[];
+/**
+ * Walk a nested collection path down to the relation it ends in.
+ *
+ * Returns `undefined` for a plain root-collection path so callers can keep the
+ * root case on its existing code path. Throws when the path is malformed, or
+ * when a segment names a relation that does not exist — the same errors the
+ * individual walks used to raise, with the available names attached.
+ */
+export declare function resolveNestedPath(path: string, registry: PostgresCollectionRegistry): NestedPathHop | undefined;
+/**
+ * A relation reached through a junction table — many-to-many, or a multi-hop
+ * `joinPath`. The target row is shared with other parents, so writing "through"
+ * such a path addresses the *link*, not the row.
+ */
+export declare function isJunctionBackedRelation(relation: ResolvedRelation): boolean;
+/**
+ * Reject a nested write whose final segment is a to-one relation.
+ *
+ * There is no column on the target row that records a to-one parent — the
+ * foreign key lives on the *parent* table. The write path used to fall through
+ * to `relation.localKey` here and stamp the parent's own FK column onto the
+ * target row, which either raised an opaque "column does not exist" or, when a
+ * column of that name happened to exist on the target, silently wrote the wrong
+ * one.
+ */
+export declare function assertWritableThrough(hop: NestedPathHop, path: string): void;

package/dist/services/realtimeService.d.ts

@@ -95,6 +95,8 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private cdcListener?;
     /** Whether database-level CDC is the active cross-instance change source. */
     private cdcActive;
+    /** Junction table → the child lists its rows belong to, built when CDC starts. */
+    private junctionLinkMap?;
     /** Reverse lookup: `schema.table` (and bare `table`) → collection, built when CDC starts. */
     private cdcTableMap?;
     /**
@@ -437,6 +439,23 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * subscriber, never per publisher.
      */
     private handleCdcEvent;
+    /**
+     * Deliver a change on a many-to-many junction table as a change to the child
+     * lists it belongs to.
+     *
+     * Linking a tag to a post writes only `posts_tags`. That table backs no
+     * collection, so change capture dropped the event as unmapped and the
+     * subscribers of `posts/1/tags` never heard about it — every other write in
+     * the system was realtime, and this one silently was not. The junction row
+     * carries both ids, so it names its own paths exactly.
+     *
+     * Notifies the nested path rather than either endpoint collection, because
+     * invalidation walks *parent* paths and never child ones: telling `tags` it
+     * changed would not reach a subscription on `posts/1/tags`.
+     *
+     * Returns whether the table was recognised as a junction.
+     */
+    private handleJunctionCdcEvent;
     /** Compute the canonical (possibly composite) id string from a captured row. */
     private extractIdFromCdcRow;
     private dedupKey;

package/dist/services/row-pipeline.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, Relation } from "@rebasepro/types";
+import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 /**
  * Turning a drizzle result into a row we serve.
@@ -26,7 +26,7 @@ export type RelationStyle = "ref" | "inline";
  * the query has to nest one level deeper for a junction, and the row walk has
  * to unwrap that same level back out.
  */
-export declare function isJunctionRelation(relation: Relation): boolean;
+export declare function isJunctionRelation(relation: ResolvedRelation): boolean;
 /**
  * The address a relation ref points at.
  *