@toa.io/storages.mongodb 1.0.0-alpha.31 → 1.0.0-alpha.310

package/test/record.test.js

@@ -1,34 +1,32 @@
-'use strict'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
 
-const {
-  to,
-  from
-} = require('../src/record')
+import { to, from, codec } from '../src/record.js'
 
 describe('to', () => {
   it('should rename id to _id', () => {
-    /** @type {toa.core.storages.Record} */
+    /** @type {import('@toa.io/core/types').storages.Record} */
     const entity = {
       id: '1',
-      _version: 0
+      VERSION: 0
     }
     const record = to(entity)
 
-    expect(record).toMatchObject({ _id: '1' })
+    assert.partialDeepStrictEqual(record, { _id: '1' })
   })
 
   it('should not modify argument', () => {
-    /** @type {toa.core.storages.Record} */
+    /** @type {import('@toa.io/core/types').storages.Record} */
     const entity = {
       id: '1',
-      _version: 0
+      VERSION: 0
     }
 
     to(entity)
 
-    expect(entity).toStrictEqual({
+    assert.deepStrictEqual(entity, {
       id: '1',
-      _version: 0
+      VERSION: 0
     })
   })
 })
@@ -38,28 +36,103 @@ describe('from', () => {
     /** @type {toa.mongodb.Record} */
     const record = {
       _id: '1',
-      _version: 0
+      VERSION: 0
     }
     const entity = from(record)
 
-    expect(entity).toStrictEqual({
+    assert.deepStrictEqual(entity, {
       id: '1',
-      _version: 0
+      VERSION: 0
     })
   })
+})
+
+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', () => {
-    /** @type {toa.mongodb.Record} */
-    const record = {
-      _id: '1',
-      _version: 0
-    }
+    const { to: write } = codec(properties)
+    const entity = { id: '1', settled: '2026-09-05T10:00:00.000Z' }
 
-    from(record)
+    write(entity)
 
-    expect(record).toStrictEqual({
-      _id: '1',
-      _version: 0
-    })
+    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

@@ -0,0 +1,217 @@
+import { describe, it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
+
+import { Storage } from '../src/storage.js'
+
+let collection
+let db
+let storage
+
+beforeEach(async () => {
+  collection = {
+    collectionName: 'test',
+    findOne: mock.fn(async () => null),
+    find: mock.fn(() => ({ stream: () => null })),
+    updateMany: mock.fn(async () => ({ modifiedCount: 0 })),
+    updateOne: mock.fn(async () => ({ upsertedCount: 0, modifiedCount: 0 }))
+  }
+
+  db = { collection: mock.fn(() => null) }
+
+  const client = { collection, db, link: () => null }
+
+  storage = new Storage(client, { schema: { properties: {} } })
+
+  await storage.open()
+})
+
+describe('open', () => {
+  it('should not touch the migrations record where the entity declares none', () => {
+    assert.equal(db.collection.mock.callCount(), 0)
+  })
+})
+
+describe('get', () => {
+  it('should filter deleted', async () => {
+    await storage.get({})
+
+    assert.ok(
+      collection.findOne.mock.calls.some(
+        (call) =>
+          call.arguments.length === 2 &&
+          isDeepStrictEqual(call.arguments[0], { DELETED: null }) &&
+          isDeepStrictEqual(call.arguments[1], {})
+      )
+    )
+  })
+
+  it('should filter deleted with sort', async () => {
+    await storage.get({ options: { sort: [['CREATED', 'desc']] } })
+
+    assert.ok(
+      collection.findOne.mock.calls.some(
+        (call) =>
+          call.arguments.length === 2 &&
+          isDeepStrictEqual(call.arguments[0], { DELETED: null }) &&
+          isDeepStrictEqual(call.arguments[1], { sort: [['CREATED', -1]] })
+      )
+    )
+  })
+
+  it('should not filter deleted if queried by id', async () => {
+    const id = 'bcb6780f50e243348cad40ed6b5ef575'
+
+    await storage.get({ id })
+
+    assert.ok(
+      collection.findOne.mock.calls.some(
+        (call) =>
+          call.arguments.length === 2 &&
+          isDeepStrictEqual(call.arguments[0], { _id: id }) &&
+          isDeepStrictEqual(call.arguments[1], {})
+      )
+    )
+  })
+
+  it('should not filter deleted if requested', async () => {
+    await storage.get({ options: { deleted: true } })
+
+    assert.ok(
+      collection.findOne.mock.calls.some(
+        (call) =>
+          call.arguments.length === 2 &&
+          isDeepStrictEqual(call.arguments[0], {}) &&
+          isDeepStrictEqual(call.arguments[1], {})
+      )
+    )
+  })
+})
+
+describe('stream', () => {
+  it('should filter deleted', async () => {
+    await storage.stream()
+
+    assert.ok(
+      collection.find.mock.calls.some(
+        (call) =>
+          call.arguments.length === 2 &&
+          isDeepStrictEqual(call.arguments[0], { DELETED: null }) &&
+          isDeepStrictEqual(call.arguments[1], {})
+      )
+    )
+  })
+
+  it('should filter deleted with sort', async () => {
+    await storage.stream({ options: { sort: [['CREATED', 'desc']] } })
+
+    assert.ok(
+      collection.find.mock.calls.some(
+        (call) =>
+          call.arguments.length === 2 &&
+          isDeepStrictEqual(call.arguments[0], { DELETED: null }) &&
+          isDeepStrictEqual(call.arguments[1], { sort: [['CREATED', -1]] })
+      )
+    )
+  })
+
+  it('should not filter deleted if requested', async () => {
+    await storage.stream({ options: { deleted: true } })
+
+    assert.ok(
+      collection.find.mock.calls.some(
+        (call) =>
+          call.arguments.length === 2 &&
+          isDeepStrictEqual(call.arguments[0], {}) &&
+          isDeepStrictEqual(call.arguments[1], {})
+      )
+    )
+  })
+})
+
+describe('converge', () => {
+  const record = { id: 'a1', VERSION: 4, REGION: 1, status: 'paid' }
+
+  const call = () => collection.updateOne.mock.calls[0].arguments
+
+  it('should select by id alone, so that what is absent is upserted', async () => {
+    await storage.converge(record)
+
+    const [criteria, , options] = call()
+
+    assert.deepEqual(criteria, { _id: 'a1' })
+    assert.equal(options.upsert, true)
+  })
+
+  it('should supersede a lower version', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+    const [older] = pipeline[0].$replaceWith.$cond[0].$or
+
+    assert.deepEqual(older, { $lt: [{ $ifNull: ['$VERSION', 0] }, 4] })
+  })
+
+  it('should supersede an equal version written by an outranked region', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+    const [, tied] = pipeline[0].$replaceWith.$cond[0].$or
+
+    assert.deepEqual(tied.$and, [
+      { $eq: ['$VERSION', 4] },
+      { $gt: [{ $ifNull: ['$REGION', 0] }, 1] }
+    ])
+  })
+
+  it('should leave what is stored where it does not', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+
+    assert.equal(pipeline[0].$replaceWith.$cond[2], '$$ROOT')
+  })
+
+  it('should write the record as a literal, so that a `$` value is not a field path', async () => {
+    await storage.converge({ ...record, status: '$paid' })
+
+    const [, pipeline] = call()
+    const written = pipeline[0].$replaceWith.$cond[1].$literal
+
+    assert.equal(written._id, 'a1')
+    assert.equal(written.status, '$paid')
+    assert.equal(written.id, undefined)
+  })
+
+  it('should answer true where it inserted', async () => {
+    collection.updateOne.mock.mockImplementationOnce(async () => ({
+      upsertedCount: 1,
+      modifiedCount: 0
+    }))
+
+    assert.equal(await storage.converge(record), true)
+  })
+
+  it('should answer true where it superseded', async () => {
+    collection.updateOne.mock.mockImplementationOnce(async () => ({
+      upsertedCount: 0,
+      modifiedCount: 1
+    }))
+
+    assert.equal(await storage.converge(record), true)
+  })
+
+  it('should read a record that lacks a region as the first one', async () => {
+    await storage.converge(record)
+
+    const [, pipeline] = call()
+    const [, tied] = pipeline[0].$replaceWith.$cond[0].$or
+
+    // the migration writes it, and one that reached here without it would win every tie
+    assert.deepEqual(tied.$and[1].$gt[0], { $ifNull: ['$REGION', 0] })
+  })
+
+  it('should answer false where it changed nothing, and not throw', async () => {
+    assert.equal(await storage.converge(record), false)
+  })
+})

