@toa.io/storages.mongodb 1.0.0-alpha.319 → 1.0.0-alpha.320

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 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.320](https://github.com/toa-io/toa/compare/v1.0.0-alpha.319...v1.0.0-alpha.320) (2026-09-28)
+
+### Features
+
+* page a stream by CREATED, and stop it after its first page ([038dc52](https://github.com/toa-io/toa/commit/038dc52f2db1a4dd58c6ec58a00de8914b3d38a3))
+
+
 # [1.0.0-alpha.319](https://github.com/toa-io/toa/compare/v1.0.0-alpha.318...v1.0.0-alpha.319) (2026-09-27)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/storages.mongodb",
-  "version": "1.0.0-alpha.319",
+  "version": "1.0.0-alpha.320",
   "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.311",
-    "@toa.io/core": "1.0.0-alpha.319",
-    "@toa.io/definitions": "1.0.0-alpha.319",
+    "@toa.io/core": "1.0.0-alpha.320",
+    "@toa.io/definitions": "1.0.0-alpha.320",
     "@toa.io/generic": "1.0.0-alpha.311",
     "@toa.io/pointer": "1.0.0-alpha.311",
     "mongodb": "7.6.0",
     "openspan": "1.0.0-alpha.305"
   },
-  "gitHead": "ee4901f2bc12c33fc2098a62f2af0c29838a2c2c"
+  "gitHead": "5ef92ab939a596e4ac820965c59c015820eba7b2"
 }

package/readme.md

@@ -33,3 +33,6 @@ A [stream](/documentation/collections.md) ends with a token of changes where two
 
 A token lasts as long as the oplog of the replica set holds the point it names — its window, which
 the size of the oplog and the rate of writes decide.
+
+A read from a token scans the oplog from the point it names: it costs what the whole replica set
+wrote since, whatever of it concerns the collection.

package/src/streams.js

@@ -10,12 +10,12 @@ import { match } from './match.js'
  * A token is a position in the history MongoDB keeps of the writes committed to the collection —
  * a change stream's resume token — so what it continues from is the order writes committed in.
  * A first read takes the position before it reads anything: what committed before it is in what
- * the read finds, and what committed after it is in the next read. A page is read after the last
+ * the read finds, and what committed after it is in the next read. A window is read after the last
  * `_id` of the one before it, ordered by `_id`, which never changes, so an entry stays on one side
- * of a page boundary for the whole read.
+ * of a window boundary for the whole read.
  *
  * Where MongoDB keeps no such history — a standalone server, or a collection that keeps no images
- * of a record before a change — pages are still read, and a complete read ends with a `null`
+ * of a record before a change — windows are still read, and a complete read ends with a `null`
  * token: there is nothing to continue from.
  */
 export class Streams {
@@ -45,16 +45,16 @@ export class Streams {
    */
   async stream(translated, given) {
     const { criteria, options } = translated
-    const hash = digest(criteria)
+    const hash = digest(criteria, options.sort)
 
     if (given === undefined) return await this.#first(criteria, options, hash)
 
     const token = decode(given)
 
     if (token.h !== hash)
-      throw new exceptions.QuerySyntaxException('The token was issued for other criteria')
+      throw new exceptions.QuerySyntaxException('The token was issued for other criteria or order')
 
-    if (token.id !== undefined) return await this.#page(criteria, options, hash, token)
+    if (token.id !== undefined) return await this.#window(criteria, options, hash, token)
     if (token.p === null || !this.#history) throw lost()
 
     return await this.#changes(criteria, options, hash, token)
@@ -74,7 +74,7 @@ export class Streams {
     }
   }
 
-  async #page(criteria, options, hash, token) {
+  async #window(criteria, options, hash, token) {
     if (token.p !== null && !this.#history) throw lost()
 
     const session = this.#client().startSession({ causalConsistency: true })
@@ -84,7 +84,7 @@ export class Streams {
     const position = token.p === null ? null : { p: token.p, t: token.t }
 
     try {
-      return await this.#read(criteria, options, hash, session, position, token.id)
+      return await this.#read(criteria, options, hash, session, position, { id: token.id, c: token.c })
     } catch (exception) {
       await session.endSession()
 
@@ -94,7 +94,7 @@ export class Streams {
 
   /**
    * The position: the resume token of a change stream opened with a batch of none. Its
-   * operation time is where a page is read at, so that a member of the replica set behind it
+   * operation time is where a window is read at, so that a member of the replica set behind it
    * waits until it has replicated it.
    */
   async #position(session) {
@@ -114,16 +114,21 @@ export class Streams {
   }
 
   /**
-   * The collection, or a page of it. A read that pages is ordered by `_id` and continues after the
-   * last one; one that does not is read in the order the query states.
+   * The collection, or a window of it. A read in windows is ordered by what an entry never changes —
+   * `_id`, or `CREATED` and then `_id` — and continues after the last entry it read; one that does
+   * not is read in the order the query states. A read told to stop ends its window with the position
+   * changes continue from.
    */
   async #read(criteria, options, hash, session, position, after) {
     const limit = options.limit
-    const filter = after === undefined ? criteria : { $and: [criteria, { _id: { $gt: after } }] }
+    const order = limit === undefined && after === undefined ? null : ordered(options.sort)
+    const filter = after === undefined ? criteria : { $and: [criteria, beyond(order, after)] }
 
     const read = { ...options, session, readConcern: { level: 'majority' } }
 
-    if (limit !== undefined) read.sort = { _id: 1 }
+    delete read.stop
+
+    if (order !== null) read.sort = order
 
     const cursor = this.#collection.find(filter, read)
 
@@ -139,14 +144,18 @@ export class Streams {
       try {
         for await (const record of cursor) {
           count++
-          last = record._id
+          last = { id: record._id, c: record.CREATED instanceof Date ? record.CREATED.getTime() : undefined }
 
           yield parts.entry(from(record))
         }
 
-        if (limit !== undefined && count === limit)
-          yield parts.token(encode({ v: VERSION, p: position?.p ?? null, t: position?.t ?? null, id: last, h: hash }))
-        else yield parts.token(position === null ? null : encode({ v: VERSION, p: position.p, h: hash }))
+        if (limit !== undefined && count === limit && options.stop !== true) {
+          const window = { v: VERSION, p: position?.p ?? null, t: position?.t ?? null, id: last.id, h: hash }
+
+          if (order?.[0]?.[0] === 'CREATED') window.c = last.c
+
+          yield parts.token(encode(window))
+        } else yield parts.token(position === null ? null : encode({ v: VERSION, p: position.p, h: hash }))
       } finally {
         await cursor.close()
         await session.endSession()
@@ -267,11 +276,44 @@ function lost() {
 }
 
 /**
- * The criteria a token was issued for: a read that continues from it under other criteria would
- * answer the changes to one collection as if they were those of another.
+ * The criteria and the order a token was issued for: a read that continues from it under other
+ * criteria would answer the changes to one collection as if they were those of another, and one in
+ * another order would window from a place that order does not have.
+ */
+function digest(criteria, sort) {
+  return createHash('sha1')
+    .update(JSON.stringify([criteria, sort ?? null]))
+    .digest('base64url')
+    .slice(0, 16)
+}
+
+/**
+ * The order of a read in windows: `_id` ascending unless the query orders by `_id` or `CREATED`,
+ * which an entry never changes, and `_id` after `CREATED`, which entries may share. An order by
+ * anything else could move an entry across a window boundary mid-read, and is refused.
  */
-function digest(criteria) {
-  return createHash('sha1').update(JSON.stringify(criteria)).digest('base64url').slice(0, 16)
+function ordered(sort) {
+  if (sort === undefined || sort.length === 0) return [['_id', 1]]
+
+  for (const [property] of sort)
+    if (!UNMOVING.includes(property))
+      throw new exceptions.QuerySyntaxException(`A stream read in windows is not ordered by '${property}', which changes`)
+
+  const [[first, direction]] = sort
+
+  return first === '_id' ? [['_id', direction]] : [['CREATED', direction], ['_id', direction]]
+}
+
+/** What comes after the last entry a window read, in its order. */
+function beyond(order, after) {
+  const [[first, direction]] = order
+  const past = direction === 1 ? '$gt' : '$lt'
+
+  if (first === '_id') return { _id: { [past]: after.id } }
+
+  const c = new Date(after.c)
+
+  return { $or: [{ CREATED: { [past]: c } }, { CREATED: c, _id: { [past]: after.id } }] }
 }
 
 function encode(token) {
@@ -295,6 +337,7 @@ function decode(given) {
     typeof token.h === 'string' &&
     (typeof token.p === 'string' || token.p === null) &&
     (token.id === undefined || typeof token.id === 'string') &&
+    (token.c === undefined || typeof token.c === 'number') &&
     (token.id === undefined || token.t === null || typeof token.t === 'string')
 
   if (!valid) throw lost()
@@ -307,6 +350,9 @@ const VERSION = 1
 
 const LOGICAL = ['$and', '$or', '$nor']
 
+/** what an entry never changes, and so what a read in windows may be ordered by */
+const UNMOVING = ['_id', 'CREATED']
+
 /** what ends a change stream: the collection it follows is gone or renamed */
 const ENDINGS = ['drop', 'rename', 'dropDatabase', 'invalidate']
 

package/src/translate/options.js

@@ -15,6 +15,9 @@ export const options = (options) => {
   if (options.projection) {
     result.projection = projection(options.projection)
   }
+  if (options.stop) {
+    result.stop = true
+  }
 
   return result
 }

package/test/storage.test.js

@@ -28,11 +28,13 @@ beforeEach(async () => {
   await storage.open()
 })
 
-function cursor() {
+function cursor(records = []) {
   return {
-    hasNext: async () => false,
+    hasNext: async () => records.length > 0,
     close: async () => undefined,
-    async *[Symbol.asyncIterator]() {}
+    async *[Symbol.asyncIterator]() {
+      yield* records
+    }
   }
 }
 
@@ -133,12 +135,39 @@ describe('stream', () => {
     assert.deepStrictEqual(parts, [{ token: null }])
   })
 
-  it('should read a page ordered by id', async () => {
+  it('should read a window ordered by id', async () => {
     await storage.stream({ options: { limit: 2 } })
 
-    assert.deepStrictEqual(read()[1].sort, { _id: 1 })
+    assert.deepStrictEqual(read()[1].sort, [['_id', 1]])
     assert.equal(read()[1].limit, 2)
   })
+
+  it('should read a window newest first, and by id where entries share a time', async () => {
+    await storage.stream({ options: { limit: 2, sort: [['CREATED', 'desc']] } })
+
+    assert.deepStrictEqual(read()[1].sort, [['CREATED', -1], ['_id', -1]])
+  })
+
+  it('should refuse a window ordered by what an entry changes', async () => {
+    await assert.rejects(
+      storage.stream({ options: { limit: 2, sort: [['title', 'asc']] } }),
+      (error) => error.code === 221
+    )
+  })
+
+  it('should end a window it was told to stop at with no window token', async () => {
+    const found = [
+      { _id: 'a', CREATED: new Date(2), VERSION: 1 },
+      { _id: 'b', CREATED: new Date(1), VERSION: 1 }
+    ]
+
+    collection.find.mock.mockImplementationOnce(() => cursor(found))
+
+    const stream = await storage.stream({ options: { limit: 2, stop: true } })
+    const parts = await stream.toArray()
+
+    assert.deepStrictEqual(parts.at(-1), { token: null })
+  })
 })
 
 describe('converge', () => {