@rebasepro/server-postgres 0.19.1 → 0.19.2-canary.g08eed46

package/dist/services/FetchService.d.ts

@@ -1,11 +1,12 @@
 import { SQL } from "drizzle-orm";
 import { PgTable } from "drizzle-orm/pg-core";
 import { FilterValues, OrderByTuple, LogicalCondition } from "@rebasepro/types";
-import type { VectorSearchParams } from "@rebasepro/types";
+import type { IncludeSpec, VectorSearchParams } from "@rebasepro/types";
 import { RelationService } from "./RelationService.js";
 import { DrizzleClient } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import { type NestedPathHop } from "./nested-path.js";
+import { type WithDeleted } from "./soft-delete.js";
 /**
  * Service for handling all row read operations.
  * Handles fetching, searching, counting, and filtering rows.
@@ -99,6 +100,21 @@ export declare class FetchService {
      * one key of several still honours the ones that did resolve.
      */
     private resolveOrderKeys;
+    /**
+     * Whether this key's NULLs sort *after* its real values.
+     *
+     * The default is Postgres's own — `NULLS LAST` ascending, `NULLS FIRST`
+     * descending — and it was previously hardcoded in two places that had to
+     * agree: the `ORDER BY` and the keyset comparison behind cursor paging. A
+     * key that states a placement overrides it, in both, because they read the
+     * answer from here.
+     *
+     * The default is also the thing a "newest first" list gets wrong: every row
+     * with no date sorts to the very top, ahead of everything real, and the only
+     * way out used to be an `is-not-null` filter that dropped those rows
+     * entirely. `orderBy: [["published_at", "desc", "last"]]` is the fix.
+     */
+    private static nullsLast;
     /**
      * The full `ORDER BY`: the caller's keys, then the id.
      *
@@ -138,21 +154,95 @@ export declare class FetchService {
      */
     private getJunctionTargetRelationName;
     /**
-     * Post-fetch joinPath relations for a single flat row.
-     * joinPath relations cannot be expressed via Drizzle's `with` config,
-     * so they must be loaded separately after the primary query.
+     * The relations one level of an include tree names, resolved.
+     *
+     * A name that is not a relation is a **400 `UNKNOWN_RELATION`**. It used to
+     * be dropped silently, which answers 200 with the field missing — and a
+     * missing relation field is indistinguishable from a row that genuinely has
+     * no related row, so a typo in an `include` looked like empty data.
      */
