prepia 1.0.0

package/src/chain/dag.mjs

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview DAG (Directed Acyclic Graph) for task dependencies.
+ * @module chain/dag
+ */
+
+export class DAG {
+  constructor() {
+    /** @type {Map<string, Set<string>>} Adjacency list: node -> dependencies */
+    this._nodes = new Map();
+    /** @type {Map<string, *>} Node metadata */
+    this._metadata = new Map();
+  }
+
+  /**
+   * Add a node to the DAG.
+   * @param {string} id - Node ID
+   * @param {*} [metadata] - Optional metadata
+   */
+  addNode(id, metadata) {
+    if (!this._nodes.has(id)) {
+      this._nodes.set(id, new Set());
+    }
+    if (metadata !== undefined) {
+      this._metadata.set(id, metadata);
+    }
+  }
+
+  /**
+   * Add a dependency edge (from depends on to).
+   * @param {string} from - Dependent node
+   * @param {string} to - Dependency node
+   */
+  addEdge(from, to) {
+    this.addNode(from);
+    this.addNode(to);
+    // Check for cycle before adding
+    if (this._wouldCycle(from, to)) {
+      throw new Error(`Adding edge ${from} -> ${to} would create a cycle`);
+    }
+    this._nodes.get(from).add(to);
+  }
+
+  /**
+   * Check if adding an edge would create a cycle.
+   * @param {string} from
+   * @param {string} to
+   * @returns {boolean}
+   * @private
+   */
+  _wouldCycle(from, to) {
+    if (from === to) return true;
+    // BFS from to to see if we can reach from
+    const visited = new Set();
+    const queue = [to];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current === from) return true;
+      if (visited.has(current)) continue;
+      visited.add(current);
+      const deps = this._nodes.get(current);
+      if (deps) {
+        for (const dep of deps) {
+          queue.push(dep);
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Check if the DAG has a cycle.
+   * @returns {boolean}
+   */
+  hasCycle() {
+    const visited = new Set();
+    const inStack = new Set();
+
+    const dfs = (node) => {
+      if (inStack.has(node)) return true;
+      if (visited.has(node)) return false;
+      visited.add(node);
+      inStack.add(node);
+      const deps = this._nodes.get(node) || new Set();
+      for (const dep of deps) {
+        if (dfs(dep)) return true;
+      }
+      inStack.delete(node);
+      return false;
+    };
+
+    for (const node of this._nodes.keys()) {
+      if (dfs(node)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get topological order of nodes.
+   * @returns {string[]} Nodes in topological order
+   * @throws {Error} If cycle detected
+   */
+  topologicalSort() {
+    const visited = new Set();
+    const result = [];
+    const inStack = new Set();
+
+    const dfs = (node) => {
+      if (inStack.has(node)) throw new Error('Cycle detected in DAG');
+      if (visited.has(node)) return;
+      visited.add(node);
+      inStack.add(node);
+      const deps = this._nodes.get(node) || new Set();
+      for (const dep of deps) {
+        dfs(dep);
+      }
+      inStack.delete(node);
+      result.push(node);
+    };
+
+    for (const node of this._nodes.keys()) {
+      dfs(node);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get nodes with no dependencies (roots).
+   * @returns {string[]}
+   */
+  getRoots() {
+    const hasDeps = new Set();
+    for (const deps of this._nodes.values()) {
+      for (const dep of deps) {
+        hasDeps.add(dep);
+      }
+    }
+    return Array.from(this._nodes.keys()).filter(n => !hasDeps.has(n));
+  }
+
+  /**
+   * Get dependencies of a node.
+   * @param {string} id
+   * @returns {string[]}
+   */
+  getDependencies(id) {
+    return Array.from(this._nodes.get(id) || []);
+  }
+
+  /**
+   * Get nodes that depend on a given node.
+   * @param {string} id
+   * @returns {string[]}
+   */
+  getDependents(id) {
+    const result = [];
+    for (const [node, deps] of this._nodes) {
+      if (deps.has(id)) result.push(node);
+    }
+    return result;
+  }
+
+  /**
+   * Get metadata for a node.
+   * @param {string} id
+   * @returns {*}
+   */
+  getMetadata(id) {
+    return this._metadata.get(id);
+  }
+
+  /**
+   * Get all node IDs.
+   * @returns {string[]}
+   */
+  getNodes() {
+    return Array.from(this._nodes.keys());
+  }
+
+  /**
+   * Get the number of nodes.
+   * @returns {number}
+   */
+  get size() {
+    return this._nodes.size;
+  }
+
+  /**
+   * Remove a node and all its edges.
+   * @param {string} id
+   */
+  removeNode(id) {
+    this._nodes.delete(id);
+    this._metadata.delete(id);
+    for (const deps of this._nodes.values()) {
+      deps.delete(id);
+    }
+  }
+
+  /**
+   * Clear the entire DAG.
+   */
+  clear() {
+    this._nodes.clear();
+    this._metadata.clear();
+  }
+}
+
+export default DAG;

package/src/chain/executor.mjs

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Task execution engine with retry support.
+ * @module chain/executor
+ */
+
+import { EventEmitter } from 'node:events';
+
+export class Executor extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.maxRetries=3] - Max retry attempts
+   * @param {number} [options.retryDelay=1000] - Base retry delay in ms
+   * @param {number} [options.timeout=30000] - Task timeout in ms
+   */
+  constructor(options = {}) {
+    super();
+    this._maxRetries = options.maxRetries ?? 3;
+    this._retryDelay = options.retryDelay ?? 1000;
+    this._timeout = options.timeout ?? 30000;
+    this._taskHandlers = new Map();
+  }
+
+  /**
+   * Register a task handler.
+   * @param {string} type - Task type
+   * @param {Function} handler - Async handler function(params) => result
+   */
+  register(type, handler) {
+    this._taskHandlers.set(type, handler);
+  }
+
+  /**
+   * Execute a single task with retries.
+   * @param {Object} task
+   * @param {string} task.id - Task ID
+   * @param {string} task.type - Task type
+   * @param {Object} [task.params] - Task parameters
+   * @returns {Promise<*>}
+   */
+  async execute(task) {
+    const handler = this._taskHandlers.get(task.type);
+    if (!handler) {
+      throw new Error(`No handler registered for task type: ${task.type}`);
+    }
+
+    let lastError;
+    for (let attempt = 0; attempt <= this._maxRetries; attempt++) {
+      try {
+        this.emit('task:attempt', { id: task.id, attempt });
+        const result = await Promise.race([
+          handler(task.params || {}),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Task timeout')), this._timeout)
+          ),
+        ]);
+        this.emit('task:success', { id: task.id, attempt });
+        return result;
+      } catch (err) {
+        lastError = err;
+        this.emit('task:retry', { id: task.id, attempt, error: err.message });
+        if (attempt < this._maxRetries) {
+          await new Promise(r => setTimeout(r, this._retryDelay * Math.pow(2, attempt)));
+        }
+      }
+    }
+
+    this.emit('task:failed', { id: task.id, error: lastError?.message });
+    throw new Error(`Task ${task.id} failed after ${this._maxRetries + 1} attempts: ${lastError?.message}`);
+  }
+
+  /**
+   * Execute multiple tasks in parallel.
+   * @param {Object[]} tasks
+   * @param {number} [concurrency=5]
+   * @returns {Promise<Map<string, *>>}
+   */
+  async executeAll(tasks, concurrency = 5) {
+    const results = new Map();
+    const executing = new Set();
+
+    for (const task of tasks) {
+      const promise = this.execute(task)
+        .then(result => {
+          executing.delete(promise);
+          results.set(task.id, result);
+        })
+        .catch(err => {
+          executing.delete(promise);
+          results.set(task.id, { error: err.message });
+        });
+      executing.add(promise);
+
+      if (executing.size >= concurrency) {
+        await Promise.race(executing);
+      }
+    }
+
+    await Promise.all(executing);
+    return results;
+  }
+}
+
+export default Executor;

package/src/chain/scheduler.mjs

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Parallel task scheduler respecting DAG dependencies.
+ * @module chain/scheduler
+ */
+
+import { EventEmitter } from 'node:events';
+
+export class Scheduler extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.maxConcurrency=5] - Max parallel tasks
+   */
+  constructor(options = {}) {
+    super();
+    this._maxConcurrency = options.maxConcurrency ?? 5;
+  }
+
+  /**
+   * Schedule and execute tasks respecting dependencies.
+   * @param {import('./dag.mjs').DAG} dag - Task dependency graph
+   * @param {Function} executor - Async function(taskId) => result
+   * @returns {Promise<Map<string, *>>} Results map
+   */
+  async schedule(dag, executor) {
+    const results = new Map();
+    const completed = new Set();
+    const failed = new Set();
+    const running = new Set();
+    const pending = new Set(dag.getNodes());
+
+    const getReady = () => {
+      const ready = [];
+      for (const nodeId of pending) {
+        if (running.has(nodeId) || failed.has(nodeId)) continue;
+        const deps = dag.getDependencies(nodeId);
+        const allDepsResolved = deps.every(d => completed.has(d) || failed.has(d));
+        const noDepsFailed = deps.every(d => !failed.has(d));
+        if (allDepsResolved && noDepsFailed) {
+          ready.push(nodeId);
+        }
+      }
+      return ready;
+    };
+
+    return new Promise((resolve) => {
+      const trySchedule = () => {
+        if (completed.size + failed.size === dag.size) {
+          resolve(results);
+          return;
+        }
+
+        const ready = getReady();
+        for (const nodeId of ready) {
+          if (running.size >= this._maxConcurrency) break;
+          if (running.has(nodeId)) continue;
+
+          running.add(nodeId);
+          pending.delete(nodeId);
+          this.emit('task:start', { nodeId });
+
+          executor(nodeId, dag.getMetadata(nodeId))
+            .then(result => {
+              results.set(nodeId, result);
+              completed.add(nodeId);
+              running.delete(nodeId);
+              this.emit('task:complete', { nodeId, result });
+              trySchedule();
+            })
+            .catch(err => {
+              results.set(nodeId, { error: err.message });
+              failed.add(nodeId);
+              running.delete(nodeId);
+              this.emit('task:error', { nodeId, error: err.message });
+              trySchedule();
+            });
+        }
+
+        // If nothing is running and nothing is ready, we're stuck
+        if (running.size === 0 && getReady().length === 0) {
+          resolve(results);
+        }
+      };
+
+      trySchedule();
+    });
+  }
+}
+
+export default Scheduler;