@toa.io/storages.mongodb 1.0.0-alpha.298 → 1.0.0-alpha.299

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.299](https://github.com/toa-io/toa/compare/v1.0.0-alpha.298...v1.0.0-alpha.299) (2026-09-10)
+
+### Features
+
+* **core:** a record carries the region that wrote it ([13ed187](https://github.com/toa-io/toa/commit/13ed187604f06dec66feec2e26ccf9dae30bb048))
+* **core:** an outbox row is published to destinations ([cfb77b4](https://github.com/toa-io/toa/commit/cfb77b4826ff0f9560769a0996981e143d6525af))
+
+
 # [1.0.0-alpha.298](https://github.com/toa-io/toa/compare/v1.0.0-alpha.297...v1.0.0-alpha.298) (2026-09-08)
 
 **Note:** Version bump only for package @toa.io/storages.mongodb

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/storages.mongodb",
-  "version": "1.0.0-alpha.298",
+  "version": "1.0.0-alpha.299",
   "type": "module",
   "description": "Toa MongoDB Storage Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,12 +21,12 @@
   },
   "dependencies": {
     "@toa.io/conveyor": "1.0.0-alpha.292",
-    "@toa.io/core": "1.0.0-alpha.293",
-    "@toa.io/definitions": "1.0.0-alpha.298",
+    "@toa.io/core": "1.0.0-alpha.299",
+    "@toa.io/definitions": "1.0.0-alpha.299",
     "@toa.io/generic": "1.0.0-alpha.292",
-    "@toa.io/pointer": "1.0.0-alpha.293",
+    "@toa.io/pointer": "1.0.0-alpha.299",
     "mongodb": "7.6.0",
     "openspan": "1.0.0-alpha.293"
   },
-  "gitHead": "334fad8726adfa7507462c33b509ce7db9db853f"
+  "gitHead": "2ba95b16f2cf06f82d6ff8d436761e843e5e4b43"
 }

package/src/outbox.js

@@ -53,16 +53,36 @@ export class Outbox {
   }
 
   /**
-   * One batched write for many events, which is why the ids are held in memory until the
-   * tick rather than updated one by one.
+   * Takes those destinations out of what those rows are outstanding for, and marks published
+   * the ones left outstanding for nothing — which is what `pending` selects on and what the
+   * TTL reaps by, so neither changes.
+   *
+   * One batched write for many rows, which is why the ids are held in memory until the tick
+   * rather than updated one by one. A row written before this property existed reads as
+   * outstanding for `events` alone, which is all there was.
    */
-  async settle(ids) {
+  async settle(ids, destinations) {
     if (ids.length === 0) return
 
-    await this.#collection.updateMany(
-      { _id: { $in: ids } },
-      { $set: { published: true, publishedAt: new Date() } }
-    )
+    await this.#collection.updateMany({ _id: { $in: ids } }, [
+      {
+        $set: {
+          outstanding: {
+            $setDifference: [{ $ifNull: ['$outstanding', [EVENTS]] }, destinations]
+          }
+        }
+      },
+      {
+        $set: {
+          published: { $eq: [{ $size: '$outstanding' }, 0] },
+          // written once, when the last destination lands: an unpublished row has none, and
+          // the TTL monitor skips a document that lacks the field it expires by
+          publishedAt: {
+            $cond: [{ $eq: [{ $size: '$outstanding' }, 0] }, '$$NOW', '$publishedAt']
+          }
+        }
+      }
+    ])
   }
 
   /**
@@ -158,7 +178,10 @@ export class Outbox {
 }
 
 const to = ({ id, ...rest }) => ({ _id: id, ...rest })
-const from = ({ _id, ...rest }) => ({ id: _id, ...rest })
+
+// a row written before destinations existed is outstanding for the events, which is all a row
+// was ever published to then
+const from = ({ _id, ...rest }) => ({ id: _id, outstanding: [EVENTS], ...rest })
 
 function retention() {
   const value = Number(environment.get('TOA_OUTBOX_RETENTION'))
@@ -166,6 +189,9 @@ function retention() {
   return Number.isNaN(value) || value < 0 ? RETENTION : value
 }
 
+/** what a component's own events are outstanding for; `Emission.name` */
+const EVENTS = 'events'
+
 /** seconds a published row is kept as a change log before the TTL monitor reaps it */
 const RETENTION = 86400
 

package/src/storage.js

@@ -65,6 +65,11 @@ export class Storage extends Connector {
     return true
   }
 
+  /** This storage converges. */
+  get converges() {
+    return true
+  }
+
   async open() {
     this.#collection = this.#client.collection
 
@@ -255,6 +260,52 @@ export class Storage extends Connector {
     }
   }
 
+  /**
+   * The filter selects by `_id` alone, so it always matches what is there and upserts what is
+   * not, and the rule is the pipeline: either the incoming document replaces the stored one, or
+   * `$$ROOT` stays where it is and nothing changes. That keeps the three answers apart — a
+   * record never seen is an upsert, a superseded one is a modification, and a stale one is
+   * neither — where putting the rule in the filter would make absence and staleness one and the
+   * same miss, and then have the upsert collide on `_id` to say so.
+   *
+   * `$literal` because a value in a pipeline is an expression, so a property holding a string
+   * that begins with `$` would otherwise be read as a field path.
+   *
+   * `$ifNull` twice, and for two reasons. On the upsert path the pipeline runs over the base
+   * document the filter builds, which is `{ _id }`, so a missing `VERSION` reads as `0` — the
+   * version an entity holds before its first write. And a record that somehow reached here
+   * without a `REGION` reads as the first region, which is what the prototype's migration
+   * writes into one: without that, such a record would lose no tie and would beat every
+   * equal-version write from anywhere, silently and for good.
+   */
+  async converge(record) {
+    const document = this.#to(record)
+
+    const supersedes = {
+      $or: [
+        { $lt: [{ $ifNull: ['$VERSION', 0] }, document.VERSION] },
+        {
+          $and: [
+            { $eq: ['$VERSION', document.VERSION] },
+            { $gt: [{ $ifNull: ['$REGION', FIRST] }, document.REGION] }
+          ]
+        }
+      ]
+    }
+
+    const pipeline = [
+      { $replaceWith: { $cond: [supersedes, { $literal: document }, '$$ROOT'] } }
+    ]
+
+    const result = await this.command(
+      'updateOne',
+      { criteria: { _id: document._id }, pipeline },
+      () => this.#collection.updateOne({ _id: document._id }, pipeline, { upsert: true })
+    )
+
+    return result.upsertedCount === 1 || result.modifiedCount === 1
+  }
+
   async upsert(query, changeset, row = undefined) {
     const { criteria, options } = translate(query, this.#dates)
 
@@ -415,6 +466,9 @@ function toPipeline(criteria, options, sample) {
   return pipeline
 }
 
+/** the rank of the first region, which is what a record written before regions reads as */
+const FIRST = 0
+
 const ERR_DUPLICATE_KEY = 11000
 
 async function retriable(error, attempt) {

package/test/storage.test.js

@@ -13,7 +13,8 @@ beforeEach(async () => {
     collectionName: 'test',
     findOne: mock.fn(async () => null),
     find: mock.fn(() => ({ stream: () => null })),
-    updateMany: mock.fn(async () => ({ modifiedCount: 0 }))
+    updateMany: mock.fn(async () => ({ modifiedCount: 0 })),
+    updateOne: mock.fn(async () => ({ upsertedCount: 0, modifiedCount: 0 }))
   }
 
   db = { collection: mock.fn(() => null) }
@@ -127,3 +128,90 @@ describe('stream', () => {
     )
   })
 })
+
+describe('converge', () => {
+  const record = { id: 'a1', VERSION: 4, REGION: 1, status: 'paid' }
+
+  const call = () => collection.updateOne.mock.calls[0].arguments
+
+  it('should select by id alone, so that what is absent is upserted', async () => {
+    await storage.converge(record)
+
+    const [criteria, , options] = call()
+
+    assert.deepEqual(criteria, { _id: 'a1' })
+    assert.equal(options.upsert, true)
+  })
+
+  it('should supersede a lower version', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+    const [older] = pipeline[0].$replaceWith.$cond[0].$or
+
+    assert.deepEqual(older, { $lt: [{ $ifNull: ['$VERSION', 0] }, 4] })
+  })
+
+  it('should supersede an equal version written by an outranked region', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+    const [, tied] = pipeline[0].$replaceWith.$cond[0].$or
+
+    assert.deepEqual(tied.$and, [
+      { $eq: ['$VERSION', 4] },
+      { $gt: [{ $ifNull: ['$REGION', 0] }, 1] }
+    ])
+  })
+
+  it('should leave what is stored where it does not', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+
+    assert.equal(pipeline[0].$replaceWith.$cond[2], '$$ROOT')
+  })
+
+  it('should write the record as a literal, so that a `$` value is not a field path', async () => {
+    await storage.converge({ ...record, status: '$paid' })
+
+    const [, pipeline] = call()
+    const written = pipeline[0].$replaceWith.$cond[1].$literal
+
+    assert.equal(written._id, 'a1')
+    assert.equal(written.status, '$paid')
+    assert.equal(written.id, undefined)
+  })
+
+  it('should answer true where it inserted', async () => {
+    collection.updateOne.mock.mockImplementationOnce(async () => ({
+      upsertedCount: 1,
+      modifiedCount: 0
+    }))
+
+    assert.equal(await storage.converge(record), true)
+  })
+
+  it('should answer true where it superseded', async () => {
+    collection.updateOne.mock.mockImplementationOnce(async () => ({
+      upsertedCount: 0,
+      modifiedCount: 1
+    }))
+
+    assert.equal(await storage.converge(record), true)
+  })
+
+  it('should read a record that lacks a region as the first one', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+    const [, tied] = pipeline[0].$replaceWith.$cond[0].$or
+
+    // the migration writes it, and one that reached here without it would win every tie
+    assert.deepEqual(tied.$and[1].$gt[0], { $ifNull: ['$REGION', 0] })
+  })
+
+  it('should answer false where it changed nothing, and not throw', async () => {
+    assert.equal(await storage.converge(record), false)
+  })
+})