@ahrowe/mongo 0.0.1

package/dist/types/outbox.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Transactional outbox. Every mutation writes one row per affected document in
+ * the SAME Mongo transaction as the data write, so an event is persisted iff the
+ * mutation committed — it survives a pod death and is delivered after a restart.
+ * A restart-safe relay (see `../outboxRelay`) claims pending rows, dispatches
+ * them to in-process listeners (at-least-once), and marks them done.
+ */
+export declare const OUTBOX_COLLECTION = "outbox";
+export declare enum OutboxOp {
+    Created = "created",
+    Updated = "updated",
+    Removed = "removed"
+}
+export declare enum OutboxStatus {
+    Pending = "pending",
+    Processing = "processing",
+    Done = "done",
+    Failed = "failed"
+}
+export interface OutboxRow<T = Record<string, unknown>> {
+    _id: string;
+    collectionName: string;
+    op: OutboxOp;
+    doc: T;
+    prevDoc?: T | null;
+    meta?: Record<string, unknown> | null;
+    context?: unknown | null;
+    status: OutboxStatus;
+    attempts: number;
+    nextAttemptAt: Date;
+    leasedUntil?: Date | null;
+    leasedBy?: string | null;
+    lastError?: string | null;
+    createdOn: Date;
+    processedOn?: Date | null;
+}
+//# sourceMappingURL=outbox.d.ts.map

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

@@ -0,0 +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;CAC3B"}

package/dist/types/outbox.js

@@ -0,0 +1,22 @@
+/**
+ * Transactional outbox. Every mutation writes one row per affected document in
+ * the SAME Mongo transaction as the data write, so an event is persisted iff the
+ * mutation committed — it survives a pod death and is delivered after a restart.
+ * A restart-safe relay (see `../outboxRelay`) claims pending rows, dispatches
+ * them to in-process listeners (at-least-once), and marks them done.
+ */
+export const OUTBOX_COLLECTION = 'outbox';
+export var OutboxOp;
+(function (OutboxOp) {
+    OutboxOp["Created"] = "created";
+    OutboxOp["Updated"] = "updated";
+    OutboxOp["Removed"] = "removed";
+})(OutboxOp || (OutboxOp = {}));
+export var OutboxStatus;
+(function (OutboxStatus) {
+    OutboxStatus["Pending"] = "pending";
+    OutboxStatus["Processing"] = "processing";
+    OutboxStatus["Done"] = "done";
+    OutboxStatus["Failed"] = "failed";
+})(OutboxStatus || (OutboxStatus = {}));
+//# sourceMappingURL=outbox.js.map

package/dist/types/outbox.js.map

@@ -0,0 +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"}

package/docs/CLAUDE.md

