octaflow 0.14.0

package/dist/core-ERYGlYsS.js

@@ -0,0 +1,574 @@
+import { z } from "zod";
+//#region src/core/result.ts
+const ok = (value) => ({
+	ok: true,
+	value
+});
+const err = (error) => ({
+	ok: false,
+	error
+});
+//#endregion
+//#region src/core/logger.ts
+const noopLogger = {
+	info() {},
+	warn() {},
+	error() {}
+};
+//#endregion
+//#region src/core/retry.ts
+/**
+* Realm-safe marker for an explicit retryability decision. `Symbol.for` so a
+* duplicated copy of this module still reads markers set by the other copy.
+*/
+const RETRYABLE = Symbol.for("octaflow.retryable");
+/**
+* Fallback store for errors that cannot carry a property — frozen, sealed, or
+* non-extensible objects, which some SDKs hand out. Keyed weakly, so marking an
+* error never keeps it alive.
+*/
+const sideTable = /* @__PURE__ */ new WeakMap();
+/**
+* Tag an error with an explicit retryability decision, overriding both the
+* step predicate and the message heuristic. Returns the same error, so it can
+* wrap a throw:
+*
+* ```ts
+* throw markRetryable(await client.readError(), true);
+* ```
+*/
+function markRetryable(error, retryable = true) {
+	if (typeof error === "object" && error !== null) try {
+		Object.defineProperty(error, RETRYABLE, {
+			value: retryable,
+			enumerable: false,
+			configurable: true
+		});
+	} catch {
+		sideTable.set(error, retryable);
+	}
+	return error;
+}
+/** An error the engine will always retry (within the step's attempt budget). */
+function retryableError(message, options) {
+	return markRetryable(new Error(message, options), true);
+}
+/** An error the engine will never retry, whatever its message says. */
+function nonRetryableError(message, options) {
+	return markRetryable(new Error(message, options), false);
+}
+/** How deep to follow `cause` before giving up. Guards against pathological chains. */
+const MAX_CAUSE_DEPTH = 8;
+/**
+* The explicit decision carried by an error, or `undefined` if it carries none.
+* Callers deciding retryability themselves should consult this first.
+*
+* Follows the `cause` chain, so a marked error keeps its decision when a caller
+* wraps it — `new Error('upstream failed', { cause: retryableError('busy') })`
+* still reports `true`. The outermost decision wins; the walk is depth-capped and
+* cycle-safe.
+*/
+function explicitRetryability(error) {
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+		if (typeof current !== "object" || current === null || seen.has(current)) return void 0;
+		seen.add(current);
+		const value = current[RETRYABLE];
+		if (typeof value === "boolean") return value;
+		const stored = sideTable.get(current);
+		if (stored !== void 0) return stored;
+		current = current.cause;
+	}
+}
+/**
+* Transient `code` values, as set by Node's networking stack and by most clients
+* built on it. Deliberately excludes permanent ones like `ENOTFOUND` (bad host)
+* and `ERR_INVALID_ARG_TYPE` (a bug).
+*/
+const RETRYABLE_CODES = /* @__PURE__ */ new Set([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ECONNABORTED",
+	"ETIMEDOUT",
+	"EPIPE",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"ENETRESET",
+	"EAI_AGAIN",
+	"EBUSY",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_HEADERS_TIMEOUT",
+	"UND_ERR_BODY_TIMEOUT"
+]);
+/** Transient HTTP statuses. 5xx is transient except the ones that mean "never".  */
+function isRetryableStatus(status) {
+	if (status === 408 || status === 425 || status === 429) return true;
+	return status >= 500 && status < 600 && status !== 501 && status !== 505;
+}
+/** Read a numeric HTTP status off the shapes clients actually use. */
+function statusOf(error) {
+	for (const key of [
+		"status",
+		"statusCode",
+		"httpStatusCode"
+	]) {
+		const v = error[key];
+		if (typeof v === "number" && Number.isFinite(v)) return v;
+	}
+	const response = error.response;
+	if (response && typeof response.status === "number") return response.status;
+}
+/**
+* Default classifier for a thrown error, used when nothing more specific applies.
+* Checked in order:
+*
+*   1. An explicit marker ({@link markRetryable}), including through `cause`.
+*   2. **Structured fields** — `code` (`ECONNRESET`, `ETIMEDOUT`, …) and HTTP
+*      status (`status` / `statusCode` / `response.status`): 408, 425, 429, 5xx.
+*   3. **The message**, matched against a small vocabulary.
+*
+* Steps 2–3 are a convenience, not a classifier. The message check especially will
+* misjudge anything whose wording it doesn't recognise — a permanent bug reading
+* `'timeout must be > 0'` looks transient. Reach for {@link retryableError} /
+* {@link nonRetryableError}, `defineStep`'s `isRetryable`, or the engine's
+* `defaultRetryable` when the answer matters.
+*/
+function isRetryableError(error) {
+	const explicit = explicitRetryability(error);
+	if (explicit !== void 0) return explicit;
+	if (typeof error === "object" && error !== null) {
+		const code = error.code;
+		if (typeof code === "string" && RETRYABLE_CODES.has(code.toUpperCase())) return true;
+		const status = statusOf(error);
+		if (status !== void 0) return isRetryableStatus(status);
+	}
+	if (!(error instanceof Error)) return false;
+	const message = error.message.toLowerCase();
+	if (message.includes("rate limit") || message.includes("429") || message.includes("too many requests")) return true;
+	if (message.includes("timeout") || message.includes("econnreset") || message.includes("fetch failed")) return true;
+	if (message.includes("503") || message.includes("service unavailable")) return true;
+	return false;
+}
+//#endregion
+//#region src/core/defineStep.ts
+/**
+* `z.object({})` typed as the empty-record schema. Zod infers `{}` for an empty object schema,
+* but we want `Record<string, never>` for input/output-less steps — hence the bridge cast.
+* Shared by `defineWaitStep`, `defineMapStep`'s child, and `defineSleepStep`.
+*/
+const emptyObjectSchema = z.object({});
+/**
+* Define a type-safe workflow step with Zod validation. Wraps a typed handler
+* into an untyped `StepHandler` with a 5-phase pipeline:
+*
+*   1. Parse `workflowInput` against `workflowInputSchema`
+*   2. Parse each dependency output against its `outputSchema`
+*   3. Build the typed context
+*   4. Call the handler
+*   5. Parse the output against `outputSchema`
+*
+* Validation errors are non-retryable (a schema mismatch is a programming error).
+*/
+function defineStep(config) {
+	const { type, workflowInputSchema, outputSchema, dependencies, handler, retry, isRetryable, timeoutMs, delayMs, waitForEvent } = config;
+	const deps = dependencies ?? {};
+	const wrappedHandler = async (ctx) => {
+		try {
+			const inputResult = workflowInputSchema.safeParse(ctx.workflowInput);
+			if (!inputResult.success) return {
+				ok: false,
+				error: {
+					key: "step_error",
+					message: `[${type}] Invalid workflow input: ${inputResult.error.message}`,
+					retryable: false
+				}
+			};
+			const parsedDeps = {};
+			for (const [depKey, depStep] of Object.entries(deps)) {
+				const depResult = depStep.outputSchema.safeParse(ctx.dependencyOutputs[depKey]);
+				if (!depResult.success) return {
+					ok: false,
+					error: {
+						key: "step_error",
+						message: `[${type}] Invalid dependency output '${depKey}': ${depResult.error.message}`,
+						retryable: false
+					}
+				};
+				parsedDeps[depKey] = depResult.data;
+			}
+			const typedCtx = {
+				workflowId: ctx.workflowId,
+				stepId: ctx.stepId,
+				stepKey: ctx.stepKey,
+				partitionKey: ctx.partitionKey,
+				workflowInput: inputResult.data,
+				stepInput: ctx.stepInput,
+				deps: parsedDeps,
+				signal: ctx.signal,
+				context: ctx.context
+			};
+			const output = await handler(typedCtx);
+			const outputResult = outputSchema.safeParse(output);
+			if (!outputResult.success) return {
+				ok: false,
+				error: {
+					key: "step_error",
+					message: `[${type}] Invalid step output: ${outputResult.error.message}`,
+					retryable: false
+				}
+			};
+			return {
+				ok: true,
+				value: outputResult.data
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown step error";
+			const marked = explicitRetryability(error);
+			return {
+				ok: false,
+				error: {
+					key: "step_error",
+					message,
+					retryable: marked ?? (isRetryable ? isRetryable(error) : isRetryableError(error)),
+					retryableFrom: marked !== void 0 ? "explicit" : isRetryable ? "predicate" : "heuristic"
+				}
+			};
+		}
+	};
+	let wrappedCompensate;
+	if (config.compensate) {
+		const compensate = config.compensate;
+		wrappedCompensate = async (ctx) => {
+			const input = workflowInputSchema.safeParse(ctx.workflowInput);
+			const parsedDeps = {};
+			for (const [depKey, depStep] of Object.entries(deps)) {
+				const r = depStep.outputSchema.safeParse(ctx.dependencyOutputs[depKey]);
+				parsedDeps[depKey] = r.success ? r.data : ctx.dependencyOutputs[depKey];
+			}
+			const out = outputSchema.safeParse(ctx.output);
+			await compensate({
+				workflowId: ctx.workflowId,
+				stepId: ctx.stepId,
+				stepKey: ctx.stepKey,
+				partitionKey: ctx.partitionKey,
+				workflowInput: input.success ? input.data : ctx.workflowInput,
+				stepInput: ctx.stepInput,
+				deps: parsedDeps,
+				signal: ctx.signal,
+				context: ctx.context,
+				output: out.success ? out.data : ctx.output
+			});
+		};
+	}
+	return {
+		type,
+		workflowInputSchema,
+		outputSchema,
+		dependencies: deps,
+		handler: wrappedHandler,
+		retry,
+		timeoutMs,
+		delayMs,
+		waitForEvent,
+		compensate: wrappedCompensate
+	};
+}
+/**
+* Define a **wait-for-event** step: once its dependencies complete, it suspends
+* (status `waiting`) instead of running, until `engine.resumeStep(workflowId, stepKey,
+* payload)` delivers an external event. The resume payload becomes the step's output
+* (validated by dependents against `outputSchema`), then the DAG advances.
+*
+* Use for human-in-the-loop approvals, webhooks, or any async external dependency.
+*/
+function defineWaitStep(config) {
+	return defineStep({
+		type: config.type,
+		workflowInputSchema: emptyObjectSchema,
+		outputSchema: config.outputSchema,
+		dependencies: config.dependencies,
+		waitForEvent: true,
+		handler: async () => ({})
+	});
+}
+/**
+* Define a **map** step: dynamic fan-out. `items(ctx)` produces a runtime-sized
+* list from the step's deps/input; the engine spawns one child per item (each running
+* `each(item, …)` with its own retry/timeout), suspends the parent as `mapping`, and
+* completes it with `{ items: childOutputs[] }` (ordered) once all children finish. A
+* failed item fails the whole map. Use for "do X for each of N images/sections/locales".
+*
+* The map step's output type is `{ items: TItemOutput[] }`; dependents read `deps.X.items`.
+*/
+function defineMapStep(config) {
+	const childType = `${config.type}__item`;
+	const parent = defineStep({
+		type: config.type,
+		workflowInputSchema: config.workflowInputSchema,
+		outputSchema: z.object({ items: z.array(z.unknown()) }),
+		dependencies: config.dependencies,
+		handler: async (ctx) => ({ items: await config.items(ctx) })
+	});
+	const child = defineStep({
+		type: childType,
+		workflowInputSchema: emptyObjectSchema,
+		outputSchema: config.itemOutputSchema,
+		retry: config.itemRetry,
+		isRetryable: config.itemIsRetryable,
+		timeoutMs: config.itemTimeoutMs,
+		handler: async (ctx) => config.each(ctx.stepInput.item, {
+			index: Number(ctx.stepInput.index ?? 0),
+			context: ctx.context,
+			workflowId: ctx.workflowId,
+			partitionKey: ctx.partitionKey
+		})
+	});
+	return {
+		...parent,
+		outputSchema: z.object({ items: z.array(config.itemOutputSchema) }),
+		map: true,
+		childType,
+		childRegistration: {
+			type: childType,
+			handler: child.handler,
+			retry: child.retry,
+			timeoutMs: child.timeoutMs
+		}
+	};
+}
+/**
+* Define a **sub-workflow** step: once its deps complete, `input(ctx)` maps the
+* parent context to the child workflow's input; the engine **starts the child workflow**
+* (sharing the partition), suspends this step as `waiting`, and resumes it with the child's
+* output once the child terminates. A failed/cancelled child fails this step (and cascades).
+*
+* Pass the built child workflow (`buildWorkflow(...)`); its step handlers are registered
+* automatically alongside the parent. The step's output type is the child's output shape —
+* give `outputSchema` to type it for dependents (defaults to an opaque record).
+*/
+function defineSubWorkflowStep(config) {
+	const recordSchema = z.record(z.string(), z.unknown());
+	return {
+		...defineStep({
+			type: config.type,
+			workflowInputSchema: config.workflowInputSchema,
+			outputSchema: recordSchema,
+			dependencies: config.dependencies,
+			handler: async (ctx) => config.input(ctx)
+		}),
+		outputSchema: config.outputSchema ?? recordSchema,
+		subWorkflowDefinition: config.childWorkflow.definition,
+		subWorkflowRegister: config.childWorkflow.register
+	};
+}
+/**
+* Define a durable **sleep** step: a no-op step that, once its dependencies complete,
+* is held in the queue for `sleepMs` before completing — advancing the DAG afterwards.
+* The delay is durable (survives restarts) because it lives in the queue, not in memory.
+*
+* A sleep step is just `defineStep` with `delayMs` and an empty handler; use this for
+* cooldowns, "continue in 1 hour", or spacing out downstream work.
+*/
+function defineSleepStep(config) {
+	return defineStep({
+		type: config.type,
+		workflowInputSchema: emptyObjectSchema,
+		outputSchema: emptyObjectSchema,
+		dependencies: config.dependencies,
+		delayMs: config.sleepMs,
+		handler: async () => ({})
+	});
+}
+/**
+* Build a typed workflow from step definitions. Derives the `WorkflowDefinition`
+* DAG from each step's dependency metadata and validates at construction time
+* that every dependency key references a real step.
+*/
+function buildWorkflow(config) {
+	const { type, inputSchema, steps } = config;
+	const stepKeys = new Set(Object.keys(steps));
+	for (const [stepKey, step] of Object.entries(steps)) for (const depKey of Object.keys(step.dependencies)) if (!stepKeys.has(depKey)) throw new Error(`[buildWorkflow] Step '${stepKey}' depends on '${depKey}', which is not a valid step key. Valid keys: ${[...stepKeys].join(", ")}`);
+	const definition = {
+		type,
+		steps: Object.entries(steps).map(([key, step]) => {
+			const depKeys = Object.keys(step.dependencies);
+			return {
+				key,
+				type: step.type,
+				...depKeys.length > 0 ? { dependencies: depKeys } : {}
+			};
+		})
+	};
+	return {
+		type,
+		inputSchema,
+		definition,
+		register(registry) {
+			for (const step of Object.values(steps)) {
+				registry.register(step.type, step.handler, {
+					retry: step.retry,
+					timeoutMs: step.timeoutMs,
+					delayMs: step.delayMs,
+					waitForEvent: step.waitForEvent,
+					map: step.map,
+					childType: step.childType,
+					subWorkflowDefinition: step.subWorkflowDefinition,
+					compensate: step.compensate
+				});
+				if (step.childRegistration) {
+					const c = step.childRegistration;
+					registry.register(c.type, c.handler, {
+						retry: c.retry,
+						timeoutMs: c.timeoutMs
+					});
+				}
+				if (step.subWorkflowRegister) step.subWorkflowRegister(registry);
+			}
+		},
+		start(engine, input, options) {
+			const parsed = inputSchema.parse(input);
+			return engine.startWorkflow(definition, parsed, options);
+		}
+	};
+}
+//#endregion
+//#region src/core/public-view.ts
+/**
+* Public wire view of a workflow — the projection every HTTP consumer was
+* hand-writing.
+*
+* The engine's records ({@link WorkflowRecord}, {@link StepRecord}) are the
+* store's data model: they carry fields that must not leak onto a public API
+* (`partitionKey`, `idempotencyKey`, sub-workflow linkage, `metadata`, retry
+* `attempts`) and step statuses that are engine mechanics rather than display
+* states. Serving them verbatim also couples the consumer's API contract to
+* flow's record shape. This module owns the boundary instead:
+*
+* - {@link toPublicWorkflow} / {@link toPublicStep} — drop the internal
+*   fields, fold engine step statuses to the five display states.
+* - {@link PUBLIC_WORKFLOW_SCHEMA} / {@link PUBLIC_WORKFLOW_STEP_SCHEMA} —
+*   the same shapes as Zod schemas, ready for route `response` declarations
+*   (OpenAPI output, response validation, typed clients).
+*
+* The projection is deliberately closed: anything consumer-specific rides on
+* top rather than through an options bag. E.g. surfacing an `appliedAt` stamp
+* kept in workflow metadata:
+*
+* ```ts
+* const schema = PUBLIC_WORKFLOW_SCHEMA.extend({ appliedAt: z.string().nullable() });
+* const view = {
+*   ...toPublicWorkflow(workflow),
+*   appliedAt: (workflow.metadata?.appliedAt as string | undefined) ?? null,
+* };
+* ```
+*/
+const STEP_DISPLAY_STATUS_SCHEMA = z.enum([
+	"pending",
+	"running",
+	"completed",
+	"failed",
+	"skipped"
+]);
+/**
+* Engine step statuses folded to display states. `waiting` (suspended for an
+* event), `mapping` (fan-out in flight), and `compensating` (rollback running)
+* are all "still in flight" from a reader's point of view; a `compensated`
+* step's work was undone, which reads as `skipped`, with the failure that
+* triggered the rollback reported by the failed step itself. Exhaustive over
+* {@link StepStatus} so a new engine status is a compile error here, not a
+* silent hole in a consumer's API.
+*/
+const STEP_DISPLAY_STATUS = {
+	pending: "pending",
+	running: "running",
+	completed: "completed",
+	failed: "failed",
+	skipped: "skipped",
+	waiting: "running",
+	mapping: "running",
+	compensating: "running",
+	compensated: "skipped"
+};
+/** Fold one engine step status to its display state. */
+function toDisplayStepStatus(status) {
+	return STEP_DISPLAY_STATUS[status];
+}
+const WORKFLOW_STATUS_SCHEMA = z.enum([
+	"pending",
+	"running",
+	"completed",
+	"failed",
+	"cancelled"
+]);
+const PUBLIC_WORKFLOW_STEP_SCHEMA = z.object({
+	id: z.number().int(),
+	key: z.string(),
+	type: z.string(),
+	status: STEP_DISPLAY_STATUS_SCHEMA,
+	dependencies: z.array(z.string()),
+	input: z.record(z.string(), z.unknown()).nullable(),
+	output: z.record(z.string(), z.unknown()).nullable(),
+	error: z.string().nullable(),
+	startedAt: z.string().nullable(),
+	completedAt: z.string().nullable()
+});
+const PUBLIC_WORKFLOW_SCHEMA = z.object({
+	id: z.number().int(),
+	type: z.string(),
+	status: WORKFLOW_STATUS_SCHEMA,
+	input: z.record(z.string(), z.unknown()),
+	output: z.record(z.string(), z.unknown()).nullable(),
+	error: z.string().nullable(),
+	entityRef: z.string().nullable(),
+	totalSteps: z.number().int(),
+	completedSteps: z.number().int(),
+	failedSteps: z.number().int(),
+	steps: z.array(PUBLIC_WORKFLOW_STEP_SCHEMA),
+	createdAt: z.string(),
+	startedAt: z.string().nullable(),
+	completedAt: z.string().nullable()
+});
+/**
+* Project a step record to its public view. Drops `workflowId` (redundant
+* under the parent), `metadata`, `attempts`, and `parentStepId`; folds the
+* status.
+*/
+function toPublicStep(step) {
+	return {
+		id: step.id,
+		key: step.key,
+		type: step.type,
+		status: toDisplayStepStatus(step.status),
+		dependencies: step.dependencies,
+		input: step.input,
+		output: step.output,
+		error: step.error,
+		startedAt: step.startedAt,
+		completedAt: step.completedAt
+	};
+}
+/**
+* Project a workflow (with steps) to its public view. Drops `partitionKey`,
+* `idempotencyKey`, `parentWorkflowId`/`parentStepId`, and `metadata`.
+*/
+function toPublicWorkflow(workflow) {
+	return {
+		id: workflow.id,
+		type: workflow.type,
+		status: workflow.status,
+		input: workflow.input,
+		output: workflow.output,
+		error: workflow.error,
+		entityRef: workflow.entityRef,
+		totalSteps: workflow.totalSteps,
+		completedSteps: workflow.completedSteps,
+		failedSteps: workflow.failedSteps,
+		steps: workflow.steps.map(toPublicStep),
+		createdAt: workflow.createdAt,
+		startedAt: workflow.startedAt,
+		completedAt: workflow.completedAt
+	};
+}
+//#endregion
+export { ok as S, markRetryable as _, WORKFLOW_STATUS_SCHEMA as a, noopLogger as b, toPublicWorkflow as c, defineSleepStep as d, defineStep as f, isRetryableError as g, explicitRetryability as h, STEP_DISPLAY_STATUS_SCHEMA as i, buildWorkflow as l, defineWaitStep as m, PUBLIC_WORKFLOW_STEP_SCHEMA as n, toDisplayStepStatus as o, defineSubWorkflowStep as p, STEP_DISPLAY_STATUS as r, toPublicStep as s, PUBLIC_WORKFLOW_SCHEMA as t, defineMapStep as u, nonRetryableError as v, err as x, retryableError as y };

package/dist/dispatcher-BydjyrgU.d.ts

@@ -0,0 +1,26 @@
+import { F as StepId, K as FlowErrorShape, V as WorkflowId, q as Result } from "./index-D_fOYfmf.js";
+//#region src/core/dispatcher.d.ts
+/** Payload handed to the dispatcher to schedule a single step for execution. */
+interface DispatchStepPayload {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  stepKey: string;
+  stepType: string;
+}
+interface EnqueueOptions {
+  /**
+   * Delay before the step becomes eligible to run, in seconds. Durable — survives
+   * restarts. Used for retry backoff (and, later, durable sleep). Default 0.
+   */
+  startAfterSeconds?: number;
+}
+/**
+ * Schedules step execution. The default adapter is a pg-boss queue, but any
+ * durable-job mechanism works: the only contract is "eventually call
+ * `engine.executeStep(workflowId, stepId)` for this payload, with retries".
+ */
+interface Dispatcher {
+  enqueueStep(payload: DispatchStepPayload, options?: EnqueueOptions): Promise<Result<void, FlowErrorShape>>;
+}
+//#endregion
+export { Dispatcher as n, EnqueueOptions as r, DispatchStepPayload as t };