lulz 1.0.0

package/CHICKEN.md

@@ -0,0 +1,156 @@
+This is the original chiken scratch that started this project
+
+ ```js
+
+const fakeServer = new EventEmitter();
+let counter = 1;
+setInterval(()=>{
+  fakeServer.emit('fakeData', counter++);
+},1_000)
+
+
+// the actual program
+
+const context = {
+  username: 'alice',
+
+};
+
+const pipes = {};
+
+// PROGRAM EXAMPLE
+const blogBuilder = [
+
+  [ socket('post'), 'post' ], // monitor web socket for new post announcement
+  [ watch('assets'), 'asset' ], // watch assets folder for changes
+
+  [ 'post', log ], // log whan a new post arrives on post pipe
+
+  [ 'asset', assets ], // listen to asset pipe and call the asset funcion
+  [ 'post', cover, audio, post, 'updated' ], // listen to post pipe and call cover+aufio+post with same data (fan not series like in ffmpeg, series would requre array ['in', [a,b,c], 'out'], where a gets in, sends a out to b, b sends b out to c, and c sends to out pipe (or funcion if a funcion follows the array) this is a todo)
+  [ 'updated', pagerizer, log ],
+
+];
+
+
+const app = flow(blogBuilder, context);
+
+
+// User Functions (DO NOT IMPLEMENT YET)
+
+function log(options){ // outer declaration: allows user to configure the funcion in program array
+
+  return (send, packet) => { // inner funcion must be arrow as .arguments are used to set inner/outer apart
+    console.log( options, this.context, packet );
+    send(packet); /* send through */
+  }
+}
+
+// examples of producers
+
+function socket(options){
+  return (send)=>{
+    fakeServer.on('fakeData', counter=>send(counter))
+  }
+}
+
+function watch(options){
+  return (send)=>{
+    fakeServer.on('fakeData', counter=>send(counter))
+  }
+}
+
+
+
+// example sink/tranducer, just pass through
+function assets(options){ return (send, packet)=>send(packet)}
+function cover(options){ return (send, packet)=>send(packet)}
+function audio(options){ return (send, packet)=>send(packet)}
+function post(options){ return (send, packet)=>send(packet)}
+function pagerizer(options){ return (send, packet)=>send(packet)}
+
+
+
+
+
+
+// System Functions
+
+function flow(graph, context){
+
+  const directions = {from:0, to:2};
+
+  const [ inputs, transforms, outputs ] = graph.reduce((a, c)=>{
+    let direction = directions.from;
+    if(typeof c === 'string'){
+     a[direction].push(makePipe(c));
+    }else{
+      direction = directions.to; // flip direction
+      const isOuter = c?.arguments;
+      let fn;
+      if(isOuter){
+        // bind outer funcion
+        const bound = c.bind(context)
+        fn = bound({}); // apply empty config and retreive inner funcion
+      }else{
+        // already inner funcion
+        // set context to an already configured inner function
+        fn.context = context;
+      }
+
+
+      a[1].push(makeNode(fn)); // store transform
+
+    }
+  },[[],[],[]]);
+
+  if(inputs.length){
+    for (const input of inputs){
+      for( const transform of transforms ){
+        input.connect(transform);
+        for (const output of outputs){
+          transform.connect(output);
+        }
+      }
+    }
+  }else{
+    for( const transform of transforms ){
+      input.connect(transform);
+      for (const output of outputs){
+        transform.connect(output);
+      }
+    }
+  }
+}
+
+
+
+
+
+
+
+
+
+
+function makeNode(name, fn) {
+  const outputs = new Set()
+  function send(packet) {
+    for (const out of outputs) out(packet)
+  }
+  function input(packet) {
+    fn(send, packet)
+  }
+  input.connect = next => {
+    outputs.add(next)
+    return next
+  }
+  input.name = name
+  return input
+}
+
+makePipe(name){
+  if(!pipes[name]) pipes[name] = {type:'pipe', name, through: makeNode(through)};
+  return pipes[name];
+}
+
+```

package/README.md

