@gravito/flux 3.0.1 → 3.0.2

package/dist/index.d.cts

@@ -1,16 +1,255 @@
-import { W as WorkflowDefinition, F as FluxWaitResult } from './types-CZwYGpou.cjs';
-export { a as FluxConfig, b as FluxLogger, c as FluxResult, d as FluxTraceEvent, e as FluxTraceEventType, f as FluxTraceSink, S as StepDefinition, g as StepDescriptor, h as StepExecution, i as StepResult, j as WorkflowContext, k as WorkflowDescriptor, l as WorkflowFilter, m as WorkflowState, n as WorkflowStatus, o as WorkflowStorage } from './types-CZwYGpou.cjs';
+import { C as CronScheduleOptions, W as WorkflowDefinition, a as WorkflowState, F as FluxWaitResult } from './types-CRz5XdLd.cjs';
+export { b as FluxConfig, c as FluxLogger, d as FluxResult, e as FluxTraceEvent, f as FluxTraceEventType, g as FluxTraceSink, L as Lock, h as LockProvider, M as MemoryLockProvider, S as StepDefinition, i as StepDescriptor, j as StepExecution, k as StepResult, l as WorkflowContext, m as WorkflowDescriptor, n as WorkflowFilter, o as WorkflowStatus, p as WorkflowStorage } from './types-CRz5XdLd.cjs';
 import { FluxEngine } from './index.node.cjs';
-export { ContextManager, FluxConsoleLogger, FluxSilentLogger, JsonFileTraceSink, MemoryStorage, OrbitFlux, OrbitFluxOptions, StateMachine, StepExecutor, WorkflowBuilder, createWorkflow } from './index.node.cjs';
+export { BatchExecutionOptions, BatchExecutor, BatchItemResult, BatchResult, ContextManager, FluxConsoleLogger, FluxSilentLogger, JsonFileTraceSink, MemoryStorage, OrbitFlux, OrbitFluxOptions, PostgreSQLStorage, PostgreSQLStorageOptions, RedisClient, RedisLockProvider, RedisLockProviderOptions, StateMachine, StepExecutor, WorkflowBuilder, createWorkflow } from './index.node.cjs';
 export { BunSQLiteStorage, BunSQLiteStorageOptions } from './bun.cjs';
 import '@gravito/core';
 import 'bun:sqlite';
 
