lulz 1.0.2 → 2.0.0

package/src/flow.js

@@ -1,38 +1,77 @@
 /**
- * lulz - A reactive dataflow system inspired by FFmpeg filtergraph
- *
- * Syntax:
- *   [source, ...transforms, destination]
- *
- * Where:
- *   - source: string (pipe name) or producer function
- *   - transforms: functions (outer or inner) or arrays for series
- *   - destination: string (pipe name) or consumer function
- *
- * Series processing:
- *   ['in', [a, b, c], 'out']  - a→b→c in sequence
- *
- * Fan-out (parallel):
- *   ['in', a, b, c, 'out']    - all receive same packet, all send to out
+ * lulz - Core Flow Engine
+ * 
+ * A reactive dataflow system that makes coders happy.
+ * 
+ * Processing Modes (2.0):
+ *   - Series (default):   ['in', a, b, c, 'out']     → a→b→c sequential
+ *   - Parallel (explicit): ['in', [a, b, c], 'out']  → all receive same packet
+ * 
+ * Helper functions for readability:
+ *   - series(a, b, c)   → sequential processing
+ *   - parallel(a, b, c) → fan-out processing
+ * 
+ * EventEmitter API:
+ *   - app.emit('pipeName', packet)  → inject packet
+ *   - app.on('pipeName', handler)   → intercept packets
  */
 
-// Distinguish outer (regular fn) from inner (arrow fn)
-function isOuter(fn) {
-  return typeof fn === 'function' && fn.hasOwnProperty('prototype');
-}
+import { EventEmitter } from 'events';
+
+
+// ─────────────────────────────────────────────────────────────
+// Function Type Detection
+// ─────────────────────────────────────────────────────────────
+
+export const isOuter = (fn) => 
+  typeof fn === 'function' && fn.hasOwnProperty('prototype');
+
+export const isInner = (fn) => 
+  typeof fn === 'function' && !fn.hasOwnProperty('prototype');
+
+export const isFlow = (obj) => 
+  obj && obj._isFlow === true;
+
+export const isParallel = (item) => 
+  Array.isArray(item) && item._parallel === true;
+
+export const isSeriesMarker = (item) => 
+  Array.isArray(item) && item._series === true;
 
