@dbos-inc/dbos-sdk 5.3.13-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 +86 -55
  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 +230 -70
  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,6 +359,11 @@ 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) {
@@ -330,6 +420,19 @@ class DBOS {
330
420
  if (executor.conductor) {
331
421
  executor.conductor.start();
332
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
+ }
333
436
  }
334
437
  /**
335
438
  * Logs all workflows that can be invoked externally, rather than directly by the application:
@@ -379,8 +482,14 @@ class DBOS {
379
482
  // Conductor stays connected for the drain, so it can still observe and cancel those workflows.
380
483
  if (executor) {
381
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
+ }
382
491
  await executor.awaitRunningWorkflows(drainTimeoutMS);
383
- await executor.stopWorkflowTimeoutSweep();
492
+ await executor.stopBackgroundJobs();
384
493
  }
385
494
  // Stop the conductor
386
495
  if (executor?.conductor) {
@@ -462,6 +571,11 @@ class DBOS {
462
571
  static get workflowID() {
463
572
  return (0, context_1.getCurrentContextStore)()?.workflowId;
464
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
+ }
465
579
  /** Use portable serialization by default? */
466
580
  static get #defaultSerializationType() {
467
581
  return (0, context_1.getCurrentContextStore)()?.serializationType;
@@ -524,21 +638,23 @@ class DBOS {
524
638
  * @param workflowID - ID of the workflow
525
639
  * @returns status of the workflow as `WorkflowStatus`, or `null` if there is no workflow with `workflowID`
526
640
  */
527
- static getWorkflowStatus(workflowID) {
641
+ static async getWorkflowStatus(workflowID, options) {
528
642
  (0, decorators_1.ensureDBOSIsLaunched)('getWorkflowStatus');
529
- if (DBOS.isWithinWorkflow()) {
530
- if (DBOS.isInStep()) {
531
- // OK to use directly
532
- return DBOS.#executor.getWorkflowStatus(workflowID);
533
- }
534
- else if (DBOS.isInWorkflow()) {
535
- return DBOS.#executor.getWorkflowStatus(workflowID, DBOS.workflowID, (0, context_1.functionIDGetIncrement)());
536
- }
537
- else {
538
- 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
+ }
539
655
  }
540
- }
541
- return DBOS.#executor.getWorkflowStatus(workflowID);
656
+ return DBOS.#executor.getWorkflowStatus(workflowID);
657
+ });
542
658
  }
543
659
  /**
544
660
  * Get the workflow result, given a workflow ID
@@ -555,7 +671,8 @@ class DBOS {
555
671
  // Reserve the function ID synchronously, before any await.
556
672
  timerFuncID = (0, context_1.functionIDGetIncrement)();
557
673
  }
558
- 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));
559
676
  }
560
677
  /**
561
678
  * Wait for any one of the given workflow handles to complete and return it.
@@ -579,9 +696,9 @@ class DBOS {
579
696
  handleMap.set(handle.workflowID, handle);
580
697
  }
581
698
  const workflowIds = [...handleMap.keys()];
582
- const completedId = await runInternalStep(async () => {
699
+ const completedId = await (0, shard_keys_1.bindShardKeys)(handles.map((h) => [h.workflowID, h.shardKey]), () => runInternalStep(async () => {
583
700
  return await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.awaitFirstWorkflowId(workflowIds, DBOS.workflowID, pollingIntervalMs);
584
- }, 'DBOS.waitFirst');
701
+ }, 'DBOS.waitFirst'));
585
702
  return handleMap.get(completedId);
586
703
  }
587
704
  /**
@@ -598,9 +715,9 @@ class DBOS {
598
715
  }
599
716
  const pollingIntervalMs = resolvePollingIntervalMs(options);
600
717
  const workflowIds = [...new Set(handles.map((handle) => handle.workflowID))];
601
- await runInternalStep(async () => {
718
+ await (0, shard_keys_1.bindShardKeys)(handles.map((h) => [h.workflowID, h.shardKey]), () => runInternalStep(async () => {
602
719
  await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.awaitWorkflowIds(workflowIds, DBOS.workflowID, pollingIntervalMs);
603
- }, 'DBOS.waitAll');
720
+ }, 'DBOS.waitAll'));
604
721
  return handles;
605
722
  }
606
723
  /**
@@ -610,15 +727,14 @@ class DBOS {
610
727
  * @param workflowID - ID of the workflow
611
728
  * @returns `WorkflowHandle` that can be used to poll for the status or result of any workflow with `workflowID`
612
729
  */