+/**
+ * Standard error codes for FluxEngine operations.
+ *
+ * Used to programmatically identify the cause of a `FluxError`.
+ */
+declare enum FluxErrorCode {
+    /** The requested workflow instance could not be found in storage. */
+    WORKFLOW_NOT_FOUND = "WORKFLOW_NOT_FOUND",
+    /** The input data provided to the workflow failed validation. */
+    WORKFLOW_INVALID_INPUT = "WORKFLOW_INVALID_INPUT",
+    /** The workflow definition has changed since the instance was created, making it unsafe to resume. */
+    WORKFLOW_DEFINITION_CHANGED = "WORKFLOW_DEFINITION_CHANGED",
+    /** The workflow name in the definition does not match the stored state. */
+    WORKFLOW_NAME_MISMATCH = "WORKFLOW_NAME_MISMATCH",
+    /** An attempt was made to transition the workflow to an incompatible state. */
+    INVALID_STATE_TRANSITION = "INVALID_STATE_TRANSITION",
+    /** An operation requiring a suspended state was attempted on a workflow that is not suspended. */
+    WORKFLOW_NOT_SUSPENDED = "WORKFLOW_NOT_SUSPENDED",
+    /** The requested step index is out of bounds for the current workflow definition. */
+    INVALID_STEP_INDEX = "INVALID_STEP_INDEX",
+    /** A workflow step exceeded its configured execution time limit. */
+    STEP_TIMEOUT = "STEP_TIMEOUT",
+    /** The requested step could not be found in the workflow definition. */
+    STEP_NOT_FOUND = "STEP_NOT_FOUND",
+    /** Multiple concurrent attempts to modify the same workflow instance were detected. */
+    CONCURRENT_MODIFICATION = "CONCURRENT_MODIFICATION",
+    /** A workflow definition must contain at least one step to be executable. */
+    EMPTY_WORKFLOW = "EMPTY_WORKFLOW",
+    /** No recovery action is registered for a step that requires recovery. */
+    NO_RECOVERY_ACTION = "NO_RECOVERY_ACTION",
+    /** An invalid JSON Pointer was provided for state manipulation. */
+    INVALID_JSON_POINTER = "INVALID_JSON_POINTER",
+    /** Cannot access a property on a non-object value in the state tree. */
+    INVALID_PATH_TRAVERSAL = "INVALID_PATH_TRAVERSAL",
+    /** Cannot replace the root object of the workflow state. */
+    CANNOT_REPLACE_ROOT = "CANNOT_REPLACE_ROOT",
+    /** Cannot remove the root object of the workflow state. */
+    CANNOT_REMOVE_ROOT = "CANNOT_REMOVE_ROOT"
+}
+/**
+ * Base class for all errors thrown by the FluxEngine.
+ *
+ * Includes a machine-readable error code and optional context for debugging.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await engine.execute(flow, input);
+ * } catch (err) {
+ *   if (err instanceof FluxError && err.code === FluxErrorCode.STEP_TIMEOUT) {
+ *     console.error('Workflow timed out');
+ *   }
+ * }
+ * ```
+ */
+declare class FluxError extends Error {
+    readonly code: FluxErrorCode;
+    readonly context?: Record<string, unknown> | undefined;
+    /**
+     * Creates a new FluxError.
+     *
+     * @param message - Human-readable error description.
+     * @param code - Machine-readable error code.
+     * @param context - Additional metadata related to the error.
+     */
+    constructor(message: string, code: FluxErrorCode, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Creates a FluxError for a missing workflow instance.
+ *
+ * @param id - The unique identifier of the missing workflow.
+ * @returns A FluxError with the WORKFLOW_NOT_FOUND code.
+ *
+ * @example
+ * ```typescript
+ * throw workflowNotFound('wf-123');
+ * ```
+ */
+declare function workflowNotFound(id: string): FluxError;
+/**
+ * Creates a FluxError for an illegal state transition.
+ *
+ * @param from - The current state of the workflow.
+ * @param to - The attempted target state.
+ * @returns A FluxError with the INVALID_STATE_TRANSITION code.
+ *
+ * @example
+ * ```typescript
+ * throw invalidStateTransition('completed', 'running');
+ * ```
+ */
+declare function invalidStateTransition(from: string, to: string): FluxError;
+/**
+ * Creates a FluxError for invalid workflow input.
+ *
+ * @param workflowName - The name of the workflow definition.
+ * @returns A FluxError with the WORKFLOW_INVALID_INPUT code.
+ *
+ * @example
+ * ```typescript
+ * throw invalidInput('order-process');
+ * ```
+ */
+declare function invalidInput(workflowName: string): FluxError;
+/**
+ * Creates a FluxError for a workflow name mismatch.
+ *
+ * @param expected - The name expected by the definition.
+ * @param received - The name found in the stored state.
+ * @returns A FluxError with the WORKFLOW_NAME_MISMATCH code.
+ */
+declare function workflowNameMismatch(expected: string, received: string): FluxError;
+/**
+ * Creates a FluxError when a workflow definition has changed incompatibly.
+ *
+ * @returns A FluxError with the WORKFLOW_DEFINITION_CHANGED code.
+ */
+declare function workflowDefinitionChanged(): FluxError;
+/**
+ * Creates a FluxError when an operation requires a suspended workflow.
+ *
+ * @param status - The current status of the workflow.
+ * @returns A FluxError with the WORKFLOW_NOT_SUSPENDED code.
+ */
+declare function workflowNotSuspended(status: string): FluxError;
+/**
+ * Creates a FluxError when a specific step cannot be found.
+ *
+ * @param step - The name or index of the missing step.
+ * @returns A FluxError with the STEP_NOT_FOUND code.
+ */
+declare function stepNotFound(step: string | number): FluxError;
+/**
+ * Creates a FluxError for an out-of-bounds step index.
+ *
+ * @param index - The invalid step index.
+ * @returns A FluxError with the INVALID_STEP_INDEX code.
+ */
+declare function invalidStepIndex(index: number): FluxError;
+/**
+ * Creates a FluxError for an empty workflow (no steps defined).
+ *
+ * @param workflowName - The name of the workflow.
+ * @returns A FluxError with the EMPTY_WORKFLOW code.
+ */
+declare function emptyWorkflow(workflowName: string): FluxError;
+/**
+ * Creates a FluxError when no recovery action is registered for a step.
+ *
+ * @param stepName - The name of the step requiring recovery.
+ * @returns A FluxError with the NO_RECOVERY_ACTION code.
+ */
+declare function noRecoveryAction(stepName: string): FluxError;
+/**
+ * Creates a FluxError for invalid JSON Pointer syntax.
+ *
+ * @param path - The invalid JSON Pointer.
+ * @returns A FluxError with the INVALID_JSON_POINTER code.
+ */
+declare function invalidJsonPointer(path: string): FluxError;
+/**
+ * Creates a FluxError when attempting to traverse a non-object value.
+ *
+ * @param segment - The property being accessed.
+ * @param current - The current value type.
+ * @returns A FluxError with the INVALID_PATH_TRAVERSAL code.
+ */
+declare function invalidPathTraversal(segment: string, current: unknown): FluxError;
+/**
+ * Creates a FluxError when attempting to replace the root object.
+ *
+ * @returns A FluxError with the CANNOT_REPLACE_ROOT code.
+ */
+declare function cannotReplaceRoot(): FluxError;
+/**
+ * Creates a FluxError when attempting to remove the root object.
+ *
+ * @returns A FluxError with the CANNOT_REMOVE_ROOT code.
+ */
+declare function cannotRemoveRoot(): FluxError;
+
+/**
+ * Built-in scheduler for Flux workflows.
+ *
+ * Manages multiple cron-based schedules and triggers workflow execution
+ * at the specified intervals.
+ */
+declare class CronTrigger {
+    private engine;
+    private schedules;
+    private timers;
+    private running;
+    /**
+     * Creates a new CronTrigger instance.
+     *
+     * @param engine - The Flux engine to use for executing scheduled workflows.
+     */
+    constructor(engine: FluxEngine);
+    /**
+     * Starts the scheduler.
+     */
+    start(): void;
+    /**
+     * Stops the scheduler and clears all timers.
+     */
+    stop(): void;
+    /**
+     * Adds a new schedule or updates an existing one.
+     *
+     * @param options - The schedule configuration.
+     */
+    addSchedule(options: CronScheduleOptions): void;
+    /**
+     * Removes a schedule.
+     *
+     * @param id - The ID of the schedule to remove.
+     */
+    removeSchedule(id: string): void;
+    /**
+     * Refreshes all active schedules.
+     * @private
+     */
+    private refreshAll;
+    /**
+     * Calculates the next execution time and sets a timer for a specific schedule.
+     *
+     * @param id - The ID of the schedule to refresh.
+     * @private
+     */
+    private refreshSchedule;
+    /**
+     * Lists all registered schedules.
+     * @returns An array of schedule configurations.
+     */
+    listSchedules(): CronScheduleOptions[];
+}
+
 /**
  * Performance metrics captured during a workflow profiling session.
  *
+ * Used to quantify the resource footprint of a workflow execution, enabling
+ * data-driven decisions for infrastructure scaling and concurrency tuning.
+ *
  * @public
- * @since 3.0.0
  */
 interface ProfileMetrics {
     /** Total wall-clock duration of the workflow execution in milliseconds. */
@@ -27,8 +266,10 @@ interface ProfileMetrics {
 /**
  * Concurrency recommendations generated by the profiler.
  *
+ * Provides actionable insights into how many instances of a workflow can safely
+ * and efficiently run in parallel on the current hardware.
+ *
  * @public
- * @since 3.0.0
  */
 interface ProfileRecommendation {
     /** The identified primary bottleneck type. */
@@ -53,21 +294,51 @@ interface ProfileRecommendation {
  * const profiler = new WorkflowProfiler();
  * const metrics = await profiler.profile(myWorkflow, { input: 'data' });
  * const advice = profiler.recommend(metrics);
- * console.log(advice.suggestedConcurrency);
+ * console.log(`Suggested concurrency: ${advice.suggestedConcurrency}`);
  * ```
  *
  * @public
- * @since 3.0.0
  */
 declare class WorkflowProfiler {
     private engine?;
+    /**
+     * Initializes the profiler with an optional engine.
+     *
+     * @param engine - The FluxEngine instance to use for execution. If omitted, a silent engine is created.
+     */
     constructor(engine?: FluxEngine | undefined);
     /**
-     * Run a profile session for a specific workflow
+     * Executes a workflow and captures its resource consumption metrics.
+     *
+     * Performs a warmup run to ensure JIT optimization before measurement.
+     *
+     * @param workflow - The workflow definition to profile.
+     * @param input - The input data for the workflow execution.
+     * @returns A promise resolving to the captured performance metrics.
+     *
+     * @example
+     * ```typescript
+     * const metrics = await profiler.profile(orderWorkflow, { id: '123' });
+     * console.log(`Duration: ${metrics.durationMs}ms`);
+     * ```
      */
     profile<TInput>(workflow: WorkflowDefinition<TInput, any>, input: TInput): Promise<ProfileMetrics>;
     /**
-     * Generate recommendations based on metrics and current environment
+     * Analyzes metrics to generate concurrency recommendations.
+     *
+     * Considers system CPU cores and total memory to calculate safe and efficient limits.
+     *
+     * @param metrics - The metrics captured during a profiling session.
+     * @param config - Optional current configuration to check against recommendations.
+     * @returns A recommendation object containing bottleneck analysis and concurrency limits.
+     *
+     * @example
+     * ```typescript
+     * const advice = profiler.recommend(metrics, { configuredConcurrency: 10 });
+     * if (advice.type === 'CPU_BOUND') {
+     *   console.warn('Workflow is CPU bound, consider reducing concurrency');
+     * }
+     * ```
      */
     recommend(metrics: ProfileMetrics, config?: {
         configuredConcurrency?: number;
@@ -75,15 +346,100 @@ declare class WorkflowProfiler {
 }
 
 /**
- * Flux helper utilities
+ * Options for customizing Mermaid diagram generation.
+ */
+interface MermaidOptions {
+    /** Include detailed step information (retries, timeout, conditions). */
+    showDetails?: boolean;
+    /** Include execution history with status colors. */
+    showStatus?: boolean;
+    /** Render parallel groups visually. */
+    showParallelGroups?: boolean;
+    /** Theme: 'default' | 'dark' | 'forest' | 'neutral'. */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+}
+/**
+ * Generates Mermaid flowchart diagrams from workflow definitions and execution states.
+ *
+ * **Features**:
+ * - Workflow structure visualization (steps, parallel groups, conditions)
+ * - Execution status overlay (completed, failed, compensated)
+ * - Detailed metadata (retries, timeout, commit markers)
+ *
+ * **Use Cases**:
+ * - Documentation generation
+ * - Debugging workflow execution
+ * - Visual workflow design validation
+ */
+declare class MermaidGenerator {
+    /**
+     * Generates a Mermaid flowchart from a workflow definition.
+     *
+     * @param definition - The workflow definition to visualize
+     * @param options - Customization options
+     * @returns Mermaid diagram syntax as a string
+     *
+     * @example
+     * ```typescript
+     * const generator = new MermaidGenerator()
+     * const diagram = generator.generateFromDefinition(workflow, {
+     *   showDetails: true,
+     *   showParallelGroups: true
+     * })
+     * console.log(diagram)
+     * ```
+     */
+    generateFromDefinition<TInput, TData>(definition: WorkflowDefinition<TInput, TData>, options?: MermaidOptions): string;
+    /**
+     * Generates a Mermaid flowchart from a workflow execution state.
+     * Overlays execution status (completed, failed, compensated) on top of the structure.
+     *
+     * @param definition - The workflow definition
+     * @param state - The current execution state
+     * @param options - Customization options
+     * @returns Mermaid diagram syntax with status overlay
+     *
+     * @example
+     * ```typescript
+     * const diagram = generator.generateFromState(workflow, executionState, {
+     *   showStatus: true,
+     *   showDetails: true
+     * })
+     * ```
+     */
+    generateFromState<TInput, TData>(definition: WorkflowDefinition<TInput, TData>, state: WorkflowState<TInput, TData>, options?: MermaidOptions): string;
+    private sanitizeNodeId;
+    private buildStepLabel;
+    private buildStepLabelWithStatus;
+    private getStatusClass;
+    private getWorkflowFinalStatus;
+    private getNextNodeId;
+}
+
+/**
+ * Flux helper utilities for workflow control flow.
+ *
+ * Provides methods to interact with the workflow engine's special behaviors,
+ * such as suspending execution to wait for external signals.
  */
 declare const Flux: {
     /**
-     * Suspend workflow execution and wait for a signal
+     * Suspends workflow execution until a specific signal is received.
+     *
+     * When a handler returns this result, the engine saves the current state
+     * and stops execution. The workflow can be resumed later using `engine.signal()`.
+     *
+     * @param signal - The unique identifier for the signal to wait for.
+     * @returns A special result object that instructs the engine to suspend.
      *
-     * @param signal - Signal name to wait for
+     * @example
+     * ```typescript
+     * .step('wait-for-approval', async (ctx) => {
+     *   return Flux.wait('manager-approval');
+     * })
+     * ```
      */
     wait: (signal: string) => FluxWaitResult;
 };
 
-export { Flux, FluxEngine, FluxWaitResult, type ProfileMetrics, type ProfileRecommendation, WorkflowDefinition, WorkflowProfiler };
+export { CronScheduleOptions, CronTrigger, Flux, FluxEngine, FluxError, FluxErrorCode, FluxWaitResult, MermaidGenerator, type MermaidOptions, type ProfileMetrics, type ProfileRecommendation, WorkflowDefinition, WorkflowProfiler, WorkflowState, cannotRemoveRoot, cannotReplaceRoot, emptyWorkflow, invalidInput, invalidJsonPointer, invalidPathTraversal, invalidStateTransition, invalidStepIndex, noRecoveryAction, stepNotFound, workflowDefinitionChanged, workflowNameMismatch, workflowNotFound, workflowNotSuspended };