-    private resolveJoinPathRelations;
+    private resolveIncludeLevel;
+    /**
+     * The extra `WHERE` an include's own `where`/`logical` puts on the target.
+     *
+     * Pushed into the batch query rather than applied to the rows it returns:
+     * filtering afterwards reads every related row of every parent to throw
+     * most of them away, and on a to-many relation that is the whole table.
+     */
+    private includeNarrowing;
     /**
-     * Resolves joinPath relations for raw REST rows and directly injects them.
-     * Uses RelationService to query the database and maps results back to the flattened objects.
+     * Sort, cap and project the rows of ONE to-many relation, per parent.
+     *
+     * `orderBy` and `limit` are applied here rather than in SQL because a limit
+     * on a batched relation load is *per parent*, and expressing that needs a
+     * LATERAL or a window function per relation kind — four of them, each with
+     * its own join shape. The rows were already narrowed by
+     * {@link includeNarrowing} in SQL, so what this sorts and cuts is the set
+     * the caller asked for and not the table.
+     */
+    private shapeRelatedRows;
+    /**
+     * Load an include tree onto `rows`, in place, one batched query per
+     * relation per level.
+     *
+     * Recurses into nested includes with the rows it just loaded, so
+     * `comments.author` is two queries for a page of posts rather than one per
+     * comment. The depth bound lives on the normalizer
+     * ({@link MAX_INCLUDE_DEPTH}); this asserts it again because the tree can
+     * also be built in-process, where nothing normalized it.
+     */
+    private loadIncludes;
+    /**
+     * The SELECT list for a read: the visible columns, narrowed to `fields`.
+     *
+     * `?fields=` used to be a trim of the *response* — every column read out of
+     * the database and most of them thrown away in JavaScript. It is a
+     * projection now, so asking for two columns of a wide row reads two
+     * columns; that is also what makes `distinct` mean anything.
+     *
+     * Two things survive a narrowing regardless:
+     *
+     * - the **primary key**, because a row nobody can address cannot be
+     *   updated, deleted, or paged past — and `meta.nextCursor` is derived from
+     *   it, so a projection without it would silently disable seeking. The one
+     *   exception is `distinct`, below;
+     * - the exclusions. `excludeFromApi` and the generated search columns are
+     *   removed *after* the narrowing, so naming one in `fields` does not
+     *   un-hide it. That was the shape of the `?searchString=` leak: a path
+     *   that skipped the projection returned a password hash the plain read
+     *   correctly withheld.
+     *
+     * An unknown column name is a 400 rather than a silent omission: a caller
+     * who mistypes `?fields=titel` otherwise gets rows without titles and no
+     * hint why.
+     *
+     * **`distinct` drops the primary key.** Keeping it is what the refusal of
+     * `distinct` beside a search or vector query already describes: a value
+     * that differs on every row makes the whole row distinct by construction,
+     * so the query "would answer 200 having done nothing". A surrogate key does
+     * that more reliably than any score — `?fields=status&distinct=true` came
+     * back with one row per row, every one carrying its `id`. So a distinct
+     * read is a read of the named columns and nothing else. It addresses no
+     * rows, which is the honest shape for one: `cursorFor` finds no key on the
+     * row and issues no cursor, and the result is a set of values rather than a
+     * set of rows to update or delete.
+     */
+    private columnProjection;
+    /**
+     * The opaque cursor that continues a listing after `row`. See
+     * {@link RestFetchService.cursorFor}.
+     *
+     * Here rather than at the route because deriving it needs the collection's
+     * primary key, which may be named anything and span several columns — the
+     * driver's knowledge, not the HTTP layer's.
      */
-    private resolveJoinPathRelationsBatchRest;
+    cursorFor(collectionPath: string, row: Record<string, unknown>, orderBy?: OrderByTuple[]): string | undefined;
     /**
-     * Build db.query-compatible options from standard fetch options.
-     * Handles filter, search, orderBy, limit, and cursor-based pagination.
+     * Post-fetch joinPath relations for a single flat row.
+     * joinPath relations cannot be expressed via Drizzle's `with` config,
+     * so they must be loaded separately after the primary query.
      */
-    private buildDrizzleQueryOptions;
+    private resolveJoinPathRelations;
     /**
      * Extract cursor pagination conditions from startAfter options.
      *
@@ -195,7 +285,7 @@ export declare class FetchService {
     /**
      * Fetch a single row by ID
      */
-    fetchOne<M extends Record<string, unknown>>(collectionPath: string, id: string | number, databaseId?: string): Promise<Record<string, unknown> | undefined>;
+    fetchOne<M extends Record<string, unknown>>(collectionPath: string, id: string | number, databaseId?: string, withDeleted?: WithDeleted): Promise<Record<string, unknown> | undefined>;
     /**
      * Unified method to fetch rows with optional search functionality
      */
