@gravito/flux 3.0.1 → 3.0.2

package/dist/index.d.ts

@@ -1,16 +1,255 @@
-import { W as WorkflowDefinition, F as FluxWaitResult } from './types-CZwYGpou.js';
-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.js';
+import { C as CronScheduleOptions, W as WorkflowDefinition, a as WorkflowState, F as FluxWaitResult } from './types-CRz5XdLd.js';
+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.js';
 import { FluxEngine } from './index.node.js';
-export { ContextManager, FluxConsoleLogger, FluxSilentLogger, JsonFileTraceSink, MemoryStorage, OrbitFlux, OrbitFluxOptions, StateMachine, StepExecutor, WorkflowBuilder, createWorkflow } from './index.node.js';
+export { BatchExecutionOptions, BatchExecutor, BatchItemResult, BatchResult, ContextManager, FluxConsoleLogger, FluxSilentLogger, JsonFileTraceSink, MemoryStorage, OrbitFlux, OrbitFluxOptions, PostgreSQLStorage, PostgreSQLStorageOptions, RedisClient, RedisLockProvider, RedisLockProviderOptions, StateMachine, StepExecutor, WorkflowBuilder, createWorkflow } from './index.node.js';
 export { BunSQLiteStorage, BunSQLiteStorageOptions } from './bun.js';
 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 };

package/dist/index.js

