lulz 1.0.0

package/examples.js

@@ -0,0 +1,317 @@
+/**
+ * lulz Examples
+ *
+ * Various patterns and use cases
+ */
+
+import {
+  flow,
+  subflow,
+  compose,
+  Inject,
+  Debug,
+  Function as Fn,
+  Change,
+  Switch,
+  Template,
+  Delay,
+  Join,
+  Split,
+} from './index.js';
+
+// Custom logger to capture output
+const logs = [];
+const logger = (...args) => {
+  logs.push(args.map(a => typeof a === 'object' ? JSON.stringify(a) : a).join(' '));
+  console.log(...args);
+};
+
+// ============================================================
+// EXAMPLE 1: Basic pipe connection
+// ============================================================
+
+console.log('\n=== Example 1: Basic Inject → Debug ===\n');
+
+const example1 = flow([
+  [Inject({ payload: 'Hello FlowGraph!', once: true }), Debug({ name: 'output', logger })],
+]);
+
+example1.start();
+
+// ============================================================
+// EXAMPLE 2: Series processing with [a, b, c] syntax
+// ============================================================
+
+console.log('\n=== Example 2: Series Processing ===\n');
+
+// Each step adds to the message
+function addStep(name) {
+  return function(options) {
+    return (send, packet) => {
+      const steps = packet.steps || [];
+      logger(`[${name}] Processing...`);
+      send({ ...packet, steps: [...steps, name] });
+    };
+  };
+}
+
+const example2 = flow([
+  ['input', [addStep('validate'), addStep('transform'), addStep('enrich')], Debug({ name: 'result', logger })],
+]);
+
+example2.inject('input', { payload: { data: 'test' } });
+
+// ============================================================
+// EXAMPLE 3: Fan-out (parallel processing)
+// ============================================================
+
+console.log('\n=== Example 3: Fan-out Processing ===\n');
+
+function processA(options) {
+  return (send, packet) => {
+    logger('[A] Fast processing');
+    send({ ...packet, processedBy: 'A' });
+  };
+}
+
+function processB(options) {
+  return (send, packet) => {
+    logger('[B] Detailed processing');
+    send({ ...packet, processedBy: 'B', extra: 'details' });
+  };
+}
+
+const example3 = flow([
+  ['input', processA, processB, 'output'], // Both receive same input
+  ['output', Debug({ name: 'fan-out-result', logger })],
+]);
+
+example3.inject('input', { payload: 'parallel test' });
+
+// ============================================================
+// EXAMPLE 4: Mixed pre-configured and auto-configured functions
+// ============================================================
+
+console.log('\n=== Example 4: Pre-configured Functions ===\n');
+
+function multiplier(options) {
+  const factor = options.factor || 1;
+  return (send, packet) => {
+    send({ ...packet, payload: packet.payload * factor });
+  };
+}
+
+const example4 = flow([
+  ['input', [
+    multiplier({ factor: 2 }),   // Pre-configured: ×2
+    multiplier,                   // Auto-configured with {}: ×1
+    multiplier({ factor: 5 }),   // Pre-configured: ×5
+  ], Debug({ name: 'multiplied', logger })],
+]);
+
+example4.inject('input', { payload: 10 }); // 10 → 20 → 20 → 100
+
+// ============================================================
+// EXAMPLE 5: Conditional routing with Switch
+// ============================================================
+
+console.log('\n=== Example 5: Conditional Routing ===\n');
+
+const example5 = flow([
+  ['input', Switch({
+    property: 'payload.temperature',
+    rules: [
+      { type: 'gte', value: 30 },
+    ]
+  }), 'hot'],
+  
+  ['input', Switch({
+    property: 'payload.temperature',
+    rules: [
+      { type: 'lt', value: 30 },
+    ]
+  }), 'cold'],
+  
+  ['hot', Debug({ name: '🔥 HOT', logger })],
+  ['cold', Debug({ name: '❄️ COLD', logger })],
+]);
+
+example5.inject('input', { payload: { temperature: 35, city: 'Phoenix' } });
+example5.inject('input', { payload: { temperature: 15, city: 'Seattle' } });
+
+// ============================================================
+// EXAMPLE 6: Template rendering
+// ============================================================
+
+console.log('\n=== Example 6: Template Rendering ===\n');
+
+const example6 = flow([
+  ['input', Template({
+    template: '{{payload.name}} from {{payload.city}} says: "{{payload.message}}"'
+  }), Debug({ name: 'message', logger })],
+]);
+
+example6.inject('input', { 
+  payload: { 
+    name: 'Alice', 
+    city: 'Wonderland',
+    message: 'Down the rabbit hole!'
+  } 
+});
+
+// ============================================================
+// EXAMPLE 7: Subflow embedding
+// ============================================================
+
+console.log('\n=== Example 7: Subflow (Reusable Component) ===\n');
+
+// Create a reusable "sanitizer" subflow
+const sanitizer = subflow([
+  ['in', Fn({
+    func: (msg) => ({
+      ...msg,
+      payload: String(msg.payload).trim().toLowerCase()
+    })
+  }), 'out'],
+]);
+
+// Use it in main flow
+const example7 = flow([
+  ['input', 'process'],
+  ['process', Debug({ name: 'sanitized', logger })],
+]);
+
+// Wire up subflow
+example7.pipes['input'].connect(sanitizer._input);
+sanitizer._output.connect(example7.pipes['process']);
+
+example7.inject('input', { payload: '  HELLO WORLD  ' });
+
+// ============================================================
+// EXAMPLE 8: Blog builder (original use case)
+// ============================================================
+
+console.log('\n=== Example 8: Blog Builder Pattern ===\n');
+
+// Simulated producer functions
+function socket(channel) {
+  return (send) => {
+    logger(`[socket] Listening on: ${channel}`);
+    // Simulate receiving data
+    setTimeout(() => {
+      send({ payload: { type: 'new-post', id: 123 }, channel });
+    }, 50);
+  };
+}
+
+function watch(folder) {
+  return (send) => {
+    logger(`[watch] Watching: ${folder}`);
+    // Simulate file change
+    setTimeout(() => {
+      send({ payload: { type: 'file-changed', path: `${folder}/image.png` }, folder });
+    }, 75);
+  };
+}
+
+// Processing functions
+function cover(options) {
+  return (send, packet) => {
+    logger('[cover] Generating cover image...');
+    send({ ...packet, cover: true });
+  };
+}
+
+function audio(options) {
+  return (send, packet) => {
+    logger('[audio] Processing audio...');
+    send({ ...packet, audio: true });
+  };
+}
+
+function post(options) {
+  return (send, packet) => {
+    logger('[post] Building post...');
+    send({ ...packet, built: true });
+  };
+}
+
+function assets(options) {
+  return (send, packet) => {
+    logger('[assets] Processing asset:', packet.payload?.path);
+    send(packet);
+  };
+}
+
+function pagerizer(options) {
+  return (send, packet) => {
+    logger('[pagerizer] Updating pagination...');
+    send({ ...packet, paginated: true });
+  };
+}
+
+const blogBuilder = flow([
+  [socket('post'), 'post'],               // Socket events → post pipe
+  [watch('assets'), 'asset'],             // File watcher → asset pipe
+  ['post', Debug({ name: 'new-post', logger })],           // Log new posts
+  ['asset', assets],                      // Process assets
+  ['post', cover, audio, post, 'updated'], // Fan-out: cover, audio, post all run
+  ['updated', pagerizer, Debug({ name: 'updated', logger })],
+], { username: 'alice' });
+
+blogBuilder.start();
+
+// ============================================================
+// EXAMPLE 9: Series with mixed fan-out
+// ============================================================
+
+console.log('\n=== Example 9: Complex Pipeline ===\n');
+
+function validate(options) {
+  return (send, packet) => {
+    if (packet.payload) {
+      logger('[validate] ✓ Valid');
+      send(packet);
+    } else {
+      logger('[validate] ✗ Invalid - dropped');
+    }
+  };
+}
+
+function enrichA(options) {
+  return (send, packet) => {
+    logger('[enrichA] Adding metadata A');
+    send({ ...packet, metaA: true });
+  };
+}
+
+function enrichB(options) {
+  return (send, packet) => {
+    logger('[enrichB] Adding metadata B');
+    send({ ...packet, metaB: true });
+  };
+}
+
+function finalize(options) {
+  return (send, packet) => {
+    logger('[finalize] Completing...');
+    send({ ...packet, finalized: true });
+  };
+}
+
+// Complex pipeline: validate → (enrichA + enrichB in parallel) → finalize
+const example9 = flow([
+  ['input', [validate], 'validated'],     // Series: just validate
+  ['validated', enrichA, enrichB, 'enriched'], // Fan-out: both enrichers
+  ['enriched', [finalize], Debug({ name: 'final', logger })], // Series: finalize
+]);
+
+example9.inject('input', { payload: { data: 'important' } });
+
+// ============================================================
+// Summary
+// ============================================================
+
+setTimeout(() => {
+  console.log('\n=== All Examples Complete ===\n');
+}, 200);