@@ -213,6 +303,23 @@ export declare class FetchService {
         logical?: LogicalCondition;
         /** Narrow to the rows reachable from a parent through a relation. */
         relatedTo?: NestedPathHop;
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
+        /**
+         * Relations to load. **Absent means none** — the same as it means
+         * over REST.
+         *
+         * It used to mean *all of them*, unconditionally, and this is the
+         * method the realtime refetch goes through. So a subscription was
+         * pushed rows carrying every relation the collection declares while
+         * the identical `find()` returned rows carrying none, and a client
+         * that rendered both saw the row change shape when a write landed.
+         */
+        include?: IncludeSpec;
+        /** Columns to read — a projection pushed into the SELECT. */
+        fields?: string[];
+        /** `SELECT DISTINCT` over the projection. */
+        distinct?: boolean;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Fallback path used when db.query is unavailable.
@@ -245,8 +352,15 @@ export declare class FetchService {
         offset?: number;
         startAfter?: Record<string, unknown>;
         searchString?: string;
+        searchExplain?: boolean;
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
+        /** Relations to load. Absent means none — see `fetchRowsWithConditions`. */
+        include?: IncludeSpec;
+        /** Columns to read — a projection pushed into the SELECT. */
+        fields?: string[];
+        /** `SELECT DISTINCT` over the projection. */
+        distinct?: boolean;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Search rows by text
@@ -285,6 +399,8 @@ export declare class FetchService {
          * request that was served three rows was told there were nine.
          */
         vectorSearch?: VectorSearchParams;
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
     }): Promise<number>;
     /**
      * `count`/`sum`/`avg`/`min`/`max`, optionally grouped.
@@ -312,6 +428,8 @@ export declare class FetchService {
         logical?: LogicalCondition;
         searchString?: string;
         limit?: number;
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Check if a field value is unique
@@ -322,12 +440,24 @@ export declare class FetchService {
      */
     getRelationService(): RelationService;
     /**
-     * Fetch a collection of rows with optional relation includes.
-     * When `include` is provided, only the specified relations are populated
-     * with full row data (not just { id, path, __type }).
-     * When `include` is absent, no relation queries are made (fast path).
+     * Fetch a collection of rows, with the relations `include` names.
+     *
+     * ## Why this no longer uses `db.query.findMany({ with })`
+     *
+     * It used to, whenever a `db.query` builder existed for the table — which
+     * is Drizzle's relational API, and which compiles a to-many relation into a
+     * lateral join. This file's own comment on the *other* read path says what
+     * that costs: "catastrophically slow for large collections (7s+ for 350
+     * rows)". So the admin fetch avoided it and REST took it, and the fast,
+     * batched loader that the admin used was unreachable from the HTTP API.
+     *
+     * There is one loader now, {@link loadIncludes}, and every read reaches it:
+     * one query per relation per level, never one per row. That also makes this
+     * method and the realtime refetch the same code, which is what stops
+     * `find()` and `listen()` returning different shapes for one query.
      *
-     * @param include - Array of relation keys to populate, or ["*"] for all
+     * @param include - see {@link IncludeSpec}: names, dotted paths, `["*"]`,
+     *   or the parametrised tree. An unknown name is a 400 `UNKNOWN_RELATION`.
      */
     fetchCollectionForRest<M extends Record<string, unknown>>(collectionPath: string, options?: {
         filter?: FilterValues<Extract<keyof M, string>>;
@@ -343,28 +473,38 @@ export declare class FetchService {
         vectorSearch?: VectorSearchParams;
         /** Narrow to the rows reachable from a parent through a relation. */
         relatedTo?: NestedPathHop;
-    }, include?: string[]): Promise<Record<string, unknown>[]>;
+        /**
+         * See `FetchCollectionProps.withDeleted`. Applied by
+         * `fetchRowsWithConditionsRaw` — the one place this pipeline builds
+         * a WHERE — so it holds for the listing, the nested-path listing
+         * and the realtime refetch alike.
+         */
+        withDeleted?: WithDeleted;
+        /** Columns to read — a projection pushed into the SELECT. */
+        fields?: string[];
+        /** `SELECT DISTINCT` over the projection. */
+        distinct?: boolean;
+        /** Ask each row which declared search fields matched. */
+        searchExplain?: boolean;
+    }, include?: IncludeSpec): Promise<Record<string, unknown>[]>;
     /**
-     * Fetch a single row with optional relation includes for REST API.
-     */
-    fetchOneForRest<M extends Record<string, unknown>>(collectionPath: string, id: string | number, include?: string[], databaseId?: string): Promise<Record<string, unknown> | null>;
+     * Fetch a single row, with the relations `include` names.
+     *
+     * The same two steps `fetchCollectionForRest` takes, for one row, through
+     * the same {@link loadIncludes}. It used to be a separate implementation on
+     * `db.query.findFirst({ with })` with a hand-written N+1 fallback beneath
+     * it, and the two disagreed: the primary path returned a to-one relation as
+     * the target's columns, the fallback merged an `id` over them, and a
+     * relation that resolved to nothing was *absent* on one path and `null` on
+     * the other. `find()[0]` and `findById()` now answer with the same row.
+     */
+    fetchOneForRest<M extends Record<string, unknown>>(collectionPath: string, id: string | number, include?: IncludeSpec, databaseId?: string, options?: {
+        fields?: string[];
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
+    }): Promise<Record<string, unknown> | null>;
     /**
      * Fetch raw rows without any relation processing (for REST fast path)
      */
     private fetchRowsWithConditionsRaw;
