@gravito/flux 3.0.2 → 4.0.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-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 { C as CronScheduleOptions, W as WorkflowDefinition, a as WorkflowState, F as FluxWaitResult } from './types-CGIEQPFv.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-CGIEQPFv.cjs';
 import { FluxEngine } 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';
+import { QueueException } from '@gravito/core';
 export { BunSQLiteStorage, BunSQLiteStorageOptions } from './bun.cjs';
-import '@gravito/core';
 import 'bun:sqlite';
 
 /**
@@ -48,6 +48,9 @@ declare enum FluxErrorCode {
 /**
  * Base class for all errors thrown by the FluxEngine.
  *
+ * Extends QueueException from @gravito/core, enabling consistent infrastructure
+ * error handling across the GravitoException hierarchy.
+ *
  * Includes a machine-readable error code and optional context for debugging.
  *
  * @example
@@ -61,17 +64,19 @@ declare enum FluxErrorCode {
  * }
  * ```
  */
-declare class FluxError extends Error {
-    readonly code: FluxErrorCode;
-    readonly context?: Record<string, unknown> | undefined;
+declare class FluxError extends QueueException {
+    /**
+     * Additional metadata related to the error.
+     */
+    readonly context?: Record<string, unknown>;
     /**
      * Creates a new FluxError.
      *
      * @param message - Human-readable error description.
-     * @param code - Machine-readable error code.
+     * @param code - Machine-readable error code (FluxErrorCode enum value).
      * @param context - Additional metadata related to the error.
      */
-    constructor(message: string, code: FluxErrorCode, context?: Record<string, unknown> | undefined);
+    constructor(message: string, code: FluxErrorCode | string, context?: Record<string, unknown>);
 }
 /**
  * Creates a FluxError for a missing workflow instance.

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-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 { C as CronScheduleOptions, W as WorkflowDefinition, a as WorkflowState, F as FluxWaitResult } from './types-CGIEQPFv.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-CGIEQPFv.js';
 import { FluxEngine } 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';
+import { QueueException } from '@gravito/core';
 export { BunSQLiteStorage, BunSQLiteStorageOptions } from './bun.js';
-import '@gravito/core';
 import 'bun:sqlite';
 
 /**
@@ -48,6 +48,9 @@ declare enum FluxErrorCode {
 /**
  * Base class for all errors thrown by the FluxEngine.
  *
+ * Extends QueueException from @gravito/core, enabling consistent infrastructure
+ * error handling across the GravitoException hierarchy.
+ *
  * Includes a machine-readable error code and optional context for debugging.
  *
  * @example
@@ -61,17 +64,19 @@ declare enum FluxErrorCode {
  * }
  * ```
  */
-declare class FluxError extends Error {
-    readonly code: FluxErrorCode;
-    readonly context?: Record<string, unknown> | undefined;
+declare class FluxError extends QueueException {
+    /**
+     * Additional metadata related to the error.
+     */
+    readonly context?: Record<string, unknown>;
     /**
      * Creates a new FluxError.
      *
      * @param message - Human-readable error description.
-     * @param code - Machine-readable error code.
+     * @param code - Machine-readable error code (FluxErrorCode enum value).
      * @param context - Additional metadata related to the error.
      */
-    constructor(message: string, code: FluxErrorCode, context?: Record<string, unknown> | undefined);
+    constructor(message: string, code: FluxErrorCode | string, context?: Record<string, unknown>);
 }
 /**
  * Creates a FluxError for a missing workflow instance.

package/dist/index.js

@@ -4,8 +4,6 @@ import {
   CronTrigger,
   FluxConsoleLogger,
   FluxEngine,
-  FluxError,
-  FluxErrorCode,
   FluxSilentLogger,
   JsonFileTraceSink,
   MemoryLockProvider,
@@ -16,9 +14,14 @@ import {
   StateMachine,
   StepExecutor,
   WorkflowBuilder,
+  createWorkflow
+} from "./chunk-JUCSCBHA.js";
+import {
+  BunSQLiteStorage,
+  FluxError,
+  FluxErrorCode,
   cannotRemoveRoot,
   cannotReplaceRoot,
-  createWorkflow,
   emptyWorkflow,
   invalidInput,
   invalidJsonPointer,
@@ -31,10 +34,7 @@ import {
   workflowNameMismatch,
   workflowNotFound,
   workflowNotSuspended
-} from "./chunk-4DXCQ6CL.js";
-import {
-  BunSQLiteStorage
-} from "./chunk-NAIVO7RR.js";
+} from "./chunk-UZKSACBE.js";
 import {
   MermaidGenerator
 } from "./chunk-WGDTB6OC.js";

package/dist/index.node.cjs

@@ -14,8 +14,8 @@
 
 
 
-var _chunkWAPZDXSXcjs = require('./chunk-WAPZDXSX.cjs');
-require('./chunk-YXBEYVGY.cjs');
+var _chunkAVWZYY7Ucjs = require('./chunk-AVWZYY7U.cjs');
+require('./chunk-OAJWPPYG.cjs');
 
 
 
@@ -32,5 +32,5 @@ require('./chunk-YXBEYVGY.cjs');
 
 
 
-exports.BatchExecutor = _chunkWAPZDXSXcjs.BatchExecutor; exports.ContextManager = _chunkWAPZDXSXcjs.ContextManager; exports.FluxConsoleLogger = _chunkWAPZDXSXcjs.FluxConsoleLogger; exports.FluxEngine = _chunkWAPZDXSXcjs.FluxEngine; exports.FluxSilentLogger = _chunkWAPZDXSXcjs.FluxSilentLogger; exports.JsonFileTraceSink = _chunkWAPZDXSXcjs.JsonFileTraceSink; exports.MemoryLockProvider = _chunkWAPZDXSXcjs.MemoryLockProvider; exports.MemoryStorage = _chunkWAPZDXSXcjs.MemoryStorage; exports.OrbitFlux = _chunkWAPZDXSXcjs.OrbitFlux; exports.PostgreSQLStorage = _chunkWAPZDXSXcjs.PostgreSQLStorage; exports.RedisLockProvider = _chunkWAPZDXSXcjs.RedisLockProvider; exports.StateMachine = _chunkWAPZDXSXcjs.StateMachine; exports.StepExecutor = _chunkWAPZDXSXcjs.StepExecutor; exports.WorkflowBuilder = _chunkWAPZDXSXcjs.WorkflowBuilder; exports.createWorkflow = _chunkWAPZDXSXcjs.createWorkflow;
+exports.BatchExecutor = _chunkAVWZYY7Ucjs.BatchExecutor; exports.ContextManager = _chunkAVWZYY7Ucjs.ContextManager; exports.FluxConsoleLogger = _chunkAVWZYY7Ucjs.FluxConsoleLogger; exports.FluxEngine = _chunkAVWZYY7Ucjs.FluxEngine; exports.FluxSilentLogger = _chunkAVWZYY7Ucjs.FluxSilentLogger; exports.JsonFileTraceSink = _chunkAVWZYY7Ucjs.JsonFileTraceSink; exports.MemoryLockProvider = _chunkAVWZYY7Ucjs.MemoryLockProvider; exports.MemoryStorage = _chunkAVWZYY7Ucjs.MemoryStorage; exports.OrbitFlux = _chunkAVWZYY7Ucjs.OrbitFlux; exports.PostgreSQLStorage = _chunkAVWZYY7Ucjs.PostgreSQLStorage; exports.RedisLockProvider = _chunkAVWZYY7Ucjs.RedisLockProvider; exports.StateMachine = _chunkAVWZYY7Ucjs.StateMachine; exports.StepExecutor = _chunkAVWZYY7Ucjs.StepExecutor; exports.WorkflowBuilder = _chunkAVWZYY7Ucjs.WorkflowBuilder; exports.createWorkflow = _chunkAVWZYY7Ucjs.createWorkflow;
 //# sourceMappingURL=index.node.cjs.map

package/dist/index.node.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/carl/Dev/Carl/gravito-core-ci-fix/packages/flux/dist/index.node.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;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;AACA;AACA;AACA;AACA;AACF,43BAAC","file":"/Users/carl/Dev/Carl/gravito-core-ci-fix/packages/flux/dist/index.node.cjs"}
+{"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;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,43BAAC","file":"/Users/carl/Dev/Carl/gravito-core/packages/flux/dist/index.node.cjs"}

package/dist/index.node.d.cts

@@ -1,5 +1,5 @@
-import { l as WorkflowContext, q as StepHandlerResult, W as WorkflowDefinition, m as WorkflowDescriptor, a as WorkflowState, o as WorkflowStatus, h as LockProvider, L as Lock, S as StepDefinition, j as StepExecution, k as StepResult, c as FluxLogger, p as WorkflowStorage, n as WorkflowFilter, g as FluxTraceSink, e as FluxTraceEvent, b as FluxConfig, d as FluxResult, C as CronScheduleOptions } from './types-CRz5XdLd.cjs';
-export { f as FluxTraceEventType, M as MemoryLockProvider, i as StepDescriptor } from './types-CRz5XdLd.cjs';
+import { l as WorkflowContext, q as StepHandlerResult, W as WorkflowDefinition, m as WorkflowDescriptor, a as WorkflowState, o as WorkflowStatus, h as LockProvider, L as Lock, S as StepDefinition, j as StepExecution, k as StepResult, c as FluxLogger, p as WorkflowStorage, n as WorkflowFilter, g as FluxTraceSink, e as FluxTraceEvent, b as FluxConfig, d as FluxResult, C as CronScheduleOptions } from './types-CGIEQPFv.cjs';
+export { f as FluxTraceEventType, M as MemoryLockProvider, i as StepDescriptor } from './types-CGIEQPFv.cjs';
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
@@ -971,7 +971,8 @@ declare class PostgreSQLStorage implements WorkflowStorage {
 /**
  * @fileoverview JSON file trace sink (NDJSON)
  *
- * Writes trace events to a newline-delimited JSON file.
+ * Writes trace events to a newline-delimited JSON file with buffering support.
+ * Uses RuntimeAdapter's FileSink for efficient batch writes instead of individual syscalls.
  */
 
 /**
@@ -984,6 +985,8 @@ interface JsonFileTraceSinkOptions {
     path: string;
     /** Whether to reset (clear) the file on initialization. @default true */
     reset?: boolean;
+    /** Buffer size for batch writes. Events are flushed when buffer reaches this size. @default 50 */
+    bufferSize?: number;
 }
 /**
  * A trace sink that writes events to a newline-delimited JSON (NDJSON) file.
@@ -991,11 +994,17 @@ interface JsonFileTraceSinkOptions {
  * This sink is ideal for local development and debugging as it produces
  * a human-readable and easily machine-parsable log of workflow events.
  *
+ * Optimizations:
+ * - Uses RuntimeAdapter's FileSink for buffered writes (reduces syscalls)
+ * - Automatic flush on buffer overflow
+ * - Batch write support for better I/O efficiency
+ *
  * @example
  * ```typescript
  * const sink = new JsonFileTraceSink({
  *   path: './traces/workflow.jsonl',
- *   reset: true
+ *   reset: true,
+ *   bufferSize: 100  // Flush every 100 events
  * });
  * ```
  *
@@ -1004,8 +1013,12 @@ interface JsonFileTraceSinkOptions {
 declare class JsonFileTraceSink implements FluxTraceSink {
     private path;
     private ready;
+    private fileSink;
+    private buffer;
+    private bufferSize;
+    private adapter;
     /**
-     * Creates a new JSON file trace sink.
+     * Creates a new JSON file trace sink with buffering support.
      *
      * @param options - Configuration options for the sink.
      */
@@ -1020,7 +1033,8 @@ declare class JsonFileTraceSink implements FluxTraceSink {
     /**
      * Appends a trace event to the file in NDJSON format.
      *
-     * Waits for initialization to complete before writing.
+     * Events are buffered and written in batches using FileSink
+     * for improved I/O efficiency. Waits for initialization to complete before writing.
      *
      * @param event - The trace event to record.
      * @throws {Error} If writing to the file fails.
@@ -1036,6 +1050,23 @@ declare class JsonFileTraceSink implements FluxTraceSink {
      * ```
      */
     emit(event: FluxTraceEvent): Promise<void>;
+    /**
+     * Flushes buffered events to disk.
+     *
+     * This is called automatically when the buffer reaches the configured size.
+     * Can also be called manually to ensure all events are written.
+     *
+     * @throws {Error} If flushing fails.
+     */
+    flushBuffer(): Promise<void>;
+    /**
+     * Closes the sink and flushes any remaining buffered events.
+     *
+     * Should be called before process exit to ensure all events are persisted.
+     *
+     * @throws {Error} If closing or flushing fails.
+     */
+    close(): Promise<void>;
 }
 
 /**

package/dist/index.node.d.ts

@@ -1,5 +1,5 @@
-import { l as WorkflowContext, q as StepHandlerResult, W as WorkflowDefinition, m as WorkflowDescriptor, a as WorkflowState, o as WorkflowStatus, h as LockProvider, L as Lock, S as StepDefinition, j as StepExecution, k as StepResult, c as FluxLogger, p as WorkflowStorage, n as WorkflowFilter, g as FluxTraceSink, e as FluxTraceEvent, b as FluxConfig, d as FluxResult, C as CronScheduleOptions } from './types-CRz5XdLd.js';
-export { f as FluxTraceEventType, M as MemoryLockProvider, i as StepDescriptor } from './types-CRz5XdLd.js';
+import { l as WorkflowContext, q as StepHandlerResult, W as WorkflowDefinition, m as WorkflowDescriptor, a as WorkflowState, o as WorkflowStatus, h as LockProvider, L as Lock, S as StepDefinition, j as StepExecution, k as StepResult, c as FluxLogger, p as WorkflowStorage, n as WorkflowFilter, g as FluxTraceSink, e as FluxTraceEvent, b as FluxConfig, d as FluxResult, C as CronScheduleOptions } from './types-CGIEQPFv.js';
+export { f as FluxTraceEventType, M as MemoryLockProvider, i as StepDescriptor } from './types-CGIEQPFv.js';
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
@@ -971,7 +971,8 @@ declare class PostgreSQLStorage implements WorkflowStorage {
 /**
  * @fileoverview JSON file trace sink (NDJSON)
  *
- * Writes trace events to a newline-delimited JSON file.
+ * Writes trace events to a newline-delimited JSON file with buffering support.
+ * Uses RuntimeAdapter's FileSink for efficient batch writes instead of individual syscalls.
  */
 
 /**
@@ -984,6 +985,8 @@ interface JsonFileTraceSinkOptions {
     path: string;
     /** Whether to reset (clear) the file on initialization. @default true */
     reset?: boolean;
+    /** Buffer size for batch writes. Events are flushed when buffer reaches this size. @default 50 */
+    bufferSize?: number;
 }
 /**
  * A trace sink that writes events to a newline-delimited JSON (NDJSON) file.
@@ -991,11 +994,17 @@ interface JsonFileTraceSinkOptions {
  * This sink is ideal for local development and debugging as it produces
  * a human-readable and easily machine-parsable log of workflow events.
  *
+ * Optimizations:
+ * - Uses RuntimeAdapter's FileSink for buffered writes (reduces syscalls)
+ * - Automatic flush on buffer overflow
+ * - Batch write support for better I/O efficiency
+ *
  * @example
  * ```typescript
  * const sink = new JsonFileTraceSink({
  *   path: './traces/workflow.jsonl',
- *   reset: true
+ *   reset: true,
+ *   bufferSize: 100  // Flush every 100 events
  * });
  * ```
  *
@@ -1004,8 +1013,12 @@ interface JsonFileTraceSinkOptions {
 declare class JsonFileTraceSink implements FluxTraceSink {
     private path;
     private ready;
+    private fileSink;
+    private buffer;
+    private bufferSize;
+    private adapter;
     /**
-     * Creates a new JSON file trace sink.
+     * Creates a new JSON file trace sink with buffering support.
      *
      * @param options - Configuration options for the sink.
      */
