@temelj/workflow 0.0.0-alpha.1

package/dist/engine/serialization.mjs

@@ -0,0 +1,85 @@
+import { WorkflowError } from "../errors/base.mjs";
+import { WorkflowSerializationError } from "../errors/failures.mjs";
+import { sanitizedWorkflowErrorDetails } from "../types/error.mjs";
+import { persistedValueIssue } from "../types/run.mjs";
+import { WorkflowStepExecutionError } from "../errors/step.mjs";
+import "../errors/mod.mjs";
+import { createSuperJsonStorageCodec } from "@temelj/storage";
+//#region src/engine/serialization.ts
+const PERSISTED_VALUE_CODEC = createSuperJsonStorageCodec({ format: "bytes" });
+function serializeError(error) {
+	if (error instanceof Error) {
+		const name = typeof error.name === "string" && error.name.trim() !== "" ? error.name : "Error";
+		const message = typeof error.message === "string" && error.message.trim() !== "" ? error.message : name;
+		const stack = typeof error.stack === "string" && error.stack.trim() !== "" ? error.stack : void 0;
+		return {
+			...error instanceof WorkflowError ? { code: error.code } : {},
+			name,
+			message,
+			...stack === void 0 ? {} : { stack },
+			...workflowErrorDetails(error)
+		};
+	}
+	return {
+		name: "Error",
+		message: String(error).trim() === "" ? "Error" : String(error)
+	};
+}
+function workflowErrorDetails(error) {
+	if (error instanceof WorkflowStepExecutionError) return { details: {
+		...sanitizedWorkflowErrorDetails(error.details),
+		...workflowErrorCauseDetails(error.cause)
+	} };
+	if (error instanceof WorkflowError && error.details !== void 0) {
+		const details = sanitizedWorkflowErrorDetails(error.details);
+		return details === void 0 ? {} : { details };
+	}
+	return {};
+}
+function workflowErrorCauseDetails(cause) {
+	if (!(cause instanceof Error)) return {};
+	const record = serializeError(cause);
+	return prefixWorkflowErrorCauseDetails({
+		...causeDetailsWithoutReservedIdentity(record.details),
+		...record.code === void 0 ? {} : { code: record.code },
+		name: record.name,
+		message: record.message,
+		...record.stack === void 0 ? {} : { stack: record.stack }
+	});
+}
+function causeDetailsWithoutReservedIdentity(details) {
+	if (details === void 0) return {};
+	return Object.fromEntries(Object.entries(details).filter(([key]) => {
+		const prefixedKey = key.startsWith("cause") ? key : `cause${key[0]?.toUpperCase() ?? ""}${key.slice(1)}`;
+		return prefixedKey !== "causeName" && prefixedKey !== "causeMessage" && prefixedKey !== "causeStack";
+	}));
+}
+function prefixWorkflowErrorCauseDetails(details) {
+	return Object.fromEntries(Object.entries(details).map(([key, value]) => [key.startsWith("cause") ? key : `cause${key[0]?.toUpperCase() ?? ""}${key.slice(1)}`, value]));
+}
+function toPersistedValue(value, path, limits) {
+	const issue = persistedValueIssue(value, path, /* @__PURE__ */ new WeakSet(), false);
+	if (issue !== void 0) WorkflowSerializationError.notSerializable(issue.path, issue.message);
+	enforceStorageValueSize(value, path, limits);
+	return value;
+}
+function toOptionalPersistedValue(value, path, limits) {
+	if (value === void 0) return;
+	return toPersistedValue(value, path, limits);
+}
+function enforceStorageValueSize(value, path, limits) {
+	if (limits?.maximumPersistedValueBytes === void 0) return;
+	if (value === void 0) return;
+	const bytes = persistedValueByteLength(value, path);
+	if (bytes > limits.maximumPersistedValueBytes) WorkflowSerializationError.notSerializable(path, `serialized size ${bytes} bytes exceeds maximumPersistedValueBytes ${limits.maximumPersistedValueBytes}`);
+}
+function persistedValueByteLength(value, path) {
+	try {
+		return PERSISTED_VALUE_CODEC.encode(value).byteLength;
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		WorkflowSerializationError.notSerializable(path, reason);
+	}
+}
+//#endregion
+export { serializeError, toOptionalPersistedValue, toPersistedValue };

package/dist/engine/start-api.d.mts

