@ax-llm/ax 12.0.18 → 12.0.19

package/index.d.cts

@@ -3602,7 +3602,7 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
     private branchContext;
     constructor(signature?: NonNullable<ConstructorParameters<typeof AxSignature>[0]>);
     /**
-     * Declares a reusable computational node and its input/output signature.
+     * Declares a reusable computational node using a signature string.
      * Returns a new AxFlow type that tracks this node in the TNodes registry.
      *
      * @param name - The name of the node
@@ -3620,6 +3620,33 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
         [K in TName]: InferAxGen<TSig>;
     }, // Add new node to registry
     TState>;
+    /**
+     * Declares a reusable computational node using an existing AxGen instance.
+     * This allows reusing pre-configured generators in the flow.
+     *
+     * @param name - The name of the node
+     * @param axgenInstance - Existing AxGen instance to use for this node
+     * @returns New AxFlow instance with updated TNodes type
+     *
+     * @example
+     * ```typescript
+     * const summarizer = new AxGen('text:string -> summary:string', { temperature: 0.1 })
+     * flow.node('summarizer', summarizer)
+     * ```
+     */
+    node<TName extends string, TGen extends AxGen<any, any>>(name: TName, axgenInstance: TGen): AxFlow<IN, OUT, TNodes & {
+        [K in TName]: TGen;
+    }, // Add new node to registry with exact type
+    TState>;
+    /**
+     * Short alias for node() - supports both signature strings and AxGen instances
+     */
+    n<TName extends string, TSig extends string>(name: TName, signature: TSig, options?: Readonly<AxProgramForwardOptions>): AxFlow<IN, OUT, TNodes & {
+        [K in TName]: InferAxGen<TSig>;
+    }, TState>;
+    n<TName extends string, TGen extends AxGen<any, any>>(name: TName, axgenInstance: TGen): AxFlow<IN, OUT, TNodes & {
+        [K in TName]: TGen;
+    }, TState>;
     /**
      * Applies a synchronous transformation to the state object.
      * Returns a new AxFlow type with the evolved state.
@@ -3633,6 +3660,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     map<TNewState extends AxFlowState>(transform: (state: TState) => TNewState): AxFlow<IN, OUT, TNodes, TNewState>;
+    /**
+     * Short alias for map()
+     */
+    m<TNewState extends AxFlowState>(transform: (state: TState) => TNewState): AxFlow<IN, OUT, TNodes, TNewState>;
     /**
      * Labels a step for later reference (useful for feedback loops).
      *
@@ -3646,6 +3677,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     label(label: string): this;
+    /**
+     * Short alias for label()
+     */
+    l(label: string): this;
     /**
      * Executes a previously defined node with full type safety.
      * The node name must exist in TNodes, and the mapping function is typed based on the node's signature.
@@ -3661,6 +3696,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     execute<TNodeName extends keyof TNodes & string>(nodeName: TNodeName, mapping: (state: TState) => GetGenIn<TNodes[TNodeName]>, dynamicContext?: AxFlowDynamicContext): AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>;
+    /**
+     * Short alias for execute()
+     */
+    e<TNodeName extends keyof TNodes & string>(nodeName: TNodeName, mapping: (state: TState) => GetGenIn<TNodes[TNodeName]>, dynamicContext?: AxFlowDynamicContext): AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>;
     /**
      * Starts a conditional branch based on a predicate function.
      *
@@ -3678,6 +3717,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     branch(predicate: (state: TState) => unknown): this;
+    /**
+     * Short alias for branch()
+     */
+    b(predicate: (state: TState) => unknown): this;
     /**
      * Defines a branch case for the current branch context.
      *
@@ -3685,12 +3728,37 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * @returns this (for chaining)
      */
     when(value: unknown): this;
+    /**
+     * Short alias for when()
+     */
+    w(value: unknown): this;
     /**
      * Ends the current branch and merges all branch paths back into the main flow.
+     * Optionally specify the explicit merged state type for better type safety.
      *
-     * @returns this (for chaining)
+     * @param explicitMergedType - Optional type hint for the merged state (defaults to current TState)
+     * @returns AxFlow instance with the merged state type
+     *
+     * @example
+     * ```typescript
+     * // Default behavior - preserves current TState
+     * flow.branch(state => state.type)
+     *   .when('simple').execute('simpleProcessor', ...)
+     *   .when('complex').execute('complexProcessor', ...)
+     *   .merge()
+     *
+     * // Explicit type - specify exact merged state shape
+     * flow.branch(state => state.type)
+     *   .when('simple').map(state => ({ result: state.simpleResult, method: 'simple' }))
+     *   .when('complex').map(state => ({ result: state.complexResult, method: 'complex' }))
+     *   .merge<{ result: string; method: string }>()
+     * ```
      */
-    merge(): this;
+    merge<TMergedState extends AxFlowState = TState>(): AxFlow<IN, OUT, TNodes, TMergedState>;
+    /**
+     * Short alias for merge()
+     */
+    mg<TMergedState extends AxFlowState = TState>(): AxFlow<IN, OUT, TNodes, TMergedState>;
     /**
      * Executes multiple operations in parallel and merges their results.
      * Both typed and legacy untyped branches are supported.
@@ -3712,6 +3780,14 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
             [K in TResultKey]: T;
         }>;
     };
+    /**
+     * Short alias for parallel()
+     */
+    p(branches: (AxFlowParallelBranch | AxFlowTypedParallelBranch<TNodes, TState>)[]): {
+        merge<T, TResultKey extends string>(resultKey: TResultKey, mergeFunction: (...results: unknown[]) => T): AxFlow<IN, OUT, TNodes, TState & {
+            [K in TResultKey]: T;
+        }>;
+    };
     /**
      * Creates a feedback loop that jumps back to a labeled step if a condition is met.
      *
@@ -3729,26 +3805,39 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     feedback(condition: (state: TState) => boolean, targetLabel: string, maxIterations?: number): this;
+    /**
+     * Short alias for feedback()
+     */
+    fb(condition: (state: TState) => boolean, targetLabel: string, maxIterations?: number): this;
     /**
      * Marks the beginning of a loop block.
      *
      * @param condition - Function that takes the current state and returns a boolean
+     * @param maxIterations - Maximum number of iterations to prevent infinite loops (default: 100)
      * @returns this (for chaining)
      *
      * @example
      * ```typescript
-     * flow.while(state => state.iterations < 3)
+     * flow.while(state => state.iterations < 3, 10)
      *   .map(state => ({ ...state, iterations: (state.iterations || 0) + 1 }))
      *   .endWhile()
      * ```
      */
-    while(condition: (state: TState) => boolean): this;
+    while(condition: (state: TState) => boolean, maxIterations?: number): this;
+    /**
+     * Short alias for while()
+     */
+    wh(condition: (state: TState) => boolean, maxIterations?: number): this;
     /**
      * Marks the end of a loop block.
      *
      * @returns this (for chaining)
      */
     endWhile(): this;
+    /**
+     * Short alias for endWhile()
+     */
+    end(): this;
     /**
      * Executes the flow with the given AI service and input values.
      *

package/index.d.ts

@@ -3602,7 +3602,7 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
     private branchContext;
     constructor(signature?: NonNullable<ConstructorParameters<typeof AxSignature>[0]>);
     /**
-     * Declares a reusable computational node and its input/output signature.
+     * Declares a reusable computational node using a signature string.
      * Returns a new AxFlow type that tracks this node in the TNodes registry.
      *
      * @param name - The name of the node
@@ -3620,6 +3620,33 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
         [K in TName]: InferAxGen<TSig>;
     }, // Add new node to registry
     TState>;
+    /**
+     * Declares a reusable computational node using an existing AxGen instance.
+     * This allows reusing pre-configured generators in the flow.
+     *
+     * @param name - The name of the node
+     * @param axgenInstance - Existing AxGen instance to use for this node
+     * @returns New AxFlow instance with updated TNodes type
+     *
+     * @example
+     * ```typescript
+     * const summarizer = new AxGen('text:string -> summary:string', { temperature: 0.1 })
+     * flow.node('summarizer', summarizer)
+     * ```
+     */
+    node<TName extends string, TGen extends AxGen<any, any>>(name: TName, axgenInstance: TGen): AxFlow<IN, OUT, TNodes & {
+        [K in TName]: TGen;
+    }, // Add new node to registry with exact type
+    TState>;
+    /**
+     * Short alias for node() - supports both signature strings and AxGen instances
+     */
+    n<TName extends string, TSig extends string>(name: TName, signature: TSig, options?: Readonly<AxProgramForwardOptions>): AxFlow<IN, OUT, TNodes & {
+        [K in TName]: InferAxGen<TSig>;
+    }, TState>;
+    n<TName extends string, TGen extends AxGen<any, any>>(name: TName, axgenInstance: TGen): AxFlow<IN, OUT, TNodes & {
+        [K in TName]: TGen;
+    }, TState>;
     /**
      * Applies a synchronous transformation to the state object.
      * Returns a new AxFlow type with the evolved state.
@@ -3633,6 +3660,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     map<TNewState extends AxFlowState>(transform: (state: TState) => TNewState): AxFlow<IN, OUT, TNodes, TNewState>;
+    /**
+     * Short alias for map()
+     */
+    m<TNewState extends AxFlowState>(transform: (state: TState) => TNewState): AxFlow<IN, OUT, TNodes, TNewState>;
     /**
      * Labels a step for later reference (useful for feedback loops).
      *
@@ -3646,6 +3677,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     label(label: string): this;
+    /**
+     * Short alias for label()
+     */
+    l(label: string): this;
     /**
      * Executes a previously defined node with full type safety.
      * The node name must exist in TNodes, and the mapping function is typed based on the node's signature.
@@ -3661,6 +3696,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     execute<TNodeName extends keyof TNodes & string>(nodeName: TNodeName, mapping: (state: TState) => GetGenIn<TNodes[TNodeName]>, dynamicContext?: AxFlowDynamicContext): AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>;
+    /**
+     * Short alias for execute()
+     */
+    e<TNodeName extends keyof TNodes & string>(nodeName: TNodeName, mapping: (state: TState) => GetGenIn<TNodes[TNodeName]>, dynamicContext?: AxFlowDynamicContext): AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>;
     /**
      * Starts a conditional branch based on a predicate function.
      *
@@ -3678,6 +3717,10 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     branch(predicate: (state: TState) => unknown): this;
+    /**
+     * Short alias for branch()
+     */
+    b(predicate: (state: TState) => unknown): this;
     /**
      * Defines a branch case for the current branch context.
      *
@@ -3685,12 +3728,37 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * @returns this (for chaining)
      */
     when(value: unknown): this;
