@brandboostinggmbh/observable-workflows 0.21.1 → 0.22.0

package/dist/index.d.ts

@@ -91,6 +91,16 @@ interface PrepareWorkflowInsertParams {
    * When provided, dependency insert statements are included in the returned statements array.
    */
   dependencies?: Array<WorkflowDependency>;
+  /**
+   * Optional delay in seconds before the queue message is delivered.
+   * Stored in the DB for transparency so the original delay intent is preserved.
+   */
+  delaySeconds?: number | null;
+  /**
+   * Absolute epoch-millisecond timestamp indicating the earliest time the queue message
+   * will be delivered. `null` or absent when no delay was requested.
+   */
+  scheduledFor?: number | null;
 }
 /** Result from preparing workflow insert statements */
 
@@ -214,6 +224,8 @@ declare function workflowTableRowToWorkflowRun({
     endTime: number | null;
     parentInstanceId: string | null;
     triggerId: string | null;
+    delaySeconds?: number | null;
+    scheduledFor?: number | null;
   };
   serializer: Serializer;
   externalBlobStorage?: ExternalBlobStorage;
@@ -259,6 +271,8 @@ declare function updateWorkflow(context: InternalWorkflowContextOptions, instanc
   startTime?: number;
   parentInstanceId?: string | null;
   triggerId?: string | null;
+  delaySeconds?: number | null;
+  scheduledFor?: number | null;
 }): Promise<D1Result<Record<string, unknown>> | {
   success: boolean;
   meta: {
@@ -484,6 +498,22 @@ type WorkflowRun = {
   isRetryOf?: WorkflowRun | null;
   retries?: WorkflowRun[] | null;
   properties?: WorkflowProperty[];
+  /**
+   * Optional queue delivery delay in seconds. Stored for transparency so the original
+   * delay intent is preserved. For waiting workflows, this value is applied when the
+   * workflow transitions from 'waiting' to 'scheduled'.
+   */
+  delaySeconds?: number | null;
+  /**
+   * Absolute epoch-millisecond timestamp indicating the earliest time the queue message
+   * will be delivered. Computed as `enqueueTime + delaySeconds * 1000` at the moment the
+   * message is actually sent to the queue.
+   *
+   * - For directly-scheduled workflows: set at enqueue time.
+   * - For waiting workflows: set when dependencies finish and the workflow transitions to 'scheduled'.
+   * - `null` or absent when no delay was requested.
+   */
+  scheduledFor?: number | null;
   /** Workflows that this workflow depends on (must complete before this workflow can start) */
   dependencies?: WorkflowDependencyRelation[];
   /** Workflows that depend on this workflow (will start after this workflow completes) */
@@ -694,6 +724,12 @@ type WorkflowEnqueueBatchItem<I, O, TYPE extends string = string> = {
   dependencies?: WorkflowDependency[];
   /** Optional trigger identifier for workflow correlation. If not provided, one will be auto-generated. */
   triggerId?: string | null;
+  /**
+   * Optional delay in seconds before the queue message is delivered.
+   * Maps directly to the Cloudflare Queue `delaySeconds` option.
+   * The message will not be delivered to a consumer until at least this many seconds have passed.
+   */
+  delaySeconds?: number;
 };
 type WorkflowQueueMessage = {
   type: 'workflow-run';
@@ -704,6 +740,8 @@ type WorkflowQueueMessage = {
   triggerId?: string | null;
   queueIdentifier?: string;
   scheduledInstanceId?: string | undefined;
+  /** Queue delivery delay in seconds (passed through to Cloudflare Queue) */
+  delaySeconds?: number;
 } | {
   type: 'workflow-retry';
   workflowType: string;
@@ -713,6 +751,7 @@ type WorkflowQueueMessage = {
   /** If true the workflow will attempt to reuse all results from successful steps. Defaults to True */
   reuseSuccessfulSteps?: boolean;
   queueIdentifier?: string;
+  scheduledInstanceId?: string | undefined;
 };
 type RetryWorkflowOptions = {
   /** If true the retry will attept to reuse all results from successful steps. Defaults to True */
@@ -723,6 +762,8 @@ type RetryWorkflowParams<I, O> = {
   retryInstanceId: string;
   triggerId?: string | null;
   retryOptions?: RetryWorkflowOptions;
+  /** Optional: Provide an existing workflow instance ID. When provided, retry will update the existing instance instead of creating a new one. */
+  scheduledInstanceId?: string | undefined;
 };
 type WorkflowCallParams<I, O> = {
   workflow: WorkflowFunction<I, O>;
@@ -878,7 +919,7 @@ declare const createLogAccessor: (context: {
 declare function createQueueWorkflowContext(options: QueueWorkflowContextOptions): {
   enqueueWorkflow: <I, O, TYPE extends string>(params: WorkflowEnqueueBatchItem<I, O, TYPE>) => Promise<ScheduledWorkflowExecutionStub<O, TYPE>>;
   enqueueWorkflowBatch: <I, O>(workflows: Array<WorkflowEnqueueBatchItem<I, O>>) => Promise<Array<ScheduledWorkflowExecutionStub<O, string>>>;
-  enqueueRetryWorkflow: <I, O>(workflow: WorkflowFunction<I, O>, tenantId: string, oldInstanceId: string, reuseSuccessfulSteps?: boolean) => Promise<void>;
+  enqueueRetryWorkflow: <I, O, TYPE extends string>(workflow: WorkflowFunction<I, O, TYPE>, tenantId: string, oldInstanceId: string, reuseSuccessfulSteps?: boolean, delaySeconds?: number) => Promise<ScheduledWorkflowExecutionStub<O, TYPE>>;
   handleWorkflowQueueMessage: ({
     message,
     env,

package/dist/index.js

@@ -9,8 +9,10 @@ async function detectSchemaVersion(db, retryConfig) {
 		const hasInputRef = workflowTableInfo.sql.includes("inputRef");
 		const hasTriggerId = workflowTableInfo.sql.includes("triggerId");
 		const hasResultRef = workflowTableInfo.sql.includes("resultRef");
+		const hasDelaySeconds = workflowTableInfo.sql.includes("delaySeconds");
 		const inputHasNotNull = workflowTableInfo.sql.includes("input TEXT NOT NULL");
-		if (hasResultRef && hasTriggerId && hasInputRef && !inputHasNotNull) workflowTable = "v6";
+		if (hasDelaySeconds && hasResultRef && hasTriggerId && hasInputRef && !inputHasNotNull) workflowTable = "v8";
+		else if (hasResultRef && hasTriggerId && hasInputRef && !inputHasNotNull) workflowTable = "v6";
 		else if (hasTriggerId && hasInputRef && !inputHasNotNull && !hasResultRef) workflowTable = "v4";
 		else if (hasInputRef && !inputHasNotNull && !hasTriggerId) workflowTable = "v2";
 		else if (!hasInputRef && inputHasNotNull) workflowTable = "v1";
@@ -123,6 +125,23 @@ async function migrateWorkflowTableV4ToV6(db, retryConfig) {
 	if (!hasResultRef) await retryD1Operation(() => db.batch([db.prepare(`ALTER TABLE WorkflowTable ADD COLUMN result TEXT`), db.prepare(`ALTER TABLE WorkflowTable ADD COLUMN resultRef TEXT`)]), retryConfig);
 }
 /**
+* Migrate WorkflowTable from V6 to V8 schema
+* Adds delaySeconds and scheduledFor columns for delayed workflow scheduling.
+*
+* - `delaySeconds` (INTEGER, nullable): The original delay intent in seconds. Preserved so that
+*   waiting workflows can apply the delay when they transition to 'scheduled'.
+* - `scheduledFor` (INTEGER, nullable): Absolute epoch-millisecond timestamp indicating the
+*   earliest time the queue message will be delivered. For directly-scheduled workflows this is
+*   computed at enqueue time (`startTime + delaySeconds * 1000`). For waiting workflows it is
+*   computed at transition time (`transitionTime + delaySeconds * 1000`). NULL when no delay
+*   was requested.
+*/
+async function migrateWorkflowTableV6ToV8(db, retryConfig) {
+	const workflowTableInfo = await retryD1Operation(() => db.prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='WorkflowTable'`).first(), retryConfig);
+	const hasDelaySeconds = workflowTableInfo.sql.includes("delaySeconds");
+	if (!hasDelaySeconds) await retryD1Operation(() => db.batch([db.prepare(`ALTER TABLE WorkflowTable ADD COLUMN delaySeconds INTEGER`), db.prepare(`ALTER TABLE WorkflowTable ADD COLUMN scheduledFor INTEGER`)]), retryConfig);
+}
+/**
 * Create or migrate WorkflowTable to the latest schema
 */
 async function migrateWorkflowTable(db, currentVersion, retryConfig) {
@@ -142,6 +161,8 @@ async function migrateWorkflowTable(db, currentVersion, retryConfig) {
           endTime INTEGER,
           parentInstanceId TEXT,
           triggerId TEXT,
+          delaySeconds INTEGER,
+          scheduledFor INTEGER,
           PRIMARY KEY (instanceId),
           UNIQUE (triggerId)
         )`).run(), retryConfig);
@@ -151,15 +172,22 @@ async function migrateWorkflowTable(db, currentVersion, retryConfig) {
 		await migrateWorkflowTableV1ToV2(db, retryConfig);
 		await migrateWorkflowTableV2V3ToV4(db, retryConfig);
 		await migrateWorkflowTableV4ToV6(db, retryConfig);
+		await migrateWorkflowTableV6ToV8(db, retryConfig);
 		return;
 	}
 	if (currentVersion === "v2") {
 		await migrateWorkflowTableV2V3ToV4(db, retryConfig);
 		await migrateWorkflowTableV4ToV6(db, retryConfig);
+		await migrateWorkflowTableV6ToV8(db, retryConfig);
 		return;
 	}
 	if (currentVersion === "v4") {
 		await migrateWorkflowTableV4ToV6(db, retryConfig);
+		await migrateWorkflowTableV6ToV8(db, retryConfig);
+		return;
+	}
+	if (currentVersion === "v6") {
+		await migrateWorkflowTableV6ToV8(db, retryConfig);
 		return;
 	}
 }
@@ -468,11 +496,11 @@ async function finalizeWorkflowRecord(options, { workflowStatus, endTime, instan
 *
 * @internal
 */
-async function prepareWorkflowInsertStatements(options, { instanceId, workflowType, workflowName, workflowMetadata, input, workflowStatus, startTime, endTime, parentInstanceId, tenantId, triggerId, dependencies }) {
+async function prepareWorkflowInsertStatements(options, { instanceId, workflowType, workflowName, workflowMetadata, input, workflowStatus, startTime, endTime, parentInstanceId, tenantId, triggerId, dependencies, delaySeconds, scheduledFor }) {
 	const { data: inputData, externalRef: inputRef } = await serializeWithExternalStorage(input, options.serializer, options.externalBlobStorage);
 	const insertWorkflowStatement = options.D1.prepare(`INSERT INTO WorkflowTable
-        (instanceId, workflowType, workflowName, workflowMetadata, input, inputRef, tenantId, workflowStatus, startTime, endTime, parentInstanceId, triggerId)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).bind(instanceId, workflowType, workflowName, options.serializer.serialize(workflowMetadata), inputData, inputRef, tenantId, workflowStatus, startTime, endTime ?? null, parentInstanceId ?? null, triggerId ?? null);
+        (instanceId, workflowType, workflowName, workflowMetadata, input, inputRef, tenantId, workflowStatus, startTime, endTime, parentInstanceId, triggerId, delaySeconds, scheduledFor)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).bind(instanceId, workflowType, workflowName, options.serializer.serialize(workflowMetadata), inputData, inputRef, tenantId, workflowStatus, startTime, endTime ?? null, parentInstanceId ?? null, triggerId ?? null, delaySeconds ?? null, scheduledFor ?? null);
 	if (!dependencies || dependencies.length === 0) return {
 		statements: [insertWorkflowStatement],
 		instanceId,
@@ -777,7 +805,9 @@ async function workflowTableRowToWorkflowRun({ row, serializer, externalBlobStor
 		startTime: row.startTime,
 		endTime: row.endTime,
 		parentInstanceId: row.parentInstanceId,
-		triggerId: row.triggerId
+		triggerId: row.triggerId,
+		delaySeconds: row.delaySeconds ?? null,
+		scheduledFor: row.scheduledFor ?? null
 	};
 }
 async function updateWorkflowName(context, instanceId, newWorkflowName) {
@@ -840,6 +870,14 @@ async function updateWorkflow(context, instanceId, updates) {
 		setClauses.push("triggerId = ?");
 		bindings.push(updates.triggerId);
 	}
+	if (updates.delaySeconds !== void 0) {
+		setClauses.push("delaySeconds = ?");
+		bindings.push(updates.delaySeconds);
+	}
+	if (updates.scheduledFor !== void 0) {
+		setClauses.push("scheduledFor = ?");
+		bindings.push(updates.scheduledFor);
+	}
 	if (updates.workflowMetadata !== void 0) {
 		setClauses.push("workflowMetadata = ?");
 		bindings.push(context.serializer.serialize(updates.workflowMetadata));
@@ -1785,7 +1823,7 @@ function createQueueWorkflowContext(options) {
 	};
 	const idFactory = internalContext.idFactory;
 	const enqueueWorkflow = async (params) => {
-		const { workflow, tenantId, input, initialName, dependencies, triggerId: providedTriggerId } = params;
+		const { workflow, tenantId, input, initialName, dependencies, triggerId: providedTriggerId, delaySeconds } = params;
 		const triggerId = providedTriggerId ?? idFactory();
 		const instanceId = idFactory();
 		const startTime = Date.now();
@@ -1801,9 +1839,12 @@ function createQueueWorkflowContext(options) {
 			parentInstanceId: void 0,
 			tenantId,
 			triggerId,
-			dependencies
+			dependencies,
+			delaySeconds: delaySeconds ?? null,
+			scheduledFor: null
 		});
 		else {
+			const scheduledFor = delaySeconds != null ? startTime + delaySeconds * 1e3 : null;
 			await insertWorkflowRecord(internalContext, {
 				instanceId,
 				workflowType: workflow.workflowType,
@@ -1815,7 +1856,9 @@ function createQueueWorkflowContext(options) {
 				endTime: null,
 				parentInstanceId: void 0,
 				tenantId,
-				triggerId
+				triggerId,
+				delaySeconds: delaySeconds ?? null,
+				scheduledFor
 			});
 			await options.QUEUE.send({
 				type: "workflow-run",
@@ -1826,15 +1869,42 @@ function createQueueWorkflowContext(options) {
 				triggerId,
 				queueIdentifier: options.queueIdentifier,
 				scheduledInstanceId: instanceId
-			});
+			}, delaySeconds != null ? { delaySeconds } : void 0);
 		}
 		return {
 			instanceId,
 			workflowType: workflow.workflowType
 		};
 	};
-	const enqueueRetryWorkflow = async (workflow, tenantId, oldInstanceId, reuseSuccessfulSteps) => {
+	const enqueueRetryWorkflow = async (workflow, tenantId, oldInstanceId, reuseSuccessfulSteps, delaySeconds) => {
 		const triggerId = idFactory();
+		const instanceId = idFactory();
+		const startTime = Date.now();
+		const scheduledFor = delaySeconds != null ? startTime + delaySeconds * 1e3 : null;
+		const logAccessor = createLogAccessor({
+			D1: options.D1,
+			externalBlobStorage: options.externalBlobStorage,
+			serializer: internalContext.serializer,
+			tenantId,
+			retryConfig: options.retryConfig
+		});
+		const oldRun = await logAccessor.getWorkflowShallow(oldInstanceId, { populateInput: true });
+		if (!oldRun) throw new Error(`Cannot retry: no workflow found for instanceId ${oldInstanceId}`);
+		await insertWorkflowRecord(internalContext, {
+			instanceId,
+			workflowType: workflow.workflowType,
+			workflowName: oldRun.workflowName ?? "unknown",
+			workflowMetadata: workflow.metadata,
+			input: oldRun.input,
+			workflowStatus: "scheduled",
+			startTime,
+			endTime: null,
+			parentInstanceId: oldInstanceId,
+			tenantId,
+			triggerId,
+			delaySeconds: delaySeconds ?? null,
+			scheduledFor
+		});
 		await options.QUEUE.send({
 			type: "workflow-retry",
 			workflowType: workflow.workflowType,
@@ -1842,8 +1912,13 @@ function createQueueWorkflowContext(options) {
 			tenantId,
 			triggerId,
 			reuseSuccessfulSteps: reuseSuccessfulSteps ?? true,
-			queueIdentifier: options.queueIdentifier
-		});
+			queueIdentifier: options.queueIdentifier,
+			scheduledInstanceId: instanceId
+		}, delaySeconds != null ? { delaySeconds } : void 0);
+		return {
+			instanceId,
+			workflowType: workflow.workflowType
+		};
 	};
 	/**
 	* Enqueue multiple workflows in a single batch operation.
@@ -1866,10 +1941,11 @@ function createQueueWorkflowContext(options) {
 		if (workflows.length > 100) throw new Error(`enqueueWorkflowBatch: Cannot enqueue more than 100 workflows in a single batch (received ${workflows.length}). Split into smaller chunks.`);
 		const startTime = Date.now();
 		console.log(`enqueueWorkflowBatch: Starting batch of ${workflows.length} workflows`);
-		const preparedWorkflows = await Promise.all(workflows.map(async ({ workflow, tenantId, input, initialName, dependencies, triggerId: providedTriggerId }) => {
+		const preparedWorkflows = await Promise.all(workflows.map(async ({ workflow, tenantId, input, initialName, dependencies, triggerId: providedTriggerId, delaySeconds }) => {
 			const instanceId = idFactory();
 			const triggerId = providedTriggerId ?? idFactory();
 			const hasDependencies = dependencies && dependencies.length > 0;
+			const scheduledFor = !hasDependencies && delaySeconds != null ? startTime + delaySeconds * 1e3 : null;
 			const prepared = await prepareWorkflowInsertStatements(internalContext, {
 				instanceId,
 				workflowType: workflow.workflowType,
@@ -1882,14 +1958,17 @@ function createQueueWorkflowContext(options) {
 				parentInstanceId: void 0,
 				tenantId,
 				triggerId,
-				dependencies
+				dependencies,
+				delaySeconds: delaySeconds ?? null,
+				scheduledFor
 			});
 			return {
 				...prepared,
 				tenantId,
 				triggerId,
 				initialName,
-				shouldQueue: !hasDependencies
+				shouldQueue: !hasDependencies,
+				delaySeconds
 			};
 		}));
 		const workflowsWithDeps = preparedWorkflows.filter((p) => !p.shouldQueue).length;
@@ -1900,16 +1979,19 @@ function createQueueWorkflowContext(options) {
 			console.log(`enqueueWorkflowBatch: Executing D1 batch with ${allStatements.length} statements`);
 			await retryD1Operation(() => options.D1.batch(allStatements), options.retryConfig);
 		}
-		const messagesToQueue = preparedWorkflows.filter((p) => p.shouldQueue).map((p) => ({ body: {
-			type: "workflow-run",
-			workflowType: p.workflowType,
-			workflowName: p.initialName,
-			input: workflows.find((w) => w.workflow.workflowType === p.workflowType && w.initialName === p.initialName)?.input,
-			tenantId: p.tenantId,
-			triggerId: p.triggerId,
-			queueIdentifier: options.queueIdentifier,
-			scheduledInstanceId: p.instanceId
-		} }));
+		const messagesToQueue = preparedWorkflows.filter((p) => p.shouldQueue).map((p) => ({
+			body: {
+				type: "workflow-run",
+				workflowType: p.workflowType,
+				workflowName: p.initialName,
+				input: workflows.find((w) => w.workflow.workflowType === p.workflowType && w.initialName === p.initialName)?.input,
+				tenantId: p.tenantId,
+				triggerId: p.triggerId,
+				queueIdentifier: options.queueIdentifier,
+				scheduledInstanceId: p.instanceId
+			},
+			...p.delaySeconds != null ? { delaySeconds: p.delaySeconds } : {}
+		}));
 		if (messagesToQueue.length > 0) {
 			console.log(`enqueueWorkflowBatch: Sending ${messagesToQueue.length} messages to queue`);
 			await options.QUEUE.sendBatch(messagesToQueue);
@@ -1942,7 +2024,8 @@ function createQueueWorkflowContext(options) {
 				workflow: workflowFunction,
 				retryInstanceId: message.retryInstanceId,
 				triggerId: message.triggerId,
-				retryOptions: { reuseSuccessfulSteps: message.reuseSuccessfulSteps ?? true }
+				retryOptions: { reuseSuccessfulSteps: message.reuseSuccessfulSteps ?? true },
+				scheduledInstanceId: message.scheduledInstanceId
 			});
 		}
 	};
@@ -1968,7 +2051,12 @@ function createQueueWorkflowContext(options) {
 			const allDepsFinished = dependencies.every((dep) => dep.workflow.workflowStatus === "completed" || dep.workflow.workflowStatus === "failed");
 			if (allDepsFinished) {
 				console.log(`Enqueuing waiting workflow ${wf.instanceId} as all dependencies are finished`);
-				await updateWorkflow(internalContext, wf.instanceId, { workflowStatus: "scheduled" });
+				const now = Date.now();
+				const scheduledFor = wf.delaySeconds != null ? now + wf.delaySeconds * 1e3 : null;
+				await updateWorkflow(internalContext, wf.instanceId, {
+					workflowStatus: "scheduled",
+					scheduledFor
+				});
 				await options.QUEUE.send({
 					type: "workflow-run",
 					workflowType: wf.workflowType,
@@ -1978,7 +2066,7 @@ function createQueueWorkflowContext(options) {
 					triggerId: wf.triggerId,
 					queueIdentifier: options.queueIdentifier,
 					scheduledInstanceId: wf.instanceId
-				});
+				}, wf.delaySeconds != null ? { delaySeconds: wf.delaySeconds } : void 0);
 			} else {
 				const unfinishedDeps = dependencies.filter((dep) => dep.workflow.workflowStatus !== "completed" && dep.workflow.workflowStatus !== "failed");
 				console.log(`Workflow ${wf.instanceId} is still waiting on dependencies. Unfinished dependencies: ${unfinishedDeps.map((d) => d.workflow.instanceId + ": " + d.workflow.workflowStatus).join(", ")}`);
@@ -2244,7 +2332,7 @@ function createWorkflowContext(options) {
 			throw error;
 		}
 	};
-	const retry = async ({ workflow, retryInstanceId, triggerId, retryOptions }) => {
+	const retry = async ({ workflow, retryInstanceId, triggerId, retryOptions, scheduledInstanceId }) => {
 		if (!ensuredTables) {
 			await ensureTables(options.D1, options.retryConfig);
 			ensuredTables = true;
@@ -2264,7 +2352,8 @@ function createWorkflowContext(options) {
 			parentInstanceId: retryInstanceId,
 			reuseSuccessfulSteps: retryOptions?.reuseSuccessfulSteps,
 			tenantId,
-			triggerId
+			triggerId,
+			scheduledInstanceId
 		});
 	};
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandboostinggmbh/observable-workflows",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "My awesome typescript library",
   "type": "module",
   "license": "MIT",