@@ -0,0 +1,250 @@
+# @ahrowe/mongo — agent guide
+
+Typed MongoDB CRUD service factory. `connect()` once, then `createService<T>(collectionName, validate?, options?)`
+gives you a typed wrapper with transactions, a transactional-outbox-backed event
+system (`created`/`updated`/`removed`), and optional document validation on
+insert/update.
+
+ESM-only (`"type": "module"`). Single entry point: `@ahrowe/mongo`.
+
+## Setup
+
+```ts
+import db from '@ahrowe/mongo';
+
+const { createService, on } = db.connect(process.env.MONGO_DB_URI!, 'myDb');
+
+type User = { _id: string; email: string; createdOn?: Date; updatedOn?: Date };
+const users = createService<User>('users');
+```
+
+`connect()` is idempotent — calling it again returns the same `{ createService, on }`
+bound to the already-open connection. It opens **two** clients: a primary and a
+secondary-preferred read client (`preferReadFromSecondary` option on `find`/`findCursor`/
+`count`/`aggregate` routes reads to the latter). Both clients have internal
+`error`/`close` handlers wired up (so a connection issue can't crash the process)
+and re-emit on a connection-level bus: `on('error', ({ source, error }) => ...)` /
+`on('close', ({ source, error }) => ...)`, `source` being `'primary'` or `'read'`.
+
+## Service API
+
+Every `createService<T>(...)` call returns:
+
+- `find(query, options?)`, `findOne(query, options?)`, `findCursor(query, options?)` —
+  reads; `findCursor` enforces no `limit` cap by default — pass `{ maxLimit }`
+  (per-call, or as a `createService` option for a service-wide default) to enforce
+  one. `findOne` throws if more than one document matches.
+- `insert(doc | doc[], options?)` — generates `_id` and `createdOn` if not supplied;
+  runs the schema validator (if any) unless `{ skipValidation: true }`; wraps in a
+  transaction unless `{ session }` is passed. Enqueues a `'created'` outbox row
+  (in the same transaction as the write) for each inserted document.
+- `updateOne(query, updateBody, options?)` and `updateMany(...)` — **`upsert` is
+  rejected**; use `insert` instead. 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).
+- `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`.
+- `count`, `exists`, `aggregate`, `distinct`, `createIndex`, `bulkWrite` (requires
+  `{ allowBulkwrite: true }` — guards against accidental unvalidated writes).
+  `bulkWrite` 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.
+- `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.
+  Outbox rows already committed are durable in MongoDB regardless. If you run
+  `startOutboxRelay` in-process, call `relay.stop()` first so it releases any
+  leases it's holding.
+
+## Validation
+
+`createService(name, validate, options)`'s `validate` is `(entity: T) => { error?: unknown }`.
+It's invoked on every insert and on the post-update document; if `error` is set on
+the result, that value is thrown as-is (no formatting or wrapping). Pass
+`{ skipValidation: true }` per-call to bypass it (e.g. for known-good system writes).
+
+The contract is validator-agnostic — plug in Zod (`schema.safeParse(entity)`), Joi
+(`schema.validate(entity)`), a plain TS guard, or nothing (`validate: null`).
+
+## Events are delivered via a transactional outbox
+
+`insert`/`updateOne`/`updateMany`/`removeOne`/`removeMany` don't dispatch events
+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
+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
+at-least-once, so listeners must be idempotent.
+
+```ts
+import { startOutboxRelay } from '@ahrowe/mongo';
+
+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
+  maxAttempts: 10,        // attempts before a row is dead-lettered to 'failed'
+  // backoffMs: (attempt) => ms,  // override the default capped-exponential backoff
+  // autoStart: false,            // don't start the poll loop — drive tick()/drain() manually (useful in tests)
+});
+// relay.stop() on shutdown
+```
+
+Run exactly one (or more — it's safe across multiple pods) relay per
+deployment that needs events delivered; nothing dispatches them otherwise.
+
+Each listener receives `{ prevDoc, doc, meta, context, eventId }` — not just
+`{ prevDoc, doc, meta }`. `eventId` is the outbox row's `_id`, stable across
+retries of the same row; since delivery is **at-least-once**, use it as an
+idempotency key if your listener's side effect can't safely run twice (e.g.
+upsert a "processed event ids" record, or make the side effect itself
+idempotent on `eventId`).
+
+Pass `{ meta: {...} }` on the triggering call to thread arbitrary data through to
+listeners on that event (e.g. a flag a specific handler checks to skip its own
+side effect, without other listeners missing the event).
+
+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.
+
+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
+is stored on the outbox row's `context` field — available to your listener even
+after a process restart, unlike a live `AsyncLocalStorage` read (which would not
+survive the relay dispatching asynchronously, possibly from a different process).
+
+### Inspecting and recovering dead-lettered rows
+
+A row that keeps failing past `maxAttempts` is marked `OutboxStatus.Failed` and
+the relay stops retrying it automatically — it's left for manual inspection.
+There's no built-in tooling for this; query/replay it directly:
+
+```ts
+import { getOutboxCollection, OutboxStatus } from '@ahrowe/mongo';
+
+const failed = await getOutboxCollection().find({ status: OutboxStatus.Failed }).toArray();
+// inspect failed[i].lastError, fix the underlying issue, then requeue:
+await getOutboxCollection().updateOne(
+  { _id: failed[0]._id },
+  { $set: { status: OutboxStatus.Pending, nextAttemptAt: new Date(), attempts: 0, lastError: null } },
+);
+```
+
+`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.
+
+### Multiple consumers
+
+The relay uses **competing-consumer** claiming: each outbox row is claimed
+atomically by exactly one relay instance, dispatched to all `.on(...)` listeners
+registered in **that process**, then marked done. This is the right model when
+all consumers run in the same process (e.g. `@ahrowe/audit-log` bundled into
+the main app alongside the relay) — `.on(...)` from multiple packages in the
+same process all fire for every row.
+
+It is **not** pub/sub broadcast across separately-deployed services. If a second
+independent consumer service ever needs to receive the same events, the standard
+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.
+
+Until a second independent consumer appears, don't add the broker. Bundle the
+relay and all listeners in the same process.
+
+### Outbox row retention
+
+The relay creates a TTL index that drops `done` (successfully processed) rows
+**7 days** after `processedOn` is set. `failed` rows keep `processedOn: null`
+and 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.
+
+## updateMany/removeMany always use the reliable per-document path
+
+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.
+
+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).
+
+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.
+
+## Transactions
+
+`insert`/`updateOne`/`updateMany` each wrap themselves in a transaction automatically
+when no `{ session }` is given (via `client.withSession` + `session.withTransaction`).
+Pass an explicit `session` (from `startSession()` or `withSession()`) to compose
+multiple service calls — even across different `createService(...)` instances/collections
+— into one atomic transaction.
+
+## Gotchas (read before integrating)
+
+- **No upserts.** `updateOne`/`updateMany` throw if `options.upsert` is set — this is
+  intentional; call `insert` for the create path.
+- **`findOne` is strict.** It throws (not silently returns the first match) if the
+  query matches more than one document.
+- **`findCursor`/`find` have no `limit` cap by default.** Pass `{ maxLimit }`
+  (per-call or via `createService`) to enforce one — a higher `limit` then throws
+  synchronously.
+- **Event delivery is asynchronous and decoupled from the write call** — the
+  caller of `insert`/`updateOne`/etc. never sees a listener's error or knows
+  when (or whether yet) a listener has run; only the outbox row's commit is
+  awaited. A throwing/rejecting listener doesn't crash the relay — that row is
+  retried with backoff and dead-lettered after `maxAttempts`. Nothing dispatches
+  events unless an outbox relay (`startOutboxRelay`) is actually running
+  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.
+- **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.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ahrowe/mongo",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "Typed MongoDB CRUD service factory with built-in transactions, event hooks, and optional document validation.",
+  "keywords": [
+    "mongodb",
+    "mongo",
+    "crud",
+    "transactions"
+  ],
+  "author": "AndreasWeinzierl",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndreasWeinzierl/ahrowe-mongo"
+  },
+  "bugs": {
+    "url": "https://github.com/AndreasWeinzierl/ahrowe-mongo/issues"
+  },
+  "homepage": "https://github.com/AndreasWeinzierl/ahrowe-mongo#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs/CLAUDE.md"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "mongodb": "^7.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@faker-js/faker": "^10.1.0",
+    "@types/lodash": "^4.17.21",
+    "@types/node": "^24.13.2",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
+    "testcontainers": "^11.9.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc",
+    "lint": "eslint .",
+    "test": "vitest",
+    "release": "bash scripts/release.sh"
+  }
+}