@toa.io/storages.mongodb 1.0.0-alpha.331 → 1.0.0-alpha.333

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.333](https://github.com/toa-io/toa/compare/v1.0.0-alpha.332...v1.0.0-alpha.333) (2026-10-26)
+
+### Bug Fixes
+
+* **storages.mongodb:** run a set again where it met a commit in flight ([2e293fe](https://github.com/toa-io/toa/commit/2e293fe1b72c3eac65f659f0061e312945829b6e))
+
+
+# [1.0.0-alpha.332](https://github.com/toa-io/toa/compare/v1.0.0-alpha.331...v1.0.0-alpha.332) (2026-10-23)
+
+### Bug Fixes
+
+* **storages.mongodb:** commit a set where the URL sets timeoutMS ([0b51f02](https://github.com/toa-io/toa/commit/0b51f0281de218dbcb677b75d6dd58685c4e2958))
+
+
 # [1.0.0-alpha.331](https://github.com/toa-io/toa/compare/v1.0.0-alpha.330...v1.0.0-alpha.331) (2026-10-16)
 
 **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.331",
+  "version": "1.0.0-alpha.333",
   "type": "module",
   "description": "Toa MongoDB Storage Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -20,13 +20,13 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/conveyor": "1.0.0-alpha.330",
-    "@toa.io/core": "1.0.0-alpha.330",
-    "@toa.io/definitions": "1.0.0-alpha.331",
-    "@toa.io/generic": "1.0.0-alpha.330",
-    "@toa.io/pointer": "1.0.0-alpha.330",
+    "@toa.io/conveyor": "1.0.0-alpha.332",
+    "@toa.io/core": "1.0.0-alpha.333",
+    "@toa.io/definitions": "1.0.0-alpha.333",
+    "@toa.io/generic": "1.0.0-alpha.332",
+    "@toa.io/pointer": "1.0.0-alpha.332",
     "mongodb": "7.7.0",
     "openspan": "1.0.0-alpha.330"
   },
-  "gitHead": "e7020d160910ca4f0c2ff9040b3cbb4fca8ea41f"
+  "gitHead": "ddb74b2f99026fae540a8a8e0a49c26cbd22886a"
 }

package/readme.md

@@ -1,5 +1,10 @@
 # MongoDB Storage
 
+## Server
+
+MongoDB 8.0 or later. An earlier server refuses a `transition` of scope `entries`
+([Operations](/documentation/component/declaration.md#operations)).
+
 ## Tracing
 
 Commands are recorded as `client` spans within the trace of the current invocation.

package/src/bulk.js

@@ -0,0 +1,26 @@
+import { MongoClientBulkWriteError, MongoServerError } from 'mongodb'
+
+/**
+ * The client's bulk write, where a command the server refused is thrown as the server sent it.
+ *
+ * The driver wraps that refusal in an error that carries none of its labels, and a transaction
+ * runs again only what is labelled as worth running again: a write conflict with a commit in
+ * flight would end the transaction as a failure of its own. A write the server refused one by
+ * one is left as it is, read off `writeErrors`.
+ *
+ * @param {import('mongodb').MongoClient} client
+ * @param {import('mongodb').AnyClientBulkWriteModel[]} operations
+ * @param {import('mongodb').ClientBulkWriteOptions} options
+ */
+export async function bulkWrite(client, operations, options) {
+  try {
+    return await client.bulkWrite(operations, options)
+  } catch (error) {
+    if (
+      error instanceof MongoClientBulkWriteError &&
+      error.cause instanceof MongoServerError
+    )
+      throw error.cause
+    else throw error
+  }
+}

package/src/outbox.js

@@ -1,5 +1,6 @@
 import { environment } from '@toa.io/generic'
 import { index, prune } from './indexes.js'
+import { bulkWrite } from './bulk.js'
 
 /**
  * The outbox rows of one component. Its lifecycle is the Client's, so it is not a Connector.
@@ -27,7 +28,14 @@ export class Outbox {
   async insertMany(rows, session) {
     if (rows.length === 0) return
 
-    await this.#collection.insertMany(rows.map(to), { session })
+    const namespace = this.#collection.namespace
+
+    // the client's bulk write, not `insertMany`: see `massStore` in ./storage.js
+    await bulkWrite(
+      this.#collection.client,
+      rows.map((row) => ({ name: 'insertOne', namespace, document: to(row) })),
+      { session }
+    )
   }
 
   /**

package/src/storage.js

@@ -4,6 +4,7 @@ import { translate } from './translate.js'
 import { codec } from './record.js'
 import { Inbox } from './inbox.js'
 import { Outbox } from './outbox.js'
+import { bulkWrite } from './bulk.js'
 import { Migrations } from './migrations.js'
 import { Streams } from './streams.js'
 import { conflicted, query } from './measurements.js'
@@ -287,33 +288,35 @@ export class Storage extends Connector {
   async massStore(entities, rows = undefined, attempt = 0) {
     if (entities.length === 0) return true
 
+    const namespace = this.#collection.namespace
+
     const operations = entities.map((entity) => {
       const record = this.#to(entity)
 
       if (entity.VERSION === 1) {
         const { VERSION, ...rest } = record
 
+        // one the read did not find: absent, and inserted, or deleted, and revived — a live
+        // one makes the upsert collide on `_id`, which is the swap lost
         return {
-          // one the read did not find: absent, and inserted, or deleted, and revived — a live
-          // one makes the upsert collide on `_id`, which is the swap lost
-          updateOne: {
-            filter: { _id: entity.id, DELETED: { $ne: null } },
-            update: {
-              $set: {
-                ...rest,
-                DELETED: null
-              },
-              $inc: { VERSION: 1 }
+          name: 'updateOne',
+          namespace,
+          filter: { _id: entity.id, DELETED: { $ne: null } },
+          update: {
+            $set: {
+              ...rest,
+              DELETED: null
             },
-            upsert: true
-          }
+            $inc: { VERSION: 1 }
+          },
+          upsert: true
         }
       } else
         return {
-          replaceOne: {
-            filter: { _id: entity.id, VERSION: entity.VERSION - 1 },
-            replacement: record
-          }
+          name: 'replaceOne',
+          namespace,
+          filter: { _id: entity.id, VERSION: entity.VERSION - 1 },
+          replacement: record
         }
     })
 
@@ -327,10 +330,13 @@ export class Storage extends Connector {
           result = await this.command(
             'bulkWrite',
             { operations: operations.length },
-            async () => await this.#collection.bulkWrite(operations, { session })
+            // the client's bulk write, not the collection's: the latter takes a `timeoutMS` the
+            // URL sets for one the call passed, and refuses it inside a transaction that has
+            // its own
+            async () => await bulkWrite(this.#collection.client, operations, { session })
           )
         } catch (error) {
-          if (!collidedOnId(error)) throw error
+          if (!collidedOnId(firstWriteError(error))) throw error
 
           await session.abortTransaction()
 
@@ -353,7 +359,7 @@ export class Storage extends Connector {
     } catch (error) {
       console.error('MongoDB error', error)
 
-      const retry = await retriable(error, attempt)
+      const retry = await retriable(firstWriteError(error), attempt)
 
       if (retry) return await this.massStore(entities, rows, attempt + 1)
       else return false
@@ -608,6 +614,13 @@ const ERR_DUPLICATE_KEY = 11000
 /** what the transaction answers where the call it carries has already been made */
 const MADE = Symbol('made')
 
+/** What an ordered bulk write stopped at, or the error itself where no write failed. */
+function firstWriteError(error) {
+  return error?.writeErrors instanceof Map && error.writeErrors.size > 0
+    ? error.writeErrors.values().next().value
+    : error
+}
+
 /** whether the key a write collided on is `_id` */
 function collidedOnId(error) {
   if (error?.code !== ERR_DUPLICATE_KEY) return false

package/test/bulk.test.js

@@ -0,0 +1,49 @@
+import { describe, it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { MongoClientBulkWriteError, MongoServerError } from 'mongodb'
+
+import { bulkWrite } from '../src/bulk.js'
+
+describe('bulkWrite', () => {
+  it('should throw what the server refused the command with, labels and all', async () => {
+    const conflict = new MongoServerError({
+      message: 'Write conflict during plan execution and yielding is disabled.',
+      code: 112,
+      errorLabels: ['TransientTransactionError']
+    })
+
+    const wrapped = new MongoClientBulkWriteError({
+      message: 'Mongo client bulk write encountered an error during execution'
+    })
+
+    wrapped.cause = conflict
+
+    const client = { bulkWrite: mock.fn(async () => Promise.reject(wrapped)) }
+
+    await assert.rejects(bulkWrite(client, [], {}), (error) => {
+      assert.equal(error, conflict)
+      assert.equal(error.hasErrorLabel('TransientTransactionError'), true)
+
+      return true
+    })
+  })
+
+  it('should throw what refused a write one by one as it is', async () => {
+    const refused = new MongoClientBulkWriteError({
+      message: 'Mongo client bulk write encountered errors during execution'
+    })
+
+    refused.writeErrors.set(0, { code: 11000, message: 'E11000 duplicate key error' })
+
+    const client = { bulkWrite: mock.fn(async () => Promise.reject(refused)) }
+
+    await assert.rejects(bulkWrite(client, [], {}), (error) => error === refused)
+  })
+
+  it('should answer what the client answers', async () => {
+    const result = { matchedCount: 1, upsertedCount: 0 }
+    const client = { bulkWrite: mock.fn(async () => result) }
+
+    assert.equal(await bulkWrite(client, [], {}), result)
+  })
+})

package/test/storage.test.js

@@ -12,6 +12,8 @@ let storage
 beforeEach(async () => {
   collection = {
     collectionName: 'test',
+    namespace: 'db.test',
+    client: {},
     findOne: mock.fn(async () => null),
     find: mock.fn(() => cursor()),
     updateMany: mock.fn(async () => ({ modifiedCount: 0 })),
@@ -270,10 +272,10 @@ describe('massStore', () => {
   const stored = { id: 'a1', VERSION: 3, foo: 1 }
   const created = { id: 'b2', VERSION: 1, foo: 1 }
 
-  const operations = () => collection.bulkWrite.mock.calls[0].arguments[0]
+  const operations = () => collection.client.bulkWrite.mock.calls[0].arguments[0]
 
   beforeEach(() => {
-    collection.bulkWrite = mock.fn(async (operations) => ({
+    collection.client.bulkWrite = mock.fn(async (operations) => ({
       matchedCount: operations.length,
       upsertedCount: 0
     }))
@@ -282,14 +284,19 @@ describe('massStore', () => {
   it('should replace a record only at the version it was read at', async () => {
     await storage.massStore([stored])
 
-    assert.deepEqual(operations()[0].replaceOne.filter, { _id: 'a1', VERSION: 2 })
+    const { name, namespace, filter } = operations()[0]
+
+    assert.equal(name, 'replaceOne')
+    assert.equal(namespace, 'db.test')
+    assert.deepEqual(filter, { _id: 'a1', VERSION: 2 })
   })
 
   it('should create a record only where none but a deleted one holds its id', async () => {
     await storage.massStore([created])
 
-    const { filter, upsert } = operations()[0].updateOne
+    const { name, filter, upsert } = operations()[0]
 
+    assert.equal(name, 'updateOne')
     assert.deepEqual(filter, { _id: 'b2', DELETED: { $ne: null } })
     assert.equal(upsert, true)
   })
@@ -300,20 +307,48 @@ describe('massStore', () => {
   })
 
   it('should abort and answer false where a record was not matched', async () => {
-    collection.bulkWrite = mock.fn(async () => ({ matchedCount: 1, upsertedCount: 0 }))
+    collection.client.bulkWrite = mock.fn(async () => ({
+      matchedCount: 1,
+      upsertedCount: 0
+    }))
 
     assert.equal(await storage.massStore([stored, { ...stored, id: 'c3' }]), false)
     assert.equal(session.abortTransaction.mock.callCount(), 1)
   })
 
   it('should abort and answer false where a record being created exists', async () => {
-    collection.bulkWrite = mock.fn(async () => {
-      throw Object.assign(new Error('E11000 duplicate key error index: _id_ dup key'), {
-        code: 11000
+    collection.client.bulkWrite = mock.fn(async () => {
+      const collision = Object.assign(
+        new Error('E11000 duplicate key error index: _id_ dup key'),
+        {
+          code: 11000
+        }
+      )
+
+      throw Object.assign(new Error('ordered bulk write encountered a write error'), {
+        writeErrors: new Map([[0, collision]])
       })
     })
 
     assert.equal(await storage.massStore([created]), false)
     assert.equal(session.abortTransaction.mock.callCount(), 1)
   })
+
+  it('should throw a duplicate where a record collides on a key other than its id', async () => {
+    collection.client.bulkWrite = mock.fn(async () => {
+      const collision = Object.assign(
+        new Error('E11000 duplicate key error index: foo_1'),
+        {
+          code: 11000,
+          keyPattern: { foo: 1 }
+        }
+      )
+
+      throw Object.assign(new Error('ordered bulk write encountered a write error'), {
+        writeErrors: new Map([[0, collision]])
+      })
+    })
+
+    await assert.rejects(storage.massStore([created]), { code: 306 })
+  })
 })