613
- static retrieveWorkflow(workflowID) {
730
+ static retrieveWorkflow(workflowID, options) {
614
731
  (0, decorators_1.ensureDBOSIsLaunched)('retrieveWorkflow');
615
- if (DBOS.isWithinWorkflow()) {
616
- if (!DBOS.isInWorkflow()) {
617
- throw new error_1.DBOSInvalidWorkflowTransitionError('Invalid call to `retrieveWorkflow` inside a `transaction` or `step`');
618
- }
619
- 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`');
620
734
  }
621
- 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);
622
738
  }
623
739
  /**
624
740
  * Query the system database for all workflows matching the provided predicate
@@ -648,14 +764,14 @@ class DBOS {
648
764
  * @param workflowID - ID of the workflow
649
765
  * @param priority - Priority value (0 to 2,147,483,647). Lower values are dequeued first.
650
766
  */
651
- static async setWorkflowPriority(workflowID, priority) {
767
+ static async setWorkflowPriority(workflowID, priority, options) {
652
768
  (0, decorators_1.ensureDBOSIsLaunched)('setWorkflowPriority');
653
769
  if (priority < dbos_executor_1.DBOS_QUEUE_MIN_PRIORITY || priority > dbos_executor_1.DBOS_QUEUE_MAX_PRIORITY) {
654
770
  throw new error_1.DBOSInvalidQueuePriorityError(priority, dbos_executor_1.DBOS_QUEUE_MIN_PRIORITY, dbos_executor_1.DBOS_QUEUE_MAX_PRIORITY);
655
771
  }
656
- return runInternalStep(async () => {
772
+ return (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], () => runInternalStep(async () => {
657
773
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.setWorkflowPriority(workflowID, priority);
658
- }, 'DBOS.setWorkflowPriority');
774
+ }, 'DBOS.setWorkflowPriority'));
659
775
  }
660
776
  /**
661
777
  * Update the delay on a DELAYED workflow.
@@ -667,9 +783,10 @@ class DBOS {
667
783
  static async setWorkflowDelay(workflowID, options) {
668
784
  (0, decorators_1.ensureDBOSIsLaunched)('setWorkflowDelay');
669
785
  const delayUntilEpochMS = resolveDelayEpochMS(options);
670
- return runInternalStep(async () => {
786
+ const shardKey = typeof options === 'object' ? options.shardKey : undefined;
787
+ return (0, shard_keys_1.bindShardKeys)([[workflowID, shardKey]], () => runInternalStep(async () => {
671
788
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.setWorkflowDelay(workflowID, delayUntilEpochMS);
672
- }, 'DBOS.setWorkflowDelay');
789
+ }, 'DBOS.setWorkflowDelay'));
673
790
  }
674
791
  /**
675
792
  * Retrieve the steps of a workflow
@@ -679,9 +796,9 @@ class DBOS {
679
796
  */
680
797
  static async listWorkflowSteps(workflowID, options) {
681
798
  (0, decorators_1.ensureDBOSIsLaunched)('listWorkflowSteps');
682
- return await runInternalStep(async () => {
799
+ return await (0, shard_keys_1.bindShardKeys)([[workflowID, options?.shardKey]], () => runInternalStep(async () => {
683
800
  return await DBOS.#executor.listWorkflowSteps(workflowID, true, options);
684
- }, 'DBOS.listWorkflowSteps');
801
+ }, 'DBOS.listWorkflowSteps'));
685
802
  }
686
803
  /**
687
804
  * Cancel a workflow given its ID.
@@ -700,9 +817,9 @@ class DBOS {
700
817
  */
701
818
  static async cancelWorkflows(workflowIDs, options) {
702
819
  (0, decorators_1.ensureDBOSIsLaunched)('cancelWorkflows');
703
- return runInternalStep(async () => {
820
+ return (0, shard_keys_1.bindShardKeys)(workflowIDs.map((wid) => [wid, options?.shardKey]), () => runInternalStep(async () => {
704
821
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.cancelWorkflows(workflowIDs, options?.cancelChildren);
705
- }, 'DBOS.cancelWorkflow');
822
+ }, 'DBOS.cancelWorkflow'));
706
823
  }
707
824
  /**
708
825
  * Resume a workflow given its ID.
@@ -710,8 +827,11 @@ class DBOS {
710
827
  * @throws DBOSNonExistentWorkflowError if the workflow does not exist
711
828
  */
712
829
  static async resumeWorkflow(workflowID, options) {
713
- const handles = await this.resumeWorkflows([workflowID], options);
714
- 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
+ });
715
835
  }
716
836
  /**
717
837
  * Resume multiple workflows given their IDs.
@@ -721,10 +841,12 @@ class DBOS {
721
841
  */
722
842
  static async resumeWorkflows(workflowIDs, options) {
723
843
  (0, decorators_1.ensureDBOSIsLaunched)('resumeWorkflows');
724
- await runInternalStep(async () => {
725
- return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.resumeWorkflows(workflowIDs, options?.queueName);
726
- }, 'DBOS.resumeWorkflow');
727
- 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
+ });
728
850
  }
729
851
  /**
730
852
  * Delete a workflow and optionally all its child workflows.
@@ -735,8 +857,8 @@ class DBOS {
735
857
  * @param workflowID - ID of the workflow to delete
736
858
  * @param deleteChildren - If true, also delete all child workflows recursively (default: false)
737
859
  */
738
- static async deleteWorkflow(workflowID, deleteChildren = false) {
739
- return this.deleteWorkflows([workflowID], deleteChildren);
860
+ static async deleteWorkflow(workflowID, deleteChildren = false, options) {
861
+ return this.deleteWorkflows([workflowID], deleteChildren, options);
740
862
  }
741
863
  /**
742
864
  * Delete multiple workflows and optionally all their child workflows.
@@ -746,11 +868,11 @@ class DBOS {
746
868
  * @param workflowIDs - IDs of the workflows to delete
747
869
  * @param deleteChildren - If true, also delete all child workflows recursively (default: false)
748
870
  */
749
- static async deleteWorkflows(workflowIDs, deleteChildren = false) {
871
+ static async deleteWorkflows(workflowIDs, deleteChildren = false, options) {
750
872
  (0, decorators_1.ensureDBOSIsLaunched)('deleteWorkflows');
751
- return runInternalStep(async () => {
873
+ return (0, shard_keys_1.bindShardKeys)(workflowIDs.map((wid) => [wid, options?.shardKey]), () => runInternalStep(async () => {
752
874
  return dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.deleteWorkflows(workflowIDs, deleteChildren);
753
- }, 'DBOS.deleteWorkflow');
875
+ }, 'DBOS.deleteWorkflow'));
754
876
  }
755
877
  /**
756
878
  * Fork a workflow given its ID.
@@ -762,10 +884,14 @@ class DBOS {
762
884
  */
763
885
  static async forkWorkflow(workflowID, startStep, options) {
764
886
  (0, decorators_1.ensureDBOSIsLaunched)('forkWorkflow');
765
- const forkedID = await runInternalStep(async () => {
766
- return await DBOS.#executor.forkWorkflow(workflowID, startStep, options);
767
- }, 'DBOS.forkWorkflow');
768
- 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
+ });
769
895
  }
770
896
  /**
771
897
  * Rewind a workflow given its ID: drop its recorded history from `startStep` onwards
@@ -789,10 +915,13 @@ class DBOS {
789
915
  static async rewindWorkflow(workflowID, options) {
790
916
  (0, decorators_1.ensureDBOSIsLaunched)('rewindWorkflow');
791
917
  const startStep = options?.startStep ?? 0;
792
- await runInternalStep(async () => {
793
- return await DBOS.#executor.rewindWorkflow(workflowID, startStep, options ?? {});
794
- }, 'DBOS.rewindWorkflow');
795
- 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
+ });
796
925
  }
797
926
  /**
798
927
  * Sleep for the specified amount of time.
@@ -907,6 +1036,13 @@ class DBOS {
907
1036
  (0, decorators_1.ensureDBOSIsLaunched)('workflows');
908
1037
  return DBOS.#withTopContext({ workflowTimeoutMS: timeoutMS }, callback);
909
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
+ }
910
1046
  static async #withTopContext(options, callback) {
911
1047
  const pctx = (0, context_1.getCurrentContextStore)();
912
1048
  if (pctx) {
@@ -994,16 +1130,16 @@ class DBOS {
994
1130
  // calls in the same workflow don't race for IDs.
995
1131
  const functionID = (0, context_1.functionIDGetIncrement)();
996
1132
  const sermsg = await (0, serialization_1.serializeValue)(message, DBOS.#executor.serializer, options?.serializationType ?? DBOS.#defaultSerializationType);
997
- 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);
998
1134
  }
999
1135
  else if (DBOS.isInStep()) {
1000
1136
  // Inside a step: not recorded, but fenced on the enclosing workflow's ownership.
1001
1137
  const sermsg = await (0, serialization_1.serializeValue)(message, DBOS.#executor.serializer, options?.serializationType ?? DBOS.#defaultSerializationType);
1002
- 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);
1003
1139
  }
1004
1140
  else {
1005
1141
  const sermsg = await (0, serialization_1.serializeValue)(message, DBOS.#executor.serializer, options?.serializationType ?? DBOS.#defaultSerializationType);
1006
- 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);
1007
1143
  }
1008
1144
  }
1009
1145
  /**
@@ -1071,6 +1207,10 @@ class DBOS {
1071
1207
  */
1072
1208
  static async getEvent(workflowID, key, options) {
1073
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) {
1074
1214
  const timeoutSeconds = resolveTimeoutSeconds(options);
1075
1215
  const pollingIntervalMs = resolvePollingIntervalMs(options);
1076
1216
  if (DBOS.isWithinWorkflow()) {
@@ -1148,6 +1288,7 @@ class DBOS {
1148
1288
  timeoutMS: resolveStreamTimeoutMS(options),
1149
1289
  functionName: system_database_1.DBOS_FUNCNAME_READSTREAM,
1150
1290
  checkpoint: true,
1291
+ shardKey: options.shardKey,
1151
1292
  });
1152
1293
  }
1153
1294
  /**
@@ -1171,6 +1312,7 @@ class DBOS {
1171
1312
  timeoutMS: resolveStreamTimeoutMS(options),
1172
1313
  functionName: system_database_1.DBOS_FUNCNAME_READSTREAMOFFSET,
1173
1314
  checkpoint: true,
1315
+ shardKey: options.shardKey,
1174
1316
  });
1175
1317
  }
1176
1318
  //////
@@ -1227,6 +1369,8 @@ class DBOS {
1227
1369
  const ppctx = (0, context_1.getCurrentContextStore)();
1228
1370
  const queueName = params.queueName ?? ppctx?.queueAssignedForWorkflows;
1229
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);
1230
1374
  const instance = $this === undefined || typeof $this === 'function' ? undefined : $this;
1231
1375
  if (instance && !(instance instanceof decorators_1.ConfiguredInstance)) {
1232
1376
  throw new error_1.DBOSInvalidWorkflowTransitionError('Attempt to call a `workflow` function on an object that is not a `ConfiguredInstance`');
@@ -1264,7 +1408,7 @@ class DBOS {
1264
1408
  if (isChild) {
1265
1409
  const pwfid = ppctx.workflowId;
1266
1410
  const wfParams = {
1267
- workflowUUID: wfId || pwfid + '-' + funcId,
1411
+ workflowUUID: wfId || (0, context_1.childWorkflowID)(pwfid, funcId, ppctx?.shardKey, shardKey),
1268
1412
  configuredInstance: instance,
1269
1413
  queueName,
1270
1414
  timeoutMS,
@@ -1276,6 +1420,7 @@ class DBOS {
1276
1420
  workflowAttributes: params.workflowAttributes,
1277
1421
  authenticatedUser: params.authenticatedUser,
1278
1422
  authenticatedRoles: params.authenticatedRoles,
1423
+ shardKey,
1279
1424
  };
1280
1425
  return await invokeRegOp(wfParams, pwfid, funcId);
1281
1426
  }
@@ -1291,6 +1436,7 @@ class DBOS {
1291
1436
  workflowAttributes: params.workflowAttributes,
1292
1437
  authenticatedUser: params.authenticatedUser,
1293
1438
  authenticatedRoles: params.authenticatedRoles,
1439
+ shardKey,
1294
1440
  };
1295
1441
  return await invokeRegOp(wfParams, undefined, undefined);
1296
1442
  }
@@ -1317,6 +1463,8 @@ class DBOS {
1317
1463
  // Reserve the parent's child-funcID once, before any await. Each loop iteration passes it
1318
1464
  // through so the return-existing retry loop consumes a single funcID instead of one per try.
1319
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)());
1320
1468
  // Resolve the workflow ID once: if the caller supplied one explicitly or via
1321
1469
  // `withNextWorkflowID`, reuse it on every iteration.
1322
1470
  const resolvedWorkflowID = (0, context_1.getNextWFID)(params.workflowID);
@@ -1337,7 +1485,7 @@ class DBOS {
1337
1485
  const now = Date.now();
1338
1486
  await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.recordOperationResult(DBOS.workflowID, childFuncId, regOP.name, true, now, now, { childWorkflowID: existingID });
1339
1487
  }
1340
- return new workflow_1.RetrievedHandle(existingID);
1488
+ return new workflow_1.RetrievedHandle(existingID, shardKey);
1341
1489
  }
1342
1490
  // The prior workflow's deduplication_id was cleared between our INSERT and
1343
1491
  // the lookup (it completed or was cancelled). Loop and try to claim the slot.
@@ -1472,6 +1620,21 @@ class DBOS {
1472
1620
  }
1473
1621
  return func();
1474
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
+ }
1475
1638
  /**
1476
1639
  * Register serialization recipe; this is used to save/retrieve objects from the DBOS system
1477
1640
  * database. This includes workflow inputs, function return values, messages, and events.
@@ -1500,9 +1663,6 @@ class DBOS {
1500
1663
  if (!DBOS.isInWorkflow()) {
1501
1664
  throw new error_1.DBOSInvalidWorkflowTransitionError('`DBOS.patch` must be called from a workflow, and not within a step');
1502
1665
  }
1503
- if (!DBOS.#dbosConfig?.enablePatching) {
1504
- throw new error_1.DBOSInvalidWorkflowTransitionError('Patching is not enabled. See `enablePatching` in `DBOSConfig`');
1505
- }
1506
1666
  const patched = await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.checkPatch(DBOS.workflowID, (0, context_1.functionIDGet)(), patchName, false);
1507
1667
  if (patched.hasEntry) {
1508
1668
  (0, context_1.functionIDGetIncrement)();
@@ -1522,9 +1682,6 @@ class DBOS {
1522
1682
  if (!DBOS.isInWorkflow()) {
1523
1683
  throw new error_1.DBOSInvalidWorkflowTransitionError('`DBOS.deprecatePatch` must be called from a workflow, and not within a step');
1524
1684
  }
1525
- if (!DBOS.#dbosConfig?.enablePatching) {
1526
- throw new error_1.DBOSInvalidWorkflowTransitionError('Patching is not enabled. See `enablePatching` in `DBOSConfig`');
1527
- }
1528
1685
  const patched = await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.checkPatch(DBOS.workflowID, (0, context_1.functionIDGet)(), patchName, true);
1529
1686
  if (patched.hasEntry) {
1530
1687
  (0, context_1.functionIDGetIncrement)();
@@ -1612,6 +1769,7 @@ class DBOS {
1612
1769
  cronTimezone: options.options?.cronTimezone ?? null,
1613
1770
  queueName: options.options?.queueName ?? null,
1614
1771
  applicationName: utils_1.globalParams.appName,
1772
+ shardKey: options.options?.shardKey,
1615
1773
  };
1616
1774
  await runTransactionalInternalStep((client) => dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.createSchedule(schedInternal, client), 'DBOS.createSchedule');
1617
1775
  }
@@ -1697,6 +1855,7 @@ class DBOS {
1697
1855
  automaticBackfill: sched.automaticBackfill ?? false,
1698
1856
  cronTimezone: sched.cronTimezone ?? null,
1699
1857
  queueName: sched.queueName ?? null,
1858
+ shardKey: sched.shardKey,
1700
1859
  });
1701
1860
  }
1702
1861
  await dbos_executor_1.DBOSExecutor.globalInstance.systemDatabase.applySchedules(internals);
@@ -1708,7 +1867,7 @@ class DBOS {
1708
1867
  }
1709
1868
  const executor = dbos_executor_1.DBOSExecutor.globalInstance;
1710
1869
  const workflowID = await (0, scheduler_1.triggerSchedule)(executor.systemDatabase, executor.serializer, name);
1711
- return new workflow_1.RetrievedHandle(workflowID);
1870
+ return new workflow_1.RetrievedHandle(workflowID, await (0, scheduler_1.scheduleShardKey)(executor.systemDatabase, name));
1712
1871
  }
1713
1872
  static async backfillSchedule(name, start, end) {
1714
1873
  (0, decorators_1.ensureDBOSIsLaunched)('backfillSchedule');
@@ -1717,7 +1876,8 @@ class DBOS {
1717
1876
  }
1718
1877
  const executor = dbos_executor_1.DBOSExecutor.globalInstance;
1719
1878
  const workflowIDs = await (0, scheduler_1.backfillSchedule)(executor.systemDatabase, executor.serializer, name, start, end);
1720
- 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));
1721
1881
  }
1722
1882
  // ==================== Application Versions ====================
1723
1883
  /**