octaflow 0.14.0

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import { A as StepError, B as WorkflowDefinition, C as FlowError, D as StepCompensateHandler, E as StartOptions, F as StepId, G as WorkflowWithSteps, H as WorkflowNotFoundError, I as StepRecord, J as err, K as FlowErrorShape, L as StepRegistration, M as StepHandler, N as StepHandlerNotFoundError, O as StepCompensationContext, P as StepHandlerRegistry, R as StepStatus, S as defineWaitStep, T as RetryPolicy, U as WorkflowRecord, V as WorkflowId, W as WorkflowStatus, Y as ok, _ as buildWorkflow, a as STEP_DISPLAY_STATUS, b as defineStep, c as WORKFLOW_STATUS_SCHEMA, d as toPublicWorkflow, f as StepOutput, g as WorkflowOutput, h as TypedWorkflow, i as PublicWorkflowStep, j as StepExecutionContext, k as StepDefinition, l as toDisplayStepStatus, m as TypedStepContext, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as STEP_DISPLAY_STATUS_SCHEMA, p as TypedStep, q as Result, r as PublicWorkflow, s as StepDisplayStatus, t as PUBLIC_WORKFLOW_SCHEMA, u as toPublicStep, v as defineMapStep, w as InvalidWorkflowDefinitionError, x as defineSubWorkflowStep, y as defineSleepStep, z as WorkflowCreatedResult } from "./index-D_fOYfmf.js";
+import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.js";
+import { C as CreateWorkflowStep, D as ListWorkflowsFilters, E as FinishWorkflowParams, O as WorkflowStore, S as CreateWorkflowParams, T as FailStepParams, _ as StepGateDecision, a as FlowTracer, b as AddChildStep, c as RecordingTracer, d as noopObserver, f as noopTracer, g as StepGate, h as RateRule, i as FlowSpan, l as createRecordingObserver, m as InMemoryStepGateConfig, n as FlowEventType, o as RecordedSpan, p as ConcurrencyRule, r as FlowObserver, s as RecordingObserver, t as FlowEvent, u as createRecordingTracer, v as StepGateRequest, w as CreatedWorkflow, x as CompleteStepParams, y as createInMemoryStepGate } from "./observability-BsrvbhDr.js";
+import { n as Dispatcher, r as EnqueueOptions, t as DispatchStepPayload } from "./dispatcher-BydjyrgU.js";
+import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-CDRFQZbT.js";
+//#region src/core/registry.d.ts
+/**
+ * Creates an in-memory step handler registry.
+ * Populate it at application startup (e.g. by registering every workflow's steps).
+ * Each registration carries the handler plus its optional retry/timeout policy.
+ */
+declare function createStepHandlerRegistry<TContext = unknown>(): StepHandlerRegistry<TContext>;
+//#endregion
+//#region src/core/retry.d.ts
+/**
+ * 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);
+ * ```
+ */
+declare function markRetryable<E>(error: E, retryable?: boolean): E;
+/** An error the engine will always retry (within the step's attempt budget). */
+declare function retryableError(message: string, options?: ErrorOptions): Error;
+/** An error the engine will never retry, whatever its message says. */
+declare function nonRetryableError(message: string, options?: ErrorOptions): Error;
+/**
+ * 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.
+ */
+declare function explicitRetryability(error: unknown): boolean | undefined;
+/**
+ * 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.
+ */
+declare function isRetryableError(error: unknown): boolean;
+//#endregion
+//#region src/core/engine.d.ts
+interface WorkflowEngineConfig {
+  /** The dispatcher's per-step expiry, in seconds. Used by the stuck-step sweeper. Default 600. */
+  stepExpirySeconds?: number;
+  /** Extra grace added to the stuck threshold beyond `stepExpirySeconds`. Default 300. */
+  stuckStepBufferSeconds?: number;
+  /**
+   * Retryability for failures nothing authoritative classified — i.e. where the
+   * default classifier fell back to guessing from the error's shape and message.
+   * Set `false` for strict mode: never guess, and treat an unmarked failure as
+   * permanent. Explicitly marked errors ({@link markRetryable}) and steps with
+   * their own `isRetryable` are unaffected, as are engine-generated failures like
+   * a step timeout.
+   *
+   * Leave unset to keep the default classifier's answer.
+   */
+  defaultRetryable?: boolean;
+}
+interface WorkflowEngineDeps<TContext = unknown> {
+  store: WorkflowStore;
+  dispatcher: Dispatcher;
+  registry: StepHandlerRegistry<TContext>;
+  /** Partition this engine instance is bound to (e.g. a tenant id). */
+  partitionKey: string;
+  logger?: Logger;
+  hooks?: WorkflowHooks<TContext>;
+  config?: WorkflowEngineConfig;
+  /**
+   * Optional admission gate (concurrency caps / rate limiting). Consulted before each
+   * step runs; a denied step is deferred (re-enqueued) without consuming an attempt.
+   */
+  gate?: StepGate;
+  /** Run-history / metrics sink. Receives a `FlowEvent` per transition. Default: no-op. */
+  observer?: FlowObserver;
+  /** Tracer: the engine wraps each `executeStep` in a span. Default: no-op. */
+  tracer?: FlowTracer;
+  /** Clock injection point for testability. Defaults to `() => new Date()`. */
+  now?: () => Date;
+}
+declare function createWorkflowEngine<TContext = unknown>(deps: WorkflowEngineDeps<TContext>): {
+  validateDefinition: (definition: WorkflowDefinition) => Result<void, FlowError>;
+  startWorkflow: (definition: WorkflowDefinition, input: Record<string, unknown>, options?: StartOptions) => Promise<Result<WorkflowCreatedResult, FlowError>>;
+  start: <TInput extends Record<string, unknown>>(workflow: {
+    inputSchema: {
+      parse(v: unknown): TInput;
+    };
+    definition: WorkflowDefinition;
+  }, input: TInput, options?: StartOptions) => Promise<Result<WorkflowCreatedResult, FlowError>>;
+  executeStep: (workflowId: WorkflowId, stepId: StepId) => Promise<Result<void, FlowError>>;
+  resumeStep: (workflowId: WorkflowId, stepKey: string, payload?: Record<string, unknown>) => Promise<Result<void, FlowError>>;
+  handleStepExhausted: (workflowId: WorkflowId, stepId: StepId, errorMessage: string) => Promise<void>;
+  recoverStuckWorkflows: () => Promise<{
+    recoveredSteps: number;
+    recoveredWorkflows: number;
+  }>;
+  cancelWorkflow: (workflowId: WorkflowId) => Promise<Result<void, FlowError>>;
+  getWorkflowStatus: (workflowId: WorkflowId) => Promise<Result<WorkflowWithSteps, FlowError>>;
+  listWorkflows: (filters?: {
+    status?: WorkflowStatus;
+    type?: string;
+    entityRef?: string;
+    limit?: number;
+  }) => Promise<Result<WorkflowWithSteps[], FlowError>>;
+};
+type WorkflowEngine<TContext = unknown> = ReturnType<typeof createWorkflowEngine<TContext>>;
+//#endregion
+//#region src/core/in-memory-store.d.ts
+/**
+ * Reference `WorkflowStore` backed by plain Maps. Intended for tests and single-
+ * process experimentation — NOT durable. Partition-scoped at construction to
+ * mirror real adapters (the partition value is recorded but isolation is trivial
+ * since each instance owns its own maps).
+ */
+declare function createInMemoryWorkflowStore(partitionKey?: string): WorkflowStore & {
+  /** Test helper: read everything currently stored. */
+  _dump(): {
+    workflows: WorkflowRecord[];
+    steps: StepRecord[];
+  };
+};
+//#endregion
+export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PublicWorkflow, PublicWorkflowStep, RateRule, RecordedSpan, RecordingObserver, RecordingTracer, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepDefinition, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowEngine, WorkflowEngineConfig, WorkflowEngineDeps, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStore, WorkflowWithSteps, buildWorkflow, createInMemoryStepGate, createInMemoryWorkflowStore, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };