@doclo/flows 0.1.9 → 0.1.11

package/dist/index.d.ts

@@ -501,9 +501,12 @@ type SerializableConditionalStep = {
     branches: Record<string, SerializableFlow | FlowReference>;
 };
 /**
- * ForEach step (split + item flow)
+ * ForEach step (split + item flow OR branches by category)
+ *
+ * Two modes:
+ * 1. itemFlow: Single flow applied to ALL split items (original behavior)
+ * 2. branches: Different flows per category, items routed by split's `type` field
  *
- * itemFlow can be either an inline flow or a reference to a separate flow.
  * Use references to avoid hitting database JSON nesting limits.
  */
 type SerializableForEachStep = {
@@ -512,7 +515,15 @@ type SerializableForEachStep = {
     name?: string;
     nodeType: 'split';
     config: SplitConfig;
-    itemFlow: SerializableFlow | FlowReference;
+    /**
+     * Single flow for all items (original forEach behavior)
+     */
+    itemFlow?: SerializableFlow | FlowReference;
+    /**
+     * Category-based branches: items routed by their `type` field from split.
+     * Keys must match the categories defined in splitConfig.categories.
+     */
+    branches?: Record<string, SerializableFlow | FlowReference>;
 };
 /**
  * Route branch configuration
@@ -823,11 +834,22 @@ interface ConditionalCompositeConfig {
 declare function createConditionalCompositeNode(config: ConditionalCompositeConfig): NodeDef<FlowInput, unknown>;
 /**
  * Configuration for forEach composite node
+ *
+ * Two modes:
+ * 1. itemFlow: Single flow applied to ALL split items
+ * 2. branches: Different flows per category, items routed by split's `type` field
  */
 interface ForEachCompositeConfig {
     stepId: string;
     splitConfig: SplitConfig;
-    itemFlow: SerializableFlow | FlowReference;
+    /**
+     * Single flow for all items (original forEach behavior)
+     */
+    itemFlow?: SerializableFlow | FlowReference;
+    /**
+     * Category-based branches: items routed by their `type` field from split
+     */
+    branches?: Record<string, SerializableFlow | FlowReference>;
     providers: ProviderRegistry;
     flows: FlowRegistry;
 }

package/dist/index.js

@@ -1467,7 +1467,10 @@ function createConditionalCompositeNode(config) {
   };
 }
 function createForEachCompositeNode(config) {
-  const { stepId, splitConfig, itemFlow, providers, flows } = config;
+  const { stepId, splitConfig, itemFlow, branches, providers, flows } = config;
+  if (!itemFlow && !branches) {
+    throw new Error("ForEach composite requires either itemFlow or branches");
+  }
   return {
     key: "forEach-composite",
     run: async (input, ctx) => {
@@ -1503,12 +1506,24 @@ function createForEachCompositeNode(config) {
           ctx.emit(`${stepId}:itemCount`, items.length);
         }
         phase = "forEach";
-        const itemFlowDef = resolveBranchFlow(itemFlow, flows);
         const itemFlowResults = [];
         const results = await Promise.allSettled(
           items.map(async (item, index) => {
+            let targetFlowDef;
+            if (branches) {
+              const itemCategory = item.type;
+              const branchFlow = branches[itemCategory] ?? branches["other"];
+              if (!branchFlow) {
+                throw new Error(
+                  `No branch found for category "${itemCategory}" and no "other" branch defined. Available branches: ${Object.keys(branches).join(", ")}`
+                );
+              }
+              targetFlowDef = resolveBranchFlow(branchFlow, flows);
+            } else {
+              targetFlowDef = resolveBranchFlow(itemFlow, flows);
+            }
             const flow = buildFlowFromConfig(
-              itemFlowDef,
+              targetFlowDef,
               providers,
               flows,
               ctx?.observability?.config ? {
@@ -1518,6 +1533,7 @@ function createForEachCompositeNode(config) {
                   parentNode: stepId,
                   phase: "forEach",
                   itemIndex: index,
+                  itemCategory: item.type,
                   totalItems: items.length
                 }
               } : void 0
@@ -1941,6 +1957,7 @@ function buildFlowFromConfig(flowDef, providers, flows, options) {
         stepId: step.id,
         splitConfig: step.config,
         itemFlow: step.itemFlow,
+        branches: step.branches,
         providers,
         flows: flows || {}
       });