@rebasepro/server-postgres 0.9.1-canary.fd3754b → 0.10.0

package/dist/services/collection-helpers.d.ts

@@ -1,6 +1,9 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 import { CollectionConfig } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+export { buildCompositeId, parseIdValues, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
+export type { PrimaryKeyInfo } from "@rebasepro/common";
+import type { PrimaryKeyInfo } from "@rebasepro/common";
 /**
  * Shared helper functions for row operations.
  * These are used by FetchService, PersistService, and RelationService.
@@ -21,18 +24,80 @@ export interface DrizzleColumnMeta {
 export declare function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta;
 export declare function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig;
 export declare function getTableForCollection(collection: CollectionConfig, registry: PostgresCollectionRegistry): PgTable<any>;
-export declare function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): {
-    fieldName: string;
-    type: "string" | "number";
-    isUUID?: boolean;
+/**
+ * The key columns a collection's rows are addressed by.
+ *
+ * Three tiers, in order: properties marked `isId`, the primary keys of the
+ * drizzle schema, and finally a column literally named `id`. Only the first is
+ * visible to the browser, which is why a key known only to drizzle is reported
+ * at boot — see {@link warnOnKeysTheAdminCannotResolve}.
+ *
+ * Returns `[]` when nothing resolves, rather than throwing. It used to open by
+ * resolving the table, which throws when there is none — so the `isId` tier,
+ * which needs no table at all, was unreachable for exactly the collections
+ * most likely to have no table registered. Every caller that wanted "no keys"
+ * to mean "no keys" had to spell that out in a try/catch.
+ *
+ * Callers that cannot proceed without a key must say so themselves, naming the
+ * collection: an empty array here means "this collection has no address", which
+ * is a different answer in a notification (broadcast a wildcard) than in a save
+ * (fail).
+ */
+export declare function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[];
+/**
+ * The key columns, for callers that cannot do their job without one.
+ *
+ * {@link getPrimaryKeys} answers "what keys, if any" and returns `[]` for a
+ * collection with no address. Most of this driver, though, is building a WHERE
+ * clause and has no meaning without a key — for those, an empty array is not an
+ * answer, and indexing `[0]` into it produces `Cannot read properties of
+ * undefined` three frames from where the real problem is. This says what is
+ * wrong and which collection it is wrong about.
+ */
+export declare function requirePrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[];
+/**
+ * Collections whose key the *browser* cannot resolve, and what it will do
+ * instead.
+ *
+ * The two sides resolve keys from different evidence. This driver reads, in
+ * order: properties marked `isId`, the primary keys of the Drizzle schema, then
+ * a column literally named `id`. The admin shares the `CollectionConfig` — it
+ * compiles the same collection files into its bundle — but never the Drizzle
+ * schema, so the middle tier is invisible to it.
+ *
+ * Nothing can normalize this at runtime: the server does not serve the admin
+ * its collections, so a key resolved here cannot be handed over there. The
+ * config files are the only thing both sides read, so the fix is an edit to
+ * them, and the most this can do is say exactly which edit.
+ *
+ * Two shapes, and the second is the dangerous one:
+ *
+ * - No `isId`, no `id` property → the admin resolves no address, warns in the
+ *   console, and rows cannot be opened or linked.
+ * - No `isId`, but an `id` property that is *not* the key → the admin addresses
+ *   rows by `id` while this driver reads the address as the real key. Nothing
+ *   errors: the addresses look right and route wrong.
+ */
+export declare function findUnresolvableKeyCollections(collections: CollectionConfig[], registry: PostgresCollectionRegistry): {
+    collection: CollectionConfig;
+    keys: PrimaryKeyInfo[];
+    shadowedByIdProperty: boolean;
 }[];
-export declare function parseIdValues(idValue: string | number, primaryKeys: {
-    fieldName: string;
-    type: "string" | "number";
-    isUUID?: boolean;
-}[]): Record<string, string | number>;
-export declare function buildCompositeId(values: Record<string, unknown>, primaryKeys: {
-    fieldName: string;
-    type: "string" | "number";
-    isUUID?: boolean;
-}[]): string;
+/**
+ * Report the collections from {@link findUnresolvableKeyCollections} at boot,
+ * with the edit that fixes each one.
+ *
+ * Grouped by failure, not by collection: the shadowed case is a routing bug and
+ * the silent case is a missing feature, and they deserve different urgency.
+ */
+export declare function warnOnKeysTheAdminCannotResolve(collections: CollectionConfig[], registry: PostgresCollectionRegistry): void;
+/**
+ * The address of a row: derived from the collection's primary keys, because a
+ * row does not carry one — it is exactly its columns.
+ *
+ * Falls back to a literal `id` column, for a row that reached us from somewhere
+ * other than this driver. Returns `""` when there is no key and no `id` —
+ * callers decide what that means, since "unaddressable" is a different answer
+ * in a notification (broadcast a wildcard) than in a save (fail).
+ */
+export declare function deriveRowAddress(row: Record<string, unknown>, collection: CollectionConfig, registry: PostgresCollectionRegistry): string;

package/dist/services/dataService.d.ts

@@ -82,7 +82,9 @@ export declare class DataService implements DataRepository {
     /**
      * Save an row (create or update)
      */
-    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
+        upsert?: boolean;
+    }): Promise<Record<string, unknown>>;
     /**
      * Delete an row by ID
      */

