@gravito/flux 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/index.node.cjs

@@ -0,0 +1,28 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+
+var _chunkRPECIW7Ocjs = require('./chunk-RPECIW7O.cjs');
+require('./chunk-SJSPR4ZU.cjs');
+
+
+
+
+
+
+
+
+
+
+
+
+exports.ContextManager = _chunkRPECIW7Ocjs.ContextManager; exports.FluxConsoleLogger = _chunkRPECIW7Ocjs.FluxConsoleLogger; exports.FluxEngine = _chunkRPECIW7Ocjs.FluxEngine; exports.FluxSilentLogger = _chunkRPECIW7Ocjs.FluxSilentLogger; exports.JsonFileTraceSink = _chunkRPECIW7Ocjs.JsonFileTraceSink; exports.MemoryStorage = _chunkRPECIW7Ocjs.MemoryStorage; exports.OrbitFlux = _chunkRPECIW7Ocjs.OrbitFlux; exports.StateMachine = _chunkRPECIW7Ocjs.StateMachine; exports.StepExecutor = _chunkRPECIW7Ocjs.StepExecutor; exports.WorkflowBuilder = _chunkRPECIW7Ocjs.WorkflowBuilder; exports.createWorkflow = _chunkRPECIW7Ocjs.createWorkflow;
+//# sourceMappingURL=index.node.cjs.map

package/dist/index.node.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/carl/Dev/Carl/gravito-core/packages/flux/dist/index.node.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,8nBAAC","file":"/Users/carl/Dev/Carl/gravito-core/packages/flux/dist/index.node.cjs"}

package/dist/index.node.d.cts

