@zeroxsolutions/db 9.4.0 → 9.5.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 9.5.0 (2026-10-16)
+
+### 🚀 Features
+
+- **db:** index the outbox's unpublished rows alone, by type and by time ([6f9dc0b](https://github.com/zeroxsolutions/zeroxsolutions/commit/6f9dc0b))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5
+- Lương Văn Tú
+
 ## 9.4.0 (2026-10-14)
 
 ### 🚀 Features

package/README.md

@@ -33,13 +33,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`      | 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                                                                                                            |
 
 ---
 
@@ -99,23 +99,23 @@ export class UserRepository extends BaseRepository<typeof users, typeof schema,
 
 #### 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 |
+| 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
 
@@ -141,13 +141,13 @@ skipping another. With no `sort`, a page is ordered by the key alone.
 `fields` and `include` are `TableQuery<typeof schema, '<export name>'>`, the shape `@zeroxsolutions/query` guards, so
 a guarded query spreads straight into the options:
 
-| 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 |
+| 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 |
+| an empty fieldset             | the primary key alone                                               |
+| an include path               | each relation on it, under its own table's fieldset                 |
 
 `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
@@ -210,7 +210,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 +224,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 +294,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 +304,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 +320,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
@@ -351,15 +356,15 @@ const condition = buildFilterConditions({
 
 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.
 
@@ -374,10 +379,10 @@ column under that same name in `resolvers`:
 import { permitsFor } from '@zeroxsolutions/query';
 import { buildFilterConditions, columnResolver } from '@zeroxsolutions/db/utils';
 
-const placesQueryPermits = permitsFor(placeAttributes, { relationships: places.relationships }).relationship(
-  'region',
-  ['equals', 'in'],
-);
+const placesQueryPermits = permitsFor(placeAttributes, { relationships: places.relationships }).relationship('region', [
+  'equals',
+  'in',
+]);
 
 const condition = buildFilterConditions({
   table: places,
@@ -417,11 +422,7 @@ only the offending field name; the calling service maps each error **type** to i
 own transport.
 
 ```ts
-import {
-  assertQueryableFields,
-  InvalidQueryFilter,
-  type QueryableFields,
-} from '@zeroxsolutions/db/utils';
+import { assertQueryableFields, InvalidQueryFilter, type QueryableFields } from '@zeroxsolutions/db/utils';
 
 const USERS_QUERYABLE = {
   filterable: ['name', 'createdAt'],
@@ -443,7 +444,10 @@ import { collectionQuerySchema } from '@zeroxsolutions/query';
 
 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.findAllAndCount(
+  buildFilterConditions({ table: users, filter: query.filter }),
+  query,
+);
 ```
 
 Pass `filterItem: filterValueSchema` in the spec so the parsed clauses are the ones this package's
@@ -454,11 +458,11 @@ builders accept. A test in `utils/filter.spec.ts` pins the absence of a second q
 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';
@@ -520,11 +524,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)),
+]);

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

@@ -1 +1 @@
-{"version":3,"file":"outbox-table.d.ts","sourceRoot":"","sources":["../../../src/base/postgres/outbox-table.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYvB,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC"}
+{"version":3,"file":"outbox-table.d.ts","sourceRoot":"","sources":["../../../src/base/postgres/outbox-table.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBvB,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC"}

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

@@ -1,3 +1,4 @@
+import { isNull } from 'drizzle-orm';
 import { index, jsonb, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
 import { v7 as uuidv7 } from 'uuid';
 /**
@@ -12,4 +13,11 @@ export const outboxTable = pgTable('outbox', {
     payload: jsonb('payload').notNull(),
     occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().defaultNow(),
     publishedAt: timestamp('published_at', { withTimezone: true }),
-}, (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)),
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/db",
-  "version": "9.4.0",
+  "version": "9.5.0",
   "description": "Generic Drizzle toolkit - the id column and audit timestamps a table takes, a base repository, the unit-of-work and transactional outbox impls, and the filter/sort/pagination query helpers, for PostgreSQL (postgres-js) and Cloudflare D1; ships no domain schema. Shared across ZeroXSolutions services.",
   "private": false,
   "type": "module",
@@ -42,8 +42,8 @@
   "dependencies": {
     "tslib": "^2.3.0",
     "uuid": "^14.0.1",
-    "@zeroxsolutions/cosmic": "0.3.4",
-    "@zeroxsolutions/query": "0.7.3"
+    "@zeroxsolutions/query": "0.7.3",
+    "@zeroxsolutions/cosmic": "0.3.4"
   },
   "peerDependencies": {
     "@testcontainers/postgresql": "^12.1.0",