package/index.js

@@ -0,0 +1,21 @@
+/**
+ * lulz - A reactive dataflow system
+ *
+ * Inspired by FFmpeg filtergraph notation and Node-RED
+ */
+
+export { flow, subflow, compose, makeNode, makePipe, isOuter, isInner } from './src/flow.js';
+export {
+  Inject,
+  Debug,
+  Function,
+  Change,
+  Switch,
+  Template,
+  Delay,
+  Join,
+  Split,
+  getProperty,
+  setProperty,
+  deleteProperty,
+} from './src/nodes.js';

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "lulz",
+  "version": "1.0.0",
+  "description": "A reactive dataflow system inspired by Visual Programming, FFmpeg filtergraph and Node-RED",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test",
+    "examples": "node examples.js"
+  },
+  "keywords": [
+    "dataflow",
+    "reactive",
+    "flow",
+    "pipeline",
+    "node-red"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/src/flow.js

@@ -0,0 +1,313 @@
+/**
+ * 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
+ */
+
+// Distinguish outer (regular fn) from inner (arrow fn)
+function isOuter(fn) {
+  return typeof fn === 'function' && fn.hasOwnProperty('prototype');
+}
+
+function isInner(fn) {
+  return typeof fn === 'function' && !fn.hasOwnProperty('prototype');
+}
+
+function isSeriesArray(item) {
+  return Array.isArray(item) && item.every(el => typeof el === 'function');
+}
+
+/**
+ * Create a processing node
+ */
+function makeNode(name, fn) {
+  const outputs = new Set();
+
+  function send(packet) {
+    for (const out of outputs) {
+      out.receive(packet);
+    }
+  }
+
+  function receive(packet) {
+    fn(send, packet);
+  }
+
+  receive.connect = (next) => {
+    outputs.add(next);
+    return next;
+  };
+
+  receive.disconnect = (next) => {
+    outputs.delete(next);
+  };
+
+  receive.receive = receive;
+  Object.defineProperty(receive, 'name', { value: name, writable: false });
+  receive.outputs = outputs;
+  receive._isNode = true;
+
+  return receive;
+}
+
+/**
+ * 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
+ */
+function flow(graph, context = {}) {
+  const pipes = {};
+  const nodes = [];
+  const producers = [];
+
+  function getPipe(name) {
+    if (!pipes[name]) {
+      pipes[name] = makePipe(name);
+    }
+    return pipes[name];
+  }
+
+  // Convert any function to a ready-to-use inner function
+  function prepareFunction(fn) {
+    if (isOuter(fn)) {
+      // Factory function: call with empty options, bind context
+      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);
+      };
+    }
+  }
+
+  // Process each line in the graph
+  for (const line of graph) {
+    if (!Array.isArray(line) || line.length < 2) continue;
+
+    const elements = [...line];
+    const first = elements[0];
+    const last = elements[elements.length - 1];
+    const middle = elements.slice(1, -1);
+
+    // === SOURCE ===
+    let source;
+    if (typeof first === 'string') {
+      source = getPipe(first);
+    } 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));
+      
+      // 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__');
+    }
+
+    // === DESTINATION ===
+    let dest;
+    if (typeof last === 'string') {
+      dest = getPipe(last);
+    } 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__');
+    }
+
+    // === MIDDLE (transforms) ===
+    if (middle.length === 0) {
+      // Direct connection
+      source.connect(dest);
+    } else {
+      // Check if we have series arrays or fan-out
+      const hasSeries = middle.some(isSeriesArray);
+      
+      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);
+          }
+        }
+      }
+    }
+  }
+
+  // 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`);
+      }
+      return this;
+    },
+
+    // Get a pipe for external connection
+    getPipe(name) {
+      return getPipe(name);
+    },
+
+    // For subflow embedding
+    _input: pipes['in'],
+    _output: pipes['out'],
+  };
+
+  return flowObj;
+}
+
+/**
+ * Create a subflow that can be embedded in other flows
+ */
+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;
+}
+
+/**
+ * Compose multiple flows
+ */
+function compose(...flows) {
+  // Connect flows in sequence
+  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);
+    }
+  }
+
+  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;
+    }
+  };
+}
+
+export {
+  flow,
+  subflow,
+  compose,
+  makeNode,
+  makePipe,
+  isOuter,
+  isInner,
+};