-    /**
-     * Check if the Drizzle instance has the relational query API available
-     * for a given collection path.
-     * Note: Primary path now uses inline `getQueryBuilder()` checks.
-     */
-    private hasDrizzleQueryAPI;
-    /**
-     * Fallback path used when db.query is unavailable.
-     * The primary path uses db.query.findMany with `with` config, which
-     * loads all relations in a single query.
-     *
-     * Batch fetch many-to-many related rows for multiple parent IDs.
-     * Groups results by parent ID to avoid N+1.
-     */
-    private batchFetchManyRelatedRows;
 }

package/dist/services/PersistService.d.ts

@@ -51,13 +51,21 @@ export declare class PersistService {
      * Save an row (create or update)
      *
      * With `options.upsert`, the row is written with INSERT ... ON CONFLICT DO
-     * UPDATE against the primary key rather than a plain UPDATE. That is one
-     * statement, so it cannot lose a race the way a read-then-write can, and it
-     * does not care whether the row already exists — which is what a re-runnable
-     * import needs.
+     * UPDATE rather than a plain UPDATE. That is one statement, so it cannot
+     * lose a race the way a read-then-write can, and it does not care whether
+     * the row already exists — which is what a re-runnable import needs. The
+     * conflict is matched on the primary key unless `options.onConflict` names
+     * other columns; see {@link SaveProps.onConflict} for why that matters.
+     *
+     * `values` may carry field operations (`{ views: { $inc: 1 } }`). They are
+     * split out here rather than at the REST boundary because every request
+     * boundary — HTTP, the WebSocket, in-process `context.data` — reaches this
+     * one method, and a rule applied at one door is a rule the other doors do
+     * not have. What they compile to is `field-op-sql.ts`.
      */
     save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
         upsert?: boolean;
+        onConflict?: readonly string[];
     }): Promise<Record<string, unknown>>;
     /**
      * Get the RelationService instance for external use
@@ -76,6 +84,11 @@ export declare class PersistService {
     getFetchService(): FetchService;
     /**
      * Translate raw PostgreSQL / Drizzle errors into user-friendly messages.
+     *
+     * `collection` is passed so the SQLSTATE can be turned into a *field*: the
+     * error carries a physical column and the caller only ever sees wire names,
+     * so `author_id` had to be translated to `authorId` by whoever read the
+     * message — which nothing does. See `pgFieldViolations`.
      */
     private toUserFriendlyError;
 }

package/dist/services/RelationService.d.ts

@@ -1,3 +1,4 @@
+import { SQL } from "drizzle-orm";
 import { DrizzleClient } from "../interfaces.js";
 import { CollectionConfig, FilterValues, OrderByTuple, ResolvedRelation, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
@@ -136,13 +137,20 @@ export declare class RelationService {
      */
     isRelated(hop: NestedPathHop, targetId: string | number): Promise<boolean>;
     /**
-     * Batch fetch related rows for multiple parent rows to avoid N+1 queries
+     * Batch fetch related rows for multiple parent rows to avoid N+1 queries.
+     *
+     * `narrow` is an extra condition on the *target* table — what a per-include
+     * `where` compiles to. It is pushed into the query rather than applied to
+     * the rows that come back, because filtering afterwards reads every related
+     * row of every parent in order to discard most of them.
      */
-    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation): Promise<Map<string, RelatedRow<Record<string, unknown>>>>;
+    batchFetchRelatedEntities(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation, narrow?: SQL): 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: ResolvedRelation): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
+    batchFetchRelatedEntitiesMany(parentCollectionPath: string, parentIds: (string | number)[], _relationKey: string, relation: ResolvedRelation, 
+    /** An extra condition on the target — see {@link batchFetchRelatedEntities}. */
+    narrow?: SQL): Promise<Map<string, RelatedRow<Record<string, unknown>>[]>>;
 }

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