package/dist/services/index.d.ts

@@ -1,4 +1,4 @@
 export { FetchService } from "./FetchService";
 export { PersistService } from "./PersistService";
 export { RelationService } from "./RelationService";
-export { getCollectionByPath, getTableForCollection, getPrimaryKeys, parseIdValues, buildCompositeId } from "./collection-helpers";
+export { getCollectionByPath, getTableForCollection, getPrimaryKeys, deriveRowAddress, parseIdValues, buildCompositeId } from "./collection-helpers";

package/dist/services/realtimeService.d.ts

@@ -4,12 +4,13 @@ import { DataDriver, WebSocketMessage } from "@rebasepro/types";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import type { ChannelRetentionRule } from "@rebasepro/types";
 /**
  * Auth context stored per-subscription so real-time refetches respect RLS.
  * Mirrors the session variables set by PostgresBackendDriver.withAuth().
  */
 export interface SubscriptionAuthContext {
-    userId: string;
+    uid: string;
     roles: string[];
 }
 /**
@@ -24,6 +25,26 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private clients;
     private channels;
     private presence;
+    /**
+     * Ordered, replayable history for channels that opt into it.
+     *
+     * Undefined until {@link configureChannelHistory} is called, and inert even
+     * then unless retention rules were supplied — so presence and ephemeral
+     * notification channels never touch it. See `channel-history.ts`.
+     */
+    private channelHistory?;
+    /**
+     * One promise chain per retained channel, so that assigning a sequence
+     * number and fanning the message out happen in the same order for every
+     * message on that channel.
+     *
+     * Without it, two concurrent broadcasts can be numbered 4 and 5 by the
+     * database and still reach subscribers as 5 then 4 — live order and replay
+     * order would disagree, which is exactly the divergence sequence numbers
+     * are supposed to rule out. Keyed by channel, so unrelated channels never
+     * wait on each other.
+     */
+    private channelSendQueues;
     private presenceInterval?;
     private static readonly PRESENCE_TIMEOUT_MS;
     private dataService;
@@ -177,8 +198,15 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     /**
      * Send a lightweight row-level patch to a collection subscriber.
      * The client can merge this into its cached data for instant feedback.
+     *
+     * The key columns ride along: the patch names a row by address, and the
+     * client has to find that row among the ones it cached — which carry
+     * columns and no address. The SDK holds no collection config to derive one
+     * from, so this is the only place the mapping can come from.
      */
     private sendCollectionPatch;
+    /** The key columns of the collection at `path`, if they can be resolved. */
+    private primaryKeysForPath;
     private sendError;
     private sendMessage;
     /**
@@ -190,8 +218,54 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     joinChannel(clientId: string, channel: string): void;
     /** Leave a broadcast channel */
     leaveChannel(clientId: string, channel: string): void;
