velocious 1.0.722 → 1.0.723

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.
@@ -69,9 +69,10 @@ export default class SyncAppliedSequenceStore {
69
69
 
70
70
  /**
71
71
  * Ensures the backing table exists.
72
+ * @param {{operation?: import("../database/operation.js").default | null}} [args] - Optional caller-owned operation.
72
73
  * @returns {Promise<void>} Resolves when ready.
73
74
  */
74
- async ensureReady() {
75
+ async ensureReady({operation} = {}) {
75
76
  if (this._isReady) return
76
77
 
77
78
  if (this._usesMemoryStorage()) {
@@ -79,43 +80,43 @@ export default class SyncAppliedSequenceStore {
79
80
  return
80
81
  }
81
82
 
82
- await this._withDb(async (db) => await this._ensureReadyWithDb(db))
83
+ await this._withDb(async (db) => await this._ensureReadyWithDb(db), operation)
83
84
  }
84
85
 
85
86
  /**
86
87
  * Returns the highest server sequence already applied to a record.
87
- * @param {{resourceType: string, resourceId: string}} identity - Resource identity.
88
+ * @param {{resourceType: string, resourceId: string, operation?: import("../database/operation.js").default | null}} identity - Resource identity and optional caller-owned operation.
88
89
  * @returns {Promise<number | null>} Applied sequence, or null when none is recorded.
89
90
  */
90
- async lastAppliedSequence(identity) {
91
- await this.ensureReady()
91
+ async lastAppliedSequence({resourceId, resourceType, operation}) {
92
+ await this.ensureReady({operation})
92
93
 
93
94
  if (this._usesMemoryStorage()) {
94
- return this._memorySequences.get(memoryKey(identity)) ?? null
95
+ return this._memorySequences.get(memoryKey({resourceId, resourceType})) ?? null
95
96
  }
96
97
 
97
98
  return await this._withDb(async (db) => {
98
- const row = await this._rowByResource(db, identity)
99
+ const row = await this._rowByResource(db, {resourceId, resourceType})
99
100
 
100
101
  return row ? row.serverSequence : null
101
- })
102
+ }, operation)
102
103
  }
103
104
 
104
105
  /**
105
106
  * Records a successfully applied server sequence for a record, keeping only
106
107
  * the highest value. Writes for the same record are serialized in-process so
107
108
  * concurrent pull/realtime applies cannot move the watermark backwards.
108
- * @param {{resourceType: string, resourceId: string, serverSequence: number}} args - Applied change identity and sequence.
109
+ * @param {{resourceType: string, resourceId: string, serverSequence: number, operation?: import("../database/operation.js").default | null}} args - Applied change identity, sequence and optional caller-owned operation.
109
110
  * @returns {Promise<void>} Resolves when recorded.
110
111
  */
111
- async recordAppliedSequence({resourceId, resourceType, serverSequence}) {
112
- await this.ensureReady()
112
+ async recordAppliedSequence({resourceId, resourceType, serverSequence, operation}) {
113
+ await this.ensureReady({operation})
113
114
 
114
115
  const identity = {resourceId, resourceType}
115
116
  const key = memoryKey(identity)
116
117
  const previousWrite = this._writeQueues.get(key) || Promise.resolve()
117
118
  const write = previousWrite
118
- .then(async () => await this._recordSequential({identity, key, serverSequence}))
119
+ .then(async () => await this._recordSequential({identity, key, operation, serverSequence}))
119
120
  .finally(() => {
120
121
  if (this._writeQueues.get(key) === write) this._writeQueues.delete(key)
121
122
  })
@@ -126,11 +127,11 @@ export default class SyncAppliedSequenceStore {
126
127
 
127
128
  /**
128
129
  * Applies one serialized watermark write.
129
- * @param {{identity: {resourceType: string, resourceId: string}, key: string, serverSequence: number}} args - Write args.
130
+ * @param {{identity: {resourceType: string, resourceId: string}, key: string, serverSequence: number, operation?: import("../database/operation.js").default | null}} args - Write args.
130
131
  * @returns {Promise<void>} Resolves when written.
131
132
  */
132
- async _recordSequential({identity, key, serverSequence}) {
133
- const currentSequence = await this.lastAppliedSequence(identity)
133
+ async _recordSequential({identity, key, serverSequence, operation}) {
134
+ const currentSequence = await this.lastAppliedSequence({resourceType: identity.resourceType, resourceId: identity.resourceId, operation})
134
135
 
135
136
  if (currentSequence !== null && currentSequence >= serverSequence) return
136
137
 
@@ -153,7 +154,7 @@ export default class SyncAppliedSequenceStore {
153
154
  tableName: TABLE_NAME,
154
155
  updateColumns: ["server_sequence", "updated_at"]
155
156
  })
156
- })
157
+ }, operation)
157
158
  }
158
159
 
159
160
  /**
@@ -227,11 +228,23 @@ export default class SyncAppliedSequenceStore {
227
228
 
228
229
  /**
229
230
  * Runs a callback with a database connection.
231
+ *
232
+ * A caller that already owns an operation on this store's physical database
233
+ * must hand it in: taking a second checkout from the same physical database
234
+ * would queue behind the operation the caller is running inside and wait
235
+ * behind itself.
230
236
  * @template Result
231
237
  * @param {(db: import("../database/drivers/base.js").default) => Promise<Result>} callback - Database callback.
238
+ * @param {import("../database/operation.js").default | null} [operation] - Caller-owned operation to run on.
232
239
  * @returns {Promise<Result>} Callback result.
233
240
  */
234
- async _withDb(callback) {
241
+ async _withDb(callback, operation) {
242
+ if (operation) {
243
+ this.assertOperationOwnership(operation)
244
+
245
+ return await callback(operation.connection())
246
+ }
247
+
235
248
  if (this.tenantHandle) {
236
249
  return await this.tenantHandle.databaseOperation({databaseIdentifier: this.databaseIdentifier, name: "Tenant sync applied-sequence store"}, async (operation) => {
237
250
  return await callback(operation.connection())
@@ -247,6 +260,22 @@ export default class SyncAppliedSequenceStore {
247
260
  })
248
261
  }
249
262
 
263
+ /**
264
+ * Fails closed when a caller hands in an operation that does not belong to this store's database.
265
+ * @param {import("../database/operation.js").default} operation - Caller-owned operation.
266
+ * @returns {void} Nothing when the operation matches the store.
267
+ * @throws {Error} When the operation belongs to another database or another physical tenant database.
268
+ */
269
+ assertOperationOwnership(operation) {
270
+ if (operation.databaseIdentifier() !== this.databaseIdentifier) {
271
+ throw new Error(`Sync applied-sequence store operation belongs to another database: ${operation.databaseIdentifier()}`)
272
+ }
273
+
274
+ if (this.tenantHandle && operation.databaseIdentity() !== this.storeIdentity) {
275
+ throw new Error(`Sync applied-sequence store operation belongs to another physical database: ${operation.databaseIdentity()}`)
276
+ }
277
+ }
278
+
250
279
  /**
251
280
  * Ensures the applied-sequences table exists.
252
281
  * @param {import("../database/drivers/base.js").default} db - Database connection.
@@ -861,7 +861,7 @@ export default class SyncClient {
861
861
  const appliedSequences = this.appliedSequenceStore()
862
862
 
863
863
  if (serverSequence !== null) {
864
- const lastAppliedSequence = await appliedSequences.lastAppliedSequence({resourceId, resourceType})
864
+ const lastAppliedSequence = await appliedSequences.lastAppliedSequence({resourceId, resourceType, operation})
865
865
 
866
866
  if (lastAppliedSequence !== null && serverSequence <= lastAppliedSequence) {
867
867
  return {changed: false, resourceType}
@@ -888,7 +888,7 @@ export default class SyncClient {
888
888
  const result = await applier(sync)
889
889
 
890
890
  if (serverSequence !== null) {
891
- await appliedSequences.recordAppliedSequence({resourceId, resourceType, serverSequence})
891
+ await appliedSequences.recordAppliedSequence({resourceId, resourceType, serverSequence, operation})
892
892
  }
893
893
 
894
894
  return result
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "velocious": "build/bin/velocious.js"
4
4
  },
5
5
  "name": "velocious",
6
- "version": "1.0.722",
6
+ "version": "1.0.723",
7
7
  "main": "build/index.js",
8
8
  "types": "build/index.d.ts",
9
9
  "files": [
@@ -1,6 +1,7 @@
1
1
  // @ts-check
2
2
 
3
3
  import BasePool from "./base.js"
4
+ import DatabasePoolCheckoutTimeoutError from "./checkout-timeout-error.js"
4
5
  import OperationLease from "../operation-lease.js"
5
6
  import {coordinateSharedTransactionConnection} from "../../testing/shared-transaction-connection-coordinator.js"
6
7
 
@@ -274,7 +275,7 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
274
275
 
275
276
  if (timeoutMillis !== null) {
276
277
  timer = setTimeout(() => {
277
- pending.reject(new Error(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`))
278
+ pending.reject(new DatabasePoolCheckoutTimeoutError(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`))
278
279
  }, timeoutMillis)
279
280
  }
280
281
  })
@@ -452,7 +453,7 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
452
453
  const timeoutMillis = pending.timeoutMillis
453
454
 
454
455
  await new Promise((resolve, reject) => {
455
- const timer = setTimeout(() => reject(new Error(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`)), timeoutMillis)
456
+ const timer = setTimeout(() => reject(new DatabasePoolCheckoutTimeoutError(`Timed out waiting for database connection checkout after ${timeoutMillis}ms.`)), timeoutMillis)
456
457
 
457
458
  previousTurn.then(() => {
458
459
  clearTimeout(timer)
@@ -69,9 +69,10 @@ export default class SyncAppliedSequenceStore {
69
69
 
70
70
  /**
71
71
  * Ensures the backing table exists.
72
+ * @param {{operation?: import("../database/operation.js").default | null}} [args] - Optional caller-owned operation.
72
73
  * @returns {Promise<void>} Resolves when ready.
73
74
  */
74
- async ensureReady() {
75
+ async ensureReady({operation} = {}) {
75
76
  if (this._isReady) return
76
77
 
77
78
  if (this._usesMemoryStorage()) {
@@ -79,43 +80,43 @@ export default class SyncAppliedSequenceStore {
79
80
  return
80
81
  }
81
82
 
82
- await this._withDb(async (db) => await this._ensureReadyWithDb(db))
83
+ await this._withDb(async (db) => await this._ensureReadyWithDb(db), operation)
83
84
  }
84
85
 
85
86
  /**
86
87
  * Returns the highest server sequence already applied to a record.
87
- * @param {{resourceType: string, resourceId: string}} identity - Resource identity.
88
+ * @param {{resourceType: string, resourceId: string, operation?: import("../database/operation.js").default | null}} identity - Resource identity and optional caller-owned operation.
88
89
  * @returns {Promise<number | null>} Applied sequence, or null when none is recorded.
89
90
  */
90
- async lastAppliedSequence(identity) {
91
- await this.ensureReady()
91
+ async lastAppliedSequence({resourceId, resourceType, operation}) {
92
+ await this.ensureReady({operation})
92
93
 
93
94
  if (this._usesMemoryStorage()) {
94
- return this._memorySequences.get(memoryKey(identity)) ?? null
95
+ return this._memorySequences.get(memoryKey({resourceId, resourceType})) ?? null
95
96
  }
96
97
 
97
98
  return await this._withDb(async (db) => {
98
- const row = await this._rowByResource(db, identity)
99
+ const row = await this._rowByResource(db, {resourceId, resourceType})
99
100
 
100
101
  return row ? row.serverSequence : null
101
- })
102
+ }, operation)
102
103
  }
103
104
 
104
105
  /**
105
106
  * Records a successfully applied server sequence for a record, keeping only
106
107
  * the highest value. Writes for the same record are serialized in-process so
107
108
  * concurrent pull/realtime applies cannot move the watermark backwards.
108
- * @param {{resourceType: string, resourceId: string, serverSequence: number}} args - Applied change identity and sequence.
109
+ * @param {{resourceType: string, resourceId: string, serverSequence: number, operation?: import("../database/operation.js").default | null}} args - Applied change identity, sequence and optional caller-owned operation.
109
110
  * @returns {Promise<void>} Resolves when recorded.
110
111
  */
111
- async recordAppliedSequence({resourceId, resourceType, serverSequence}) {
112
- await this.ensureReady()
112
+ async recordAppliedSequence({resourceId, resourceType, serverSequence, operation}) {
113
+ await this.ensureReady({operation})
113
114
 
114
115
  const identity = {resourceId, resourceType}
115
116
  const key = memoryKey(identity)
116
117
  const previousWrite = this._writeQueues.get(key) || Promise.resolve()
117
118
  const write = previousWrite
118
- .then(async () => await this._recordSequential({identity, key, serverSequence}))
119
+ .then(async () => await this._recordSequential({identity, key, operation, serverSequence}))
119
120
  .finally(() => {
120
121
  if (this._writeQueues.get(key) === write) this._writeQueues.delete(key)
121
122
  })
@@ -126,11 +127,11 @@ export default class SyncAppliedSequenceStore {
126
127
 
127
128
  /**
128
129
  * Applies one serialized watermark write.
129
- * @param {{identity: {resourceType: string, resourceId: string}, key: string, serverSequence: number}} args - Write args.
130
+ * @param {{identity: {resourceType: string, resourceId: string}, key: string, serverSequence: number, operation?: import("../database/operation.js").default | null}} args - Write args.
130
131
  * @returns {Promise<void>} Resolves when written.
131
132
  */
132
- async _recordSequential({identity, key, serverSequence}) {
133
- const currentSequence = await this.lastAppliedSequence(identity)
133
+ async _recordSequential({identity, key, serverSequence, operation}) {
134
+ const currentSequence = await this.lastAppliedSequence({resourceType: identity.resourceType, resourceId: identity.resourceId, operation})
134
135
 
135
136
  if (currentSequence !== null && currentSequence >= serverSequence) return
136
137
 
@@ -153,7 +154,7 @@ export default class SyncAppliedSequenceStore {
153
154
  tableName: TABLE_NAME,
154
155
  updateColumns: ["server_sequence", "updated_at"]
155
156
  })
156
- })
157
+ }, operation)
157
158
  }
158
159
 
159
160
  /**
@@ -227,11 +228,23 @@ export default class SyncAppliedSequenceStore {
227
228
 
228
229
  /**
229
230
  * Runs a callback with a database connection.
231
+ *
232
+ * A caller that already owns an operation on this store's physical database
233
+ * must hand it in: taking a second checkout from the same physical database
234
+ * would queue behind the operation the caller is running inside and wait
235
+ * behind itself.
230
236
  * @template Result
231
237
  * @param {(db: import("../database/drivers/base.js").default) => Promise<Result>} callback - Database callback.
238
+ * @param {import("../database/operation.js").default | null} [operation] - Caller-owned operation to run on.
232
239
  * @returns {Promise<Result>} Callback result.
233
240
  */
234
- async _withDb(callback) {
241
+ async _withDb(callback, operation) {
242
+ if (operation) {
243
+ this.assertOperationOwnership(operation)
244
+
245
+ return await callback(operation.connection())
246
+ }
247
+
235
248
  if (this.tenantHandle) {
236
249
  return await this.tenantHandle.databaseOperation({databaseIdentifier: this.databaseIdentifier, name: "Tenant sync applied-sequence store"}, async (operation) => {
237
250
  return await callback(operation.connection())
@@ -247,6 +260,22 @@ export default class SyncAppliedSequenceStore {
247
260
  })
248
261
  }
249
262
 
263
+ /**
264
+ * Fails closed when a caller hands in an operation that does not belong to this store's database.
265
+ * @param {import("../database/operation.js").default} operation - Caller-owned operation.
266
+ * @returns {void} Nothing when the operation matches the store.
267
+ * @throws {Error} When the operation belongs to another database or another physical tenant database.
268
+ */
269
+ assertOperationOwnership(operation) {
270
+ if (operation.databaseIdentifier() !== this.databaseIdentifier) {
271
+ throw new Error(`Sync applied-sequence store operation belongs to another database: ${operation.databaseIdentifier()}`)
272
+ }
273
+
274
+ if (this.tenantHandle && operation.databaseIdentity() !== this.storeIdentity) {
275
+ throw new Error(`Sync applied-sequence store operation belongs to another physical database: ${operation.databaseIdentity()}`)
276
+ }
277
+ }
278
+
250
279
  /**
251
280
  * Ensures the applied-sequences table exists.
252
281
  * @param {import("../database/drivers/base.js").default} db - Database connection.
@@ -861,7 +861,7 @@ export default class SyncClient {
861
861
  const appliedSequences = this.appliedSequenceStore()
862
862
 
863
863
  if (serverSequence !== null) {
864
- const lastAppliedSequence = await appliedSequences.lastAppliedSequence({resourceId, resourceType})
864
+ const lastAppliedSequence = await appliedSequences.lastAppliedSequence({resourceId, resourceType, operation})
865
865
 
866
866
  if (lastAppliedSequence !== null && serverSequence <= lastAppliedSequence) {
867
867
  return {changed: false, resourceType}
@@ -888,7 +888,7 @@ export default class SyncClient {
888
888
  const result = await applier(sync)
889
889
 
890
890
  if (serverSequence !== null) {
891
- await appliedSequences.recordAppliedSequence({resourceId, resourceType, serverSequence})
891
+ await appliedSequences.recordAppliedSequence({resourceId, resourceType, serverSequence, operation})
892
892
  }
893
893
 
894
894
  return result