@notionhq/apps 0.0.17 → 0.0.18

package/src/workflow.ts

@@ -17,6 +17,7 @@ import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata, type RunMetadata } from "./runtime-metadata.js";
 import { createWorkflowTriggers } from "./triggers.generated.js";
+import { createWorkflowStepState, type WorkflowState } from "./workflow-state.js";
 import type {
 	WorkflowEventMap,
 	WorkflowTrigger,
@@ -29,6 +30,45 @@ type HandlerOptions = {
 	concreteOutput?: true;
 };
 
+type WorkflowWaitDurationValues = {
+	milliseconds?: number;
+	seconds?: number;
+	minutes?: number;
+	hours?: number;
+	days?: number;
+	weeks?: number;
+};
+
+export type WorkflowWaitDuration = {
+	[Unit in keyof WorkflowWaitDurationValues]-?: Required<Pick<WorkflowWaitDurationValues, Unit>> &
+		WorkflowWaitDurationValues;
+}[keyof WorkflowWaitDurationValues];
+
+type WorkflowWaitKey = string | string[];
+
+export type WorkflowWaitUntilOptions =
+	| {
+			at: Date;
+			key?: WorkflowWaitKey;
+	  }
+	| {
+			after: WorkflowWaitDuration;
+			key?: WorkflowWaitKey;
+	  };
+
+export type WorkflowWaitUntilResult = {
+	status: "waiting";
+	wait: {
+		type: "until";
+		name: string;
+		resumeAtMs: number;
+	};
+};
+
+type WorkflowHandlerResult = { status: "success" } | WorkflowWaitUntilResult;
+
+const MAX_WORKFLOW_WAIT_MS = 7 * 24 * 60 * 60 * 1_000;
+
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 
 export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
@@ -111,7 +151,7 @@ export type Workflow<
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
 		options?: HandlerOptions,
-	) => Promise<{ status: "success" } | undefined>;
+	) => Promise<WorkflowHandlerResult | undefined>;
 };
 
 /**
@@ -181,11 +221,12 @@ export function workflow<
 		async handler(
 			event: WorkflowEventForTriggers<TTriggers>,
 			options?: HandlerOptions,
-		): Promise<{ status: "success" } | undefined> {
+		): Promise<WorkflowHandlerResult | undefined> {
 			try {
 				event = await resolveRuntimeInput(event);
 				const runMetadata = readRunMetadata();
 				const baseContext = createCapabilityContext();
+				const step = createStep(runMetadata);
 				const capabilityContext: WorkflowContext<TConnections> = {
 					...baseContext,
 					connections: createWorkflowConnections(
@@ -193,7 +234,8 @@ export function workflow<
 						connectionDeclarations,
 					),
 					...runMetadata,
-					step: createStep(runMetadata),
+					step,
+					wait: createWait(step),
 				};
 				await configuration.handler(event, capabilityContext);
 
@@ -203,6 +245,18 @@ export function workflow<
 
 				writeOutput({ _tag: "success", value: { status: "success" } });
 			} catch (err) {
+				if (err instanceof WorkflowWaitInterrupt) {
+					if (options?.concreteOutput) {
+						return err.result;
+					}
+
+					writeOutput({
+						_tag: "wait",
+						wait: err.result.wait,
+					});
+					return;
+				}
+
 				const error = new ExecutionError(err);
 
 				if (!options?.concreteOutput) {
@@ -229,6 +283,13 @@ export type StepContext = {
 	 * Use this to make side effects idempotent when the workflow is retried.
 	 */
 	id: string;
+	/**
+	 * Durable key-value state shared by every run of this workflow.
+	 *
+	 * State is exposed on the step context because every operation participates
+	 * in the active step's durability and replay boundary.
+	 */
+	state: WorkflowState;
 };
 
 type WorkflowStepResult<T> = T extends void ? null : T;
@@ -252,6 +313,14 @@ type WorkflowStep = {
 	): Promise<WorkflowStepResult<T>>;
 };
 
+type WorkflowWait = {
+	/**
+	 * Suspend the workflow until a relative duration has elapsed or an absolute
+	 * date has been reached.
+	 */
+	until(name: string, options: WorkflowWaitUntilOptions): Promise<void>;
+};
+
 /** Context passed to a workflow handler. */
 export type WorkflowContext<
 	TConnections extends WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
