@zeroxsolutions/db 9.4.0 → 10.0.0

package/README.md

@@ -5,16 +5,17 @@ A shared database library providing base entities, repository patterns, and quer
 ## Features
 
 - Base table schema with common audit columns (`id`, `createdAt`, `updatedAt`, `deletedAt`)
-- Abstract `BaseRepository` with full CRUD, soft-delete, pagination, and relation support
-- `BaseViewRepository` for PostgreSQL materialized views
-- Type-safe filter and ordering utilities with Zod validation, plus a `QueryableFields` whitelist guard
-  (`assertQueryableFields`) keyed to the row type, so a removed column fails typecheck at the whitelist
+- Abstract `BaseRepository` split as a Spring Data repository is: public methods that take no condition, and
+  protected ones taking a `where` that only a finder the repository names can call
+- `BaseViewRepository` for PostgreSQL materialized views, reading with the options a table repository takes
+- Reads that name what they load: a `read` of columns and nested relations, a `filter` tree, an `orderBy` with the
+  primary key appended, and a page window only when one is given
+- `READS` (`defineReads`), declared once per context: each table's order as a relation and its `virtual` filter and
+  order names; `relationsOf` for the relationships a permit list names
 - The filter vocabulary the wire toolkit is generic over: `filterOperatorSchema` / `FilterOperator` (15 operators),
-  `filterValueSchema`, and typed refusals (`UnknownQueryField`, `InvalidQueryFilter`, `InvalidQuerySort`)
-- Finders read a JSON:API query as drizzle's relational config: `fields` and `include`, typed off the schema by
-  `TableQuery`, resolved by `buildRelationalRead`
+  `filterValueSchema`, and typed refusals (`UnknownQueryField`, `UnknownReadName`)
 - Transaction support for all operations
-- Automatic soft-delete filtering (excludes `deletedAt IS NOT NULL` by default)
+- Automatic soft-delete filtering at every level of a read (excludes `deletedAt IS NOT NULL` by default)
 - `DrizzleUnitOfWork` + transactional `outboxTable` / `DrizzleOutbox` - the `@zeroxsolutions/cosmic` `IUnitOfWork` port implementation (atomic use case + domain events staged in the same transaction)
 
 ## Installation
@@ -33,13 +34,13 @@ Import from the subpath that matches your driver. **There is no root entry**: `p
 declares `"."`, but no `src/index.ts` exists for the build to emit it from, so
 `from '@zeroxsolutions/db'` does not resolve.
 
-| Export path              | Description                                |
-| ------------------------ | ------------------------------------------ |
-| `@zeroxsolutions/db/postgres` | PostgreSQL entity, repository, view repository, unit of work, outbox, and types |
-| `@zeroxsolutions/db/d1`  | Cloudflare D1 (SQLite) entity, repository, unit of work, outbox, and types |
-| `@zeroxsolutions/db/utils` | Filter and order builders, `TableQuery` and the relational-read builder, the field-whitelist guard, the filter-value schema + operator enum, omit masks, pagination constants |
-| `@zeroxsolutions/db/testing` | A throwaway Postgres container carrying your schema, on the engine you name, plus the container timeout and a fake uuid v7 |
-| `@zeroxsolutions/db/containers` | The forced remove that tears down a container you started yourself |
+| Export path                     | Description                                                                                                                |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@zeroxsolutions/db/postgres`   | PostgreSQL entity, repository, view repository, unit of work, outbox, and types                                            |
+| `@zeroxsolutions/db/d1`         | Cloudflare D1 (SQLite) entity, repository, unit of work, outbox, and types                                                 |
+| `@zeroxsolutions/db/utils`      | `defineReads`, `relationsOf`, the read and order types, the filter-value schema + operator enum, the refusals, omit masks  |
+| `@zeroxsolutions/db/testing`    | A throwaway Postgres container carrying your schema, on the engine you name, plus the container timeout and a fake uuid v7 |
+| `@zeroxsolutions/db/containers` | The forced remove that tears down a container you started yourself                                                         |
 
 ---
 
