@toa.io/storages.mongodb 1.0.0-alpha.266 → 1.0.0-alpha.270

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 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.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/storages.mongodb",
-  "version": "1.0.0-alpha.266",
+  "version": "1.0.0-alpha.270",
   "description": "Toa MongoDB Storage Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,12 +20,12 @@
   },
   "dependencies": {
     "@toa.io/conveyor": "1.0.0-alpha.254",
-    "@toa.io/core": "1.0.0-alpha.266",
+    "@toa.io/core": "1.0.0-alpha.270",
     "@toa.io/generic": "1.0.0-alpha.254",
-    "@toa.io/pointer": "1.0.0-alpha.263",
+    "@toa.io/pointer": "1.0.0-alpha.270",
     "mongodb": "7.2.0",
-    "openspan": "1.0.0-alpha.264",
+    "openspan": "1.0.0-alpha.270",
     "saslprep": "1.0.3"
   },
-  "gitHead": "0d2b83ff9ed6bf6d9fee7bf00f979b9ee38e9713"
+  "gitHead": "94400bdd411b4c25074ffcf58184580ddd060268"
 }

package/src/client.js

@@ -11,7 +11,6 @@ const { Connector } = require('@toa.io/core')
 const { resolve } = require('@toa.io/pointer')
 const { ID } = require('./deployment')
 const { MongoClient } = require('mongodb')