+    /**
+     * Short alias for when()
+     */
+    w(value: unknown): this;
     /**
      * Ends the current branch and merges all branch paths back into the main flow.
+     * Optionally specify the explicit merged state type for better type safety.
      *
-     * @returns this (for chaining)
+     * @param explicitMergedType - Optional type hint for the merged state (defaults to current TState)
+     * @returns AxFlow instance with the merged state type
+     *
+     * @example
+     * ```typescript
+     * // Default behavior - preserves current TState
+     * flow.branch(state => state.type)
+     *   .when('simple').execute('simpleProcessor', ...)
+     *   .when('complex').execute('complexProcessor', ...)
+     *   .merge()
+     *
+     * // Explicit type - specify exact merged state shape
+     * flow.branch(state => state.type)
+     *   .when('simple').map(state => ({ result: state.simpleResult, method: 'simple' }))
+     *   .when('complex').map(state => ({ result: state.complexResult, method: 'complex' }))
+     *   .merge<{ result: string; method: string }>()
+     * ```
      */
-    merge(): this;
+    merge<TMergedState extends AxFlowState = TState>(): AxFlow<IN, OUT, TNodes, TMergedState>;
+    /**
+     * Short alias for merge()
+     */
+    mg<TMergedState extends AxFlowState = TState>(): AxFlow<IN, OUT, TNodes, TMergedState>;
     /**
      * Executes multiple operations in parallel and merges their results.
      * Both typed and legacy untyped branches are supported.
@@ -3712,6 +3780,14 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
             [K in TResultKey]: T;
         }>;
     };
+    /**
+     * Short alias for parallel()
+     */
+    p(branches: (AxFlowParallelBranch | AxFlowTypedParallelBranch<TNodes, TState>)[]): {
+        merge<T, TResultKey extends string>(resultKey: TResultKey, mergeFunction: (...results: unknown[]) => T): AxFlow<IN, OUT, TNodes, TState & {
+            [K in TResultKey]: T;
+        }>;
+    };
     /**
      * Creates a feedback loop that jumps back to a labeled step if a condition is met.
      *
@@ -3729,26 +3805,39 @@ TState extends AxFlowState = IN> extends AxProgramWithSignature<IN, OUT> {
      * ```
      */
     feedback(condition: (state: TState) => boolean, targetLabel: string, maxIterations?: number): this;
