semola 0.5.2 → 0.5.4

package/dist/lib/workflow/index.d.mts

@@ -0,0 +1,85 @@
+//#region src/lib/workflow/types.d.ts
+type WorkflowStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+type WorkflowErrorType = "WorkflowError" | "WorkflowNotFoundError" | "WorkflowStateError" | "WorkflowSerializationError" | "WorkflowLockError" | "WorkflowExecutionError" | "WorkflowCancelledError";
+type WorkflowError = {
+  type: WorkflowErrorType;
+  message: string;
+};
+type StepSnapshot = {
+  name: string;
+  completedAt: number;
+};
+type WorkflowExecution<TInput, TResult> = {
+  id: string;
+  name: string;
+  status: WorkflowStatus;
+  input: TInput;
+  result: TResult | null;
+  error: string | null;
+  createdAt: number;
+  updatedAt: number;
+  completedAt: number | null;
+  failedAt: number | null;
+  cancelledAt: number | null;
+  steps: StepSnapshot[];
+};
+type StepHandler<TInput, TStep> = (input: TInput, signal: AbortSignal) => TStep | Promise<TStep>;
+type WorkflowHandlerContext<TInput> = {
+  input: TInput;
+  executionId: string;
+  signal: AbortSignal;
+  step: <TStep>(name: string, handler: StepHandler<TInput, TStep>) => Promise<TStep>;
+};
+type SerializeValue<T> = (value: T) => string;
+type DeserializeValue<T> = (raw: string) => T;
+type WorkflowOptions<TInput, TResult> = {
+  name: string;
+  redis: Bun.RedisClient;
+  handler: (context: WorkflowHandlerContext<TInput>) => TResult | Promise<TResult>;
+  lockTTL?: number;
+  serializeInput?: SerializeValue<TInput>;
+  deserializeInput?: DeserializeValue<TInput>;
+  serializeResult?: SerializeValue<TResult>;
+  deserializeResult?: DeserializeValue<TResult>;
+  serializeStepOutput?: SerializeValue<unknown>;
+  deserializeStepOutput?: DeserializeValue<unknown>;
+};
+type WorkflowStartOptions = {
+  executionId?: string;
+};
+type WorkflowStartResult = {
+  executionId: string;
+  status: WorkflowStatus;
+};
+type WorkflowCancelResult = {
+  status: WorkflowStatus;
+  executionId: string;
+  updatedAt: number;
+  cancelledAt: number;
+  createdAt: number;
+};
+type WorkflowMeta = {
+  status: string;
+  input: string;
+  result: string;
+  error: string;
+  createdAt: string;
+  updatedAt: string;
+  completedAt: string;
+  failedAt: string;
+  cancelledAt: string;
+  steps: string;
+};
+type WorkflowMetaField = keyof WorkflowMeta;
+type Workflow<TInput, TResult> = {
+  start: (input: TInput, options?: WorkflowStartOptions) => Promise<readonly [WorkflowError | null, WorkflowStartResult | null]>;
+  run: (input: TInput, options?: WorkflowStartOptions) => Promise<readonly [WorkflowError | null, TResult | null]>;
+  resume: (executionId: string) => Promise<readonly [WorkflowError | null, WorkflowStartResult | null]>;
+  get: (executionId: string) => Promise<readonly [WorkflowError | null, WorkflowExecution<TInput, TResult> | null]>;
+  cancel: (executionId: string) => Promise<readonly [WorkflowError | null, WorkflowCancelResult | null]>;
+};
+//#endregion
+//#region src/lib/workflow/index.d.ts
+declare const defineWorkflow: <TInput, TResult = void>(options: WorkflowOptions<TInput, TResult>) => Workflow<TInput, TResult>;
+//#endregion
+export { type StepHandler, type Workflow, type WorkflowError, type WorkflowExecution, type WorkflowHandlerContext, type WorkflowMeta, type WorkflowMetaField, type WorkflowOptions, type WorkflowStartOptions, type WorkflowStartResult, type WorkflowStatus, defineWorkflow };

