@toa.io/storages.mongodb 1.0.0-alpha.27 → 1.0.0-alpha.272

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Change Log
+
+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.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
+
+
+* refactor(core)!: pump the outbox in one cycle ([bf590fe](https://github.com/toa-io/toa/commit/bf590fe8ed59c701b5fd1a91ba4874685b79242f))
+* feat(core)!: commit events with the state that produced them ([1eb68cc](https://github.com/toa-io/toa/commit/1eb68cc435dbfa03faa16009fceb866693d22e1a)), closes [#20](https://github.com/toa-io/toa/issues/20)
+
+
+### BREAKING CHANGES
+
+* `Storage.outbox.pending` takes a fourth argument, the id to
+continue from.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `event.changeset` is removed; use `origin` and `state`. `State`
+takes an `Outbox` in place of an `Emission`. `difference` is dropped from
+`@toa.io/generic` along with its last caller.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+
+
+
+
+# [1.0.0-alpha.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
+
+
+### Performance Improvements
+
+* **boot:** stop paying for what a composition does not need to start ([1619c27](https://github.com/toa-io/toa/commit/1619c2743072f4706939ce72f3074e615d26a91e))
+* **storages.mongodb:** time the call instead of monitoring the command ([135f1a9](https://github.com/toa-io/toa/commit/135f1a97c753b1caed9291f85cea0521ef68b0e3))
+
+
+
+
+
+# [1.0.0-alpha.266](https://github.com/toa-io/toa/compare/v1.0.0-alpha.265...v1.0.0-alpha.266) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.265](https://github.com/toa-io/toa/compare/v1.0.0-alpha.264...v1.0.0-alpha.265) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.264](https://github.com/toa-io/toa/compare/v1.0.0-alpha.263...v1.0.0-alpha.264) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.263](https://github.com/toa-io/toa/compare/v1.0.0-alpha.262...v1.0.0-alpha.263) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.259](https://github.com/toa-io/toa/compare/v1.0.0-alpha.258...v1.0.0-alpha.259) (2026-08-24)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.257](https://github.com/toa-io/toa/compare/v1.0.0-alpha.256...v1.0.0-alpha.257) (2026-08-24)
+
+**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.27",
+  "version": "1.0.0-alpha.272",
   "description": "Toa MongoDB Storage Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -19,13 +19,13 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/console": "1.0.0-alpha.27",
-    "@toa.io/conveyor": "1.0.0-alpha.27",
-    "@toa.io/core": "1.0.0-alpha.27",
-    "@toa.io/generic": "1.0.0-alpha.27",
-    "@toa.io/pointer": "1.0.0-alpha.27",
-    "mongodb": "6.3.0",
+    "@toa.io/conveyor": "1.0.0-alpha.272",
+    "@toa.io/core": "1.0.0-alpha.272",
+    "@toa.io/generic": "1.0.0-alpha.272",
+    "@toa.io/pointer": "1.0.0-alpha.272",
+    "mongodb": "7.2.0",
+    "openspan": "1.0.0-alpha.272",
     "saslprep": "1.0.3"
   },
-  "gitHead": "9bc4bdb919688c5272791020746f70d51a520750"
+  "gitHead": "1a451755445935c04cf5b373bcc73942cac0bb10"
 }

package/readme.md

@@ -0,0 +1,16 @@
+# MongoDB Storage
+
+## Tracing
+
+Commands are recorded as `client` spans within the trace of the current invocation,
+using the [driver command monitoring events](https://www.mongodb.com/docs/drivers/node/current/monitoring/command-monitoring/).
+
+Spans are named `{command} {collection}` and carry `db.*` attributes following the
+[OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/mongodb/):
+`db.system`, `db.namespace`, `db.collection.name`, `db.operation.name`.
+
+Commands executed outside of a sampled trace context (e.g. index management on startup)
+and internal driver commands (`hello`, `ping`, authentication) are not recorded.
+
+Monitoring is client-side only and does not affect the MongoDB server. Span recording
+adds no waiting to the query path: exporting is buffered and happens in the background.

package/src/client.js

@@ -6,6 +6,7 @@
  * @typedef {import('@toa.io/core').Locator} Locator
  */
 
+const { console } = require('openspan')
 const { Connector } = require('@toa.io/core')
 const { resolve } = require('@toa.io/pointer')
 const { ID } = require('./deployment')
@@ -17,12 +18,33 @@ const { MongoClient } = require('mongodb')
 const INSTANCES = {}
 
 class Client extends Connector {
+  name
+
   /**
    * @public
    * @type {import('mongodb').Collection}
    */
   collection
 
+  /**
+   * The outbox rows of this component, absent unless something consumes its events. Created
+   * eagerly beside the entity collection, because a transaction cannot create a collection and
+   * an index build cannot run inside one.
+   *
+   * @public
+   * @type {import('mongodb').Collection | undefined}
+   */
+  outbox
+
+  /**
+   * Whether this deployment can run transactions at all. A standalone mongod cannot, and an
+   * outbox without atomicity is worse than none, so the storage falls back to inline emission.
+   *
+   * @public
+   * @type {boolean}
+   */
+  transactional = false
+
   /**
    * @private
    * @type {Locator}
@@ -41,13 +63,22 @@ class Client extends Connector {
    */
   key
 
+  /**
+   * @private
+   * @type {boolean}
+   */
+  publishes
+
   /**
    * @param {Locator} locator
+   * @param {boolean} [publishes] whether this component publishes anything
    */
-  constructor (locator) {
+  constructor (locator, publishes = false) {
     super()
 
     this.locator = locator
+    this.name = locator.lowercase
+    this.publishes = publishes
   }
 
   /**
@@ -58,26 +89,44 @@ class Client extends Connector {
   async open () {
     const urls = await this.resolveURLs()
     const dbname = this.resolveDB()
-    const collname = this.locator.lowercase
 
     this.key = getKey(dbname, urls)
 
-    INSTANCES[this.key] ??= this.createInstance(urls)
+    try {
+      INSTANCES[this.key] ??= this.createInstance(urls)
+    } catch (error) {
+      console.error('Failed to connect to MongoDB', { urls, error })
+    }
 
     this.instance = await INSTANCES[this.key]
     this.instance.count++
 
     const db = this.instance.client.db(dbname)
 
-    try {
-      this.collection = await db.createCollection(collname)
-    } catch (e) {
-      if (e.code !== ALREADY_EXISTS) {
-        throw e
-      }
+    this.collection = await collection(db, this.name)
+    this.transactional = await transactional(db)
 
-      this.collection = db.collection(collname)
-    }
+    if (!this.publishes) return
+
+    if (this.transactional) this.outbox = await collection(db, this.name + OUTBOX)
+    else
+      console.warn('MongoDB is not a replica set; events are emitted inline, without an outbox',
+        { collection: this.name })
+  }
+
+  /**
+   * Runs `fn` in a transaction and answers what it returned. The driver may call `fn` more
+   * than once, so it must not hold state of its own — an outbox row is built by the caller
+   * and reused, and a rolled back attempt leaves nothing behind.
+   *
+   * @public
+   * @template T
+   * @param {(session: import('mongodb').ClientSession) => Promise<T>} fn
+   * @return {Promise<T>}
+   */
+  async transaction (fn) {
+    return this.instance.client.withSession(async (session) =>
+      session.withTransaction(async () => fn(session)))
   }
 
   /**
@@ -105,7 +154,7 @@ class Client extends Connector {
     const client = new MongoClient(urls.join(','), OPTIONS)
     const hosts = urls.map((str) => new URL(str).host)
 
-    console.info('Connecting to MongoDB:', hosts.join(', '))
+    console.info('Connecting to MongoDB', { address: hosts.join(', ') })
 
     await client.connect()
 
@@ -148,12 +197,42 @@ function getKey (db, urls) {
   return db + ':' + urls.sort().join(' ')
 }
 
+/**
+ * Concurrent pods race to create the same collection, and losing that race is not an error.
+ */
+async function collection (db, name) {
+  try {
+    return await db.createCollection(name)
+  } catch (e) {
+    if (e.code !== ALREADY_EXISTS) throw e
+
+    return db.collection(name)
+  }
+}
+
+async function transactional (db) {
+  try {
+    const hello = await db.admin().command({ hello: 1 })
+
+    return hello.setName !== undefined || hello.msg === 'isdbgrid'
+  } catch (e) {
+    console.warn('MongoDB transaction support could not be determined', { error: e })
+
+    return false
+  }
+}
+
+/**
+ * `monitorCommands` is deliberately absent. It makes the driver materialize every reply
+ * eagerly to populate the monitoring event (`CommandSucceededEvent`), which defeats the
+ * lazy per-document deserialization a cursor exists for — a 100-document batch is then
+ * deserialized twice. `Storage` times its own calls instead.
+ */
 const OPTIONS = {
-  ignoreUndefined: true,
-  connectTimeoutMS: 0,
-  serverSelectionTimeoutMS: 0
+  ignoreUndefined: true
 }
 
 const ALREADY_EXISTS = 48
+const OUTBOX = '_outbox'
 
 exports.Client = Client

package/src/factory.js

@@ -1,15 +1,13 @@
 'use strict'
 
 const { Client } = require('./client')
-const { Collection } = require('./collection')
 const { Storage } = require('./storage')
 
 class Factory {
-  storage (locator, entity) {
-    const client = new Client(locator)
-    const connection = new Collection(client)
+  storage (locator, entity, options = {}) {
+    const client = new Client(locator, options.outbox === true)
 
-    return new Storage(connection, entity)
+    return new Storage(client, entity)
   }
 }
 

package/src/outbox.js

@@ -0,0 +1,129 @@
+'use strict'
+
+const { console } = require('openspan')
+
+/**
+ * The outbox rows of one component. Its lifecycle is the Client's, so it is not a Connector.
+ *
+ * Core owns what a row means — its id, its lane and when it becomes due. This only writes
+ * them, reads back what is due, and marks what has been published.
+ */
+class Outbox {
+  /** @type {import('mongodb').Collection} */
+  #collection
+
+  #retention
+
+  constructor (collection) {
+    this.#collection = collection
+    this.#retention = retention()
+  }
+
+  /** @param {import('mongodb').ClientSession} session */
+  async insert (row, session) {
+    await this.#collection.insertOne(to(row), { session })
+  }
+
+  /** @param {import('mongodb').ClientSession} session */
+  async insertMany (rows, session) {
+    if (rows.length === 0) return
+
+    await this.#collection.insertMany(rows.map(to), { session })
+  }
+
+  /**
+   * One page of what this replica should publish: due, still unpublished, and in a lane it
+   * owns. In steady state the first page is empty.
+   *
+   * `after` continues from the last id of the page before. Ids are uuid v7, so their order is
+   * the order rows were written and a page is never read twice within a cycle — which matters
+   * because a row stays unpublished in the database until the cycle that sent it marks it.
+   */
+  async pending (lanes, now, limit, after = undefined) {
+    const criteria = { lane: { $in: lanes }, published: false, pending: { $lte: now } }
+
+    if (after !== undefined) criteria._id = { $gt: after }
+
+    const rows = await this.#collection
+      .find(criteria)
+      .sort({ _id: 1 })
+      .limit(limit)
+      .toArray()
+
+    return rows.map(from)
+  }
+
+  /**
+   * One batched write for many events, which is why the ids are held in memory until the
+   * tick rather than updated one by one.
+   */
+  async settle (ids) {
+    if (ids.length === 0) return
+
+    await this.#collection.updateMany({ _id: { $in: ids } },
+      { $set: { published: true, publishedAt: new Date() } })
+  }
+
+  /**
+   * The entity collection's index management does not reach here, so this collection keeps
+   * its own — including pruning, or a later change leaves the old index behind forever.
+   */
+  async index () {
+    const desired = {
+      // holds only what is not published yet, so it stays at in-flight size
+      outbox_pending: {
+        fields: { lane: 1, pending: 1 },
+        options: { name: 'outbox_pending', partialFilterExpression: { published: false } }
+      },
+      // an unpublished row has no `publishedAt`, and the TTL monitor skips those — so a row
+      // that never made it out is never reaped
+      outbox_published_at: {
+        fields: { publishedAt: 1 },
+        options: { name: 'outbox_published_at', expireAfterSeconds: this.#retention }
+      }
+    }
+
+    for (const { fields, options } of Object.values(desired))
+      await this.#collection.createIndex(fields, options)
+        .catch((e) => console.warn('MongoDB outbox index creation failed',
+          { collection: this.#collection.collectionName, name: options.name, error: e }))
+
+    await this.#prune(Object.keys(desired))
+  }
+
+  /** @private */
+  async #prune (desired) {
+    let current
+
+    try {
+      current = await this.#collection.listIndexes().toArray()
+    } catch {
+      return
+    }
+
+    const obsolete = current
+      .map(({ name }) => name)
+      .filter((name) => name !== '_id_' && !desired.includes(name))
+
+    if (obsolete.length === 0) return
+
+    console.info('Removing obsolete outbox indexes',
+      { collection: this.#collection.collectionName, indexes: obsolete.join(', ') })
+
+    await Promise.all(obsolete.map((name) => this.#collection.dropIndex(name)))
+  }
+}
+
+const to = ({ id, ...rest }) => ({ _id: id, ...rest })
+const from = ({ _id, ...rest }) => ({ id: _id, ...rest })
+
+function retention () {
+  const value = Number(process.env.TOA_OUTBOX_RETENTION)
+
+  return Number.isNaN(value) || value < 0 ? RETENTION : value
+}
+
+/** seconds a published row is kept as a change log before the TTL monitor reaps it */
+const RETENTION = 86400
+
+exports.Outbox = Outbox

package/src/record.js

@@ -1,29 +1,16 @@
 'use strict'
 
-/**
- * @param {toa.core.storages.Record} entity
- * @returns {toa.mongodb.Record}
- */
-const to = (entity) => {
-  const {
-    id,
-    ...rest
-  } = entity
+function to (entity) {
+  const { id, ...rest } = entity
 
   return /** @type {toa.mongodb.Record} */ { _id: id, ...rest }
 }
 
-/**
- * @param {toa.mongodb.Record} record
- * @returns {toa.core.storages.Record}
- */
-const from = (record) => {
-  if (record === undefined || record === null) return null
+function from (record) {
+  if (record === undefined || record === null)
+    return null
 
-  const {
-    _id,
-    ...rest
-  } = record
+  const { _id, ...rest } = record
 
   return { id: _id, ...rest }
 }

package/src/storage.js

@@ -1,102 +1,228 @@
 'use strict'
 
-const {
-  Connector,
-  exceptions
-} = require('@toa.io/core')
-
+const { Connector, exceptions } = require('@toa.io/core')
+const { console } = require('openspan')
 const { translate } = require('./translate')
-const {
-  to,
-  from
-} = require('./record')
+const { to, from } = require('./record')
+const { Outbox } = require('./outbox')
+const { ReturnDocument } = require('mongodb')
 
 class Storage extends Connector {
-  #connection
+  #client
+
+  /** @type {import('mongodb').Collection} */
+  #collection
   #entity
 
-  constructor (connection, entity) {
+  /**
+   * @type {Outbox | undefined} absent when nothing consumes this component's events, or when
+   * the deployment cannot run transactions
+   */
+  #outbox
+
+  /** @type {Map<string, object>} span options per driver method */
+  #spans = new Map()
+
+  constructor (client, entity) {
     super()
 
-    this.#connection = connection
+    this.#client = client
     this.#entity = entity
 
-    this.depends(connection)
+    this.depends(client)
+  }
+
+  get raw () {
+    return this.#collection
+  }
+
+  /**
+   * The outbox is offered only where a row can be committed atomically with the entity.
+   * Without that it would be a second write with a window in front of it — worse than the
+   * inline emission it replaces — so the storage simply does not advertise it.
+   */
+  get outbox () {
+    return this.#outbox
   }
 
   async open () {
+    this.#collection = this.#client.collection
+
+    if (this.#client.outbox !== undefined)
+      this.#outbox = new Outbox(this.#client.outbox)
+
+    this.#spans.clear()
+
     await this.index()
+    await this.#outbox?.index()
   }
 
   async get (query) {
-    const {
-      criteria,
-      options
-    } = translate(query)
+    const { criteria, options } = translate(query)
+
+    // identity lookups must return deleted records, so that callers
+    // can tell a deleted entity from a missing one
+    if (query?.id === undefined && query?.options?.deleted !== true)
+      criteria._deleted = null
 
-    const record = await this.#connection.get(criteria, options)
+    const record = await this.command('findOne', { criteria, options },
+      () => this.#collection.findOne(criteria, options))
 
     return from(record)
   }
 
   async find (query) {
-    const {
-      criteria,
-      options
-    } = translate(query)
+    const { criteria, options, sample } = translate(query)
 
-    const recordset = await this.#connection.find(criteria, options)
+    if (query?.options?.deleted !== true)
+      criteria._deleted = null
+
+    const recordset = sample === undefined
+      ? await this.command('find', { criteria, options },
+        async () => await this.#collection.find(criteria, options).toArray())
+      : await this.aggregate(criteria, options, sample)
 
     return recordset.map((item) => from(item))
   }
 
-  async add (entity) {
+  /** @private */
+  async aggregate (criteria, options, sample) {
+    const pipeline = toPipeline(criteria, options, sample)
+
+    return await this.command('aggregate', { pipeline },
+      async () => await this.#collection.aggregate(pipeline).toArray())
+  }
+
+  async stream (query = undefined) {
+    const { criteria, options } = translate(query)
+
+    if (query?.options?.deleted !== true)
+      criteria._deleted = null
+
+    this.debug('find (stream)', { criteria, options })
+
+    return this.#collection.find(criteria, options).stream({ transform: from })
+  }
+
+  async add (entity, session = undefined) {
     const record = to(entity)
-    const result = await this.#connection.add(record)
+
+    const result = await this.command('insertOne', { record },
+      () => this.#collection.insertOne(record, { session }))
 
     return result.acknowledged
   }
 
-  async set (entity) {
+  async set (entity, session = undefined) {
     const criteria = {
       _id: entity.id,
       _version: entity._version - 1
     }
-    const result = await this.#connection.replace(criteria, to(entity))
+
+    const record = to(entity)
+
+    const result = await this.command('findOneAndReplace', { criteria, record },
+      () => this.#collection.findOneAndReplace(criteria, record, { session }))
 
     return result !== null
   }
 
-  async store (entity) {
+  async store (entity, row = undefined, attempt = 0) {
     try {
-      if (entity._version === 1) {
-        return await this.add(entity)
-      } else {
-        return await this.set(entity)
+      if (row === undefined || this.#outbox === undefined) {
+        if (entity._version === 1)
+          return await this.add(entity)
+        else
+          return await this.set(entity)
       }
-    } catch (error) {
-      if (error.code === ERR_DUPLICATE_KEY) {
 
-        const id = error.keyPattern === undefined
-          ? error.message.includes(' index: _id_ ') // AWS DocumentDB
-          : error.keyPattern._id === 1
+      const committed = await this.#client.transaction(async (session) => {
+        const ok = entity._version === 1
+          ? await this.add(entity, session)
+          : await this.set(entity, session)
+
+        // a lost compare-and-swap must take the row down with it, or a retried transition
+        // leaves a row for a write that never happened
+        if (!ok) {
+          await session.abortTransaction()
 
-        if (id) {
           return false
-        } else {
-          throw new exceptions.DuplicateException()
         }
-      } else {
-        throw error
-      }
+
+        await this.#outbox.insert(row, session)
+
+        return true
+      })
+
+      return committed === true
+    } catch (error) {
+      console.error('MongoDB error', error)
+
+      const retry = await retriable(error, attempt)
+
+      if (retry)
+        return await this.store(entity, row, attempt + 1)
+      else
+        return false
     }
   }
 
-  async upsert (query, changeset) {
-    const {
-      criteria,
-      options
-    } = translate(query)
+  async massStore (entities, rows = undefined, attempt = 0) {
+    if (entities.length === 0)
+      return true
+
+    const operations = entities.map((entity) => {
+      const record = to(entity)
+
+      if (entity._version === 1) {
+        const { _version, ...rest } = record
+
+        return { // upsert in required when document is deleted
+          updateOne: {
+            filter: { _id: entity.id },
+            update: {
+              $set: {    
+                ...rest,
+                _deleted: null
+              },
+              $inc: { _version: 1 },
+            },
+            upsert: true
+          } 
+        }
+      } else
+        return {  
+          replaceOne: { 
+            filter: { _id: entity.id, _version: entity._version - 1 },
+            replacement: record
+          }
+        }
+    })
+
+    try {
+      await this.#client.transaction(async (session) => {
+        await this.command('bulkWrite', { operations: operations.length },
+          async () => await this.#collection.bulkWrite(operations, { session }))
+
+        if (rows !== undefined && this.#outbox !== undefined)
+          await this.#outbox.insertMany(rows, session)
+      })
+
+      return true
+    } catch (error) {
+      console.error('MongoDB error', error)
+
+      const retry = await retriable(error, attempt)
+
+      if (retry)
+        return await this.massStore(entities, rows, attempt + 1)
+      else
+        return false
+    }
+  }
+
+  async upsert (query, changeset, row = undefined) {
+    const { criteria, options } = translate(query)
 
     if (!('_deleted' in changeset) || changeset._deleted === null) {
       delete criteria._deleted
@@ -108,46 +234,115 @@ class Storage extends Connector {
       $inc: { _version: 1 }
     }
 
-    options.returnDocument = 'after'
+    // BEFORE, so that the filter is applied once and atomically and the pre-image comes back
+    // with it — an assignment is the one event whose images are the write's own
+    options.returnDocument = ReturnDocument.BEFORE
+
+    const apply = async (session) => {
+      const found = await this.command('findOneAndUpdate', { criteria, update, options },
+        () => this.#collection.findOneAndUpdate(criteria, update, { ...options, session }))
+
+      if (found === null) return null
+
+      const origin = from(found)
+
+      /*
+       * The post-image is `update` applied to the pre-image, computed rather than read back.
+       * That is exact, not approximate: `$set` on top-level keys is a spread (entity property
+       * names cannot contain dots, so a changeset never carries a path), and `_version` is
+       * incremented by one. It is also a coupling — an operator added to `update` and not
+       * mirrored here diverges silently — which `features/events/outbox.feature` guards.
+       */
+      const state = { ...origin, ...changeset, _version: origin._version + 1 }
+
+      // an assignment's event is the write's own images, so they are filled in here whether
+      // or not the row is going to be committed
+      if (row !== undefined)
+        row.event = { origin, state, ...row.event }
+
+      if (row !== undefined && this.#outbox !== undefined)
+        await this.#outbox.insert(row, session)
+
+      return state
+    }
+
+    if (row === undefined || this.#outbox === undefined)
+      return apply(undefined)
+
+    return this.#client.transaction(apply)
+  }
+
+  async ensure (query, properties, state, row = undefined) {
+    let { criteria, options } = translate(query)
 
-    const result = await this.#connection.update(criteria, update, options)
+    if (query === undefined)
+      criteria = properties
 
-    return from(result)
+    const update = { $setOnInsert: to(state) }
+
+    options.upsert = true
+    options.returnDocument = ReturnDocument.AFTER
+
+    try {
+      const result = row === undefined || this.#outbox === undefined
+        ? await this.command('findOneAndUpdate', { criteria, update, options },
+          () => this.#collection.findOneAndUpdate(criteria, update, options))
+        : await this.#client.transaction(async (session) => {
+          const found = await this.command('findOneAndUpdate', { criteria, update, options },
+            () => this.#collection.findOneAndUpdate(criteria, update, { ...options, session }))
+
+          // only an insert is an event; finding an existing record is not
+          if (found !== null && found._id === state.id)
+            await this.#outbox.insert(row, session)
+
+          return found
+        })
+
+      if (result._deleted !== undefined && result._deleted !== null)
+        return null
+      else
+        return from(result)
+    } catch (error) {
+      if (error.code === ERR_DUPLICATE_KEY)
+        throw new exceptions.DuplicateException(this.#client.name)
+      else
+        throw error
+    }
   }
 
+  /** A component does not start before this returns, so the indexes are created at once. */
   async index () {
-    const indexes = []
+    const pending = []
 
-    if (this.#entity.unique !== undefined) {
+    if (this.#entity.unique !== undefined)
       for (const [name, fields] of Object.entries(this.#entity.unique)) {
-        const sparse = this.checkFields(fields)
-        const unique = await this.uniqueIndex(name, fields, sparse)
+        const optional = this.getOptional(fields)
 
-        indexes.push(unique)
+        pending.push(this.uniqueIndex(name, fields, optional))
       }
-    }
 
-    if (this.#entity.index !== undefined) {
+    if (this.#entity.index !== undefined)
       for (const [suffix, declaration] of Object.entries(this.#entity.index)) {
         const name = 'index_' + suffix
         const fields = Object.fromEntries(Object.entries(declaration)
-          .map(([name, type]) => [name, INDEX_TYPES[type]]))
+          .map(([name, type]) => [name, INDEX_TYPES[type] ?? type]))
 
-        const sparse = this.checkFields(Object.keys(fields))
+        const optional = this.getOptional(Object.keys(fields))
+        const options = { name, sparse: optional.length > 0 }
 
-        await this.#connection.index(fields, {
-          name,
-          sparse
-        })
+        console.info('Creating index', { fields, options })
 
-        indexes.push(name)
+        pending.push(this.#collection.createIndex(fields, options)
+          .catch((e) => console.warn('MongoDB index creation failed', { collection: this.#collection.collectionName, name, fields, error: e }))
+          .then(() => name))
       }
-    }
 
-    await this.removeObsolete(indexes)
+    const indexes = await Promise.all(pending)
+
+    await this.removeObsoleteIndexes(indexes)
   }
 
-  async uniqueIndex (name, properties, sparse = false) {
+  async uniqueIndex (name, properties, optional) {
     const fields = properties.reduce((acc, property) => {
       acc[property] = 1
       return acc
@@ -155,48 +350,122 @@ class Storage extends Connector {
 
     name = 'unique_' + name
 
-    await this.#connection.index(fields, {
-      name,
-      unique: true,
-      sparse
-    })
+    const options = { name, unique: true }
+
+    if (optional.length > 0)
+      options.partialFilterExpression = Object.fromEntries(optional.map((field) => [field, { $exists: true }]))
+
+    console.info('Creating unique index', { name, fields, options })
+
+    await this.#collection.createIndex(fields, options)
+      .catch((e) => console.warn('MongoDB unique index creation failed', 
+        { collection: this.#collection.collectionName, name, fields, error: e }))
 
     return name
   }
 
-  async removeObsolete (desired) {
-    const current = await this.#connection.indexes()
+  async removeObsoleteIndexes (desired) {
+    const current = await this.getCurrentIndexes()
     const obsolete = current.filter((name) => !desired.includes(name))
 
     if (obsolete.length > 0) {
-      console.info(`Remove obsolete indexes: [${obsolete.join(', ')}]`)
+      console.info('Removing obsolete indexes', { collection: this.#collection.collectionName, indexes: obsolete.join(', ') })
+
+      await Promise.all(obsolete.map((name) => this.#collection.dropIndex(name)))
+    }
+  }
+
+  async getCurrentIndexes () {
+    try {
+      const array = await this.#collection.listIndexes().toArray()
 
-      await this.#connection.dropIndexes(obsolete)
+      return array.map(({ name }) => name).filter((name) => name !== '_id_')
+    } catch {
+      return []
     }
   }
 
-  checkFields (fields) {
+  getOptional (fields) {
     const optional = []
 
-    for (const field of fields) {
-      if (!(field in this.#entity.schema.properties)) {
+    for (const field of fields) {      
+      if (!field.includes('.') && !(field in this.#entity.schema.properties))
         throw new Error(`Index field '${field}' is not defined.`)
-      }
 
-      if (!this.#entity.schema.required?.includes(field)) {
+      if (!this.#entity.schema.required?.includes(field))
         optional.push(field)
-      }
     }
 
-    if (optional.length > 0) {
-      console.info(`Index fields [${optional.join(', ')}] are optional, creating sparse index.`)
+    return optional
+  }
 
-      return true
-    } else {
-      return false
+  /**
+   * Names, logs and times a call into the driver. The driver's own command monitoring is
+   * off (see `client.js`), so this is where a query becomes a span.
+   *
+   * @private
+   */
+  async command (method, attributes, task) {
+    this.debug(method, attributes)
+
+    return console.span(this.span(method), task)
+  }
+
+  /**
+   * The span of a driver method is the same object every time: the collection is fixed
+   * for a storage, and nothing downstream writes to what it is given.
+   *
+   * @private
+   */
+  span (method) {
+    let options = this.#spans.get(method)
+
+    if (options === undefined) {
+      const collection = this.#collection.collectionName
+
+      options = {
+        name: `${method} ${collection}`,
+        kind: 'client',
+        // https://opentelemetry.io/docs/specs/semconv/database/mongodb/
+        attributes: {
+          'db.system': 'mongodb',
+          'db.namespace': this.#collection.dbName,
+          'db.operation.name': method,
+          'db.collection.name': collection
+        }
+      }
+
+      this.#spans.set(method, options)
     }
+
+    return options
   }
 
+  debug (method, attributes) {
+    console.debug('MongoDB query', {
+      collection: this.#collection.collectionName,
+      method,
+      ...attributes
+    })
+  }
+}
+
+function toPipeline (criteria, options, sample) {
+  const pipeline = []
+
+  if (criteria !== undefined)
+    pipeline.push({ $match: criteria })
+
+  if (sample !== undefined)
+    pipeline.push({ $sample: { size: sample } })
+
+  if (options?.sort !== undefined)
+    pipeline.push({ $sort: options.sort })
+
+  if (options?.projection !== undefined)
+    pipeline.push({ $project: options.projection })
+
+  return pipeline
 }
 
 const INDEX_TYPES = {
@@ -207,4 +476,29 @@ const INDEX_TYPES = {
 
 const ERR_DUPLICATE_KEY = 11000
 
+async function retriable (error, attempt) {
+  if (error.code === ERR_DUPLICATE_KEY) {
+    const id = error.keyPattern === undefined
+      ? error.message.includes(' index: _id_ ') // AWS DocumentDB
+      : error.keyPattern._id === 1
+
+    if (id)
+      return false
+    else
+      throw new exceptions.DuplicateException()
+  } else if (error.cause?.code === 'ECONNREFUSED') {
+    if (attempt === LAST_ATTEMPT)
+      throw error
+
+    const timeout = 1000 + 500 * attempt
+
+    await new Promise((resolve) => setTimeout(resolve, timeout))
+
+    return true
+  } else
+    throw error
+}
+
+const LAST_ATTEMPT = 9
+
 exports.Storage = Storage

package/src/translate.js

@@ -9,18 +9,21 @@ const parse = { ...require('./translate/criteria'), ...require('./translate/opti
 const translate = (query) => {
   const result = {
     criteria: query?.criteria === undefined ? {} : parse.criteria(query.criteria),
-    options: query?.options === undefined ? {} : parse.options(query.options)
+    options: query?.options === undefined ? {} : parse.options(query.options),
+    sample: query?.options?.sample
   }
 
-  if (query?.id !== undefined) {
+  if (query?.id !== undefined)
     result.criteria._id = query.id
-  }
 
-  if (query?.version !== undefined) {
+  if (query?.ids !== undefined)
+    result.criteria._id = { $in: query.ids }
+
+  if (query?.version !== undefined)
     result.criteria._version = query.version
-  }
 
-  result.criteria._deleted = null
+  if (query?.search !== undefined)
+    result.criteria.$text = { $search: query.search }
 
   return result
 }

package/test/record.test.js

@@ -47,19 +47,4 @@ describe('from', () => {
       _version: 0
     })
   })
-
-  it('should not modify argument', () => {
-    /** @type {toa.mongodb.Record} */
-    const record = {
-      _id: '1',
-      _version: 0
-    }
-
-    from(record)
-
-    expect(record).toStrictEqual({
-      _id: '1',
-      _version: 0
-    })
-  })
 })

package/test/storage.test.js

@@ -0,0 +1,73 @@
+'use strict'
+
+const { Storage } = require('../src/storage')
+
+let collection
+let storage
+
+beforeEach(async () => {
+  collection = {
+    collectionName: 'test',
+    findOne: jest.fn(async () => null),
+    find: jest.fn(() => ({ stream: () => null }))
+  }
+
+  const client = {
+    collection,
+    link: () => null
+  }
+
+  storage = new Storage(client, { schema: { properties: {} } })
+
+  await storage.open()
+})
+
+describe('get', () => {
+  it('should filter deleted', async () => {
+    await storage.get({})
+
+    expect(collection.findOne).toHaveBeenCalledWith({ _deleted: null }, {})
+  })
+
+  it('should filter deleted with sort', async () => {
+    await storage.get({ options: { sort: [['_created', 'desc']] } })
+
+    expect(collection.findOne)
+      .toHaveBeenCalledWith({ _deleted: null }, { sort: [['_created', -1]] })
+  })
+
+  it('should not filter deleted if queried by id', async () => {
+    const id = 'bcb6780f50e243348cad40ed6b5ef575'
+
+    await storage.get({ id })
+
+    expect(collection.findOne).toHaveBeenCalledWith({ _id: id }, {})
+  })
+
+  it('should not filter deleted if requested', async () => {
+    await storage.get({ options: { deleted: true } })
+
+    expect(collection.findOne).toHaveBeenCalledWith({}, {})
+  })
+})
+
+describe('stream', () => {
+  it('should filter deleted', async () => {
+    await storage.stream()
+
+    expect(collection.find).toHaveBeenCalledWith({ _deleted: null }, {})
+  })
+
+  it('should filter deleted with sort', async () => {
+    await storage.stream({ options: { sort: [['_created', 'desc']] } })
+
+    expect(collection.find)
+      .toHaveBeenCalledWith({ _deleted: null }, { sort: [['_created', -1]] })
+  })
+
+  it('should not filter deleted if requested', async () => {
+    await storage.stream({ options: { deleted: true } })
+
+    expect(collection.find).toHaveBeenCalledWith({}, {})
+  })
+})

package/src/collection.js

@@ -1,69 +0,0 @@
-'use strict'
-
-const { Connector } = require('@toa.io/core')
-
-class Collection extends Connector {
-  #client
-  #collection
-
-  constructor (client) {
-    super()
-
-    this.#client = client
-
-    this.depends(client)
-  }
-
-  async open () {
-    this.#collection = this.#client.collection
-  }
-
-  /** @hot */
-  async get (query, options) {
-    return /** @type {toa.mongodb.Record} */ this.#collection.findOne(query, options)
-  }
-
-  /** @hot */
-  async find (query, options) {
-    const cursor = this.#collection.find(query, options)
-
-    return cursor.toArray()
-  }
-
-  /** @hot */
-  async add (record) {
-    return await this.#collection.insertOne(record)
-  }
-
-  /** @hot */
-  async replace (query, record, options) {
-    return await this.#collection.findOneAndReplace(query, record, options)
-  }
-
-  /** @hot */
-  async update (query, update, options) {
-    return this.#collection.findOneAndUpdate(query, update, options)
-  }
-
-  async index (keys, options) {
-    return this.#collection.createIndex(keys, options)
-  }
-
-  async indexes () {
-    try {
-      const array = await this.#collection.listIndexes().toArray()
-
-      return array.map(({ name }) => name).filter((name) => name !== '_id_')
-    } catch {
-      return []
-    }
-  }
-
-  async dropIndexes (names) {
-    const all = names.map((name) => this.#collection.dropIndex(name))
-
-    return Promise.all(all)
-  }
-}
-
-exports.Collection = Collection