flowcraft 1.0.0 → 2.1.0

package/dist/chunk-HEO3XL4Z.js

@@ -1,328 +0,0 @@
-import { sleep } from './chunk-6QCXIRLA.js';
-import { InMemoryExecutor } from './chunk-BRFMFLR6.js';
-import { AbstractNode } from './chunk-VZDHIOCH.js';
-import { getFlowConstructor } from './chunk-S4WFNGQG.js';
-import { AbortError, WorkflowError, FatalWorkflowError } from './chunk-64DNBF5W.js';
-import { NullLogger } from './chunk-IIKTTIW5.js';
-import { DEFAULT_ACTION, FILTER_FAILED } from './chunk-AOHBHYF6.js';
-
-// src/workflow/Node.ts
-var Node = class _Node extends AbstractNode {
-  /** The total number of times the `exec` phase will be attempted. */
-  maxRetries;
-  /** The time in milliseconds to wait between failed `exec` attempts. */
-  wait;
-  /**
-   * @param options Configuration options for the node's behavior.
-   * @param options.maxRetries Total number of `exec` attempts. Defaults to `1`.
-   * @param options.wait Milliseconds to wait between failed `exec` attempts. Defaults to `0`.
-   */
-  constructor(options = {}) {
-    super();
-    this.maxRetries = options.maxRetries ?? 1;
-    this.wait = options.wait ?? 0;
-  }
-  _wrapError(e, phase) {
-    if (e instanceof AbortError || e instanceof WorkflowError)
-      return e;
-    return new WorkflowError(`Failed in ${phase} phase for node ${this.constructor.name}`, this.constructor.name, phase, e);
-  }
-  /**
-   * (Lifecycle) Prepares data for execution. Runs once before `exec`.
-   * This is the ideal place to read data from the `Context`.
-   * @param args The arguments for the node, including `ctx` and `params`.
-   * @returns The data required by the `exec` phase.
-   */
-  async prep(args) {
-    return void 0;
-  }
-  /**
-   * (Lifecycle) Performs the core, isolated logic of the node.
-   * This is the only phase that is retried on failure. It should not access the `Context` directly.
-   * @param args The arguments for the node, including `prepRes`.
-   * @returns The result of the execution.
-   */
-  async exec(args) {
-    return void 0;
-  }
-  /**
-   * (Lifecycle) Processes results and determines the next step. Runs once after `exec` succeeds.
-   * This is the ideal place to write data to the `Context`.
-   * @param args The arguments for the node, including `execRes`.
-   * @returns An "action" string to determine which successor to execute next. Defaults to `DEFAULT_ACTION`.
-   */
-  async post(args) {
-    return DEFAULT_ACTION;
-  }
-  /**
-   * (Lifecycle) A fallback that runs if all `exec` retries fail.
-   * If not implemented, the final error will be re-thrown, halting the workflow.
-   * @param args The arguments for the node, including the final `error` that caused the failure.
-   * @returns A fallback result of type `ExecRes`, allowing the workflow to recover and continue.
-   */
-  async execFallback(args) {
-    if (args.error)
-      throw args.error;
-    throw new Error(`Node ${this.constructor.name} failed and has no fallback implementation.`);
-  }
-  /**
-   * The internal retry-aware execution logic for the `exec` phase.
-   * @internal
-   */
-  async _exec(args) {
-    let lastError;
-    for (let curRetry = 0; curRetry < this.maxRetries; curRetry++) {
-      if (args.signal?.aborted)
-        throw new AbortError();
-      try {
-        return await this.exec(args);
-      } catch (e) {
-        const error = e;
-        lastError = error;
-        if (error instanceof FatalWorkflowError)
-          throw error;
-        if (error instanceof AbortError || error.name === "AbortError")
-          throw error;
-        if (curRetry < this.maxRetries - 1) {
-          args.logger.warn(`Attempt ${curRetry + 1}/${this.maxRetries} failed for ${this.constructor.name}. Retrying...`, { error });
-          if (this.wait > 0)
-            await sleep(this.wait, args.signal);
-        }
-      }
-    }
-    args.logger.error(`All retries failed for ${this.constructor.name}. Executing fallback.`, { error: lastError });
-    if (args.signal?.aborted)
-      throw new AbortError();
-    return await this.execFallback({ ...args, error: lastError });
-  }
-  /**
-   * The internal method that executes the node's full lifecycle.
-   * @internal
-   */
-  async _run({ ctx, params, signal, logger, executor, visitedInParallel }) {
-    if (signal?.aborted)
-      throw new AbortError();
-    let prepRes;
-    try {
-      prepRes = await this.prep({ ctx, params, signal, logger, prepRes: void 0, execRes: void 0, executor, visitedInParallel });
-    } catch (e) {
-      throw this._wrapError(e, "prep");
-    }
-    if (signal?.aborted)
-      throw new AbortError();
-    let execRes;
-    try {
-      execRes = await this._exec({ ctx, params, signal, logger, prepRes, execRes: void 0, executor, visitedInParallel });
-    } catch (e) {
-      throw this._wrapError(e, "exec");
-    }
-    if (signal?.aborted)
-      throw new AbortError();
-    try {
-      const action = await this.post({ ctx, params, signal, logger, prepRes, execRes, executor, visitedInParallel });
-      return action === void 0 ? DEFAULT_ACTION : action;
-    } catch (e) {
-      throw this._wrapError(e, "post");
-    }
-  }
-  /**
-   * Runs the node as a standalone unit, independent of a larger flow.
-   * This is useful for testing individual nodes in isolation.
-   *
-   * @param ctx The shared workflow context.
-   * @param options Runtime options like a logger or abort controller.
-   * @returns The result of the node's `post` method (its action).
-   */
-  async run(ctx, options) {
-    const Flow = getFlowConstructor();
-    const logger = options?.logger ?? new NullLogger();
-    if (this.successors.size > 0 && !(this instanceof Flow))
-      logger.warn("Node.run() called directly on a node with successors. The flow will not continue. Use a Flow to execute a sequence.");
-    const executor = options?.executor ?? new InMemoryExecutor();
-    return executor.run(new Flow(this), ctx, { ...options, params: this.params });
-  }
-  /**
-   * Creates a new node that transforms the result of this node's `exec` phase.
-   *
-   * @remarks
-   * This method returns a **new** `Node` instance and does not modify the original.
-   * The new node inherits the original's `prep` method. The original `post` method
-   * is discarded as it is incompatible with the new result type.
-   *
-   * @example
-   * const fetchUserNode = new FetchUserNode() // returns { id: 1, name: 'Alice' }
-   * const getUserNameNode = fetchUserNode.map(user => user.name) // returns 'Alice'
-   *
-   * @param fn A sync or async function to transform the execution result from `ExecRes` to `NewRes`.
-   * @returns A new `Node` instance with the transformed output type.
-   */
-  map(fn) {
-    const originalNode = this;
-    const maxRetries = this.maxRetries;
-    const wait = this.wait;
-    return new class extends _Node {
-      constructor() {
-        super({ maxRetries, wait });
-      }
-      async prep(args) {
-        return originalNode.prep(args);
-      }
-      async exec(args) {
-        const originalResult = await originalNode.exec(args);
-        return fn(originalResult);
-      }
-      async post(_args) {
-        return DEFAULT_ACTION;
-      }
-    }();
-  }
-  /**
-   * Creates a new node that stores the result of this node's `exec` phase in the `Context`.
-   * This is a common terminal operation for a data processing chain.
-   *
-   * @remarks
-   * This method returns a **new** `Node` instance and does not modify the original.
-   *
-   * @example
-   * const USER_NAME = contextKey<string>('user_name')
-   * const workflow = new FetchUserNode()
-   *   .map(user => user.name)
-   *   .toContext(USER_NAME)
-   *
-   * @param key The type-safe `ContextKey` to use for storing the result.
-   * @returns A new `Node` instance that performs the context update in its `post` phase.
-   */
-  toContext(key) {
-    const originalNode = this;
-    const maxRetries = this.maxRetries;
-    const wait = this.wait;
-    return new class extends _Node {
-      constructor() {
-        super({ maxRetries, wait });
-      }
-      async prep(args) {
-        return originalNode.prep(args);
-      }
-      async exec(args) {
-        return originalNode.exec(args);
-      }
-      async post(args) {
-        args.ctx.set(key, args.execRes);
-        return DEFAULT_ACTION;
-      }
-    }();
-  }
-  /**
-   * Creates a new node that acts as a conditional gate based on the `exec` result.
-   * If the predicate returns `true`, the node returns `DEFAULT_ACTION`.
-   * If it returns `false`, the node returns `FILTER_FAILED`, enabling branching.
-   *
-   * @remarks
-   * This method returns a **new** `Node` instance and does not modify the original.
-   *
-   * @example
-   * const checkAdminNode = new FetchUserNode().filter(user => user.isAdmin)
-   *
-   * checkAdminNode.next(adminOnlyNode, DEFAULT_ACTION)
-   * checkAdminNode.next(accessDeniedNode, FILTER_FAILED)
-   *
-   * @param predicate A sync or async function that returns `true` or `false`.
-   * @returns A new `Node` instance that implements the filter logic.
-   */
-  filter(predicate) {
-    const originalNode = this;
-    return new class extends _Node {
-      didPass = false;
-      async prep(args) {
-        return originalNode.prep(args);
-      }
-      async exec(args) {
-        const result = await originalNode.exec(args);
-        this.didPass = await predicate(result);
-        if (!this.didPass)
-          args.logger.debug(`[Filter] Predicate failed for node ${this.constructor.name}.`);
-        return result;
-      }
-      async post(_args) {
-        return this.didPass ? DEFAULT_ACTION : FILTER_FAILED;
-      }
-    }();
-  }
-  /**
-   * Creates a new node that performs a side effect with the `exec` result,
-   * but passes the original result through unmodified. Ideal for logging or debugging.
-   *
-   * @remarks
-   * This method returns a **new** `Node` instance and does not modify the original.
-   *
-   * @example
-   * const workflow = new FetchUserNode()
-   *   .tap(user => console.log('Fetched User:', user))
-   *   .map(user => user.id)
-   *
-   * @param fn A function to call with the execution result for its side effect.
-   * @returns A new `Node` instance that wraps the original.
-   */
-  tap(fn) {
-    const originalNode = this;
-    const maxRetries = this.maxRetries;
-    const wait = this.wait;
-    return new class extends _Node {
-      constructor() {
-        super({ maxRetries, wait });
-      }
-      async prep(args) {
-        return originalNode.prep(args);
-      }
-      async exec(args) {
-        const originalResult = await originalNode.exec(args);
-        await fn(originalResult);
-        return originalResult;
-      }
-      async post(args) {
-        return originalNode.post(args);
-      }
-    }();
-  }
-  /**
-   * Creates a new node that applies a context mutation using a lens before executing.
-   * This allows for declaratively setting or updating context as part of a fluent chain.
-   *
-   * @remarks
-   * This method returns a **new** `Node` instance and does not modify the original.
-   *
-   * @example
-   * const VALUE = contextKey<number>('value')
-   * const valueLens = lens(VALUE)
-   *
-   * const nodeWithLens = new SomeNode().withLens(valueLens, 42) // Sets VALUE to 42 before SomeNode runs
-   *
-   * @param lens The `ContextLens` to use for the operation.
-   * @param value The value to set in the context via the lens.
-   * @returns A new `Node` instance that applies the context change.
-   */
-  withLens(lens, value) {
-    const originalNode = this;
-    const maxRetries = this.maxRetries;
-    const wait = this.wait;
-    return new class extends _Node {
-      constructor() {
-        super({ maxRetries, wait });
-      }
-      async prep(args) {
-        await lens.set(value)(args.ctx);
-        return originalNode.prep(args);
-      }
-      async exec(args) {
-        return originalNode.exec(args);
-      }
-      async post(args) {
-        return originalNode.post(args);
-      }
-    }();
-  }
-};
-
-export { Node };
-//# sourceMappingURL=chunk-HEO3XL4Z.js.map
-//# sourceMappingURL=chunk-HEO3XL4Z.js.map

