@ahrowe/mongo 0.1.3 → 0.2.0

package/dist/outboxRelay.js

@@ -1,5 +1,4 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { getOutboxCollection, getRegisteredCollections, getServiceBus } from './db.js';
+import { dispatchEvent, getOutboxCollection, getRegisteredCollections } from './db.js';
 import { OutboxStatus } from './types/outbox.js';
 const logger = {
     info: console.info,
@@ -11,34 +10,33 @@ const defaultBackoff = (attempt) => Math.min(30000, 1000 * 2 ** Math.max(0, atte
 /** Rows past their retention are removed by the TTL index on `expireAt`. `null` keeps a row forever. */
 const expiryAfter = (keepMs) => (Number.isFinite(keepMs) ? new Date(Date.now() + keepMs) : null);
 /**
- * Due rows, plus rows whose lease ran out, for collections this process has a service for.
- * A row for any other collection waits for a relay that has its listeners, instead of
- * being marked done with nobody notified. Exported for the index test, not part of the public barrel.
+ * Due rows for collections this process has a service for. A claimed row whose lease ran out is
+ * due again, so it needs no condition of its own. A row for any other collection waits for a relay
+ * that has its listeners, instead of being marked done with nobody notified. Exported for the
+ * index test, not part of the public barrel.
  */
 export const claimFilter = (now, collectionNames) => ({
     collectionName: { $in: collectionNames },
-    $or: [
-        { status: OutboxStatus.Pending, nextAttemptAt: { $lte: now } },
-        { status: OutboxStatus.Processing, leasedUntil: { $lt: now } },
-    ],
+    status: OutboxStatus.Pending,
+    nextAttemptAt: { $lte: now },
 });
 /**
- * Longest-due first. nextAttemptAt (equal to createdOn for a fresh row) is in
- * the status index, so both $or branches come back pre-sorted and get merged.
- * Sorting by createdOn instead read and sorted every due row in memory, once
- * per claimed row.
+ * Longest-due first. nextAttemptAt (equal to createdOn for a fresh row) is in the status index,
+ * so the rows come back pre-sorted. Sorting by createdOn instead read and sorted every due row in
+ * memory, once per claimed row.
  */
 export const CLAIM_SORT = { nextAttemptAt: 1 };
 /**
  * Drains the transactional outbox and dispatches each event to the in-process
  * listeners registered on its source collection's bus.
  *
- * Restart-safe and multi-pod-safe: rows are claimed with an atomic
- * findOneAndUpdate + a lease, stale leases are reclaimed, and delivery is
- * at-least-once (consumers must be idempotent).
+ * Restart-safe and multi-pod-safe: a claim is an atomic findOneAndUpdate that
+ * pushes the row's nextAttemptAt past a lease, so a row whose holder died is
+ * due again once the lease runs out. Delivery is at-least-once (consumers must
+ * be idempotent).
  */
 export const startOutboxRelay = (options) => {
-    const { instanceId, pollIntervalMs = 500, batchSize = 20, leaseMs = 30000, maxAttempts = 10, backoffMs = defaultBackoff, keepDoneMs = 7 * 24 * 60 * 60 * 1000, keepFailedMs = Infinity, autoStart = true, } = options;
+    const { instanceId, pollIntervalMs = 500, batchSize = 20, leaseMs = 30000, maxAttempts = 10, backoffMs = defaultBackoff, keepDoneMs = 7 * 24 * 60 * 60 * 1000, keepFailedMs = 90 * 24 * 60 * 60 * 1000, autoStart = true, } = options;
     let running = true;
     let loopPromise = null;
     let indexesReady = null;
@@ -46,15 +44,10 @@ export const startOutboxRelay = (options) => {
         if (!indexesReady) {
             const col = getOutboxCollection();
             indexesReady = (async () => {
-                await col.createIndex({ status: 1, nextAttemptAt: 1, leasedUntil: 1 });
+                await col.createIndex({ status: 1, nextAttemptAt: 1 });
                 // Retention is per row: markDone/markFailure set expireAt, so changing keepDoneMs
                 // needs no index change (createIndex can't alter expireAfterSeconds of an existing index).
                 await col.createIndex({ expireAt: 1 }, { expireAfterSeconds: 0 });
-                // v0.1.x expired done rows 7 days after processedOn, which would override keepDoneMs.
-                await col.dropIndex('processedOn_1').catch((err) => {
-                    if (err?.codeName !== 'IndexNotFound')
-                        throw err;
-                });
             })().catch((err) => {
                 // Don't cache a failure: the next tick tries again instead of failing forever.
                 indexesReady = null;
@@ -67,37 +60,18 @@ export const startOutboxRelay = (options) => {
         const col = getOutboxCollection();
         const now = new Date();
         const claimed = await col.findOneAndUpdate(claimFilter(now, getRegisteredCollections()), {
-            $set: {
-                status: OutboxStatus.Processing,
-                leasedBy: instanceId,
-                leasedUntil: new Date(now.getTime() + leaseMs),
-            },
+            $set: { leasedBy: instanceId, nextAttemptAt: new Date(now.getTime() + leaseMs) },
             $inc: { attempts: 1 },
         }, { sort: CLAIM_SORT, returnDocument: 'after' });
         return claimed ?? null;
     };
-    const dispatch = async (row) => {
-        const bus = getServiceBus(row.collectionName);
-        // claimFilter only matches registered collections, so this can't happen. Never mark such a row done.
-        if (!bus)
-            throw new Error(`No service registered for collection '${row.collectionName}'`);
-        const payload = {
-            prevDoc: row.prevDoc ?? undefined,
-            doc: row.doc,
-            meta: row.meta ?? undefined,
-            context: row.context ?? undefined,
-            eventId: row._id,
-        };
-        const listeners = bus.listeners(row.op);
-        await Promise.all(listeners.map(async (l) => l(payload)));
-    };
     /**
      * Writes a claimed row's outcome, but only while this claim still holds it. attempts goes up
      * on every claim, so a holder whose lease ran out (and whose row another instance reclaimed)
      * matches nothing instead of overwriting the newer claim's outcome.
      */
     const settle = async (row, set) => {
-        const { matchedCount } = await getOutboxCollection().updateOne({ _id: row._id, leasedBy: instanceId, attempts: row.attempts }, { $set: { ...set, leasedBy: null, leasedUntil: null } });
+        const { matchedCount } = await getOutboxCollection().updateOne({ _id: row._id, leasedBy: instanceId, attempts: row.attempts }, { $set: { ...set, leasedBy: null } });
         if (matchedCount === 0) {
             logger.warn(`Outbox row ${row._id} (${row.collectionName}/${row.op}) was reclaimed after its lease ran out. ` +
                 'Raise leaseMs above your slowest listener.');
@@ -122,8 +96,21 @@ export const startOutboxRelay = (options) => {
         }
     };
     const processRow = async (row) => {
+        // markFailure dead-letters at maxAttempts, so only claims whose lease ran out get past it: a
+        // listener that crashes the process or outlasts leaseMs. Dispatching again would repeat that.
+        if (row.attempts > maxAttempts) {
+            await markFailure(row, new Error(`lease of ${leaseMs}ms ran out on earlier attempts; not dispatched again`));
+            return;
+        }
         try {
-            await dispatch(row);
+            await dispatchEvent(row.collectionName, {
+                op: row.op,
+                eventId: row._id,
+                doc: row.doc,
+                prevDoc: row.prevDoc,
+                meta: row.meta,
+                context: row.context,
+            });
             await markDone(row);
         }
         catch (err) {
@@ -171,7 +158,9 @@ export const startOutboxRelay = (options) => {
         if (loopPromise)
             await loopPromise;
         try {
-            await getOutboxCollection().updateMany({ status: OutboxStatus.Processing, leasedBy: instanceId }, { $set: { status: OutboxStatus.Pending, leasedBy: null, leasedUntil: null } });
+            // A held row's nextAttemptAt is its lease end, still ahead: the condition keeps this off the due backlog.
+            const now = new Date();
+            await getOutboxCollection().updateMany({ status: OutboxStatus.Pending, nextAttemptAt: { $gt: now }, leasedBy: instanceId }, { $set: { leasedBy: null, nextAttemptAt: now } });
         }
         catch (err) {
             logger.error('Outbox relay failed to release leased rows on stop:', err);

package/dist/outboxRelay.js.map

@@ -1 +1 @@
-{"version":3,"file":"outboxRelay.js","sourceRoot":"","sources":["../src/outboxRelay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"outboxRelay.js","sourceRoot":"","sources":["../src/outboxRelay.ts"],"names":[],"mappings":"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"}

package/dist/types/outbox.d.ts

@@ -11,12 +11,24 @@ export declare enum OutboxOp {
     Updated = "updated",
     Removed = "removed"
 }
+/**
+ * A claimed row stays `pending`: the claim pushes `nextAttemptAt` past its lease, so a row whose
+ * holder died is due again through the same query that finds new rows.
+ */
 export declare enum OutboxStatus {
     Pending = "pending",
-    Processing = "processing",
     Done = "done",
     Failed = "failed"
 }
+/** What `dispatchEvent` delivers, and listeners receive. `eventId` is the outbox row's `_id`. */
+export interface OutboxEvent {
+    op: `${OutboxOp}`;
+    eventId: string;
+    doc: unknown;
+    prevDoc?: unknown;
+    meta?: Record<string, unknown> | null;
+    context?: unknown;
+}
 export interface OutboxRow<T = Record<string, unknown>> {
     _id: string;
     collectionName: string;
@@ -28,7 +40,6 @@ export interface OutboxRow<T = Record<string, unknown>> {
     status: OutboxStatus;
     attempts: number;
     nextAttemptAt: Date;
-    leasedUntil?: Date | null;
     leasedBy?: string | null;
     lastError?: string | null;
     createdOn: Date;

package/dist/types/outbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../src/types/outbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,oBAAY,QAAQ;IAClB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB;AAED,oBAAY,YAAY;IACtB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,QAAQ,CAAC;IACb,GAAG,EAAE,CAAC,CAAC;IACP,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,IAAI,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB"}
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../src/types/outbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,oBAAY,QAAQ;IAClB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,oBAAY,YAAY;IACtB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,GAAG,QAAQ,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,QAAQ,CAAC;IACb,GAAG,EAAE,CAAC,CAAC;IACP,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB"}

package/dist/types/outbox.js

@@ -12,10 +12,13 @@ export var OutboxOp;
     OutboxOp["Updated"] = "updated";
     OutboxOp["Removed"] = "removed";
 })(OutboxOp || (OutboxOp = {}));
+/**
+ * A claimed row stays `pending`: the claim pushes `nextAttemptAt` past its lease, so a row whose
+ * holder died is due again through the same query that finds new rows.
+ */
 export var OutboxStatus;
 (function (OutboxStatus) {
     OutboxStatus["Pending"] = "pending";
-    OutboxStatus["Processing"] = "processing";
     OutboxStatus["Done"] = "done";
     OutboxStatus["Failed"] = "failed";
 })(OutboxStatus || (OutboxStatus = {}));

package/dist/types/outbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../src/types/outbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAE1C,MAAM,CAAN,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,+BAAmB,CAAA;IACnB,+BAAmB,CAAA;IACnB,+BAAmB,CAAA;AACrB,CAAC,EAJW,QAAQ,KAAR,QAAQ,QAInB;AAED,MAAM,CAAN,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,yCAAyB,CAAA;IACzB,6BAAa,CAAA;IACb,iCAAiB,CAAA;AACnB,CAAC,EALW,YAAY,KAAZ,YAAY,QAKvB"}
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../src/types/outbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAE1C,MAAM,CAAN,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,+BAAmB,CAAA;IACnB,+BAAmB,CAAA;IACnB,+BAAmB,CAAA;AACrB,CAAC,EAJW,QAAQ,KAAR,QAAQ,QAInB;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,6BAAa,CAAA;IACb,iCAAiB,CAAA;AACnB,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB"}

package/docs/CLAUDE.md

@@ -49,13 +49,14 @@ Every `createService<T>(...)` call returns:
   is rejected**; use `upsertOne` for create-or-update, `insert` for explicit creates. Adds `updatedOn: new Date()` to the `$set`
   unless `addUpdatedOnField: false` was passed to `createService`. Enqueues an
   `'updated'` outbox row with `{ prevDoc, doc, meta }` for each document that
-  actually changed. `updateMany` always uses the reliable per-document path (see
-  "Events are delivered via a transactional outbox" below).
+  actually changed. For `updateMany`, see "How updateMany/removeMany work" below.
 - `removeOne(query, options?)` and `removeMany(query, options?)` — `removeMany`
   returns removed docs under `results` unless `{ returnRemoved: false }`. Enqueues
   a `'removed'` outbox row with `{ doc, meta }` for each removed document (no row
-  if nothing matched). `removeMany` always uses the reliable per-document path,
-  same as `updateMany`.
+  if nothing matched). For `removeMany`, see "How updateMany/removeMany work" below.
+- Write methods reject `projection` and `includeResultMetadata` (types omit them,
+  and they throw at runtime): validation and outbox events need the full
+  document. Read the fields you need with `find`/`findOne` afterwards.
 - `createIndex(fields, options?)` — `fields` is `IndexSpec<T>`: any top-level key of
   `T` or a dotted path into it (`'users._id'`), following arrays into their element
   type, mapped to `IndexDirection` (`1 | -1 | 'text' | 'hashed' | '2dsphere' | '2d'`).
@@ -65,12 +66,13 @@ Every `createService<T>(...)` call returns:
   having to enumerate that far.
 - `count`, `exists`, `aggregate`, `distinct`, `dropIndex`, `bulkWrite`
   (requires `{ allowBulkwrite: true }` — guards against accidental unvalidated writes).
-  `bulkWrite` does not enqueue outbox rows. `dropIndex(indexName, options?)` drops
+  `bulkWrite` writes no outbox rows, so it throws on a service that emits them.
+  `dropIndex(indexName, options?)` drops
   a single index by name (not by key spec) and does not enqueue outbox rows.
-- `on(event, cb)` / `onPropertiesUpdated(properties, cb)` — subscribe to the
-  service's own `eventBus` (a plain `node:events` `EventEmitter`). Listeners
-  registered here are dispatched to by `startOutboxRelay`, not by the write call
-  itself.
+- `on(event, cb)` / `onPropertiesUpdated(properties, cb)`: register a listener
+  for `'created' | 'updated' | 'removed'` on this collection. Returns a function
+  that removes it. Listeners are called by `startOutboxRelay` (or
+  `dispatchEvent`), not by the write call itself.
 - `withSession(cb)` / `startSession(options?)` — exported from the module (not
   per-service) for manual multi-document transactions across several services.
 - `disconnect()` — exported from the module; closes both MongoDB clients.
@@ -94,8 +96,9 @@ The contract is validator-agnostic — plug in Zod (`schema.safeParse(entity)`),
 directly — writing to the data collection can't be suppressed per-call, so for
 each document actually affected, one row is written to an internal `outbox`
 collection **in the same transaction** as the data write. A separate process,
-`startOutboxRelay({ instanceId, ... })`, claims pending rows (atomic leased
-`findOneAndUpdate`, safe across multiple pods) and dispatches each to whatever's
+`startOutboxRelay({ instanceId, ... })`, claims pending rows (an atomic
+`findOneAndUpdate` that pushes `nextAttemptAt` past a lease, safe across
+multiple pods) and dispatches each to whatever's
 registered via `.on(event, cb)` on that collection's service, retrying with
 backoff and dead-lettering after `maxAttempts`. This means delivery is durable —
 it survives a crash between the write committing and a listener running — and
@@ -108,10 +111,10 @@ const relay = startOutboxRelay({
   instanceId: process.env.HOSTNAME ?? 'local', // required — identifies this lease holder
   pollIntervalMs: 500,    // idle poll interval when the outbox is empty
   batchSize: 20,          // rows claimed+dispatched per tick
-  leaseMs: 30_000,        // how long a claim is held before another instance may reclaim it
+  leaseMs: 30_000,        // how long a claimed row stays hidden from other claims
   maxAttempts: 10,        // attempts before a row is dead-lettered to 'failed'
   keepDoneMs: 7 * 24 * 60 * 60 * 1000, // how long 'done' rows are kept; Infinity = forever
-  keepFailedMs: Infinity, // how long 'failed' rows are kept; default forever, for inspection/replay
+  keepFailedMs: 90 * 24 * 60 * 60 * 1000, // how long 'failed' rows are kept for inspection/replay; Infinity = forever
   // backoffMs: (attempt) => ms,  // override the default capped-exponential backoff
   // autoStart: false,            // don't start the poll loop — drive tick()/drain() manually (useful in tests)
 });
@@ -145,6 +148,16 @@ Set `{ emitOutboxEvents: false }` on `createService` for infra collections with
 no listeners (sequences, the outbox itself, etc.) — writes then take a leaner
 fast path with no pre-reads and no transaction-wrapped outbox insert.
 
+Set `{ toOutboxDoc: (doc) => ... }` on `createService` to decide what a
+collection's outbox rows hold of a document, `doc` and `prevDoc` alike. Rows
+reach every listener, and whatever those store (an audit log, a broker), so a
+secret in a row leaks there. `({ secret, ...hook }) => hook` leaves it out (a
+misspelled field is a type error), and an update that changes only that field
+records no row. To have the change show without the value, return a hash of it
+instead. The function must be pure and must not modify the document it gets. It
+also gets stored documents that were never validated against `T` (older ones,
+`skipValidation` writes), so handle a missing field: a throw fails the write.
+
 If a listener needs request/actor context (e.g. an audit log), register
 `setOutboxContextProvider(fn)` once at startup. It's called **synchronously at
 write time**, in the same transaction as the data write, and the captured value
@@ -169,11 +182,10 @@ await getOutboxCollection().updateOne(
 );
 ```
 
-`getServiceBus(collectionName)` and `getRegisteredCollections()` are the same
-internals the relay itself uses to route a row to its listeners — reach for
-them only if you're building custom tooling around the outbox (a dashboard, a
-manual replay script); normal listener registration is just `.on(...)` on the
-service.
+`getRegisteredCollections()` lists the collections with a service in this
+process (the ones the relay claims rows for). Reach for it only if you're
+building custom tooling around the outbox; normal listener registration is just
+`.on(...)` on the service.
 
 ### Multiple consumers
 
@@ -190,7 +202,10 @@ move is to bridge: run one relay whose only job is to republish each row to a
 message broker (Kafka, SNS, SQS, etc.), and let downstream services subscribe
 there. The outbox guarantees the write reaches the broker exactly once; the
 broker handles fan-out from there. That bridging code lives in your app — this
-package has no broker dependency by design.
+package has no broker dependency by design. On the consuming side, hand each
+received event to `dispatchEvent(collectionName, event)`: it calls the
+listeners registered via `.on(...)` exactly like the relay does (awaits all of
+them, rejects with the first failure so your consumer can retry).
 
 Until a second independent consumer appears, don't add the broker. Bundle the
 relay and all listeners in the same process.
@@ -198,41 +213,35 @@ relay and all listeners in the same process.
 ### Outbox row retention
 
 When a row is marked `done` or `failed`, the relay sets its `expireAt` from
-`keepDoneMs` (default **7 days**) or `keepFailedMs` (default: never), and a TTL
-index deletes it after that. MongoDB's TTL task runs every 60 seconds, so
-deletion isn't instant. Retention is stored per row, so changing it needs no
-index migration; it applies to rows settled from then on.
-
-By default `failed` rows are **never** auto-deleted. They accumulate until
-manually requeued or removed, so a steady stream of permanently-failing events
-will grow the outbox collection unbounded until someone looks at it. Set
-`keepFailedMs` to cap that. When requeuing a failed row by hand, clear
+`keepDoneMs` (default **7 days**) or `keepFailedMs` (default **90 days**), and a
+TTL index deletes it after that; `Infinity` keeps rows forever. MongoDB's TTL
+task runs every 60 seconds, so deletion isn't instant. Retention is stored per
+row, so changing it needs no index migration; it applies to rows settled from
+then on. A row no relay processes stays until one does. When requeuing a failed row by hand, clear
 `expireAt` (as in the snippet above), or the TTL index may delete it while it
 waits.
 
-Upgrading from v0.1.2 or earlier: the relay drops the old fixed 7-day TTL
-index on `processedOn` on startup.
-
-## updateMany/removeMany always use the reliable per-document path
+## How updateMany/removeMany work
 
-Unlike a single native bulk `updateMany`/`deleteMany` call, both methods process
-every matched document one at a time, sequentially (MongoDB doesn't allow
-concurrent operations on one session), inside a single transaction so the whole
-batch still rolls back together (data **and** outbox rows) on any failure. Every
-document is individually validated, and each outbox row's `{ prevDoc, doc }` pair
-comes from its own atomic `findOneAndUpdate`/`findOneAndDelete` — not a diff
-between two independent before/after scans, which could otherwise miss or
-misattribute documents if the matched set changed mid-operation.
+Both collect the matched `_id`s, then work through them in chunks of 500 inside a
+single transaction: per chunk, one read of the current documents, one native
+`updateMany`/`deleteMany` by `_id`, and (for `updateMany`) one read of the
+results, plus one outbox insert. A failure in any chunk rolls back every chunk,
+data **and** outbox rows. Every updated document is validated, and each outbox
+row's `{ prevDoc, doc }` pair is exact: once the transaction has read a document,
+any concurrent write to it makes the transaction fail with a transient write
+conflict, and the whole call is retried.
 
-This path has **no size cap by default** — pass `{ maxBatchSize }` (per-call, or
-as a `createService` option) to enforce one and fail fast; a single transaction
-processing a very large matched set risks hitting MongoDB's transaction lifetime
-limit (default 60s). Past that limit it throws — use `bulkWrite` for larger jobs
-(no transaction/validation/event guarantees, but no cap either).
+With `emitOutboxEvents: false`, `updateMany` still validates every document
+(skipping the `prevDoc` reads and outbox rows); only without a validator, or
+with `{ skipValidation: true }`, does it become one native `updateMany`.
 
-Internally this is powered by `src/batchify.ts` (sequential `concurrency: 1`,
-`throwOnError: true` so a per-document failure aborts the whole transaction) — an
-internal implementation detail, not exported from the package.
+There is **no size cap by default**. Pass `{ maxBatchSize }` (per-call, or as a
+`createService` option) to fail fast: a single transaction processing a very
+large matched set risks MongoDB's transaction lifetime limit (default 60s).
+Past the cap it throws before writing anything; it never processes a partial
+batch, so it can't be used to loop. For more than fits one transaction, split
+the work into several calls (see the README for a rerunnable migration loop).
 
 ## Transactions
 
@@ -265,42 +274,23 @@ Exceptions: `bulkWrite`, and `removeOne`/`removeMany` on a service with
   somewhere in the deployment.
 - **Two MongoDB clients per `connect()` call** (primary + secondary-preferred reader).
   `preferReadFromSecondary: true` only affects `find`/`findCursor`/`count`/`aggregate`.
-- **`bulkWrite` requires `{ allowBulkwrite: true }`** — there is no other safety net
-  (no schema validation runs on bulk writes).
-- **`updateOne`'s `prevDoc` can be stale** — and so can `updateMany`/`removeMany`'s
-  reliable path, since it reuses the exact same single-document logic
-  (`performSingleUpdate` in `db.ts`). To populate `{ prevDoc, doc }` on the outbox
-  row, the document is read with a separate `findOne` *before* running the atomic
-  `findOneAndUpdate` — a concurrent write landing in that gap means `prevDoc` may
-  not reflect the actual immediately-prior state. The atomic update itself is
-  unaffected (Mongo still applies it correctly); only the `prevDoc` value in the
-  outbox row can be stale. Treat `prevDoc` as best-effort, not authoritative, for
-  anything safety-critical.
-- **`emitOutboxEvents: false` (no-outbox) writes only validate one sampled
-  document on `updateMany`, not every updated document.** For `$set`-with-literal-values
-  updates this is representative (every matched doc lands on the same value for
-  the touched fields), but for operators whose result depends on a document's
-  prior value (`$inc`, `$mul`, `$min`, `$max`, `$push`/`$addToSet`, `$rename`,
-  positional array filters), the same update can be valid for the sampled
-  document and invalid for another — undetected on that fast path. The default
-  reliable path (`emitOutboxEvents: true`, the default) validates every document
-  individually and doesn't have this gap.
+- **`bulkWrite` requires `{ allowBulkwrite: true }`** and a service with
+  `emitOutboxEvents: false` — no schema validation runs on bulk writes, and no
+  outbox rows are written.
 - **Nothing dispatches outbox events unless a relay is running.** Outbox rows
   accumulate (durably, harmlessly) until some process calls `startOutboxRelay`.
   Make sure at least one instance in your deployment runs it, or `.on(...)`
   listeners will never fire.
-- **`createService` called twice for the same collection name reuses the first
-  call's `eventBus` (and logs a warning).** The registry mapping collection name
-  → `eventBus` is process-wide, so without this, a second call's fresh
-  `EventEmitter` would silently replace the first's, orphaning any listeners
-  already registered on it. Reuse means `.on(...)`/`onPropertiesUpdated(...)`
+- **`createService` called twice for the same collection name shares the first
+  call's listeners (and logs a warning).** Listeners are registered per
+  collection name, process-wide, so `.on(...)`/`onPropertiesUpdated(...)`
   registered on *either* instance still receive dispatched events — but other
   per-instance config is **not** shared, and a mismatch there is easy to miss
-  since the shared bus makes everything else look consistent:
+  since the shared listeners make everything else look consistent:
   - **`emitOutboxEvents`** — if one instance has it `false`, writes through
-    that instance never enqueue an outbox row, so listeners on the shared bus
-    silently never fire for those writes specifically (not a bus problem —
-    no event is generated at all). This can be an intentional choice (e.g. a
+    that instance never enqueue an outbox row, so the shared listeners
+    silently never fire for those writes specifically (no event is generated
+    at all). This can be an intentional choice (e.g. a
     backfill/migration instance skipping outbox writes on purpose), so it's
     not something `createService` should reject — just be deliberate about it.
   - **`validate`** — two instances can enforce different schemas on the same
@@ -310,10 +300,24 @@ Exceptions: `bulkWrite`, and `removeOne`/`removeMany` on a service with
   - **`addCreatedOnField`/`addUpdatedOnField`** — documents written through
     one instance may end up with `createdOn`/`updatedOn` and documents
     written through the other may not, for the same collection.
+  - **`toOutboxDoc`** — a field one instance keeps out of the outbox reaches
+    the shared listeners through the other. Give every instance the same one.
   Prefer creating each service once (e.g. in a shared module) and importing
   that instance everywhere it's used, unless one of the above divergences is
-  actually what you want. Because the bus is shared, `.eventBus
-  .removeAllListeners()` (or `.off(...)`/`.removeListener(...)`) called on
-  *either* instance also removes listeners registered via the *other*
-  instance — teardown code needs to account for that instead of assuming it
-  only touches its own listeners.
+  actually what you want.
+
+## Upgrading from 0.1
+
+`CHANGELOG.md` (shipped with the package) lists what changed in 0.2.0. One step
+has no place there: once no 0.1 relay runs any more, run this once per database.
+It requeues rows a 0.1 relay left in status `processing` (a relay of this version
+never claims them), and drops the indexes 0.1 created:
+
+```js
+db.outbox.updateMany({ status: 'processing' }, [
+  { $set: { status: 'pending', leasedBy: null, nextAttemptAt: { $ifNull: ['$leasedUntil', '$$NOW'] } } },
+  { $unset: 'leasedUntil' },
+]);
+db.outbox.dropIndex('status_1_nextAttemptAt_1_leasedUntil_1');
+db.outbox.dropIndex('processedOn_1'); // only if it still exists
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/mongo",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Typed MongoDB CRUD service factory with built-in transactions, event hooks, and optional document validation.",
@@ -23,7 +23,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs/CLAUDE.md"
+    "docs/CLAUDE.md",
+    "CHANGELOG.md"
   ],
   "sideEffects": false,
   "exports": {
@@ -40,6 +41,7 @@
     "mongodb": "^7.0.0"
   },
   "devDependencies": {
+    "@changesets/cli": "^3.0.3",
     "@eslint/js": "^10.0.1",
     "@faker-js/faker": "^10.1.0",
     "@types/lodash": "^4.17.21",
@@ -56,6 +58,7 @@
     "build": "tsc",
     "lint": "eslint .",
     "test": "vitest",
+    "changeset": "changeset",
     "release": "bash scripts/release.sh"
   }
 }

package/dist/batchify.d.ts

@@ -1,36 +0,0 @@
-interface BatchifyOptions<T> {
-    /**
-     * Returns the next batch of data, or an array containing all data (sliced into
-     * batches automatically). When a function: receives the requested batch size
-     * and the number of items already processed.
-     */
-    dataDelivery?: T[] | ((requestedBatchSize: number, alreadyProcessed: number) => T[] | Promise<T[]>);
-    /** Number of items fetched per `dataDelivery` call. Default 1000. */
-    batchSize?: number;
-    /**
-     * Number of items from the current batch processed concurrently. Defaults to
-     * `batchSize` (the whole batch at once). Set to `1` for strictly sequential
-     * processing — required when items share a MongoDB session/transaction, which
-     * doesn't allow concurrent operations.
-     */
-    concurrency?: number;
-    /** Function to run for each item. Receives the item and its global index. */
-    functionToRun?: (data: T, index: number) => void | Promise<void>;
-    /** Invoked after each batch completes, with the total number of items processed so far. */
-    onProgress?: (processedAmount: number) => void | Promise<void>;
-    /** Called when processing an item fails. Receives the failed item and the error. */
-    onError?: (entry: T, err: unknown) => void | Promise<void>;
-    /** If true, stop fetching further batches once any error has occurred. */
-    returnOnError?: boolean;
-    /**
-     * If true, rethrow the first error out of `batchify()` itself once the batch
-     * it occurred in has settled, instead of only invoking `onError`. Use this when
-     * the caller needs the failure to actually propagate (e.g. to abort a transaction).
-     */
-    throwOnError?: boolean;
-    /** Milliseconds to wait after completing each batch before starting the next. */
-    pauseAfterBatch?: number;
-}
-export declare function batchify<T>({ dataDelivery, batchSize, concurrency, functionToRun, onProgress, onError, returnOnError, throwOnError, pauseAfterBatch, }?: BatchifyOptions<T>): Promise<void>;
-export {};
-//# sourceMappingURL=batchify.d.ts.map

package/dist/batchify.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"batchify.d.ts","sourceRoot":"","sources":["../src/batchify.ts"],"names":[],"mappings":"AAAA,UAAU,eAAe,CAAC,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,kBAAkB,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpG,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,2FAA2F;IAC3F,UAAU,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,oFAAoF;IACpF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,EAChC,YAAuB,EACvB,SAAgB,EAChB,WAAW,EACX,aAA+B,EAC/B,UAA4B,EAC5B,OAAyB,EACzB,aAAqB,EACrB,YAAoB,EACpB,eAAmB,GACpB,GAAE,eAAe,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDzC"}