-    /** Broadcast a message to all clients in a channel except sender */
+    /**
+     * Broadcast a message to all clients in a channel except the sender.
+     *
+     * On a channel with no retention rule this is what it always was: a
+     * synchronous fan-out to whoever is connected, with no sequence number, no
+     * SQL and no await — the body below runs to completion before returning.
+     *
+     * On a retained channel the message is durably numbered first and only then
+     * delivered, through a per-channel queue so that delivery order matches
+     * sequence order. That ordering is the whole point: a client that catches up
+     * with `sinceSeq` has to arrive at the same state as one that never
+     * disconnected.
+     */
     broadcastToChannel(clientId: string, channel: string, event: string, payload: unknown): void;
+    /**
+     * Number a broadcast, store it, then deliver it.
+     *
+     * A message that cannot be stored is **not** delivered. Delivering it would
+     * put it in front of live subscribers while leaving it absent from every
+     * future replay — the two views of the channel would disagree permanently,
+     * and no later message could repair the gap. Failing loudly to the sender
+     * instead lets it retry, which for an operation stream is the only outcome
+     * that keeps clients convergent.
+     */
+    private persistAndFanOut;
+    /** Deliver a broadcast frame to every member of a channel but the sender. */
+    private fanOutBroadcast;
+    /**
+     * Install retention rules and create the tables they need.
+     *
+     * Safe to call with no rules (and safe not to call at all): the store stays
+     * inert, no schema is created, and broadcast keeps its original
+     * fire-and-forget path.
+     */
+    configureChannelHistory(rules: ChannelRetentionRule[] | undefined): Promise<void>;
+    /** Whether any channel is configured to retain messages. */
+    isChannelHistoryEnabled(): boolean;
+    /**
+     * Answer a client's catch-up request.
+     *
+     * A channel with no retention rule is answered with `retained: false`
+     * rather than an empty list, so the client can tell "you missed nothing"
+     * apart from "this channel never keeps anything" — the second means its
+     * reconnect strategy has to be a full resync, and silence would leave it
+     * guessing.
+     */
+    private handleChannelHistoryRequest;
+    private sendChannelHistory;
     /** Track presence in a channel */
     trackPresence(clientId: string, channel: string, state: Record<string, unknown>): void;
     /** Remove presence from a channel */

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

@@ -0,0 +1,63 @@
+import { CollectionConfig, Relation } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Turning a drizzle result into a row we serve.
+ *
+ * There are two shapes, and they are the same walk. Both take a row whose
+ * relation fields hold nested objects, both unwrap junction rows to reach the
+ * target behind them, and both leave every other column alone. They differ only
+ * in what they put where the relation was:
+ *
+ * - `"ref"` — a `{ id, path, __type: "relation" }` reference carrying the
+ *   target's values. This is what the admin renders.
+ * - `"inline"` — the target's own columns, flat. This is what REST serves.
+ *
+ * They used to be two functions that happened to agree, and the agreement was
+ * not enforced by anything: the row-identity bug had to be fixed five times
+ * across differently-shaped copies of this walk, and one of the copies was
+ * dead code nobody had noticed. Whatever the next cross-cutting change is, it
+ * is one edit here.
+ */
+export type RelationStyle = "ref" | "inline";
+/**
+ * Whether a many-relation reaches its target through a junction table.
+ *
+ * Also used to build the drizzle `with` config, which is why it is exported:
+ * 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;
+/**
+ * The address a relation ref points at.
+ *
+ * The whole key, not its first column: a composite-keyed target addressed by
+ * `tenant_id` alone points at every row that shares it. A target whose key
+ * cannot be resolved at all used to throw here — reading `[0]` of an empty
+ * array — taking down the parent's fetch over a relation it may not even have
+ * asked for. The first column is a guess, but a ref that resolves to nothing
+ * beats no rows at all.
+ */
+export declare function relationTargetAddress(targetRow: Record<string, unknown>, targetCollection: CollectionConfig, registry: PostgresCollectionRegistry): string;
+/**
+ * The row the admin renders: every column, with relations as references.
+ *
+ * Values are normalized (dates, numbers, NaN) because the admin's view-model
+ * expects real types. The row's own address is *not* among the columns — it is
+ * derived by the consumer from the collection's primary keys.
+ */
+export declare function toCmsRow(row: Record<string, unknown>, collection: CollectionConfig, registry: PostgresCollectionRegistry): Record<string, unknown>;
+/**
+ * The row REST serves: every column under its own name, with the value Postgres
+ * returned, and relations inlined as the target's columns.
+ *
+ * Values are the ones the database returned, except where that contradicts the
+ * declared type: a `number` property is served as a number (see
+ * {@link coerceDeclaredNumber}). Dates stay as the database returned them —
+ * JSON has its own opinions about dates that the admin's view-model does not
+ * share.
+ *
+ * Keyed by the row rather than by the relation list — a REST fetch only loads
+ * the relations `include` asked for, so the row is the authority on which are
+ * actually there.
+ */
+export declare function toRestRow(row: Record<string, unknown>, collection: CollectionConfig, registry: PostgresCollectionRegistry): Record<string, unknown>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-postgres",
   "type": "module",