@@ -0,0 +1,30 @@
+import { WorkflowStartTarget } from "../types/definition.mjs";
+import { HandleOperations, WorkflowHandle } from "../types/result.mjs";
+import { Telemetry } from "../types/telemetry.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { ResolvedScheduleNextOptions, ScheduleNextOptions, WorkflowBatchStartItem, WorkflowStartOptions } from "../types/run-options.mjs";
+import { WorkflowEventReader, WorkflowIdempotencyIndex, WorkflowRunCreationRepository, WorkflowRunReaderRepository, WorkflowStoreNamespace } from "../types/store.mjs";
+import { WorkflowExecutionLimits } from "../types/engine-options.mjs";
+import { WorkflowRunStarter } from "../types/engine.mjs";
+//#region src/engine/start-api.d.ts
+interface WorkflowEngineStartApi {
+  startWorkflow<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, input: TRawInput, options?: WorkflowStartOptions): Promise<WorkflowHandle<TOutput>>;
+  startWorkflows<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, items: readonly WorkflowBatchStartItem<TRawInput>[]): Promise<readonly WorkflowHandle<TOutput>[]>;
+  scheduleNextWorkflow<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, input: TRawInput, options: ScheduleNextOptions): Promise<WorkflowHandle<TOutput>>;
+}
+/** Resolves schedule-next options and derives the start time for the next run. */
+declare function resolveScheduleNextOptions(options: ScheduleNextOptions, now: () => Temporal.Instant): ResolvedScheduleNextOptions;
+type WorkflowEngineStartStore = WorkflowStoreNamespace & WorkflowRunCreationRepository & WorkflowRunReaderRepository & WorkflowIdempotencyIndex & WorkflowEventReader;
+interface WorkflowEngineStartApiOptions {
+  readonly store: WorkflowEngineStartStore;
+  readonly now: () => Temporal.Instant;
+  readonly limits: WorkflowExecutionLimits;
+  readonly createRunId: () => string;
+  readonly telemetry?: Telemetry;
+  readonly emitRunEvent: (run: WorkflowRunRecord) => void;
+  readonly starter: WorkflowRunStarter;
+  readonly handleOperations: HandleOperations;
+}
+declare function createWorkflowEngineStartApi(service: WorkflowEngineStartApiOptions): WorkflowEngineStartApi;
+//#endregion
+export { WorkflowEngineStartApi, createWorkflowEngineStartApi, resolveScheduleNextOptions };

package/dist/engine/start-api.mjs

