@temelj/workflow 0.0.0-alpha.2 → 0.0.0-alpha.4

package/dist/engine/lock.d.mts

@@ -1,21 +1,16 @@
 import { AcquireLockOptions, LockRecord, ReleaseLockOptions } from "../types/lock.mjs";
-import { WorkflowStepContext, WorkflowStepLockApi, WorkflowStepRunConfig } from "../types/step.mjs";
-import { WorkflowLockConditionalWriterRepository, WorkflowLockReaderRepository, WorkflowRunListerRepository, WorkflowRunUnconditionalWriterRepository, WorkflowStepAttemptLookup, WorkflowStoreNamespace } from "../types/store.mjs";
-import { WorkflowExecutionEnvironment } from "../types/engine.mjs";
+import { StepLockApi, StepRunConfig, WorkflowStepContext } from "../types/step.mjs";
+import { WorkflowStore } from "../types/store.mjs";
+import { ExecutionEnvironment } from "../types/engine.mjs";
 //#region src/engine/lock.d.ts
-type WorkflowLockCommandStore = WorkflowStoreNamespace & WorkflowLockReaderRepository & WorkflowLockConditionalWriterRepository;
-type WorkflowLockRunWakeStore = WorkflowRunListerRepository & WorkflowRunUnconditionalWriterRepository;
-type WorkflowLockStepAttemptWakeStore = WorkflowStepAttemptLookup;
-type WorkflowLockWakeStore = WorkflowLockRunWakeStore & WorkflowLockStepAttemptWakeStore;
-type WorkflowLockReleaseStore = WorkflowLockCommandStore & WorkflowLockWakeStore;
-interface WorkflowStepLockEngine {
+interface StepLockEngine {
   acquireLock(key: string, options: AcquireLockOptions): Promise<LockRecord>;
   releaseLock(key: string, options: ReleaseLockOptions): Promise<LockRecord>;
 }
-type WorkflowStepLockRunner = <TOutput>(config: WorkflowStepRunConfig, callback: (context: WorkflowStepContext) => Promise<TOutput> | TOutput) => Promise<TOutput>;
-declare function createWorkflowStepLockApi(environment: WorkflowExecutionEnvironment, engine: WorkflowStepLockEngine, run: WorkflowStepLockRunner): WorkflowStepLockApi;
-declare function acquireLock(store: WorkflowLockCommandStore, key: string, lockOptions: AcquireLockOptions, acquiredAt: Temporal.Instant): Promise<LockRecord>;
-declare function releaseLock(store: WorkflowLockReleaseStore, key: string, lockOptions: ReleaseLockOptions, releasedAt: Temporal.Instant): Promise<LockRecord>;
-declare function releaseStaleLock(store: WorkflowLockReleaseStore, key: string, releasedAt: Temporal.Instant): Promise<LockRecord>;
+type StepLockRunner = <TOutput>(config: StepRunConfig, callback: (context: WorkflowStepContext) => Promise<TOutput> | TOutput) => Promise<TOutput>;
+export declare function createStepLockApi(environment: ExecutionEnvironment, engine: StepLockEngine, run: StepLockRunner): StepLockApi;
+export declare function acquireLock(store: WorkflowStore, key: string, lockOptions: AcquireLockOptions, acquiredAt: Temporal.Instant): Promise<LockRecord>;
+export declare function releaseLock(store: WorkflowStore, key: string, lockOptions: ReleaseLockOptions, releasedAt: Temporal.Instant): Promise<LockRecord>;
+export declare function releaseStaleLock(store: WorkflowStore, key: string, releasedAt: Temporal.Instant): Promise<LockRecord>;
 //#endregion
-export { WorkflowStepLockEngine, acquireLock, createWorkflowStepLockApi, releaseLock, releaseStaleLock };
+export {};

package/dist/engine/lock.mjs

@@ -1,13 +1,16 @@
+import { WorkflowErrorCode } from "../errors/codes.mjs";
 import { WorkflowOptionsError } from "../errors/base.mjs";
 import { WorkflowNonRetryableError, WorkflowRetryableError } from "../errors/failures.mjs";
-import { isPositiveSafeInteger, positiveSafeInteger } from "../utility.mjs";
 import { WorkflowLockError, WorkflowLockStateError } from "../errors/lock.mjs";
+import { matchesWorkflowError } from "../errors/records.mjs";
 import "../errors/mod.mjs";
-import { WorkflowSuspended, patchRun } from "./state.mjs";
-import { recordWorkflowDeterministicValue } from "./deterministic.mjs";
-import { requireLockReleaseReplayMatches, requireLockReplayMatches, requireLockWaitDeadlineReplayMatches, requireLockWaitReplayMatches } from "./lock-replay.mjs";
+import { isPositiveSafeInteger, positiveSafeInteger } from "../values.mjs";
+import { Suspended } from "./signals.mjs";
+import { patchRun } from "./state.mjs";
+import { recordDeterministicValue } from "./deterministic.mjs";
+import { parseLockWaitDeadlineReplay, requireLockReleaseReplayMatches, requireLockReplayMatches, requireLockWaitReplayMatches } from "./lock-replay.mjs";
 //#region src/engine/lock.ts
-function createWorkflowStepLockApi(environment, engine, run) {
+function createStepLockApi(environment, engine, run) {
 	const { runId, history } = environment;
 	const acquire = async (commandId, key, options) => {
 		const requestedLeaseDuration = positiveSafeInteger(options.leaseDuration.total({ unit: "millisecond" }), "Workflow lock lease duration");
@@ -17,13 +20,14 @@ function createWorkflowStepLockApi(environment, engine, run) {
 			commandId,
 			retry: { maximumAttempts: options.wait === true ? 0 : 1 }
 		}, async (context) => {
-			return await engine.acquireLock(key, {
+			const acquireOptions = {
 				...engineLockOptions,
 				holderId: options.holderId ?? runId,
 				holderRunId: runId,
 				holderStepId: context.step.id,
-				...waitDeadlineAt === void 0 ? {} : { waitDeadlineAt }
-			});
+				waitDeadlineAt
+			};
+			return await engine.acquireLock(key, acquireOptions);
 		});
 		requireLockReplayMatches(lock, {
 			key,
@@ -43,10 +47,11 @@ function createWorkflowStepLockApi(environment, engine, run) {
 			commandId,
 			retry: { maximumAttempts: 1 }
 		}, async () => {
-			return await engine.releaseLock(key, {
+			const releaseOptions = {
 				holderId,
-				...options?.now === void 0 ? {} : { now: options.now }
-			});
+				now: options?.now
+			};
+			return await engine.releaseLock(key, releaseOptions);
 		});
 		requireLockReleaseReplayMatches(lock, {
 			key,
@@ -61,17 +66,19 @@ function createWorkflowStepLockApi(environment, engine, run) {
 			const lock = await acquire(`${commandId}:acquire`, key, options);
 			try {
 				const output = await callback(lock);
-				await release(`${commandId}:release`, key, {
-					...options.holderId === void 0 ? {} : { holderId: options.holderId },
-					...options.now === void 0 ? {} : { now: options.now }
-				});
+				const releaseOptions = {
+					holderId: options.holderId,
+					now: options.now
+				};
+				await release(`${commandId}:release`, key, releaseOptions);
 				return output;
 			} catch (error) {
-				if (error instanceof WorkflowSuspended) throw error;
-				await release(`${commandId}:release`, key, {
-					...options.holderId === void 0 ? {} : { holderId: options.holderId },
-					...options.now === void 0 ? {} : { now: options.now }
-				});
+				if (error instanceof Suspended) throw error;
+				const releaseOptions = {
+					holderId: options.holderId,
+					now: options.now
+				};
+				await release(`${commandId}:release`, key, releaseOptions);
 				throw error;
 			}
 		}
@@ -84,70 +91,75 @@ async function acquireLock(store, key, lockOptions, acquiredAt) {
 	const existing = await store.getLock(key);
 	if (existing !== void 0 && !(existing.holderId === holderId || existing.releasedAt !== void 0) && Temporal.Instant.compare(existing.leaseExpiresAt, acquiredAt) > 0) {
 		if (lockOptions.wait === true) {
-			if (waitDeadlineAt !== void 0 && Temporal.Instant.compare(waitDeadlineAt, acquiredAt) <= 0) WorkflowNonRetryableError.failed(`Workflow lock wait timed out: ${key}`, { details: {
+			if (waitDeadlineAt !== void 0 && Temporal.Instant.compare(waitDeadlineAt, acquiredAt) <= 0) throw new WorkflowNonRetryableError(`Workflow lock wait timed out: ${key}`, { details: {
 				key,
 				holderId,
 				currentHolderId: existing.holderId,
 				waitDeadlineAt: waitDeadlineAt.toString()
 			} });
 			const retryAt = workflowLockRetryAt(existing, acquiredAt, waitDeadlineAt);
-			throw WorkflowRetryableError.lockAlreadyHeld(key, {
+			const details = {
+				key,
+				holderId,
+				currentHolderId: existing.holderId,
+				waitDeadlineAt: waitDeadlineAt !== void 0 ? waitDeadlineAt.toString() : void 0
+			};
+			throw new WorkflowRetryableError(`Workflow lock is already held: ${key}`, {
 				retryAt,
+				code: WorkflowErrorCode.LOCK_ALREADY_HELD,
 				details: {
-					key,
-					holderId,
-					currentHolderId: existing.holderId,
-					...waitDeadlineAt === void 0 ? {} : { waitDeadlineAt: waitDeadlineAt.toString() }
+					...details,
+					key
 				}
 			});
 		}
-		WorkflowLockError.alreadyHeld(key);
+		throw new WorkflowLockError(`Workflow lock is already held: ${key}`, WorkflowErrorCode.LOCK_ALREADY_HELD_WITHOUT_WAIT, { key });
 	}
 	const lock = {
 		key,
 		namespace: store.namespace,
 		holderId,
-		...lockOptions.holderRunId === void 0 ? {} : { holderRunId: lockOptions.holderRunId },
-		...lockOptions.holderStepId === void 0 ? {} : { holderStepId: lockOptions.holderStepId },
+		holderRunId: lockOptions.holderRunId,
+		holderStepId: lockOptions.holderStepId,
 		fencingToken: (existing?.fencingToken ?? 0) + 1,
 		acquiredAt,
 		leaseExpiresAt: acquiredAt.add(Temporal.Duration.from({ milliseconds: leaseDuration }))
 	};
 	const acquired = await store.updateLockIfCurrent(existing, lock);
-	if (acquired === void 0) WorkflowLockStateError.acquireConflictExhausted(key);
+	if (acquired === void 0) throw new WorkflowLockStateError(`Failed to acquire workflow lock ${key}`, WorkflowErrorCode.LOCK_ACQUIRE_CONFLICT_EXHAUSTED, { key });
 	return acquired;
 }
 async function releaseLock(store, key, lockOptions, releasedAt) {
 	const holderId = lockOptions.holderId;
 	const current = await store.getLock(key);
 	if (current === void 0) WorkflowLockStateError.notFound(key);
-	if (current.holderId !== holderId) WorkflowLockError.holderMismatch(key);
+	if (current.holderId !== holderId) throw new WorkflowLockError(`Workflow lock holder mismatch: ${key}`, WorkflowErrorCode.LOCK_HOLDER_MISMATCH, { key });
 	const released = {
 		...current,
 		releasedAt
 	};
 	const updated = await store.updateLockIfCurrent(current, released);
-	if (updated === void 0) WorkflowLockStateError.releaseConflictExhausted(key);
-	await wakeWorkflowRunsWaitingForLock(store, key, releasedAt);
+	if (updated === void 0) throw new WorkflowLockStateError(`Failed to release workflow lock ${key}`, WorkflowErrorCode.LOCK_RELEASE_CONFLICT_EXHAUSTED, { key });
+	await wakeRunsWaitingForLock(store, key, releasedAt);
 	return updated;
 }
 async function releaseStaleLock(store, key, releasedAt) {
 	const current = await store.getLock(key);
 	if (current === void 0) WorkflowLockStateError.notFound(key);
-	if (current.releasedAt !== void 0) WorkflowLockError.alreadyReleased(key);
-	if (Temporal.Instant.compare(current.leaseExpiresAt, releasedAt) > 0) WorkflowLockError.notStale(key);
+	if (current.releasedAt !== void 0) throw new WorkflowLockError(`Workflow lock is already released: ${key}`, WorkflowErrorCode.LOCK_ALREADY_RELEASED, { key });
+	if (Temporal.Instant.compare(current.leaseExpiresAt, releasedAt) > 0) throw new WorkflowLockError(`Workflow lock is not stale: ${key}`, WorkflowErrorCode.LOCK_NOT_STALE, { key });
 	const released = {
 		...current,
 		releasedAt
 	};
 	const updated = await store.updateLockIfCurrent(current, released);
-	if (updated === void 0) WorkflowLockStateError.staleReleaseConflictExhausted(key);
-	await wakeWorkflowRunsWaitingForLock(store, key, releasedAt);
+	if (updated === void 0) throw new WorkflowLockStateError(`Failed to release stale workflow lock ${key}`, WorkflowErrorCode.LOCK_STALE_RELEASE_CONFLICT_EXHAUSTED, { key });
+	await wakeRunsWaitingForLock(store, key, releasedAt);
 	return updated;
 }
 function resolveLockWaitDeadline(options, now) {
-	if (options.waitTimeout !== void 0 && options.waitDeadlineAt !== void 0) WorkflowLockError.waitDeadlineConflict();
-	if ((options.waitTimeout !== void 0 || options.waitDeadlineAt !== void 0) && options.wait !== true) WorkflowLockError.timeoutRequiresWait();
+	if (options.waitTimeout !== void 0 && options.waitDeadlineAt !== void 0) throw new WorkflowLockError("Workflow lock options cannot include both waitTimeout and waitDeadlineAt", WorkflowErrorCode.LOCK_WAIT_DEADLINE_CONFLICT, void 0);
+	if ((options.waitTimeout !== void 0 || options.waitDeadlineAt !== void 0) && options.wait !== true) throw new WorkflowLockError("Workflow lock timeout options require wait: true", WorkflowErrorCode.LOCK_TIMEOUT_REQUIRES_WAIT, void 0);
 	if (options.waitDeadlineAt !== void 0) return options.waitDeadlineAt;
 	if (options.waitTimeout === void 0) return;
 	positiveDurationMilliseconds(options.waitTimeout, "Workflow lock waitTimeout");
@@ -155,38 +167,40 @@ function resolveLockWaitDeadline(options, now) {
 }
 function positiveDurationMilliseconds(duration, label) {
 	const milliseconds = duration.total({ unit: "millisecond" });
-	if (!isPositiveSafeInteger(milliseconds)) WorkflowOptionsError.positiveSafeIntegerDuration(label);
+	if (!isPositiveSafeInteger(milliseconds)) throw new WorkflowOptionsError(`${label} must be a positive safe integer duration`, {
+		code: WorkflowErrorCode.OPTIONS_EXPECTED_POSITIVE_SAFE_INTEGER_DURATION,
+		details: { label }
+	});
 	return milliseconds;
 }
 async function recordLockWaitDeadline(environment, name, timeout) {
 	const resolvedTimeout = positiveSafeInteger(timeout.total({ unit: "millisecond" }), "Workflow lock waitTimeout");
-	return await recordWorkflowDeterministicValue(environment, `${name}:wait-deadline`, () => environment.now().add(Temporal.Duration.from({ milliseconds: resolvedTimeout })), (recorded) => requireLockWaitDeadlineReplayMatches(recorded, resolvedTimeout));
+	return await recordDeterministicValue(environment, `${name}:wait-deadline`, () => environment.now().add(Temporal.Duration.from({ milliseconds: resolvedTimeout })), (recorded) => parseLockWaitDeadlineReplay(recorded, resolvedTimeout));
 }
 function workflowLockRetryAt(lock, now, waitDeadlineAt) {
 	const retryAt = Temporal.Instant.compare(lock.leaseExpiresAt, now) <= 0 ? now : lock.leaseExpiresAt;
 	if (waitDeadlineAt !== void 0 && Temporal.Instant.compare(waitDeadlineAt, retryAt) < 0) return waitDeadlineAt;
 	return retryAt;
 }
-async function wakeWorkflowRunsWaitingForLock(store, key, timestamp) {
-	const wakeAt = timestamp;
+async function wakeRunsWaitingForLock(store, key, timestamp) {
 	const waitingRuns = await store.listRuns({
 		status: "waiting",
 		retryReason: "step"
 	});
 	await Promise.all(waitingRuns.map(async (run) => {
-		if (run.availableAt !== void 0 && Temporal.Instant.compare(run.availableAt, wakeAt) <= 0) return;
+		if (run.availableAt !== void 0 && Temporal.Instant.compare(run.availableAt, timestamp) <= 0) return;
 		if (!(await store.listStepAttempts(run.id, {
 			kind: "run",
 			status: "failed"
-		})).some((attempt) => WorkflowRetryableError.isLockAlreadyHeld(attempt.error, key))) return;
+		})).some((attempt) => matchesWorkflowError(attempt.error, WorkflowErrorCode.LOCK_ALREADY_HELD, { key }))) return;
 		await patchRun(store, run, {
-			availableAt: wakeAt,
-			retryAt: wakeAt,
-			updatedAt: wakeAt,
-			lastTransitionAt: wakeAt,
+			availableAt: timestamp,
+			retryAt: timestamp,
+			updatedAt: timestamp,
+			lastTransitionAt: timestamp,
 			lastTransitionReason: "retry",
 			deadlineAt: run.deadlineAt,
-			startedAt: run.startedAt ?? wakeAt,
+			startedAt: run.startedAt ?? timestamp,
 			error: run.error,
 			output: void 0,
 			finishedAt: void 0
@@ -194,4 +208,4 @@ async function wakeWorkflowRunsWaitingForLock(store, key, timestamp) {
 	}));
 }
 //#endregion
-export { acquireLock, createWorkflowStepLockApi, releaseLock, releaseStaleLock };
+export { acquireLock, createStepLockApi, releaseLock, releaseStaleLock };

package/dist/engine/message.d.mts

@@ -1,47 +1,27 @@
-import { RunId } from "../types/run-id.mjs";
+import { RunId } from "../types/ids.mjs";
 import { BroadcastMessageChannelOptions, BroadcastMessageInput, BroadcastMessageResult, MessageChannel, SendMessageChannelOptions, SendMessageInput, SendMessageOptions, WaitForMessageOptions } from "../types/message.mjs";
-import { WorkflowStepMessageApi } from "../types/step.mjs";
+import { StepMessageApi } from "../types/step.mjs";
 import { Telemetry, TelemetryContext } from "../types/telemetry.mjs";
-import { WorkflowStepIdentity } from "../types/run.mjs";
 import { EventRecord } from "../types/events.mjs";
-import "../history/mod.mjs";
-import { WorkflowConditionalEventAppender, WorkflowEventReader, WorkflowMessageIdempotencyIndexLookup, WorkflowRunConditionalWriterRepository, WorkflowRunListerRepository, WorkflowRunReaderRepository } from "../types/store.mjs";
-import { WorkflowExecutionLimits } from "../types/engine-options.mjs";
-import { WorkflowExecutionEnvironment } from "../types/engine.mjs";
+import { WorkflowStore } from "../types/store.mjs";
+import { ExecutionLimits } from "../types/engine-options.mjs";
+import { EngineContext } from "./context.mjs";
+import { ExecutionEnvironment } from "../types/engine.mjs";
 import { Schema } from "@temelj/standard-schema";
+import { StorageValue } from "@temelj/storage";
 //#region src/engine/message.d.ts
 type MessageWaitSource = Extract<EventRecord, {
   readonly kind: "message_wait_started";
 }>["source"];
-type WorkflowMessageWaitOptions = WaitForMessageOptions<Schema | undefined> & {
+type MessageWaitOptions<TPayload = StorageValue | undefined> = WaitForMessageOptions<Schema<unknown, TPayload> | undefined> & {
   readonly source?: MessageWaitSource;
 };
-type WorkflowMessageDeliveryStore = WorkflowMessageIdempotencyIndexLookup & WorkflowRunReaderRepository & WorkflowEventReader & WorkflowConditionalEventAppender & WorkflowRunConditionalWriterRepository;
-type WorkflowMessageStore = WorkflowMessageDeliveryStore & WorkflowRunListerRepository;
-interface WorkflowMessageServiceOptions {
-  readonly store: WorkflowMessageStore;
-  readonly now: () => Temporal.Instant;
-  readonly limits: WorkflowExecutionLimits;
-  readonly observeMessageSent?: (runId: RunId, event: Extract<EventRecord, {
-    readonly kind: "message_sent";
-  }>) => void;
-  readonly telemetry?: Telemetry;
-}
-declare function createWorkflowStepMessageApi(environment: WorkflowExecutionEnvironment): WorkflowStepMessageApi;
-declare function sendWorkflowMessageInput<TPayload, TKey = void>(service: WorkflowMessageServiceOptions, runId: RunId, messageInput: SendMessageInput | MessageChannel<TPayload, TKey>, channelOptions: SendMessageChannelOptions<TPayload, TKey> | undefined): Promise<void>;
-declare function broadcastWorkflowMessageInput<TPayload, TKey = void>(service: WorkflowMessageServiceOptions, messageInput: BroadcastMessageInput | MessageChannel<TPayload, TKey>, channelOptions: BroadcastMessageChannelOptions<TPayload, TKey> | undefined): Promise<BroadcastMessageResult>;
-declare function sendWorkflowMessage(store: WorkflowMessageDeliveryStore, runId: RunId, options: SendMessageOptions, now: () => Temporal.Instant, limits: WorkflowExecutionLimits, observeMessageSent?: (runId: RunId, event: Extract<EventRecord, {
+export declare function createStepMessageApi(environment: ExecutionEnvironment): StepMessageApi;
+export declare function sendMessageInput<TPayload, TRawPayload = TPayload>(context: EngineContext, runId: RunId, messageInput: SendMessageInput | MessageChannel<TPayload, TRawPayload>, channelOptions: SendMessageChannelOptions<TRawPayload> | undefined): Promise<void>;
+export declare function broadcastMessageInput<TPayload, TRawPayload = TPayload>(context: EngineContext, messageInput: BroadcastMessageInput | MessageChannel<TPayload, TRawPayload>, channelOptions: BroadcastMessageChannelOptions<TRawPayload> | undefined): Promise<BroadcastMessageResult>;
+export declare function sendWorkflowMessage(store: WorkflowStore, runId: RunId, options: SendMessageOptions, now: () => Temporal.Instant, limits: ExecutionLimits, observeMessageSent?: (runId: RunId, event: Extract<EventRecord, {
   readonly kind: "message_sent";
 }>) => void, telemetry?: Telemetry, traceContext?: TelemetryContext): Promise<void>;
-declare function waitForWorkflowMessage(environment: WorkflowExecutionEnvironment, options: WorkflowMessageWaitOptions): Promise<unknown>;
-declare function requireMessageWaitReplayMatches(identity: WorkflowStepIdentity, started: Extract<EventRecord, {
-  readonly kind: "message_wait_started";
-}> | undefined, event: Extract<EventRecord, {
-  readonly kind: "message_wait_started" | "message_wait_completed" | "message_wait_failed";
-}>, options: WorkflowMessageWaitOptions): void;
-declare function messageWaitAvailableAt(now: () => Temporal.Instant, timeoutAt: Temporal.Instant | undefined, deadlineAt: Temporal.Instant | undefined): Temporal.Instant;
-declare function wakeRunForMessageEvent(store: WorkflowRunReaderRepository & WorkflowEventReader & WorkflowRunConditionalWriterRepository, runId: RunId, messageEvent: Extract<EventRecord, {
-  readonly kind: "message_sent";
-}>): Promise<void>;
+export declare function waitForMessage<TPayload = never>(environment: ExecutionEnvironment, options: MessageWaitOptions<TPayload>): Promise<TPayload | StorageValue | undefined>;
 //#endregion
-export { broadcastWorkflowMessageInput, createWorkflowStepMessageApi, messageWaitAvailableAt, requireMessageWaitReplayMatches, sendWorkflowMessage, sendWorkflowMessageInput, waitForWorkflowMessage, wakeRunForMessageEvent };
+export {};