@@ -77,94 +78,132 @@ export const users = pgTable(
 
 ### BaseRepository
 
-Extend `BaseRepository` to get a fully featured data access layer:
+Extend `BaseRepository`; a read or a write keyed by anything but the id is a finder you name, over a protected method:
 
 ```ts
 import { eq } from 'drizzle-orm';
-import { BaseRepository } from '@zeroxsolutions/db/postgres';
+import { BaseRepository, type FindAllOptions } from '@zeroxsolutions/db/postgres';
 import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
-import { users } from './schema';
-import type * as schema from './schema';
+import * as schema from './schema';
+import { READS, usersTable } from './schema';
 
-export class UserRepository extends BaseRepository<typeof users, typeof schema, 'users'> {
+export class UserRepository extends BaseRepository<typeof usersTable, typeof schema, 'usersTable'> {
   constructor(db: PostgresJsDatabase<typeof schema>) {
-    super(db, users, 'users'); // 'users' is the queryKey for relational queries
+    super(db, usersTable, 'usersTable', READS); // the export name, and the context's READS
   }
 
-  findOneByEmail(email: string) {
-    return this.findOne(eq(users.email, email));
+  findAllAndCountByTenantId(tenantId: string, options?: FindAllOptions<typeof schema, 'usersTable'>) {
+    return this.findAllAndCountWhere(eq(usersTable.tenantId, tenantId), options);
   }
 }
 ```
 
-#### Available Methods
-
-| Method | Description |
-| ------ | ----------- |
-| `findAll(where, options?)` | Paginated list query |
-| `findAllAndCount(where, options?)` | Paginated list + total count in parallel |
-| `findOne(where, options?)` | First matching record or `null` |
-| `findOneById(id, options?)` | Find by primary key or `null` |
-| `create(data, options?)` | Insert one record, returns inserted row |
-| `createMany(data[], options?)` | Bulk insert, returns inserted rows |
-| `update(where, data, options?)` | Update matching records, returns first updated row |
-| `updateById(id, data, options?)` | Update by primary key |
-| `delete(where, options?)` | Hard delete matching records |
-| `deleteById(id, options?)` | Hard delete by primary key |
-| `count(where, options?)` | Count matching records |
-| `exists(where, options?)` | Returns `true` if any record matches |
-| `softDelete(where, options?)` | Sets `deletedAt` to now |
-| `softDeleteById(id, options?)` | Soft delete by primary key |
-| `nullifyBy(field, value, options?)` | Set field to `null` where field equals value |
-
-#### FindAll Options
+The third argument is the table's EXPORT name in the schema, which drizzle's relational query looks a relation up
+by; omitted, a read that loads a relation throws.
+
+#### Public methods
+
+No public method takes a condition, so no SQL reaches the repository from outside it.
+
+| Method                             | Description                                                  |
+| ---------------------------------- | ------------------------------------------------------------ |
+| `findOneById(id, options?)`        | The row with that id, or `null`                              |
+| `findAllById(ids, options?)`       | Every row with one of those ids; no page window              |
+| `existsById(id, options?)`         | Whether a row holds the id                                   |
+| `findAll(options?)`                | The rows the options match                                   |
+| `findAllAndCount(options?)`        | Those rows, and the count under the same filter, in parallel |
+| `count(options?)`                  | How many rows the filter matches                             |
+| `create(data, options?)`           | Insert one row, returns it                                   |
+| `createMany(data[], options?)`     | Bulk insert, returns the rows                                |
+| `updateById(id, data, options?)`   | Update by id                                                 |
+| `deleteById(id, options?)`         | Hard delete by id                                            |
+| `deleteAllById(ids, options?)`     | Hard delete every id                                         |
+| `softDeleteById(id, options?)`     | Set `deletedAt` by id                                        |
+| `softDeleteAllById(ids, options?)` | Set `deletedAt` on every id                                  |
+
+On a multi-tenant table every one of them crosses tenants; a tenant-scoped repository exposes named finders instead.
+
+#### Protected methods
+
+`findOneWhere`, `findAllWhere`, `findAllAndCountWhere`, `countWhere`, `existsWhere`, `updateWhere`, `deleteWhere`,
+`softDeleteWhere` and `nullifyBy`, each taking a drizzle `where` beside the options. A finder's name states that
+condition (`findAllAndCountByTenantId`), the way a Spring Data derived query's does.
+
+#### Read options
 
 ```ts
-type FindAllOptions = {
-  tx?: Transaction;      // Run within a transaction
-  limit?: number;        // Default: 20; a larger value is clamped to 100, not rejected
-  offset?: number;       // Default: 0
-  softDeleted?: boolean; // Include soft-deleted records (default: false)
-  sort?: SortField[];    // [{ field: 'createdAt', direction: 'desc' }]; the primary key is appended
-  fields?: { books?: readonly ('title' | 'author')[] }; // Fieldsets keyed by TABLE name: columns and relations
-  include?: readonly ('author' | 'author.books')[];      // Relation paths, dot-separated (requires queryKey)
-  columns?: { authorId?: boolean }; // Root columns added to the root fieldset; never narrows the row
-  with?: { ... };        // Drizzle relational "with" clause, spelled out (requires queryKey)
+type FindOneOptions = {
+  read?: Read; // what loads; every column and no relation where absent
+  softDeleted?: boolean; // whether marked root rows match (default: false)
+  at?: Date; // the instant a virtual name is decided at (default: the call)
+};
+type FindAllOptions = FindOneOptions & {
+  filter?: FilterNode[]; // the condition tree; root nodes join by `and`
+  orderBy?: { field: string; direction: 'asc' | 'desc' }[]; // the primary key is appended
+  limit?: number; // with none, every match
+  offset?: number;
 };
+type CountOptions = { filter?: FilterNode[]; softDeleted?: boolean; at?: Date };
 ```
 
-`findAll` and `findAllAndCount` order by `sort` followed by each primary key column it does not
-already name, ascending, on both Postgres and D1. Rows that tie on `sort` have no order of their own,
-so without the key two pages could be cut from two orders of the same rows, repeating one row and
-skipping another. With no `sort`, a page is ordered by the key alone.
+A read holds no transaction: one that must see a write in progress belongs to an aggregate repository on the unit of
+work's executor. The writes still take `tx`.
 
-`fields` and `include` are `TableQuery<typeof schema, '<export name>'>`, the shape `@zeroxsolutions/query` guards, so
-a guarded query spreads straight into the options:
+| `read` holds                   | The finder loads                                                            |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| nothing                        | every column of the root table, and no relation                             |
+| `columns`                      | those columns; on the root table its primary key beside them                |
+| `relations.<name>`             | that relation under its own nested `read`, every column where it names none |
+| `relations.<name>.orderBy`     | the related rows in that order, in place of the one `READS` declares        |
+| `relations.<name>.softDeleted` | that relation's marked rows too                                             |
 
-| The query says | The finder loads |
-| --- | --- |
-| no fieldset for a table | every column of that table |
-| a fieldset | those columns and the table's primary key |
-| a relation name in a fieldset | that relation's primary keys - the linkage a relationship publishes |
-| an empty fieldset | the primary key alone |
-| an include path | each relation on it, under its own table's fieldset |
+The soft-delete condition holds at every level: a marked related row of a relation to one loads as `null`, and the
+marked rows of a relation to many are left out. A name the table does not hold throws `UnknownReadName`, naming its
+path. A read loading no relation takes a plain `select`, so a repository given no `queryKey` still narrows its row.
 
-`with` and `include` reach the same relational query; where both name one relation, `with` wins. A read loading no
-relation takes a plain `select` of the columns it narrowed to, so a repository given no `queryKey` still narrows its
-own row. An include path is typed three relations deep; spell a deeper one out with `with`.
+`findAll` and `findAllAndCount` order by `orderBy` followed by each primary key column it does not already name,
+ascending, on both Postgres and D1. Rows that tie have no order of their own, so without the key two pages could be cut
+from two orders of the same rows, repeating one row and skipping another.
+
+A filter or an order name resolves to a `virtual` name of the context's `READS` first, then to a relation to one row,
+compared by the related row's id (`equals` and `in` only), then to a column; anything else throws `UnknownQueryField`
+before any SQL is built.
+
+#### READS
+
+```ts
+import { defineReads } from '@zeroxsolutions/db/utils';
+
+export const READS = defineReads(schema, {
+  openingHoursTable: { orderBy: [{ field: 'weekday', direction: 'asc' }] },
+  placesTable: {
+    virtual: {
+      'openState.status': {
+        filter: (condition, { at }) => sql`(<an expression over ${placesTable.id} and ${at}>) = ${condition.value}`,
+        order: ({ at }) => sql`<an expression over ${placesTable.id} and ${at}>`,
+      },
+    },
+  },
+});
+```
+
+Each key is a table's export name and each order field one of its columns, checked when `defineReads` runs. A
+`virtual` filter expression is wrapped in parentheses, so its `or` cannot reach the soft-delete condition.
 
 #### Nullify FK
 
-Set a foreign key column to `null` where it matches a given value. Useful when soft-deleting a parent but keeping child rows:
+`nullifyBy` sets a foreign key column to `null` where it matches a given value, from inside a named method:
 
 ```ts
 // Set categoryId = null on all transactions where categoryId = '123'
-await transactionRepo.nullifyBy('categoryId', '123', { tx });
+detachCategory(categoryId: string, tx: Transaction) {
+  return this.nullifyBy('categoryId', categoryId, { tx });
+}
 ```
 
 #### Transactions
 
-All methods accept an optional `tx` in their options:
+Every write accepts an optional `tx` in its options:
 
 ```ts
 await db.transaction(async (tx) => {
@@ -182,7 +221,7 @@ import { userSummaryView } from './views';
 // The same schema-typed client the service's table repositories take.
 export class UserSummaryViewRepository extends BaseViewRepository<typeof userSummaryView, typeof schema> {
   constructor(db: PostgresJsDatabase<typeof schema>) {
-    super(db, userSummaryView);
+    super(db, userSummaryView, ['tenantId']); // the columns of the view's unique index
   }
 }
 
@@ -190,10 +229,13 @@ export class UserSummaryViewRepository extends BaseViewRepository<typeof userSum
 await repo.refresh({ concurrently: true });
 ```
 
-`findAll` takes `FindAllViewOptions` - `tx`, `limit`, `offset` and `fields` - and `findOne` the same without the page
-window. `fields` is keyed by the view's name; a fieldset loads those columns and any the view selected from a table's
-primary key. A view has no `deletedAt` and no relational config, so it takes no `softDeleted`, `with` or `include`,
-and a view read is ordered in the view's own definition.
+A view repository reads with the options a table repository takes, without relations, `softDeleted` or `at`:
+`FindAllViewOptions` holds a `read` of `columns`, `filter`, `orderBy`, `limit` and `offset`, `FindOneViewOptions` the
+`read`, and `CountViewOptions` the `filter`. Its public `findAll`, `findAllAndCount` and `count` take no condition, and
+the protected `findAllWhere`, `findOneWhere`, `findAllAndCountWhere` and `countWhere` do. The constructor's third
+argument, the columns of the view's unique index, is appended to every order: a materialized view is read back with no
+order of its own, and PostgreSQL documents that different `LIMIT` and `OFFSET` values give inconsistent results
+without an `ORDER BY` that fixes one.
 
 ### Unit of Work & Transactional Outbox
 
@@ -210,7 +252,7 @@ import { DrizzleUnitOfWork, DrizzleOutbox } from '@zeroxsolutions/db/postgres';
 
 // built in the transport per invocation (the db client comes from the connection string)
 const uow = new DrizzleUnitOfWork(db, (tx) => {
-  const scope = container.createChildContainer();          // bind the transaction to a scoped container
+  const scope = container.createChildContainer(); // bind the transaction to a scoped container
   scope.register(TOKENS.TX, { useValue: tx });
   scope.register(TOKENS.OUTBOX, { useValue: new DrizzleOutbox(tx) });
   return scope;
@@ -224,9 +266,14 @@ await uow.run(async (tx) => {
 ```
 
 `outboxTable` columns: `id` (uuid v7), `type` (event discriminator), `payload` (`jsonb`), `occurredAt`,
-and `publishedAt` (NULL until the relay sends it; indexed). The relay reads unsent rows with
+and `publishedAt` (NULL until the relay sends it). The relay reads unsent rows with
 `outbox.pullUnpublished(limit)` and acknowledges them with `outbox.markPublished(ids, publishedAt)`.
 
+Two indexes hold the unsent rows alone, so the published ones never slow a relay down:
+`idx_outbox_unpublished_occurred_at` on `occurredAt`, for a relay that sends every type, and
+`idx_outbox_unpublished_type_occurred_at` on `(type, occurredAt)`, for one that sends only some. Both
+answer in `occurredAt` order without a sort.
+
 ---
 
 ## Cloudflare D1 (SQLite)
@@ -289,7 +336,7 @@ import { DrizzleD1UnitOfWork, DrizzleOutbox } from '@zeroxsolutions/db/d1';
 
 // built in the transport per invocation (the db client comes from the Hyperdrive/D1 binding)
 const uow = new DrizzleD1UnitOfWork(db, ({ db, collector }) => {
-  const scope = container.createChildContainer();   // reads use db; writes push to collector
+  const scope = container.createChildContainer(); // reads use db; writes push to collector
   scope.register(TOKENS.TX, { useValue: { db, collector } });
   scope.register(TOKENS.OUTBOX, { useValue: new DrizzleOutbox(db, collector) });
   return scope;
@@ -299,7 +346,7 @@ const uow = new DrizzleD1UnitOfWork(db, ({ db, collector }) => {
 await uow.run(async (tx) => {
   await tx.resolve<ILinkAggregateRepository>(TOKENS.LINK_AGGREGATE_REPOSITORY).save(link);
   await tx.resolve<IOutboxWriter>(TOKENS.OUTBOX).stage(link.pullEvents());
-});                                            // -> flush [save, ...stage] as ONE batch()
+}); // -> flush [save, ...stage] as ONE batch()
 ```
 
 A consuming context's D1 aggregate repository takes both the `db` (for immediate `load` reads) and
@@ -315,7 +362,7 @@ The D1 `DrizzleOutbox` mirrors the Postgres surface (`stage` / `pullUnpublished(
 (so it commits with the aggregate write), or executes immediately when constructed standalone (relay
 use). `outboxTable` columns: `id` (uuid v7), `type` (event discriminator), `payload` (text - SQLite
 has no `jsonb`, so the relay `JSON.parse`s), `occurredAt`, and `publishedAt` (NULL until the relay
-sends it; indexed).
+sends it), with the same two indexes over the unsent rows as the Postgres table.
 
 > **Limitation.** D1's `batch()` is atomic but non-interactive, so the D1 UoW gives all-or-nothing
 > write atomicity without a transaction-scoped read snapshot. A handler that loads, decides, then
@@ -325,140 +372,62 @@ sends it; indexed).
 
 ## Utilities
 
-Import from `@zeroxsolutions/db/utils`.
-
-### Filter Builder
-
-Converts typed filter descriptors into Drizzle `SQL` conditions:
-
-Takes one options object, so a parsed wire query spreads straight in. Returns `undefined` when the
-tree contributes no condition, and throws `UnknownQueryField` when a clause names a column the table
-does not hold:
-
-```ts
-import { buildFilterConditions } from '@zeroxsolutions/db/utils';
-
-const condition = buildFilterConditions({
-  table: users,
-  filter: [
-    { field: 'name', operator: 'contains', value: 'alice' },
-    { field: 'createdAt', operator: 'gte', value: '2024-01-01' },
-  ],
-});
-```
+Import from `@zeroxsolutions/db/utils`. The builders that turn a filter and an order into SQL are the base
+repository's own; a finder hands `filter` and `orderBy` to it unchanged.
 
 #### Supported Operators
 
 All 15, as `filterOperatorSchema` declares them:
 
-| Operator | Description |
-| -------- | ----------- |
-| `equals` / `notEquals` | Exact match / not equal |
-| `in` / `notIn` | Array membership; an empty array contributes no condition |
+| Operator                               | Description                                                                                                     |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `equals` / `notEquals`                 | Exact match / not equal                                                                                         |
+| `in` / `notIn`                         | Array membership; an empty array contributes no condition                                                       |
 | `contains` / `startsWith` / `endsWith` | Case-insensitive text match: `ILIKE` on Postgres, `LIKE` on SQLite, which is already case-insensitive for ASCII |
-| `gt` / `gte` / `lt` / `lte` | Numeric/date comparisons |
-| `between` | Range (`from` / `to`, both optional) |
-| `notBetween` | Range exclusion (`from` and `to`, both required) |
-| `isNull` / `isNotNull` | Null checks; carry no `value` key at all |
+| `gt` / `gte` / `lt` / `lte`            | Numeric/date comparisons                                                                                        |
+| `between`                              | Range (`from` / `to`, both optional)                                                                            |
+| `notBetween`                           | Range exclusion (`from` and `to`, both required)                                                                |
+| `isNull` / `isNotNull`                 | Null checks; carry no `value` key at all                                                                        |
 
 A `%` or `_` in a text value is escaped, so it matches literally rather than as a wildcard.
 
-#### Relationship Filters
-
-A relationship named in a permit list is no column - its id sits in a foreign-key column instead, which
-`buildFilterConditions` cannot resolve on its own. Declare the permit through `permitsFor`'s own
-`relationship(name, operators)` (`@zeroxsolutions/query`), then hand `columnResolver` the foreign-key
-column under that same name in `resolvers`:
-
-```ts
-import { permitsFor } from '@zeroxsolutions/query';
-import { buildFilterConditions, columnResolver } from '@zeroxsolutions/db/utils';
-
-const placesQueryPermits = permitsFor(placeAttributes, { relationships: places.relationships }).relationship(
-  'region',
-  ['equals', 'in'],
-);
-
-const condition = buildFilterConditions({
-  table: places,
-  filter: query.filter,
-  resolvers: { region: columnResolver(places.regionId) },
-});
-```
-
-`columnResolver` answers `equals` and `in` - the only two operators a relationship filter grants -
-comparing the id against the column it closes over, and throws on any other operator.
-
-- `relationshipsOf(schema, '<table export>')` - the relations the schema declares on that table, as the map
-  `permitsFor(schema, { relationships })` takes, so a relationship filter names a relation the schema holds.
-  Throws on a key that is no table export (a table's SQL name is not one).
+### relationsOf
 
-### Order Builder
-
-```ts
-import { buildOrderBy } from '@zeroxsolutions/db/utils';
-
-const clauses = buildOrderBy(users, [
-  { field: 'createdAt', direction: 'desc' },
-  { field: 'name', direction: 'asc' },
-]);
-```
-
-`buildOrderBy` translates exactly the clauses it is given and appends no key, so it can build part of
-an order one clause at a time. A read that pages over its result owes itself a unique last clause.
-
-### Field Whitelist Guard
-
-Reject a `filter`/`sort` on any field outside a listable entity's whitelist **before** building SQL, so a
-client can never filter or order by a hidden column (e.g. an access code). `QueryableFields<TSelect>` is keyed
-to the row's `$inferSelect` type, so a renamed/removed column fails typecheck at the whitelist. The guard is
-transport-agnostic - it throws a plain `Error` subclass (`InvalidQueryFilter` / `InvalidQuerySort`) carrying
-only the offending field name; the calling service maps each error **type** to its HTTP status/code at its
-own transport.
-
-```ts
-import {
-  assertQueryableFields,
-  InvalidQueryFilter,
-  type QueryableFields,
-} from '@zeroxsolutions/db/utils';
-
-const USERS_QUERYABLE = {
-  filterable: ['name', 'createdAt'],
-  sortable: ['name', 'createdAt'],
-} as const satisfies QueryableFields<typeof users.$inferSelect>;
-
-// In a repository finder, before building SQL:
-assertQueryableFields(query, USERS_QUERYABLE); // throws InvalidQueryFilter / InvalidQuerySort on a hidden field
-```
+`relationsOf(schema, '<table export>')` answers the relations the schema declares on that table, each with the type
+its fieldset is keyed by (its table's SQL name), its primary key, and its own relations, read when a path walks into
+them. A permit list carries it as `relationships`, `permitsFor` checks a relationship filter's name against it, and
+`findOptionsOf` in `@zeroxsolutions/jsonapi` finds an included relation's fieldset through it. It throws on a key that
+is no table export (a table's SQL name is not one).
 
 ### Reading the query off a request
 
-This package ships **no** query schema. Parse the request with
-[`@zeroxsolutions/query`](../query) and hand its result straight to a finder - the
-member names line up (`offset` / `limit` / `sort` / `filter` / `fields` / `include`), so nothing renames anything:
+This package ships **no** query schema and knows no wire format. Parse the request with
+[`@zeroxsolutions/query`](../query), and turn the guarded query into finder options with `findOptionsOf` from
+[`@zeroxsolutions/jsonapi`](../jsonapi):
 
 ```ts
 import { collectionQuerySchema } from '@zeroxsolutions/query';
+import { findOptionsOf } from '@zeroxsolutions/jsonapi';
 
 createRoute({ request: { query: collectionQuerySchema(usersQueryPermits) } });
-const query = c.req.valid('query');
-const [rows, total] = await usersRepository.findAllAndCount(buildFilterConditions({ table: users, filter: query.filter }), query);
+const [rows, total] = await usersRepository.findAllAndCountByTenantId(
+  tenantId,
+  findOptionsOf(c.req.valid('query'), usersQueryPermits),
+);
 ```
 
-Pass `filterItem: filterValueSchema` in the spec so the parsed clauses are the ones this package's
-builders accept. A test in `utils/filter.spec.ts` pins the absence of a second query shape.
+Pass `filterItem: filterValueSchema` in the permits so the parsed clauses are the ones this package's finders accept.
 
 ### Omit Constants
 
 Three column masks, each a plain `{ column: true }` object to hand to a schema builder's `omit` or to
 `Omit<...>`. This package exports the masks only - it ships no `omit` helper of its own.
 
-| Mask | Drops |
-| ---- | ----- |
-| `defaultSelectOmit` | `deletedAt` |
+| Mask                  | Drops                                   |
+| --------------------- | --------------------------------------- |
+| `defaultSelectOmit`   | `deletedAt`                             |
 | `defaultResponseOmit` | the above plus `createdAt`, `updatedAt` |
-| `defaultInsertOmit` | the above plus `id` |
+| `defaultInsertOmit`   | the above plus `id`                     |
 
 ```ts
 import { defaultInsertOmit } from '@zeroxsolutions/db/utils';
@@ -466,15 +435,6 @@ import { defaultInsertOmit } from '@zeroxsolutions/db/utils';
 type InsertUser = Omit<typeof users.$inferInsert, keyof typeof defaultInsertOmit>;
 ```
 
-### Pagination Constants
-
-```ts
-import { DEFAULT_PAGE_SIZE, DEFAULT_OFFSET, MAX_PAGE_SIZE } from '@zeroxsolutions/db/utils';
-// DEFAULT_PAGE_SIZE = 20
-// DEFAULT_OFFSET    = 0
-// MAX_PAGE_SIZE     = 100
-```
-
 ---
 
 ## Testing Seam
@@ -520,11 +480,11 @@ This package names no engine for you, and exports no constant standing in as tha
 major you run is your deployment's own fact, so `image` takes no default: a forgotten argument is a
 typecheck failure rather than a suite that quietly passed on a major you do not deploy.
 
-| Export | What it is |
-| ------ | ---------- |
+| Export                                   | What it is                                                                                                                                                                                                                                                 |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `startDisposablePostgres(schema, image)` | Starts the container, creates `schema` in it, and returns a Drizzle client typed against it, the `connectionString` it dialled, and the `stop()` that tears it down. A server `WARNING` prints as one line on `console.warn`; lower severities are dropped |
-| `CONTAINER_TIMEOUT_MS` | 180s, for the hook that starts a container: an image pull on a cold machine outruns vitest's 5s default |
-| `fakeUuidV7` | Random bits in a v7 layout: it passes a v7 check, and is not time-ordered like a minted id |
+| `CONTAINER_TIMEOUT_MS`                   | 180s, for the hook that starts a container: an image pull on a cold machine outruns vitest's 5s default                                                                                                                                                    |
+| `fakeUuidV7`                             | Random bits in a v7 layout: it passes a v7 check, and is not time-ordered like a minted id                                                                                                                                                                 |
 
 ### A container you started yourself
 

package/dist/base/d1/outbox-table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outbox-table.d.ts","sourceRoot":"","sources":["../../../src/base/d1/outbox-table.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAcvB,CAAC;AAEF,sGAAsG;AACtG,MAAM,MAAM,SAAS,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC"}
+{"version":3,"file":"outbox-table.d.ts","sourceRoot":"","sources":["../../../src/base/d1/outbox-table.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBvB,CAAC;AAEF,sGAAsG;AACtG,MAAM,MAAM,SAAS,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC"}

package/dist/base/d1/outbox-table.js

@@ -1,3 +1,4 @@
+import { isNull } from 'drizzle-orm';
 import { index, sqliteTable, text } from 'drizzle-orm/sqlite-core';
 import { v7 as uuidv7 } from 'uuid';
 /**
@@ -16,4 +17,11 @@ export const outboxTable = sqliteTable('outbox', {
         .notNull()
         .$defaultFn(() => new Date().toISOString()),
     publishedAt: text('published_at'),
-}, (table) => [index('idx_outbox_published_at').on(table.publishedAt)]);
+}, 
+// Both hold the unpublished rows alone, so a backlog of published rows never slows a relay. The
+// first answers a relay that publishes every type, the second one that publishes only some, each in
+// `occurredAt` order without a sort.
+(table) => [
+    index('idx_outbox_unpublished_occurred_at').on(table.occurredAt).where(isNull(table.publishedAt)),
+    index('idx_outbox_unpublished_type_occurred_at').on(table.type, table.occurredAt).where(isNull(table.publishedAt)),
+]);