@@ -1020,7 +1033,8 @@ declare class JsonFileTraceSink implements FluxTraceSink {
     /**
      * Appends a trace event to the file in NDJSON format.
      *
-     * Waits for initialization to complete before writing.
+     * Events are buffered and written in batches using FileSink
+     * for improved I/O efficiency. Waits for initialization to complete before writing.
      *
      * @param event - The trace event to record.
      * @throws {Error} If writing to the file fails.
@@ -1036,6 +1050,23 @@ declare class JsonFileTraceSink implements FluxTraceSink {
      * ```
      */
     emit(event: FluxTraceEvent): Promise<void>;
+    /**
+     * Flushes buffered events to disk.
+     *
+     * This is called automatically when the buffer reaches the configured size.
+     * Can also be called manually to ensure all events are written.
+     *
+     * @throws {Error} If flushing fails.
+     */
+    flushBuffer(): Promise<void>;
+    /**
+     * Closes the sink and flushes any remaining buffered events.
+     *
+     * Should be called before process exit to ensure all events are persisted.
+     *
+     * @throws {Error} If closing or flushing fails.
+     */
+    close(): Promise<void>;
 }
 
 /**

package/dist/index.node.js

@@ -14,8 +14,8 @@ import {
   StepExecutor,
   WorkflowBuilder,
   createWorkflow
-} from "./chunk-4DXCQ6CL.js";
-import "./chunk-NAIVO7RR.js";
+} from "./chunk-JUCSCBHA.js";
+import "./chunk-UZKSACBE.js";
 export {
   BatchExecutor,
   ContextManager,

package/dist/{types-CRz5XdLd.d.cts → types-CGIEQPFv.d.cts}

@@ -359,6 +359,16 @@ interface FluxTraceSink {
      * @param event - The event to record.
      */
     emit(event: FluxTraceEvent): void | Promise<void>;