@@ -279,6 +348,8 @@ export type WorkflowContext<
 		 * ```
 		 */
 		step: WorkflowStep;
+		/** Suspend this workflow without consuming compute resources. */
+		wait: WorkflowWait;
 	};
 
 type StepCompletionType = "success" | "failure";
@@ -314,7 +385,10 @@ function writeStepEvent(
 	);
 }
 
-function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowContext["step"] {
+function createStep(
+	metadata: Pick<RunMetadata, "runGroupId" | "workerId">,
+): WorkflowContext["step"] {
+	const { runGroupId } = metadata;
 	const stepNameByKey = new Map<string, string>();
 
 	async function step<T>(
@@ -338,7 +412,9 @@ function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowCo
 		}
 		stepNameByKey.set(key, name);
 
-		const context: StepContext = { id: `${runGroupId}:${key}` };
+		const id = `${runGroupId}:${key}`;
+		const stepState = createWorkflowStepState(metadata, id);
+		const context: StepContext = { id, state: stepState.state };
 		const event = { id: context.id, name, key };
 		const startedAt = performance.now();
 
@@ -367,7 +443,7 @@ function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowCo
 				return checkpoint.value as WorkflowStepResult<T>;
 			}
 
-			const value = normalizeWorkflowStepResult(await fn(context));
+			const value = normalizeWorkflowStepResult(await stepState.run(() => fn(context)));
 			writeStepEvent("success", { ...event, value }, startedAt);
 			writeStepEvent(
 				"completed",
@@ -407,6 +483,104 @@ function createStep({ runGroupId }: Pick<RunMetadata, "runGroupId">): WorkflowCo
 	return step;
 }
 
+class WorkflowWaitInterrupt extends Error {
+	constructor(readonly result: WorkflowWaitUntilResult) {
+		super(`Workflow is waiting until ${new Date(result.wait.resumeAtMs).toISOString()}`);
+		this.name = "WorkflowWaitInterrupt";
+	}
+}
+
+function createWait(step: WorkflowStep): WorkflowWait {
+	return {
+		async until(name, options) {
+			const keyInput = options.key ?? name;
+			const keySegments = [
+				"wait",
+				"until",
+				...(typeof keyInput === "string" ? [keyInput] : keyInput),
+			];
+			const resumeAtMs = await step(name, { key: keySegments }, () =>
+				resolveWaitUntilMs(options),
+			);
+
+			if (Date.now() >= resumeAtMs) {
+				return;
+			}
+
+			throw new WorkflowWaitInterrupt({
+				status: "waiting",
+				wait: {
+					type: "until",
+					name,
+					resumeAtMs,
+				},
+			});
+		},
+	};
+}
+
+function resolveWaitUntilMs(options: WorkflowWaitUntilOptions): number {
+	const now = Date.now();
+	if ("at" in options) {
+		const resumeAtMs = options.at.getTime();
+		if (!Number.isFinite(resumeAtMs)) {
+			throw new Error("Workflow wait date must be valid.");
+		}
+		assertWaitFitsCheckpointRetention(resumeAtMs - now);
+		return resumeAtMs;
+	}
+
+	const durationMs = workflowWaitDurationMs(options.after);
+	assertWaitFitsCheckpointRetention(durationMs);
+	return now + durationMs;
+}
+
+function workflowWaitDurationMs(duration: WorkflowWaitDuration): number {
+	const entries = Object.entries(duration);
+	if (entries.length === 0) {
+		throw new Error("Workflow wait duration must specify at least one unit.");
+	}
+
+	let durationMs = 0;
+	for (const [unit, value] of entries) {
+		if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+			throw new Error("Workflow wait duration values must be positive finite integers.");
+		}
+
+		durationMs += value * waitDurationUnitMultiplier(unit);
+		if (!Number.isSafeInteger(durationMs)) {
+			throw new Error("Workflow wait duration is too large.");
+		}
+	}
+
+	return durationMs;
+}
+
+function assertWaitFitsCheckpointRetention(durationMs: number): void {
+	if (durationMs >= MAX_WORKFLOW_WAIT_MS) {
+		throw new Error("Workflow waits must be shorter than 7 days.");
+	}
+}
+
+function waitDurationUnitMultiplier(unit: string): number {
+	switch (unit) {
+		case "milliseconds":
+			return 1;
+		case "seconds":
+			return 1_000;
+		case "minutes":
+			return 60_000;
+		case "hours":
+			return 3_600_000;
+		case "days":
+			return 86_400_000;
+		case "weeks":
+			return 604_800_000;
+		default:
+			throw new Error(`Unsupported workflow wait duration unit: ${unit}`);
+	}
+}
+
 function createWorkflowStepKey(segments: readonly unknown[]): string {
 	if (segments.length === 0) {
 		throw new Error("Workflow step keys must contain at least one segment.");