package/dist/lib/workflow/index.mjs

@@ -0,0 +1,533 @@
+import { err, mightThrow, mightThrowSync, ok } from "../errors/index.mjs";
+//#region src/lib/workflow/index.ts
+const DEFAULT_LOCK_TTL = 300 * 1e3;
+const now = () => Date.now();
+const toErrorMessage = (error) => {
+	if (error instanceof Error) return error.message;
+	return String(error);
+};
+const envelopeSerialize = (value) => {
+	return JSON.stringify({ value });
+};
+const envelopeDeserialize = (raw) => {
+	const [parseError, parsed] = mightThrowSync(() => JSON.parse(raw));
+	if (parseError) throw parseError;
+	if (parsed === null) return;
+	if (typeof parsed !== "object") return;
+	if ("value" in parsed) return parsed.value;
+};
+const knownStatuses = [
+	"pending",
+	"running",
+	"completed",
+	"failed",
+	"cancelled"
+];
+var WorkflowDefinition = class {
+	options;
+	lockTTL;
+	constructor(options) {
+		this.options = options;
+		this.lockTTL = options.lockTTL ?? DEFAULT_LOCK_TTL;
+	}
+	async start(input, options) {
+		const executionId = options?.executionId ?? crypto.randomUUID();
+		const [createError] = await this.createExecution(executionId, input);
+		if (createError) return err(createError.type, createError.message);
+		return this.execute(executionId, input);
+	}
+	async run(input, options) {
+		const [startError, startData] = await this.start(input, options);
+		if (startError) return err(startError.type, startError.message);
+		if (!startData) return err("WorkflowError", "Unexpected empty start result");
+		if (startData.status === "cancelled") return err("WorkflowCancelledError", `Workflow execution ${startData.executionId} was cancelled`);
+		if (startData.status !== "completed") return err("WorkflowExecutionError", `Workflow execution ${startData.executionId} did not complete`);
+		const [getError, execution] = await this.get(startData.executionId);
+		if (getError) return err(getError.type, getError.message);
+		if (!execution) return err("WorkflowError", "Unexpected empty execution");
+		return ok(execution.result);
+	}
+	async resume(executionId) {
+		const [getError, execution] = await this.get(executionId);
+		if (getError) return err(getError.type, getError.message);
+		if (!execution) return err("WorkflowNotFoundError", `Workflow execution ${executionId} not found`);
+		if (execution.status === "completed") return ok({
+			executionId,
+			status: execution.status
+		});
+		if (execution.status === "cancelled") return ok({
+			executionId,
+			status: execution.status
+		});
+		return this.execute(executionId, execution.input);
+	}
+	async get(executionId) {
+		const [statusError, status] = await this.getMeta(executionId, "status");
+		if (statusError) return err(statusError.type, statusError.message);
+		if (!status) return err("WorkflowNotFoundError", `Workflow execution ${executionId} not found`);
+		const normalizedStatus = this.normalizeStatus(status);
+		if (!normalizedStatus) return err("WorkflowStateError", `Workflow execution ${executionId} has invalid status ${status}`);
+		const [inputError, input] = await this.readInput(executionId);
+		if (inputError) return err(inputError.type, inputError.message);
+		if (input === null) return err("WorkflowStateError", `Workflow execution ${executionId} has invalid input`);
+		const [resultError, result] = await this.readResult(executionId);
+		if (resultError) return err(resultError.type, resultError.message);
+		const [stepsError, steps] = await this.readStepSnapshots(executionId);
+		if (stepsError) return err(stepsError.type, stepsError.message);
+		const [createdAtError, createdAt] = await this.readNumberMeta(executionId, "createdAt");
+		if (createdAtError) return err(createdAtError.type, createdAtError.message);
+		if (createdAt === null) return err("WorkflowStateError", `Workflow execution ${executionId} is missing createdAt`);
+		const [updatedAtError, updatedAt] = await this.readNumberMeta(executionId, "updatedAt");
+		if (updatedAtError) return err(updatedAtError.type, updatedAtError.message);
+		if (updatedAt === null) return err("WorkflowStateError", `Workflow execution ${executionId} is missing updatedAt`);
+		const [metaError, errorMessage] = await this.getMeta(executionId, "error");
+		if (metaError) return err(metaError.type, metaError.message);
+		const [completedAtError, completedAt] = await this.readNumberMeta(executionId, "completedAt");
+		if (completedAtError) return err(completedAtError.type, completedAtError.message);
+		const [failedAtError, failedAt] = await this.readNumberMeta(executionId, "failedAt");
+		if (failedAtError) return err(failedAtError.type, failedAtError.message);
+		const [cancelledAtError, cancelledAt] = await this.readNumberMeta(executionId, "cancelledAt");
+		if (cancelledAtError) return err(cancelledAtError.type, cancelledAtError.message);
+		return ok({
+			id: executionId,
+			name: this.options.name,
+			status: normalizedStatus,
+			input,
+			result,
+			error: errorMessage,
+			createdAt,
+			updatedAt,
+			completedAt,
+			failedAt,
+			cancelledAt,
+			steps
+		});
+	}
+	async cancel(executionId) {
+		const [getError, execution] = await this.get(executionId);
+		if (getError) return err(getError.type, getError.message);
+		if (!execution) return err("WorkflowNotFoundError", `Workflow execution ${executionId} not found`);
+		if (execution.status === "completed") return err("WorkflowStateError", `Workflow execution ${executionId} is already completed`);
+		const timestamp = now();
+		const [statusError] = await this.setMeta(executionId, "status", "cancelled");
+		if (statusError) return err(statusError.type, statusError.message);
+		const [updatedAtError] = await this.setMeta(executionId, "updatedAt", String(timestamp));
+		if (updatedAtError) return err(updatedAtError.type, updatedAtError.message);
+		const [cancelledAtError] = await this.setMeta(executionId, "cancelledAt", String(timestamp));
+		if (cancelledAtError) return err(cancelledAtError.type, cancelledAtError.message);
+		const [clearErrorError] = await this.setMeta(executionId, "error", "");
+		if (clearErrorError) return err(clearErrorError.type, clearErrorError.message);
+		const [clearFailedAtError] = await this.setMeta(executionId, "failedAt", "");
+		if (clearFailedAtError) return err(clearFailedAtError.type, clearFailedAtError.message);
+		return ok({
+			executionId,
+			createdAt: execution.createdAt,
+			cancelledAt: timestamp,
+			updatedAt: timestamp,
+			status: "cancelled"
+		});
+	}
+	executionKey(executionId) {
+		return `workflow:${this.options.name}:execution:${executionId}`;
+	}
+	metaKey(executionId) {
+		return `${this.executionKey(executionId)}:meta`;
+	}
+	stepsKey(executionId) {
+		return `${this.executionKey(executionId)}:steps`;
+	}
+	lockKey(executionId) {
+		return `${this.executionKey(executionId)}:lock`;
+	}
+	async createExecution(executionId, input) {
+		const [serializeError, serializedInput] = this.serializeInput(input);
+		if (serializeError) return err("WorkflowSerializationError", `Unable to serialize workflow input for ${executionId}`);
+		const timestamp = now();
+		const [statusReadError, existingStatus] = await this.getMeta(executionId, "status");
+		if (statusReadError) return err(statusReadError.type, statusReadError.message);
+		if (existingStatus) return err("WorkflowStateError", `Workflow execution ${executionId} already exists`);
+		const metadata = {
+			status: "pending",
+			input: serializedInput,
+			result: "",
+			error: "",
+			createdAt: String(timestamp),
+			updatedAt: String(timestamp),
+			completedAt: "",
+			failedAt: "",
+			cancelledAt: "",
+			steps: "[]"
+		};
+		const [writeError] = await mightThrow(this.options.redis.hset(this.metaKey(executionId), metadata));
+		if (writeError) return err("WorkflowError", `Unable to persist metadata for execution ${executionId}`);
+		return ok(null);
+	}
+	async execute(executionId, input) {
+		const token = crypto.randomUUID();
+		const [lockError] = await this.acquireLock(executionId, token);
+		if (lockError) return err(lockError.type, lockError.message);
+		const [statusCheckError, currentStatus] = await this.getMeta(executionId, "status");
+		if (statusCheckError) {
+			await this.releaseLock(executionId, token);
+			return err(statusCheckError.type, statusCheckError.message);
+		}
+		if (currentStatus === "cancelled") {
+			await this.releaseLock(executionId, token);
+			return err("WorkflowStateError", `Workflow execution ${executionId} was cancelled`);
+		}
+		const timestamp = now();
+		const [runningStatusError] = await this.setMeta(executionId, "status", "running");
+		if (runningStatusError) {
+			await this.releaseLock(executionId, token);
+			return err(runningStatusError.type, runningStatusError.message);
+		}
+		const [runningUpdatedAtError] = await this.setMeta(executionId, "updatedAt", String(timestamp));
+		if (runningUpdatedAtError) {
+			await this.releaseLock(executionId, token);
+			return err(runningUpdatedAtError.type, runningUpdatedAtError.message);
+		}
+		const controller = new AbortController();
+		const renewInterval = Math.floor(this.lockTTL / 3);
+		let lockLost = false;
+		const renewTimer = setInterval(async () => {
+			const [renewError] = await this.extendLock(executionId, token);
+			if (renewError) {
+				lockLost = true;
+				controller.abort();
+				clearInterval(renewTimer);
+			}
+		}, renewInterval);
+		const step = async (name, handler) => {
+			const [cancelledError, cancelled] = await this.isCancelled(executionId);
+			if (cancelledError) return Promise.reject(new Error(cancelledError.message));
+			if (cancelled) {
+				controller.abort();
+				return Promise.reject(/* @__PURE__ */ new Error("Workflow cancelled"));
+			}
+			const [readError, cachedStep] = await this.readStepOutput(executionId, name);
+			if (readError) return Promise.reject(new Error(readError.message));
+			if (cachedStep.found) return cachedStep.value;
+			const [stepError, output] = await mightThrow(Promise.resolve(handler(input, controller.signal)));
+			if (stepError) return Promise.reject(stepError);
+			const [writeError] = await this.writeStepOutput(executionId, name, output);
+			if (writeError) return Promise.reject(new Error(writeError.message));
+			return output;
+		};
+		const [handlerError, result] = await mightThrow(Promise.resolve(this.options.handler({
+			input,
+			executionId,
+			signal: controller.signal,
+			step
+		})));
+		clearInterval(renewTimer);
+		if (lockLost) {
+			await this.releaseLock(executionId, token);
+			return err("WorkflowLockError", `Lock expired during execution ${executionId}`);
+		}
+		const [cancelledError, cancelled] = await this.isCancelled(executionId);
+		if (cancelledError) {
+			await this.releaseLock(executionId, token);
+			return err(cancelledError.type, cancelledError.message);
+		}
+		if (cancelled) {
+			const cancelledAt = now();
+			const [cancelledStatusError] = await this.setMeta(executionId, "status", "cancelled");
+			if (cancelledStatusError) {
+				await this.releaseLock(executionId, token);
+				return err(cancelledStatusError.type, cancelledStatusError.message);
+			}
+			const [cancelledUpdatedAtError] = await this.setMeta(executionId, "updatedAt", String(cancelledAt));
+			if (cancelledUpdatedAtError) {
+				await this.releaseLock(executionId, token);
+				return err(cancelledUpdatedAtError.type, cancelledUpdatedAtError.message);
+			}
+			const [cancelledAtError] = await this.setMeta(executionId, "cancelledAt", String(cancelledAt));
+			if (cancelledAtError) {
+				await this.releaseLock(executionId, token);
+				return err(cancelledAtError.type, cancelledAtError.message);
+			}
+			await this.releaseLock(executionId, token);
+			return ok({
+				executionId,
+				status: "cancelled"
+			});
+		}
+		if (handlerError) {
+			const failedAt = now();
+			const [failedStatusError] = await this.setMeta(executionId, "status", "failed");
+			if (failedStatusError) {
+				await this.releaseLock(executionId, token);
+				return err(failedStatusError.type, failedStatusError.message);
+			}
+			const [failedMessageError] = await this.setMeta(executionId, "error", toErrorMessage(handlerError));
+			if (failedMessageError) {
+				await this.releaseLock(executionId, token);
+				return err(failedMessageError.type, failedMessageError.message);
+			}
+			const [failedUpdatedAtError] = await this.setMeta(executionId, "updatedAt", String(failedAt));
+			if (failedUpdatedAtError) {
+				await this.releaseLock(executionId, token);
+				return err(failedUpdatedAtError.type, failedUpdatedAtError.message);
+			}
+			const [failedAtError] = await this.setMeta(executionId, "failedAt", String(failedAt));
+			if (failedAtError) {
+				await this.releaseLock(executionId, token);
+				return err(failedAtError.type, failedAtError.message);
+			}
+			await this.releaseLock(executionId, token);
+			return err("WorkflowExecutionError", `Workflow execution ${executionId} failed: ${toErrorMessage(handlerError)}`);
+		}
+		const [serializeResultError, serializedResult] = this.serializeResult(result);
+		if (serializeResultError) {
+			const failedAt = now();
+			const [failedStatusError] = await this.setMeta(executionId, "status", "failed");
+			if (failedStatusError) {
+				await this.releaseLock(executionId, token);
+				return err(failedStatusError.type, failedStatusError.message);
+			}
+			const [failedMessageError] = await this.setMeta(executionId, "error", serializeResultError.message);
+			if (failedMessageError) {
+				await this.releaseLock(executionId, token);
+				return err(failedMessageError.type, failedMessageError.message);
+			}
+			const [failedUpdatedAtError] = await this.setMeta(executionId, "updatedAt", String(failedAt));
+			if (failedUpdatedAtError) {
+				await this.releaseLock(executionId, token);
+				return err(failedUpdatedAtError.type, failedUpdatedAtError.message);
+			}
+			const [failedAtError] = await this.setMeta(executionId, "failedAt", String(failedAt));
+			if (failedAtError) {
+				await this.releaseLock(executionId, token);
+				return err(failedAtError.type, failedAtError.message);
+			}
+			await this.releaseLock(executionId, token);
+			return err("WorkflowSerializationError", `Unable to serialize workflow result for ${executionId}`);
+		}
+		const completedAt = now();
+		const [completedResultError] = await this.setMeta(executionId, "result", serializedResult);
+		if (completedResultError) {
+			await this.releaseLock(executionId, token);
+			return err(completedResultError.type, completedResultError.message);
+		}
+		const [completedStatusError] = await this.setMeta(executionId, "status", "completed");
+		if (completedStatusError) {
+			await this.releaseLock(executionId, token);
+			return err(completedStatusError.type, completedStatusError.message);
+		}
+		const [completedClearErrorError] = await this.setMeta(executionId, "error", "");
+		if (completedClearErrorError) {
+			await this.releaseLock(executionId, token);
+			return err(completedClearErrorError.type, completedClearErrorError.message);
+		}
+		const [completedClearFailedAtError] = await this.setMeta(executionId, "failedAt", "");
+		if (completedClearFailedAtError) {
+			await this.releaseLock(executionId, token);
+			return err(completedClearFailedAtError.type, completedClearFailedAtError.message);
+		}
+		const [completedUpdatedAtError] = await this.setMeta(executionId, "updatedAt", String(completedAt));
+		if (completedUpdatedAtError) {
+			await this.releaseLock(executionId, token);
+			return err(completedUpdatedAtError.type, completedUpdatedAtError.message);
+		}
+		const [completedAtError] = await this.setMeta(executionId, "completedAt", String(completedAt));
+		if (completedAtError) {
+			await this.releaseLock(executionId, token);
+			return err(completedAtError.type, completedAtError.message);
+		}
+		await this.releaseLock(executionId, token);
+		return ok({
+			executionId,
+			status: "completed"
+		});
+	}
+	async acquireLock(executionId, token) {
+		const [lockError, lockResult] = await mightThrow(this.options.redis.set(this.lockKey(executionId), token, "PX", String(this.lockTTL), "NX"));
+		if (lockError) return err("WorkflowLockError", `Unable to acquire lock for execution ${executionId}`);
+		if (lockResult !== "OK") return err("WorkflowLockError", `Workflow execution ${executionId} is already running`);
+		return ok(null);
+	}
+	async releaseLock(executionId, token) {
+		const [evalError] = await mightThrow(this.options.redis.send("EVAL", [
+			"if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) else return 0 end",
+			"1",
+			this.lockKey(executionId),
+			token
+		]));
+		if (evalError) return err("WorkflowLockError", `Unable to release lock for execution ${executionId}`);
+		return ok(null);
+	}
+	async extendLock(executionId, token) {
+		const [evalError, result] = await mightThrow(this.options.redis.send("EVAL", [
+			"if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) else return 0 end",
+			"1",
+			this.lockKey(executionId),
+			token,
+			String(this.lockTTL)
+		]));
+		if (evalError) return err("WorkflowLockError", `Unable to extend lock for execution ${executionId}`);
+		if (result === 0) return err("WorkflowLockError", `Lock ownership lost for execution ${executionId}`);
+		return ok(null);
+	}
+	async isCancelled(executionId) {
+		const [statusError, status] = await this.getMeta(executionId, "status");
+		if (statusError) return err(statusError.type, statusError.message);
+		return ok(status === "cancelled");
+	}
+	async setMeta(executionId, field, value) {
+		const [writeError] = await mightThrow(this.options.redis.hset(this.metaKey(executionId), field, value));
+		if (writeError) return err("WorkflowError", `Unable to persist ${field} for execution ${executionId}`);
+		return ok(null);
+	}
+	async getMeta(executionId, field) {
+		const [readError, value] = await mightThrow(this.options.redis.hget(this.metaKey(executionId), field));
+		if (readError) return err("WorkflowError", `Unable to read ${field} for execution ${executionId}`);
+		if (value === null || value === void 0) return ok(null);
+		if (typeof value !== "string") return err("WorkflowStateError", `Invalid ${field} value for execution ${executionId}`);
+		if (value.length === 0) return ok(null);
+		return ok(value);
+	}
+	async readNumberMeta(executionId, field) {
+		const [readError, value] = await this.getMeta(executionId, field);
+		if (readError) return err(readError.type, readError.message);
+		if (!value) return ok(null);
+		const parsed = Number(value);
+		if (!Number.isFinite(parsed)) return err("WorkflowStateError", `Invalid ${field} value for execution ${executionId}`);
+		return ok(parsed);
+	}
+	runSerializer(value, serializer, label) {
+		const [serializeError, serialized] = mightThrowSync(() => serializer(value));
+		if (serializeError) return err("WorkflowSerializationError", `Unable to serialize ${label}: ${toErrorMessage(serializeError)}`);
+		if (typeof serialized !== "string") return err("WorkflowSerializationError", `${label} serializer must return a string`);
+		return ok(serialized);
+	}
+	runDeserializer(raw, deserializer, label) {
+		const [deserializeError, value] = mightThrowSync(() => deserializer(raw));
+		if (deserializeError) return err("WorkflowSerializationError", `Unable to deserialize ${label}: ${toErrorMessage(deserializeError)}`);
+		return ok(value);
+	}
+	serializeInput(input) {
+		return this.runSerializer(input, this.options.serializeInput ?? envelopeSerialize, "workflow input");
+	}
+	deserializeInput(raw) {
+		const deserializer = this.options.deserializeInput ?? ((value) => envelopeDeserialize(value));
+		return this.runDeserializer(raw, deserializer, "workflow input");
+	}
+	serializeResult(result) {
+		if (result === null) return ok(envelopeSerialize(null));
+		return this.runSerializer(result, this.options.serializeResult ?? envelopeSerialize, "workflow result");
+	}
+	deserializeResult(raw) {
+		const deserializer = this.options.deserializeResult ?? ((value) => envelopeDeserialize(value));
+		return this.runDeserializer(raw, deserializer, "workflow result");
+	}
+	serializeStepOutput(output) {
+		return this.runSerializer(output, this.options.serializeStepOutput ?? envelopeSerialize, "step output");
+	}
+	deserializeStepOutput(raw) {
+		const deserializer = this.options.deserializeStepOutput ?? ((value) => envelopeDeserialize(value));
+		return this.runDeserializer(raw, deserializer, "step output");
+	}
+	async readInput(executionId) {
+		const [readError, raw] = await this.getMeta(executionId, "input");
+		if (readError) return err(readError.type, readError.message);
+		if (!raw) return err("WorkflowStateError", `Workflow execution ${executionId} input not found`);
+		return this.deserializeInput(raw);
+	}
+	async readResult(executionId) {
+		const [readError, raw] = await this.getMeta(executionId, "result");
+		if (readError) return err(readError.type, readError.message);
+		if (!raw) return ok(null);
+		const [deserializeError, result] = this.deserializeResult(raw);
+		if (deserializeError) return err(deserializeError.type, deserializeError.message);
+		return ok(result);
+	}
+	async writeStepOutput(executionId, stepName, output) {
+		const [serializeError, serializedOutput] = this.serializeStepOutput(output);
+		if (serializeError) return err("WorkflowSerializationError", `Unable to serialize step ${stepName} output`);
+		const payload = {
+			output: serializedOutput,
+			completedAt: now()
+		};
+		const [payloadError, payloadRaw] = mightThrowSync(() => JSON.stringify(payload));
+		if (payloadError || typeof payloadRaw !== "string") return err("WorkflowSerializationError", `Unable to persist step ${stepName} output`);
+		const [writeError] = await mightThrow(this.options.redis.hset(this.stepsKey(executionId), stepName, payloadRaw));
+		if (writeError) return err("WorkflowError", `Unable to persist step ${stepName} for execution ${executionId}`);
+		const [stepNamesError, stepNames] = await this.readStepNames(executionId);
+		if (stepNamesError) return err(stepNamesError.type, stepNamesError.message);
+		if (!stepNames.includes(stepName)) {
+			const nextStepNames = [...stepNames, stepName];
+			const [serializeStepsError, serializedSteps] = mightThrowSync(() => JSON.stringify(nextStepNames));
+			if (serializeStepsError || typeof serializedSteps !== "string") return err("WorkflowSerializationError", `Unable to persist step history for execution ${executionId}`);
+			const [updateStepsError] = await this.setMeta(executionId, "steps", serializedSteps);
+			if (updateStepsError) return err(updateStepsError.type, updateStepsError.message);
+		}
+		const [updatedError] = await this.setMeta(executionId, "updatedAt", String(now()));
+		if (updatedError) return err(updatedError.type, updatedError.message);
+		return ok(null);
+	}
+	async readStepOutput(executionId, stepName) {
+		const [readError, payloadRaw] = await mightThrow(this.options.redis.hget(this.stepsKey(executionId), stepName));
+		if (readError) return err("WorkflowError", `Unable to read step ${stepName} for execution ${executionId}`);
+		if (!payloadRaw) return ok({
+			found: false,
+			value: null
+		});
+		if (typeof payloadRaw !== "string") return err("WorkflowStateError", `Invalid step payload for ${stepName} in execution ${executionId}`);
+		const [parseError, parsed] = mightThrowSync(() => JSON.parse(payloadRaw));
+		if (parseError || parsed === null || typeof parsed !== "object") return err("WorkflowStateError", `Invalid step payload for ${stepName} in execution ${executionId}`);
+		if (typeof parsed.output !== "string") return err("WorkflowStateError", `Invalid step output for ${stepName} in execution ${executionId}`);
+		const outputRaw = parsed.output;
+		const [deserializeError, value] = this.deserializeStepOutput(outputRaw);
+		if (deserializeError) return err(deserializeError.type, deserializeError.message);
+		return ok({
+			found: true,
+			value
+		});
+	}
+	async readStepNames(executionId) {
+		const [readError, stepsRaw] = await this.getMeta(executionId, "steps");
+		if (readError) return [readError, []];
+		if (!stepsRaw) return ok([]);
+		const [parseError, values] = mightThrowSync(() => JSON.parse(stepsRaw));
+		if (parseError || !Array.isArray(values)) return err("WorkflowStateError", `Invalid step index for execution ${executionId}`);
+		const stepNames = [];
+		for (const value of values) if (typeof value === "string") stepNames.push(value);
+		return ok(stepNames);
+	}
+	async readStepSnapshots(executionId) {
+		const [stepNamesError, stepNames] = await this.readStepNames(executionId);
+		if (stepNamesError) return [stepNamesError, []];
+		const steps = [];
+		for (const stepName of stepNames) {
+			const [readError, payloadRaw] = await mightThrow(this.options.redis.hget(this.stepsKey(executionId), stepName));
+			if (readError) return err("WorkflowError", `Unable to read step ${stepName} for execution ${executionId}`);
+			if (!payloadRaw) continue;
+			if (typeof payloadRaw !== "string") return err("WorkflowStateError", `Invalid step payload for ${stepName} in execution ${executionId}`);
+			const [parseError, parsed] = mightThrowSync(() => JSON.parse(payloadRaw));
+			if (parseError || parsed === null || typeof parsed !== "object") return err("WorkflowStateError", `Invalid step payload for ${stepName} in execution ${executionId}`);
+			if (typeof parsed.completedAt !== "number") return err("WorkflowStateError", `Invalid step payload for ${stepName} in execution ${executionId}`);
+			const completedAt = parsed.completedAt;
+			steps.push({
+				name: stepName,
+				completedAt
+			});
+		}
+		return ok(steps);
+	}
+	normalizeStatus(value) {
+		for (const status of knownStatuses) if (status === value) return status;
+		return null;
+	}
+};
+const defineWorkflow = (options) => {
+	const workflow = new WorkflowDefinition(options);
+	return {
+		start: (input, startOptions) => workflow.start(input, startOptions),
+		run: (input, startOptions) => workflow.run(input, startOptions),
+		resume: (executionId) => workflow.resume(executionId),
+		get: (executionId) => workflow.get(executionId),
+		cancel: (executionId) => workflow.cancel(executionId)
+	};
+};
+//#endregion
+export { defineWorkflow };

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "semola",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Zero-dependency TypeScript utilities for Bun. Type-safe APIs, Redis queues, pub/sub, i18n, caching & auth with tree-shakeable imports.",
   "type": "module",