@@ -0,0 +1,98 @@
+import { defineWorkflowFromTarget, parseWorkflowInput } from "../definition.mjs";
+import { captureTelemetryContext } from "../telemetry.mjs";
+import { toOptionalPersistedValue, toPersistedValue } from "./serialization.mjs";
+import { workflowHandle } from "./run-utils.mjs";
+import { resolveWorkflowStartSpec } from "./run-service.mjs";
+//#region src/engine/start-api.ts
+/** Resolves schedule-next options and derives the start time for the next run. */
+function resolveScheduleNextOptions(options, now) {
+	const from = options.from ?? now();
+	const start = {
+		...options.id === void 0 ? {} : { id: options.id },
+		idempotencyKey: options.idempotencyKey,
+		...options.workflowVersion === void 0 ? {} : { workflowVersion: options.workflowVersion },
+		...options.workflowVersionResolver === void 0 ? {} : { workflowVersionResolver: options.workflowVersionResolver },
+		...options.context === void 0 ? {} : { context: options.context },
+		...options.parent === void 0 ? {} : { parent: options.parent },
+		availableAt: from.toZonedDateTimeISO("UTC").add(options.every).toInstant(),
+		...options.deadlineAt === void 0 ? {} : { deadlineAt: options.deadlineAt }
+	};
+	return {
+		schedule: {
+			...options,
+			from
+		},
+		start
+	};
+}
+function createWorkflowEngineStartApi(service) {
+	return {
+		async startWorkflow(workflow, input, startOptions) {
+			const resolvedDefinition = await resolveWorkflowStartSpec(defineWorkflowFromTarget(workflow), startOptions);
+			const parsedInput = await parseWorkflowInput(resolvedDefinition, input);
+			const idempotencyKey = startOptions?.idempotencyKey;
+			const explicitRunId = startOptions?.id;
+			const existingRun = idempotencyKey === void 0 ? void 0 : await service.store.getRunByIdempotencyKey({
+				workflowName: resolvedDefinition.name,
+				...resolvedDefinition.version === void 0 ? {} : { workflowVersion: resolvedDefinition.version },
+				idempotencyKey
+			});
+			if (existingRun !== void 0) return workflowStartHandle(service, resolvedDefinition, existingRun.id);
+			const runId = explicitRunId ?? service.createRunId();
+			const timestamp = service.now();
+			const availableAt = startOptions?.availableAt;
+			const deadlineAt = startOptions?.deadlineAt;
+			const parent = startOptions?.parent === void 0 ? void 0 : startOptions.parent;
+			const persistedInput = toOptionalPersistedValue(parsedInput, "workflow input", service.limits);
+			const run = {
+				id: runId,
+				namespace: service.store.namespace,
+				workflowName: resolvedDefinition.name,
+				...resolvedDefinition.version === void 0 ? {} : { workflowVersion: resolvedDefinition.version },
+				status: "pending",
+				...persistedInput === void 0 ? {} : { input: persistedInput },
+				...startOptions?.context === void 0 ? {} : { context: toPersistedValue(startOptions.context, "workflow context", service.limits) },
+				...(() => {
+					const telemetryContext = captureTelemetryContext(service.telemetry);
+					return telemetryContext === void 0 ? {} : { telemetryContext };
+				})(),
+				attempts: 0,
+				...idempotencyKey === void 0 ? {} : { idempotencyKey },
+				...parent === void 0 ? {} : {
+					parentRunId: parent.runId,
+					...parent.stepId === void 0 ? {} : { parentStepId: parent.stepId },
+					...parent.stepName === void 0 ? {} : { parentStepName: parent.stepName },
+					...parent.stepAttempt === void 0 ? {} : { parentStepAttempt: parent.stepAttempt }
+				},
+				createdAt: timestamp,
+				updatedAt: timestamp,
+				lastTransitionAt: timestamp,
+				lastTransitionReason: "created",
+				...availableAt === void 0 ? {} : { availableAt },
+				...deadlineAt === void 0 ? {} : { deadlineAt }
+			};
+			const createdRun = await service.store.createRun(run);
+			service.emitRunEvent(createdRun);
+			return workflowStartHandle(service, resolvedDefinition, createdRun.id);
+		},
+		async startWorkflows(workflow, items) {
+			const handles = [];
+			for (const item of items) handles.push(await service.starter.startWorkflow(workflow, item.input, item.options));
+			return handles;
+		},
+		async scheduleNextWorkflow(workflow, input, scheduleOptions) {
+			const options = resolveScheduleNextOptions(scheduleOptions, service.now).start;
+			return await service.starter.startWorkflow(workflow, input, options);
+		}
+	};
+}
+function workflowStartHandle(service, definition, runId) {
+	return workflowHandle(service.store, definition, runId, service.now, {
+		getTimeline: async (currentRunId) => await service.handleOperations.getTimeline(currentRunId),
+		setMetadata: async (currentRunId, metadata) => await service.handleOperations.setMetadata(currentRunId, metadata),
+		setAttributes: async (currentRunId, attributes) => await service.handleOperations.setAttributes(currentRunId, attributes),
+		cancel: async (currentRunId) => await service.handleOperations.cancel(currentRunId)
+	});
+}
+//#endregion
+export { createWorkflowEngineStartApi, resolveScheduleNextOptions };

package/dist/engine/state.d.mts