-function isInner(fn) {
-  return typeof fn === 'function' && !fn.hasOwnProperty('prototype');
+
+// ─────────────────────────────────────────────────────────────
+// Processing Mode Markers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Mark functions for parallel (fan-out) processing
+ * All functions receive the same packet simultaneously
+ */
+export function parallel(...fns) {
+  const arr = [...fns];
+  arr._parallel = true;
+  return arr;
 }
 
-function isSeriesArray(item) {
-  return Array.isArray(item) && item.every(el => typeof el === 'function');
+/**
+ * Mark functions for series (sequential) processing
+ * Explicit marker, though series is the default
+ */
+export function series(...fns) {
+  const arr = [...fns];
+  arr._series = true;
+  return arr;
 }
 
+
+// ─────────────────────────────────────────────────────────────
+// Node Factory
+// ─────────────────────────────────────────────────────────────
+
 /**
  * Create a processing node
  */
-function makeNode(name, fn) {
+export function makeNode(name, fn) {
   const outputs = new Set();
 
   function send(packet) {
@@ -41,91 +80,173 @@ function makeNode(name, fn) {
     }
   }
 
-  function receive(packet) {
+  function node(packet) {
     fn(send, packet);
   }
 
-  receive.connect = (next) => {
+  node.connect = function(next) {
     outputs.add(next);
     return next;
   };
 
-  receive.disconnect = (next) => {
+  node.disconnect = function(next) {
     outputs.delete(next);
+    return next;
   };
 
-  receive.receive = receive;
-  Object.defineProperty(receive, 'name', { value: name, writable: false });
-  receive.outputs = outputs;
-  receive._isNode = true;
+  node.receive = node;
+  node.send = send;
+  node.nodeName = name;
+  node.outputs = outputs;
+  node._isNode = true;
 
-  return receive;
+  return node;
 }
 
-/**
- * Create a pass-through pipe
- */
-function makePipe(name) {
-  return makeNode(name, (send, packet) => send(packet));
-}
 
-/**
- * Build a series chain: a→b→c
- * Returns { input, output } nodes
- */
-function buildSeries(fns, context, prepareFunction) {
-  if (fns.length === 0) {
-    const passthrough = makeNode('passthrough', (send, packet) => send(packet));
-    return { input: passthrough, output: passthrough };
-  }
-
-  const nodes = fns.map((fn, i) => {
-    const inner = prepareFunction(fn);
-    return makeNode(fn.name || `series-${i}`, inner);
-  });
-
-  // Chain them: node[0] → node[1] → ... → node[n-1]
-  for (let i = 0; i < nodes.length - 1; i++) {
-    nodes[i].connect(nodes[i + 1]);
-  }
-
-  return {
-    input: nodes[0],
-    output: nodes[nodes.length - 1]
-  };
-}
+// ─────────────────────────────────────────────────────────────
+// Main Flow Builder
+// ─────────────────────────────────────────────────────────────
 
 /**
- * Main flow builder
+ * Create a reactive flow from a graph definition
+ * 
+ * @param {Array} graph - Array of pipeline definitions
+ * @param {Object} context - Shared context object
+ * @returns {EventEmitter} Flow instance with emit/on API
  */
-function flow(graph, context = {}) {
-  const pipes = {};
-  const nodes = [];
-  const producers = [];
-
-  function getPipe(name) {
-    if (!pipes[name]) {
-      pipes[name] = makePipe(name);
+export function flow(graph, context = {}) {
+  
+  // ─── EventEmitter Base ───
+  const app = new EventEmitter();
+  app._isFlow = true;
+  app._context = context;
+  app._pipes = {};
+  app._nodes = [];
+  app._producers = [];
+  app._cleanups = [];
+  
+  // Store original emit for internal use
+  const _originalEmit = app.emit.bind(app);
+
+  
+  // ─── Pipe Management ───
+  
+  const getPipe = (name) => {
+    if (!app._pipes[name]) {
+      const node = makeNode(`pipe:${name}`, (send, packet) => {
+        // Notify EventEmitter listeners (use original to avoid loop)
+        _originalEmit(name, packet);
+        // Continue down the chain
+        send(packet);
+      });
+      app._pipes[name] = node;
     }
-    return pipes[name];
-  }
+    return app._pipes[name];
+  };
 
-  // Convert any function to a ready-to-use inner function
-  function prepareFunction(fn) {
+  
+  // ─── Function Preparation ───
+  
+  const prepareFunction = (fn) => {
     if (isOuter(fn)) {
-      // Factory function: call with empty options, bind context
+      // Factory function: bind context, call with empty options
       const bound = fn.bind({ context });
       return bound({});
     } else {
-      // Arrow (inner) function - wrap to provide context
-      return (send, packet) => {
-        // Create a this-like object for arrow functions via closure
-        fn(send, packet);
-      };
+      // Already an inner (arrow) function
+      return fn;
     }
-  }
+  };
+
+  
+  // ─── Build Series Chain ───
+  
+  const buildSeries = (fns) => {
+    if (fns.length === 0) {
+      const passthrough = makeNode('passthrough', (send, packet) => send(packet));
+      return { input: passthrough, output: passthrough };
+    }
+
+    const nodes = fns.map((fn, i) => {
+      if (isFlow(fn)) {
+        // Embedded flow - return its input, wire to its output
+        return { 
+          _isEmbeddedFlow: true, 
+          flow: fn,
+          receive: (packet) => fn.emit('in', packet)
+        };
+      }
+      
+      const inner = prepareFunction(fn);
+      return makeNode(fn.name || `series:${i}`, inner);
+    });
+
+    // Chain: node[0] → node[1] → ... → node[n-1]
+    for (let i = 0; i < nodes.length - 1; i++) {
+      const current = nodes[i];
+      const next = nodes[i + 1];
+      
+      if (current._isEmbeddedFlow) {
+        // Wire flow's output to next node
+        current.flow.on('out', (packet) => {
+          if (next._isEmbeddedFlow) {
+            next.flow.emit('in', packet);
+          } else {
+            next.receive(packet);
+          }
+        });
+      } else if (next._isEmbeddedFlow) {
+        // Wire current node to flow's input
+        current.connect({
+          receive: (packet) => next.flow.emit('in', packet)
+        });
+      } else {
+        current.connect(next);
+      }
+    }
+
+    // Return input of first, output of last
+    const first = nodes[0];
+    const last = nodes[nodes.length - 1];
+    
+    return {
+      input: first._isEmbeddedFlow 
+        ? { receive: (packet) => first.flow.emit('in', packet) }
+        : first,
+      output: last._isEmbeddedFlow
+        ? { connect: (next) => last.flow.on('out', (packet) => next.receive(packet)) }
+        : last
+    };
+  };
+
+  
+  // ─── Build Parallel Fan-out ───
+  
+  const buildParallel = (fns, dest) => {
+    const nodes = [];
+    
+    for (const fn of fns) {
+      if (isFlow(fn)) {
+        // Embedded flow
+        const adapter = {
+          receive: (packet) => fn.emit('in', packet),
+          connect: (next) => fn.on('out', (packet) => next.receive(packet))
+        };
+        nodes.push(adapter);
+      } else {
+        const inner = prepareFunction(fn);
+        const node = makeNode(fn.name || 'parallel', inner);
+        nodes.push(node);
+      }
+    }
+    
+    return nodes;
+  };
 
-  // Process each line in the graph
+  
+  // ─── Process Graph ───
+  
   for (const line of graph) {
     if (!Array.isArray(line) || line.length < 2) continue;
 
@@ -134,180 +255,206 @@ function flow(graph, context = {}) {
     const last = elements[elements.length - 1];
     const middle = elements.slice(1, -1);
 
-    // === SOURCE ===
+    // ─── SOURCE ───
     let source;
+    
     if (typeof first === 'string') {
       source = getPipe(first);
+    } else if (isFlow(first)) {
+      // Flow as source - create adapter
+      source = makeNode('flow-source', (send, packet) => send(packet));
+      first.on('out', (packet) => source.receive(packet));
+      first.start?.();
     } else if (typeof first === 'function') {
       // Producer function
-      const producerFn = isOuter(first) ? first.bind({ context })({}) : first;
-      const node = makeNode(first.name || 'producer', (send, packet) => send(packet));
+      const producerFn = isOuter(first) 
+        ? first.bind({ context })({}) 
+        : first;
+      
+      source = makeNode(first.name || 'producer', (send, packet) => send(packet));
       
-      // Store producer for later activation
-      producers.push({ fn: producerFn, node });
-      source = node;
-    } else if (first?._isFlow) {
-      // Subflow as source
-      source = first._output || getPipe('__subflow_out__');
+      app._producers.push({ 
+        fn: producerFn, 
+        node: source 
+      });
     }
 
-    // === DESTINATION ===
+    // ─── DESTINATION ───
     let dest;
+    
     if (typeof last === 'string') {
       dest = getPipe(last);
+    } else if (isFlow(last)) {
+      // Flow as destination
+      dest = { 
+        receive: (packet) => last.emit('in', packet),
+        _isNode: true
+      };
     } else if (typeof last === 'function') {
       const inner = prepareFunction(last);
       dest = makeNode(last.name || 'sink', inner);
-      nodes.push(dest);
-    } else if (last?._isFlow) {
-      // Subflow as destination
-      dest = last._input || getPipe('__subflow_in__');
+      app._nodes.push(dest);
     }
 
-    // === MIDDLE (transforms) ===
+    // ─── MIDDLE (transforms) ───
+    
     if (middle.length === 0) {
       // Direct connection
-      source.connect(dest);
+      if (source.connect) source.connect(dest);
+      
+    } else if (middle.length === 1 && isSeriesMarker(middle[0])) {
+      // Explicit series marker: ['in', series(a, b, c), 'out']
+      const { input, output } = buildSeries(middle[0]);
+      if (source.connect) source.connect(input);
+      if (output.connect) output.connect(dest);
+      
+    } else if (middle.length === 1 && (isParallel(middle[0]) || Array.isArray(middle[0]))) {
+      // Explicit parallel: ['in', [a, b, c], 'out'] or ['in', parallel(a,b,c), 'out']
+      const fns = middle[0];
+      const nodes = buildParallel(fns, dest);
+      
+      for (const node of nodes) {
+        if (source.connect) source.connect(node);
+        if (node.connect) node.connect(dest);
+      }
+      
     } else {
-      // Check if we have series arrays or fan-out
-      const hasSeries = middle.some(isSeriesArray);
+      // Default: SERIES processing (a → b → c)
+      const allFns = [];
       
-      if (middle.length === 1 && isSeriesArray(middle[0])) {
-        // Pure series: ['in', [a, b, c], 'out']
-        const { input, output } = buildSeries(middle[0], context, prepareFunction);
-        source.connect(input);
-        output.connect(dest);
-        nodes.push(input);
-      } else {
-        // Fan-out or mixed
-        for (const item of middle) {
-          if (isSeriesArray(item)) {
-            // Series within fan-out: ['in', a, [b, c, d], e, 'out']
-            const { input, output } = buildSeries(item, context, prepareFunction);
-            source.connect(input);
-            output.connect(dest);
-            nodes.push(input);
-          } else if (typeof item === 'function') {
-            // Regular transform in fan-out
-            const inner = prepareFunction(item);
-            const node = makeNode(item.name || 'transform', inner);
-            source.connect(node);
-            node.connect(dest);
-            nodes.push(node);
-          }
+      for (const item of middle) {
+        if (isParallel(item) || (Array.isArray(item) && !isSeriesMarker(item))) {
+          // Nested parallel within series - treat as single parallel block
+          allFns.push({ _parallelBlock: true, fns: item });
+        } else if (isSeriesMarker(item)) {
+          // Nested explicit series
+          allFns.push(...item);
+        } else {
+          allFns.push(item);
         }
       }
+      
+      // Build the series chain
+      const { input, output } = buildSeries(allFns.filter(f => !f._parallelBlock));
+      
+      if (source.connect) source.connect(input);
+      if (output.connect) output.connect(dest);
     }
   }
 
-  // Create the flow object
-  const flowObj = {
-    pipes,
-    nodes,
-    producers,
-    _isFlow: true,
-
-    // Start all producers
-    start() {
-      for (const { fn, node } of producers) {
-        fn((packet) => node.receive(packet));
-      }
-      return this;
-    },
-
-    // Stop all producers (if they return cleanup functions)
-    stop() {
-      // TODO: implement cleanup
-      return this;
-    },
-
-    // Inject a packet into a pipe
-    inject(pipeName, packet) {
-      const pipe = pipes[pipeName];
-      if (pipe) {
-        pipe.receive(packet);
-      } else {
-        console.warn(`Pipe "${pipeName}" not found`);
+  
+  // ─── EventEmitter Injection Setup ───
+  
+  // Override emit to inject into pipes
+  app.emit = (event, packet) => {
+    // If it's a pipe name, inject the packet (which will trigger _originalEmit)
+    if (app._pipes[event] && packet !== undefined) {
+      app._pipes[event].receive(packet);
+      return true;
+    }
+    // For non-pipe events, use original emit
+    return _originalEmit(event, packet);
+  };
+
+  
+  // ─── API Methods ───
+  
+  app.start = () => {
+    for (const { fn, node } of app._producers) {
+      const cleanup = fn((packet) => node.receive(packet));
+      if (typeof cleanup === 'function') {
+        app._cleanups.push(cleanup);
       }
-      return this;
-    },
+    }
+    app.emit('start');
+    return app;
+  };
 
-    // Get a pipe for external connection
-    getPipe(name) {
-      return getPipe(name);
-    },
+  app.stop = () => {
+    for (const cleanup of app._cleanups) {
+      cleanup();
+    }
+    app._cleanups = [];
+    app.emit('stop');
+    return app;
+  };
 
-    // For subflow embedding
-    _input: pipes['in'],
-    _output: pipes['out'],
+  app.inject = (pipeName, packet) => {
+    app.emit(pipeName, packet);
+    return app;
   };
 
-  return flowObj;
+  app.pipe = (name) => getPipe(name);
+  
+  // Expose for subflow wiring
+  app._input = getPipe('in');
+  app._output = getPipe('out');
+
+  return app;
 }
 
+
+// ─────────────────────────────────────────────────────────────
+// Subflow Helper
+// ─────────────────────────────────────────────────────────────
+
 /**
- * Create a subflow that can be embedded in other flows
+ * Create a subflow - a reusable flow component
+ * Uses 'in' and 'out' pipes for embedding
  */
-function subflow(graph, context = {}) {
-  // Ensure the subflow has 'in' and 'out' pipes
-  const flowObj = flow(graph, context);
-  
-  // Mark as subflow
-  flowObj._isSubflow = true;
-  flowObj._input = flowObj.getPipe('in');
-  flowObj._output = flowObj.getPipe('out');
-
-  return flowObj;
+export function subflow(graph, context = {}) {
+  const sub = flow(graph, context);
+  sub._isSubflow = true;
+  return sub;
 }
 
+
+// ─────────────────────────────────────────────────────────────
+// Compose Helper
+// ─────────────────────────────────────────────────────────────
+
 /**
- * Compose multiple flows
+ * Compose multiple flows in sequence
  */
-function compose(...flows) {
-  // Connect flows in sequence
+export function compose(...flows) {
+  const composed = new EventEmitter();
+  composed._isFlow = true;
+  composed._isComposed = true;
+  composed._flows = flows;
+
+  // Wire flows together
   for (let i = 0; i < flows.length - 1; i++) {
     const current = flows[i];
     const next = flows[i + 1];
-    
-    if (current._output && next._input) {
-      current._output.connect(next._input);
-    }
+    current.on('out', (packet) => next.emit('in', packet));
   }
 
-  return {
-    _isFlow: true,
-    _isComposed: true,
-    flows,
-    _input: flows[0]?._input,
-    _output: flows[flows.length - 1]?._output,
-    
-    start() {
-      for (const f of flows) {
-        if (f.start) f.start();
-      }
-      return this;
-    },
-    
-    stop() {
-      for (const f of flows) {
-        if (f.stop) f.stop();
-      }
-      return this;
-    },
-    
-    inject(pipeName, packet) {
-      flows[0]?.inject(pipeName, packet);
-      return this;
+  // Expose first input, last output
+  composed._input = flows[0]?._input;
+  composed._output = flows[flows.length - 1]?._output;
+
+  composed.start = () => {
+    for (const f of flows) f.start?.();
+    return composed;
+  };
+
+  composed.stop = () => {
+    for (const f of flows) f.stop?.();
+    return composed;
+  };
+
+  // Forward 'in' to first flow
+  composed.emit = (event, packet) => {
+    if (event === 'in') {
+      flows[0]?.emit('in', packet);
     }
+    return EventEmitter.prototype.emit.call(composed, event, packet);
   };
-}
 
-export {
-  flow,
-  subflow,
-  compose,
-  makeNode,
-  makePipe,
-  isOuter,
-  isInner,
-};
+  // Forward 'out' from last flow
+  flows[flows.length - 1]?.on('out', (packet) => {
+    EventEmitter.prototype.emit.call(composed, 'out', packet);
+  });
+
+  return composed;
+}