@@ -38,6 +38,14 @@ export declare function getCollectionByPath(collectionPath: string, registry: Po
 /**
  * Reject a write naming something that is not a column of the table.
  *
+ * "The table" is the one read back from `information_schema` at boot — see
+ * `catalogue-schema.ts` — so this asks the database, not a file. It used to ask
+ * the generated module, which made the commonest cause of this error a stale
+ * `schema.generated.ts`: a property added to a collection was created in the
+ * database by boot-ensure and still answered `400` on its first save, because
+ * the module had not been regenerated. That cause no longer exists, and the
+ * remedy below no longer names it.
+ *
  * Drizzle builds INSERT from `Object.entries(table[Symbol.Columns])` and UPDATE
  * from `Object.keys(tableColumns)`, so a key the table does not carry is not
  * rejected by anything — it is *left out of the statement*. The insert answers
@@ -81,10 +89,16 @@ export declare function getTableForCollection(collection: CollectionConfig, regi
  * 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
+ * registered table, and finally a column literally named `id`. Only the first is
+ * visible to the browser, which is why a key known only to the table is reported
  * at boot — see {@link warnOnKeysTheAdminCannotResolve}.
  *
+ * The second tier reads the table the registry holds, which is built from
+ * `information_schema` — the database's own primary key, not a generated file's
+ * claim about it. Composite keys are declared as a table constraint rather than
+ * on each column (that is the only legal way to say it), so both shapes are
+ * asked for.
+ *
  * 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

package/dist/services/dataService.d.ts

@@ -1,6 +1,7 @@
-import { FilterValues, LogicalCondition, OrderByTuple } from "@rebasepro/types";
+import { FilterValues, IncludeSpec, LogicalCondition, OrderByTuple } from "@rebasepro/types";
 import type { VectorSearchParams } from "@rebasepro/types";
 import { FetchService } from "./FetchService.js";
+import type { WithDeleted } from "./soft-delete.js";
 import { PersistService } from "./PersistService.js";
 import { RelationService } from "./RelationService.js";
 import { DataRepository, DrizzleClient } from "../interfaces.js";
@@ -30,7 +31,9 @@ export declare class DataService implements DataRepository {
     /**
      * Fetch a single row by ID
      */
-    fetchOne<M extends Record<string, unknown>>(collectionPath: string, id: string | number, databaseId?: string): Promise<Record<string, unknown> | undefined>;
+    fetchOne<M extends Record<string, unknown>>(collectionPath: string, id: string | number, databaseId?: string, 
+    /** See `FetchCollectionProps.withDeleted`. */
+    withDeleted?: WithDeleted): Promise<Record<string, unknown> | undefined>;
     /**
      * Fetch a collection of rows with optional filtering, ordering, and pagination
      */
@@ -46,7 +49,28 @@ export declare class DataService implements DataRepository {
         searchString?: string;
         databaseId?: string;
         vectorSearch?: VectorSearchParams;
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
     }): Promise<Record<string, unknown>[]>;
+    /**
+     * The REST read pipeline: flat rows, with exactly the relations `include`
+     * names — see {@link FetchService.fetchCollectionForRest}.
+     *
+     * Exposed on the facade because it is what *every* consumer should be
+     * reading through. The realtime refetch used to go via `fetchCollection`
+     * above, which nests a relation under a `{ __type: "relation" }` envelope
+     * and loaded every relation regardless, so a subscription and a REST list
+     * answered the same query with two different row shapes.
+     */
+    fetchCollectionForRest<M extends Record<string, unknown>>(collectionPath: string, options?: Parameters<FetchService["fetchCollectionForRest"]>[1], include?: IncludeSpec): Promise<Record<string, unknown>[]>;
+    /** One row, through the same pipeline. See {@link FetchService.fetchOneForRest}. */
+    fetchOneForRest<M extends Record<string, unknown>>(collectionPath: string, id: string | number, include?: IncludeSpec, databaseId?: string, options?: {
+        fields?: string[];
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
+    }): Promise<Record<string, unknown> | null>;
+    /** See {@link FetchService.cursorFor}. */
+    cursorFor(collectionPath: string, row: Record<string, unknown>, orderBy?: OrderByTuple[]): string | undefined;
     /**
      * Search rows by text
      */
