@synergenius/flow-weaver 0.33.2 → 0.44.0

package/docs/reference/iterative-development.md

@@ -41,11 +41,11 @@ export function myWorkflow(
   execute: boolean,
   params: { input: any }
 ): { onSuccess: boolean; onFailure: boolean; result: any } {
-  return { onSuccess: true, onFailure: false, result: null };
+  throw new Error('generated body was not installed');
 }
 ```
 
-**IMPORTANT:** Second parameter MUST be named `params`.
+**IMPORTANT:** Second parameter MUST be named `params`. The body is a stub: the compiler installs the real one, so never return fake data from it. The signature (`execute`, `params`, `onSuccess`/`onFailure` plus the `@returns` ports) is fixed regardless of the node modes used inside.
 
 Test:
 
@@ -81,43 +81,65 @@ function addNumbers(a: number, b: number): number {
 }
 ```
 
-> Use `@expression` for most nodes. Expression nodes support failure branching via throw. Only use normal mode for error-with-data patterns or void returns.
+> Use `@expression` for most nodes. A throw in an expression node marks it failed and propagates the error out of the workflow call. Use normal mode when a failure must be routed to another node or to `Exit.onFailure`, must carry data, or the function returns void.
 
-**Normal mode (for custom error handling):**
+**Async expression mode (fetching, I/O):**
+
+An `async` function is still an expression node. Its resolved value is the output; a throw (or a rejected promise) marks the node failed and propagates out of the workflow call:
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @expression
+ * @label Fetch JSON
+ * @input url - URL to fetch
+ * @output data - Parsed response body
+ */
+async function fetchJson(url: string): Promise<any> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+  return await res.json();
+}
+```
+
+**Normal mode (error-with-data only):**
+
+Switch to normal mode only when a downstream node needs data from the failure itself. Here the HTTP status must be available even when the fetch fails, so the node sets `onSuccess`/`onFailure` by hand:
 
 ```typescript
 /**
  * @flowWeaver nodeType
- * @label Risky Operation
+ * @label Fetch With Status
  * @input url - URL to fetch
- * @output data - Fetched data
+ * @output data - Parsed response body
+ * @output status - HTTP status code, also reported on failure
  */