package/dist/chunk-HEO3XL4Z.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/workflow/Node.ts"],"names":[],"mappings":";;;;;;;;;AAsBO,IAAM,IAAA,GAAN,MAAM,KAAA,SAMH,YAAA,CAAyC;AAAA;AAAA,EAE3C,UAAA;AAAA;AAAA,EAEA,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOP,WAAA,CAAY,OAAA,GAAuB,EAAC,EAAG;AACtC,IAAA,KAAA,EAAM;AACN,IAAA,IAAA,CAAK,UAAA,GAAa,QAAQ,UAAA,IAAc,CAAA;AACxC,IAAA,IAAA,CAAK,IAAA,GAAO,QAAQ,IAAA,IAAQ,CAAA;AAAA,EAC7B;AAAA,EAEU,UAAA,CAAW,GAAQ,KAAA,EAAwC;AACpE,IAAA,IAAI,CAAA,YAAa,cAAc,CAAA,YAAa,aAAA;AAC3C,MAAA,OAAO,CAAA;AAER,IAAA,OAAO,IAAI,aAAA,CAAc,CAAA,UAAA,EAAa,KAAK,CAAA,gBAAA,EAAmB,IAAA,CAAK,WAAA,CAAY,IAAI,CAAA,CAAA,EAAI,IAAA,CAAK,WAAA,CAAY,IAAA,EAAM,OAAO,CAAU,CAAA;AAAA,EAChI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,KAAK,IAAA,EAAiE;AAAE,IAAA,OAAO,MAAA;AAAA,EAAgC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQrH,MAAM,KAAK,IAAA,EAAoE;AAAE,IAAA,OAAO,MAAA;AAAA,EAAgC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQxH,MAAM,KAAK,IAAA,EAAuE;AAAE,IAAA,OAAO,cAAA;AAAA,EAAsB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQjH,MAAM,aAAa,IAAA,EAAoE;AACtF,IAAA,IAAI,IAAA,CAAK,KAAA;AACR,MAAA,MAAM,IAAA,CAAK,KAAA;AAEZ,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,KAAA,EAAQ,IAAA,CAAK,WAAA,CAAY,IAAI,CAAA,2CAAA,CAA6C,CAAA;AAAA,EAC3F;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,MAAM,IAAA,EAAoE;AAC/E,IAAA,IAAI,SAAA;AACJ,IAAA,KAAA,IAAS,QAAA,GAAW,CAAA,EAAG,QAAA,GAAW,IAAA,CAAK,YAAY,QAAA,EAAA,EAAY;AAC9D,MAAA,IAAI,KAAK,MAAA,EAAQ,OAAA;AAChB,QAAA,MAAM,IAAI,UAAA,EAAW;AACtB,MAAA,IAAI;AACH,QAAA,OAAO,MAAM,IAAA,CAAK,IAAA,CAAK,IAAI,CAAA;AAAA,MAC5B,SACO,CAAA,EAAG;AACT,QAAA,MAAM,KAAA,GAAQ,CAAA;AACd,QAAA,SAAA,GAAY,KAAA;AAEZ,QAAA,IAAI,KAAA,YAAiB,kBAAA;AACpB,UAAA,MAAM,KAAA;AAEP,QAAA,IAAI,KAAA,YAAiB,UAAA,IAAc,KAAA,CAAM,IAAA,KAAS,YAAA;AACjD,UAAA,MAAM,KAAA;AAEP,QAAA,IAAI,QAAA,GAAW,IAAA,CAAK,UAAA,GAAa,CAAA,EAAG;AACnC,UAAA,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,CAAA,QAAA,EAAW,QAAA,GAAW,CAAC,CAAA,CAAA,EAAI,IAAA,CAAK,UAAU,CAAA,YAAA,EAAe,KAAK,WAAA,CAAY,IAAI,CAAA,aAAA,CAAA,EAAiB,EAAE,OAAO,CAAA;AACzH,UAAA,IAAI,KAAK,IAAA,GAAO,CAAA;AACf,YAAA,MAAM,KAAA,CAAM,IAAA,CAAK,IAAA,EAAM,IAAA,CAAK,MAAM,CAAA;AAAA,QACpC;AAAA,MACD;AAAA,IACD;AACA,IAAA,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,CAAA,uBAAA,EAA0B,IAAA,CAAK,WAAA,CAAY,IAAI,CAAA,qBAAA,CAAA,EAAyB,EAAE,KAAA,EAAO,SAAA,EAAW,CAAA;AAC9G,IAAA,IAAI,KAAK,MAAA,EAAQ,OAAA;AAChB,MAAA,MAAM,IAAI,UAAA,EAAW;AACtB,IAAA,OAAO,MAAM,KAAK,YAAA,CAAa,EAAE,GAAG,IAAA,EAAM,KAAA,EAAO,WAAW,CAAA;AAAA,EAC7D;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,KAAK,EAAE,GAAA,EAAK,QAAQ,MAAA,EAAQ,MAAA,EAAQ,QAAA,EAAU,iBAAA,EAAkB,EAA+C;AACpH,IAAA,IAAI,MAAA,EAAQ,OAAA;AACX,MAAA,MAAM,IAAI,UAAA,EAAW;AACtB,IAAA,IAAI,OAAA;AACJ,IAAA,IAAI;AACH,MAAA,OAAA,GAAU,MAAM,IAAA,CAAK,IAAA,CAAK,EAAE,KAAsB,MAAA,EAA2B,MAAA,EAAQ,MAAA,EAAQ,OAAA,EAAS,KAAA,CAAA,EAAW,OAAA,EAAS,KAAA,CAAA,EAAW,QAAA,EAAU,mBAAmB,CAAA;AAAA,IACnK,SACO,CAAA,EAAG;AACT,MAAA,MAAM,IAAA,CAAK,UAAA,CAAW,CAAA,EAAG,MAAM,CAAA;AAAA,IAChC;AAEA,IAAA,IAAI,MAAA,EAAQ,OAAA;AACX,MAAA,MAAM,IAAI,UAAA,EAAW;AACtB,IAAA,IAAI,OAAA;AACJ,IAAA,IAAI;AACH,MAAA,OAAA,GAAU,MAAM,IAAA,CAAK,KAAA,CAAM,EAAE,GAAA,EAAsB,MAAA,EAA2B,MAAA,EAAQ,MAAA,EAAQ,OAAA,EAAS,OAAA,EAAS,KAAA,CAAA,EAAW,QAAA,EAAU,mBAAmB,CAAA;AAAA,IACzJ,SACO,CAAA,EAAG;AACT,MAAA,MAAM,IAAA,CAAK,UAAA,CAAW,CAAA,EAAG,MAAM,CAAA;AAAA,IAChC;AAEA,IAAA,IAAI,MAAA,EAAQ,OAAA;AACX,MAAA,MAAM,IAAI,UAAA,EAAW;AACtB,IAAA,IAAI;AACH,MAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,CAAK,EAAE,GAAA,EAAsB,MAAA,EAA2B,MAAA,EAAQ,MAAA,EAAQ,OAAA,EAAS,OAAA,EAAS,QAAA,EAAU,mBAAmB,CAAA;AACjJ,MAAA,OAAO,MAAA,KAAW,SAAY,cAAA,GAAwB,MAAA;AAAA,IACvD,SACO,CAAA,EAAG;AACT,MAAA,MAAM,IAAA,CAAK,UAAA,CAAW,CAAA,EAAG,MAAM,CAAA;AAAA,IAChC;AAAA,EACD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,GAAA,CAAI,GAAA,EAAe,OAAA,EAAwC;AAChE,IAAA,MAAM,OAAO,kBAAA,EAAmB;AAChC,IAAA,MAAM,MAAA,GAAS,OAAA,EAAS,MAAA,IAAU,IAAI,UAAA,EAAW;AACjD,IAAA,IAAI,IAAA,CAAK,UAAA,CAAW,IAAA,GAAO,CAAA,IAAK,EAAE,IAAA,YAAgB,IAAA,CAAA;AACjD,MAAA,MAAA,CAAO,KAAK,qHAAqH,CAAA;AAClI,IAAA,MAAM,QAAA,GAAW,OAAA,EAAS,QAAA,IAAY,IAAI,gBAAA,EAAiB;AAE3D,IAAA,OAAO,QAAA,CAAS,GAAA,CAAI,IAAI,IAAA,CAAK,IAAI,CAAA,EAAG,GAAA,EAAK,EAAE,GAAG,OAAA,EAAS,MAAA,EAAQ,IAAA,CAAK,QAAQ,CAAA;AAAA,EAC7E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,IAAY,EAAA,EAAkG;AAC7G,IAAA,MAAM,YAAA,GAAe,IAAA;AACrB,IAAA,MAAM,aAAa,IAAA,CAAK,UAAA;AACxB,IAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAElB,IAAA,OAAO,IAAI,cAAc,KAAA,CAA8C;AAAA,MACtE,WAAA,GAAc;AAAE,QAAA,KAAA,CAAM,EAAE,UAAA,EAAY,IAAA,EAAM,CAAA;AAAA,MAAE;AAAA,MAC5C,MAAM,KAAK,IAAA,EAAiE;AAAE,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAAE;AAAA,MAC7G,MAAM,KAAK,IAAA,EAAmE;AAC7E,QAAA,MAAM,cAAA,GAAiB,MAAM,YAAA,CAAa,IAAA,CAAK,IAAI,CAAA;AACnD,QAAA,OAAO,GAAG,cAAc,CAAA;AAAA,MACzB;AAAA,MAEA,MAAM,KAAK,KAAA,EAAmE;AAC7E,QAAA,OAAO,cAAA;AAAA,MACR;AAAA,KACD,EAAE;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,UAAU,GAAA,EAA0E;AACnF,IAAA,MAAM,YAAA,GAAe,IAAA;AACrB,IAAA,MAAM,aAAa,IAAA,CAAK,UAAA;AACxB,IAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAElB,IAAA,OAAO,IAAI,cAAc,KAAA,CAA+C;AAAA,MACvE,WAAA,GAAc;AAAE,QAAA,KAAA,CAAM,EAAE,UAAA,EAAY,IAAA,EAAM,CAAA;AAAA,MAAE;AAAA,MAC5C,MAAM,KAAK,IAAA,EAAiE;AAAE,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAAE;AAAA,MAC7G,MAAM,KAAK,IAAA,EAAoE;AAAE,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAAE;AAAA,MAChH,MAAM,KAAK,IAAA,EAAmE;AAC7E,QAAA,IAAA,CAAK,GAAA,CAAI,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,OAAO,CAAA;AAC9B,QAAA,OAAO,cAAA;AAAA,MACR;AAAA,KACD,EAAE;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBA,OAAO,SAAA,EAA4G;AAClH,IAAA,MAAM,YAAA,GAAe,IAAA;AAErB,IAAA,OAAO,IAAI,cAAc,KAAA,CAA+C;AAAA,MAC/D,OAAA,GAAU,KAAA;AAAA,MAElB,MAAM,KAAK,IAAA,EAA+C;AAAE,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAAE;AAAA,MAC3F,MAAM,KAAK,IAAA,EAAoE;AAC9E,QAAA,MAAM,MAAA,GAAS,MAAM,YAAA,CAAa,IAAA,CAAK,IAAI,CAAA;AAC3C,QAAA,IAAA,CAAK,OAAA,GAAU,MAAM,SAAA,CAAU,MAAM,CAAA;AACrC,QAAA,IAAI,CAAC,IAAA,CAAK,OAAA;AACT,UAAA,IAAA,CAAK,OAAO,KAAA,CAAM,CAAA,mCAAA,EAAsC,IAAA,CAAK,WAAA,CAAY,IAAI,CAAA,CAAA,CAAG,CAAA;AAEjF,QAAA,OAAO,MAAA;AAAA,MACR;AAAA,MAEA,MAAM,KAAK,KAAA,EAAoE;AAC9E,QAAA,OAAO,IAAA,CAAK,UAAU,cAAA,GAAiB,aAAA;AAAA,MACxC;AAAA,KACD,EAAE;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,IAAI,EAAA,EAAmG;AACtG,IAAA,MAAM,YAAA,GAAe,IAAA;AACrB,IAAA,MAAM,aAAa,IAAA,CAAK,UAAA;AACxB,IAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAElB,IAAA,OAAO,IAAI,cAAc,KAAA,CAAmD;AAAA,MAC3E,WAAA,GAAc;AAAE,QAAA,KAAA,CAAM,EAAE,UAAA,EAAY,IAAA,EAAM,CAAA;AAAA,MAAE;AAAA,MAC5C,MAAM,KAAK,IAAA,EAAiE;AAC3E,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAC9B;AAAA,MAEA,MAAM,KAAK,IAAA,EAAoE;AAC9E,QAAA,MAAM,cAAA,GAAiB,MAAM,YAAA,CAAa,IAAA,CAAK,IAAI,CAAA;AACnD,QAAA,MAAM,GAAG,cAAc,CAAA;AACvB,QAAA,OAAO,cAAA;AAAA,MACR;AAAA,MAEA,MAAM,KAAK,IAAA,EAAuE;AACjF,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAC9B;AAAA,KACD,EAAE;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBA,QAAA,CAAY,MAAsB,KAAA,EAA8D;AAC/F,IAAA,MAAM,YAAA,GAAe,IAAA;AACrB,IAAA,MAAM,aAAa,IAAA,CAAK,UAAA;AACxB,IAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAElB,IAAA,OAAO,IAAI,cAAc,KAAA,CAAmD;AAAA,MAC3E,WAAA,GAAc;AAAE,QAAA,KAAA,CAAM,EAAE,UAAA,EAAY,IAAA,EAAM,CAAA;AAAA,MAAE;AAAA,MAC5C,MAAM,KAAK,IAAA,EAAiE;AAE3E,QAAA,MAAM,IAAA,CAAK,GAAA,CAAI,KAAK,CAAA,CAAE,KAAK,GAAG,CAAA;AAC9B,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAC9B;AAAA,MAEA,MAAM,KAAK,IAAA,EAAoE;AAC9E,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAC9B;AAAA,MAEA,MAAM,KAAK,IAAA,EAAuE;AACjF,QAAA,OAAO,YAAA,CAAa,KAAK,IAAI,CAAA;AAAA,MAC9B;AAAA,KACD,EAAE;AAAA,EACH;AACD","file":"chunk-HEO3XL4Z.js","sourcesContent":["/* eslint-disable unused-imports/no-unused-vars, ts/no-this-alias */\n\nimport type { Context, ContextKey, ContextLens } from '../context'\nimport type { NodeArgs, NodeOptions, NodeRunContext, Params, RunOptions } from '../types'\nimport { AbortError, FatalWorkflowError, WorkflowError } from '../errors'\nimport { InMemoryExecutor } from '../executors/in-memory'\nimport { NullLogger } from '../logger'\nimport { DEFAULT_ACTION, FILTER_FAILED } from '../types'\nimport { sleep } from '../utils/index'\nimport { AbstractNode } from './AbstractNode'\nimport { getFlowConstructor } from './registry'\n\n/**\n * The fundamental building block of a workflow, representing a single unit of work.\n * It features a three-phase lifecycle, retry logic, and a fluent API for creating\n * data processing pipelines.\n *\n * @template PrepRes The type of data returned by the `prep` phase.\n * @template ExecRes The type of data returned by the `exec` phase.\n * @template PostRes The type of the action returned by the `post` phase.\n * @template TParams The type for the node's static parameters.\n */\nexport class Node<\n\tPrepRes = any,\n\tExecRes = any,\n\tPostRes = any,\n\tTParams extends Params = Params,\n\tTContext extends Context = Context,\n> extends AbstractNode<PostRes, TParams, TContext> {\n\t/** The total number of times the `exec` phase will be attempted. */\n\tpublic maxRetries: number\n\t/** The time in milliseconds to wait between failed `exec` attempts. */\n\tpublic wait: number\n\n\t/**\n\t * @param options Configuration options for the node's behavior.\n\t * @param options.maxRetries Total number of `exec` attempts. Defaults to `1`.\n\t * @param options.wait Milliseconds to wait between failed `exec` attempts. Defaults to `0`.\n\t */\n\tconstructor(options: NodeOptions = {}) {\n\t\tsuper()\n\t\tthis.maxRetries = options.maxRetries ?? 1\n\t\tthis.wait = options.wait ?? 0\n\t}\n\n\tprotected _wrapError(e: any, phase: 'prep' | 'exec' | 'post'): Error {\n\t\tif (e instanceof AbortError || e instanceof WorkflowError)\n\t\t\treturn e\n\n\t\treturn new WorkflowError(`Failed in ${phase} phase for node ${this.constructor.name}`, this.constructor.name, phase, e as Error)\n\t}\n\n\t/**\n\t * (Lifecycle) Prepares data for execution. Runs once before `exec`.\n\t * This is the ideal place to read data from the `Context`.\n\t * @param args The arguments for the node, including `ctx` and `params`.\n\t * @returns The data required by the `exec` phase.\n\t */\n\tasync prep(args: NodeArgs<void, void, TParams, TContext>): Promise<PrepRes> { return undefined as unknown as PrepRes }\n\n\t/**\n\t * (Lifecycle) Performs the core, isolated logic of the node.\n\t * This is the only phase that is retried on failure. It should not access the `Context` directly.\n\t * @param args The arguments for the node, including `prepRes`.\n\t * @returns The result of the execution.\n\t */\n\tasync exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes> { return undefined as unknown as ExecRes }\n\n\t/**\n\t * (Lifecycle) Processes results and determines the next step. Runs once after `exec` succeeds.\n\t * This is the ideal place to write data to the `Context`.\n\t * @param args The arguments for the node, including `execRes`.\n\t * @returns An \"action\" string to determine which successor to execute next. Defaults to `DEFAULT_ACTION`.\n\t */\n\tasync post(args: NodeArgs<PrepRes, ExecRes, TParams, TContext>): Promise<PostRes> { return DEFAULT_ACTION as any }\n\n\t/**\n\t * (Lifecycle) A fallback that runs if all `exec` retries fail.\n\t * If not implemented, the final error will be re-thrown, halting the workflow.\n\t * @param args The arguments for the node, including the final `error` that caused the failure.\n\t * @returns A fallback result of type `ExecRes`, allowing the workflow to recover and continue.\n\t */\n\tasync execFallback(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes> {\n\t\tif (args.error)\n\t\t\tthrow args.error\n\n\t\tthrow new Error(`Node ${this.constructor.name} failed and has no fallback implementation.`)\n\t}\n\n\t/**\n\t * The internal retry-aware execution logic for the `exec` phase.\n\t * @internal\n\t */\n\tasync _exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes> {\n\t\tlet lastError: Error | undefined\n\t\tfor (let curRetry = 0; curRetry < this.maxRetries; curRetry++) {\n\t\t\tif (args.signal?.aborted)\n\t\t\t\tthrow new AbortError()\n\t\t\ttry {\n\t\t\t\treturn await this.exec(args)\n\t\t\t}\n\t\t\tcatch (e) {\n\t\t\t\tconst error = e as Error\n\t\t\t\tlastError = error\n\n\t\t\t\tif (error instanceof FatalWorkflowError)\n\t\t\t\t\tthrow error\n\n\t\t\t\tif (error instanceof AbortError || error.name === 'AbortError')\n\t\t\t\t\tthrow error\n\n\t\t\t\tif (curRetry < this.maxRetries - 1) {\n\t\t\t\t\targs.logger.warn(`Attempt ${curRetry + 1}/${this.maxRetries} failed for ${this.constructor.name}. Retrying...`, { error })\n\t\t\t\t\tif (this.wait > 0)\n\t\t\t\t\t\tawait sleep(this.wait, args.signal)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\targs.logger.error(`All retries failed for ${this.constructor.name}. Executing fallback.`, { error: lastError })\n\t\tif (args.signal?.aborted)\n\t\t\tthrow new AbortError()\n\t\treturn await this.execFallback({ ...args, error: lastError })\n\t}\n\n\t/**\n\t * The internal method that executes the node's full lifecycle.\n\t * @internal\n\t */\n\tasync _run({ ctx, params, signal, logger, executor, visitedInParallel }: NodeRunContext<TContext>): Promise<PostRes> {\n\t\tif (signal?.aborted)\n\t\t\tthrow new AbortError()\n\t\tlet prepRes: PrepRes\n\t\ttry {\n\t\t\tprepRes = await this.prep({ ctx: ctx as TContext, params: params as TParams, signal, logger, prepRes: undefined, execRes: undefined, executor, visitedInParallel })\n\t\t}\n\t\tcatch (e) {\n\t\t\tthrow this._wrapError(e, 'prep')\n\t\t}\n\n\t\tif (signal?.aborted)\n\t\t\tthrow new AbortError()\n\t\tlet execRes: ExecRes\n\t\ttry {\n\t\t\texecRes = await this._exec({ ctx: ctx as TContext, params: params as TParams, signal, logger, prepRes, execRes: undefined, executor, visitedInParallel })\n\t\t}\n\t\tcatch (e) {\n\t\t\tthrow this._wrapError(e, 'exec')\n\t\t}\n\n\t\tif (signal?.aborted)\n\t\t\tthrow new AbortError()\n\t\ttry {\n\t\t\tconst action = await this.post({ ctx: ctx as TContext, params: params as TParams, signal, logger, prepRes, execRes, executor, visitedInParallel })\n\t\t\treturn action === undefined ? DEFAULT_ACTION as any : action\n\t\t}\n\t\tcatch (e) {\n\t\t\tthrow this._wrapError(e, 'post')\n\t\t}\n\t}\n\n\t/**\n\t * Runs the node as a standalone unit, independent of a larger flow.\n\t * This is useful for testing individual nodes in isolation.\n\t *\n\t * @param ctx The shared workflow context.\n\t * @param options Runtime options like a logger or abort controller.\n\t * @returns The result of the node's `post` method (its action).\n\t */\n\tasync run(ctx: TContext, options?: RunOptions): Promise<PostRes> {\n\t\tconst Flow = getFlowConstructor()\n\t\tconst logger = options?.logger ?? new NullLogger()\n\t\tif (this.successors.size > 0 && !(this instanceof Flow))\n\t\t\tlogger.warn('Node.run() called directly on a node with successors. The flow will not continue. Use a Flow to execute a sequence.')\n\t\tconst executor = options?.executor ?? new InMemoryExecutor()\n\t\t// Wrap the node in a Flow and pass its params via the options.\n\t\treturn executor.run(new Flow(this), ctx, { ...options, params: this.params })\n\t}\n\n\t/**\n\t * Creates a new node that transforms the result of this node's `exec` phase.\n\t *\n\t * @remarks\n\t * This method returns a **new** `Node` instance and does not modify the original.\n\t * The new node inherits the original's `prep` method. The original `post` method\n\t * is discarded as it is incompatible with the new result type.\n\t *\n\t * @example\n\t * const fetchUserNode = new FetchUserNode() // returns { id: 1, name: 'Alice' }\n\t * const getUserNameNode = fetchUserNode.map(user => user.name) // returns 'Alice'\n\t *\n\t * @param fn A sync or async function to transform the execution result from `ExecRes` to `NewRes`.\n\t * @returns A new `Node` instance with the transformed output type.\n\t */\n\tmap<NewRes>(fn: (result: ExecRes) => NewRes | Promise<NewRes>): Node<PrepRes, NewRes, any, TParams, TContext> {\n\t\tconst originalNode = this\n\t\tconst maxRetries = this.maxRetries\n\t\tconst wait = this.wait\n\n\t\treturn new class extends Node<PrepRes, NewRes, any, TParams, TContext> {\n\t\t\tconstructor() { super({ maxRetries, wait }) }\n\t\t\tasync prep(args: NodeArgs<void, void, TParams, TContext>): Promise<PrepRes> { return originalNode.prep(args) }\n\t\t\tasync exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<NewRes> {\n\t\t\t\tconst originalResult = await originalNode.exec(args)\n\t\t\t\treturn fn(originalResult)\n\t\t\t}\n\n\t\t\tasync post(_args: NodeArgs<PrepRes, NewRes, TParams, TContext>): Promise<any> {\n\t\t\t\treturn DEFAULT_ACTION\n\t\t\t}\n\t\t}()\n\t}\n\n\t/**\n\t * Creates a new node that stores the result of this node's `exec` phase in the `Context`.\n\t * This is a common terminal operation for a data processing chain.\n\t *\n\t * @remarks\n\t * This method returns a **new** `Node` instance and does not modify the original.\n\t *\n\t * @example\n\t * const USER_NAME = contextKey<string>('user_name')\n\t * const workflow = new FetchUserNode()\n\t *   .map(user => user.name)\n\t *   .toContext(USER_NAME)\n\t *\n\t * @param key The type-safe `ContextKey` to use for storing the result.\n\t * @returns A new `Node` instance that performs the context update in its `post` phase.\n\t */\n\ttoContext(key: ContextKey<ExecRes>): Node<PrepRes, ExecRes, any, TParams, TContext> {\n\t\tconst originalNode = this\n\t\tconst maxRetries = this.maxRetries\n\t\tconst wait = this.wait\n\n\t\treturn new class extends Node<PrepRes, ExecRes, any, TParams, TContext> {\n\t\t\tconstructor() { super({ maxRetries, wait }) }\n\t\t\tasync prep(args: NodeArgs<void, void, TParams, TContext>): Promise<PrepRes> { return originalNode.prep(args) }\n\t\t\tasync exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes> { return originalNode.exec(args) }\n\t\t\tasync post(args: NodeArgs<PrepRes, ExecRes, TParams, TContext>): Promise<any> {\n\t\t\t\targs.ctx.set(key, args.execRes)\n\t\t\t\treturn DEFAULT_ACTION\n\t\t\t}\n\t\t}()\n\t}\n\n\t/**\n\t * Creates a new node that acts as a conditional gate based on the `exec` result.\n\t * If the predicate returns `true`, the node returns `DEFAULT_ACTION`.\n\t * If it returns `false`, the node returns `FILTER_FAILED`, enabling branching.\n\t *\n\t * @remarks\n\t * This method returns a **new** `Node` instance and does not modify the original.\n\t *\n\t * @example\n\t * const checkAdminNode = new FetchUserNode().filter(user => user.isAdmin)\n\t *\n\t * checkAdminNode.next(adminOnlyNode, DEFAULT_ACTION)\n\t * checkAdminNode.next(accessDeniedNode, FILTER_FAILED)\n\t *\n\t * @param predicate A sync or async function that returns `true` or `false`.\n\t * @returns A new `Node` instance that implements the filter logic.\n\t */\n\tfilter(predicate: (result: ExecRes) => boolean | Promise<boolean>): Node<PrepRes, ExecRes, any, TParams, TContext> {\n\t\tconst originalNode = this\n\n\t\treturn new class extends Node<PrepRes, ExecRes, any, TParams, TContext> {\n\t\t\tprivate didPass = false\n\n\t\t\tasync prep(args: NodeArgs<void, void, TParams, TContext>) { return originalNode.prep(args) }\n\t\t\tasync exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes> {\n\t\t\t\tconst result = await originalNode.exec(args)\n\t\t\t\tthis.didPass = await predicate(result)\n\t\t\t\tif (!this.didPass)\n\t\t\t\t\targs.logger.debug(`[Filter] Predicate failed for node ${this.constructor.name}.`)\n\n\t\t\t\treturn result\n\t\t\t}\n\n\t\t\tasync post(_args: NodeArgs<PrepRes, ExecRes, TParams, TContext>): Promise<any> {\n\t\t\t\treturn this.didPass ? DEFAULT_ACTION : FILTER_FAILED\n\t\t\t}\n\t\t}()\n\t}\n\n\t/**\n\t * Creates a new node that performs a side effect with the `exec` result,\n\t * but passes the original result through unmodified. Ideal for logging or debugging.\n\t *\n\t * @remarks\n\t * This method returns a **new** `Node` instance and does not modify the original.\n\t *\n\t * @example\n\t * const workflow = new FetchUserNode()\n\t *   .tap(user => console.log('Fetched User:', user))\n\t *   .map(user => user.id)\n\t *\n\t * @param fn A function to call with the execution result for its side effect.\n\t * @returns A new `Node` instance that wraps the original.\n\t */\n\ttap(fn: (result: ExecRes) => void | Promise<void>): Node<PrepRes, ExecRes, PostRes, TParams, TContext> {\n\t\tconst originalNode = this\n\t\tconst maxRetries = this.maxRetries\n\t\tconst wait = this.wait\n\n\t\treturn new class extends Node<PrepRes, ExecRes, PostRes, TParams, TContext> {\n\t\t\tconstructor() { super({ maxRetries, wait }) }\n\t\t\tasync prep(args: NodeArgs<void, void, TParams, TContext>): Promise<PrepRes> {\n\t\t\t\treturn originalNode.prep(args)\n\t\t\t}\n\n\t\t\tasync exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes> {\n\t\t\t\tconst originalResult = await originalNode.exec(args)\n\t\t\t\tawait fn(originalResult)\n\t\t\t\treturn originalResult\n\t\t\t}\n\n\t\t\tasync post(args: NodeArgs<PrepRes, ExecRes, TParams, TContext>): Promise<PostRes> {\n\t\t\t\treturn originalNode.post(args)\n\t\t\t}\n\t\t}()\n\t}\n\n\t/**\n\t * Creates a new node that applies a context mutation using a lens before executing.\n\t * This allows for declaratively setting or updating context as part of a fluent chain.\n\t *\n\t * @remarks\n\t * This method returns a **new** `Node` instance and does not modify the original.\n\t *\n\t * @example\n\t * const VALUE = contextKey<number>('value')\n\t * const valueLens = lens(VALUE)\n\t *\n\t * const nodeWithLens = new SomeNode().withLens(valueLens, 42) // Sets VALUE to 42 before SomeNode runs\n\t *\n\t * @param lens The `ContextLens` to use for the operation.\n\t * @param value The value to set in the context via the lens.\n\t * @returns A new `Node` instance that applies the context change.\n\t */\n\twithLens<T>(lens: ContextLens<T>, value: T): Node<PrepRes, ExecRes, PostRes, TParams, TContext> {\n\t\tconst originalNode = this\n\t\tconst maxRetries = this.maxRetries\n\t\tconst wait = this.wait\n\n\t\treturn new class extends Node<PrepRes, ExecRes, PostRes, TParams, TContext> {\n\t\t\tconstructor() { super({ maxRetries, wait }) }\n\t\t\tasync prep(args: NodeArgs<void, void, TParams, TContext>): Promise<PrepRes> {\n\t\t\t\t// Apply the lens transformation before executing the original node's logic.\n\t\t\t\tawait lens.set(value)(args.ctx)\n\t\t\t\treturn originalNode.prep(args)\n\t\t\t}\n\n\t\t\tasync exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes> {\n\t\t\t\treturn originalNode.exec(args)\n\t\t\t}\n\n\t\t\tasync post(args: NodeArgs<PrepRes, ExecRes, TParams, TContext>): Promise<PostRes> {\n\t\t\t\treturn originalNode.post(args)\n\t\t\t}\n\t\t}()\n\t}\n}\n"]}

package/dist/chunk-IIKTTIW5.js

@@ -1,56 +0,0 @@
-// src/logger.ts
-var NullLogger = class {
-  debug() {
-  }
-  info() {
-  }
-  warn() {
-  }
-  error() {
-  }
-};
-var levelPriorities = {
-  debug: 1,
-  info: 2,
-  warn: 3,
-  error: 4
-};
-var ConsoleLogger = class {
-  minLevel;
-  /**
-   * @param options Configuration for the logger.
-   * @param options.level The minimum level of messages to log. Defaults to 'info'.
-   */
-  constructor(options = {}) {
-    this.minLevel = options.level ?? "info";
-  }
-  log(level, message, context) {
-    if (levelPriorities[level] < levelPriorities[this.minLevel]) {
-      return;
-    }
-    const fullMessage = `[${level.toUpperCase()}] ${message}`;
-    if (context && Object.keys(context).length > 0) {
-      const logMethod = console[level] || console.log;
-      logMethod(fullMessage, context);
-    } else {
-      const logMethod = console[level] || console.log;
-      logMethod(fullMessage);
-    }
-  }
-  debug(message, context) {
-    this.log("debug", message, context);
-  }
-  info(message, context) {
-    this.log("info", message, context);
-  }
-  warn(message, context) {
-    this.log("warn", message, context);
-  }
-  error(message, context) {
-    this.log("error", message, context);
-  }
-};
-
-export { ConsoleLogger, NullLogger };
-//# sourceMappingURL=chunk-IIKTTIW5.js.map
-//# sourceMappingURL=chunk-IIKTTIW5.js.map

package/dist/chunk-IIKTTIW5.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/logger.ts"],"names":[],"mappings":";AAgBO,IAAM,aAAN,MAAmC;AAAA,EACzC,KAAA,GAAQ;AAAA,EAAc;AAAA,EACtB,IAAA,GAAO;AAAA,EAAc;AAAA,EACrB,IAAA,GAAO;AAAA,EAAc;AAAA,EACrB,KAAA,GAAQ;AAAA,EAAc;AACvB;AAIA,IAAM,eAAA,GAA4C;AAAA,EACjD,KAAA,EAAO,CAAA;AAAA,EACP,IAAA,EAAM,CAAA;AAAA,EACN,IAAA,EAAM,CAAA;AAAA,EACN,KAAA,EAAO;AACR,CAAA;AAMO,IAAM,gBAAN,MAAsC;AAAA,EACpC,QAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMR,WAAA,CAAY,OAAA,GAAgC,EAAC,EAAG;AAC/C,IAAA,IAAA,CAAK,QAAA,GAAW,QAAQ,KAAA,IAAS,MAAA;AAAA,EAClC;AAAA,EAEQ,GAAA,CAAI,KAAA,EAAiB,OAAA,EAAiB,OAAA,EAAkB;AAC/D,IAAA,IAAI,gBAAgB,KAAK,CAAA,GAAI,eAAA,CAAgB,IAAA,CAAK,QAAQ,CAAA,EAAG;AAC5D,MAAA;AAAA,IACD;AAEA,IAAA,MAAM,cAAc,CAAA,CAAA,EAAI,KAAA,CAAM,WAAA,EAAa,KAAK,OAAO,CAAA,CAAA;AACvD,IAAA,IAAI,WAAW,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,CAAE,SAAS,CAAA,EAAG;AAC/C,MAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,KAAK,CAAA,IAAK,OAAA,CAAQ,GAAA;AAC5C,MAAA,SAAA,CAAU,aAAa,OAAO,CAAA;AAAA,IAC/B,CAAA,MACK;AACJ,MAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,KAAK,CAAA,IAAK,OAAA,CAAQ,GAAA;AAC5C,MAAA,SAAA,CAAU,WAAW,CAAA;AAAA,IACtB;AAAA,EACD;AAAA,EAEA,KAAA,CAAM,SAAiB,OAAA,EAAkB;AAAE,IAAA,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,OAAA,EAAS,OAAO,CAAA;AAAA,EAAE;AAAA,EAC/E,IAAA,CAAK,SAAiB,OAAA,EAAkB;AAAE,IAAA,IAAA,CAAK,GAAA,CAAI,MAAA,EAAQ,OAAA,EAAS,OAAO,CAAA;AAAA,EAAE;AAAA,EAC7E,IAAA,CAAK,SAAiB,OAAA,EAAkB;AAAE,IAAA,IAAA,CAAK,GAAA,CAAI,MAAA,EAAQ,OAAA,EAAS,OAAO,CAAA;AAAA,EAAE;AAAA,EAC7E,KAAA,CAAM,SAAiB,OAAA,EAAkB;AAAE,IAAA,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,OAAA,EAAS,OAAO,CAAA;AAAA,EAAE;AAChF","file":"chunk-IIKTTIW5.js","sourcesContent":["/**\n * Defines the interface for a logger that can be used by the workflow engine.\n * This allows for plugging in any logging library (e.g., Pino, Winston).\n */\nexport interface Logger {\n\tdebug: (message: string, context?: object) => void\n\tinfo: (message: string, context?: object) => void\n\twarn: (message: string, context?: object) => void\n\terror: (message: string, context?: object) => void\n}\n\n/**\n * A logger implementation that performs no action (a \"no-op\" logger).\n * This is the default logger used by the framework if none is provided,\n * making Flowcraft silent out-of-the-box.\n */\nexport class NullLogger implements Logger {\n\tdebug() { /* no-op */ }\n\tinfo() { /* no-op */ }\n\twarn() { /* no-op */ }\n\terror() { /* no-op */ }\n}\n\ntype LogLevel = 'debug' | 'info' | 'warn' | 'error'\n\nconst levelPriorities: Record<LogLevel, number> = {\n\tdebug: 1,\n\tinfo: 2,\n\twarn: 3,\n\terror: 4,\n}\n\n/**\n * A default logger implementation that writes messages to the `console`.\n * It supports a minimum log level to control verbosity.\n */\nexport class ConsoleLogger implements Logger {\n\tprivate minLevel: LogLevel\n\n\t/**\n\t * @param options Configuration for the logger.\n\t * @param options.level The minimum level of messages to log. Defaults to 'info'.\n\t */\n\tconstructor(options: { level?: LogLevel } = {}) {\n\t\tthis.minLevel = options.level ?? 'info'\n\t}\n\n\tprivate log(level: LogLevel, message: string, context?: object) {\n\t\tif (levelPriorities[level] < levelPriorities[this.minLevel]) {\n\t\t\treturn\n\t\t}\n\n\t\tconst fullMessage = `[${level.toUpperCase()}] ${message}`\n\t\tif (context && Object.keys(context).length > 0) {\n\t\t\tconst logMethod = console[level] || console.log\n\t\t\tlogMethod(fullMessage, context)\n\t\t}\n\t\telse {\n\t\t\tconst logMethod = console[level] || console.log\n\t\t\tlogMethod(fullMessage)\n\t\t}\n\t}\n\n\tdebug(message: string, context?: object) { this.log('debug', message, context) }\n\tinfo(message: string, context?: object) { this.log('info', message, context) }\n\twarn(message: string, context?: object) { this.log('warn', message, context) }\n\terror(message: string, context?: object) { this.log('error', message, context) }\n}\n"]}

package/dist/chunk-KOBEU2EM.js

@@ -1,3 +0,0 @@
-
-//# sourceMappingURL=chunk-KOBEU2EM.js.map
-//# sourceMappingURL=chunk-KOBEU2EM.js.map

package/dist/chunk-KOBEU2EM.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-KOBEU2EM.js"}

package/dist/chunk-L5PK5VL2.js

@@ -1,178 +0,0 @@
-import { Flow } from './chunk-UY4PNPBX.js';
-import { AbortError } from './chunk-64DNBF5W.js';
-
-// src/builder/patterns.ts
-var SequenceFlow = class extends Flow {
-  /**
-   * @param nodes A sequence of `Node` or `Flow` instances to be executed in order.
-   */
-  constructor(...nodes) {
-    if (nodes.length === 0) {
-      super();
-      return;
-    }
-    super(nodes[0]);
-    let current = nodes[0];
-    for (let i = 1; i < nodes.length; i++)
-      current = current.next(nodes[i]);
-  }
-};
-var ParallelFlow = class extends Flow {
-  /**
-   * @param nodesToRun The array of nodes to execute concurrently.
-   */
-  constructor(nodesToRun = []) {
-    super();
-    this.nodesToRun = nodesToRun;
-  }
-  /** A tag to reliably identify this node type in the visualizer. */
-  isParallelContainer = true;
-  /**
-   * Orchestrates the parallel execution of all nodes.
-   * @internal
-   */
-  async exec({ ctx, params, signal, logger, executor, visitedInParallel }) {
-    if (!visitedInParallel)
-      throw new Error("ParallelFlow requires a visitedInParallel set from its executor.");
-    const branches = this.nodesToRun.length > 0 ? this.nodesToRun : Array.from(this.successors.values()).flat();
-    if (branches.length === 0) {
-      logger.debug("[ParallelFlow] No branches to execute.");
-      return;
-    }
-    const runBranch = async (startNode) => {
-      let currentNode = startNode;
-      while (currentNode) {
-        if (signal?.aborted)
-          throw new AbortError();
-        if (visitedInParallel.has(currentNode))
-          break;
-        visitedInParallel.add(currentNode);
-        const action = await currentNode._run({
-          ctx,
-          params: { ...params, ...currentNode.params },
-          signal,
-          logger,
-          executor,
-          visitedInParallel
-        });
-        currentNode = executor?.getNextNode(currentNode, action);
-      }
-    };
-    const promises = branches.map(runBranch);
-    await Promise.allSettled(promises);
-  }
-};
-var BatchFlow = class extends Flow {
-  constructor() {
-    super();
-  }
-  /**
-   * (Abstract) Prepares the list of items to be processed.
-   * This method is called once before the batch processing begins.
-   * @param _args The arguments for the node, including `ctx` and `params`.
-   * @returns An array or iterable of parameter objects, one for each item.
-   * The `nodeToRun` will be executed once for each of these objects.
-   */
-  async prep(_args) {
-    return [];
-  }
-  /**
-   * Orchestrates the sequential execution of `nodeToRun` for each item.
-   * @internal
-   */
-  async exec(args) {
-    if (!this.nodeToRun)
-      return null;
-    const combinedParams = { ...this.params, ...args.params };
-    const batchParamsIterable = await this.prep(args) || [];
-    const batchParamsList = Array.from(batchParamsIterable);
-    for (const batchParams of batchParamsList) {
-      if (args.signal?.aborted)
-        throw new AbortError();
-      await this.nodeToRun._run({
-        ctx: args.ctx,
-        params: { ...combinedParams, ...batchParams },
-        signal: args.signal,
-        logger: args.logger,
-        executor: args.executor
-      });
-    }
-    return null;
-  }
-};
-var ParallelBatchFlow = class extends Flow {
-  constructor() {
-    super();
-  }
-  /**
-   * (Abstract) Prepares the list of items to be processed.
-   * This method is called once before the batch processing begins.
-   * @param _args The arguments for the node, including `ctx` and `params`.
-   * @returns An array or iterable of parameter objects, one for each item.
-   * The `nodeToRun` will be executed concurrently for each of these objects.
-   */
-  async prep(_args) {
-    return [];
-  }
-  /**
-   * Orchestrates the parallel execution of `nodeToRun` for each item.
-   * @internal
-   */
-  async exec(args) {
-    if (!this.nodeToRun)
-      return [];
-    const combinedParams = { ...this.params, ...args.params };
-    const batchParamsIterable = await this.prep(args) || [];
-    const batchParamsList = Array.from(batchParamsIterable);
-    const promises = batchParamsList.map((batchParams) => {
-      return this.nodeToRun._run({
-        ctx: args.ctx,
-        params: { ...combinedParams, ...batchParams },
-        signal: args.signal,
-        logger: args.logger,
-        executor: args.executor
-      });
-    });
-    const results = await Promise.allSettled(promises);
-    for (const result of results) {
-      if (result.status === "rejected") {
-        args.logger.error("A parallel batch item failed.", { error: result.reason });
-      }
-    }
-    return results;
-  }
-};
-function mapCollection(items, fn) {
-  return new class extends Flow {
-    async exec() {
-      const promises = items.map((item) => fn(item));
-      return Promise.all(promises);
-    }
-  }();
-}
-function filterCollection(items, predicate) {
-  return new class extends Flow {
-    async exec() {
-      const results = await Promise.all(items.map((item) => predicate(item)));
-      return items.filter((_, index) => results[index]);
-    }
-  }();
-}
-function reduceCollection(items, reducer, initialValue) {
-  return new class extends Flow {
-    async exec(_args) {
-      let accumulator = initialValue;
-      for (const item of items) {
-        if (_args.signal?.aborted) {
-          throw new AbortError();
-        }
-        accumulator = await reducer(accumulator, item);
-      }
-      return accumulator;
-    }
-  }();
-}
-
-export { BatchFlow, ParallelBatchFlow, ParallelFlow, SequenceFlow, filterCollection, mapCollection, reduceCollection };
-//# sourceMappingURL=chunk-L5PK5VL2.js.map
-//# sourceMappingURL=chunk-L5PK5VL2.js.map

package/dist/chunk-L5PK5VL2.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/builder/patterns.ts"],"names":[],"mappings":"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","file":"chunk-L5PK5VL2.js","sourcesContent":["import type { Context } from '../context'\nimport type { NodeFunction } from '../functions'\nimport type { NodeArgs, Params } from '../types'\nimport type { AbstractNode } from '../workflow/index'\nimport { AbortError } from '../errors'\nimport { Flow } from '../workflow/index'\n\n/**\n * A `Flow` that creates a linear workflow from a sequence of nodes,\n * automatically chaining them in order.\n */\nexport class SequenceFlow<\n\tPrepRes = any,\n\tExecRes = any,\n\tTParams extends Params = Params,\n\tTContext extends Context = Context,\n> extends Flow<PrepRes, ExecRes, TParams, TContext> {\n\t/**\n\t * @param nodes A sequence of `Node` or `Flow` instances to be executed in order.\n\t */\n\tconstructor(...nodes: AbstractNode<any, any, TContext>[]) {\n\t\tif (nodes.length === 0) {\n\t\t\tsuper()\n\t\t\treturn\n\t\t}\n\t\tsuper(nodes[0])\n\t\tlet current = nodes[0]\n\t\tfor (let i = 1; i < nodes.length; i++)\n\t\t\tcurrent = current.next(nodes[i])\n\t}\n}\n\n/**\n * A `Flow` that executes a collection of different nodes concurrently.\n * This is the core of the \"fan-out, fan-in\" pattern for structural parallelism.\n * After all parallel branches complete, the flow can proceed to a single successor.\n */\nexport class ParallelFlow<\n\tTContext extends Context = Context,\n> extends Flow<void, void, Params, TContext> {\n\t/** A tag to reliably identify this node type in the visualizer. */\n\tpublic readonly isParallelContainer = true\n\n\t/**\n\t * @param nodesToRun The array of nodes to execute concurrently.\n\t */\n\tconstructor(protected nodesToRun: AbstractNode<any, any, TContext>[] = []) {\n\t\tsuper()\n\t}\n\n\t/**\n\t * Orchestrates the parallel execution of all nodes.\n\t * @internal\n\t */\n\tasync exec({ ctx, params, signal, logger, executor, visitedInParallel }: NodeArgs<void, void, Params, TContext>): Promise<void> {\n\t\tif (!visitedInParallel)\n\t\t\tthrow new Error('ParallelFlow requires a visitedInParallel set from its executor.')\n\n\t\tconst branches = this.nodesToRun.length > 0\n\t\t\t? this.nodesToRun\n\t\t\t: Array.from(this.successors.values()).flat()\n\n\t\tif (branches.length === 0) {\n\t\t\tlogger.debug('[ParallelFlow] No branches to execute.')\n\t\t\treturn\n\t\t}\n\n\t\tconst runBranch = async (startNode: AbstractNode<any, any, TContext>) => {\n\t\t\tlet currentNode: AbstractNode<any, any, TContext> | undefined = startNode\n\t\t\twhile (currentNode) {\n\t\t\t\tif (signal?.aborted)\n\t\t\t\t\tthrow new AbortError()\n\n\t\t\t\tif (visitedInParallel.has(currentNode))\n\t\t\t\t\tbreak\n\t\t\t\tvisitedInParallel.add(currentNode)\n\n\t\t\t\tconst action = await currentNode._run({\n\t\t\t\t\tctx,\n\t\t\t\t\tparams: { ...params, ...currentNode.params },\n\t\t\t\t\tsignal,\n\t\t\t\t\tlogger,\n\t\t\t\t\texecutor,\n\t\t\t\t\tvisitedInParallel,\n\t\t\t\t})\n\n\t\t\t\tcurrentNode = executor?.getNextNode(currentNode, action)\n\t\t\t}\n\t\t}\n\n\t\tconst promises = branches.map(runBranch)\n\t\tawait Promise.allSettled(promises)\n\t}\n}\n\n/**\n * An abstract `Flow` that processes a collection of items sequentially, one by one.\n * Subclasses must implement the `prep` method to provide the items and the\n * `nodeToRun` property to define the processing logic for each item.\n */\nexport abstract class BatchFlow<\n\tT = any,\n\tTContext extends Context = Context,\n> extends Flow<Iterable<T>, null, Params, TContext> {\n\t/**\n\t * The `Node` instance that will be executed for each item in the batch.\n\t * This must be implemented by any subclass.\n\t */\n\tprotected abstract nodeToRun: AbstractNode<any, any, TContext>\n\n\tconstructor() {\n\t\tsuper()\n\t}\n\n\t/**\n\t * (Abstract) Prepares the list of items to be processed.\n\t * This method is called once before the batch processing begins.\n\t * @param _args The arguments for the node, including `ctx` and `params`.\n\t * @returns An array or iterable of parameter objects, one for each item.\n\t * The `nodeToRun` will be executed once for each of these objects.\n\t */\n\tasync prep(_args: NodeArgs<void, void, Params, TContext>): Promise<Iterable<any>> {\n\t\treturn []\n\t}\n\n\t/**\n\t * Orchestrates the sequential execution of `nodeToRun` for each item.\n\t * @internal\n\t */\n\tasync exec(args: NodeArgs<void, void, Params, TContext>): Promise<null> {\n\t\tif (!this.nodeToRun)\n\t\t\treturn null\n\n\t\tconst combinedParams = { ...this.params, ...args.params }\n\t\tconst batchParamsIterable = (await this.prep(args)) || []\n\t\tconst batchParamsList = Array.from(batchParamsIterable)\n\n\t\tfor (const batchParams of batchParamsList) {\n\t\t\tif (args.signal?.aborted)\n\t\t\t\tthrow new AbortError()\n\n\t\t\tawait this.nodeToRun._run({\n\t\t\t\tctx: args.ctx,\n\t\t\t\tparams: { ...combinedParams, ...batchParams },\n\t\t\t\tsignal: args.signal,\n\t\t\t\tlogger: args.logger,\n\t\t\t\texecutor: args.executor,\n\t\t\t})\n\t\t}\n\t\treturn null\n\t}\n}\n\n/**\n * An abstract `Flow` that processes a collection of items concurrently.\n * Subclasses must implement the `prep` method to provide the items and the\n * `nodeToRun` property to define the processing logic for each item.\n * This provides a significant performance boost for I/O-bound tasks.\n */\nexport abstract class ParallelBatchFlow<\n\tT = any,\n\tTContext extends Context = Context,\n> extends Flow<Iterable<T>, PromiseSettledResult<any>[], Params, TContext> {\n\t/**\n\t * The `Node` instance that will be executed concurrently for each item in the batch.\n\t * This must be implemented by any subclass.\n\t */\n\tprotected abstract nodeToRun: AbstractNode<any, any, TContext>\n\n\tconstructor() {\n\t\tsuper()\n\t}\n\n\t/**\n\t * (Abstract) Prepares the list of items to be processed.\n\t * This method is called once before the batch processing begins.\n\t * @param _args The arguments for the node, including `ctx` and `params`.\n\t * @returns An array or iterable of parameter objects, one for each item.\n\t * The `nodeToRun` will be executed concurrently for each of these objects.\n\t */\n\tasync prep(_args: NodeArgs<void, void, Params, TContext>): Promise<Iterable<any>> {\n\t\treturn []\n\t}\n\n\t/**\n\t * Orchestrates the parallel execution of `nodeToRun` for each item.\n\t * @internal\n\t */\n\tasync exec(args: NodeArgs<any, void, Params, TContext>): Promise<PromiseSettledResult<any>[]> {\n\t\tif (!this.nodeToRun)\n\t\t\treturn []\n\n\t\tconst combinedParams = { ...this.params, ...args.params }\n\t\tconst batchParamsIterable = (await this.prep(args)) || []\n\t\tconst batchParamsList = Array.from(batchParamsIterable)\n\n\t\tconst promises = batchParamsList.map((batchParams) => {\n\t\t\treturn this.nodeToRun._run({\n\t\t\t\tctx: args.ctx,\n\t\t\t\tparams: { ...combinedParams, ...batchParams },\n\t\t\t\tsignal: args.signal,\n\t\t\t\tlogger: args.logger,\n\t\t\t\texecutor: args.executor,\n\t\t\t})\n\t\t})\n\n\t\tconst results = await Promise.allSettled(promises)\n\n\t\tfor (const result of results) {\n\t\t\tif (result.status === 'rejected') {\n\t\t\t\targs.logger.error('A parallel batch item failed.', { error: result.reason })\n\t\t\t}\n\t\t}\n\n\t\treturn results\n\t}\n}\n\n/**\n * Creates a flow that applies a mapping function to each item in a collection in parallel\n * and returns a new array containing the results.\n *\n * @example\n * const numbers = [1, 2, 3];\n * const double = (n: number) => n * 2;\n * const processingFlow = mapCollection(numbers, double);\n * // When run, processingFlow's result will be [2, 4, 6]\n *\n * @param items The initial array of items of type `T`.\n * @param fn An async or sync function that transforms an item from type `T` to type `U`.\n * @returns A `Flow` instance that, when run, will output an array of type `U[]`.\n */\nexport function mapCollection<T, U, TContext extends Context = Context>(items: T[], fn: NodeFunction<T, U>): Flow<void, U[], Params, TContext> {\n\treturn new class extends Flow<void, U[], Params, TContext> {\n\t\tasync exec(): Promise<U[]> {\n\t\t\tconst promises = items.map(item => fn(item))\n\t\t\treturn Promise.all(promises)\n\t\t}\n\t}()\n}\n\n/**\n * Creates a flow that filters a collection based on a predicate function,\n * returning a new array containing only the items that pass the predicate.\n * The predicate is applied to all items concurrently.\n *\n * @example\n * const users = [{ id: 1, admin: true }, { id: 2, admin: false }];\n * const isAdmin = async (user: { admin: boolean }) => user.admin;\n * const adminFilterFlow = filterCollection(users, isAdmin);\n * // When run, the result will be [{ id: 1, admin: true }]\n *\n * @param items The initial array of items of type `T`.\n * @param predicate An async or sync function that returns `true` or `false` for an item.\n * @returns A `Flow` instance that, when run, will output a filtered array of type `T[]`.\n */\nexport function filterCollection<T, TContext extends Context = Context>(items: T[], predicate: (item: T) => boolean | Promise<boolean>): Flow<void, T[], Params, TContext> {\n\treturn new class extends Flow<void, T[], Params, TContext> {\n\t\tasync exec(): Promise<T[]> {\n\t\t\tconst results = await Promise.all(items.map(item => predicate(item)))\n\t\t\treturn items.filter((_, index) => results[index])\n\t\t}\n\t}()\n}\n\n/**\n * Creates a flow that reduces a collection to a single value by executing a\n * reducer function sequentially for each item, similar to `Array.prototype.reduce()`.\n *\n * @example\n * const numbers = [1, 2, 3, 4];\n * const sumReducer = (acc: number, val: number) => acc + val;\n * const sumFlow = reduceCollection(numbers, sumReducer, 0);\n * // When run, the result will be 10.\n *\n * @param items The array of items to be reduced.\n * @param reducer An async or sync function that processes the accumulator and the current item.\n * @param initialValue The initial value for the accumulator.\n * @returns A `Flow` instance that, when run, will output the final accumulated value of type `U`.\n */\nexport function reduceCollection<T, U, TContext extends Context = Context>(\n\titems: T[],\n\treducer: (accumulator: U, item: T) => U | Promise<U>,\n\tinitialValue: U,\n): Flow<void, U, Params, TContext> {\n\treturn new class extends Flow<void, U, Params, TContext> {\n\t\tasync exec(_args: NodeArgs<void, void, Params, TContext>): Promise<U> {\n\t\t\tlet accumulator = initialValue\n\t\t\tfor (const item of items) {\n\t\t\t\tif (_args.signal?.aborted) {\n\t\t\t\t\tthrow new AbortError()\n\t\t\t\t}\n\t\t\t\taccumulator = await reducer(accumulator, item)\n\t\t\t}\n\t\t\treturn accumulator\n\t\t}\n\t}()\n}\n"]}