@@ -0,0 +1,285 @@
+# lulz
+
+A reactive dataflow system inspired by FFmpeg filtergraph notation and Node-RED.
+
+## Installation
+
+```bash
+npm install lulz
+```
+
+## Quick Start
+
+```javascript
+const { flow, Inject, Debug } = require('./index');
+
+const app = flow([
+  [Inject({ payload: 'Hello World!' }), Debug({ name: 'output' })],
+]);
+
+app.start();
+```
+
+## Core Concepts
+
+### Flow Syntax
+
+Each line in a flow is an array: `[source, ...transforms, destination]`
+
+- **Source**: A string (pipe name) or producer function
+- **Transforms**: Functions that process packets
+- **Destination**: A string (pipe name) or consumer function
+
+```javascript
+const app = flow([
+  [producer, 'pipeName'],          // Producer → pipe
+  ['pipeName', transform, 'out'],  // Pipe → transform → pipe
+  ['out', consumer],               // Pipe → consumer
+]);
+```
+
+### Function Types
+
+**Outer functions** (factories) are regular functions that return inner functions:
+
+```javascript
+function myTransform(options) {           // Outer - receives config
+  return (send, packet) => {              // Inner - processes packets
+    send({ ...packet, modified: true });
+  };
+}
+```
+
+**Inner functions** are arrow functions that do the actual processing:
+
+```javascript
+const passthrough = (send, packet) => send(packet);
+```
+
+The system auto-detects which is which using `fn.hasOwnProperty('prototype')`:
+- Regular functions have `prototype` → outer
+- Arrow functions don't → inner
+
+### Pre-configured vs Auto-configured
+
+```javascript
+['input', myTransform, 'output']              // Auto-config: called with {}
+['input', myTransform({ option: 1 }), 'output'] // Pre-configured
+```
+
+## Processing Modes
+
+### Fan-out (Parallel)
+
+All transforms receive the same packet simultaneously:
+
+```javascript
+['input', transformA, transformB, transformC, 'output']
+//         ↓           ↓           ↓
+//      packet      packet      packet
+//         ↓           ↓           ↓
+//         └───────────┴───────────┘
+//                     ↓
+//                  output (receives 3 packets)
+```
+
+### Series (Sequential)
+
+Use `[a, b, c]` syntax for sequential processing:
+
+```javascript
+['input', [transformA, transformB, transformC], 'output']
+//                ↓
+//            packet
+//                ↓
+//           transformA
+//                ↓
+//           transformB
+//                ↓
+//           transformC
+//                ↓
+//             output (receives 1 packet)
+```
+
+### Mixed
+
+Combine both in a single line:
+
+```javascript
+['input', validate, [enrich, format], notify, 'output']
+//           ↓              ↓            ↓
+//        fan-out        series       fan-out
+```
+
+## Built-in Nodes
+
+### Inject
+
+Produces packets on schedule or trigger:
+
+```javascript
+Inject({
+  payload: 'hello',        // or () => Date.now() for dynamic
+  topic: 'greeting',
+  once: true,              // Emit once on start
+  onceDelay: 100,          // Delay before first emit (ms)
+  interval: 1000,          // Repeat interval (ms)
+})
+```
+
+### Debug
+
+Logs packets:
+
+```javascript
+Debug({
+  name: 'my-debug',
+  active: true,
+  complete: false,         // true = show full msg, false = payload only
+  logger: console.log,     // Custom logger function
+})
+```
+
+### Function
+
+Execute custom JavaScript:
+
+```javascript
+Function({
+  func: (msg, context) => {
+    return { ...msg, payload: msg.payload.toUpperCase() };
+  },
+})
+```
+
+Return `null` to drop the message.
+
+### Change
+
+Modify message properties:
+
+```javascript
+Change({
+  rules: [
+    { type: 'set', prop: 'payload', to: 'new value' },
+    { type: 'set', prop: 'topic', to: (msg) => msg.payload.type },
+    { type: 'change', prop: 'payload', from: /old/, to: 'new' },
+    { type: 'delete', prop: 'unwanted' },
+    { type: 'move', prop: 'payload', to: 'data' },
+  ]
+})
+```
+
+### Switch
+
+Route messages based on conditions:
+
+```javascript
+Switch({
+  property: 'payload',
+  rules: [
+    { type: 'eq', value: 'hello' },
+    { type: 'gt', value: 100 },
+    { type: 'regex', value: /^test/ },
+    { type: 'else' },
+  ],
+  checkall: false,  // Stop at first match
+})
+```
+
+Rule types: `eq`, `neq`, `lt`, `gt`, `lte`, `gte`, `regex`, `true`, `false`, `null`, `nnull`, `else`
+
+### Template
+
+Render mustache templates:
+
+```javascript
+Template({
+  template: 'Hello {{name}}, you have {{count}} messages!',
+  field: 'payload',  // Output field
+})
+```
+
+### Delay
+
+Delay or rate-limit messages:
+
+```javascript
+Delay({
+  delay: 1000,    // Delay in ms
+  rate: 10,       // Or rate limit (msgs/sec)
+  drop: false,    // Drop vs queue when rate limited
+})
+```
+
+### Split
+
+Split arrays/strings into sequences:
+
+```javascript
+Split({
+  property: 'payload',
+  delimiter: ',',  // For strings, or 'array' for arrays
+})
+```
+
+### Join
+
+Join sequences back together:
+
+```javascript
+Join({
+  count: 5,           // Emit after N messages
+  property: 'payload',
+  mode: 'manual',     // 'auto', 'manual', 'reduce'
+})
+```
+
+## Subflows
+
+Create reusable flow components:
+
+```javascript
+const sanitizer = subflow([
+  ['in', Function({ func: (msg) => ({
+    ...msg,
+    payload: String(msg.payload).trim().toLowerCase()
+  })}), 'out'],
+]);
+
+// Wire into main flow
+mainFlow.pipes['input'].connect(sanitizer._input);
+sanitizer._output.connect(mainFlow.pipes['process']);
+```
+
+## API
+
+### `flow(graph, context)`
+
+Create a new flow from a graph definition.
+
+Returns:
+- `start()` - Start all producers
+- `stop()` - Stop all producers
+- `inject(pipeName, packet)` - Inject a packet into a pipe
+- `getPipe(name)` - Get a pipe by name
+- `pipes` - Object of all pipes
+
+### `subflow(graph, context)`
+
+Create a subflow with `in` and `out` pipes.
+
+### `compose(...flows)`
+
+Connect multiple flows in sequence.
+
+## Running
+
+```bash
+npm test      # Run tests
+npm run examples  # Run examples
+```
+
+## License
+
+MIT