@@ -0,0 +1,77 @@
+import { RunId } from "../types/run-id.mjs";
+import { WorkflowDefinition } from "../types/definition.mjs";
+import { WorkflowStepAttemptRecord } from "../types/step-attempts.mjs";
+import { ExecutionResult } from "../types/result.mjs";
+import { WorkflowAttributePatch, WorkflowRunRecord, WorkflowRunRetryReason, WorkflowStepIdentity } from "../types/run.mjs";
+import { WorkflowErrorRecord } from "../types/error.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowHistory } from "../history/mod.mjs";
+import { WorkflowConditionalEventAppender, WorkflowEventReader, WorkflowLockConditionalWriterRepository, WorkflowLockListerRepository, WorkflowRunConditionalWriterRepository, WorkflowRunReaderRepository, WorkflowRunUnconditionalWriterRepository, WorkflowRunWriterRepository, WorkflowStepAttemptLookup } from "../types/store.mjs";
+import { getRequiredRun } from "../utility.mjs";
+import { StorageValue } from "@temelj/storage";
+//#region src/engine/state.d.ts
+interface WorkflowEngineStateLimits {
+  readonly maximumEventHistoryEvents?: number;
+}
+type WorkflowRunLookup = WorkflowRunReaderRepository;
+type WorkflowRunWriter = WorkflowRunUnconditionalWriterRepository;
+type WorkflowRunConditionalWriter = WorkflowRunConditionalWriterRepository;
+type WorkflowRunStateStore = WorkflowRunLookup & WorkflowRunWriter & WorkflowRunWriterRepository;
+type WorkflowCurrentEventAppender = WorkflowConditionalEventAppender;
+type WorkflowLockReleaseStore = WorkflowLockListerRepository & WorkflowLockConditionalWriterRepository;
+type WorkflowChildWakeStore = WorkflowRunStateStore & WorkflowEventReader & WorkflowStepAttemptLookup;
+type WorkflowChildCascadeStore = WorkflowChildWakeStore & WorkflowLockReleaseStore;
+type WorkflowChildRunStateStore = WorkflowChildCascadeStore & WorkflowCurrentEventAppender;
+declare function requireDefinitionMatchesRun<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, run: WorkflowRunRecord): void;
+declare function appendEventIfCurrentExecution(store: WorkflowCurrentEventAppender, history: WorkflowHistory, event: EventRecord, executionOwner: WorkflowRunRecord, limits: WorkflowEngineStateLimits, beforeAppend?: () => void, afterAppend?: (event: EventRecord, events: readonly EventRecord[]) => void): Promise<void>;
+declare function requireCurrentExecutionOwner(store: WorkflowRunLookup, runId: RunId, executionOwner: WorkflowRunRecord): Promise<void>;
+declare function patchRun(store: WorkflowRunWriter, current: WorkflowRunRecord, patch: Partial<WorkflowRunRecord>): Promise<WorkflowRunRecord>;
+declare function patchRunIfCurrent(store: WorkflowRunConditionalWriter, current: WorkflowRunRecord, patch: Partial<WorkflowRunRecord>): Promise<WorkflowRunRecord | undefined>;
+declare function updateRunMetadataIfCurrent(store: WorkflowRunLookup & WorkflowRunConditionalWriter, runId: RunId, metadata: StorageValue, timestamp: Temporal.Instant): Promise<WorkflowRunRecord>;
+declare function setRunAttributesIfCurrent(store: WorkflowRunLookup & WorkflowRunConditionalWriter, runId: RunId, attributes: WorkflowAttributePatch, timestamp: Temporal.Instant): Promise<WorkflowRunRecord>;
+declare function patchCurrentExecutionRun(store: WorkflowRunLookup & WorkflowRunConditionalWriter, executionOwner: WorkflowRunRecord, patch: Partial<WorkflowRunRecord>): Promise<WorkflowRunRecord | undefined>;
+declare function patchCurrentExecutionRunAttributes(store: WorkflowRunLookup & WorkflowRunConditionalWriter, executionOwner: WorkflowRunRecord, attributes: WorkflowAttributePatch, timestamp: Temporal.Instant): Promise<WorkflowRunRecord | undefined>;
+declare function transitionRunToMissingImplementationWait(run: WorkflowRunRecord, error: WorkflowErrorRecord, timestamp: Temporal.Instant, availableAt: Temporal.Instant, retryAttempt: number): WorkflowRunRecord;
+declare function transitionRunToFailed(run: WorkflowRunRecord, error: WorkflowErrorRecord, timestamp: Temporal.Instant, lastTransitionReason: "deadline" | "failed", deadlineAt?: Temporal.Instant): WorkflowRunRecord;
+declare function transitionRunToRunning(run: WorkflowRunRecord, timestamp: Temporal.Instant, attempts: number | undefined): WorkflowRunRecord;
+declare function transitionRunToCompleted(run: WorkflowRunRecord, output: StorageValue | undefined, timestamp: Temporal.Instant): WorkflowRunRecord;
+declare function transitionRunToExecutionWait(run: WorkflowRunRecord, timestamp: Temporal.Instant, availableAt: Temporal.Instant, options?: {
+  readonly retryAt?: Temporal.Instant;
+  readonly retryReason?: WorkflowRunRetryReason;
+  readonly retryAttempt?: number;
+  readonly retryStepId?: string;
+  readonly retryStepName?: string;
+  readonly error?: WorkflowErrorRecord;
+}): WorkflowRunRecord;
+declare function transitionRunToWaiting(run: WorkflowRunRecord, timestamp: Temporal.Instant, availableAt: Temporal.Instant): WorkflowRunRecord;
+declare function transitionRunToRescheduled(run: WorkflowRunRecord, timestamp: Temporal.Instant, availableAt: Temporal.Instant): WorkflowRunRecord;
+declare function transitionRunAfterStaleLeaseRelease(run: WorkflowRunRecord, timestamp: Temporal.Instant, availableAt: Temporal.Instant): WorkflowRunRecord;
+declare function transitionRunToManualRetry(run: WorkflowRunRecord, timestamp: Temporal.Instant, availableAt: Temporal.Instant, retryAttempt: number): WorkflowRunRecord;
+declare function transitionRunToPermanentFailure(run: WorkflowRunRecord, error: WorkflowErrorRecord, timestamp: Temporal.Instant): WorkflowRunRecord;
+declare function transitionRunToCanceled(run: WorkflowRunRecord, error: WorkflowErrorRecord, timestamp: Temporal.Instant): WorkflowRunRecord;
+declare function transitionRunAfterParentWake(run: WorkflowRunRecord, timestamp: Temporal.Instant): WorkflowRunRecord;
+declare function isCurrentExecutionOwner(current: WorkflowRunRecord, execution: WorkflowRunRecord): boolean;
+declare function cancelRunWithChildren(store: WorkflowChildCascadeStore, runId: RunId, canceledAt: Temporal.Instant): Promise<WorkflowRunRecord>;
+declare function cancelActiveChildRuns(store: WorkflowChildCascadeStore, parentRunId: RunId, canceledAt: Temporal.Instant): Promise<void>;
+declare function wakeParentRunForTerminalChild(store: WorkflowChildWakeStore, childRun: WorkflowRunRecord, timestamp: Temporal.Instant): Promise<void>;
+declare function wakeParentRunForWaitingChild(store: WorkflowChildWakeStore, childRun: WorkflowRunRecord, availableAt: Temporal.Instant): Promise<void>;
+declare function parentHasActiveChildWorkflowAttemptForRun(store: WorkflowChildWakeStore, parentRunId: RunId, childRun: WorkflowRunRecord): Promise<boolean>;
+declare function parentHasActiveChildWorkflowEventForAttempt(store: WorkflowEventReader, parentRunId: RunId, attempt: WorkflowStepAttemptRecord): Promise<boolean>;
+declare function failRunForDeadline<TOutput>(store: WorkflowChildRunStateStore, run: WorkflowRunRecord, deadlineAt: Temporal.Instant, failedAt: Temporal.Instant, executionOwner?: WorkflowRunRecord): Promise<ExecutionResult<TOutput>>;
+declare function releaseLocksForRun(store: WorkflowLockReleaseStore, runId: RunId, releasedAt: Temporal.Instant): Promise<void>;
+declare class WorkflowSuspended extends Error {
+  readonly availableAt: Temporal.Instant;
+  readonly retryAt?: Temporal.Instant;
+  readonly retryReason?: "step";
+  readonly retryAttempt?: number;
+  readonly retryStep?: WorkflowStepIdentity;
+  constructor(availableAt: Temporal.Instant, context?: Function);
+  static until(this: void, availableAt: Temporal.Instant): never;
+  static forStepRetry(this: void, retryAt: Temporal.Instant, retryStep: WorkflowStepIdentity, retryAttempt: number): never;
+}
+declare class WorkflowStaleExecutionError extends Error {
+  constructor(runId: RunId, context?: Function);
+  static stale(this: void, runId: RunId): never;
+}
+//#endregion
+export { WorkflowStaleExecutionError, WorkflowSuspended, appendEventIfCurrentExecution, cancelActiveChildRuns, cancelRunWithChildren, failRunForDeadline, getRequiredRun, isCurrentExecutionOwner, parentHasActiveChildWorkflowAttemptForRun, parentHasActiveChildWorkflowEventForAttempt, patchCurrentExecutionRun, patchCurrentExecutionRunAttributes, patchRun, patchRunIfCurrent, releaseLocksForRun, requireCurrentExecutionOwner, requireDefinitionMatchesRun, setRunAttributesIfCurrent, transitionRunAfterParentWake, transitionRunAfterStaleLeaseRelease, transitionRunToCanceled, transitionRunToCompleted, transitionRunToExecutionWait, transitionRunToFailed, transitionRunToManualRetry, transitionRunToMissingImplementationWait, transitionRunToPermanentFailure, transitionRunToRescheduled, transitionRunToRunning, transitionRunToWaiting, updateRunMetadataIfCurrent, wakeParentRunForTerminalChild, wakeParentRunForWaitingChild };