+    /**
+     * Short alias for feedback()
+     */
+    fb(condition: (state: TState) => boolean, targetLabel: string, maxIterations?: number): this;
     /**
      * Marks the beginning of a loop block.
      *
      * @param condition - Function that takes the current state and returns a boolean
+     * @param maxIterations - Maximum number of iterations to prevent infinite loops (default: 100)
      * @returns this (for chaining)
      *
      * @example
      * ```typescript
-     * flow.while(state => state.iterations < 3)
+     * flow.while(state => state.iterations < 3, 10)
      *   .map(state => ({ ...state, iterations: (state.iterations || 0) + 1 }))
      *   .endWhile()
      * ```
      */
-    while(condition: (state: TState) => boolean): this;
+    while(condition: (state: TState) => boolean, maxIterations?: number): this;
+    /**
+     * Short alias for while()
+     */
+    wh(condition: (state: TState) => boolean, maxIterations?: number): this;
     /**
      * Marks the end of a loop block.
      *
      * @returns this (for chaining)
      */
     endWhile(): this;
+    /**
+     * Short alias for endWhile()
+     */
+    end(): this;
     /**
      * Executes the flow with the given AI service and input values.
      *

package/index.js

@@ -13010,34 +13010,35 @@ var AxFlow = class extends AxProgramWithSignature {
   constructor(signature = "userInput:string -> flowOutput:string") {
     super(signature);
   }
-  /**
-   * Declares a reusable computational node and its input/output signature.
-   * Returns a new AxFlow type that tracks this node in the TNodes registry.
-   *
-   * @param name - The name of the node
-   * @param signature - Signature string in the same format as AxSignature
-   * @param options - Optional program forward options (same as AxGen)
-   * @returns New AxFlow instance with updated TNodes type
-   *
-   * @example
-   * ```typescript
-   * flow.node('summarizer', 'text:string -> summary:string')
-   * flow.node('analyzer', 'text:string -> analysis:string, confidence:number', { debug: true })
-   * ```
-   */
-  node(name, signature, options) {
-    if (!signature) {
-      throw new Error(
-        `Invalid signature for node '${name}': signature cannot be empty`
+  // Implementation
+  node(name, signatureOrAxGen, options) {
+    if (signatureOrAxGen instanceof AxGen) {
+      this.nodes.set(name, {
+        inputs: {},
+        outputs: {}
+      });
+      this.nodeGenerators.set(
+        name,
+        signatureOrAxGen
       );
+    } else {
+      const signature = signatureOrAxGen;
+      if (!signature) {
+        throw new Error(
+          `Invalid signature for node '${name}': signature cannot be empty`
+        );
+      }
+      this.nodes.set(name, {
+        inputs: {},
+        outputs: {}
+      });
+      this.nodeGenerators.set(name, new AxGen(signature, options));
     }
-    this.nodes.set(name, {
-      inputs: {},
-      outputs: {}
-    });
-    this.nodeGenerators.set(name, new AxGen(signature, options));
     return this;
   }
+  n(name, signatureOrAxGen, options) {
+    return this.node(name, signatureOrAxGen, options);
+  }
   /**
    * Applies a synchronous transformation to the state object.
    * Returns a new AxFlow type with the evolved state.
@@ -13068,6 +13069,12 @@ var AxFlow = class extends AxProgramWithSignature {
     }
     return this;
   }
+  /**
+   * Short alias for map()
+   */
+  m(transform) {
+    return this.map(transform);
+  }
   /**
    * Labels a step for later reference (useful for feedback loops).
    *
@@ -13087,6 +13094,12 @@ var AxFlow = class extends AxProgramWithSignature {
     this.stepLabels.set(label, this.flowDefinition.length);
     return this;
   }
+  /**
+   * Short alias for label()
+   */
+  l(label) {
+    return this.label(label);
+  }
   /**
    * Executes a previously defined node with full type safety.
    * The node name must exist in TNodes, and the mapping function is typed based on the node's signature.
@@ -13135,6 +13148,12 @@ var AxFlow = class extends AxProgramWithSignature {
     }
     return this;
   }
+  /**
+   * Short alias for execute()
+   */
+  e(nodeName, mapping, dynamicContext) {
+    return this.execute(nodeName, mapping, dynamicContext);
+  }
   /**
    * Starts a conditional branch based on a predicate function.
    *
@@ -13162,6 +13181,12 @@ var AxFlow = class extends AxProgramWithSignature {
     };
     return this;
   }
+  /**
+   * Short alias for branch()
+   */
+  b(predicate) {
+    return this.branch(predicate);
+  }
   /**
    * Defines a branch case for the current branch context.
    *
@@ -13176,10 +13201,33 @@ var AxFlow = class extends AxProgramWithSignature {
     this.branchContext.branches.set(value, []);
     return this;
   }
+  /**
+   * Short alias for when()
+   */
+  w(value) {
+    return this.when(value);
+  }
   /**
    * Ends the current branch and merges all branch paths back into the main flow.
+   * Optionally specify the explicit merged state type for better type safety.
    *
-   * @returns this (for chaining)
+   * @param explicitMergedType - Optional type hint for the merged state (defaults to current TState)
+   * @returns AxFlow instance with the merged state type
+   *
+   * @example
+   * ```typescript
+   * // Default behavior - preserves current TState
+   * flow.branch(state => state.type)
+   *   .when('simple').execute('simpleProcessor', ...)
+   *   .when('complex').execute('complexProcessor', ...)
+   *   .merge()
+   *
+   * // Explicit type - specify exact merged state shape
+   * flow.branch(state => state.type)
+   *   .when('simple').map(state => ({ result: state.simpleResult, method: 'simple' }))
+   *   .when('complex').map(state => ({ result: state.complexResult, method: 'complex' }))
+   *   .merge<{ result: string; method: string }>()
+   * ```
    */
   merge() {
     if (!this.branchContext) {
@@ -13201,6 +13249,12 @@ var AxFlow = class extends AxProgramWithSignature {
     });
     return this;
   }
+  /**
+   * Short alias for merge()
+   */
+  mg() {
+    return this.merge();
+  }
   /**
    * Executes multiple operations in parallel and merges their results.
    * Both typed and legacy untyped branches are supported.
@@ -13250,6 +13304,12 @@ var AxFlow = class extends AxProgramWithSignature {
       }
     };
   }
+  /**
+   * Short alias for parallel()
+   */
+  p(branches) {
+    return this.parallel(branches);
+  }
   /**
    * Creates a feedback loop that jumps back to a labeled step if a condition is met.
    *
@@ -13295,32 +13355,46 @@ var AxFlow = class extends AxProgramWithSignature {
     });
     return this;
   }
+  /**
+   * Short alias for feedback()
+   */
+  fb(condition, targetLabel, maxIterations = 10) {
+    return this.feedback(condition, targetLabel, maxIterations);
+  }
   /**
    * Marks the beginning of a loop block.
    *
    * @param condition - Function that takes the current state and returns a boolean
+   * @param maxIterations - Maximum number of iterations to prevent infinite loops (default: 100)
    * @returns this (for chaining)
    *
    * @example
    * ```typescript
-   * flow.while(state => state.iterations < 3)
+   * flow.while(state => state.iterations < 3, 10)
    *   .map(state => ({ ...state, iterations: (state.iterations || 0) + 1 }))
    *   .endWhile()
    * ```
    */
-  while(condition) {
+  while(condition, maxIterations = 100) {
     const loopStartIndex = this.flowDefinition.length;
     this.loopStack.push(loopStartIndex);
     const placeholderStep = Object.assign(
       (state) => state,
       {
         _condition: condition,
+        _maxIterations: maxIterations,
         _isLoopStart: true
       }
     );
     this.flowDefinition.push(placeholderStep);
     return this;
   }
+  /**
+   * Short alias for while()
+   */
+  wh(condition, maxIterations = 100) {
+    return this.while(condition, maxIterations);
+  }
   /**
    * Marks the end of a loop block.
    *
@@ -13336,18 +13410,32 @@ var AxFlow = class extends AxProgramWithSignature {
       throw new Error("Loop start step not found or invalid");
     }
     const condition = placeholderStep._condition;
+    const maxIterations = placeholderStep._maxIterations;
     const loopBodySteps = this.flowDefinition.splice(loopStartIndex + 1);
     this.flowDefinition[loopStartIndex] = async (state, context3) => {
       let currentState = state;
-      while (condition(currentState)) {
+      let iterations = 0;
+      while (condition(currentState) && iterations < maxIterations) {
+        iterations++;
         for (const step of loopBodySteps) {
           currentState = await step(currentState, context3);
         }
       }
+      if (iterations >= maxIterations && condition(currentState)) {
+        throw new Error(
+          `While loop exceeded maximum iterations (${maxIterations}). Consider increasing maxIterations or ensuring the loop condition eventually becomes false.`
+        );
+      }
       return currentState;
     };
     return this;
   }
+  /**
+   * Short alias for endWhile()
+   */
+  end() {
+    return this.endWhile();
+  }
   /**
    * Executes the flow with the given AI service and input values.
    *