package/test/translate.test.js

@@ -1,33 +1,85 @@
-'use strict'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { translate } = require('../src/translate')
+import { translate } from '../src/translate.js'
 
 describe('options', () => {
   it('should translate omit', () => {
     const options = { omit: 10 }
     const query = translate({ options })
 
-    expect(query.options.skip).toStrictEqual(options.omit)
+    assert.deepStrictEqual(query.options.skip, options.omit)
   })
 
   it('should translate limit', () => {
     const options = { limit: 10 }
     const query = translate({ options })
 
-    expect(query.options.limit).toStrictEqual(options.limit)
+    assert.deepStrictEqual(query.options.limit, options.limit)
   })
 
   it('should translate sort', () => {
-    const options = { sort: [['a', 'asc'], ['b', 'desc'], ['id', 'asc']] }
+    const options = {
+      sort: [
+        ['a', 'asc'],
+        ['b', 'desc'],
+        ['id', 'asc']
+      ]
+    }
     const query = translate({ options })
 
-    expect(query.options.sort).toStrictEqual([['a', 1], ['b', -1], ['_id', 1]])
+    assert.deepStrictEqual(query.options.sort, [
+      ['a', 1],
+      ['b', -1],
+      ['_id', 1]
+    ])
   })
 
   it('should translate projection', () => {
     const options = { projection: ['a', 'b', 'c', 'id'] }
     const query = translate({ options })
 
-    expect(query.options.projection).toStrictEqual({ a: 1, b: 1, c: 1, _id: 1 })
+    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')
   })
 })