@@ -0,0 +1,499 @@
+import { i as WorkflowContext, W as WorkflowDefinition, j as WorkflowDescriptor, F as FluxConfig, b as FluxResult, l as WorkflowState, n as WorkflowStorage, k as WorkflowFilter, e as FluxTraceSink, c as FluxTraceEvent, m as WorkflowStatus, S as StepDefinition, g as StepExecution, h as StepResult, a as FluxLogger } from './types-DvVHBmP6.cjs';
+export { d as FluxTraceEventType, f as StepDescriptor } from './types-DvVHBmP6.cjs';
+
+/**
+ * @fileoverview Workflow Builder - Fluent API for defining workflows
+ *
+ * Type-safe, chainable workflow definition.
+ *
+ * @module @gravito/flux/builder
+ */
+
+/**
+ * Step options
+ */
+interface StepOptions {
+    retries?: number;
+    timeout?: number;
+    when?: (ctx: WorkflowContext) => boolean;
+}
+/**
+ * Workflow Builder
+ *
+ * Provides fluent API for defining workflows with type inference.
+ *
+ * @example
+ * ```typescript
+ * const workflow = createWorkflow('order-process')
+ *   .input<{ orderId: string }>()
+ *   .step('validate', async (ctx) => {
+ *     ctx.data.order = await fetchOrder(ctx.input.orderId)
+ *   })
+ *   .step('process', async (ctx) => {
+ *     await processOrder(ctx.data.order)
+ *   })
+ *   .commit('notify', async (ctx) => {
+ *     await sendEmail(ctx.data.order.email)
+ *   })
+ * ```
+ */
+declare class WorkflowBuilder<TInput = unknown, TData = Record<string, unknown>> {
+    private _name;
+    private _steps;
+    private _validateInput?;
+    constructor(name: string);
+    /**
+     * Define input type
+     *
+     * This method is used for TypeScript type inference.
+     */
+    input<T>(): WorkflowBuilder<T, TData>;
+    /**
+     * Define workflow data (state) type
+     *
+     * This method is used for TypeScript type inference.
+     */
+    data<T>(): WorkflowBuilder<TInput, T>;
+    /**
+     * Add input validator
+     */
+    validate(validator: (input: unknown) => input is TInput): this;
+    /**
+     * Add a step to the workflow
+     */
+    step(name: string, handler: (ctx: WorkflowContext<TInput, TData>) => Promise<void> | void, options?: StepOptions): this;
+    /**
+     * Add a commit step (always executes, even on replay)
+     *
+     * Commit steps are for side effects that should not be skipped,
+     * such as database writes or external API calls.
+     */
+    commit(name: string, handler: (ctx: WorkflowContext<TInput, TData>) => Promise<void> | void, options?: StepOptions): this;
+    /**
+     * Build the workflow definition
+     */
+    build(): WorkflowDefinition<TInput, TData>;
+    /**
+     * Describe workflow (serializable metadata)
+     */
+    describe(): WorkflowDescriptor;
+    /**
+     * Get workflow name
+     */
+    get name(): string;
+    /**
+     * Get step count
+     */
+    get stepCount(): number;
+}
+/**
+ * Create a new workflow builder
+ *
+ * @param name - Unique workflow name
+ * @returns WorkflowBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const uploadFlow = createWorkflow('image-upload')
+ *   .input<{ file: Buffer }>()
+ *   .step('resize', async (ctx) => {
+ *     ctx.data.resized = await sharp(ctx.input.file).resize(200).toBuffer()
+ *   })
+ *   .commit('save', async (ctx) => {
+ *     await storage.put(ctx.data.resized)
+ *   })
+ * ```
+ */
+declare function createWorkflow(name: string): WorkflowBuilder;
+
+/**
+ * @fileoverview Flux Engine - Main workflow execution engine
+ *
+ * Orchestrates workflow execution with storage and event handling.
+ *
+ * @module @gravito/flux
+ */
+
+/**
+ * Flux Engine
+ *
+ * Main workflow execution engine.
+ *
+ * @example
+ * ```typescript
+ * const engine = new FluxEngine({ storage: new MemoryStorage() })
+ *
+ * const workflow = createWorkflow('process-order')
+ *   .input<{ orderId: string }>()
+ *   .step('fetch', async (ctx) => { ... })
+ *   .step('validate', async (ctx) => { ... })
+ *   .commit('save', async (ctx) => { ... })
+ *
+ * const result = await engine.execute(workflow, { orderId: '123' })
+ * ```
+ */
+declare class FluxEngine {
+    private storage;
+    private executor;
+    private contextManager;
+    private config;
+    constructor(config?: FluxConfig);
+    /**
+     * Execute a workflow with input data
+     *
+     * @param workflow - Workflow builder or definition
+     * @param input - Input data for the workflow
+     * @returns Execution result
+     */
+    execute<TInput, TData = any>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, input: TInput): Promise<FluxResult<TData>>;
+    /**
+     * Resume a paused or failed workflow
+     *
+     * @param workflowId - Workflow instance ID
+     * @returns Execution result or null if not found
+     */
+    resume<TInput, TData = any>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, options?: {
+        fromStep?: number | string;
+    }): Promise<FluxResult<TData> | null>;
+    /**
+     * Retry a specific step (replays from that step onward)
+     */
+    retryStep<TInput, TData = any>(workflow: WorkflowBuilder<TInput, TData> | WorkflowDefinition<TInput, TData>, workflowId: string, stepName: string): Promise<FluxResult<TData> | null>;
+    /**
+     * Get workflow state by ID
+     */
+    get<TInput = any, TData = any>(workflowId: string): Promise<WorkflowState<TInput, TData> | null>;
+    /**
+     * Save workflow state manually (e.g., for external updates)
+     */
+    saveState<TInput, TData>(state: WorkflowState<TInput, TData>): Promise<void>;
+    /**
+     * List workflows
+     */
+    list(filter?: Parameters<WorkflowStorage['list']>[0]): Promise<WorkflowState<any, any>[]>;
+    /**
+     * Initialize engine (init storage)
+     */
+    init(): Promise<void>;
+    /**
+     * Shutdown engine (cleanup)
+     */
+    close(): Promise<void>;
+    private resolveDefinition;
+    private resolveStartIndex;
+    private resetHistoryFrom;
+    private runFrom;
+    private emitTrace;
+}
+
+/**
+ * @fileoverview In-memory storage adapter
+ *
+ * Simple storage for development and testing.
+ *
+ * @module @gravito/flux/storage
+ */
+
+/**
+ * Memory Storage
+ *
+ * In-memory storage adapter for development and testing.
+ * Data is not persisted across restarts.
+ */
+declare class MemoryStorage implements WorkflowStorage {
+    private store;
+    save(state: WorkflowState): Promise<void>;
+    load(id: string): Promise<WorkflowState | null>;
+    list(filter?: WorkflowFilter): Promise<WorkflowState[]>;
+    delete(id: string): Promise<void>;
+    init(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Get store size (for testing)
+     */
+    size(): number;
+}
+
+/**
+ * @fileoverview JSON file trace sink (NDJSON)
+ *
+ * Writes trace events to a newline-delimited JSON file.
+ */
+
+interface JsonFileTraceSinkOptions {
+    path: string;
+    reset?: boolean;
+}
+declare class JsonFileTraceSink implements FluxTraceSink {
+    private path;
+    private ready;
+    constructor(options: JsonFileTraceSinkOptions);
+    private init;
+    emit(event: FluxTraceEvent): Promise<void>;
+}
+
+/**
+ * @fileoverview Context Manager for workflow execution
+ *
+ * Manages workflow context lifecycle and state snapshots.
+ *
+ * @module @gravito/flux/core
+ */
+
+/**
+ * Context Manager
+ *
+ * Creates and manages workflow execution contexts.
+ */
+declare class ContextManager {
+    /**
+     * Create a new workflow context
+     */
+    create<TInput, TData = any>(name: string, input: TInput, stepCount: number): WorkflowContext<TInput, TData>;
+    /**
+     * Restore context from saved state
+     */
+    restore<TInput, TData = any>(state: WorkflowState<TInput, TData>): WorkflowContext<TInput, TData>;
+    /**
+     * Convert context to serializable state
+     */
+    toState<TInput, TData>(ctx: WorkflowContext<TInput, TData>): WorkflowState<TInput, TData>;
+    /**
+     * Update context status (returns new context for immutability)
+     */
+    updateStatus<TInput, TData>(ctx: WorkflowContext<TInput, TData>, status: WorkflowStatus): WorkflowContext<TInput, TData>;
+    /**
+     * Advance to next step
+     */
+    advanceStep<TInput, TData>(ctx: WorkflowContext<TInput, TData>): WorkflowContext<TInput, TData>;
+    /**
+     * Update step name in history
+     */
+    setStepName<TInput, TData>(ctx: WorkflowContext<TInput, TData>, index: number, name: string): void;
+}
+
+/**
+ * @fileoverview State Machine for workflow status transitions
+ *
+ * Pure state machine with no runtime dependencies.
+ *
+ * @module @gravito/flux/core
+ */
+
+/**
+ * State Machine for workflow status management
+ *
+ * Provides validated state transitions using EventTarget for events.
+ */
+declare class StateMachine extends EventTarget {
+    private _status;
+    /**
+     * Current status
+     */
+    get status(): WorkflowStatus;
+    /**
+     * Check if transition to target status is allowed
+     */
+    canTransition(to: WorkflowStatus): boolean;
+    /**
+     * Transition to a new status
+     *
+     * @throws {Error} If transition is not allowed
+     */
+    transition(to: WorkflowStatus): void;
+    /**
+     * Force set status (for replay/restore)
+     */
+    forceStatus(status: WorkflowStatus): void;
+    /**
+     * Check if workflow is in terminal state
+     */
+    isTerminal(): boolean;
+    /**
+     * Check if workflow can be executed
+     */
+    canExecute(): boolean;
+}
+
+/**
+ * @fileoverview Step Executor for workflow steps
+ *
+ * Handles step execution with retry and timeout support.
+ *
+ * @module @gravito/flux/core
+ */
+
+/**
+ * Step Executor
+ *
+ * Executes individual workflow steps with retry and timeout support.
+ */
+declare class StepExecutor {
+    private defaultRetries;
+    private defaultTimeout;
+    private onRetry?;
+    constructor(options?: {
+        defaultRetries?: number;
+        defaultTimeout?: number;
+        onRetry?: (step: StepDefinition<any, any>, ctx: WorkflowContext<any, any>, error: Error, attempt: number, maxRetries: number) => void | Promise<void>;
+    });
+    /**
+     * Execute a step with retry and timeout
+     */
+    execute<TInput, TData>(step: StepDefinition<TInput, TData>, ctx: WorkflowContext<TInput, TData>, execution: StepExecution): Promise<StepResult>;
+    /**
+     * Execute handler with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+
+/**
+ * @fileoverview Console Logger for FluxEngine
+ *
+ * Default logger implementation using console.
+ *
+ * @module @gravito/flux
+ */
+
+/**
+ * Console Logger
+ *
+ * Default logger that outputs to console.
+ *
+ * @example
+ * ```typescript
+ * const engine = new FluxEngine({
+ *   logger: new FluxConsoleLogger()
+ * })
+ * ```
+ */
+declare class FluxConsoleLogger implements FluxLogger {
+    private prefix;
+    constructor(prefix?: string);
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Silent Logger
+ *
+ * Logger that outputs nothing (for testing or production).
+ */
+declare class FluxSilentLogger implements FluxLogger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+
+/**
+ * @fileoverview OrbitFlux - Gravito PlanetCore Integration
+ *
+ * Integrates FluxEngine with Gravito's PlanetCore for seamless workflow management.
+ *
+ * @module @gravito/flux
+ */
+
+/**
+ * Minimal PlanetCore interface for type compatibility
+ * (Avoids importing @gravito/core sources which causes rootDir issues)
+ */
+interface PlanetCore {
+    logger: {
+        debug(message: string, ...args: unknown[]): void;
+        info(message: string, ...args: unknown[]): void;
+        warn(message: string, ...args: unknown[]): void;
+        error(message: string, ...args: unknown[]): void;
+    };
+    services: {
+        set(key: string, value: unknown): void;
+        get<T>(key: string): T | undefined;
+    };
+    hooks: {
+        doAction(name: string, payload?: unknown): void;
+    };
+}
+/**
+ * GravitoOrbit interface
+ */
+interface GravitoOrbit {
+    install(core: PlanetCore): void | Promise<void>;
+}
+/**
+ * OrbitFlux configuration options
+ */
+interface OrbitFluxOptions {
+    /**
+     * Storage driver: 'memory' | 'sqlite' | custom WorkflowStorage
+     * @default 'memory'
+     */
+    storage?: 'memory' | 'sqlite' | WorkflowStorage;
+    /**
+     * SQLite database path (only used if storage is 'sqlite')
+     * @default ':memory:'
+     */
+    dbPath?: string;
+    /**
+     * Service name in core.services
+     * @default 'flux'
+     */
+    exposeAs?: string;
+    /**
+     * Custom logger
+     */
+    logger?: FluxLogger;
+    /**
+     * Default retry count for steps
+     * @default 3
+     */
+    defaultRetries?: number;
+    /**
+     * Default timeout for steps (ms)
+     * @default 30000
+     */
+    defaultTimeout?: number;
+}
+/**
+ * OrbitFlux - Gravito Workflow Integration
+ *
+ * @example
+ * ```typescript
+ * import { OrbitFlux } from '@gravito/flux'
+ *
+ * const core = await PlanetCore.boot({
+ *   orbits: [
+ *     new OrbitFlux({ storage: 'sqlite', dbPath: './data/workflows.db' })
+ *   ]
+ * })
+ *
+ * // Access via services
+ * const flux = core.services.get<FluxEngine>('flux')
+ * await flux.execute(myWorkflow, input)
+ * ```
+ */
+declare class OrbitFlux implements GravitoOrbit {
+    private options;
+    private engine?;
+    constructor(options?: OrbitFluxOptions);
+    /**
+     * Create OrbitFlux with configuration
+     */
+    static configure(options?: OrbitFluxOptions): OrbitFlux;
+    /**
+     * Install into PlanetCore
+     *
+     * @param core - The PlanetCore instance
+     */
+    install(core: PlanetCore): Promise<void>;
+    /**
+     * Get the FluxEngine instance
+     */
+    getEngine(): FluxEngine | undefined;
+}
+
+export { ContextManager, FluxConfig, FluxConsoleLogger, FluxEngine, FluxLogger, FluxResult, FluxSilentLogger, FluxTraceEvent, FluxTraceSink, JsonFileTraceSink, MemoryStorage, OrbitFlux, type OrbitFluxOptions, StateMachine, StepDefinition, StepExecution, StepExecutor, StepResult, WorkflowBuilder, WorkflowContext, WorkflowDefinition, WorkflowDescriptor, WorkflowFilter, WorkflowState, WorkflowStatus, WorkflowStorage, createWorkflow };