@dbos-inc/dbos-sdk 5.3.12-preview → 5.4.0

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.
Files changed (80) hide show
  1. package/dist/src/auto_upgrade.d.ts +27 -0
  2. package/dist/src/auto_upgrade.d.ts.map +1 -0
  3. package/dist/src/auto_upgrade.js +84 -0
  4. package/dist/src/auto_upgrade.js.map +1 -0
  5. package/dist/src/cli/cli.js +56 -13
  6. package/dist/src/cli/cli.js.map +1 -1
  7. package/dist/src/client.d.ts +20 -10
  8. package/dist/src/client.d.ts.map +1 -1
  9. package/dist/src/client.js +76 -44
  10. package/dist/src/client.js.map +1 -1
  11. package/dist/src/config.d.ts +1 -0
  12. package/dist/src/config.d.ts.map +1 -1
  13. package/dist/src/config.js +12 -0
  14. package/dist/src/config.js.map +1 -1
  15. package/dist/src/context.d.ts +6 -0
  16. package/dist/src/context.d.ts.map +1 -1
  17. package/dist/src/context.js +15 -1
  18. package/dist/src/context.js.map +1 -1
  19. package/dist/src/datasource.d.ts +2 -0
  20. package/dist/src/datasource.d.ts.map +1 -1
  21. package/dist/src/datasource.js +7 -1
  22. package/dist/src/datasource.js.map +1 -1
  23. package/dist/src/dbos-executor.d.ts +39 -4
  24. package/dist/src/dbos-executor.d.ts.map +1 -1
  25. package/dist/src/dbos-executor.js +89 -56
  26. package/dist/src/dbos-executor.js.map +1 -1
  27. package/dist/src/dbos.d.ts +60 -11
  28. package/dist/src/dbos.d.ts.map +1 -1
  29. package/dist/src/dbos.js +240 -79
  30. package/dist/src/dbos.js.map +1 -1
  31. package/dist/src/enqueue_options.d.ts +2 -0
  32. package/dist/src/enqueue_options.d.ts.map +1 -1
  33. package/dist/src/enqueue_options.js +3 -0
  34. package/dist/src/enqueue_options.js.map +1 -1
  35. package/dist/src/enqueue_workflow.d.ts.map +1 -1
  36. package/dist/src/enqueue_workflow.js +11 -5
  37. package/dist/src/enqueue_workflow.js.map +1 -1
  38. package/dist/src/enterprise.d.ts +67 -2
  39. package/dist/src/enterprise.d.ts.map +1 -1
  40. package/dist/src/enterprise.js +185 -9
  41. package/dist/src/enterprise.js.map +1 -1
  42. package/dist/src/eventreceiver.d.ts +2 -0
  43. package/dist/src/eventreceiver.d.ts.map +1 -1
  44. package/dist/src/eventreceiver.js +7 -1
  45. package/dist/src/eventreceiver.js.map +1 -1
  46. package/dist/src/index.d.ts +2 -1
  47. package/dist/src/index.d.ts.map +1 -1
  48. package/dist/src/index.js.map +1 -1
  49. package/dist/src/scheduler/scheduler.d.ts +5 -0
  50. package/dist/src/scheduler/scheduler.d.ts.map +1 -1
  51. package/dist/src/scheduler/scheduler.js +14 -4
  52. package/dist/src/scheduler/scheduler.js.map +1 -1
  53. package/dist/src/shard_keys.d.ts +13 -0
  54. package/dist/src/shard_keys.d.ts.map +1 -0
  55. package/dist/src/shard_keys.js +55 -0
  56. package/dist/src/shard_keys.js.map +1 -0
  57. package/dist/src/streams.d.ts +2 -0
  58. package/dist/src/streams.d.ts.map +1 -1
  59. package/dist/src/streams.js +5 -2
  60. package/dist/src/streams.js.map +1 -1
  61. package/dist/src/sysdb_migrations/internal/migrations.js +16 -0
  62. package/dist/src/sysdb_migrations/internal/migrations.js.map +1 -1
  63. package/dist/src/system_database.d.ts +143 -9
  64. package/dist/src/system_database.d.ts.map +1 -1
  65. package/dist/src/system_database.js +1134 -519
  66. package/dist/src/system_database.js.map +1 -1
  67. package/dist/src/wfqueue.d.ts +1 -2
  68. package/dist/src/wfqueue.d.ts.map +1 -1
  69. package/dist/src/wfqueue.js +83 -63
  70. package/dist/src/wfqueue.js.map +1 -1
  71. package/dist/src/workflow.d.ts +19 -2
  72. package/dist/src/workflow.d.ts.map +1 -1
  73. package/dist/src/workflow.js +14 -9
  74. package/dist/src/workflow.js.map +1 -1
  75. package/dist/src/workflow_management.d.ts +6 -3
  76. package/dist/src/workflow_management.d.ts.map +1 -1
  77. package/dist/src/workflow_management.js +46 -14
  78. package/dist/src/workflow_management.js.map +1 -1
  79. package/dist/tsconfig.tsbuildinfo +1 -1
  80. package/package.json +6 -5
package/dist/src/dbos.js CHANGED
@@ -26,7 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
26
26
  return (mod && mod.__esModule) ? mod : { "default": mod };
27
27
  };
28
28
  Object.defineProperty(exports, "__esModule", { value: true });
29
- exports.DBOS = exports.runTransactionalInternalStep = exports.getResultInternal = exports.runInternalStep = exports.getExecutor = exports.resolveDelayEpochMS = exports.resolveStreamTimeoutMS = exports.resolveStreamPollingIntervalMs = exports.resolveStreamOffset = exports.resolvePollingIntervalMs = exports.resolveTimeoutSeconds = void 0;
29
+ exports.DBOS = exports.StepReservation = exports.runTransactionalInternalStep = exports.getResultInternal = exports.runInternalStep = exports.getExecutor = exports.resolveDelayEpochMS = exports.resolveStreamTimeoutMS = exports.resolveStreamPollingIntervalMs = exports.resolveStreamOffset = exports.resolvePollingIntervalMs = exports.resolveTimeoutSeconds = void 0;
30
30
  const context_1 = require("./context");