-async function riskyFetch(
+async function fetchWithStatus(
   execute: boolean,
   url: string
-): Promise<{ onSuccess: boolean; onFailure: boolean; data: any }> {
-  if (!execute) return { onSuccess: false, onFailure: false, data: null };
-  try {
-    const res = await fetch(url);
-    return { onSuccess: true, onFailure: false, data: await res.json() };
-  } catch {
-    return { onSuccess: false, onFailure: true, data: null };
-  }
+): Promise<{ onSuccess: boolean; onFailure: boolean; data: any; status: number }> {
+  // Normal mode: the caller needs the status code even when the fetch fails (error-with-data).
+  if (!execute) return { onSuccess: false, onFailure: false, data: null, status: 0 };
+  const res = await fetch(url);
+  if (!res.ok) return { onSuccess: false, onFailure: true, data: null, status: res.status };
+  return { onSuccess: true, onFailure: false, data: await res.json(), status: res.status };
 }
 ```
 
-Add node instances with `@node` and connections with `@connect`:
+Add node instances with `@node` and declare the route with `@path`:
 
 ```typescript
 /**
  * @flowWeaver workflow
- * @node adder addNumbers [position: 180 0]
- * @connect Start.a -> adder.a
- * @connect adder.result -> Exit.result
+ * @param a - First number
+ * @param b - Second number
+ * @returns result - Sum
+ * @node adder addNumbers
+ * @path Start -> adder -> Exit
  */
 ```
 
-> Expression nodes don't need explicit STEP connections -- the compiler infers execution order from data connections. Add STEP connections explicitly only when you need branching control.
+> `@path` writes the STEP connections and wires the data ports by name: `adder.a` and `adder.b` come from the `Start` params, and `Exit.result` from `adder.result`. Name your ports consistently and a linear pipeline needs no `@connect` at all. Add `@connect` only for ports whose names differ, and `:ok`/`:fail` suffixes on a step when you need branching control.
 
 Test after each change:
 
@@ -131,8 +153,7 @@ After everything is connected:
 
 1. Run multiple test scenarios
 2. If not returning values, check return type
-3. Verify node positioning with `[position: x y]` on `@node` lines (in pixels)
-4. Inspect the compiled source file for errors (compilation modifies the file in-place)
+3. Inspect the compiled source file for errors (compilation modifies the file in-place)
 
 Final validation:
 
@@ -144,18 +165,19 @@ fw describe <file>  # Get workflow structure as JSON
 
 ## Common Mistakes
 
-### 1. Missing STEP Connections (Normal Mode) or Adding Unnecessary Ones (Expression Mode)
+### 1. Leaving a Node Off the Path
 
-**Normal mode nodes** need explicit STEP wiring: `@connect Start.execute -> firstNode.execute`. Without this, no node will run. **Expression mode** nodes auto-wire STEP connections from data flow -- you only need data connections for linear pipelines. Add explicit STEP connections when you need to route `onFailure` to a specific node (both expression and normal mode nodes support this).
+Every node needs a STEP source. Put it on a `@path` and the compiler writes `execute`/`onSuccess` wiring for it, whatever its mode. **Normal mode nodes** left off the path need explicit STEP wiring by hand: `@connect Start.execute -> firstNode.execute`. Without either, the node never runs. **Expression mode** nodes auto-wire STEP connections from data flow, but a `@path` is still the clearest statement of order. To route `onFailure` to a specific node, use a `:fail` suffix on the path step (or an explicit STEP `@connect`); both expression and normal mode nodes support this.
 
 ### 2. Wrapping Node Inputs in Object
 
 ```typescript
 // WRONG -- this is workflow style, not node style
-function myNode(execute: boolean, params: { a: number; b: number });
+function myNode(params: { a: number; b: number });
 
 // CORRECT -- node inputs are direct parameters
-function myNode(execute: boolean, a: number, b: number);
+function myNode(a: number, b: number): number; // expression mode
+function myNode(execute: boolean, a: number, b: number); // normal mode only
 ```
 
 ### 3. Mixing STEP and Data Ports
@@ -164,7 +186,7 @@ function myNode(execute: boolean, a: number, b: number);
 
 ### 4. Forgetting Exit Connections
 
-If the workflow should return values, connect them: `@connect lastNode.result -> Exit.resultPort`. Also connect `lastNode.onSuccess -> Exit.onSuccess`.
+If the workflow should return values, end the `@path` at `Exit` and name each `@returns` port after the output that produces it: `@path ... -> lastNode -> Exit` wires `lastNode.result -> Exit.result` and `lastNode.onSuccess -> Exit.onSuccess`. For a port whose name differs, add `@connect lastNode.result -> Exit.resultPort`. A `Start` param never reaches `Exit` by name; write that pass-through as an explicit `@connect`.
 
 ### 5. Not Validating After Each Change
 
@@ -172,7 +194,7 @@ Always run `fw validate` after adding nodes/connections. Don't batch 10 changes
 
 ### 6. Using Normal Mode When Expression Mode Works
 
-If the function returns a value, use `@expression`. It's simpler and less error-prone. Expression mode eliminates the `execute` parameter, the `if (!execute)` guard, and the `onSuccess`/`onFailure` boilerplate. The compiler wraps the call in try/catch, so throwing triggers the `onFailure` path automatically.
+If the function returns a value, use `@expression`. It's simpler and less error-prone. Expression mode eliminates the `execute` parameter, the `if (!execute)` guard, and the `onSuccess`/`onFailure` boilerplate. The compiler wraps the call in try/catch: a throw marks the node's `onFailure` port and is then rethrown out of the workflow call. If another node must run on failure, that node's predecessor has to be a normal-mode node returning `onFailure: true`.
 
 **Rule of thumb:** If you are writing `if (!execute) return ...` and a `try/catch` that just returns `{ onSuccess: false, onFailure: true }`, you should be using expression mode instead.