+  "bin": {
+    "semola": "./dist/cli/index.js"
+  },
   "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
     "./errors": {
       "import": {
         "types": "./dist/lib/errors/index.d.mts",
@@ -85,8 +92,14 @@
       }
     },
     "./logging": {
-      "import": "./dist/lib/logging/index.js",
-      "types": "./dist/lib/logging/index.d.ts"
+      "import": {
+        "types": "./dist/lib/logging/index.d.mts",
+        "default": "./dist/lib/logging/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/logging/index.d.cts",
+        "default": "./dist/lib/logging/index.cjs"
+      }
     },
     "./prompts": {
       "import": {
@@ -97,6 +110,16 @@
         "types": "./dist/lib/prompts/index.d.cts",
         "default": "./dist/lib/prompts/index.cjs"
       }
+    },
+    "./workflow": {
+      "import": {
+        "types": "./dist/lib/workflow/index.d.mts",
+        "default": "./dist/lib/workflow/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/workflow/index.d.cts",
+        "default": "./dist/lib/workflow/index.cjs"
+      }
     }
   },
   "files": [
@@ -124,6 +147,9 @@
     "cron",
     "scheduler",
     "job-scheduler",
+    "workflow",
+    "durable-workflow",
+    "resumable-workflow",
     "i18n",
     "internationalization",
     "authorization",