@gravito/flux 3.0.1 → 3.0.3

package/dist/{chunk-ZAMVC732.js → chunk-EZGSU6AW.js}

@@ -4,12 +4,21 @@ var BunSQLiteStorage = class {
   db;
   tableName;
   initialized = false;
+  /**
+   * Creates a new instance of BunSQLiteStorage.
+   *
+   * @param options - Configuration for the database connection and table naming.
+   */
   constructor(options = {}) {
     this.db = new Database(options.path ?? ":memory:");
-    this.tableName = options.tableName ?? "flux_workflows";
+    this.tableName = validateSqlIdentifier(options.tableName ?? "flux_workflows", "tableName");
   }
   /**
-   * Initialize storage (create tables)
+   * Initializes the database schema and required indexes.
+   *
+   * This method is idempotent and will be called automatically by other operations if not invoked manually.
+   *
+   * @throws {Error} If the database schema cannot be created or indexes fail to initialize.
    */
   async init() {
     if (this.initialized) {
@@ -27,7 +36,9 @@ var BunSQLiteStorage = class {
         error TEXT,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL,
-        completed_at TEXT
+        completed_at TEXT,
+        version INTEGER NOT NULL DEFAULT 1,
+        definition_version TEXT
       )
     `);
     this.db.run(`
@@ -45,14 +56,19 @@ var BunSQLiteStorage = class {
     this.initialized = true;
   }
   /**
-   * Save workflow state
+   * Persists or updates a workflow state in the database.
+   *
+   * Uses an "INSERT OR REPLACE" strategy to ensure the latest state is always stored for a given ID.
+   *
+   * @param state - The current state of the workflow to be saved.
+   * @throws {Error} If the database write operation fails or serialization errors occur.
    */
   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)
+      (id, name, status, input, data, current_step, history, error, created_at, updated_at, completed_at, version, definition_version)
+      VALUES ($id, $name, $status, $input, $data, $currentStep, $history, $error, $createdAt, $updatedAt, $completedAt, $version, $definitionVersion)
     `);
     stmt.run({
       $id: state.id,
@@ -65,11 +81,17 @@ var BunSQLiteStorage = class {
       $error: state.error ?? null,
       $createdAt: state.createdAt.toISOString(),
       $updatedAt: state.updatedAt.toISOString(),
-      $completedAt: state.completedAt?.toISOString() ?? null
+      $completedAt: state.completedAt?.toISOString() ?? null,
+      $version: state.version,
+      $definitionVersion: state.definitionVersion ?? null
     });
   }
   /**
-   * Load workflow state by ID
+   * Retrieves a workflow state by its unique identifier.
+   *
+   * @param id - The unique ID of the workflow to load.
+   * @returns The reconstructed workflow state, or null if no record is found.
+   * @throws {Error} If the database query fails or deserialization of stored JSON fails.
    */
   async load(id) {
     await this.init();
@@ -83,7 +105,13 @@ var BunSQLiteStorage = class {
     return this.rowToState(row);
   }
   /**
-   * List workflow states with optional filter
+   * Lists workflow states based on the provided filtering criteria.
+   *
+   * Results are returned in descending order of creation time.
+   *
+   * @param filter - Criteria for filtering and paginating the results.
+   * @returns An array of workflow states matching the filter.
+   * @throws {Error} If the database query fails.
    */
   async list(filter) {
     await this.init();
@@ -105,6 +133,10 @@ var BunSQLiteStorage = class {
         params.$status = filter.status;
       }
     }
+    if (filter?.version) {
+      query += " AND definition_version = $version";
+      params.$version = filter.version;
+    }
     query += " ORDER BY created_at DESC";
     if (filter?.limit) {
       query += " LIMIT $limit";
@@ -119,7 +151,10 @@ var BunSQLiteStorage = class {
     return rows.map((row) => this.rowToState(row));
   }
   /**
-   * Delete workflow state
+   * Deletes a workflow state from the database.
+   *
+   * @param id - The unique ID of the workflow to delete.
+   * @throws {Error} If the database deletion fails.
    */
   async delete(id) {
     await this.init();
@@ -129,14 +164,20 @@ var BunSQLiteStorage = class {
     stmt.run({ $id: id });
   }
   /**
-   * Close database connection
+   * Closes the database connection and resets the initialization state.
+   *
+   * @throws {Error} If the database connection cannot be closed cleanly.
    */
   async close() {
     this.db.close();
     this.initialized = false;
   }
   /**
-   * Convert SQLite row to WorkflowState
+   * Converts a raw database row into a structured WorkflowState object.
+   *
+   * @param row - The raw SQLite row data.
+   * @returns The parsed workflow state.
+   * @private
    */
   rowToState(row) {
     return {
@@ -150,24 +191,40 @@ var BunSQLiteStorage = class {
       error: row.error ?? void 0,
       createdAt: new Date(row.created_at),
       updatedAt: new Date(row.updated_at),
-      completedAt: row.completed_at ? new Date(row.completed_at) : void 0
+      completedAt: row.completed_at ? new Date(row.completed_at) : void 0,
+      version: row.version,
+      definitionVersion: row.definition_version ?? void 0
     };
   }
   /**
-   * Get raw database (for advanced usage)
+   * Provides direct access to the underlying Bun SQLite Database instance.
+   *
+   * Useful for performing custom queries or maintenance tasks.
+   *
+   * @returns The raw Database instance.
    */
   getDatabase() {
     return this.db;
   }
   /**
-   * Run a vacuum to optimize database
+   * Performs a VACUUM operation to reclaim unused space and defragment the database.
+   *
+   * @throws {Error} If the VACUUM operation fails.
    */
   vacuum() {
     this.db.run("VACUUM");
   }
 };
+function validateSqlIdentifier(value, field) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(
+      `Invalid ${field}: "${value}". Only letters, numbers, and underscores are allowed.`
+    );
+  }
+  return value;
+}
 
 export {
   BunSQLiteStorage
 };
-//# sourceMappingURL=chunk-ZAMVC732.js.map
+//# sourceMappingURL=chunk-EZGSU6AW.js.map

package/dist/chunk-EZGSU6AW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage/BunSQLiteStorage.ts"],"sourcesContent":["import { Database } from 'bun:sqlite'\nimport type { WorkflowFilter, WorkflowState, WorkflowStorage } from '../types'\n\n/**\n * Configuration options for the Bun SQLite storage adapter.\n */\nexport interface BunSQLiteStorageOptions {\n  /**\n   * Path to the SQLite database file.\n   * Use ':memory:' for an ephemeral in-memory database.\n   */\n  path?: string\n  /**\n   * Name of the table used to store workflow states.\n   */\n  tableName?: string\n}\n\n/**\n * BunSQLiteStorage provides a persistent storage backend for Flux workflows using Bun's native SQLite module.\n *\n * It handles automatic table creation, indexing for performance, and serialization of workflow state\n * into a relational format.\n *\n * @example\n * ```typescript\n * const storage = new BunSQLiteStorage({\n *   path: './workflows.db',\n *   tableName: 'my_workflows'\n * });\n * await storage.init();\n * ```\n */\nexport class BunSQLiteStorage implements WorkflowStorage {\n  private db: Database\n  private tableName: string\n  private initialized = false\n\n  /**\n   * Creates a new instance of BunSQLiteStorage.\n   *\n   * @param options - Configuration for the database connection and table naming.\n   */\n  constructor(options: BunSQLiteStorageOptions = {}) {\n    this.db = new Database(options.path ?? ':memory:')\n    this.tableName = validateSqlIdentifier(options.tableName ?? 'flux_workflows', 'tableName')\n  }\n\n  /**\n   * Initializes the database schema and required indexes.\n   *\n   * This method is idempotent and will be called automatically by other operations if not invoked manually.\n   *\n   * @throws {Error} If the database schema cannot be created or indexes fail to initialize.\n   */\n  async init(): Promise<void> {\n    if (this.initialized) {\n      return\n    }\n\n    this.db.run(`\n      CREATE TABLE IF NOT EXISTS ${this.tableName} (\n        id TEXT PRIMARY KEY,\n        name TEXT NOT NULL,\n        status TEXT NOT NULL,\n        input TEXT NOT NULL,\n        data TEXT NOT NULL,\n        current_step INTEGER NOT NULL,\n        history TEXT NOT NULL,\n        error TEXT,\n        created_at TEXT NOT NULL,\n        updated_at TEXT NOT NULL,\n        completed_at TEXT,\n        version INTEGER NOT NULL DEFAULT 1,\n        definition_version TEXT\n      )\n    `)\n\n    this.db.run(`\n      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_name \n      ON ${this.tableName}(name)\n    `)\n    this.db.run(`\n      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_status \n      ON ${this.tableName}(status)\n    `)\n    this.db.run(`\n      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_created \n      ON ${this.tableName}(created_at DESC)\n    `)\n\n    this.initialized = true\n  }\n\n  /**\n   * Persists or updates a workflow state in the database.\n   *\n   * Uses an \"INSERT OR REPLACE\" strategy to ensure the latest state is always stored for a given ID.\n   *\n   * @param state - The current state of the workflow to be saved.\n   * @throws {Error} If the database write operation fails or serialization errors occur.\n   */\n  async save(state: WorkflowState): Promise<void> {\n    await this.init()\n\n    const stmt = this.db.prepare(`\n      INSERT OR REPLACE INTO ${this.tableName} \n      (id, name, status, input, data, current_step, history, error, created_at, updated_at, completed_at, version, definition_version)\n      VALUES ($id, $name, $status, $input, $data, $currentStep, $history, $error, $createdAt, $updatedAt, $completedAt, $version, $definitionVersion)\n    `)\n\n    stmt.run({\n      $id: state.id,\n      $name: state.name,\n      $status: state.status,\n      $input: JSON.stringify(state.input),\n      $data: JSON.stringify(state.data),\n      $currentStep: state.currentStep,\n      $history: JSON.stringify(state.history),\n      $error: state.error ?? null,\n      $createdAt: state.createdAt.toISOString(),\n      $updatedAt: state.updatedAt.toISOString(),\n      $completedAt: state.completedAt?.toISOString() ?? null,\n      $version: state.version,\n      $definitionVersion: state.definitionVersion ?? null,\n    })\n  }\n\n  /**\n   * Retrieves a workflow state by its unique identifier.\n   *\n   * @param id - The unique ID of the workflow to load.\n   * @returns The reconstructed workflow state, or null if no record is found.\n   * @throws {Error} If the database query fails or deserialization of stored JSON fails.\n   */\n  async load(id: string): Promise<WorkflowState | null> {\n    await this.init()\n\n    const stmt = this.db.prepare(`\n      SELECT * FROM ${this.tableName} WHERE id = $id\n    `)\n\n    const row = stmt.get({ $id: id }) as SQLiteRow | null\n\n    if (!row) {\n      return null\n    }\n\n    return this.rowToState(row)\n  }\n\n  /**\n   * Lists workflow states based on the provided filtering criteria.\n   *\n   * Results are returned in descending order of creation time.\n   *\n   * @param filter - Criteria for filtering and paginating the results.\n   * @returns An array of workflow states matching the filter.\n   * @throws {Error} If the database query fails.\n   */\n  async list(filter?: WorkflowFilter): Promise<WorkflowState[]> {\n    await this.init()\n\n    let query = `SELECT * FROM ${this.tableName} WHERE 1=1`\n    const params: Record<string, unknown> = {}\n\n    if (filter?.name) {\n      query += ' AND name = $name'\n      params.$name = filter.name\n    }\n\n    if (filter?.status) {\n      if (Array.isArray(filter.status)) {\n        const placeholders = filter.status.map((_, i) => `$status${i}`).join(', ')\n        query += ` AND status IN (${placeholders})`\n        filter.status.forEach((s, i) => {\n          params[`$status${i}`] = s\n        })\n      } else {\n        query += ' AND status = $status'\n        params.$status = filter.status\n      }\n    }\n\n    if (filter?.version) {\n      query += ' AND definition_version = $version'\n      params.$version = filter.version\n    }\n\n    query += ' ORDER BY created_at DESC'\n\n    if (filter?.limit) {\n      query += ' LIMIT $limit'\n      params.$limit = filter.limit\n    }\n\n    if (filter?.offset) {\n      query += ' OFFSET $offset'\n      params.$offset = filter.offset\n    }\n\n    const stmt = this.db.prepare(query)\n    const rows = stmt.all(params as Record<string, any>) as SQLiteRow[]\n\n    return rows.map((row) => this.rowToState(row))\n  }\n\n  /**\n   * Deletes a workflow state from the database.\n   *\n   * @param id - The unique ID of the workflow to delete.\n   * @throws {Error} If the database deletion fails.\n   */\n  async delete(id: string): Promise<void> {\n    await this.init()\n\n    const stmt = this.db.prepare(`\n      DELETE FROM ${this.tableName} WHERE id = $id\n    `)\n\n    stmt.run({ $id: id })\n  }\n\n  /**\n   * Closes the database connection and resets the initialization state.\n   *\n   * @throws {Error} If the database connection cannot be closed cleanly.\n   */\n  async close(): Promise<void> {\n    this.db.close()\n    this.initialized = false\n  }\n\n  /**\n   * Converts a raw database row into a structured WorkflowState object.\n   *\n   * @param row - The raw SQLite row data.\n   * @returns The parsed workflow state.\n   * @private\n   */\n  private rowToState(row: SQLiteRow): WorkflowState {\n    return {\n      id: row.id,\n      name: row.name,\n      status: row.status as WorkflowState['status'],\n      input: JSON.parse(row.input),\n      data: JSON.parse(row.data),\n      currentStep: row.current_step,\n      history: JSON.parse(row.history),\n      error: row.error ?? undefined,\n      createdAt: new Date(row.created_at),\n      updatedAt: new Date(row.updated_at),\n      completedAt: row.completed_at ? new Date(row.completed_at) : undefined,\n      version: row.version,\n      definitionVersion: row.definition_version ?? undefined,\n    }\n  }\n\n  /**\n   * Provides direct access to the underlying Bun SQLite Database instance.\n   *\n   * Useful for performing custom queries or maintenance tasks.\n   *\n   * @returns The raw Database instance.\n   */\n  getDatabase(): Database {\n    return this.db\n  }\n\n  /**\n   * Performs a VACUUM operation to reclaim unused space and defragment the database.\n   *\n   * @throws {Error} If the VACUUM operation fails.\n   */\n  vacuum(): void {\n    this.db.run('VACUUM')\n  }\n}\n\nfunction validateSqlIdentifier(value: string, field: string): string {\n  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {\n    throw new Error(\n      `Invalid ${field}: \"${value}\". Only letters, numbers, and underscores are allowed.`\n    )\n  }\n  return value\n}\n\n/**\n * Internal representation of a workflow record in the SQLite database.\n */\ninterface SQLiteRow {\n  id: string\n  name: string\n  status: string\n  input: string\n  data: string\n  current_step: number\n  history: string\n  error: string | null\n  created_at: string\n  updated_at: string\n  completed_at: string | null\n  version: number\n  definition_version: string | null\n}\n"],"mappings":"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","names":[]}