@synergenius/flow-weaver 0.3.0 → 0.4.1

package/docs/reference/export-interface.md

@@ -0,0 +1,229 @@
+---
+name: Export Interface (Ports)
+description: How to define workflow input/output ports, scoped iteration, and forEach patterns
+keywords: [ports, interface, inputs, outputs, scoped, forEach, iteration, param, returns, workflow]
+---
+
+# Code-First Architecture
+
+Flow Weaver generates JS/TS files from TypeScript sources with `@flowWeaver` annotations. Each export becomes a callable function.
+
+Any `.ts`, `.tsx`, `.js`, or `.jsx` file with `@flowWeaver` annotations works.
+
+# Port Definition
+
+## Workflow Inputs (@param)
+
+Use JSDoc `@param` to define Start node ports:
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @param data - Input data to process
+ * @param [optional] - Optional input (brackets = optional in TS type)
+ * @param [withDefault=42] - Optional with default value
+ */
+export function myWorkflow(
+  execute: boolean,
+  params: { data: any; optional?: any; withDefault?: number }
+) { ... }
+```
+
+**IMPORTANT:**
+
+- Second parameter MUST be named `params` - generator uses this name
+- Optional `[param]` marks the TypeScript type as optional, but **if you connect to that port, you must provide a value**. Use optional params for ports that may not be connected.
+
+## Workflow Outputs (@returns)
+
+Use JSDoc `@returns` to define Exit node ports:
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @returns result - The output result
+ * @returns status - Status message
+ */
+export function myWorkflow(...): {
+  onSuccess: boolean;
+  onFailure: boolean;
+  result: any;
+  status: string
+} { ... }
+```
+
+## Node Inputs/Outputs
+
+Use `@input` and `@output` for node types. **Inputs become direct parameters:**
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @input value - Value to process
+ * @input count - Number of times
+ * @output result - Processed result
+ */
+function processNode(execute: boolean, value: any, count: number) { ... }
+//                                     ^           ^
+//                               Direct parameters (NOT wrapped in object)
+```
+
+# Mandatory Ports
+
+Always present on every node/workflow:
+
+**Input:**
+
+- `execute` (STEP) - First function parameter
+
+**Output:**
+
+- `onSuccess` (STEP) - In return type
+- `onFailure` (STEP) - In return type
+
+# Async Workflows
+
+Use `async` keyword on function - no annotation needed:
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @param data - Input
+ * @returns result - Output
+ */
+export async function asyncWorkflow(
+  execute: boolean,
+  params: { data: any }
+): Promise<{ onSuccess: boolean; onFailure: boolean; result: any }> {
+  // async implementation
+}
+```
+
+# Scoped Ports (Iteration/Looping)
+
+For iteration (forEach), use **per-port scopes** with `scope:scopeName` suffix on ports.
+
+## 1. Define ForEach Node Type
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @label For Each
+ * @input items - Array to iterate
+ * @output start scope:processItem - Mandatory: triggers child execute
+ * @output item scope:processItem - Current item to process
+ * @input success scope:processItem - Mandatory: from child onSuccess
+ * @input failure scope:processItem - Mandatory: from child onFailure
+ * @input processed scope:processItem - Result from child
+ * @output results - Collected results
+ */
+function forEach(
+  execute: boolean,
+  items: any[],
+  processItem: (start: boolean, item: any) => { success: boolean; failure: boolean; processed: any }
+) {
+  if (!execute) return { onSuccess: false, onFailure: false, results: [] };
+  const results = items.map((item) => processItem(true, item).processed);
+  return { onSuccess: true, onFailure: false, results };
+}
+```
+
+Key points:
+
+- Scope name (`processItem`) MUST match callback parameter name
+- Callback is auto-generated by compiler, receives scoped port values as args
+- The node implementation iterates by calling callback for each item
+- Mandatory scoped STEP ports: `start` (output), `success`/`failure` (inputs)
+
+## 2. Use ForEach in Workflow
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @node loop forEach
+ * @node proc processor loop.processItem
+ * @connect Start.execute -> loop.execute
+ * @connect Start.items -> loop.items
+ * @connect loop.start:processItem -> proc.execute
+ * @connect loop.item:processItem -> proc.item
+ * @connect proc.result -> loop.processed:processItem
+ * @connect proc.onSuccess -> loop.success:processItem
+ * @connect proc.onFailure -> loop.failure:processItem
+ * @connect loop.results -> Exit.results
+ * @connect loop.onSuccess -> Exit.onSuccess
+ * @connect loop.onFailure -> Exit.onFailure
+ */
+```
+
+Key syntax:
+
+- `@node proc processor loop.processItem` - child node inside `loop`'s `processItem` scope
+- `loop.item:processItem` - scoped OUTPUT port (`:scopeName` suffix)
+- `loop.processed:processItem` - scoped INPUT port (`:scopeName` suffix)
+- Connect child's `execute`/`onSuccess`/`onFailure` to scope's mandatory ports
+
+**IMPORTANT:** Don't forget to wire `Start.execute` and `Exit.onSuccess/onFailure`!
+
+# Common Mistakes
+
+**Wrong node signature (wrapping inputs)**
+
+```typescript
+// WRONG - inputs wrapped in object
+function node(execute: boolean, params: { value: any }) { ... }
+
+// CORRECT - direct parameters for nodes
+function node(execute: boolean, value: any) { ... }
+```
+
+**Missing execute parameter**
+
+```typescript
+// WRONG - no execute
+function node(value: any) { ... }
+
+// CORRECT
+function node(execute: boolean, value: any) { ... }
+```
+
+**Missing return properties**
+
+```typescript
+// WRONG - missing onFailure
+return { onSuccess: true, result: 42 };
+
+// CORRECT
+return { onSuccess: true, onFailure: false, result: 42 };
+```
+
+**Multiple connections to same Exit port**
+
+```typescript
+// PROBLEMATIC - only one value will be used
+@connect nodeA.result -> Exit.output
+@connect nodeB.result -> Exit.output
+
+// BETTER - use separate Exit ports
+@connect nodeA.result -> Exit.successOutput
+@connect nodeB.result -> Exit.errorOutput
+```
+
+**Using reserved names for node types**
+
+```typescript
+// WRONG - 'process' is a Node.js global
+function process(execute: boolean, item: any) { ... }
+
+// CORRECT - use non-reserved names
+function processItem(execute: boolean, item: any) { ... }
+```
+
+Avoid: `process`, `module`, `require`, `exports`, `console`, `global`
+
+# Validation
+
+Always validate after changes:
+
+```bash
+flow-weaver validate <file>
+```

