@gravito/flux 3.0.0 → 3.0.2

package/dist/types-CRz5XdLd.d.ts

@@ -0,0 +1,433 @@
+/**
+ * @fileoverview Lock Provider interface for distributed execution
+ *
+ * Provides a mechanism for coordinating workflow execution across multiple
+ * nodes by ensuring only one node executes a specific workflow instance at a time.
+ *
+ * @module @gravito/flux/core
+ */
+/**
+ * Represents a distributed lock for a specific resource.
+ */
+interface Lock {
+    /** The unique identifier for the locked resource. */
+    id: string;
+    /** The owner of the lock (e.g., node identifier). */
+    owner: string;
+    /** Unix timestamp when the lock expires. */
+    expiresAt: number;
+    /** Releases the lock manually. */
+    release(): Promise<void>;
+}
+/**
+ * Interface for implementing distributed locking mechanisms.
+ * Required for Cluster Mode to prevent race conditions in multi-node environments.
+ */
+interface LockProvider {
+    /**
+     * Attempts to acquire a lock for a specific resource.
+     *
+     * @param resourceId - The unique ID of the resource to lock (e.g., workflowId).
+     * @param owner - The identifier of the node/process requesting the lock.
+     * @param ttl - Time-to-live for the lock in milliseconds.
+     * @returns A Lock object if successful, otherwise null.
+     */
+    acquire(resourceId: string, owner: string, ttl: number): Promise<Lock | null>;
+    /**
+     * Refreshes an existing lock to extend its lifetime.
+     *
+     * @param resourceId - The ID of the resource.
+     * @param owner - The current owner of the lock.
+     * @param ttl - The new time-to-live from the current moment.
+     * @returns True if the lock was successfully refreshed.
+     */
+    refresh(resourceId: string, owner: string, ttl: number): Promise<boolean>;
+    /**
+     * Forcefully releases a lock, regardless of the owner.
+     *
+     * @param resourceId - The ID of the resource to unlock.
+     */
+    release(resourceId: string): Promise<void>;
+}
+/**
+ * In-memory implementation of LockProvider for local development and testing.
+ * Does NOT support multiple processes or nodes.
+ */
+declare class MemoryLockProvider implements LockProvider {
+    private locks;
+    acquire(resourceId: string, owner: string, ttl: number): Promise<Lock | null>;
+    refresh(resourceId: string, owner: string, ttl: number): Promise<boolean>;
+    release(resourceId: string): Promise<void>;
+    private createLock;
+}
+
+/**
+ * Represents the current lifecycle state of a workflow instance.
+ * Used to track progress and determine valid state transitions.
+ */
+type WorkflowStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'suspended' | 'rolling_back' | 'rolled_back' | 'compensation_failed';
+/**
+ * Signal payload returned by a step to pause execution until an external event occurs.
+ * This enables long-running workflows that wait for human approval or webhooks.
+ */
+interface FluxWaitResult {
+    __kind: 'flux_wait';
+    /** The unique identifier for the signal this workflow is waiting for. */
+    signal: string;
+}
+/**
+ * The possible return values from a step handler.
+ * Supports synchronous results, promises, and suspension signals.
+ */
+type StepHandlerResult = undefined | undefined | FluxWaitResult | Promise<undefined | undefined | FluxWaitResult>;
+/**
+ * Internal representation of a step's execution outcome.
+ * Captures performance metrics and state for persistence and observability.
+ */
+interface StepResult<T = unknown> {
+    /** Indicates if the step completed without unhandled exceptions. */
+    success: boolean;
+    /** The data produced by the step, if any. */
+    data?: T;
+    /** The error encountered during execution, if success is false. */
+    error?: Error;
+    /** Execution time in milliseconds. */
+    duration: number;
+    /** Whether the step requested workflow suspension. */
+    suspended?: boolean;
+    /** The signal name if the step is suspended. */
+    waitingFor?: string;
+}
+/**
+ * Audit log entry for a single step execution within a workflow.
+ * Provides a historical record for debugging and compliance.
+ */
+interface StepExecution {
+    /** The unique name of the step as defined in the workflow. */
+    name: string;
+    /** The execution outcome status. */
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'suspended' | 'compensated' | 'compensating';
+    /** ISO timestamp when the step started. */
+    startedAt?: Date;
+    /** ISO timestamp when the step finished. */
+    completedAt?: Date;
+    /** ISO timestamp when the step was suspended. */
+    suspendedAt?: Date;
+    /** ISO timestamp when compensation logic finished. */
+    compensatedAt?: Date;
+    /** The signal name if currently suspended. */
+    waitingFor?: string;
+    /** Total execution time in milliseconds. */
+    duration?: number;
+    /** Serialized output data from the step. */
+    output?: any;
+    /** Error message if the step failed. */
+    error?: string;
+    /** Number of retry attempts performed. */
+    retries: number;
+}
+/**
+ * Configuration for a single unit of work within a workflow.
+ * Defines the business logic, error handling, and execution conditions.
+ */
+interface StepDefinition<TInput = unknown, TData = Record<string, any>> {
+    /** Unique identifier for the step within the workflow. */
+    name: string;
+    /**
+     * The core business logic for this step.
+     * @param ctx - The current workflow execution context.
+     * @returns A result indicating completion or suspension.
+     */
+    handler: (ctx: WorkflowContext<TInput, TData>) => StepHandlerResult;
+    /**
+     * Logic to execute if a subsequent step fails, enabling the Saga pattern.
+     * @param ctx - The current workflow execution context.
+     */
+    compensate?: (ctx: WorkflowContext<TInput, TData>) => Promise<void> | void;
+    /** Maximum number of times to retry on failure before giving up. */
+    retries?: number;
+    /** Maximum execution time in milliseconds before timing out. */
+    timeout?: number;
+    /**
+     * Predicate to determine if this step should be executed.
+     * @param ctx - The current workflow execution context.
+     * @returns True if the step should run.
+     */
+    when?: (ctx: WorkflowContext<TInput, TData>) => boolean;
+    /** If true, the step is considered a side-effect that should not be re-run on replay. */
+    commit?: boolean;
+    /** If set, this step belongs to a parallel execution group with this ID. */
+    parallelGroup?: string;
+}
+/**
+ * Shared state and utilities provided to every step during execution.
+ * Acts as the "source of truth" for the current workflow run.
+ */
+interface WorkflowContext<TInput = unknown, TData = Record<string, any>> {
+    /** Unique UUID for this specific workflow instance. */
+    readonly id: string;
+    /** The name of the workflow definition. */
+    readonly name: string;
+    /** Immutable input data provided when the workflow started. */
+    readonly input: TInput;
+    /** Mutable state shared across all steps in the workflow. */
+    data: TData;
+    /** Current lifecycle status of the workflow. */
+    readonly status: WorkflowStatus;
+    /** Zero-based index of the step currently being executed. */
+    readonly currentStep: number;
+    /** Full history of all steps executed so far. */
+    readonly history: StepExecution[];
+    /** Optimistic locking version to prevent concurrent modification issues. */
+    readonly version: number;
+}
+/**
+ * Persistable representation of a workflow's entire state.
+ * This structure is what storage adapters save and load.
+ */
+interface WorkflowState<TInput = unknown, TData = Record<string, any>> {
+    /** Unique UUID for the workflow instance. */
+    id: string;
+    /** Name of the workflow definition. */
+    name: string;
+    /** Current lifecycle status. */
+    status: WorkflowStatus;
+    /** Original input data. */
+    input: TInput;
+    /** Current accumulated data. */
+    data: TData;
+    /** Index of the next step to execute. */
+    currentStep: number;
+    /** Audit trail of step executions. */
+    history: StepExecution[];
+    /** When the instance was first created. */
+    createdAt: Date;
+    /** When the instance was last modified. */
+    updatedAt: Date;
+    /** When the workflow reached a terminal state. */
+    completedAt?: Date;
+    /** Final error message if the workflow failed. */
+    error?: string;
+    /** Version number for concurrency control. */
+    version: number;
+    /** The version of the workflow definition used to create this instance */
+    definitionVersion?: string;
+}
+/**
+ * The blueprint for a workflow, containing its name and ordered steps.
+ */
+interface WorkflowDefinition<TInput = unknown, TData = Record<string, any>> {
+    /** Unique name for this workflow type. */
+    name: string;
+    /** Semantic version of this workflow definition (e.g., "1.0.0", "2.1.0") */
+    version?: string;
+    /** Ordered list of steps to execute. */
+    steps: StepDefinition<TInput, TData>[];
+    /** Optional runtime validation for the workflow input. */
+    validateInput?: (input: unknown) => input is TInput;
+}
+/**
+ * Metadata describing a workflow's structure for UI or documentation.
+ */
+interface WorkflowDescriptor {
+    /** Name of the workflow. */
+    name: string;
+    /** Semantic version of the workflow definition */
+    version?: string;
+    /** Metadata for each step in the workflow. */
+    steps: StepDescriptor[];
+}
+/**
+ * Metadata describing a single step's configuration.
+ */
+interface StepDescriptor {
+    /** Name of the step. */
+    name: string;
+    /** Whether the step is marked as a commit. */
+    commit: boolean;
+    /** Configured retry limit. */
+    retries?: number;
+    /** Configured timeout in milliseconds. */
+    timeout?: number;
+    /** Whether the step has a conditional execution predicate. */
+    hasCondition: boolean;
+}
+/**
+ * Interface for implementing custom persistence layers.
+ * Allows workflows to survive process restarts and scale across nodes.
+ */
+interface WorkflowStorage {
+    /**
+     * Persists the current state of a workflow.
+     * @param state - The state to save.
+     * @throws If the storage operation fails or version conflict occurs.
+     */
+    save(state: WorkflowState): Promise<void>;
+    /**
+     * Retrieves a workflow state by its unique ID.
+     * @param id - The workflow instance ID.
+     * @returns The state if found, otherwise null.
+     */
+    load(id: string): Promise<WorkflowState | null>;
+    /**
+     * Queries workflow instances based on filters.
+     * @param filter - Criteria for selecting workflows.
+     * @returns A list of matching workflow states.
+     */
+    list(filter?: WorkflowFilter): Promise<WorkflowState[]>;
+    /**
+     * Permanently removes a workflow instance from storage.
+     * @param id - The workflow instance ID.
+     */
+    delete(id: string): Promise<void>;
+    /** Optional initialization logic for the storage provider. */
+    init?(): Promise<void>;
+    /** Optional cleanup logic for the storage provider. */
+    close?(): Promise<void>;
+}
+/**
+ * Criteria for filtering workflow instances in storage queries.
+ */
+interface WorkflowFilter {
+    /** Filter by workflow definition name. */
+    name?: string;
+    /** Filter by one or more lifecycle statuses. */
+    status?: WorkflowStatus | WorkflowStatus[];
+    /** Filter by definition version */
+    version?: string;
+    /** Maximum number of results to return. */
+    limit?: number;
+    /** Number of results to skip for pagination. */
+    offset?: number;
+}
+/**
+ * Generic logging interface for the Flux engine.
+ * Allows integration with various logging libraries (Pino, Winston, etc.).
+ */
+interface FluxLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Enumeration of all observable events emitted by the engine.
+ * Used for tracing, monitoring, and debugging.
+ */
+type FluxTraceEventType = 'workflow:start' | 'workflow:complete' | 'workflow:error' | 'workflow:rollback_start' | 'workflow:rollback_complete' | 'step:start' | 'step:complete' | 'step:error' | 'step:skipped' | 'step:retry' | 'step:suspend' | 'step:compensate' | 'signal:received';
+/**
+ * A single telemetry event captured during workflow execution.
+ */
+interface FluxTraceEvent {
+    /** The type of event being recorded. */
+    type: FluxTraceEventType;
+    /** Unix timestamp in milliseconds. */
+    timestamp: number;
+    /** ID of the workflow instance. */
+    workflowId: string;
+    /** Name of the workflow definition. */
+    workflowName: string;
+    /** Name of the step, if applicable. */
+    stepName?: string;
+    /** Index of the step, if applicable. */
+    stepIndex?: number;
+    /** Whether the step was a commit. */
+    commit?: boolean;
+    /** Current retry attempt number. */
+    retries?: number;
+    /** Maximum allowed retries. */
+    maxRetries?: number;
+    /** Duration of the operation in milliseconds. */
+    duration?: number;
+    /** Error message if the event represents a failure. */
+    error?: string;
+    /** Current status of the workflow or step. */
+    status?: WorkflowStatus | StepExecution['status'];
+    /** Input data associated with the event. */
+    input?: unknown;
+    /** Current workflow data associated with the event. */
+    data?: Record<string, unknown>;
+    /** Additional contextual metadata. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Destination for trace events, such as OpenTelemetry, ELK, or a simple console.
+ */
+interface FluxTraceSink {
+    /**
+     * Processes a trace event.
+     * @param event - The event to record.
+     */
+    emit(event: FluxTraceEvent): void | Promise<void>;
+}
+/**
+ * Global configuration for the Flux engine instance.
+ */
+interface FluxConfig<TData = Record<string, any>> {
+    /** Persistence provider for workflow states. */
+    storage?: WorkflowStorage;
+    /** Logger for internal engine operations. */
+    logger?: FluxLogger;
+    /** Telemetry sink for execution events. */
+    trace?: FluxTraceSink;
+    /** Default retry limit for steps that don't specify one. */
+    defaultRetries?: number;
+    /** Default timeout in milliseconds for steps that don't specify one. */
+    defaultTimeout?: number;
+    /** Whether to allow parallel execution of independent workflows (if supported). */
+    parallel?: boolean;
+    /** Lifecycle hooks for custom logic at specific execution points. */
+    on?: {
+        stepStart?: <TInput = unknown>(step: string, ctx: WorkflowContext<TInput, TData>) => void;
+        stepComplete?: <TInput = unknown>(step: string, ctx: WorkflowContext<TInput, TData>, result: StepResult) => void;
+        stepError?: <TInput = unknown>(step: string, ctx: WorkflowContext<TInput, TData>, error: Error) => void;
+        workflowComplete?: <TInput = unknown>(ctx: WorkflowContext<TInput, TData>) => void;
+        workflowError?: <TInput = unknown>(ctx: WorkflowContext<TInput, TData>, error: Error) => void;
+    };
+    /** Configuration for data optimization (handling large objects). */
+    optimizer?: {
+        enabled: boolean;
+        threshold?: number;
+        defaultLocation?: 's3' | 'redis' | 'database' | 'memory';
+    };
+    /** Distributed lock provider for cluster mode. */
+    lockProvider?: LockProvider;
+}
+/**
+ * Configuration for a scheduled workflow execution.
+ */
+interface CronScheduleOptions<TInput = unknown> {
+    /** Unique identifier for the schedule. */
+    id: string;
+    /** Cron expression (e.g., "* * * * *"). */
+    cron: string;
+    /** Workflow definition to execute. */
+    workflow: WorkflowDefinition<TInput, any> | string;
+    /** Input to provide to the workflow. */
+    input: TInput;
+    /** Optional metadata for the schedule. */
+    meta?: Record<string, unknown>;
+    /** Whether the schedule is active. @default true */
+    enabled?: boolean;
+}
+/**
+ * The final outcome of a workflow execution.
+ */
+interface FluxResult<TData = Record<string, any>> {
+    /** Unique ID of the workflow instance. */
+    id: string;
+    /** Final lifecycle status. */
+    status: WorkflowStatus;
+    /** Final state of the workflow data. */
+    data: TData;
+    /** Full execution history. */
+    history: StepExecution[];
+    /** Total execution time in milliseconds. */
+    duration: number;
+    /** The error that caused failure, if any. */
+    error?: Error;
+    /** Final version of the workflow state. */
+    version: number;
+}
+
+export { type CronScheduleOptions as C, type FluxWaitResult as F, type Lock as L, MemoryLockProvider as M, type StepDefinition as S, type WorkflowDefinition as W, type WorkflowState as a, type FluxConfig as b, type FluxLogger as c, type FluxResult as d, type FluxTraceEvent as e, type FluxTraceEventType as f, type FluxTraceSink as g, type LockProvider as h, type StepDescriptor as i, type StepExecution as j, type StepResult as k, type WorkflowContext as l, type WorkflowDescriptor as m, type WorkflowFilter as n, type WorkflowStatus as o, type WorkflowStorage as p, type StepHandlerResult as q };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/flux",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Platform-agnostic workflow engine for Gravito",
   "type": "module",
   "main": "./dist/index.node.cjs",
@@ -41,21 +41,29 @@
     "build": "tsup",
     "dev:viewer": "node ./bin/flux.js dev --trace ./.flux/trace.ndjson --port 4280",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage --coverage-threshold=80",
-    "test:ci": "bun test --coverage --coverage-threshold=80"
+    "test": "bun test --timeout=10000",
+    "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:unit": "bun test tests/ --timeout=10000",
+    "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
   "peerDependencies": {
-    "@gravito/core": "workspace:*"
+    "@gravito/core": "^1.6.1",
+    "pg": "^8.18.0"
   },
   "peerDependenciesMeta": {
     "@gravito/core": {
       "optional": true
+    },
+    "pg": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@gravito/core": "^1.6.1",
+    "@types/pg": "^8.16.0",
     "bun-types": "latest",
-    "@gravito/core": "workspace:*",
+    "pg": "^8.18.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
@@ -76,5 +84,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "cron-parser": "^5.5.0"
   }
 }