-const { monitor } = require('./monitoring')
 
 /**
  * @type {Record<string, Promise<Instance>>}
@@ -113,8 +112,6 @@ class Client extends Connector {
     const client = new MongoClient(urls.join(','), OPTIONS)
     const hosts = urls.map((str) => new URL(str).host)
 
-    monitor(client)
-
     console.info('Connecting to MongoDB', { address: hosts.join(', ') })
 
     await client.connect()
@@ -158,9 +155,14 @@ function getKey (db, urls) {
   return db + ':' + urls.sort().join(' ')
 }
 
+/**
+ * `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,
-  monitorCommands: true
+  ignoreUndefined: true
 }
 
 const ALREADY_EXISTS = 48

package/src/storage.js

@@ -13,6 +13,9 @@ class Storage extends Connector {
   #collection
   #entity
 
+  /** @type {Map<string, object>} span options per driver method */
+  #spans = new Map()
+
   constructor (client, entity) {
     super()
 
@@ -29,6 +32,8 @@ class Storage extends Connector {
   async open () {
     this.#collection = this.#client.collection
 
+    this.#spans.clear()
+
     await this.index()
   }
 
@@ -40,9 +45,8 @@ class Storage extends Connector {
     if (query?.id === undefined && query?.options?.deleted !== true)
       criteria._deleted = null
 
-    this.debug('findOne', { criteria, options })
-
-    const record = await this.#collection.findOne(criteria, options)
+    const record = await this.command('findOne', { criteria, options },
+      () => this.#collection.findOne(criteria, options))
 
     return from(record)
   }
@@ -53,23 +57,20 @@ class Storage extends Connector {
     if (query?.options?.deleted !== true)
       criteria._deleted = null
 
-    let cursor
-
-    if (sample === undefined) {
-      this.debug('find', { criteria, options })
+    const recordset = sample === undefined
+      ? await this.command('find', { criteria, options },
+        async () => await this.#collection.find(criteria, options).toArray())
+      : await this.aggregate(criteria, options, sample)
 
-      cursor = this.#collection.find(criteria, options)
-    } else {
-      const pipeline = toPipeline(criteria, options, sample)
-
-      this.debug('aggregate', { pipeline })
-
-      cursor = this.#collection.aggregate(pipeline)
-    }
+    return recordset.map((item) => from(item))
+  }
 
-    const recordset = await cursor.toArray()
+  /** @private */
+  async aggregate (criteria, options, sample) {
+    const pipeline = toPipeline(criteria, options, sample)
 
-    return recordset.map((item) => from(item))
+    return await this.command('aggregate', { pipeline },
+      async () => await this.#collection.aggregate(pipeline).toArray())
   }
 
   async stream (query = undefined) {
@@ -86,9 +87,8 @@ class Storage extends Connector {
   async add (entity) {
     const record = to(entity)
 
-    this.debug('insertOne', { record })
-
-    const result = await this.#collection.insertOne(record)
+    const result = await this.command('insertOne', { record },
+      () => this.#collection.insertOne(record))
 
     return result.acknowledged
   }
@@ -101,9 +101,8 @@ class Storage extends Connector {
 
     const record = to(entity)
 
-    this.debug('findOneAndReplace', { criteria, record })
-
-    const result = await this.#collection.findOneAndReplace(criteria, record)
+    const result = await this.command('findOneAndReplace', { criteria, record },
+      () => this.#collection.findOneAndReplace(criteria, record))
 
     return result !== null
   }
@@ -162,11 +161,9 @@ class Storage extends Connector {
 
     try {
       await client.withSession(async (session) => {
-        await session.withTransaction(async () => {
-          this.debug('bulkWrite', { operations: operations.length })
-
-          await this.#collection.bulkWrite(operations, { session })
-        })
+        await session.withTransaction(async () =>
+          await this.command('bulkWrite', { operations: operations.length },
+            async () => await this.#collection.bulkWrite(operations, { session })))
       })
 
       return true
@@ -197,9 +194,8 @@ class Storage extends Connector {
 
     options.returnDocument = ReturnDocument.AFTER
 
-    this.debug('findOneAndUpdate', { criteria, update, options })
-
-    const result = await this.#collection.findOneAndUpdate(criteria, update, options)
+    const result = await this.command('findOneAndUpdate', { criteria, update, options },
+      () => this.#collection.findOneAndUpdate(criteria, update, options))
 
     return from(result)
   }
@@ -215,10 +211,9 @@ class Storage extends Connector {
     options.upsert = true
     options.returnDocument = ReturnDocument.AFTER
 
-    console.debug('Database query', { collection: this.#collection.collectionName, method: 'findOneAndUpdate', criteria, update, options })
-
     try {
-      const result = await this.#collection.findOneAndUpdate(criteria, update, options)
+      const result = await this.command('findOneAndUpdate', { criteria, update, options },
+        () => this.#collection.findOneAndUpdate(criteria, update, options))
 
       if (result._deleted !== undefined && result._deleted !== null)
         return null
@@ -232,19 +227,18 @@ class Storage extends Connector {
     }
   }
 
+  /** 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 optional = this.getOptional(fields)
-        const unique = await this.uniqueIndex(name, fields, optional)
 
-        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)
@@ -255,12 +249,12 @@ class Storage extends Connector {
 
         console.info('Creating index', { fields, options })
 
-        await this.#collection.createIndex(fields, options)
+        pending.push(this.#collection.createIndex(fields, options)
           .catch((e) => console.warn('MongoDB index creation failed', { collection: this.#collection.collectionName, name, fields, error: e }))
-
-        indexes.push(name)
+          .then(() => name))
       }
-    }
+
+    const indexes = await Promise.all(pending)
 
     await this.removeObsoleteIndexes(indexes)
   }
@@ -322,6 +316,48 @@ class Storage extends Connector {
     return optional
   }
 
+  /**
+   * 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,

package/src/monitoring.js

@@ -1,87 +0,0 @@
-'use strict'
-
-const { create, current, record } = require('openspan')
-
-/**
- * Records MongoDB commands as client spans using the driver command monitoring events.
- * Requires the client to be created with `monitorCommands: true`.
- *
- * Commands executed outside of a sampled trace context are not recorded.
- *
- * @param {import('mongodb').MongoClient} client
- */
-function monitor (client) {
-  /** @type {Map<number, { context: object, time: number, attributes: object }>} */
-  const pending = new Map()
-
-  client.on('commandStarted', (event) => {
-    if (IGNORE.has(event.commandName))
-      return
-
-    const parent = current()
-
-    if (parent === undefined || !parent.sampled)
-      return
-
-    if (pending.size >= CAPACITY) // should never happen
-      pending.delete(pending.keys().next().value)
-
-    // https://opentelemetry.io/docs/specs/semconv/database/mongodb/
-    const attributes = {
-      'db.system': 'mongodb',
-      'db.namespace': event.databaseName,
-      'db.operation.name': event.commandName
-    }
-
-    const collection = event.command?.[event.commandName]
-
-    if (typeof collection === 'string')
-      attributes['db.collection.name'] = collection
-
-    pending.set(event.requestId, {
-      context: create(parent),
-      time: Date.now(),
-      attributes
-    })
-  })
-
-  client.on('commandSucceeded', (event) => complete(event))
-  client.on('commandFailed', (event) => complete(event, 'error'))
-
-  function complete (event, status) {
-    const started = pending.get(event.requestId)
-
-    if (started === undefined)
-      return
-
-    pending.delete(event.requestId)
-
-    const collection = started.attributes['db.collection.name']
-
-    const span = {
-      name: collection === undefined
-        ? event.commandName
-        : `${event.commandName} ${collection}`,
-      traceId: started.context.traceId,
-      spanId: started.context.spanId,
-      parentId: started.context.parentId,
-      kind: 'client',
-      time: started.time,
-      duration: event.duration,
-      attributes: started.attributes,
-      service: started.context.service
-    }
-
-    if (status !== undefined)
-      span.status = status
-
-    record(span)
-  }
-}
-
-// internal commands, including authentication and connection management
-const IGNORE = new Set(['hello', 'ismaster', 'ping', 'endSessions', 'saslStart', 'saslContinue'])
-
-const CAPACITY = 1024
-
-exports.monitor = monitor

package/test/monitoring.test.js

@@ -1,99 +0,0 @@
-'use strict'
-
-const { EventEmitter } = require('node:events')
-const { create, exporting, run, traces } = require('openspan')
-const { monitor } = require('../src/monitoring')
-
-let client
-let spans
-
-beforeEach(() => {
-  client = new EventEmitter()
-  spans = []
-
-  exporting([{ export: (span) => spans.push(span) }])
-  monitor(client)
-})
-
-afterEach(() => {
-  traces()
-})
-
-const started = {
-  requestId: 1,
-  commandName: 'find',
-  databaseName: 'toa-dev',
-  command: { find: 'pots', filter: {} }
-}
-
-const succeeded = { requestId: 1, commandName: 'find', duration: 1.5 }
-const failed = { requestId: 1, commandName: 'find', duration: 0.5, failure: 'boom' }
-
-it('should record a command as a client span', () => {
-  const context = create()
-
-  run(context, () => client.emit('commandStarted', started))
-  client.emit('commandSucceeded', succeeded)
-
-  expect(spans).toHaveLength(1)
-
-  expect(spans[0]).toMatchObject({
-    name: 'find pots',
-    traceId: context.traceId,
-    parentId: context.spanId,
-    kind: 'client',
-    duration: 1.5,
-    attributes: {
-      'db.system': 'mongodb',
-      'db.namespace': 'toa-dev',
-      'db.operation.name': 'find',
-      'db.collection.name': 'pots'
-    }
-  })
-
-  expect(spans[0].status).toBeUndefined()
-})
-
-it('should record failed commands with error status', () => {
-  run(create(), () => client.emit('commandStarted', started))
-  client.emit('commandFailed', failed)
-
-  expect(spans).toHaveLength(1)
-  expect(spans[0].status).toBe('error')
-})
-
-it('should not record commands outside of a trace context', () => {
-  client.emit('commandStarted', started)
-  client.emit('commandSucceeded', succeeded)
-
-  expect(spans).toHaveLength(0)
-})
-
-it('should not record commands of unsampled traces', () => {
-  const context = { ...create(), sampled: false }
-
-  run(context, () => client.emit('commandStarted', started))
-  client.emit('commandSucceeded', succeeded)
-
-  expect(spans).toHaveLength(0)
-})
-
-it('should ignore internal commands', () => {
-  run(create(), () => {
-    client.emit('commandStarted', { ...started, commandName: 'hello', command: { hello: 1 } })
-  })
-
-  client.emit('commandSucceeded', { ...succeeded, commandName: 'hello' })
-
-  expect(spans).toHaveLength(0)
-})
-
-it('should name spans without a collection by the command', () => {
-  const start = { ...started, commandName: 'listIndexes', command: { listIndexes: 1 } }
-
-  run(create(), () => client.emit('commandStarted', start))
-  client.emit('commandSucceeded', { ...succeeded, commandName: 'listIndexes' })
-
-  expect(spans).toHaveLength(1)
-  expect(spans[0].name).toBe('listIndexes')
-})