@toa.io/storages.mongodb 1.0.0-alpha.286 → 1.0.0-alpha.288

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 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.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+### Features
+
+* **mongodb:** a migration says what it is doing ([a917a81](https://github.com/toa-io/toa/commit/a917a81fdc94eb23fd73182c0edf891e6b2df843))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/storages.mongodb",
-  "version": "1.0.0-alpha.286",
+  "version": "1.0.0-alpha.288",
   "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.286",
-    "@toa.io/core": "1.0.0-alpha.286",
+    "@toa.io/core": "1.0.0-alpha.288",
     "@toa.io/generic": "1.0.0-alpha.286",
-    "@toa.io/pointer": "1.0.0-alpha.286",
+    "@toa.io/pointer": "1.0.0-alpha.287",
     "mongodb": "7.6.0",
     "openspan": "1.0.0-alpha.286",
     "saslprep": "1.0.3"
   },
-  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
+  "gitHead": "d3d696f0a4e287c3c297ac81028d600ad7574112"
 }

package/src/migrations.js

@@ -37,26 +37,66 @@ export class Migrations {
    * against what an earlier one leaves behind.
    */
   async run() {
-    for (const migration of this.#list) await this.#apply(migration)
+    let applied = 0
+
+    for (const migration of this.#list) if (await this.#apply(migration)) applied++
+
+    // debug, because the ordinary start has nothing to report: every migration was applied
+    // long ago by whoever started first. But a run that says nothing at all cannot be told
+    // from one that never looked
+    console.debug('Migrations checked', {
+      collection: this.#collection.collectionName,
+      declared: this.#list.length,
+      applied
+    })
   }
 
-  /** @private */
+  /**
+   * Answers whether this replica was the one that applied it.
+   *
+   * @private
+   */
   async #apply(migration) {
     const id = `${this.#collection.collectionName}:${migration.id}`
 
+    /** when the wait for another replica was last reported */
+    let announced
+
     while (true) {
-      if (await this.#claim(id)) return await this.#run(id, migration)
+      if (await this.#claim(id)) {
+        await this.#run(id, migration)
+
+        return true
+      }
 
       const row = await this.#state.findOne({ _id: id })
 
       // removed between the claim and the read; whoever did that wants it applied again
       if (row === null) continue
 
-      if (row.state === DONE) return
+      if (row.state === DONE) {
+        console.debug('Migration was applied already', { migration: id })
+
+        return false
+      }
 
       const stale = Date.now() - row.heartbeat.getTime() > LEASE
 
       if (!stale) {
+        /*
+         * The component does not serve until this returns, so a replica waiting here is a pod
+         * that is simply not up, with nothing anywhere saying why. On its own cadence rather
+         * than the poll's, which is a second.
+         */
+        if (announced === undefined || Date.now() - announced > PROGRESS) {
+          announced = Date.now()
+
+          console.info('Waiting for another replica to apply a migration', {
+            migration: id,
+            owner: row.owner
+          })
+        }
+
         await sleep(POLL)
 
         continue
@@ -68,7 +108,11 @@ export class Migrations {
         heartbeat: row.heartbeat
       })
 
-      if (await this.#steal(id, row.heartbeat)) return await this.#run(id, migration)
+      if (await this.#steal(id, row.heartbeat)) {
+        await this.#run(id, migration)
+
+        return true
+      }
     }
   }
 
@@ -118,7 +162,10 @@ export class Migrations {
    * @private
    */
   async #run(id, migration) {
-    console.info('Applying migration', { migration: id, steps: migration.steps.length })
+    const total = migration.steps.length
+    const started = Date.now()
+
+    console.info('Applying migration', { migration: id, steps: total })
 
     const beat = setInterval(() => {
       this.#state
@@ -130,8 +177,30 @@ export class Migrations {
 
     beat.unref?.()
 
+    let applying = 0
+
+    /*
+     * A backfill takes as long as the collection is large, and every replica of the group waits
+     * out the whole of it. On its own cadence rather than the heartbeat's, which is every five
+     * seconds and would say this a dozen times a minute.
+     */
+    const progress = setInterval(() => {
+      console.info('Migration is still being applied', {
+        migration: id,
+        step: applying,
+        steps: total,
+        elapsed: Date.now() - started
+      })
+    }, PROGRESS)
+
+    progress.unref?.()
+
     try {
-      for (const step of migration.steps) await this.#step(id, step)
+      for (const step of migration.steps) {
+        applying++
+
+        await this.#step(id, step)
+      }
 
       await this.#state.updateOne(
         { _id: id },
@@ -139,9 +208,10 @@ export class Migrations {
       )
     } finally {
       clearInterval(beat)
+      clearInterval(progress)
     }
 
-    console.info('Migration applied', { migration: id })
+    console.info('Migration applied', { migration: id, elapsed: Date.now() - started })
   }
 
   /** @private */
@@ -257,6 +327,9 @@ const LEASE = 30_000
 const HEARTBEAT = 5_000
 const POLL = 1_000
 
+/** how often a run that is taking its time says it is still going, and a wait that it is waiting */
+const PROGRESS = 30_000
+
 /**
  * Which process holds a claim, and nothing more: it is read by whoever takes an abandoned
  * one over, and told to whoever reads the collection. Random, because there is no identity

package/src/record.js

@@ -11,3 +11,84 @@ export function from(record) {
 
   return { id: _id, ...rest }
 }
+
+/**
+ * How this collection's records are written and read back.
+ *
+ * A property the entity declares as a moment is held as a BSON date rather than as what the
+ * entity carries. It is what the TTL monitor reads — it skips a field that is not a date,
+ * silently — and what sorts and compares as a moment rather than as text or as a number that
+ * happens to be one. The entity keeps what it declared, so nothing outside this connector
+ * learns a type only one storage has.
+ *
+ * Two ways to say it, because they differ in what userland holds rather than in what is
+ * stored: `{ string, date-time }` for an application that carries ISO strings, and
+ * `{ integer, epoch-millis }` for one that carries what `Date.now()` answers. The system
+ * timestamps of every record are the second.
+ *
+ * Top-level properties only. One nested inside an object or an array is left as it is, and
+ * `norm` refuses it, so that the declaration does not mean two things.
+ *
+ * A component that declares no moment holds the plain pair, and pays nothing for any of this.
+ */
+export function codec(properties) {
+  /** @type {Array<[string, (value: Date) => unknown]>} */
+  const read = []
+
+  for (const [name, schema] of Object.entries(properties ?? {})) {
+    const cast = READ[schema?.format]
+
+    if (cast !== undefined && schema.type === TYPES[schema.format]) read.push([name, cast])
+  }
+
+  const dates = read.map(([name]) => name)
+
+  if (dates.length === 0) return { to, from, dates }
+
+  return {
+    dates,
+
+    // one way in for both: `Date` takes the milliseconds and the ISO string alike
+    to: (entity) => convert(to(entity), dates.map((name) => [name, date])),
+
+    from: (record) => {
+      const state = from(record)
+
+      return state === null ? null : convert(state, read)
+    }
+  }
+}
+
+/**
+ * Writes into an object either `to` or `from` has just made, so nothing the caller holds is
+ * touched.
+ *
+ * @private
+ */
+function convert(record, casts) {
+  for (const [name, cast] of casts) {
+    const value = record[name]
+
+    // absent, or the null a property that has not been written to holds
+    if (value === undefined || value === null) continue
+
+    record[name] = cast(value)
+  }
+
+  return record
+}
+
+const date = (value) => new Date(value)
+
+/*
+ * What a record written before the property was declared a moment holds is what it was given,
+ * and it is answered as it is: a collection is converted by a migration rather than by every
+ * read that finds one.
+ */
+const READ = {
+  'date-time': (value) => (value instanceof Date ? value.toISOString() : value),
+  'epoch-millis': (value) => (value instanceof Date ? value.getTime() : value)
+}
+
+/** What each format is written on, so that one said of the wrong type is not acted on. */
+const TYPES = { 'date-time': 'string', 'epoch-millis': 'integer' }

package/src/storage.js

@@ -1,9 +1,10 @@
 import { Connector, exceptions } from '@toa.io/core'
 import { console } from 'openspan'
 import { translate } from './translate.js'
-import { to, from } from './record.js'
+import { codec } from './record.js'
 import { Outbox } from './outbox.js'
 import { Migrations } from './migrations.js'
+import { SYSTEM } from './system.js'
 import { ReturnDocument } from 'mongodb'
 
 export class Storage extends Connector {
@@ -25,12 +26,25 @@ export class Storage extends Connector {
   /** @type {Map<string, object>} span options per driver method */
   #spans = new Map()
 
+  /** how a record is written and read back, which depends on what the entity declares */
+  #to
+  #from
+
+  /** properties held as BSON dates, so that a criterion against one is one too */
+  #dates
+
   constructor(client, entity) {
     super()
 
     this.#client = client
     this.#entity = entity
 
+    const { to, from, dates } = codec(entity?.properties)
+
+    this.#to = to
+    this.#from = from
+    this.#dates = dates
+
     this.depends(client)
   }
 
@@ -59,19 +73,19 @@ export class Storage extends Connector {
 
     this.#spans.clear()
 
-    if (this.#entity.migrations?.length > 0)
-      this.#migrations = new Migrations(
-        this.#client.db,
-        this.#collection,
-        this.#entity.migrations
-      )
+    // the runtime's own come first: what a component declares is written against a collection
+    // whose system properties are already what this release holds them as
+    this.#migrations = new Migrations(this.#client.db, this.#collection, [
+      ...SYSTEM,
+      ...(this.#entity.migrations ?? [])
+    ])
 
-    await this.#migrations?.run()
+    await this.#migrations.run()
     await this.#outbox?.index()
   }
 
   async get(query) {
-    const { criteria, options } = translate(query)
+    const { criteria, options } = translate(query, this.#dates)
 
     // identity lookups must return deleted records, so that callers
     // can tell a deleted entity from a missing one
@@ -82,11 +96,11 @@ export class Storage extends Connector {
       this.#collection.findOne(criteria, options)
     )
 
-    return from(record)
+    return this.#from(record)
   }
 
   async find(query) {
-    const { criteria, options, sample } = translate(query)
+    const { criteria, options, sample } = translate(query, this.#dates)
 
     if (query?.options?.deleted !== true) criteria.DELETED = null
 
@@ -99,7 +113,7 @@ export class Storage extends Connector {
           )
         : await this.aggregate(criteria, options, sample)
 
-    return recordset.map((item) => from(item))
+    return recordset.map((item) => this.#from(item))
   }
 
   /** @private */
@@ -114,17 +128,17 @@ export class Storage extends Connector {
   }
 
   async stream(query = undefined) {
-    const { criteria, options } = translate(query)
+    const { criteria, options } = translate(query, this.#dates)
 
     if (query?.options?.deleted !== true) criteria.DELETED = null
 
     this.debug('find (stream)', { criteria, options })
 
-    return this.#collection.find(criteria, options).stream({ transform: from })
+    return this.#collection.find(criteria, options).stream({ transform: this.#from })
   }
 
   async add(entity, session = undefined) {
-    const record = to(entity)
+    const record = this.#to(entity)
 
     const result = await this.command('insertOne', { record }, () =>
       this.#collection.insertOne(record, { session })
@@ -139,7 +153,7 @@ export class Storage extends Connector {
       VERSION: entity.VERSION - 1
     }
 
-    const record = to(entity)
+    const record = this.#to(entity)
 
     const result = await this.command('findOneAndReplace', { criteria, record }, () =>
       this.#collection.findOneAndReplace(criteria, record, { session })
@@ -189,7 +203,7 @@ export class Storage extends Connector {
     if (entities.length === 0) return true
 
     const operations = entities.map((entity) => {
-      const record = to(entity)
+      const record = this.#to(entity)
 
       if (entity.VERSION === 1) {
         const { VERSION, ...rest } = record
@@ -241,7 +255,7 @@ export class Storage extends Connector {
   }
 
   async upsert(query, changeset, row = undefined) {
-    const { criteria, options } = translate(query)
+    const { criteria, options } = translate(query, this.#dates)
 
     if (!('DELETED' in changeset) || changeset.DELETED === null) {
       delete criteria.DELETED
@@ -266,7 +280,7 @@ export class Storage extends Connector {
 
       if (found === null) return null
 
-      const origin = from(found)
+      const origin = this.#from(found)
 
       /*
        * The post-image is `update` applied to the pre-image, computed rather than read back.
@@ -293,11 +307,11 @@ export class Storage extends Connector {
   }
 
   async ensure(query, properties, state, row = undefined) {
-    let { criteria, options } = translate(query)
+    let { criteria, options } = translate(query, this.#dates)
 
     if (query === undefined) criteria = properties
 
-    const update = { $setOnInsert: to(state) }
+    const update = { $setOnInsert: this.#to(state) }
 
     options.upsert = true
     options.returnDocument = ReturnDocument.AFTER
@@ -327,7 +341,7 @@ export class Storage extends Connector {
             })
 
       if (result.DELETED !== undefined && result.DELETED !== null) return null
-      else return from(result)
+      else return this.#from(result)
     } catch (error) {
       if (error.code === ERR_DUPLICATE_KEY)
         throw new exceptions.DuplicateException(this.#client.name)

package/src/system.js

@@ -0,0 +1,44 @@
+/**
+ * Migrations the runtime owns, applied to every collection ahead of whatever the component
+ * declares.
+ *
+ * These convert what the runtime itself writes, so they are declared here rather than in a
+ * migration every component would have to write — the same reason the outbox keeps its own
+ * indexes. A component cannot write them: it does not own the system properties, and a
+ * prototype's migrations are not inherited.
+ *
+ * They are applied once for the database, recorded beside the component's own, and named so
+ * that the two can never collide.
+ */
+export const SYSTEM = [
+  {
+    id: 'system:0001-epoch-millis',
+    steps: [
+      {
+        /*
+         * The system timestamps became dates: what sorts, compares and expires as a moment
+         * rather than as a number that happens to be one. A record written before this holds
+         * them as milliseconds, and a collection holding both would sort every number ahead of
+         * every date — so the release that brings this stops the deployment first.
+         *
+         * `CREATED` says whether a record has been converted, because every record has one.
+         * Null passes through both conversions, which is what an undeleted record's `DELETED`
+         * is; and the widening is not decoration — MongoDB makes a date from a long and
+         * refuses one from an int, and a small enough millisecond is stored as an int.
+         */
+        update: {
+          filter: { CREATED: { $type: 'number' } },
+          update: [
+            {
+              $set: {
+                CREATED: { $toDate: { $toLong: '$CREATED' } },
+                UPDATED: { $toDate: { $toLong: '$UPDATED' } },
+                DELETED: { $toDate: { $toLong: '$DELETED' } }
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+]

package/src/translate/criteria.js

@@ -2,13 +2,14 @@ import { rename } from './rename.js'
 
 /**
  * @param {import('@toa.io/core/types').storages.Node} node
+ * @param {string[]} dates properties held as BSON dates
  * @returns {import('mongodb').Filter}
  */
-export const criteria = (node) => {
+export const criteria = (node, dates = NONE) => {
   if (TYPES[node.type] === undefined)
     throw new Error(`AST parse error: unknown node type '${node.type}'`)
 
-  return TYPES[node.type](node)
+  return TYPES[node.type](node, dates)
 }
 
 const OPERATORS = {
@@ -32,23 +33,33 @@ const OPERATORS = {
 
 const TYPES = {}
 
-TYPES.LOGIC = (expression) => {
-  const left = criteria(expression.left)
-  const right = criteria(expression.right)
+TYPES.LOGIC = (expression, dates) => {
+  const left = criteria(expression.left, dates)
+  const right = criteria(expression.right, dates)
 
   return { [OPERATORS.LOGIC[expression.operator]]: [left, right] }
 }
 
-TYPES.COMPARISON = (expression) => {
-  const left = criteria(expression.left)
-  const right = criteria(expression.right)
+TYPES.COMPARISON = (expression, dates) => {
+  const left = criteria(expression.left, dates)
+  const right = criteria(expression.right, dates)
   const operator = OPERATORS.COMPARISON[expression.operator]
 
   if (operator === undefined)
     throw new Error(`AST parse error: unknown operator '${expression.operator}'`)
 
-  return { [left]: { [operator]: right } }
+  // the record holds a date where the criterion carries the string the entity declares, and a
+  // string compared against a date is a criterion that quietly matches nothing
+  const value = dates.includes(left) ? date(right) : right
+
+  return { [left]: { [operator]: value } }
 }
 
 TYPES.SELECTOR = (expression) => rename(expression.selector)
 TYPES.VALUE = (expression) => expression.value
+
+/** `=in=` and `=out=` carry a list, and every other operator one value. */
+const date = (value) =>
+  Array.isArray(value) ? value.map(date) : value === null ? null : new Date(value)
+
+const NONE = []

package/src/translate.js

@@ -5,11 +5,12 @@ const parse = { ..._criteria, ..._options }
 
 /**
  * @param {import('@toa.io/core/types').storages.Query} query
+ * @param {string[]} [dates] properties held as BSON dates, so a criterion against one is one too
  * @returns {{criteria: Object, options: Object}}
  */
-export const translate = (query) => {
+export const translate = (query, dates) => {
   const result = {
-    criteria: query?.criteria === undefined ? {} : parse.criteria(query.criteria),
+    criteria: query?.criteria === undefined ? {} : parse.criteria(query.criteria, dates),
     options: query?.options === undefined ? {} : parse.options(query.options),
     sample: query?.options?.sample
   }

package/test/migrations.test.js

@@ -1,4 +1,5 @@
-import { describe, it, beforeEach, mock } from 'node:test'
+import { describe, it, beforeEach, afterEach, mock } from 'node:test'
+import { console } from 'openspan'
 import assert from 'node:assert/strict'
 
 import { Migrations, STATE } from '../src/migrations.js'
@@ -331,3 +332,57 @@ describe('state', () => {
     assert.equal(rows.size, 1)
   })
 })
+
+describe('logging', () => {
+  let info
+  let debug
+
+  const messages = (spy) => spy.mock.calls.map((call) => call.arguments[0])
+
+  beforeEach(() => {
+    info = mock.method(console, 'info', () => undefined)
+    debug = mock.method(console, 'debug', () => undefined)
+  })
+
+  afterEach(() => {
+    info.mock.restore()
+    debug.mock.restore()
+  })
+
+  it('should report a migration it applies', async () => {
+    await run([{ id: '0001', steps: [{ update: { update: {} } }] }])
+
+    assert.ok(messages(info).includes('Applying migration'))
+    assert.ok(messages(info).includes('Migration applied'))
+  })
+
+  it('should say at debug that a migration was applied already', async () => {
+    const list = [{ id: '0001', steps: [{ update: { update: {} } }] }]
+
+    await run(list)
+
+    info.mock.resetCalls()
+    debug.mock.resetCalls()
+
+    await run(list)
+
+    assert.deepStrictEqual(messages(info), [], 'the ordinary start has nothing to report')
+    assert.ok(messages(debug).includes('Migration was applied already'))
+  })
+
+  it('should say how many of the declared ones it applied', async () => {
+    await run([
+      { id: '0001', steps: [{ update: { update: {} } }] },
+      { id: '0002', steps: [{ update: { update: {} } }] }
+    ])
+
+    const [message, attributes] = debug.mock.calls.at(-1).arguments
+
+    assert.strictEqual(message, 'Migrations checked')
+    assert.deepStrictEqual(attributes, {
+      collection: 'test_one',
+      declared: 2,
+      applied: 2
+    })
+  })
+})

package/test/record.test.js

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { to, from } from '../src/record.js'
+import { to, from, codec } from '../src/record.js'
 
 describe('to', () => {
   it('should rename id to _id', () => {
@@ -46,3 +46,93 @@ describe('from', () => {
     })
   })
 })
+
+describe('codec', () => {
+  const properties = {
+    settled: { type: 'string', format: 'date-time' },
+    endpoint: { type: 'string' }
+  }
+
+  it('should hold a plain record where the entity declares no date', () => {
+    const { to: write, from: read, dates } = codec({ endpoint: { type: 'string' } })
+
+    assert.deepStrictEqual(dates, [])
+    assert.strictEqual(write, to)
+    assert.strictEqual(read, from)
+  })
+
+  it('should write a date-time property as a date', () => {
+    const { to: write } = codec(properties)
+    const record = write({ id: '1', settled: '2026-09-05T10:00:00.000Z', endpoint: 'a.b.c' })
+
+    assert.ok(record.settled instanceof Date)
+    assert.strictEqual(record.settled.toISOString(), '2026-09-05T10:00:00.000Z')
+    assert.strictEqual(record.endpoint, 'a.b.c', 'and leaves every other property alone')
+  })
+
+  it('should read a date back as the string the entity carries', () => {
+    const { from: read } = codec(properties)
+    const entity = read({ _id: '1', settled: new Date('2026-09-05T10:00:00.000Z') })
+
+    assert.strictEqual(entity.settled, '2026-09-05T10:00:00.000Z')
+  })
+
+  it('should leave a property that has not been written to', () => {
+    const { to: write, from: read } = codec(properties)
+
+    assert.strictEqual(write({ id: '1', settled: null }).settled, null)
+    assert.strictEqual(read({ _id: '1' }).settled, undefined)
+  })
+
+  it('should read a record written before the property was declared a date', () => {
+    const { from: read } = codec(properties)
+
+    assert.strictEqual(read({ _id: '1', settled: 'not a date' }).settled, 'not a date')
+  })
+
+  it('should not modify argument', () => {
+    const { to: write } = codec(properties)
+    const entity = { id: '1', settled: '2026-09-05T10:00:00.000Z' }
+
+    write(entity)
+
+    assert.strictEqual(entity.settled, '2026-09-05T10:00:00.000Z')
+  })
+
+  it('should ignore a format said of the wrong type', () => {
+    assert.deepStrictEqual(codec({ at: { type: 'string', format: 'epoch-millis' } }).dates, [])
+    assert.deepStrictEqual(codec({ at: { type: 'integer', format: 'date-time' } }).dates, [])
+  })
+})
+
+describe('codec, epoch-millis', () => {
+  const properties = {
+    DELETED: { type: 'integer', format: 'epoch-millis' },
+    VERSION: { type: 'integer' }
+  }
+
+  const millis = 1788698804112
+
+  it('should write milliseconds as a date', () => {
+    const record = codec(properties).to({ id: '1', DELETED: millis, VERSION: 2 })
+
+    assert.ok(record.DELETED instanceof Date)
+    assert.strictEqual(record.DELETED.getTime(), millis)
+    assert.strictEqual(record.VERSION, 2, 'and leaves a plain integer alone')
+  })
+
+  it('should read a date back as milliseconds', () => {
+    const entity = codec(properties).from({ _id: '1', DELETED: new Date(millis) })
+
+    assert.strictEqual(entity.DELETED, millis)
+  })
+
+  it('should leave the null of a record that is not deleted', () => {
+    assert.strictEqual(codec(properties).to({ id: '1', DELETED: null }).DELETED, null)
+    assert.strictEqual(codec(properties).from({ _id: '1', DELETED: null }).DELETED, null)
+  })
+
+  it('should read a record written before the property was a date', () => {
+    assert.strictEqual(codec(properties).from({ _id: '1', DELETED: millis }).DELETED, millis)
+  })
+})

package/test/storage.test.js

@@ -11,11 +11,21 @@ beforeEach(async () => {
   collection = {
     collectionName: 'test',
     findOne: mock.fn(async () => null),
-    find: mock.fn(() => ({ stream: () => null }))
+    find: mock.fn(() => ({ stream: () => null })),
+    updateMany: mock.fn(async () => ({ modifiedCount: 0 }))
+  }
+
+  // the runtime's own migrations are applied to every collection, so a storage needs the
+  // database its record of them lives in
+  const state = {
+    insertOne: mock.fn(async () => ({})),
+    findOne: mock.fn(async () => null),
+    updateOne: mock.fn(async () => ({ modifiedCount: 1 }))
   }
 
   const client = {
     collection,
+    db: { collection: () => state },
     link: () => null
   }
 

package/test/translate.test.js

@@ -42,3 +42,44 @@ describe('options', () => {
     assert.deepStrictEqual(query.options.projection, { a: 1, b: 1, c: 1, _id: 1 })
   })
 })
+
+describe('dates', () => {
+  const comparison = (selector, operator, value) => ({
+    type: 'COMPARISON',
+    operator,
+    left: { type: 'SELECTOR', selector },
+    right: { type: 'VALUE', value }
+  })
+
+  it('should compare a date property against a date', () => {
+    const criteria = comparison('settled', '<', '2026-09-05T10:00:00.000Z')
+    const query = translate({ criteria }, ['settled'])
+
+    assert.ok(query.criteria.settled.$lt instanceof Date)
+    assert.strictEqual(
+      query.criteria.settled.$lt.toISOString(),
+      '2026-09-05T10:00:00.000Z'
+    )
+  })
+
+  it('should convert every value of a list', () => {
+    const criteria = comparison('settled', '=in=', ['2026-09-05T10:00:00.000Z'])
+    const query = translate({ criteria }, ['settled'])
+
+    assert.ok(query.criteria.settled.$in[0] instanceof Date)
+  })
+
+  it('should leave a property that is not a date', () => {
+    const criteria = comparison('endpoint', '==', 'a.b.c')
+    const query = translate({ criteria }, ['settled'])
+
+    assert.deepStrictEqual(query.criteria, { endpoint: { $eq: 'a.b.c' } })
+  })
+
+  it('should leave every criterion where the entity declares no date', () => {
+    const criteria = comparison('settled', '<', '2026-09-05T10:00:00.000Z')
+    const query = translate({ criteria })
+
+    assert.strictEqual(query.criteria.settled.$lt, '2026-09-05T10:00:00.000Z')
+  })
+})