@gravito/flux 1.0.0-alpha.1

package/dist/node/index.mjs

@@ -0,0 +1,619 @@
+// src/builder/WorkflowBuilder.ts
+class WorkflowBuilder {
+  _name;
+  _steps = [];
+  _validateInput;
+  constructor(name) {
+    this._name = name;
+  }
+  input() {
+    return this;
+  }
+  validate(validator) {
+    this._validateInput = validator;
+    return this;
+  }
+  step(name, handler, options) {
+    this._steps.push({
+      name,
+      handler,
+      retries: options?.retries,
+      timeout: options?.timeout,
+      when: options?.when,
+      commit: false
+    });
+    return this;
+  }
+  commit(name, handler, options) {
+    this._steps.push({
+      name,
+      handler,
+      retries: options?.retries,
+      timeout: options?.timeout,
+      when: options?.when,
+      commit: true
+    });
+    return this;
+  }
+  build() {
+    if (this._steps.length === 0) {
+      throw new Error(`Workflow "${this._name}" has no steps`);
+    }
+    return {
+      name: this._name,
+      steps: [...this._steps],
+      validateInput: this._validateInput
+    };
+  }
+  get name() {
+    return this._name;
+  }
+  get stepCount() {
+    return this._steps.length;
+  }
+}
+function createWorkflow(name) {
+  return new WorkflowBuilder(name);
+}
+// src/core/ContextManager.ts
+function generateId() {
+  return crypto.randomUUID();
+}
+
+class ContextManager {
+  create(name, input, stepCount) {
+    const history = Array.from({ length: stepCount }, (_, _i) => ({
+      name: "",
+      status: "pending",
+      retries: 0
+    }));
+    return {
+      id: generateId(),
+      name,
+      input,
+      data: {},
+      status: "pending",
+      currentStep: 0,
+      history
+    };
+  }
+  restore(state) {
+    return {
+      id: state.id,
+      name: state.name,
+      input: state.input,
+      data: { ...state.data },
+      status: state.status,
+      currentStep: state.currentStep,
+      history: state.history.map((h) => ({ ...h }))
+    };
+  }
+  toState(ctx) {
+    return {
+      id: ctx.id,
+      name: ctx.name,
+      status: ctx.status,
+      input: ctx.input,
+      data: { ...ctx.data },
+      currentStep: ctx.currentStep,
+      history: ctx.history.map((h) => ({ ...h })),
+      createdAt: new Date,
+      updatedAt: new Date
+    };
+  }
+  updateStatus(ctx, status) {
+    return {
+      ...ctx,
+      status
+    };
+  }
+  advanceStep(ctx) {
+    return {
+      ...ctx,
+      currentStep: ctx.currentStep + 1
+    };
+  }
+  setStepName(ctx, index, name) {
+    if (ctx.history[index]) {
+      ctx.history[index].name = name;
+    }
+  }
+}
+
+// src/core/StateMachine.ts
+var TRANSITIONS = {
+  pending: ["running", "failed"],
+  running: ["paused", "completed", "failed"],
+  paused: ["running", "failed"],
+  completed: [],
+  failed: ["pending"]
+};
+
+class StateMachine extends EventTarget {
+  _status = "pending";
+  get status() {
+    return this._status;
+  }
+  canTransition(to) {
+    return TRANSITIONS[this._status].includes(to);
+  }
+  transition(to) {
+    if (!this.canTransition(to)) {
+      throw new Error(`Invalid state transition: ${this._status} → ${to}`);
+    }
+    const from = this._status;
+    this._status = to;
+    this.dispatchEvent(new CustomEvent("transition", {
+      detail: { from, to }
+    }));
+  }
+  forceStatus(status) {
+    this._status = status;
+  }
+  isTerminal() {
+    return this._status === "completed" || this._status === "failed";
+  }
+  canExecute() {
+    return this._status === "pending" || this._status === "paused";
+  }
+}
+
+// src/core/StepExecutor.ts
+class StepExecutor {
+  defaultRetries;
+  defaultTimeout;
+  constructor(options = {}) {
+    this.defaultRetries = options.defaultRetries ?? 3;
+    this.defaultTimeout = options.defaultTimeout ?? 30000;
+  }
+  async execute(step, ctx, execution) {
+    const maxRetries = step.retries ?? this.defaultRetries;
+    const timeout = step.timeout ?? this.defaultTimeout;
+    const startTime = Date.now();
+    if (step.when && !step.when(ctx)) {
+      execution.status = "skipped";
+      return {
+        success: true,
+        duration: 0
+      };
+    }
+    execution.status = "running";
+    execution.startedAt = new Date;
+    let lastError;
+    for (let attempt = 0;attempt <= maxRetries; attempt++) {
+      execution.retries = attempt;
+      try {
+        await this.executeWithTimeout(step.handler, ctx, timeout);
+        execution.status = "completed";
+        execution.completedAt = new Date;
+        execution.duration = Date.now() - startTime;
+        return {
+          success: true,
+          duration: execution.duration
+        };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < maxRetries) {
+          await this.sleep(Math.min(1000 * 2 ** attempt, 1e4));
+        }
+      }
+    }
+    execution.status = "failed";
+    execution.completedAt = new Date;
+    execution.duration = Date.now() - startTime;
+    execution.error = lastError?.message;
+    return {
+      success: false,
+      error: lastError,
+      duration: execution.duration
+    };
+  }
+  async executeWithTimeout(handler, ctx, timeout) {
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("Step timeout")), timeout);
+    });
+    await Promise.race([Promise.resolve(handler(ctx)), timeoutPromise]);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// src/storage/MemoryStorage.ts
+class MemoryStorage {
+  store = new Map;
+  async save(state) {
+    this.store.set(state.id, {
+      ...state,
+      updatedAt: new Date
+    });
+  }
+  async load(id) {
+    return this.store.get(id) ?? null;
+  }
+  async list(filter) {
+    let results = Array.from(this.store.values());
+    if (filter?.name) {
+      results = results.filter((s) => s.name === filter.name);
+    }
+    if (filter?.status) {
+      const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+      results = results.filter((s) => statuses.includes(s.status));
+    }
+    results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+    if (filter?.offset) {
+      results = results.slice(filter.offset);
+    }
+    if (filter?.limit) {
+      results = results.slice(0, filter.limit);
+    }
+    return results;
+  }
+  async delete(id) {
+    this.store.delete(id);
+  }
+  async init() {}
+  async close() {
+    this.store.clear();
+  }
+  size() {
+    return this.store.size;
+  }
+}
+
+// src/engine/FluxEngine.ts
+class FluxEngine {
+  storage;
+  executor;
+  contextManager;
+  config;
+  constructor(config = {}) {
+    this.config = config;
+    this.storage = config.storage ?? new MemoryStorage;
+    this.executor = new StepExecutor({
+      defaultRetries: config.defaultRetries,
+      defaultTimeout: config.defaultTimeout
+    });
+    this.contextManager = new ContextManager;
+  }
+  async execute(workflow, input) {
+    const startTime = Date.now();
+    const definition = workflow instanceof WorkflowBuilder ? workflow.build() : workflow;
+    if (definition.validateInput && !definition.validateInput(input)) {
+      throw new Error(`Invalid input for workflow "${definition.name}"`);
+    }
+    const ctx = this.contextManager.create(definition.name, input, definition.steps.length);
+    const stateMachine = new StateMachine;
+    await this.storage.save(this.contextManager.toState(ctx));
+    try {
+      stateMachine.transition("running");
+      Object.assign(ctx, { status: "running" });
+      for (let i = 0;i < definition.steps.length; i++) {
+        const step = definition.steps[i];
+        const execution = ctx.history[i];
+        this.contextManager.setStepName(ctx, i, step.name);
+        Object.assign(ctx, { currentStep: i });
+        this.config.on?.stepStart?.(step.name, ctx);
+        const result = await this.executor.execute(step, ctx, execution);
+        if (result.success) {
+          this.config.on?.stepComplete?.(step.name, ctx, result);
+        } else {
+          this.config.on?.stepError?.(step.name, ctx, result.error);
+          stateMachine.transition("failed");
+          Object.assign(ctx, { status: "failed" });
+          await this.storage.save({
+            ...this.contextManager.toState(ctx),
+            error: result.error?.message
+          });
+          return {
+            id: ctx.id,
+            status: "failed",
+            data: ctx.data,
+            history: ctx.history,
+            duration: Date.now() - startTime,
+            error: result.error
+          };
+        }
+        await this.storage.save(this.contextManager.toState(ctx));
+      }
+      stateMachine.transition("completed");
+      Object.assign(ctx, { status: "completed" });
+      await this.storage.save({
+        ...this.contextManager.toState(ctx),
+        completedAt: new Date
+      });
+      this.config.on?.workflowComplete?.(ctx);
+      return {
+        id: ctx.id,
+        status: "completed",
+        data: ctx.data,
+        history: ctx.history,
+        duration: Date.now() - startTime
+      };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.config.on?.workflowError?.(ctx, err);
+      stateMachine.forceStatus("failed");
+      Object.assign(ctx, { status: "failed" });
+      await this.storage.save({
+        ...this.contextManager.toState(ctx),
+        error: err.message
+      });
+      return {
+        id: ctx.id,
+        status: "failed",
+        data: ctx.data,
+        history: ctx.history,
+        duration: Date.now() - startTime,
+        error: err
+      };
+    }
+  }
+  async resume(workflowId) {
+    const state = await this.storage.load(workflowId);
+    if (!state) {
+      return null;
+    }
+    throw new Error("Resume not yet implemented");
+  }
+  async get(workflowId) {
+    return this.storage.load(workflowId);
+  }
+  async list(filter) {
+    return this.storage.list(filter);
+  }
+  async init() {
+    await this.storage.init?.();
+  }
+  async close() {
+    await this.storage.close?.();
+  }
+}
+// src/logger/FluxLogger.ts
+class FluxConsoleLogger {
+  prefix;
+  constructor(prefix = "[Flux]") {
+    this.prefix = prefix;
+  }
+  debug(message, ...args) {
+    console.debug(`${this.prefix} ${message}`, ...args);
+  }
+  info(message, ...args) {
+    console.info(`${this.prefix} ${message}`, ...args);
+  }
+  warn(message, ...args) {
+    console.warn(`${this.prefix} ${message}`, ...args);
+  }
+  error(message, ...args) {
+    console.error(`${this.prefix} ${message}`, ...args);
+  }
+}
+
+class FluxSilentLogger {
+  debug() {}
+  info() {}
+  warn() {}
+  error() {}
+}
+// src/storage/BunSQLiteStorage.ts
+import { Database } from "bun:sqlite";
+
+class BunSQLiteStorage {
+  db;
+  tableName;
+  initialized = false;
+  constructor(options = {}) {
+    this.db = new Database(options.path ?? ":memory:");
+    this.tableName = options.tableName ?? "flux_workflows";
+  }
+  async init() {
+    if (this.initialized) {
+      return;
+    }
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        status TEXT NOT NULL,
+        input TEXT NOT NULL,
+        data TEXT NOT NULL,
+        current_step INTEGER NOT NULL,
+        history TEXT NOT NULL,
+        error TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        completed_at TEXT
+      )
+    `);
+    this.db.run(`
+      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_name 
+      ON ${this.tableName}(name)
+    `);
+    this.db.run(`
+      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_status 
+      ON ${this.tableName}(status)
+    `);
+    this.db.run(`
+      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_created 
+      ON ${this.tableName}(created_at DESC)
+    `);
+    this.initialized = true;
+  }
+  async save(state) {
+    await this.init();
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO ${this.tableName} 
+      (id, name, status, input, data, current_step, history, error, created_at, updated_at, completed_at)
+      VALUES ($id, $name, $status, $input, $data, $currentStep, $history, $error, $createdAt, $updatedAt, $completedAt)
+    `);
+    stmt.run({
+      $id: state.id,
+      $name: state.name,
+      $status: state.status,
+      $input: JSON.stringify(state.input),
+      $data: JSON.stringify(state.data),
+      $currentStep: state.currentStep,
+      $history: JSON.stringify(state.history),
+      $error: state.error ?? null,
+      $createdAt: state.createdAt.toISOString(),
+      $updatedAt: state.updatedAt.toISOString(),
+      $completedAt: state.completedAt?.toISOString() ?? null
+    });
+  }
+  async load(id) {
+    await this.init();
+    const stmt = this.db.prepare(`
+      SELECT * FROM ${this.tableName} WHERE id = $id
+    `);
+    const row = stmt.get({ $id: id });
+    if (!row) {
+      return null;
+    }
+    return this.rowToState(row);
+  }
+  async list(filter) {
+    await this.init();
+    let query = `SELECT * FROM ${this.tableName} WHERE 1=1`;
+    const params = {};
+    if (filter?.name) {
+      query += " AND name = $name";
+      params.$name = filter.name;
+    }
+    if (filter?.status) {
+      if (Array.isArray(filter.status)) {
+        const placeholders = filter.status.map((_, i) => `$status${i}`).join(", ");
+        query += ` AND status IN (${placeholders})`;
+        filter.status.forEach((s, i) => {
+          params[`$status${i}`] = s;
+        });
+      } else {
+        query += " AND status = $status";
+        params.$status = filter.status;
+      }
+    }
+    query += " ORDER BY created_at DESC";
+    if (filter?.limit) {
+      query += " LIMIT $limit";
+      params.$limit = filter.limit;
+    }
+    if (filter?.offset) {
+      query += " OFFSET $offset";
+      params.$offset = filter.offset;
+    }
+    const stmt = this.db.prepare(query);
+    const rows = stmt.all(params);
+    return rows.map((row) => this.rowToState(row));
+  }
+  async delete(id) {
+    await this.init();
+    const stmt = this.db.prepare(`
+      DELETE FROM ${this.tableName} WHERE id = $id
+    `);
+    stmt.run({ $id: id });
+  }
+  async close() {
+    this.db.close();
+    this.initialized = false;
+  }
+  rowToState(row) {
+    return {
+      id: row.id,
+      name: row.name,
+      status: row.status,
+      input: JSON.parse(row.input),
+      data: JSON.parse(row.data),
+      currentStep: row.current_step,
+      history: JSON.parse(row.history),
+      error: row.error ?? undefined,
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at),
+      completedAt: row.completed_at ? new Date(row.completed_at) : undefined
+    };
+  }
+  getDatabase() {
+    return this.db;
+  }
+  vacuum() {
+    this.db.run("VACUUM");
+  }
+}
+
+// src/orbit/OrbitFlux.ts
+class OrbitFlux {
+  options;
+  engine;
+  constructor(options = {}) {
+    this.options = {
+      storage: "memory",
+      exposeAs: "flux",
+      defaultRetries: 3,
+      defaultTimeout: 30000,
+      ...options
+    };
+  }
+  static configure(options = {}) {
+    return new OrbitFlux(options);
+  }
+  async install(core) {
+    const { storage, dbPath, exposeAs, defaultRetries, defaultTimeout, logger } = this.options;
+    let storageAdapter;
+    if (typeof storage === "string") {
+      switch (storage) {
+        case "sqlite":
+          storageAdapter = new BunSQLiteStorage({ path: dbPath });
+          break;
+        default:
+          storageAdapter = new MemoryStorage;
+      }
+    } else {
+      storageAdapter = storage;
+    }
+    await storageAdapter.init?.();
+    const engineConfig = {
+      storage: storageAdapter,
+      defaultRetries,
+      defaultTimeout,
+      logger: logger ?? {
+        debug: (msg) => core.logger.debug(`[Flux] ${msg}`),
+        info: (msg) => core.logger.info(`[Flux] ${msg}`),
+        warn: (msg) => core.logger.warn(`[Flux] ${msg}`),
+        error: (msg) => core.logger.error(`[Flux] ${msg}`)
+      },
+      on: {
+        stepStart: (step) => {
+          core.hooks.doAction("flux:step:start", { step });
+        },
+        stepComplete: (step, ctx, result) => {
+          core.hooks.doAction("flux:step:complete", { step, ctx, result });
+        },
+        stepError: (step, ctx, error) => {
+          core.hooks.doAction("flux:step:error", { step, ctx, error });
+        },
+        workflowComplete: (ctx) => {
+          core.hooks.doAction("flux:workflow:complete", { ctx });
+        },
+        workflowError: (ctx, error) => {
+          core.hooks.doAction("flux:workflow:error", { ctx, error });
+        }
+      }
+    };
+    this.engine = new FluxEngine(engineConfig);
+    core.services.set(exposeAs, this.engine);
+    core.logger.info(`[OrbitFlux] Initialized (Storage: ${typeof storage === "string" ? storage : "custom"})`);
+  }
+  getEngine() {
+    return this.engine;
+  }
+}
+export {
+  createWorkflow,
+  WorkflowBuilder,
+  StepExecutor,
+  StateMachine,
+  OrbitFlux,
+  MemoryStorage,
+  FluxSilentLogger,
+  FluxEngine,
+  FluxConsoleLogger,
+  ContextManager
+};

package/dist/orbit/OrbitFlux.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview OrbitFlux - Gravito PlanetCore Integration
+ *
+ * Integrates FluxEngine with Gravito's PlanetCore for seamless workflow management.
+ *
+ * @module @gravito/flux
+ */
+import { FluxEngine } from '../engine/FluxEngine';
+import type { FluxLogger, WorkflowStorage } from '../types';
+/**
+ * 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
+ */
+export interface GravitoOrbit {
+    install(core: PlanetCore): void | Promise<void>;
+}
+/**
+ * OrbitFlux configuration options
+ */
+export 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)
+ * ```
+ */
+export 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 {};
+//# sourceMappingURL=OrbitFlux.d.ts.map