package/types/connection.d.ts

@@ -6,26 +6,32 @@ import type {
   FindOneAndReplaceOptions,
   FindOneAndUpdateOptions,
   FindOptions,
-  UpdateFilter,
+  UpdateFilter
 } from 'mongodb'
 
 import type { Connector } from '@toa.io/core'
-import type { Record } from './record'
+import type { Record } from './record.d.ts'
 
-declare namespace toa.mongodb{
+declare namespace toa.mongodb {
+  interface Connection extends Connector {
+    get(query: Filter<Record>, options?: FindOptions<Record>): Promise<Record>
 
-  interface Connection extends Connector{
-    get (query: Filter<Record>, options?: FindOptions<Record>): Promise<Record>
+    find(query: Filter<Record>, options?: FindOptions<Record>): Promise<Record[]>
 
-    find (query: Filter<Record>, options?: FindOptions<Record>): Promise<Record[]>
+    add(record: Record): Promise<boolean>
 
-    add (record: Record): Promise<boolean>
+    addMany(records: Record[]): Promise<boolean>
 
-    addMany (records: Record[]): Promise<boolean>
+    replace(
+      query: Filter<Record>,
+      record: UpdateFilter<Record>,
+      options?: FindOneAndReplaceOptions
+    ): Promise<any>
 
-    replace (query: Filter<Record>, record: UpdateFilter<Record>, options?: FindOneAndReplaceOptions): Promise<any>
-
-    update (query: Filter<Record>, update: UpdateFilter<Record>, options?: FindOneAndUpdateOptions): Promise<any>
+    update(
+      query: Filter<Record>,
+      update: UpdateFilter<Record>,
+      options?: FindOneAndUpdateOptions
+    ): Promise<any>
   }
-
 }

package/types/pointer.d.ts

@@ -1,10 +1,8 @@
 import type { Pointer as Base } from '@toa.io/pointer/types'
 
 declare namespace toa.mongodb {
-
-    interface Pointer extends Base {
-        db: string
-        collection: string
-    }
-
+  interface Pointer extends Base {
+    db: string
+    collection: string
+  }
 }

package/types/record.d.ts

@@ -1,12 +1,10 @@
 declare namespace toa.mongodb {
+  interface Record {
+    _id: string
+    VERSION: number
 
-    interface Record {
-        _id: string
-        _version: number
-
-        [key: string]: any
-    }
-
+    [key: string]: any
+  }
 }
 
 export type Record = toa.mongodb.Record

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

package/src/deployment.js

@@ -1,22 +0,0 @@
-'use strict'
-
-const { createVariables } = require('@toa.io/pointer')
-
-const deployment = (instances, annotation) => {
-  const requests = instances.map((instance) => createRequest(instance))
-  const variables = createVariables(ID, annotation, requests)
-
-  return { variables }
-}
-
-function createRequest (instance) {
-  return {
-    group: instance.locator.label,
-    selectors: [instance.locator.id]
-  }
-}
-
-const ID = 'mongodb'
-
-exports.ID = ID
-exports.deployment = deployment