lulz 1.0.2 → 2.0.0

package/src/utils.js

@@ -0,0 +1,270 @@
+/**
+ * lulz - Utilities
+ * 
+ * Helper functions and utilities.
+ */
+
+
+// ─────────────────────────────────────────────────────────────
+// Packet Helpers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a properly formatted packet
+ */
+export const packet = (payload, meta = {}) => ({
+  payload,
+  topic: meta.topic ?? '',
+  _id: meta._id ?? crypto.randomUUID?.() ?? Math.random().toString(36).slice(2),
+  _ts: Date.now(),
+  ...meta,
+});
+
+/**
+ * Clone a packet (deep copy)
+ */
+export const clonePacket = (pkt) => 
+  JSON.parse(JSON.stringify(pkt));
+
+/**
+ * Merge packets
+ */
+export const mergePackets = (...packets) => 
+  packets.reduce((acc, p) => ({
+    ...acc,
+    ...p,
+    payload: p.payload ?? acc.payload,
+  }), {});
+
+
+// ─────────────────────────────────────────────────────────────
+// Function Composition Helpers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Pipe functions left to right
+ */
+export const pipe = (...fns) => (x) => 
+  fns.reduce((v, f) => f(v), x);
+
+/**
+ * Compose functions right to left
+ */
+export const compose = (...fns) => (x) => 
+  fns.reduceRight((v, f) => f(v), x);
+
+/**
+ * Identity function
+ */
+export const identity = (x) => x;
+
+/**
+ * Constant function
+ */
+export const constant = (x) => () => x;
+
+/**
+ * Noop function
+ */
+export const noop = () => {};
+
+
+// ─────────────────────────────────────────────────────────────
+// Async Helpers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Sleep for ms
+ */
+export const sleep = (ms) => 
+  new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Timeout a promise
+ */
+export const withTimeout = (promise, ms, message = 'Timeout') =>
+  Promise.race([
+    promise,
+    new Promise((_, reject) => 
+      setTimeout(() => reject(new Error(message)), ms)
+    ),
+  ]);
+
+/**
+ * Retry a function
+ */
+export const withRetry = async (fn, { retries = 3, delay = 1000, backoff = 2 } = {}) => {
+  let lastError;
+  
+  for (let i = 0; i <= retries; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (i < retries) {
+        await sleep(delay * Math.pow(backoff, i));
+      }
+    }
+  }
+  
+  throw lastError;
+};
+
+
+// ─────────────────────────────────────────────────────────────
+// Collection Helpers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Chunk array into groups
+ */
+export const chunk = (arr, size) => {
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+};
+
+/**
+ * Flatten nested arrays
+ */
+export const flatten = (arr, depth = 1) => 
+  arr.flat(depth);
+
+/**
+ * Unique values
+ */
+export const unique = (arr, keyFn = (x) => x) => {
+  const seen = new Set();
+  return arr.filter(item => {
+    const key = keyFn(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
+
+/**
+ * Group by key
+ */
+export const groupBy = (arr, keyFn) => {
+  return arr.reduce((acc, item) => {
+    const key = keyFn(item);
+    if (!acc[key]) acc[key] = [];
+    acc[key].push(item);
+    return acc;
+  }, {});
+};
+
+/**
+ * Partition by predicate
+ */
+export const partition = (arr, predicate) => {
+  const truthy = [];
+  const falsy = [];
+  
+  for (const item of arr) {
+    (predicate(item) ? truthy : falsy).push(item);
+  }
+  
+  return [truthy, falsy];
+};
+
+
+// ─────────────────────────────────────────────────────────────
+// Object Helpers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Deep clone
+ */
+export const deepClone = (obj) => 
+  JSON.parse(JSON.stringify(obj));
+
+/**
+ * Deep merge
+ */
+export const deepMerge = (target, ...sources) => {
+  if (!sources.length) return target;
+  const source = sources.shift();
+
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isObject(source[key])) {
+        if (!target[key]) Object.assign(target, { [key]: {} });
+        deepMerge(target[key], source[key]);
+      } else {
+        Object.assign(target, { [key]: source[key] });
+      }
+    }
+  }
+
+  return deepMerge(target, ...sources);
+};
+
+const isObject = (item) => 
+  item && typeof item === 'object' && !Array.isArray(item);
+
+/**
+ * Pick keys from object
+ */
+export const pick = (obj, keys) => 
+  keys.reduce((acc, key) => {
+    if (key in obj) acc[key] = obj[key];
+    return acc;
+  }, {});
+
+/**
+ * Omit keys from object
+ */
+export const omit = (obj, keys) => {
+  const result = { ...obj };
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result;
+};
+
+
+// ─────────────────────────────────────────────────────────────
+// Debug Helpers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a debug logger
+ */
+export const createLogger = (namespace, enabled = true) => {
+  const log = (...args) => {
+    if (enabled) {
+      console.log(`[${namespace}]`, ...args);
+    }
+  };
+  
+  log.error = (...args) => console.error(`[${namespace}:error]`, ...args);
+  log.warn = (...args) => console.warn(`[${namespace}:warn]`, ...args);
+  log.info = (...args) => enabled && console.info(`[${namespace}:info]`, ...args);
+  log.debug = (...args) => enabled && console.debug(`[${namespace}:debug]`, ...args);
+  
+  return log;
+};
+
+/**
+ * Measure execution time
+ */
+export const measure = async (label, fn) => {
+  const start = performance.now();
+  const result = await fn();
+  const end = performance.now();
+  console.log(`[${label}] ${(end - start).toFixed(2)}ms`);
+  return result;
+};
+
+/**
+ * Assert condition
+ */
+export const assert = (condition, message = 'Assertion failed') => {
+  if (!condition) {
+    throw new Error(message);
+  }
+};

package/src/workers.js

@@ -0,0 +1,367 @@
+/**
+ * lulz - Worker Task Queue
+ * 
+ * EventEmitter-wrapped task queue using:
+ *   - Worker Threads (Node.js)
+ *   - Web Workers (browsers)
+ * 
+ * Default worker count: os.cpus().length
+ */
+
+import { EventEmitter } from 'events';
+import { cpus } from 'os';
+import { Worker, isMainThread, parentPort, workerData } from 'worker_threads';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+
+// ─────────────────────────────────────────────────────────────
+// Task Queue
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a task queue with worker pool
+ * 
+ * @param {Object} options
+ * @param {number} options.workers - Number of workers (default: CPU count)
+ * @param {string} options.workerScript - Path to worker script
+ * @param {Function} options.handler - Task handler for inline workers
+ * 
+ * @returns {EventEmitter} Queue with submit/on API
+ * 
+ * Events:
+ *   - 'result' - Task completed { id, result }
+ *   - 'error' - Task failed { id, error }
+ *   - 'drain' - All tasks completed
+ *   - 'idle' - Workers are idle
+ * 
+ * Usage:
+ *   const queue = taskQueue({ workers: 4, handler: (data) => data * 2 });
+ *   queue.on('result', ({ id, result }) => console.log(result));
+ *   queue.submit({ id: 1, data: 42 });
+ */
+export function taskQueue(options = {}) {
+  const {
+    workers: workerCount = cpus().length,
+    workerScript = null,
+    handler = null,
+  } = options;
+
+  const queue = new EventEmitter();
+  const pending = [];           // Tasks waiting for a worker
+  const running = new Map();    // taskId → worker
+  const pool = [];              // Available workers
+  let taskIdCounter = 0;
+  let totalSubmitted = 0;
+  let totalCompleted = 0;
+
+  // ─── Worker Management ───
+
+  const createWorker = () => {
+    let worker;
+
+    if (workerScript) {
+      // External script
+      worker = new Worker(workerScript);
+    } else if (handler) {
+      // Inline handler - create worker with eval
+      const handlerStr = handler.toString();
+      const code = `
+        const { parentPort } = require('worker_threads');
+        const handler = ${handlerStr};
+        parentPort.on('message', async (task) => {
+          try {
+            const result = await handler(task.data);
+            parentPort.postMessage({ id: task.id, result });
+          } catch (error) {
+            parentPort.postMessage({ id: task.id, error: error.message });
+          }
+        });
+      `;
+      worker = new Worker(code, { eval: true });
+    } else {
+      throw new Error('taskQueue requires either workerScript or handler');
+    }
+
+    worker._busy = false;
+
+    worker.on('message', (msg) => {
+      worker._busy = false;
+      running.delete(msg.id);
+      totalCompleted++;
+
+      if (msg.error) {
+        queue.emit('error', { id: msg.id, error: msg.error });
+      } else {
+        queue.emit('result', { id: msg.id, result: msg.result });
+      }
+
+      // Process next task
+      if (pending.length > 0) {
+        processNext(worker);
+      } else {
+        pool.push(worker);
+        
+        if (totalCompleted === totalSubmitted) {
+          queue.emit('drain');
+        }
+        
+        if (pool.length === workerCount) {
+          queue.emit('idle');
+        }
+      }
+    });
+
+    worker.on('error', (err) => {
+      console.error('[taskQueue] Worker error:', err);
+      // Replace crashed worker
+      const idx = pool.indexOf(worker);
+      if (idx > -1) pool.splice(idx, 1);
+      pool.push(createWorker());
+    });
+
+    return worker;
+  };
+
+  // Initialize worker pool
+  for (let i = 0; i < workerCount; i++) {
+    pool.push(createWorker());
+  }
+
+  // ─── Task Processing ───
+
+  const processNext = (worker) => {
+    if (pending.length === 0) return;
+
+    const task = pending.shift();
+    worker._busy = true;
+    running.set(task.id, worker);
+    worker.postMessage(task);
+  };
+
+  const tryProcess = () => {
+    while (pending.length > 0 && pool.length > 0) {
+      const worker = pool.pop();
+      processNext(worker);
+    }
+  };
+
+  // ─── API ───
+
+  /**
+   * Submit a task to the queue
+   * @param {Object} task - Task object with data property
+   * @returns {number} Task ID
+   */
+  queue.submit = (task) => {
+    const id = task.id ?? ++taskIdCounter;
+    const taskObj = { id, data: task.data ?? task };
+    
+    totalSubmitted++;
+    pending.push(taskObj);
+    tryProcess();
+    
+    return id;
+  };
+
+  /**
+   * Submit multiple tasks
+   * @param {Array} tasks - Array of tasks
+   * @returns {number[]} Task IDs
+   */
+  queue.submitAll = (tasks) => {
+    return tasks.map(t => queue.submit(t));
+  };
+
+  /**
+   * Get queue statistics
+   */
+  queue.stats = () => ({
+    pending: pending.length,
+    running: running.size,
+    available: pool.length,
+    totalSubmitted,
+    totalCompleted,
+  });
+
+  /**
+   * Terminate all workers
+   */
+  queue.terminate = async () => {
+    const terminatePromises = [];
+    
+    for (const worker of pool) {
+      terminatePromises.push(worker.terminate());
+    }
+    
+    for (const worker of running.values()) {
+      terminatePromises.push(worker.terminate());
+    }
+    
+    await Promise.all(terminatePromises);
+    pool.length = 0;
+    running.clear();
+    pending.length = 0;
+    
+    queue.emit('terminated');
+  };
+
+  /**
+   * Wait for all tasks to complete
+   */
+  queue.drain = () => {
+    return new Promise((resolve) => {
+      if (totalCompleted === totalSubmitted && pending.length === 0) {
+        resolve();
+      } else {
+        queue.once('drain', resolve);
+      }
+    });
+  };
+
+  return queue;
+}
+
+
+// ─────────────────────────────────────────────────────────────
+// Worker Node for Flow Integration
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Worker node - Process packets in worker threads
+ * 
+ * @param {Object} options
+ * @param {number} options.workers - Worker count
+ * @param {Function} options.handler - Processing function
+ * 
+ * Usage in flow:
+ *   ['input', worker({ workers: 4, handler: (data) => heavyComputation(data) }), 'output']
+ */
+export function worker(options = {}) {
+  const {
+    workers: workerCount = cpus().length,
+    handler = (data) => data,
+  } = options;
+
+  // Create dedicated queue for this node
+  let queue = null;
+  const pendingCallbacks = new Map();
+
+  return (send, packet) => {
+    // Lazy initialization
+    if (!queue) {
+      queue = taskQueue({ workers: workerCount, handler });
+      
+      queue.on('result', ({ id, result }) => {
+        const original = pendingCallbacks.get(id);
+        pendingCallbacks.delete(id);
+        
+        if (original) {
+          send({ ...original, payload: result });
+        }
+      });
+      
+      queue.on('error', ({ id, error }) => {
+        const original = pendingCallbacks.get(id);
+        pendingCallbacks.delete(id);
+        
+        if (original) {
+          send({ ...original, error });
+        }
+      });
+    }
+
+    const taskId = queue.submit({ data: packet.payload ?? packet });
+    pendingCallbacks.set(taskId, packet);
+  };
+}
+
+
+// ─────────────────────────────────────────────────────────────
+// Parallel Map - Map with worker pool
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * parallelMap - Process items in parallel using workers
+ * 
+ * @param {Object} options
+ * @param {Function} options.fn - Mapping function
+ * @param {number} options.workers - Worker count
+ * @param {number} options.batchSize - Items per batch
+ */
+export function parallelMap(options = {}) {
+  const {
+    fn = (x) => x,
+    workers: workerCount = cpus().length,
+    batchSize = 1,
+  } = options;
+
+  let queue = null;
+  const results = new Map();
+  let expectedCount = 0;
+
+  return (send, packet) => {
+    if (!queue) {
+      queue = taskQueue({ workers: workerCount, handler: fn });
+    }
+
+    const items = Array.isArray(packet.payload) ? packet.payload : [packet.payload];
+    expectedCount = items.length;
+    results.clear();
+
+    const handleResult = ({ id, result }) => {
+      results.set(id, result);
+      
+      if (results.size === expectedCount) {
+        // Preserve order
+        const ordered = items.map((_, i) => results.get(i + 1));
+        send({ ...packet, payload: ordered });
+      }
+    };
+
+    queue.on('result', handleResult);
+
+    items.forEach((item, i) => {
+      queue.submit({ id: i + 1, data: item });
+    });
+  };
+}
+
+
+// ─────────────────────────────────────────────────────────────
+// CPU-bound Task Helper
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * cpuTask - Wrap a CPU-bound function for worker execution
+ * 
+ * @param {Function} fn - CPU-bound function
+ * @returns {Function} Worker-enabled function
+ */
+export function cpuTask(fn) {
+  return worker({ handler: fn });
+}
+
+
+// ─────────────────────────────────────────────────────────────
+// Export for Worker Script Usage
+// ─────────────────────────────────────────────────────────────
+
+// If this module is loaded in a worker thread
+if (!isMainThread && parentPort) {
+  // This allows the module to be used as a worker script
+  // Usage: new Worker('./workers.js', { workerData: { handler: ... } })
+  
+  if (workerData?.handler) {
+    const handler = new Function('return ' + workerData.handler)();
+    
+    parentPort.on('message', async (task) => {
+      try {
+        const result = await handler(task.data);
+        parentPort.postMessage({ id: task.id, result });
+      } catch (error) {
+        parentPort.postMessage({ id: task.id, error: error.message });
+      }
+    });
+  }
+}