+    /**
+     * Optional method to flush any buffered events.
+     * Called to ensure all events are persisted before shutdown.
+     */
+    flush?(): Promise<void>;
+    /**
+     * Optional method to close the sink and release resources.
+     * Should be called before process exit.
+     */
+    close?(): Promise<void>;
 }
 /**
  * Global configuration for the Flux engine instance.

package/dist/{types-CRz5XdLd.d.ts → types-CGIEQPFv.d.ts}

@@ -359,6 +359,16 @@ interface FluxTraceSink {
      * @param event - The event to record.
      */
     emit(event: FluxTraceEvent): void | Promise<void>;
+    /**
+     * Optional method to flush any buffered events.
+     * Called to ensure all events are persisted before shutdown.
+     */
+    flush?(): Promise<void>;
+    /**
+     * Optional method to close the sink and release resources.
+     * Should be called before process exit.
+     */
+    close?(): Promise<void>;
 }
 /**
  * Global configuration for the Flux engine instance.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/flux",
-  "version": "3.0.2",
+  "sideEffects": false,
+  "version": "4.0.0",
   "description": "Platform-agnostic workflow engine for Gravito",
   "type": "module",
   "main": "./dist/index.node.cjs",
@@ -39,6 +40,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "build:dts": "tsup --dts --dts-only",
     "dev:viewer": "node ./bin/flux.js dev --trace ./.flux/trace.ndjson --port 4280",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
     "test": "bun test --timeout=10000",
@@ -48,7 +50,7 @@
     "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": "^1.6.1",
+    "@gravito/core": "^3.0.0",
     "pg": "^8.18.0"
   },
   "peerDependenciesMeta": {
@@ -60,7 +62,7 @@
     }
   },
   "devDependencies": {
-    "@gravito/core": "^1.6.1",
+    "@gravito/core": "workspace:*",
     "@types/pg": "^8.16.0",
     "bun-types": "latest",
     "pg": "^8.18.0",