@wundr.io/langgraph-orchestrator 1.0.3

package/dist/edges/loop-edge.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Loop Edge - Cyclic edges for iterative workflows
+ * @module @wundr.io/langgraph-orchestrator
+ */
+import { z } from 'zod';
+import type { AgentState, EdgeDefinition, EdgeCondition, EdgeConditionEvaluator } from '../types';
+/**
+ * Configuration for loop behavior
+ */
+export interface LoopConfig {
+    /** Maximum number of iterations */
+    readonly maxIterations?: number;
+    /** Counter field in state.data */
+    readonly counterField?: string;
+    /** Condition to continue looping */
+    readonly condition: EdgeCondition;
+    /** What to do when max iterations reached */
+    readonly onMaxIterations?: 'error' | 'exit' | 'force-exit';
+    /** Exit node when loop completes */
+    readonly exitNode?: string;
+}
+/**
+ * Builder for loop edges with fluent API
+ */
+export declare class LoopEdgeBuilder<TState extends AgentState = AgentState> {
+    private readonly from;
+    private readonly to;
+    private maxIterations;
+    private counterField;
+    private condition?;
+    private exitNode?;
+    private onMaxIterations;
+    /**
+     * Create a new loop edge builder
+     * @param from - Source node name
+     * @param to - Target node name (can be same as from for self-loop)
+     */
+    constructor(from: string, to?: string);
+    /**
+     * Set maximum iterations
+     * @param max - Maximum number of loop iterations
+     * @returns this for chaining
+     */
+    maxIter(max: number): this;
+    /**
+     * Set the counter field name in state
+     * @param field - Field name for storing iteration count
+     * @returns this for chaining
+     */
+    counter(field: string): this;
+    /**
+     * Set condition to continue looping
+     * @param condition - Condition that must be true to continue
+     * @returns this for chaining
+     */
+    while(condition: EdgeCondition): this;
+    /**
+     * Continue while field equals value
+     * @param field - Field to check
+     * @param value - Expected value
+     * @returns this for chaining
+     */
+    whileEquals(field: string, value: unknown): this;
+    /**
+     * Continue while field is less than value
+     * @param field - Field to check
+     * @param value - Maximum value
+     * @returns this for chaining
+     */
+    whileLessThan(field: string, value: number): this;
+    /**
+     * Continue while custom condition is true
+     * @param evaluate - Custom evaluator function
+     * @returns this for chaining
+     */
+    whileCustom(evaluate: EdgeConditionEvaluator<TState>): this;
+    /**
+     * Set the exit node when loop completes
+     * @param node - Node to transition to after loop
+     * @returns this for chaining
+     */
+    exitTo(node: string): this;
+    /**
+     * Set behavior when max iterations reached
+     * @param behavior - What to do on max iterations
+     * @returns this for chaining
+     */
+    onMax(behavior: 'error' | 'exit' | 'force-exit'): this;
+    /**
+     * Build the loop edge configuration
+     * @returns LoopConfig object
+     */
+    build(): LoopConfig;
+    /**
+     * Build as EdgeDefinition
+     * @returns EdgeDefinition for the loop
+     */
+    buildEdge(): EdgeDefinition;
+    /**
+     * Create the composite loop condition
+     */
+    private createLoopCondition;
+}
+/**
+ * Create a loop edge builder
+ *
+ * @example
+ * ```typescript
+ * const loopEdge = loopEdge('process')
+ *   .maxIter(10)
+ *   .whileLessThan('data.retryCount', 3)
+ *   .exitTo('success')
+ *   .onMax('exit')
+ *   .buildEdge();
+ *
+ * graph.addLoopEdge(loopEdge.from, loopEdge.to, loopEdge.condition!);
+ * ```
+ *
+ * @param from - Source node name
+ * @param to - Optional target node (defaults to from for self-loop)
+ * @returns LoopEdgeBuilder
+ */
+export declare function loopEdge<TState extends AgentState = AgentState>(from: string, to?: string): LoopEdgeBuilder<TState>;
+/**
+ * Create a for-loop style edge
+ *
+ * @example
+ * ```typescript
+ * const forLoop = createForLoop({
+ *   from: 'process-item',
+ *   iterations: 5,
+ *   counterField: 'data.itemIndex',
+ *   exitNode: 'complete'
+ * });
+ * ```
+ *
+ * @param options - For loop configuration
+ * @returns EdgeDefinition for the loop
+ */
+export declare function createForLoop(options: {
+    from: string;
+    to?: string;
+    iterations: number;
+    counterField?: string;
+    exitNode?: string;
+}): EdgeDefinition;
+/**
+ * Create a while-loop style edge
+ *
+ * @example
+ * ```typescript
+ * const whileLoop = createWhileLoop({
+ *   from: 'check',
+ *   to: 'process',
+ *   condition: conditions.lessThan('data.errorCount', 5),
+ *   exitNode: 'done',
+ *   maxIterations: 100
+ * });
+ * ```
+ *
+ * @param options - While loop configuration
+ * @returns EdgeDefinition for the loop
+ */
+export declare function createWhileLoop(options: {
+    from: string;
+    to?: string;
+    condition: EdgeCondition;
+    exitNode?: string;
+    maxIterations?: number;
+}): EdgeDefinition;
+/**
+ * Create a do-while loop (executes at least once)
+ *
+ * @example
+ * ```typescript
+ * const doWhileLoop = createDoWhileLoop({
+ *   from: 'retry',
+ *   condition: conditions.equals('data.success', false),
+ *   exitNode: 'complete',
+ *   maxIterations: 5
+ * });
+ * ```
+ *
+ * @param options - Do-while loop configuration
+ * @returns EdgeDefinition for the loop
+ */
+export declare function createDoWhileLoop(options: {
+    from: string;
+    to?: string;
+    condition: EdgeCondition;
+    exitNode?: string;
+    maxIterations?: number;
+}): EdgeDefinition;
+/**
+ * Create a retry loop with exponential backoff
+ *
+ * @example
+ * ```typescript
+ * const retryLoop = createRetryLoop({
+ *   from: 'api-call',
+ *   maxRetries: 3,
+ *   exitOnSuccess: 'process-result',
+ *   exitOnFailure: 'handle-error',
+ *   successCondition: conditions.equals('data.success', true)
+ * });
+ * ```
+ *
+ * @param options - Retry loop configuration
+ * @returns EdgeDefinition for the loop
+ */
+export declare function createRetryLoop(options: {
+    from: string;
+    to?: string;
+    maxRetries: number;
+    retryCountField?: string;
+    successCondition: EdgeCondition;
+    exitOnSuccess?: string;
+    exitOnFailure?: string;
+}): EdgeDefinition;
+/**
+ * Create a pagination loop for iterating through paged data
+ *
+ * @example
+ * ```typescript
+ * const paginationLoop = createPaginationLoop({
+ *   from: 'fetch-page',
+ *   pageField: 'data.currentPage',
+ *   hasMoreField: 'data.hasMore',
+ *   exitNode: 'process-all'
+ * });
+ * ```
+ *
+ * @param options - Pagination loop configuration
+ * @returns EdgeDefinition for the loop
+ */
+export declare function createPaginationLoop(options: {
+    from: string;
+    to?: string;
+    pageField?: string;
+    hasMoreField: string;
+    maxPages?: number;
+    exitNode?: string;
+}): EdgeDefinition;
+/**
+ * Schema for loop configuration validation
+ */
+export declare const LoopConfigSchema: z.ZodObject<{
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    counterField: z.ZodOptional<z.ZodString>;
+    condition: z.ZodObject<{
+        type: z.ZodEnum<["equals", "not_equals", "contains", "greater_than", "less_than", "exists", "not_exists", "custom"]>;
+        field: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        type: "equals" | "not_equals" | "contains" | "greater_than" | "less_than" | "exists" | "not_exists" | "custom";
+        value?: unknown;
+        field?: string | undefined;
+    }, {
+        type: "equals" | "not_equals" | "contains" | "greater_than" | "less_than" | "exists" | "not_exists" | "custom";
+        value?: unknown;
+        field?: string | undefined;
+    }>;
+    onMaxIterations: z.ZodOptional<z.ZodEnum<["error", "exit", "force-exit"]>>;
+    exitNode: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    condition: {
+        type: "equals" | "not_equals" | "contains" | "greater_than" | "less_than" | "exists" | "not_exists" | "custom";
+        value?: unknown;
+        field?: string | undefined;
+    };
+    maxIterations?: number | undefined;
+    counterField?: string | undefined;
+    onMaxIterations?: "error" | "exit" | "force-exit" | undefined;
+    exitNode?: string | undefined;
+}, {
+    condition: {
+        type: "equals" | "not_equals" | "contains" | "greater_than" | "less_than" | "exists" | "not_exists" | "custom";
+        value?: unknown;
+        field?: string | undefined;
+    };
+    maxIterations?: number | undefined;
+    counterField?: string | undefined;
+    onMaxIterations?: "error" | "exit" | "force-exit" | undefined;
+    exitNode?: string | undefined;
+}>;
+/**
+ * Validate a loop configuration
+ */
+export declare function validateLoopConfig(config: LoopConfig): boolean;
+//# sourceMappingURL=loop-edge.d.ts.map

package/dist/edges/loop-edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-edge.d.ts","sourceRoot":"","sources":["../../src/edges/loop-edge.ts"],"names":[],"mappings":"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"}