@toa.io/storages.mongodb 1.0.0-alpha.33 → 1.0.0-alpha.331

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/storage.js CHANGED
@@ -1,202 +1,635 @@
1
- 'use strict'
1
+ import { Connector, exceptions } from '@toa.io/core'
2
+ import { console } from 'openspan'
3
+ import { translate } from './translate.js'
4
+ import { codec } from './record.js'
5
+ import { Inbox } from './inbox.js'
6
+ import { Outbox } from './outbox.js'
7
+ import { Migrations } from './migrations.js'
8
+ import { Streams } from './streams.js'
9
+ import { conflicted, query } from './measurements.js'
10
+ import { ReturnDocument } from 'mongodb'
11
+
12
+ export class Storage extends Connector {
13
+ #client
14
+
15
+ /** @type {import('mongodb').Collection} */
16
+ #collection
17
+ #entity
2
18
 
3
- const { Connector, exceptions } = require('@toa.io/core')
19
+ /**
20
+ * @type {Outbox | undefined} absent when nothing consumes this component's events, or when
21
+ * the deployment cannot run transactions
22
+ */
23
+ #outbox
4
24
 
5
- const { translate } = require('./translate')
6
- const { to, from } = require('./record')
25
+ /**
26
+ * @type {Inbox | undefined} absent unless the component declares `once` somewhere; a
27
+ * deployment that cannot commit one with the entity does not boot, so this is present
28
+ * wherever it was asked for
29
+ */
30
+ #inbox
7
31
 
8
- class Storage extends Connector {
9
- #connection
10
- #entity
32
+ /** @type {Migrations | undefined} absent where the component declares no migrations */
33
+ #migrations
34
+
35
+ /** @type {Map<string, object>} span options per driver method */
36
+ #spans = new Map()
37
+
38
+ /** @type {Streams | undefined} what a stream reads, and where it continues from */
39
+ #streams
11
40
 
12
- constructor (connection, entity) {
41
+ /** how a record is written and read back, which depends on what the entity declares */
42
+ #to
43
+ #from
44
+ #changes
45
+
46
+ /** properties held as BSON dates, so that a criterion against one is one too */
47
+ #dates
48
+
49
+ constructor(client, entity) {
13
50
  super()
14
51
 
15
- this.#connection = connection
52
+ this.#client = client
16
53
  this.#entity = entity
17
54
 
18
- this.depends(connection)
55
+ const { to, from, changes, dates } = codec(entity?.properties)
56
+
57
+ this.#to = to
58
+ this.#from = from
59
+ this.#changes = changes
60
+ this.#dates = dates
61
+
62
+ this.depends(client)
63
+ }
64
+
65
+ get raw() {
66
+ return this.#collection
67
+ }
68
+
69
+ /**
70
+ * The outbox is offered only where a row can be committed atomically with the entity.
71
+ * Without that it would be a second write with a window in front of it — worse than the
72
+ * inline emission it replaces — so the storage simply does not advertise it.
73
+ */
74
+ get outbox() {
75
+ return this.#outbox
76
+ }
77
+
78
+ get inbox() {
79
+ return this.#inbox
80
+ }
81
+
82
+ /** This storage can record a call, given a deployment that can commit one. */
83
+ get claims() {
84
+ return true
85
+ }
86
+
87
+ /** This storage applies what a component's `migrations` directory declares. */
88
+ get migrates() {
89
+ return true
90
+ }
91
+
92
+ /** This storage converges. */
93
+ get converges() {
94
+ return true
95
+ }
96
+
97
+ async open() {
98
+ this.#collection = this.#client.collection
99
+
100
+ if (this.#client.outbox !== undefined) this.#outbox = new Outbox(this.#client.outbox)
101
+ if (this.#client.inbox !== undefined) this.#inbox = new Inbox(this.#client.inbox)
102
+
103
+ this.#spans.clear()
104
+
105
+ if (this.#entity.migrations?.length > 0) {
106
+ this.#migrations = new Migrations(
107
+ this.#client.db,
108
+ this.#collection,
109
+ this.#entity.migrations
110
+ )
111
+
112
+ await this.#migrations.run()
113
+ }
114
+
115
+ await this.#outbox?.index()
116
+ await this.#inbox?.index()
117
+
118
+ this.#streams = new Streams(
119
+ this.#collection,
120
+ () => this.#client.instance.client,
121
+ this.#from,
122
+ this.#client.transactional === true && (await this.#images())
123
+ )
19
124
  }
20
125
 
21
- async open () {
22
- await this.index()
126
+ /** Whether the collection keeps what a record was before a change, which a migration says. */
127
+ async #images() {
128
+ const collection = await this.#client.db
129
+ .listCollections({ name: this.#collection.collectionName })
130
+ .next()
131
+
132
+ return collection?.options?.changeStreamPreAndPostImages?.enabled === true
23
133
  }
24
134
 
25
- async get (query) {
26
- const { criteria, options } = translate(query)
27
- const record = await this.#connection.get(criteria, options)
135
+ async get(query) {
136
+ const { criteria, options } = translate(query, this.#dates)
137
+
138
+ // identity lookups must return deleted records, so that callers
139
+ // can tell a deleted entity from a missing one
140
+ if (query?.id === undefined && query?.options?.deleted !== true)
141
+ criteria.DELETED = null
28
142
 
29
- return from(record)
143
+ const record = await this.command('findOne', { criteria, options }, () =>
144
+ this.#collection.findOne(criteria, options)
145
+ )
146
+
147
+ return this.#from(record)
30
148
  }
31
149
 
32
- async find (query) {
33
- const { criteria, options } = translate(query)
34
- const recordset = await this.#connection.find(criteria, options)
150
+ async find(query) {
151
+ const { criteria, options, sample } = translate(query, this.#dates)
152
+
153
+ if (query?.options?.deleted !== true) criteria.DELETED = null
35
154
 
36
- return recordset.map((item) => from(item))
155
+ const recordset =
156
+ sample === undefined
157
+ ? await this.command(
158
+ 'find',
159
+ { criteria, options },
160
+ async () => await this.#collection.find(criteria, options).toArray()
161
+ )
162
+ : await this.aggregate(criteria, options, sample)
163
+
164
+ return recordset.map((item) => this.#from(item))
37
165
  }
38
166
 
39
- async stream (query = undefined) {
40
- const { criteria, options } = translate(query)
167
+ /** @private */
168
+ async aggregate(criteria, options, sample) {
169
+ const pipeline = toPipeline(criteria, options, sample)
41
170
 
42
- return await this.#connection.stream(criteria, options, from)
171
+ return await this.command(
172
+ 'aggregate',
173
+ { pipeline },
174
+ async () => await this.#collection.aggregate(pipeline).toArray()
175
+ )
43
176
  }
44
177
 
45
- async add (entity) {
46
- const record = to(entity)
47
- const result = await this.#connection.add(record)
178
+ async stream(query = undefined) {
179
+ const { criteria, options } = translate(query, this.#dates)
180
+
181
+ if (query?.options?.deleted !== true) criteria.DELETED = null
182
+
183
+ this.debug('find (stream)', { criteria, options })
184
+
185
+ return this.#streams.stream({ criteria, options }, query?.options?.token)
186
+ }
187
+
188
+ async add(entity, session = undefined) {
189
+ const record = this.#to(entity)
190
+
191
+ const result = await this.command('insertOne', { record }, () =>
192
+ this.#collection.insertOne(record, { session })
193
+ )
48
194
 
49
195
  return result.acknowledged
50
196
  }
51
197
 
52
- async set (entity) {
198
+ async set(entity, session = undefined) {
53
199
  const criteria = {
54
200
  _id: entity.id,
55
- _version: entity._version - 1
201
+ VERSION: entity.VERSION - 1
56
202
  }
57
- const result = await this.#connection.replace(criteria, to(entity))
203
+
204
+ const record = this.#to(entity)
205
+
206
+ const result = await this.command('findOneAndReplace', { criteria, record }, () =>
207
+ this.#collection.findOneAndReplace(criteria, record, { session })
208
+ )
209
+
210
+ // the version moved under this write: whoever asked either retries it or raises
211
+ if (result === null) conflicted(this.#collection.collectionName)
58
212
 
59
213
  return result !== null
60
214
  }
61
215
 
62
- async store (entity) {
216
+ async store(entity, row = undefined, call = undefined, attempt = 0) {
217
+ const writes = row !== undefined && this.#outbox !== undefined
218
+ const records = call !== undefined && this.#inbox !== undefined
219
+
220
+ let committed
221
+
63
222
  try {
64
- if (entity._version === 1) {
65
- return await this.add(entity)
66
- } else {
67
- return await this.set(entity)
223
+ if (!writes && !records) {
224
+ if (entity.VERSION === 1) return await this.add(entity)
225
+ else return await this.set(entity)
68
226
  }
69
- } catch (error) {
70
- if (error.code === ERR_DUPLICATE_KEY) {
71
227
 
72
- const id = error.keyPattern === undefined
73
- ? error.message.includes(' index: _id_ ') // AWS DocumentDB
74
- : error.keyPattern._id === 1
228
+ committed = await this.#client.transaction(async (session) => {
229
+ /*
230
+ * First, so that a call already made pays for nothing else: the duplicate key is the
231
+ * whole mechanism, and it takes the entity write down with it. Caught here rather than
232
+ * around the transaction, because here is where which key refused it is known — the
233
+ * driver's message is the only other thing that says, and it is worded differently by
234
+ * DocumentDB.
235
+ */
236
+ if (records)
237
+ try {
238
+ await this.#inbox.insert(call, session)
239
+ } catch (error) {
240
+ if (error?.code !== ERR_DUPLICATE_KEY) throw error
241
+
242
+ await session.abortTransaction()
243
+
244
+ return MADE
245
+ }
246
+
247
+ const ok =
248
+ entity.VERSION === 1
249
+ ? await this.add(entity, session)
250
+ : await this.set(entity, session)
251
+
252
+ // a lost compare-and-swap must take the row down with it, or a retried transition
253
+ // leaves a row for a write that never happened
254
+ if (!ok) {
255
+ await session.abortTransaction()
75
256
 
76
- if (id) {
77
257
  return false
78
- } else {
79
- throw new exceptions.DuplicateException()
80
258
  }
81
- } else {
82
- throw error
83
- }
259
+
260
+ if (writes) await this.#outbox.insert(row, session)
261
+
262
+ return true
263
+ })
264
+ } catch (error) {
265
+ console.error('MongoDB error', error)
266
+
267
+ const retry = await retriable(error, attempt)
268
+
269
+ if (retry) return await this.store(entity, row, call, attempt + 1)
270
+ else return false
84
271
  }
272
+
273
+ /*
274
+ * Outside the catch: the call has been made and what it changed is changed, which is not a
275
+ * driver failure and not worth another attempt. Raised rather than answered `false`, which
276
+ * means a lost compare-and-swap and *is* worth one.
277
+ */
278
+ if (committed === MADE) throw new exceptions.DuplicateCallException(call.id)
279
+
280
+ return committed === true
85
281
  }
86
282
 
87
- async upsert (query, changeset) {
88
- const {
89
- criteria,
90
- options
91
- } = translate(query)
283
+ /**
284
+ * A transition over a set, committed as one compare-and-swap: every record is written at the
285
+ * version it was read at, and its rows with it, or nothing is and the answer is `false`.
286
+ */
287
+ async massStore(entities, rows = undefined, attempt = 0) {
288
+ if (entities.length === 0) return true
289
+
290
+ const operations = entities.map((entity) => {
291
+ const record = this.#to(entity)
292
+
293
+ if (entity.VERSION === 1) {
294
+ const { VERSION, ...rest } = record
295
+
296
+ return {
297
+ // one the read did not find: absent, and inserted, or deleted, and revived — a live
298
+ // one makes the upsert collide on `_id`, which is the swap lost
299
+ updateOne: {
300
+ filter: { _id: entity.id, DELETED: { $ne: null } },
301
+ update: {
302
+ $set: {
303
+ ...rest,
304
+ DELETED: null
305
+ },
306
+ $inc: { VERSION: 1 }
307
+ },
308
+ upsert: true
309
+ }
310
+ }
311
+ } else
312
+ return {
313
+ replaceOne: {
314
+ filter: { _id: entity.id, VERSION: entity.VERSION - 1 },
315
+ replacement: record
316
+ }
317
+ }
318
+ })
319
+
320
+ let committed
92
321
 
93
- if (!('_deleted' in changeset) || changeset._deleted === null) {
94
- delete criteria._deleted
95
- changeset._deleted = null
322
+ try {
323
+ committed = await this.#client.transaction(async (session) => {
324
+ let result
325
+
326
+ try {
327
+ result = await this.command(
328
+ 'bulkWrite',
329
+ { operations: operations.length },
330
+ async () => await this.#collection.bulkWrite(operations, { session })
331
+ )
332
+ } catch (error) {
333
+ if (!collidedOnId(error)) throw error
334
+
335
+ await session.abortTransaction()
336
+
337
+ return false
338
+ }
339
+
340
+ // a replacement whose version moved matches nothing, which is no error to a bulk
341
+ // write: without this the rest of the set would be committed around it
342
+ if (result.matchedCount + result.upsertedCount < operations.length) {
343
+ await session.abortTransaction()
344
+
345
+ return false
346
+ }
347
+
348
+ if (rows !== undefined && this.#outbox !== undefined)
349
+ await this.#outbox.insertMany(rows, session)
350
+
351
+ return true
352
+ })
353
+ } catch (error) {
354
+ console.error('MongoDB error', error)
355
+
356
+ const retry = await retriable(error, attempt)
357
+
358
+ if (retry) return await this.massStore(entities, rows, attempt + 1)
359
+ else return false
96
360
  }
97
361
 
98
- const update = {
99
- $set: { ...changeset },
100
- $inc: { _version: 1 }
362
+ // counted once per set: one commit lost, and one retry
363
+ if (committed !== true) conflicted(this.#collection.collectionName)
364
+
365
+ return committed === true
366
+ }
367
+
368
+ /**
369
+ * The filter selects by `_id` alone, so it always matches what is there and upserts what is
370
+ * not, and the rule is the pipeline: either the incoming document replaces the stored one, or
371
+ * `$$ROOT` stays where it is and nothing changes. That keeps the three answers apart — a
372
+ * record never seen is an upsert, a superseded one is a modification, and a stale one is
373
+ * neither — where putting the rule in the filter would make absence and staleness one and the
374
+ * same miss, and then have the upsert collide on `_id` to say so.
375
+ *
376
+ * `$literal` because a value in a pipeline is an expression, so a property holding a string
377
+ * that begins with `$` would otherwise be read as a field path.
378
+ *
379
+ * `$ifNull` twice, and for two reasons. On the upsert path the pipeline runs over the base
380
+ * document the filter builds, which is `{ _id }`, so a missing `VERSION` reads as `0` — the
381
+ * version an entity holds before its first write. And a record that somehow reached here
382
+ * without a `REGION` reads as the first region, which is what the prototype's migration
383
+ * writes into one: without that, such a record would lose no tie and would beat every
384
+ * equal-version write from anywhere, silently and for good.
385
+ */
386
+ async converge(record) {
387
+ const document = this.#to(record)
388
+
389
+ const supersedes = {
390
+ $or: [
391
+ { $lt: [{ $ifNull: ['$VERSION', 0] }, document.VERSION] },
392
+ {
393
+ $and: [
394
+ { $eq: ['$VERSION', document.VERSION] },
395
+ { $gt: [{ $ifNull: ['$REGION', FIRST] }, document.REGION] }
396
+ ]
397
+ }
398
+ ]
101
399
  }
102
400
 
103
- options.returnDocument = 'after'
401
+ const pipeline = [
402
+ { $replaceWith: { $cond: [supersedes, { $literal: document }, '$$ROOT'] } }
403
+ ]
104
404
 
105
- const result = await this.#connection.update(criteria, update, options)
405
+ const result = await this.command(
406
+ 'updateOne',
407
+ { criteria: { _id: document._id }, pipeline },
408
+ () => this.#collection.updateOne({ _id: document._id }, pipeline, { upsert: true })
409
+ )
106
410
 
107
- return from(result)
411
+ return result.upsertedCount === 1 || result.modifiedCount === 1
108
412
  }
109
413
 
110
- async index () {
111
- const indexes = []
112
-
113
- if (this.#entity.unique !== undefined) {
114
- for (const [name, fields] of Object.entries(this.#entity.unique)) {
115
- const sparse = this.checkFields(fields)
116
- const unique = await this.uniqueIndex(name, fields, sparse)
414
+ async upsert(query, changeset, row = undefined, call = undefined) {
415
+ const records = call !== undefined && this.#inbox !== undefined
416
+ const { criteria, options } = translate(query, this.#dates)
117
417
 
118
- indexes.push(unique)
119
- }
418
+ if (!('DELETED' in changeset) || changeset.DELETED === null) {
419
+ delete criteria.DELETED
420
+ changeset.DELETED = null
120
421
  }
121
422
 
122
- if (this.#entity.index !== undefined) {
123
- for (const [suffix, declaration] of Object.entries(this.#entity.index)) {
124
- const name = 'index_' + suffix
125
- const fields = Object.fromEntries(Object.entries(declaration)
126
- .map(([name, type]) => [name, INDEX_TYPES[type]]))
423
+ const update = {
424
+ $set: this.#changes(changeset),
425
+ $inc: { VERSION: 1 }
426
+ }
127
427
 
128
- const sparse = this.checkFields(Object.keys(fields))
428
+ // BEFORE, so that the filter is applied once and atomically and the pre-image comes back
429
+ // with it — an assignment is the one event whose images are the write's own
430
+ options.returnDocument = ReturnDocument.BEFORE
431
+
432
+ const apply = async (session) => {
433
+ const found = await this.command(
434
+ 'findOneAndUpdate',
435
+ { criteria, update, options },
436
+ () => this.#collection.findOneAndUpdate(criteria, update, { ...options, session })
437
+ )
438
+
439
+ if (found === null) return null
440
+
441
+ const origin = this.#from(found)
442
+
443
+ /*
444
+ * The post-image is `update` applied to the pre-image, computed rather than read back.
445
+ * That is exact, not approximate: `$set` on top-level keys is a spread (entity property
446
+ * names cannot contain dots, so a changeset never carries a path), and `VERSION` is
447
+ * incremented by one. It is also a coupling — an operator added to `update` and not
448
+ * mirrored here diverges silently — which `features/events/outbox.feature` guards.
449
+ */
450
+ const state = { ...origin, ...changeset, VERSION: origin.VERSION + 1 }
451
+
452
+ // an assignment's event is the write's own images, so they are filled in here whether
453
+ // or not the row is going to be committed
454
+ if (row !== undefined) row.event = { origin, state, ...row.event }
455
+
456
+ /*
457
+ * The reply is what a duplicate is answered with, and an assignment answers the post-image
458
+ * where its algorithm named nothing — which is this, computed here and nowhere else. Held
459
+ * to a copy: the driver may run this again, and the call is the caller's object.
460
+ */
461
+ if (records) {
462
+ const reply =
463
+ call.reply?.output === undefined ? { ...call.reply, output: state } : call.reply
464
+
465
+ try {
466
+ await this.#inbox.insert({ ...call, reply }, session)
467
+ } catch (error) {
468
+ if (error?.code !== ERR_DUPLICATE_KEY) throw error
469
+
470
+ await session.abortTransaction()
471
+
472
+ return MADE
473
+ }
474
+ }
129
475
 
130
- await this.#connection.index(fields, {
131
- name,
132
- sparse
133
- })
476
+ if (row !== undefined && this.#outbox !== undefined)
477
+ await this.#outbox.insert(row, session)
134
478
 
135
- indexes.push(name)
136
- }
479
+ return state
137
480
  }
138
481
 
139
- await this.removeObsolete(indexes)
140
- }
482
+ if ((row === undefined || this.#outbox === undefined) && !records)
483
+ return apply(undefined)
141
484
 
142
- async uniqueIndex (name, properties, sparse = false) {
143
- const fields = properties.reduce((acc, property) => {
144
- acc[property] = 1
145
- return acc
146
- }, {})
485
+ const result = await this.#client.transaction(apply)
147
486
 
148
- name = 'unique_' + name
487
+ if (result === MADE) throw new exceptions.DuplicateCallException(call.id)
149
488
 
150
- await this.#connection.index(fields, {
151
- name,
152
- unique: true,
153
- sparse
154
- })
155
-
156
- return name
489
+ return result
157
490
  }
158
491
 
159
- async removeObsolete (desired) {
160
- const current = await this.#connection.indexes()
161
- const obsolete = current.filter((name) => !desired.includes(name))
492
+ async ensure(query, properties, state, row = undefined) {
493
+ let { criteria, options } = translate(query, this.#dates)
494
+
495
+ if (query === undefined) criteria = { ...properties }
496
+
497
+ // a deleted record is not one to get: the upsert passes it by and creates
498
+ if (query?.options?.deleted !== true) criteria.DELETED = null
499
+
500
+ const update = { $setOnInsert: this.#to(state) }
162
501
 
163
- if (obsolete.length > 0) {
164
- console.info(`Remove obsolete indexes: [${obsolete.join(', ')}]`)
502
+ options.upsert = true
503
+ options.returnDocument = ReturnDocument.AFTER
165
504
 
166
- await this.#connection.dropIndexes(obsolete)
505
+ try {
506
+ const result =
507
+ row === undefined || this.#outbox === undefined
508
+ ? await this.command('findOneAndUpdate', { criteria, update, options }, () =>
509
+ this.#collection.findOneAndUpdate(criteria, update, options)
510
+ )
511
+ : await this.#client.transaction(async (session) => {
512
+ const found = await this.command(
513
+ 'findOneAndUpdate',
514
+ { criteria, update, options },
515
+ () =>
516
+ this.#collection.findOneAndUpdate(criteria, update, {
517
+ ...options,
518
+ session
519
+ })
520
+ )
521
+
522
+ // only an insert is an event; finding an existing record is not
523
+ if (found !== null && found._id === state.id)
524
+ await this.#outbox.insert(row, session)
525
+
526
+ return found
527
+ })
528
+
529
+ return this.#from(result)
530
+ } catch (error) {
531
+ if (error.code === ERR_DUPLICATE_KEY)
532
+ throw new exceptions.DuplicateException(this.#client.name)
533
+ else throw error
167
534
  }
168
535
  }
169
536
 
170
- checkFields (fields) {
171
- const optional = []
537
+ /**
538
+ * Names, logs and times a call into the driver. The driver's own command monitoring is
539
+ * off (see `client.js`), so this is where a query becomes a span.
540
+ *
541
+ * @private
542
+ */
543
+ async command(method, attributes, task) {
544
+ this.debug(method, attributes)
172
545
 
173
- for (const field of fields) {
174
- if (!(field in this.#entity.schema.properties)) {
175
- throw new Error(`Index field '${field}' is not defined.`)
176
- }
546
+ return console.span(this.span(method), task)
547
+ }
177
548
 
178
- if (!this.#entity.schema.required?.includes(field)) {
179
- optional.push(field)
549
+ /**
550
+ * The span of a driver method is the same object every time: the collection is fixed
551
+ * for a storage, and nothing downstream writes to what it is given.
552
+ *
553
+ * @private
554
+ */
555
+ span(method) {
556
+ let options = this.#spans.get(method)
557
+
558
+ if (options === undefined) {
559
+ const collection = this.#collection.collectionName
560
+
561
+ options = {
562
+ name: `${method} ${collection}`,
563
+ kind: 'client',
564
+ // https://opentelemetry.io/docs/specs/semconv/database/mongodb/
565
+ attributes: {
566
+ 'db.system': 'mongodb',
567
+ 'db.namespace': this.#collection.dbName,
568
+ 'db.operation.name': method,
569
+ 'db.collection.name': collection
570
+ },
571
+ measure: query(collection, method)
180
572
  }
181
- }
182
573
 
183
- if (optional.length > 0) {
184
- console.info(`Index fields [${optional.join(', ')}] are optional, creating sparse index.`)
185
-
186
- return true
187
- } else {
188
- return false
574
+ this.#spans.set(method, options)
189
575
  }
576
+
577
+ return options
190
578
  }
191
579
 
580
+ debug(method, attributes) {
581
+ console.debug('MongoDB query', {
582
+ collection: this.#collection.collectionName,
583
+ method,
584
+ ...attributes
585
+ })
586
+ }
192
587
  }
193
588
 
194
- const INDEX_TYPES = {
195
- 'asc': 1,
196
- 'desc': -1,
197
- 'hash': 'hashed'
589
+ function toPipeline(criteria, options, sample) {
590
+ const pipeline = []
591
+
592
+ if (criteria !== undefined) pipeline.push({ $match: criteria })
593
+
594
+ if (sample !== undefined) pipeline.push({ $sample: { size: sample } })
595
+
596
+ if (options?.sort !== undefined) pipeline.push({ $sort: options.sort })
597
+
598
+ if (options?.projection !== undefined) pipeline.push({ $project: options.projection })
599
+
600
+ return pipeline
198
601
  }
199
602
 
603
+ /** the rank of the first region, which is what a record written before regions reads as */
604
+ const FIRST = 0
605
+
200
606
  const ERR_DUPLICATE_KEY = 11000
201
607
 
202
- exports.Storage = Storage
608
+ /** what the transaction answers where the call it carries has already been made */
609
+ const MADE = Symbol('made')
610
+
611
+ /** whether the key a write collided on is `_id` */
612
+ function collidedOnId(error) {
613
+ if (error?.code !== ERR_DUPLICATE_KEY) return false
614
+
615
+ return error.keyPattern === undefined
616
+ ? error.message.includes(' index: _id_ ') // AWS DocumentDB, and a bulk write
617
+ : error.keyPattern._id === 1
618
+ }
619
+
620
+ async function retriable(error, attempt) {
621
+ if (error.code === ERR_DUPLICATE_KEY) {
622
+ if (collidedOnId(error)) return false
623
+ else throw new exceptions.DuplicateException()
624
+ } else if (error.cause?.code === 'ECONNREFUSED') {
625
+ if (attempt === LAST_ATTEMPT) throw error
626
+
627
+ const timeout = 1000 + 500 * attempt
628
+
629
+ await new Promise((resolve) => setTimeout(resolve, timeout))
630
+
631
+ return true
632
+ } else throw error
633
+ }
634
+
635
+ const LAST_ATTEMPT = 9