@ax-llm/ax 12.0.18 → 12.0.19

package/index.cjs

@@ -13188,34 +13188,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.
@@ -13246,6 +13247,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).
    *
@@ -13265,6 +13272,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.
@@ -13313,6 +13326,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.
    *
@@ -13340,6 +13359,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.
    *
@@ -13354,10 +13379,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) {
@@ -13379,6 +13427,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.
@@ -13428,6 +13482,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.
    *
@@ -13473,32 +13533,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.
    *
@@ -13514,18 +13588,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.
    *