@@ -1,23 +1,52 @@
 import {
+  BatchExecutor,
   ContextManager,
+  CronTrigger,
   FluxConsoleLogger,
   FluxEngine,
+  FluxError,
+  FluxErrorCode,
   FluxSilentLogger,
   JsonFileTraceSink,
+  MemoryLockProvider,
   MemoryStorage,
   OrbitFlux,
+  PostgreSQLStorage,
+  RedisLockProvider,
   StateMachine,
   StepExecutor,
   WorkflowBuilder,
-  createWorkflow
-} from "./chunk-3JGQYHUN.js";
+  cannotRemoveRoot,
+  cannotReplaceRoot,
+  createWorkflow,
+  emptyWorkflow,
+  invalidInput,
+  invalidJsonPointer,
+  invalidPathTraversal,
+  invalidStateTransition,
+  invalidStepIndex,
+  noRecoveryAction,
+  stepNotFound,
+  workflowDefinitionChanged,
+  workflowNameMismatch,
+  workflowNotFound,
+  workflowNotSuspended
+} from "./chunk-4DXCQ6CL.js";
 import {
   BunSQLiteStorage
-} from "./chunk-ZAMVC732.js";
+} from "./chunk-NAIVO7RR.js";
+import {
+  MermaidGenerator
+} from "./chunk-WGDTB6OC.js";
 
 // src/profiler/WorkflowProfiler.ts
 import * as os from "os";
 var WorkflowProfiler = class {
+  /**
+   * 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) {
     this.engine = engine;
     if (!this.engine) {
@@ -27,7 +56,19 @@ var WorkflowProfiler = class {
     }
   }
   /**
-   * 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`);
+   * ```
    */
   async profile(workflow, input) {
     try {
@@ -60,7 +101,21 @@ var WorkflowProfiler = class {
     };
   }
   /**
-   * 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, config) {
     const totalMem = os.totalmem();
@@ -107,9 +162,20 @@ var WorkflowProfiler = class {
 // src/index.ts
 var 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) => ({
     __kind: "flux_wait",
@@ -117,19 +183,41 @@ var Flux = {
   })
 };
 export {
+  BatchExecutor,
   BunSQLiteStorage,
   ContextManager,
+  CronTrigger,
   Flux,
   FluxConsoleLogger,
   FluxEngine,
+  FluxError,
+  FluxErrorCode,
   FluxSilentLogger,
   JsonFileTraceSink,
+  MemoryLockProvider,
   MemoryStorage,
+  MermaidGenerator,
   OrbitFlux,
+  PostgreSQLStorage,
+  RedisLockProvider,
   StateMachine,
   StepExecutor,
   WorkflowBuilder,
   WorkflowProfiler,
-  createWorkflow
+  cannotRemoveRoot,
+  cannotReplaceRoot,
+  createWorkflow,
+  emptyWorkflow,
+  invalidInput,
+  invalidJsonPointer,
+  invalidPathTraversal,
+  invalidStateTransition,
+  invalidStepIndex,
+  noRecoveryAction,
+  stepNotFound,
+  workflowDefinitionChanged,
+  workflowNameMismatch,
+  workflowNotFound,
+  workflowNotSuspended
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/profiler/WorkflowProfiler.ts","../src/index.ts"],"sourcesContent":["import * as os from 'node:os'\nimport { FluxEngine } from '../engine/FluxEngine'\nimport { FluxSilentLogger } from '../logger/FluxLogger'\nimport type { WorkflowDefinition } from '../types'\n\n/**\n * Performance metrics captured during a workflow profiling session.\n *\n * @public\n * @since 3.0.0\n */\nexport interface ProfileMetrics {\n  /** Total wall-clock duration of the workflow execution in milliseconds. */\n  durationMs: number\n  /** Amount of time spent in user-space CPU operations in milliseconds. */\n  cpuUserMs: number\n  /** Amount of time spent in system-space CPU operations in milliseconds. */\n  cpuSysMs: number\n  /** Estimated heap memory increase during execution in bytes. */\n  memDeltaBytes: number\n  /** Ratio of CPU time to wall-clock time (0.0 to 1.0+). Higher values indicate CPU-bound tasks. */\n  cpuRatio: number\n}\n\n/**\n * Concurrency recommendations generated by the profiler.\n *\n * @public\n * @since 3.0.0\n */\nexport interface ProfileRecommendation {\n  /** The identified primary bottleneck type. */\n  type: 'IO_BOUND' | 'CPU_BOUND' | 'MEMORY_BOUND'\n  /** Maximum safe concurrency considering memory and system stability. */\n  safeConcurrency: number\n  /** Most efficient concurrency level considering CPU utilization. */\n  efficientConcurrency: number\n  /** A suggested range for worker concurrency configuration. */\n  suggestedConcurrency: string\n  /** Detailed explanation for the recommendation. */\n  reason: string\n}\n\n/**\n * WorkflowProfiler analyzes workflow performance characteristics.\n *\n * It measures CPU usage, memory consumption, and execution duration to recommend\n * optimal concurrency settings for Gravito Quasar workers or high-throughput consumers.\n *\n * @example\n * ```typescript\n * const profiler = new WorkflowProfiler();\n * const metrics = await profiler.profile(myWorkflow, { input: 'data' });\n * const advice = profiler.recommend(metrics);\n * console.log(advice.suggestedConcurrency);\n * ```\n *\n * @public\n * @since 3.0.0\n */\nexport class WorkflowProfiler {\n  constructor(private engine?: FluxEngine) {\n    if (!this.engine) {\n      // Default minimal engine for profiling (Silent)\n      this.engine = new FluxEngine({\n        logger: new FluxSilentLogger(),\n      })\n    }\n  }\n\n  /**\n   * Run a profile session for a specific workflow\n   */\n  async profile<TInput>(\n    workflow: WorkflowDefinition<TInput, any>,\n    input: TInput\n  ): Promise<ProfileMetrics> {\n    // 1. Warmup (JIT)\n    try {\n      await this.engine?.execute(workflow, input)\n    } catch {}\n\n    // 2. Measure\n    if (global.gc) {\n      global.gc()\n    }\n\n    const startCpu = process.cpuUsage()\n    const startMem = process.memoryUsage().heapUsed\n    const startTime = process.hrtime.bigint()\n\n    await this.engine?.execute(workflow, input)\n\n    const endTime = process.hrtime.bigint()\n    const endCpu = process.cpuUsage(startCpu)\n    const endMem = process.memoryUsage().heapUsed\n\n    // 3. Calculate\n    const durationNs = Number(endTime - startTime)\n    const durationMs = durationNs / 1_000_000\n    const cpuUserMs = endCpu.user / 1000\n    const cpuSysMs = endCpu.system / 1000\n    const totalCpuMs = cpuUserMs + cpuSysMs\n    const memDeltaBytes = Math.max(0, endMem - startMem) // Clamp to 0\n\n    // CPU Ratio: How much % of the time was spent on CPU vs Waiting\n    const cpuRatio = totalCpuMs / durationMs\n\n    return {\n      durationMs,\n      cpuUserMs,\n      cpuSysMs,\n      memDeltaBytes,\n      cpuRatio,\n    }\n  }\n\n  /**\n   * Generate recommendations based on metrics and current environment\n   */\n  recommend(\n    metrics: ProfileMetrics,\n    config?: { configuredConcurrency?: number }\n  ): ProfileRecommendation {\n    const totalMem = os.totalmem()\n    const cpus = os.cpus().length\n\n    // 1. Analyze Bottleneck Type\n    let type: ProfileRecommendation['type'] = 'IO_BOUND'\n    if (metrics.cpuRatio > 0.5) {\n      type = 'CPU_BOUND'\n    } else if (metrics.memDeltaBytes > 50 * 1024 * 1024) {\n      // > 50MB per run\n      type = 'MEMORY_BOUND'\n    }\n\n    // 2. Calculate Limits\n\n    // Memory Limit: Keep 30% buffer for system, divide rest by per-workflow memory\n    const safeMem = totalMem * 0.7\n    // Use at least 1MB as baseline to avoid division by zero or huge numbers\n    const perInstanceMem = Math.max(metrics.memDeltaBytes, 1024 * 1024)\n    const maxMemConcurrency = Math.floor(safeMem / perInstanceMem)\n\n    // CPU Limit:\n    // If IO Bound (0.2% cpu), we can run many. 100% / 0.2% = 500 tasks per core.\n    // We cap efficiency at a reasonable number to avoid Event Loop Lag density.\n    const cpuEfficiencyFactor = 1 / Math.max(metrics.cpuRatio, 0.001) // Avoid div by 0\n    const maxCpuConcurrency = Math.floor(cpus * cpuEfficiencyFactor)\n\n    // 3. Synthesize Recommendation\n    const safe = Math.min(maxMemConcurrency, 200) // Hard cap at 200 for sanity\n    let efficient = Math.min(maxCpuConcurrency, 200)\n\n    // If CPU bound, strict limit based on cores\n    if (type === 'CPU_BOUND') {\n      efficient = cpus // 1:1 mapping is best for CPU bound\n    }\n\n    const recommended = Math.min(safe, efficient)\n\n    let reason = ''\n    if (type === 'IO_BOUND') {\n      reason = `Workflow is I/O intensive (CPU usage ${(metrics.cpuRatio * 100).toFixed(1)}%). It is safe to run high concurrency up to ${recommended}.`\n    } else if (type === 'CPU_BOUND') {\n      reason = `Workflow is CPU intensive. Limiting concurrency to match CPU cores (${cpus}) is recommended to prevent blocking.`\n    } else {\n      reason = `Workflow consumes significant memory (${(metrics.memDeltaBytes / 1024 / 1024).toFixed(1)}MB). Concurrency limited by available RAM.`\n    }\n\n    if (config?.configuredConcurrency && config.configuredConcurrency > recommended) {\n      reason += ` \\n⚠️ Warning: Your current setting (${config.configuredConcurrency}) exceeds the recommended limit (${recommended}).`\n    }\n\n    return {\n      type,\n      safeConcurrency: safe,\n      efficientConcurrency: efficient,\n      suggestedConcurrency: `${Math.max(1, Math.floor(recommended * 0.5))} - ${recommended}`,\n      reason,\n    }\n  }\n}\n","/**\n * @fileoverview @gravito/flux - Platform-agnostic Workflow Engine\n *\n * High-performance, type-safe workflow engine with Bun optimizations.\n *\n * @example Basic Usage\n * ```typescript\n * import { FluxEngine, createWorkflow } from '@gravito/flux'\n *\n * const workflow = createWorkflow('order-process')\n *   .input<{ orderId: string }>()\n *   .step('validate', async (ctx) => {\n *     ctx.data.order = await fetchOrder(ctx.input.orderId)\n *   })\n *   .step('process', async (ctx) => {\n *     await processPayment(ctx.data.order)\n *   })\n *   .commit('notify', async (ctx) => {\n *     await sendEmail(ctx.data.order.email)\n *   })\n *\n * const engine = new FluxEngine()\n * const result = await engine.execute(workflow, { orderId: '123' })\n * ```\n *\n * @module @gravito/flux\n */\n\n// Builder\nexport { createWorkflow, WorkflowBuilder } from './builder/WorkflowBuilder'\nexport { ContextManager } from './core/ContextManager'\n// Core (for advanced usage)\nexport { StateMachine } from './core/StateMachine'\nexport { StepExecutor } from './core/StepExecutor'\n// Core\nexport { FluxEngine } from './engine/FluxEngine'\n// Logger\nexport { FluxConsoleLogger, FluxSilentLogger } from './logger/FluxLogger'\n// Gravito Integration\nexport { OrbitFlux, type OrbitFluxOptions } from './orbit/OrbitFlux'\n// Profiler\nexport {\n  type ProfileMetrics,\n  type ProfileRecommendation,\n  WorkflowProfiler,\n} from './profiler/WorkflowProfiler'\nexport { BunSQLiteStorage, type BunSQLiteStorageOptions } from './storage/BunSQLiteStorage'\n// Storage\nexport { MemoryStorage } from './storage/MemoryStorage'\n// Trace\nexport { JsonFileTraceSink } from './trace/JsonFileTraceSink'\n\n// Types\nexport type {\n  // Config\n  FluxConfig,\n  // Logger\n  FluxLogger,\n  FluxResult,\n  // Trace\n  FluxTraceEvent,\n  FluxTraceEventType,\n  FluxTraceSink,\n  // Helper\n  FluxWaitResult,\n  // Step types\n  StepDefinition,\n  StepDescriptor,\n  StepExecution,\n  StepResult,\n  WorkflowContext,\n  WorkflowDefinition,\n  WorkflowDescriptor,\n  WorkflowFilter,\n  WorkflowState,\n  // Core types\n  WorkflowStatus,\n  // Storage\n  WorkflowStorage,\n} from './types'\n\n/**\n * Flux helper utilities\n */\nexport const Flux = {\n  /**\n   * Suspend workflow execution and wait for a signal\n   *\n   * @param signal - Signal name to wait for\n   */\n  wait: (signal: string): import('./types').FluxWaitResult => ({\n    __kind: 'flux_wait',\n    signal,\n  }),\n}\n"],"mappings":"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","names":["cpus"]}
+{"version":3,"sources":["../src/profiler/WorkflowProfiler.ts","../src/index.ts"],"sourcesContent":["import * as os from 'node:os'\nimport { FluxEngine } from '../engine/FluxEngine'\nimport { FluxSilentLogger } from '../logger/FluxLogger'\nimport type { WorkflowDefinition } from '../types'\n\n/**\n * Performance metrics captured during a workflow profiling session.\n *\n * Used to quantify the resource footprint of a workflow execution, enabling\n * data-driven decisions for infrastructure scaling and concurrency tuning.\n *\n * @public\n */\nexport interface ProfileMetrics {\n  /** Total wall-clock duration of the workflow execution in milliseconds. */\n  durationMs: number\n  /** Amount of time spent in user-space CPU operations in milliseconds. */\n  cpuUserMs: number\n  /** Amount of time spent in system-space CPU operations in milliseconds. */\n  cpuSysMs: number\n  /** Estimated heap memory increase during execution in bytes. */\n  memDeltaBytes: number\n  /** Ratio of CPU time to wall-clock time (0.0 to 1.0+). Higher values indicate CPU-bound tasks. */\n  cpuRatio: number\n}\n\n/**\n * Concurrency recommendations generated by the profiler.\n *\n * Provides actionable insights into how many instances of a workflow can safely\n * and efficiently run in parallel on the current hardware.\n *\n * @public\n */\nexport interface ProfileRecommendation {\n  /** The identified primary bottleneck type. */\n  type: 'IO_BOUND' | 'CPU_BOUND' | 'MEMORY_BOUND'\n  /** Maximum safe concurrency considering memory and system stability. */\n  safeConcurrency: number\n  /** Most efficient concurrency level considering CPU utilization. */\n  efficientConcurrency: number\n  /** A suggested range for worker concurrency configuration. */\n  suggestedConcurrency: string\n  /** Detailed explanation for the recommendation. */\n  reason: string\n}\n\n/**\n * WorkflowProfiler analyzes workflow performance characteristics.\n *\n * It measures CPU usage, memory consumption, and execution duration to recommend\n * optimal concurrency settings for Gravito Quasar workers or high-throughput consumers.\n *\n * @example\n * ```typescript\n * const profiler = new WorkflowProfiler();\n * const metrics = await profiler.profile(myWorkflow, { input: 'data' });\n * const advice = profiler.recommend(metrics);\n * console.log(`Suggested concurrency: ${advice.suggestedConcurrency}`);\n * ```\n *\n * @public\n */\nexport class WorkflowProfiler {\n  /**\n   * Initializes the profiler with an optional engine.\n   *\n   * @param engine - The FluxEngine instance to use for execution. If omitted, a silent engine is created.\n   */\n  constructor(private engine?: FluxEngine) {\n    if (!this.engine) {\n      // Default minimal engine for profiling (Silent)\n      this.engine = new FluxEngine({\n        logger: new FluxSilentLogger(),\n      })\n    }\n  }\n\n  /**\n   * Executes a workflow and captures its resource consumption metrics.\n   *\n   * Performs a warmup run to ensure JIT optimization before measurement.\n   *\n   * @param workflow - The workflow definition to profile.\n   * @param input - The input data for the workflow execution.\n   * @returns A promise resolving to the captured performance metrics.\n   *\n   * @example\n   * ```typescript\n   * const metrics = await profiler.profile(orderWorkflow, { id: '123' });\n   * console.log(`Duration: ${metrics.durationMs}ms`);\n   * ```\n   */\n  async profile<TInput>(\n    workflow: WorkflowDefinition<TInput, any>,\n    input: TInput\n  ): Promise<ProfileMetrics> {\n    // 1. Warmup (JIT)\n    try {\n      await this.engine?.execute(workflow, input)\n    } catch {}\n\n    // 2. Measure\n    if (global.gc) {\n      global.gc()\n    }\n\n    const startCpu = process.cpuUsage()\n    const startMem = process.memoryUsage().heapUsed\n    const startTime = process.hrtime.bigint()\n\n    await this.engine?.execute(workflow, input)\n\n    const endTime = process.hrtime.bigint()\n    const endCpu = process.cpuUsage(startCpu)\n    const endMem = process.memoryUsage().heapUsed\n\n    // 3. Calculate\n    const durationNs = Number(endTime - startTime)\n    const durationMs = durationNs / 1_000_000\n    const cpuUserMs = endCpu.user / 1000\n    const cpuSysMs = endCpu.system / 1000\n    const totalCpuMs = cpuUserMs + cpuSysMs\n    const memDeltaBytes = Math.max(0, endMem - startMem) // Clamp to 0\n\n    // CPU Ratio: How much % of the time was spent on CPU vs Waiting\n    const cpuRatio = totalCpuMs / durationMs\n\n    return {\n      durationMs,\n      cpuUserMs,\n      cpuSysMs,\n      memDeltaBytes,\n      cpuRatio,\n    }\n  }\n\n  /**\n   * Analyzes metrics to generate concurrency recommendations.\n   *\n   * Considers system CPU cores and total memory to calculate safe and efficient limits.\n   *\n   * @param metrics - The metrics captured during a profiling session.\n   * @param config - Optional current configuration to check against recommendations.\n   * @returns A recommendation object containing bottleneck analysis and concurrency limits.\n   *\n   * @example\n   * ```typescript\n   * const advice = profiler.recommend(metrics, { configuredConcurrency: 10 });\n   * if (advice.type === 'CPU_BOUND') {\n   *   console.warn('Workflow is CPU bound, consider reducing concurrency');\n   * }\n   * ```\n   */\n  recommend(\n    metrics: ProfileMetrics,\n    config?: { configuredConcurrency?: number }\n  ): ProfileRecommendation {\n    const totalMem = os.totalmem()\n    const cpus = os.cpus().length\n\n    // 1. Analyze Bottleneck Type\n    let type: ProfileRecommendation['type'] = 'IO_BOUND'\n    if (metrics.cpuRatio > 0.5) {\n      type = 'CPU_BOUND'\n    } else if (metrics.memDeltaBytes > 50 * 1024 * 1024) {\n      // > 50MB per run\n      type = 'MEMORY_BOUND'\n    }\n\n    // 2. Calculate Limits\n\n    // Memory Limit: Keep 30% buffer for system, divide rest by per-workflow memory\n    const safeMem = totalMem * 0.7\n    // Use at least 1MB as baseline to avoid division by zero or huge numbers\n    const perInstanceMem = Math.max(metrics.memDeltaBytes, 1024 * 1024)\n    const maxMemConcurrency = Math.floor(safeMem / perInstanceMem)\n\n    // CPU Limit:\n    // If IO Bound (0.2% cpu), we can run many. 100% / 0.2% = 500 tasks per core.\n    // We cap efficiency at a reasonable number to avoid Event Loop Lag density.\n    const cpuEfficiencyFactor = 1 / Math.max(metrics.cpuRatio, 0.001) // Avoid div by 0\n    const maxCpuConcurrency = Math.floor(cpus * cpuEfficiencyFactor)\n\n    // 3. Synthesize Recommendation\n    const safe = Math.min(maxMemConcurrency, 200) // Hard cap at 200 for sanity\n    let efficient = Math.min(maxCpuConcurrency, 200)\n\n    // If CPU bound, strict limit based on cores\n    if (type === 'CPU_BOUND') {\n      efficient = cpus // 1:1 mapping is best for CPU bound\n    }\n\n    const recommended = Math.min(safe, efficient)\n\n    let reason = ''\n    if (type === 'IO_BOUND') {\n      reason = `Workflow is I/O intensive (CPU usage ${(metrics.cpuRatio * 100).toFixed(1)}%). It is safe to run high concurrency up to ${recommended}.`\n    } else if (type === 'CPU_BOUND') {\n      reason = `Workflow is CPU intensive. Limiting concurrency to match CPU cores (${cpus}) is recommended to prevent blocking.`\n    } else {\n      reason = `Workflow consumes significant memory (${(metrics.memDeltaBytes / 1024 / 1024).toFixed(1)}MB). Concurrency limited by available RAM.`\n    }\n\n    if (config?.configuredConcurrency && config.configuredConcurrency > recommended) {\n      reason += ` \\n⚠️ Warning: Your current setting (${config.configuredConcurrency}) exceeds the recommended limit (${recommended}).`\n    }\n\n    return {\n      type,\n      safeConcurrency: safe,\n      efficientConcurrency: efficient,\n      suggestedConcurrency: `${Math.max(1, Math.floor(recommended * 0.5))} - ${recommended}`,\n      reason,\n    }\n  }\n}\n","/**\n * @fileoverview @gravito/flux - Platform-agnostic Workflow Engine\n *\n * High-performance, type-safe workflow engine with Bun optimizations.\n *\n * @example Basic Usage\n * ```typescript\n * import { FluxEngine, createWorkflow } from '@gravito/flux'\n *\n * const workflow = createWorkflow('order-process')\n *   .input<{ orderId: string }>()\n *   .step('validate', async (ctx) => {\n *     ctx.data.order = await fetchOrder(ctx.input.orderId)\n *   })\n *   .step('process', async (ctx) => {\n *     await processPayment(ctx.data.order)\n *   })\n *   .commit('notify', async (ctx) => {\n *     await sendEmail(ctx.data.order.email)\n *   })\n *\n * const engine = new FluxEngine()\n * const result = await engine.execute(workflow, { orderId: '123' })\n * ```\n *\n * @module @gravito/flux\n */\n\n// Builder\nexport { createWorkflow, WorkflowBuilder } from './builder/WorkflowBuilder'\nexport { ContextManager } from './core/ContextManager'\nexport { type Lock, type LockProvider, MemoryLockProvider } from './core/LockProvider'\nexport {\n  type RedisClient,\n  RedisLockProvider,\n  type RedisLockProviderOptions,\n} from './core/RedisLockProvider'\n// Core (for advanced usage)\nexport { StateMachine } from './core/StateMachine'\nexport { StepExecutor } from './core/StepExecutor'\nexport {\n  type BatchExecutionOptions,\n  BatchExecutor,\n  type BatchItemResult,\n  type BatchResult,\n} from './engine/BatchExecutor'\n// Core\nexport { FluxEngine } from './engine/FluxEngine'\n// Errors\nexport {\n  cannotRemoveRoot,\n  cannotReplaceRoot,\n  emptyWorkflow,\n  FluxError,\n  FluxErrorCode,\n  invalidInput,\n  invalidJsonPointer,\n  invalidPathTraversal,\n  invalidStateTransition,\n  invalidStepIndex,\n  noRecoveryAction,\n  stepNotFound,\n  workflowDefinitionChanged,\n  workflowNameMismatch,\n  workflowNotFound,\n  workflowNotSuspended,\n} from './errors'\n// Logger\nexport { FluxConsoleLogger, FluxSilentLogger } from './logger/FluxLogger'\nexport { CronTrigger } from './orbit/CronTrigger'\n// Gravito Integration\nexport { OrbitFlux, type OrbitFluxOptions } from './orbit/OrbitFlux'\n// Profiler\nexport {\n  type ProfileMetrics,\n  type ProfileRecommendation,\n  WorkflowProfiler,\n} from './profiler/WorkflowProfiler'\nexport { BunSQLiteStorage, type BunSQLiteStorageOptions } from './storage/BunSQLiteStorage'\n// Storage\nexport { MemoryStorage } from './storage/MemoryStorage'\nexport { PostgreSQLStorage, type PostgreSQLStorageOptions } from './storage/PostgreSQLStorage'\n// Trace\nexport { JsonFileTraceSink } from './trace/JsonFileTraceSink'\n// Types\nexport type {\n  CronScheduleOptions,\n  // Config\n  FluxConfig,\n  // Logger\n  FluxLogger,\n  FluxResult,\n  // Trace\n  FluxTraceEvent,\n  FluxTraceEventType,\n  FluxTraceSink,\n  // Helper\n  FluxWaitResult,\n  // Step types\n  StepDefinition,\n  StepDescriptor,\n  StepExecution,\n  StepResult,\n  WorkflowContext,\n  WorkflowDefinition,\n  WorkflowDescriptor,\n  WorkflowFilter,\n  WorkflowState,\n  // Core types\n  WorkflowStatus,\n  // Storage\n  WorkflowStorage,\n} from './types'\n// Visualization\nexport { MermaidGenerator, type MermaidOptions } from './visualization/MermaidGenerator'\n\n/**\n * Flux helper utilities for workflow control flow.\n *\n * Provides methods to interact with the workflow engine's special behaviors,\n * such as suspending execution to wait for external signals.\n */\nexport const Flux = {\n  /**\n   * Suspends workflow execution until a specific signal is received.\n   *\n   * When a handler returns this result, the engine saves the current state\n   * and stops execution. The workflow can be resumed later using `engine.signal()`.\n   *\n   * @param signal - The unique identifier for the signal to wait for.\n   * @returns A special result object that instructs the engine to suspend.\n   *\n   * @example\n   * ```typescript\n   * .step('wait-for-approval', async (ctx) => {\n   *   return Flux.wait('manager-approval');\n   * })\n   * ```\n   */\n  wait: (signal: string): import('./types').FluxWaitResult => ({\n    __kind: 'flux_wait',\n    signal,\n  }),\n}\n"],"mappings":"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","names":["cpus"]}