31
31
  const dbos_executor_1 = require("./dbos-executor");
32
32
  const traces_1 = require("./telemetry/traces");
@@ -40,6 +40,7 @@ const serialization_1 = require("./serialization");
40
40
  const node_crypto_1 = require("node:crypto");
41
41
  const step_1 = require("./step");
42
42
  const enterprise = __importStar(require("./enterprise"));
43
+ const auto_upgrade_1 = require("./auto_upgrade");
43
44
  const system_database_1 = require("./system_database");
44
45
  const streams_1 = require("./streams");
45
46
  const scheduler_1 = require("./scheduler/scheduler");
@@ -47,6 +48,7 @@ const crontab_1 = require("./scheduler/crontab");
47
48
  const wfqueue_1 = require("./wfqueue");
48
49
  const enqueue_workflow_1 = require("./enqueue_workflow");
49
50
  const node_assert_1 = __importDefault(require("node:assert"));
51
+ const shard_keys_1 = require("./shard_keys");
50
52
  function resolveTimeoutSeconds(options) {
51
53
  if (options === undefined)
52
54
  return undefined;
@@ -191,6 +193,46 @@ async function runTransactionalInternalStep(callback, funcName) {
191
193
  return callback(undefined);
192
194
  }
193
195
  exports.runTransactionalInternalStep = runTransactionalInternalStep;
196
+ /**
197
+ * A step ID drawn by `DBOS.reserveStep`, run exactly once later with `run`.
198
+ * It must run in the workflow that reserved it; a reservation that never runs leaves a gap in the step IDs.
199
+ */
200
+ class StepReservation {
201
+ stepID;
202
+ ctx;
203
+ #used = false;
204
+ constructor(
205
+ /** The reserved step ID */
206
+ stepID, ctx) {
207
+ this.stepID = stepID;
208
+ this.ctx = ctx;
209
+ }
210
+ /**
211
+ * Run `func` as a checkpointed step at the reserved step ID
212
+ * @param func - The function to run as a step
213
+ * @param config - Configuration information for the step, particularly the retry policy and name
214
+ * @returns - result (either obtained from invoking function, or retrieved if run before)
215
+ */
216
+ async run(func, config = {}) {
217
+ (0, decorators_1.ensureDBOSIsLaunched)('steps');
218
+ if (this.#used) {
219
+ throw new error_1.DBOSInvalidWorkflowTransitionError('A step reservation can only be run once');
220
+ }
221
+ const ctx = (0, context_1.getCurrentContextStore)();
222
+ if (ctx === undefined ||
223
+ !(0, context_1.isInWorkflowCtx)(ctx) ||
224
+ ctx.workflowId !== this.ctx.workflowId ||
225
+ ctx.ownerXid !== this.ctx.ownerXid) {
226
+ throw new error_1.DBOSInvalidWorkflowTransitionError(`Step ${this.stepID} was reserved in workflow ${this.ctx.workflowId} and must be run from that workflow, outside any step or transaction`);
227
+ }
228
+ const name = config.name ?? func.name;
229
+ (0, step_1.validateStepConfig)(config, name);
230
+ // Claimed before any await, so a concurrent second run is rejected.
231
+ this.#used = true;
232
+ return await dbos_executor_1.DBOSExecutor.globalInstance.callStepFunctionAt(this.stepID, this.ctx, func, name, config, null);
233
+ }
234
+ }
235
+ exports.StepReservation = StepReservation;
194
236
  class DBOS {
195
237
  ///////
196
238
  // Lifecycle
@@ -218,8 +260,29 @@ class DBOS {
218
260
  * @param systemDatabaseUrl - The system database to create or migrate
219
261
  * @param options.schemaName - The schema holding the DBOS system tables (default: `dbos`)
220
262
  * @param options.applicationRole - A role to grant access to the system schema once migrated
263
+ * @param options.sharding - Create or migrate a sharded system database (requires @dbos-inc/dbos-enterprise)
221
264
  */
222
265
  static async migrate(systemDatabaseUrl, options = {}) {
266
+ if (options.sharding) {
267
+ // Sharded migrations come from Transact Enterprise; the grant is the same.
268
+ const sysdb = (0, system_database_1.createSystemDatabase)({
269
+ systemDatabaseUrl,
270
+ logger: new logs_1.GlobalLogger(),
271
+ serializer: serialization_1.DBOSJSON,
272
+ schemaName: options.schemaName ?? 'dbos',
273
+ sharding: true,
274
+ });
275
+ try {
276
+ await sysdb.runMigrations();
277
+ }
278
+ finally {
279
+ await sysdb.destroy();
280
+ }
281
+ if (options.applicationRole) {
282
+ await (0, system_database_1.grantDbosSchemaPermissions)(systemDatabaseUrl, options.applicationRole, new logs_1.GlobalLogger(), options.schemaName ?? 'dbos');
283
+ }
284
+ return;
285
+ }
223
286
  await (0, system_database_1.migrateSystemDatabase)(systemDatabaseUrl, new logs_1.GlobalLogger(), options.schemaName ?? 'dbos', options.applicationRole);
224
287
  }
225
288
  /**
@@ -238,8 +301,6 @@ class DBOS {
238
301
  throw new error_1.DBOSInitializationError('No application name was provided: set `name` in DBOS.setConfig.');
239
302
  }
240
303
  const internalConfig = (0, config_1.translateDbosConfig)(config);
241
- // DBOS Cloud always uses Conductor. Checked before any state exists, so a missing package fails cleanly.
242
- const loadedEnterprise = options?.conductorKey || utils_1.globalParams.dbosCloud ? enterprise.load() : undefined;
243
304
  utils_1.globalParams.enableOTLP = DBOS.#dbosConfig?.enableOTLP ?? utils_1.globalParams.dbosCloud;
244
305
  utils_1.globalParams.tracingEnabled = DBOS.#dbosConfig?.tracingEnabled || utils_1.globalParams.enableOTLP;
245
306
  if (!(0, traces_1.isTraceContextWorking)())
@@ -249,6 +310,30 @@ class DBOS {
249
310
  return;
250
311
  }
251
312
  (0, decorators_1.finalizeClassRegistrations)();
313
+ // Every enterprise feature requires Conductor to report the org entitled to it, and the package.
314
+ let features = enterprise.enabledFeatures(config);
315
+ if (internalConfig.sharding) {
316
+ // Auto-upgrade is disabled on a sharded system database, so it needs no entitlement.
317
+ features = features.filter((f) => f !== enterprise.AUTO_UPGRADE);
318
+ }
319
+ const entitlementOptions = {
320
+ enterpriseKey: config.transactEnterpriseKey,
321
+ conductorKey: options?.conductorKey,
322
+ conductorURL: options?.conductorURL,
323
+ };
324
+ await enterprise.requireEnterprise(features, entitlementOptions);
325
+ // DBOS Cloud always uses Conductor.
326
+ let loadedEnterprise = options?.conductorKey || utils_1.globalParams.dbosCloud
327
+ ? enterprise.load()
328
+ : features.length > 0
329
+ ? enterprise.load(features[0].description)
330
+ : undefined;
331
+ // Workflows can also enroll for auto-upgrade individually, which the config flag's check above does not cover.
332
+ const autoUpgradableWorkflowNames = (0, auto_upgrade_1.autoUpgradableWorkflows)(internalConfig.autoUpgrade);
333
+ if (autoUpgradableWorkflowNames.length > 0 && !internalConfig.autoUpgrade && !internalConfig.sharding) {
334
+ await enterprise.requireEnterprise([enterprise.AUTO_UPGRADE], entitlementOptions);
335
+ loadedEnterprise ??= enterprise.load(enterprise.AUTO_UPGRADE.description);
336
+ }
252
337
  // Globally set the application name, version and executor ID.
253
338
  // Only launch may change these: work outliving a shutdown still checkpoints under this identity.
254
339
  utils_1.globalParams.appName = internalConfig.name;
@@ -274,19 +359,16 @@ class DBOS {
274
359
  dbos_executor_1.DBOSExecutor.globalInstance = new dbos_executor_1.DBOSExecutor(internalConfig);
275
360
  (0, decorators_1.recordDBOSLaunch)();
276
361
  const executor = dbos_executor_1.DBOSExecutor.globalInstance;
362
+ if (DBOS.#dbosConfig?.enablePatching) {
363
+ executor.logger.warn('enablePatching is deprecated and will be removed in a future release. ' +
364
+ 'DBOS.patch and DBOS.deprecatePatch no longer require it. ' +
365
+ 'To keep every deployment on one application version, as the flag does, set applicationVersion explicitly.');
366
+ }
277
367
  // Initialize data sources before executor.init() dispatches recovery, so recovered
278
368
  // workflows can run their transactions immediately instead of racing initialization.
279
369
  for (const [_n, ds] of decorators_1.transactionalDataSources) {
280
370
  await ds.initialize();
281
371
  }
282
- await executor.init();
283
- // Register the current application version
284
- await executor.systemDatabase.createApplicationVersion(utils_1.globalParams.appVersion);
285
- const latest = await executor.systemDatabase.getLatestApplicationVersion();
286
- if (latest.versionName !== utils_1.globalParams.appVersion) {
287
- executor.logger.warn(`Current version '${utils_1.globalParams.appVersion}' is not the latest version. Latest version is '${latest.versionName}'.`);
288
- }
289
- await dbos_executor_1.DBOSExecutor.globalInstance.initEventReceivers(this.#dbosConfig?.listenQueues || null);
290
372
  const conductorMetadataOnlyMode = options?.conductorMetadataOnlyMode === true;
291
373
  if (utils_1.globalParams.dbosCloud) {
292
374
  const cloudAppName = process.env.DBOS__CONDUCTOR_APP_NAME;
@@ -300,7 +382,6 @@ class DBOS {
300
382
  conductorURL: cloudConductorURL,
301
383
  metadataOnlyMode: conductorMetadataOnlyMode,
302
384
  });
303
- executor.conductor.start();
304
385
  }
305
386
  }
306
387
  else if (loadedEnterprise && options?.conductorKey) {
@@ -327,8 +408,31 @@ class DBOS {
327
408
  executorMetadata,
328
409
  metadataOnlyMode: conductorMetadataOnlyMode,
329
410
  });
411
+ }
412
+ await executor.init();
413
+ // Register the current application version
414
+ await executor.systemDatabase.createApplicationVersion(utils_1.globalParams.appVersion);
415
+ const latest = await executor.systemDatabase.getLatestApplicationVersion();
416
+ if (latest.versionName !== utils_1.globalParams.appVersion) {
417
+ executor.logger.warn(`Current version '${utils_1.globalParams.appVersion}' is not the latest version. Latest version is '${latest.versionName}'.`);
418
+ }
419
+ await dbos_executor_1.DBOSExecutor.globalInstance.initEventReceivers(this.#dbosConfig?.listenQueues || null);
420
+ if (executor.conductor) {
330
421
  executor.conductor.start();
331
422
  }
423
+ // Start the auto-upgrade loop if any workflow takes part.
424
+ if (autoUpgradableWorkflowNames.length > 0 && executor.systemDatabase.sharded) {
425
+ // Its queries aren't keyed by shard, so it doesn't run on a sharded database.
426
+ executor.logger.warn('Auto-upgrade is disabled: it is not supported on a sharded system database.');
427
+ }
428
+ else if (autoUpgradableWorkflowNames.length > 0) {
429
+ (0, node_assert_1.default)(loadedEnterprise, 'the enterprise package is loaded whenever a workflow enrolls in auto-upgrade');
430
+ const upgradePass = new loadedEnterprise.AutoUpgradePass(executor, {
431
+ graceMs: internalConfig.autoUpgradeGraceMs ?? auto_upgrade_1.DEFAULT_AUTO_UPGRADE_GRACE_MS,
432
+ });
433
+ executor.autoUpgrader = new auto_upgrade_1.AutoUpgradeLoop(upgradePass, internalConfig.autoUpgradeIntervalMs ?? auto_upgrade_1.DEFAULT_AUTO_UPGRADE_INTERVAL_MS, executor.logger);
434
+ executor.autoUpgrader.start();
435
+ }
332
436
  }
333
437
  /**
334
438
  * Logs all workflows that can be invoked externally, rather than directly by the application:
@@ -378,8 +482,14 @@ class DBOS {
378
482
  // Conductor stays connected for the drain, so it can still observe and cancel those workflows.
379
483
  if (executor) {
380
484
  await executor.deactivateEventReceivers();
485
+ // The upgrader stops before the drain: it holds the application's lease, which other
486
+ // executors on the latest version wait on, and nothing below depends on it.
487
+ if (executor.autoUpgrader) {
488
+ await executor.autoUpgrader.stop();
489
+ executor.autoUpgrader = undefined;
490
+ }
381
491
  await executor.awaitRunningWorkflows(drainTimeoutMS);
382
- await executor.stopWorkflowTimeoutSweep();
492
+ await executor.stopBackgroundJobs();
383
493
  }
384
494
  // Stop the conductor
385
495
  if (executor?.conductor) {
@@ -461,6 +571,11 @@ class DBOS {
461
571
  static get workflowID() {
462
572
  return (0, context_1.getCurrentContextStore)()?.workflowId;
463
573
  }
574
+ /** The shard key of the currently executing workflow; undefined outside a workflow or on an unsharded database. */
575
+ static get shardKey() {
576
+ const ctx = (0, context_1.getCurrentContextStore)();
577
+ return ctx?.workflowId !== undefined ? ctx.shardKey : undefined;
578
+ }
464
579
  /** Use portable serialization by default? */
465
580
  static get #defaultSerializationType() {
466
581
  return (0, context_1.getCurrentContextStore)()?.serializationType;
@@ -523,21 +638,23 @@ class DBOS {
523
638
  * @param workflowID - ID of the workflow
524
639
  * @returns status of the workflow as `WorkflowStatus`, or `null` if there is no workflow with `workflowID`
525
640
  */
526
- static getWorkflowStatus(workflowID) {
641
+ static async getWorkflowStatus(workflowID, options) {
527
642
  (0, decorators_1.ensureDBOSIsLaunched)('getWorkflowStatus');
528
- if (DBOS.isWithinWorkflow()) {
529
- if (DBOS.isInStep()) {
530
- // OK to use directly
531
- return DBOS.#executor.getWorkflowStatus(workflowID);
532
- }
533
- else if (DBOS.isInWorkflow()) {
534
- return DBOS.#executor.getWorkflowStatus(workflowID, DBOS.workflowID, (0, context_1.functionIDGetIncrement)());
535
- }
536
- else {
537
- throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `getWorkflowStatus` inside a `transaction`');
643
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], () => {
644
+ if (DBOS.isWithinWorkflow()) {
645
+ if (DBOS.isInStep()) {
646
+ // OK to use directly
647
+ return DBOS.#executor.getWorkflowStatus(workflowID);
648
+ }
649
+ else if (DBOS.isInWorkflow()) {
650
+ return DBOS.#executor.getWorkflowStatus(workflowID, DBOS.workflowID, (0, context_1.functionIDGetIncrement)());
651
+ }
652
+ else {
653
+ throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `getWorkflowStatus` inside a `transaction`');
654
+ }
538
655
  }
539
- }
540
- return DBOS.#executor.getWorkflowStatus(workflowID);
656
+ return DBOS.#executor.getWorkflowStatus(workflowID);
657
+ });
541
658
  }
542
659
  /**
543
660
  * Get the workflow result, given a workflow ID
@@ -554,7 +671,8 @@ class DBOS {
554
671
  // Reserve the function ID synchronously, before any await.
555
672
  timerFuncID = (0, context_1.functionIDGetIncrement)();
556
673
  }
557
- return await getResultInternal(workflowID, timeoutSeconds, timerFuncID, undefined, pollingIntervalMs);
674
+ const shardKey = typeof options === 'object' ? options.shardKey : undefined;
675
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, shardKey]], () => getResultInternal(workflowID, timeoutSeconds, timerFuncID, undefined, pollingIntervalMs));
558
676
  }
559
677
  /**
560
678
  * Wait for any one of the given workflow handles to complete and return it.
@@ -578,9 +696,9 @@ class DBOS {
578
696
  handleMap.set(handle.workflowID, handle);
579
697
  }
580
698
  const workflowIds = [...handleMap.keys()];
581
- const completedId = await runInternalStep(async () => {
699
+ const completedId = await (0, shard_keys_1.bindShardKeys)(handles.map((h) => [h.workflowID, h.shardKey]), () => runInternalStep(async () => {
582
700
  return await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.awaitFirstWorkflowId(workflowIds, DBOS.workflowID, pollingIntervalMs);
583
- }, 'DBOS.waitFirst');
701
+ }, 'DBOS.waitFirst'));
584
702
  return handleMap.get(completedId);
585
703
  }
586
704
  /**
@@ -597,9 +715,9 @@ class DBOS {
597
715
  }
598
716
  const pollingIntervalMs = resolvePollingIntervalMs(options);
599
717
  const workflowIds = [...new Set(handles.map((handle) => handle.workflowID))];
600
- await runInternalStep(async () => {
718
+ await (0, shard_keys_1.bindShardKeys)(handles.map((h) => [h.workflowID, h.shardKey]), () => runInternalStep(async () => {
601
719
  await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.awaitWorkflowIds(workflowIds, DBOS.workflowID, pollingIntervalMs);
602
- }, 'DBOS.waitAll');
720
+ }, 'DBOS.waitAll'));
603
721
  return handles;
604
722
  }
605
723
  /**
@@ -609,15 +727,14 @@ class DBOS {
609
727
  * @param workflowID - ID of the workflow
610
728
  * @returns `WorkflowHandle` that can be used to poll for the status or result of any workflow with `workflowID`
611
729
  */
612
- static retrieveWorkflow(workflowID) {
730
+ static retrieveWorkflow(workflowID, options) {
613
731
  (0, decorators_1.ensureDBOSIsLaunched)('retrieveWorkflow');
614
- if (DBOS.isWithinWorkflow()) {
615
- if (!DBOS.isInWorkflow()) {
616
- throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `retrieveWorkflow` inside a `transaction` or `step`');
617
- }
618
- return new workflow_1.RetrievedHandle(workflowID);
732
+ if (DBOS.isWithinWorkflow() && !DBOS.isInWorkflow()) {
733
+ throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `retrieveWorkflow` inside a `transaction` or `step`');
619
734
  }
620
- return DBOS.#executor.retrieveWorkflow(workflowID);
735
+ // The resolved key, so the handle also works outside this binding.
736
+ const shardKey = (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], () => DBOS.#executor.systemDatabase.keyHint(workflowID));
737
+ return new workflow_1.RetrievedHandle(workflowID, shardKey);
621
738
  }
622
739
  /**
623
740
  * Query the system database for all workflows matching the provided predicate
@@ -647,14 +764,14 @@ class DBOS {
647
764
  * @param workflowID - ID of the workflow
648
765
  * @param priority - Priority value (0 to 2,147,483,647). Lower values are dequeued first.
649
766
  */
650
- static async setWorkflowPriority(workflowID, priority) {
767
+ static async setWorkflowPriority(workflowID, priority, options) {
651
768
  (0, decorators_1.ensureDBOSIsLaunched)('setWorkflowPriority');
652
769
  if (priority < dbos_executor_1.DBOS_QUEUE_MIN_PRIORITY || priority > dbos_executor_1.DBOS_QUEUE_MAX_PRIORITY) {
653
770
  throw new error_1.DBOSInvalidQueuePriorityError(priority, dbos_executor_1.DBOS_QUEUE_MIN_PRIORITY, dbos_executor_1.DBOS_QUEUE_MAX_PRIORITY);
654
771
  }
655
- return runInternalStep(async () => {
772
+ return (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], () => runInternalStep(async () => {
656
773
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.setWorkflowPriority(workflowID, priority);
657
- }, 'DBOS.setWorkflowPriority');
774
+ }, 'DBOS.setWorkflowPriority'));
658
775
  }
659
776
  /**
660
777
  * Update the delay on a DELAYED workflow.
@@ -666,9 +783,10 @@ class DBOS {
666
783
  static async setWorkflowDelay(workflowID, options) {
667
784
  (0, decorators_1.ensureDBOSIsLaunched)('setWorkflowDelay');
668
785
  const delayUntilEpochMS = resolveDelayEpochMS(options);
669
- return runInternalStep(async () => {
786
+ const shardKey = typeof options === 'object' ? options.shardKey : undefined;
787
+ return (0, shard_keys_1.bindShardKeys)([[workflowID, shardKey]], () => runInternalStep(async () => {
670
788
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.setWorkflowDelay(workflowID, delayUntilEpochMS);
671
- }, 'DBOS.setWorkflowDelay');
789
+ }, 'DBOS.setWorkflowDelay'));
672
790
  }
673
791
  /**
674
792
  * Retrieve the steps of a workflow
@@ -678,9 +796,9 @@ class DBOS {
678
796
  */
679
797
  static async listWorkflowSteps(workflowID, options) {
680
798
  (0, decorators_1.ensureDBOSIsLaunched)('listWorkflowSteps');
681
- return await runInternalStep(async () => {
799
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], () => runInternalStep(async () => {
682
800
  return await DBOS.#executor.listWorkflowSteps(workflowID, true, options);
683
- }, 'DBOS.listWorkflowSteps');
801
+ }, 'DBOS.listWorkflowSteps'));
684
802
  }
685
803
  /**
686
804
  * Cancel a workflow given its ID.
@@ -699,9 +817,9 @@ class DBOS {
699
817
  */
700
818
  static async cancelWorkflows(workflowIDs, options) {
701
819
  (0, decorators_1.ensureDBOSIsLaunched)('cancelWorkflows');
702
- return runInternalStep(async () => {
820
+ return (0, shard_keys_1.bindShardKeys)(workflowIDs.map((wid) => [wid, options?.shardKey]), () => runInternalStep(async () => {
703
821
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.cancelWorkflows(workflowIDs, options?.cancelChildren);
704
- }, 'DBOS.cancelWorkflow');
822
+ }, 'DBOS.cancelWorkflow'));
705
823
  }
706
824
  /**
707
825
  * Resume a workflow given its ID.
@@ -709,8 +827,11 @@ class DBOS {
709
827
  * @throws DBOSNonExistentWorkflowError if the workflow does not exist
710
828
  */
711
829
  static async resumeWorkflow(workflowID, options) {
712
- const handles = await this.resumeWorkflows([workflowID], options);
713
- return handles[0];
830
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], async () => {
831
+ await this.resumeWorkflows([workflowID], options);
832
+ // The resolved key, so the handle also works outside this binding.
833
+ return new workflow_1.RetrievedHandle(workflowID, DBOS.#executor.systemDatabase.keyHint(workflowID));
834
+ });
714
835
  }
715
836
  /**
716
837
  * Resume multiple workflows given their IDs.
@@ -720,10 +841,12 @@ class DBOS {
720
841
  */
721
842
  static async resumeWorkflows(workflowIDs, options) {
722
843
  (0, decorators_1.ensureDBOSIsLaunched)('resumeWorkflows');
723
- await runInternalStep(async () => {
724
- return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.resumeWorkflows(workflowIDs, options?.queueName);
725
- }, 'DBOS.resumeWorkflow');
726
- return workflowIDs.map((wfid) => this.retrieveWorkflow(wfid));
844
+ return await (0, shard_keys_1.bindShardKeys)(workflowIDs.map((wid) => [wid, options?.shardKey]), async () => {
845
+ await runInternalStep(async () => {
846
+ return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.resumeWorkflows(workflowIDs, options?.queueName);
847
+ }, 'DBOS.resumeWorkflow');
848
+ return workflowIDs.map((wfid) => new workflow_1.RetrievedHandle(wfid, options?.shardKey));
849
+ });
727
850
  }
728
851
  /**
729
852
  * Delete a workflow and optionally all its child workflows.
@@ -734,8 +857,8 @@ class DBOS {
734
857
  * @param workflowID - ID of the workflow to delete
735
858
  * @param deleteChildren - If true, also delete all child workflows recursively (default: false)
736
859
  */
737
- static async deleteWorkflow(workflowID, deleteChildren = false) {
738
- return this.deleteWorkflows([workflowID], deleteChildren);
860
+ static async deleteWorkflow(workflowID, deleteChildren = false, options) {
861
+ return this.deleteWorkflows([workflowID], deleteChildren, options);
739
862
  }
740
863
  /**
741
864
  * Delete multiple workflows and optionally all their child workflows.
@@ -745,11 +868,11 @@ class DBOS {
745
868
  * @param workflowIDs - IDs of the workflows to delete
746
869
  * @param deleteChildren - If true, also delete all child workflows recursively (default: false)
747
870
  */
748
- static async deleteWorkflows(workflowIDs, deleteChildren = false) {
871
+ static async deleteWorkflows(workflowIDs, deleteChildren = false, options) {
749
872
  (0, decorators_1.ensureDBOSIsLaunched)('deleteWorkflows');
750
- return runInternalStep(async () => {
873
+ return (0, shard_keys_1.bindShardKeys)(workflowIDs.map((wid) => [wid, options?.shardKey]), () => runInternalStep(async () => {
751
874
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.deleteWorkflows(workflowIDs, deleteChildren);
752
- }, 'DBOS.deleteWorkflow');
875
+ }, 'DBOS.deleteWorkflow'));
753
876
  }
754
877
  /**
755
878
  * Fork a workflow given its ID.
@@ -761,10 +884,14 @@ class DBOS {
761
884
  */
762
885
  static async forkWorkflow(workflowID, startStep, options) {
763
886
  (0, decorators_1.ensureDBOSIsLaunched)('forkWorkflow');
764
- const forkedID = await runInternalStep(async () => {
765
- return await DBOS.#executor.forkWorkflow(workflowID, startStep, options);
766
- }, 'DBOS.forkWorkflow');
767
- return this.retrieveWorkflow(forkedID);
887
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], async () => {
888
+ const forkedID = await runInternalStep(async () => {
889
+ return await DBOS.#executor.forkWorkflow(workflowID, startStep, options);
890
+ }, 'DBOS.forkWorkflow');
891
+ // A fork lives under its original's shard key, however the caller supplied it.
892
+ const forkKey = DBOS.#executor.systemDatabase.keyHint(workflowID);
893
+ return new workflow_1.RetrievedHandle(forkedID, forkKey);
894
+ });
768
895
  }
769
896
  /**
770
897
  * Rewind a workflow given its ID: drop its recorded history from `startStep` onwards
@@ -788,10 +915,13 @@ class DBOS {
788
915
  static async rewindWorkflow(workflowID, options) {
789
916
  (0, decorators_1.ensureDBOSIsLaunched)('rewindWorkflow');
790
917
  const startStep = options?.startStep ?? 0;
791
- await runInternalStep(async () => {
792
- return await DBOS.#executor.rewindWorkflow(workflowID, startStep, options ?? {});
793
- }, 'DBOS.rewindWorkflow');
794
- return this.retrieveWorkflow(workflowID);
918
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], async () => {
919
+ await runInternalStep(async () => {
920
+ return await DBOS.#executor.rewindWorkflow(workflowID, startStep, options ?? {});
921
+ }, 'DBOS.rewindWorkflow');
922
+ // The resolved key, so the handle also works outside this binding.
923
+ return new workflow_1.RetrievedHandle(workflowID, DBOS.#executor.systemDatabase.keyHint(workflowID));
924
+ });
795
925
  }
796
926
  /**
797
927
  * Sleep for the specified amount of time.
@@ -906,6 +1036,13 @@ class DBOS {
906
1036
  (0, decorators_1.ensureDBOSIsLaunched)('workflows');
907
1037
  return DBOS.#withTopContext({ workflowTimeoutMS: timeoutMS }, callback);
908
1038
  }
1039
+ /** Set the shard key of each workflow started, enqueued, or called in `callback`; their children don't inherit it. */
1040
+ static async withShardKey(shardKey, callback) {
1041
+ if (typeof shardKey !== 'string' || shardKey === '') {
1042
+ throw new error_1.DBOSError('shardKey must be a non-empty string');
1043
+ }
1044
+ return DBOS.#withTopContext({ shardKeyForNextWorkflow: shardKey }, callback);
1045
+ }
909
1046
  static async #withTopContext(options, callback) {
910
1047
  const pctx = (0, context_1.getCurrentContextStore)();
911
1048
  if (pctx) {
@@ -993,16 +1130,16 @@ class DBOS {
993
1130
  // calls in the same workflow don't race for IDs.
994
1131
  const functionID = (0, context_1.functionIDGetIncrement)();
995
1132
  const sermsg = await (0, serialization_1.serializeValue)(message, DBOS.#executor.serializer, options?.serializationType ?? DBOS.#defaultSerializationType);
996
- return await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.send(DBOS.workflowID, functionID, destinationID, sermsg.serializedValue, topic, sermsg.serialization, idempotencyKey);
1133
+ return await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.send(DBOS.workflowID, functionID, destinationID, sermsg.serializedValue, topic, sermsg.serialization, idempotencyKey, options?.shardKey);
997
1134
  }
998
1135
  else if (DBOS.isInStep()) {
999
1136
  // Inside a step: not recorded, but fenced on the enclosing workflow's ownership.
1000
1137
  const sermsg = await (0, serialization_1.serializeValue)(message, DBOS.#executor.serializer, options?.serializationType ?? DBOS.#defaultSerializationType);
1001
- return await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.sendFromStep(DBOS.workflowID, destinationID, sermsg.serializedValue, topic, sermsg.serialization, idempotencyKey);
1138
+ return await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.sendFromStep(DBOS.workflowID, destinationID, sermsg.serializedValue, topic, sermsg.serialization, idempotencyKey, options?.shardKey);
1002
1139
  }
1003
1140
  else {
1004
1141
  const sermsg = await (0, serialization_1.serializeValue)(message, DBOS.#executor.serializer, options?.serializationType ?? DBOS.#defaultSerializationType);
1005
- return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.sendDirect(destinationID, sermsg.serializedValue, topic, sermsg.serialization, idempotencyKey);
1142
+ return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.sendDirect(destinationID, sermsg.serializedValue, topic, sermsg.serialization, idempotencyKey, undefined, options?.shardKey);
1006
1143
  }
1007
1144
  }
1008
1145
  /**
@@ -1070,6 +1207,10 @@ class DBOS {
1070
1207
  */
1071
1208
  static async getEvent(workflowID, key, options) {
1072
1209
  (0, decorators_1.ensureDBOSIsLaunched)('getEvent');
1210
+ const shardKey = typeof options === 'object' ? options.shardKey : undefined;
1211
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, shardKey]], () => DBOS.#getEvent(workflowID, key, options));
1212
+ }
1213
+ static async #getEvent(workflowID, key, options) {
1073
1214
  const timeoutSeconds = resolveTimeoutSeconds(options);
1074
1215
  const pollingIntervalMs = resolvePollingIntervalMs(options);
1075
1216
  if (DBOS.isWithinWorkflow()) {
@@ -1147,6 +1288,7 @@ class DBOS {
1147
1288
  timeoutMS: resolveStreamTimeoutMS(options),
1148
1289
  functionName: system_database_1.DBOS_FUNCNAME_READSTREAM,
1149
1290
  checkpoint: true,
1291
+ shardKey: options.shardKey,
1150
1292
  });
1151
1293
  }
1152
1294
  /**
@@ -1170,6 +1312,7 @@ class DBOS {
1170
1312
  timeoutMS: resolveStreamTimeoutMS(options),
1171
1313
  functionName: system_database_1.DBOS_FUNCNAME_READSTREAMOFFSET,
1172
1314
  checkpoint: true,
1315
+ shardKey: options.shardKey,
1173
1316
  });
1174
1317
  }
1175
1318
  //////
@@ -1226,6 +1369,8 @@ class DBOS {
1226
1369
  const ppctx = (0, context_1.getCurrentContextStore)();
1227
1370
  const queueName = params.queueName ?? ppctx?.queueAssignedForWorkflows;
1228
1371
  const timeoutMS = params.timeoutMS ?? ppctx?.workflowTimeoutMS;
1372
+ // Set by DBOS.withShardKey; a workflow never inherits its caller's own key.
1373
+ const shardKey = (0, context_1.nextWorkflowShardKey)(ppctx);
1229
1374
  const instance = $this === undefined || typeof $this === 'function' ? undefined : $this;
1230
1375
  if (instance && !(instance instanceof decorators_1.ConfiguredInstance)) {
1231
1376
  throw new error_1.DBOSInvalidWorkflowTransitionError('Attempt to call a `workflow` function on an object that is not a `ConfiguredInstance`');
@@ -1263,7 +1408,7 @@ class DBOS {
1263
1408
  if (isChild) {
1264
1409
  const pwfid = ppctx.workflowId;
1265
1410
  const wfParams = {
1266
- workflowUUID: wfId || pwfid + '-' + funcId,
1411
+ workflowUUID: wfId || (0, context_1.childWorkflowID)(pwfid, funcId, ppctx?.shardKey, shardKey),
1267
1412
  configuredInstance: instance,
1268
1413
  queueName,
1269
1414
  timeoutMS,
@@ -1275,6 +1420,7 @@ class DBOS {
1275
1420
  workflowAttributes: params.workflowAttributes,
1276
1421
  authenticatedUser: params.authenticatedUser,
1277
1422
  authenticatedRoles: params.authenticatedRoles,
1423
+ shardKey,
1278
1424
  };
1279
1425
  return await invokeRegOp(wfParams, pwfid, funcId);
1280
1426
  }
@@ -1290,6 +1436,7 @@ class DBOS {
1290
1436
  workflowAttributes: params.workflowAttributes,
1291
1437
  authenticatedUser: params.authenticatedUser,
1292
1438
  authenticatedRoles: params.authenticatedRoles,
1439
+ shardKey,
1293
1440
  };
1294
1441
  return await invokeRegOp(wfParams, undefined, undefined);
1295
1442
  }
@@ -1316,6 +1463,8 @@ class DBOS {
1316
1463
  // Reserve the parent's child-funcID once, before any await. Each loop iteration passes it
1317
1464
  // through so the return-existing retry loop consumes a single funcID instead of one per try.
1318
1465
  const childFuncId = DBOS.isInWorkflow() ? (0, context_1.functionIDGetIncrement)() : undefined;
1466
+ // The key the attached-to workflow lives under, as the start would have used.
1467
+ const shardKey = (0, context_1.nextWorkflowShardKey)((0, context_1.getCurrentContextStore)());
1319
1468
  // Resolve the workflow ID once: if the caller supplied one explicitly or via
1320
1469
  // `withNextWorkflowID`, reuse it on every iteration.
1321
1470
  const resolvedWorkflowID = (0, context_1.getNextWFID)(params.workflowID);
@@ -1336,7 +1485,7 @@ class DBOS {
1336
1485
  const now = Date.now();
1337
1486
  await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.recordOperationResult(DBOS.workflowID, childFuncId, regOP.name, true, now, now, { childWorkflowID: existingID });
1338
1487
  }
1339
- return new workflow_1.RetrievedHandle(existingID);
1488
+ return new workflow_1.RetrievedHandle(existingID, shardKey);
1340
1489
  }
1341
1490
  // The prior workflow's deduplication_id was cleared between our INSERT and
1342
1491
  // the lookup (it completed or was cancelled). Loop and try to claim the slot.
@@ -1471,6 +1620,21 @@ class DBOS {
1471
1620
  }
1472
1621
  return func();
1473
1622
  }
1623
+ /**
1624
+ * Draw the next step ID now, so a step can run at it later (for example, from another task) with `run`.
1625
+ * This fixes the step's position in the workflow's history when it would otherwise depend on timing.
1626
+ * Must be called from workflow code, not from a step or transaction.
1627
+ * @returns - a `StepReservation` that runs a step at the reserved ID
1628
+ */
1629
+ static reserveStep() {
1630
+ (0, decorators_1.ensureDBOSIsLaunched)('steps');
1631
+ const ctx = (0, context_1.getCurrentContextStore)();
1632
+ if (ctx === undefined || !(0, context_1.isInWorkflowCtx)(ctx)) {
1633
+ throw new error_1.DBOSInvalidWorkflowTransitionError('DBOS.reserveStep must be called from a workflow, outside any step or transaction');
1634
+ }
1635
+ const stepID = (0, context_1.functionIDGetIncrement)();
1636
+ return new StepReservation(stepID, { ...ctx });
1637
+ }
1474
1638
  /**
1475
1639
  * Register serialization recipe; this is used to save/retrieve objects from the DBOS system
1476
1640
  * database. This includes workflow inputs, function return values, messages, and events.
@@ -1499,9 +1663,6 @@ class DBOS {
1499
1663
  if (!DBOS.isInWorkflow()) {
1500
1664
  throw new error_1.DBOSInvalidWorkflowTransitionError('`DBOS.patch` must be called from a workflow, and not within a step');
1501
1665
  }
1502
- if (!DBOS.#dbosConfig?.enablePatching) {
1503
- throw new error_1.DBOSInvalidWorkflowTransitionError('Patching is not enabled. See `enablePatching` in `DBOSConfig`');
1504
- }
1505
1666
  const patched = await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.checkPatch(DBOS.workflowID, (0, context_1.functionIDGet)(), patchName, false);
1506
1667
  if (patched.hasEntry) {
1507
1668
  (0, context_1.functionIDGetIncrement)();
@@ -1521,9 +1682,6 @@ class DBOS {
1521
1682
  if (!DBOS.isInWorkflow()) {
1522
1683
  throw new error_1.DBOSInvalidWorkflowTransitionError('`DBOS.deprecatePatch` must be called from a workflow, and not within a step');
1523
1684
  }
1524
- if (!DBOS.#dbosConfig?.enablePatching) {
1525
- throw new error_1.DBOSInvalidWorkflowTransitionError('Patching is not enabled. See `enablePatching` in `DBOSConfig`');
1526
- }
1527
1685
  const patched = await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.checkPatch(DBOS.workflowID, (0, context_1.functionIDGet)(), patchName, true);
1528
1686
  if (patched.hasEntry) {
1529
1687
  (0, context_1.functionIDGetIncrement)();
@@ -1611,6 +1769,7 @@ class DBOS {
1611
1769
  cronTimezone: options.options?.cronTimezone ?? null,
1612
1770
  queueName: options.options?.queueName ?? null,
1613
1771
  applicationName: utils_1.globalParams.appName,
1772
+ shardKey: options.options?.shardKey,
1614
1773
  };
1615
1774
  await runTransactionalInternalStep((client) => dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.createSchedule(schedInternal, client), 'DBOS.createSchedule');
1616
1775
  }
@@ -1696,6 +1855,7 @@ class DBOS {
1696
1855
  automaticBackfill: sched.automaticBackfill ?? false,
1697
1856
  cronTimezone: sched.cronTimezone ?? null,
1698
1857
  queueName: sched.queueName ?? null,
1858
+ shardKey: sched.shardKey,
1699
1859
  });
1700
1860
  }
1701
1861
  await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.applySchedules(internals);
@@ -1707,7 +1867,7 @@ class DBOS {
1707
1867
  }
1708
1868
  const executor = dbos_executor_1.DBOSExecutor.globalInstance;
1709
1869
  const workflowID = await (0, scheduler_1.triggerSchedule)(executor.systemDatabase, executor.serializer, name);
1710
- return new workflow_1.RetrievedHandle(workflowID);
1870
+ return new workflow_1.RetrievedHandle(workflowID, await (0, scheduler_1.scheduleShardKey)(executor.systemDatabase, name));
1711
1871
  }
1712
1872
  static async backfillSchedule(name, start, end) {
1713
1873
  (0, decorators_1.ensureDBOSIsLaunched)('backfillSchedule');
@@ -1716,7 +1876,8 @@ class DBOS {
1716
1876
  }
1717
1877
  const executor = dbos_executor_1.DBOSExecutor.globalInstance;
1718
1878
  const workflowIDs = await (0, scheduler_1.backfillSchedule)(executor.systemDatabase, executor.serializer, name, start, end);
1719
- return workflowIDs.map((id) => new workflow_1.RetrievedHandle(id));
1879
+ const shardKey = await (0, scheduler_1.scheduleShardKey)(executor.systemDatabase, name);
1880
+ return workflowIDs.map((id) => new workflow_1.RetrievedHandle(id, shardKey));
1720
1881
  }
1721
1882
  // ==================== Application Versions ====================
1722
1883
  /**