package/docs/reference/iterative-development.md

@@ -0,0 +1,186 @@
+---
+name: Flow Weaver Iterative Development
+description: Step-by-step workflow building with test-driven approach
+keywords: [iterative, TDD, step-by-step, building, testing, development process, expression, validate]
+---
+
+# Build Process
+
+Test every step. Building everything before testing is like writing 1000 lines of code without running it.
+
+Workflows are TypeScript files with @flowWeaver annotations. Any `.ts`, `.tsx`, `.js`, or `.jsx` file works.
+
+### Phase 1: Plan your Flow
+
+First understand what the Flow is trying to achieve. Think of it as a function - it takes in data and returns data.
+
+Plan:
+
+- Export Interface (inputs/outputs)
+- What nodes are needed
+- If async behavior is required (use `async` function)
+
+The whole point is for each node to become a module - encapsulated abstracted logic that can be swapped and changed.
+
+### Phase 2: Specify and Test the Export Interface
+
+Create the Export Interface by editing the workflow file directly.
+
+Define:
+
+- Start ports using `@param` JSDoc tags
+- Exit ports using `@returns` JSDoc tags
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @param input - Input data
+ * @returns result - Output result
+ */
+export function myWorkflow(
+  execute: boolean,
+  params: { input: any }
+): { onSuccess: boolean; onFailure: boolean; result: any } {
+  return { onSuccess: true, onFailure: false, result: null };
+}
+```
+
+**IMPORTANT:** Second parameter MUST be named `params`.
+
+Test:
+
+```bash
+flow-weaver validate <file>
+```
+
+### Phase 3: Create the Nodes
+
+**Start with `@expression` mode for all nodes.** Only switch to normal mode when you need explicit branching (quality gates, conditional routing, error-with-data patterns).
+
+Create nodes by adding `@flowWeaver nodeType` annotated functions.
+
+Create at most 3 nodes at a time, test each.
+
+Default to expression mode. Use normal mode only for:
+- **Quality gates** -- routing to different paths based on success/failure
+- **Conditional routing** -- explicit `onSuccess`/`onFailure` branching
+- **Error-with-data patterns** -- returning error details alongside the failure signal
+
+**Expression mode (recommended for most nodes):**
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @expression
+ * @label Add Numbers
+ * @input a - First number
+ * @input b - Second number
+ * @output result - Sum
+ */
+function addNumbers(a: number, b: number): number {
+  return a + b;
+}
+```
+
+> Use `@expression` for most nodes. Only use normal mode when you need custom failure handling or void returns.
+
+**Normal mode (for custom error handling):**
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @label Risky Operation
+ * @input url - URL to fetch
+ * @output data - Fetched data
+ */
+async function riskyFetch(
+  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 };
+  }
+}
+```
+
+Add node instances with `@node` and connections with `@connect`:
+
+```typescript
+/**
+ * @flowWeaver workflow
+ * @node adder addNumbers
+ * @connect Start.a -> adder.a
+ * @connect adder.result -> Exit.result
+ * @position adder 180 0
+ */
+```
+
+> 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.
+
+Test after each change:
+
+```bash
+flow-weaver validate <file>
+```
+
+### Phase 4: Finalizing
+
+After everything is connected:
+
+1. Run multiple test scenarios
+2. If not returning values, check return type
+3. Verify node positioning with `@position nodeId x y` (in pixels)
+4. Inspect the compiled source file for errors (compilation modifies the file in-place)
+
+Final validation:
+
+```bash
+flow-weaver validate <file>
+flow-weaver compile <file>
+flow-weaver describe <file>  # Get workflow structure as JSON
+```
+
+## Common Mistakes
+
+### 1. Missing STEP Connections (Normal Mode) or Adding Unnecessary Ones (Expression Mode)
+
+**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 only for branching (e.g., routing `onFailure` to a different node).
+
+### 2. Wrapping Node Inputs in Object
+
+```typescript
+// WRONG -- this is workflow style, not node style
+function myNode(execute: boolean, params: { a: number; b: number });
+
+// CORRECT -- node inputs are direct parameters
+function myNode(execute: boolean, a: number, b: number);
+```
+
+### 3. Mixing STEP and Data Ports
+
+`onSuccess` -> `inputData` is WRONG. STEP ports only connect to STEP ports. Data ports only connect to data ports.
+
+### 4. Forgetting Exit Connections
+
+If the workflow should return values, connect them: `@connect lastNode.result -> Exit.resultPort`. Also connect `lastNode.onSuccess -> Exit.onSuccess`.
+
+### 5. Not Validating After Each Change
+
+Always run `flow-weaver validate` after adding nodes/connections. Don't batch 10 changes then validate -- validate incrementally.
+
+### 6. Using Normal Mode When Expression Mode Works
+
+If the function returns a value and doesn't need custom error handling, 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 handles all of it.
+
+**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.
+
+### 7. Defaulting to Normal Mode
+
+Normal mode adds boilerplate that expression mode handles automatically. Default to `@expression` for every node. Only reach for normal mode when the function needs to:
+- Route to different downstream nodes on success vs. failure
+- Return error data (not just signal failure)
+- Perform void side-effects with explicit control flow