-  "version": "0.9.1-canary.fd3754b",
+  "version": "0.10.0",
   "description": "PostgreSQL data source backend implementation for Rebase with Drizzle ORM",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -13,7 +13,7 @@
     "url": "https://github.com/rebasepro/rebase.git",
     "directory": "packages/server-postgres"
   },
-  "main": "./dist/index.umd.js",
+  "main": "./dist/index.es.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
   "source": "src/index.ts",
@@ -29,39 +29,11 @@
     "backend",
     "rebase"
   ],
-  "jest": {
-    "transform": {
-      "^.+\\.tsx?$": "ts-jest"
-    },
-    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
-    "testPathIgnorePatterns": [
-      "/node_modules/",
-      "test/e2e/"
-    ],
-    "moduleFileExtensions": [
-      "ts",
-      "tsx",
-      "js",
-      "jsx",
-      "json",
-      "node"
-    ],
-    "moduleNameMapper": {
-      "^chalk$": "<rootDir>/test/mocks/chalk.cjs",
-      "^@rebasepro/client$": "<rootDir>/../client/src/index.ts",
-      "^@rebasepro/common$": "<rootDir>/../common/src/index.ts",
-      "^@rebasepro/types$": "<rootDir>/../types/src/index.ts",
-      "^@rebasepro/utils$": "<rootDir>/../utils/src/index.ts",
-      "^@rebasepro/server$": "<rootDir>/../server/src/index.ts",
-      "^(\\.{1,2}/.*)\\.js$": "$1"
-    }
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "development": "./dist/index.es.js",
-      "import": "./dist/index.es.js",
-      "require": "./dist/index.umd.js"
+      "import": "./dist/index.es.js"
     },
     "./package.json": "./package.json"
   },
@@ -73,21 +45,23 @@
     "dotenv": "^17.4.2",
     "drizzle-orm": "^0.45.2",
     "execa": "^9.6.1",
-    "hono": "^4.12.25",
     "pg": "^8.21.0",
     "ws": "^8.21.0",
-    "@rebasepro/common": "0.9.1-canary.fd3754b",
-    "@rebasepro/codegen": "0.9.1-canary.fd3754b",
-    "@rebasepro/server": "0.9.1-canary.fd3754b",
-    "@rebasepro/types": "0.9.1-canary.fd3754b",
-    "@rebasepro/utils": "0.9.1-canary.fd3754b"
+    "@rebasepro/codegen": "0.10.0",
+    "@rebasepro/common": "0.10.0",
+    "@rebasepro/types": "0.10.0",
+    "@rebasepro/utils": "0.10.0",
+    "@rebasepro/server": "0.10.0"
   },
   "devDependencies": {
+    "@hono/node-server": "^2.0.9",
+    "@jest/globals": "^30.4.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.9.3",
     "@types/pg": "^8.20.0",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^6.0.2",
+    "hono": "^4.12.25",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",
     "typescript": "^6.0.3",
@@ -104,10 +78,11 @@
   ],
   "scripts": {
     "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
-    "test": "jest --passWithNoTests",
+    "test": "jest",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
+    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
+    "smoke:baas": "tsx scripts/smoke-baas.ts"
   }
 }