@@ -71,6 +95,8 @@ export declare class DataService implements DataRepository {
         databaseId?: string;
         /** Only the `threshold` narrows the count — see `FetchService.count`. */
         vectorSearch?: VectorSearchParams;
+        /** See `FetchCollectionProps.withDeleted`. */
+        withDeleted?: WithDeleted;
     }): Promise<number>;
     /**
      * Check if a field value is unique in a collection
@@ -93,6 +119,7 @@ export declare class DataService implements DataRepository {
      */
     save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
         upsert?: boolean;
+        onConflict?: readonly string[];
     }): Promise<Record<string, unknown>>;
     /**
      * Delete an row by ID

package/dist/services/field-op-sql.d.ts

@@ -0,0 +1,16 @@
+import { SQL } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import type { ParsedFieldOp } from "@rebasepro/server";
+/**
+ * The expression one operation compiles to, or a 400 saying why it cannot.
+ *
+ * `field` is the property key; it is already known to be a column of `table`
+ * (the caller checks that against the same table it builds the statement from).
+ */
+export declare function compileFieldOp(table: PgTable, field: string, op: ParsedFieldOp, context: {
+    collectionPath: string;
+}): SQL;
+/** Compile a whole map of operations into a `SET`-ready object. */
+export declare function compileFieldOps(table: PgTable, fieldOps: Record<string, ParsedFieldOp>, context: {
+    collectionPath: string;
+}): Record<string, SQL>;

package/dist/services/field-viewer.d.ts

@@ -0,0 +1,19 @@
+import type { FieldViewer } from "@rebasepro/common";
+/**
+ * Run `fn` with `viewer` as the caller every row strip judges against.
+ *
+ * Nested calls shadow: a `dataAsAdmin` read inside a user request runs under the
+ * service identity for its duration and the user's viewer is restored after it,
+ * which is the behaviour both halves need and the reason this is not a variable.
+ */
+export declare function withFieldViewer<T>(viewer: FieldViewer | undefined, fn: () => T): T;
+/**
+ * The caller the current read is for, or `undefined` on the trusted server plane
+ * — an in-process `rebase.data` call on the base driver, a migration, the auth
+ * adapter reading a password hash to verify it.
+ *
+ * Absence cannot be reached from outside: every API ingress scopes its driver
+ * with `withAuth`, including an unauthenticated one (`roles: ["anon"]`), and
+ * that is what establishes the viewer.
+ */
+export declare function currentFieldViewer(): FieldViewer | undefined;

package/dist/services/realtimeService.d.ts

@@ -1,6 +1,6 @@
 import { WebSocket } from "ws";
 import { EventEmitter } from "events";
-import { DataDriver, WebSocketMessage, LogicalCondition, OrderByTuple } from "@rebasepro/types";
+import { DataDriver, IncludeSpec, WebSocketMessage, LogicalCondition, OrderByTuple } from "@rebasepro/types";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
@@ -21,6 +21,15 @@ export interface SubscriptionAuthContext {
      * makes a realtime leak invisible from the surface people test.
      */
     isAnonymous?: boolean;
+    /**
+     * The custom claims on the socket's token, for the same reason
+     * `isAnonymous` is here: a refetch has to evaluate the same policies
+     * against the same principal the initial fetch did. A tenancy policy reads
+     * a claim, so a subscription that carried none would answer every frame
+     * from the tenant of nobody — which is no rows, silently, on a collection
+     * whose first page loaded fine.
+     */
+    claims?: Record<string, unknown>;
 }
 /** What a channel frame is asking to do. */
 export type ChannelAction = "join" | "broadcast" | "presence" | "history";
@@ -72,6 +81,20 @@ type StoredCollectionRequest = {
     searchString?: string;
     /** Ask each row which declared search field matched — populates `_matches`. */
     searchExplain?: boolean;
+    /**
+     * Relations to load, exactly as a REST list would.
+     *
+     * A subscription could not name any, and the refetch loaded **every**
+     * relation because it passed none — so `find()` returned a row with a
+     * foreign key and `listen()` returned the same row with a nested object
+     * where that key was. Same query, two shapes, and a client rendering both
+     * saw the row change the moment a write landed.
+     */
+    include?: IncludeSpec;
+    /** Columns to return — the same projection `?fields=` asks for. */
+    fields?: string[];
+    /** `SELECT DISTINCT` over the projection. */
+    distinct?: boolean;
 };
 /**
  * A registered subscription, plus the two counters that order its deliveries.
@@ -356,6 +379,17 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * with set_config calls so PostgreSQL RLS policies are enforced.
      */
     private fetchCollectionWithAuth;
+    /**
+     * The `meta` a `collection_update` frame carries beside its rows.
+     *
+     * Frames used to carry rows and primary keys and nothing else, so the
+     * client issued a `GET /count` **per push** to fill in a total it needed to
+     * render the same list it had just been handed — one extra round trip per
+     * write, per subscriber, forever. The refetch already knows the query; it
+     * counts once, here, under the same RLS transaction that read the rows, so
+     * the total describes the same set they came from.
+     */
+    private collectionMetaWithAuth;
     /**
      * Debounce an row refetch for a WebSocket subscription.
      */

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

@@ -29,17 +29,41 @@ export type RelationStyle = "ref" | "inline";
  * to unwrap that same level back out.
  */
 export declare function isJunctionRelation(relation: ResolvedRelation): boolean;
+/**
+ * Apply {@link toRestScalar} across a row, leaving undeclared columns alone.
+ *
+ * Exported because the include loader attaches related rows itself, and a
+ * target rendered differently from its parent is the shape bug this whole file
+ * exists to prevent — a date was a string at the top level and a
+ * `{ __type: "date" }` envelope one level down, in the same response.
+ */
+export declare function toRestValues(row: Record<string, unknown>, collection: CollectionConfig): Record<string, unknown>;
 /** Render one target row in the requested style. */
 /**
- * Drop every column the collection marked `excludeFromApi`.
+ * Drop every column this caller may not read.
  *
  * Password hashes and verification tokens have to be readable server-side but
  * must never reach a client — and "never" has to mean every exit from this
  * pipeline, including relation targets, or a secret leaks through whichever
  * path was overlooked. Keyed by both the property name and its column name,
  * since a row can arrive keyed either way depending on the caller.
+ *
+ * `excludeFromApi` is the case with no roles in it: `effectiveAccess` expands
+ * the flag to `read: []`, which no caller satisfies, so the flag needs no branch
+ * of its own here and no longer has one. `access.read: ["hr"]` is the same walk
+ * asking a different question of {@link currentFieldViewer}.
+ *
+ * The field is **deleted**, never nulled. A withheld value that arrives as
+ * `null` is indistinguishable from a stored `null`, which turns a permission
+ * boundary into a question a client can answer by counting nulls — and it makes
+ * an `update` that echoes the row back overwrite the real value with the null it
+ * was handed.
+ *
+ * `_matches` is filtered rather than deleted: it is the list of fields a text
+ * search hit, and a field the caller cannot read must not appear in it even
+ * though the array itself is theirs to see.
  */
-export declare function stripExcluded(row: Record<string, unknown>, collection: CollectionConfig): Record<string, unknown>;
+export declare function stripUnreadable(row: Record<string, unknown>, collection: CollectionConfig): Record<string, unknown>;
 /**
  * The address a relation ref points at.
  *
@@ -65,9 +89,9 @@ export declare function toFlatRow(row: Record<string, unknown>, collection: Coll
  *
  * 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.
+ * {@link coerceDeclaredNumber}) and a `date` as RFC 3339, which is what this
+ * server's own OpenAPI document says a date column is (see
+ * {@link toRestDate}).
  *
  * 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