@centralping/ergo 0.1.0-beta.1

package/utils/iterables/chain.js

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Iterable pipeline composition utility.
+ *
+ * Pipes an initial value (source iterable) through a series of generator functions,
+ * where each generator wraps the previous one. The composition is left-to-right:
+ * the first generator receives the source, the second receives the first's output, etc.
+ *
+ * This is the core primitive for building lazy data pipelines with the iterable utilities.
+ *
+ * @module utils/iterables/chain
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {chain, map, filter, reduce} from 'ergo/utils/iterables';
+ *
+ * chain(
+ *   [1, 2, 3, 4, 5],
+ *   filter(x => x % 2 === 0),
+ *   map(x => x * 10),
+ *   reduce((acc, x) => acc + x, 0)
+ * ); // => 60
+ */
+
+/**
+ * @param {...(Iterable|function)} generators - Source iterable followed by generator transform functions
+ * @returns {*} - Final pipeline result (iterable or reduced value)
+ */
+export default (...generators) =>
+  generators.reduce((iterable, generator) => {
+    return generator(iterable);
+  });

package/utils/iterables/exec-all.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview RegExp exec-all generator for iterating all matches in a string.
+ *
+ * Creates a generator function that iterates all non-overlapping regex matches in a
+ * string, yielding the capture groups (not the full match) for each. Ensures the `g`
+ * flag is added to avoid infinite loops with stateful regexes.
+ *
+ * @module utils/iterables/exec-all
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import execAll from 'ergo/utils/iterables/exec-all';
+ *
+ * const findWords = execAll(/([a-z]+)/ig);
+ * [...findWords('hello world')] // => [['hello'], ['world']]
+ */
+
+/**
+ * @param {RegExp} re - Regular expression pattern (global flag added if missing)
+ * @returns {function} - Generator function `(str) => Generator<string[]>` yielding match arrays
+ */
+export default re => {
+  const localRe = new RegExp(re, [...new Set([...re.flags, 'g'])].join(''));
+
+  /**
+   * @param {string} str - Input string to match against the pattern
+   */
+  return function* (str) {
+    localRe.lastIndex = 0;
+    let match;
+
+    while ((match = localRe.exec(str)) !== null) {
+      yield match.slice(1);
+      if (match[0].length === 0) {
+        // Advance past zero-length match; use code-point width for Unicode regexes
+        const cp = str.codePointAt(localRe.lastIndex);
+        localRe.lastIndex += localRe.unicode && cp !== undefined && cp > 0xffff ? 2 : 1;
+      }
+    }
+  };
+};

package/utils/iterables/filter.js

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Iterable filter generator.
+ *
+ * Creates a generator function that yields only values from the source iterable
+ * for which the predicate returns truthy. Passes the value, index, and iterable
+ * to the predicate (same signature as `Array.prototype.filter`).
+ *
+ * @module utils/iterables/filter
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {chain, filter} from 'ergo/utils/iterables';
+ *
+ * [...chain([1, 2, 3, 4], filter(x => x % 2 === 0))] // => [2, 4]
+ */
+
+/**
+ * @param {function} predicate - Filter predicate `(value, index, iterable) => boolean`
+ * @returns {function} - Generator function `(iterable) => Generator` yielding matched values
+ */
+export default predicate => {
+  /**
+   * @param {Iterable} iterable - Source iterable to filter
+   */
+  return function* (iterable) {
+    let i = 0;
+
+    for (const val of iterable) {
+      if (predicate(val, i++, iterable)) {
+        yield val;
+      }
+    }
+  };
+};

package/utils/iterables/for-each.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Iterable forEach generator (side-effect tap).
+ *
+ * Creates a generator that calls a callback for each value as a side effect,
+ * then passes the value through unchanged. Equivalent to `Array.prototype.forEach`
+ * for iterables, but composable in a `chain()` pipeline.
+ *
+ * @module utils/iterables/for-each
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./map.js
+ *
+ * @example
+ * import {chain, forEach, reduce} from 'ergo/utils/iterables';
+ *
+ * chain(
+ *   [1, 2, 3],
+ *   forEach(x => console.log('processing', x)),
+ *   reduce((acc, x) => acc + x, 0)
+ * ); // logs each value, returns 6
+ */
+import map from './map.js';
+/**
+ * Side-effect callback for each iterable value.
+ *
+ * @param {function} cb - Called with `(value, index, iterable)` for each item
+ * @returns {function} - Generator function that yields each value unchanged
+ */
+export default cb =>
+  map((val, ...args) => {
+    cb(val, ...args);
+    return val;
+  });

package/utils/iterables/from-stream.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Converts a Node.js Readable stream to an async iterable.
+ *
+ * All Node.js Readable streams support `Symbol.asyncIterator` natively since
+ * Node.js 12. This module simply returns the stream as-is, providing a stable
+ * interface for code that receives streams and needs to iterate them.
+ *
+ * @module utils/iterables/from-stream
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import fromStream from 'ergo/utils/iterables/from-stream';
+ * import {Readable} from 'node:stream';
+ *
+ * const readable = Readable.from(['hello', ' ', 'world']);
+ * for await (const chunk of fromStream(readable)) {
+ *   process.stdout.write(chunk.toString());
+ * }
+ */
+
+/**
+ * Returns a Node.js Readable stream as an async iterable.
+ * All Readable streams support Symbol.asyncIterator since Node.js 12.
+ *
+ * @param {import('node:stream').Readable} stream - Readable stream to iterate
+ * @returns {AsyncIterable} - The stream itself, which natively supports async iteration
+ */
+export default stream => stream;

package/utils/iterables/index.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Async iterables utilities barrel export.
+ *
+ * Exports composable generator-based utilities for building lazy data pipelines.
+ * Designed for use with `chain()` to compose pipelines:
+ *   `chain(source, bufferSplit(sep), map(fn), reduce(fn, init))`
+ *
+ * @module utils/iterables
+ * @version 0.1.0
+ * @since 0.1.0
+ */
+export {default as bufferSplit} from './buffer-split.js';
+export {default as chain} from './chain.js';
+export {default as execAll} from './exec-all.js';
+export {default as filter} from './filter.js';
+export {default as forEach} from './for-each.js';
+export {default as fromStream} from './from-stream.js';
+export {default as map} from './map.js';
+export {default as range} from './range.js';
+export {default as reduce} from './reduce.js';
+export {default as take} from './take.js';

package/utils/iterables/map.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Iterable map generator.
+ *
+ * Creates a generator function that transforms each value from the source iterable
+ * using a transform function. Automatically detects async transforms and produces
+ * async generators; sync transforms produce sync generators.
+ *
+ * @module utils/iterables/map
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../type.js
+ *
+ * @example
+ * import {chain, map} from 'ergo/utils/iterables';
+ *
+ * [...chain([1, 2, 3], map(x => x * 2))] // => [2, 4, 6]
+ *
+ * // Async transform
+ * for await (const v of chain([1, 2, 3], map(async x => await fetchSomething(x)))) { ... }
+ */
+import type from '../type.js';
+/**
+ * Creates a map generator function.
+ *
+ * @param {function} transform - Sync or async transform `(value, index, iterable) => newValue`
+ * @returns {function} - Generator function `(iterable) => Generator|AsyncGenerator`
+ */
+export default transform => {
+  /**
+   * @param {Iterable} iterable - Source iterable to transform
+   */
+  return type(transform).startsWith('Async')
+    ? async function* (iterable) {
+        let i = 0;
+
+        for await (const val of iterable) {
+          yield await transform(val, i++, iterable);
+        }
+      }
+    : function* (iterable) {
+        let i = 0;
+
+        for (const val of iterable) {
+          yield transform(val, i++, iterable);
+        }
+      };
+};

package/utils/iterables/range.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Integer range generator.
+ *
+ * Produces a sequence of integers from `start` (inclusive) to `stop` (exclusive)
+ * stepping by `step`. Mirrors Python's `range()` behaviour.
+ *
+ * @module utils/iterables/range
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import range from 'ergo/utils/iterables/range';
+ *
+ * [...range(5)]        // => [0, 1, 2, 3, 4]
+ * [...range(1, 5)]     // => [1, 2, 3, 4]
+ * [...range(0, 10, 2)] // => [0, 2, 4, 6, 8]
+ */
+
+/**
+ * @param {number} start - Start value (or stop if only one arg)
+ * @param {number} [stop] - Exclusive upper bound
+ * @param {number} [step=1] - Step increment
+ * @returns {Generator<number>} - Sequence of integers
+ */
+/* eslint-disable-next-line no-param-reassign */
+export default function* (start, stop = start + (start = 0), step = 1) {
+  if (step === 0) return;
+
+  const length = (stop - start) / step;
+
+  for (let i = 0; i < length; i++) {
+    yield i * step + start;
+  }
+}

package/utils/iterables/reduce.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Iterable reduce utility.
+ *
+ * Creates a function that eagerly consumes an iterable and reduces it to a single value
+ * using a reducer function. When no `initialValue` is provided and the iterable has at
+ * least one element, the first element is used as the initial accumulator.
+ *
+ * @module utils/iterables/reduce
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {chain, reduce} from 'ergo/utils/iterables';
+ *
+ * chain([1, 2, 3, 4], reduce((sum, x) => sum + x, 0)) // => 10
+ */
+
+/**
+ * @param {function} reducer - Reducer `(accumulator, value, index, iterable) => newAccumulator`
+ * @param {*} [initialValue] - Initial accumulator value; first element used if omitted
+ * @returns {function} - Function `(iterable) => accumulated value`
+ */
+export default (reducer, initialValue) => {
+  /**
+   * @param {Iterable} iterable - Source iterable to reduce over
+   * @returns {*} - Accumulated value from the reducer function
+   */
+  return function (iterable) {
+    let i = 0;
+    let accumulator = initialValue;
+
+    for (const val of iterable) {
+      if (i === 0 && accumulator === undefined) {
+        accumulator = val;
+      } else {
+        accumulator = reducer(accumulator, val, i, iterable);
+      }
+      i++;
+    }
+
+    return accumulator;
+  };
+};

package/utils/iterables/take.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Iterable take generator.
+ *
+ * Creates a generator function that yields at most `n` values from the source iterable,
+ * then returns (stops iteration).
+ *
+ * @module utils/iterables/take
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {chain, take} from 'ergo/utils/iterables';
+ *
+ * [...chain([1, 2, 3, 4, 5], take(3))] // => [1, 2, 3]
+ */
+
+/**
+ * @param {number} [n=Infinity] - Maximum number of values to yield
+ * @returns {function} - Generator function `(iterable) => Generator` yielding at most n values
+ */
+export default (n = Infinity) => {
+  /**
+   * @param {Iterable} iterable - Source iterable to take elements from
+   */
+  return function* (iterable) {
+    let i = 0;
+
+    for (const val of iterable) {
+      if (i++ >= n) {
+        return;
+      }
+
+      yield val;
+    }
+  };
+};

package/utils/observables/buffer-split.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Observable Buffer split async generator.
+ *
+ * Push-model variant of `utils/iterables/buffer-split`. Accepts chunks via generator
+ * `.next(chunk)` calls and routes split buffers to a downstream generator. Designed for
+ * integration with observable-style pipelines built with `utils/observables/chain`.
+ *
+ * @module utils/observables/buffer-split
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../buffers/split.js
+ *
+ * @example
+ * // Used internally by the multipart body parser's streaming pipeline
+ */
+import split from '../buffers/split.js';
+
+/**
+ * @param {import('node:buffer').Buffer|string} [separator=Buffer.from('')] - Byte pattern to split on
+ * @param {number} [limit=Infinity] - Maximum number of parts to yield
+ * @returns {function} - Async generator function `(generator) => AsyncGenerator<[number, import('node:buffer').Buffer]>`
+ */
+export default (separator = Buffer.from(''), limit = Infinity) => {
+  const sepBuffer = Buffer.isBuffer(separator) ? separator : Buffer.from(separator);
+
+  /**
+   * @param {Generator} generator - Downstream async generator receiving split buffer segments via `.next()`
+   */
+  return async function* (generator) {
+    let partialCarryover = Buffer.from('');
+    let partialCarryoverIndexInc = false;
+    let index = 0;
+    let value;
+    let done;
+    let err;
+
+    try {
+      let buffers;
+      let lookup;
+      let partial;
+
+      while (index < limit) {
+        let chunk = yield value;
+
+        // Append the previous iteration's carryover from a partial match
+        // for the separator.
+        const pCoLen = partialCarryover.length;
+
+        if (pCoLen > 0) {
+          chunk = Buffer.concat([partialCarryover, chunk], pCoLen + chunk.length);
+        }
+
+        const incStart = partialCarryoverIndexInc && partial ? -1 : 0;
+
+        ({buffers, lookup, partial} = split(chunk, sepBuffer, {limit, lookup, partial}));
+
+        partialCarryoverIndexInc = buffers.length > 1;
+
+        if (partial > 0) {
+          if (partial === buffers.at(-1).length) {
+            partialCarryover = buffers.pop();
+          } else {
+            const last = buffers.at(-1);
+            partialCarryover = last.slice(-partial);
+            buffers[buffers.length - 1] = last.slice(0, -partial);
+          }
+        } else {
+          partialCarryover = Buffer.from('');
+        }
+
+        for (let i = 0; i < buffers.length; i++) {
+          if (i > incStart) {
+            index++;
+          }
+
+          if (index >= limit) {
+            return;
+          }
+
+          const buffer = buffers[i];
+          ({value, done} = await generator.next([index, buffer]));
+
+          if (done) {
+            return;
+          }
+        }
+      }
+    } catch (e) {
+      err = e;
+      throw e;
+    } finally {
+      if (!err) {
+        if (partialCarryoverIndexInc) {
+          index++;
+        }
+
+        // Push the carryover if a buffer ends with a partial match
+        if (partialCarryover.length && index < limit) {
+          ({value} = await generator.next([index, partialCarryover]));
+        }
+
+        ({value = value} = await generator.return());
+
+        /* eslint-disable-next-line no-unsafe-finally */
+        return value;
+      }
+    }
+  };
+};

package/utils/observables/chain.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Observable pipeline composition utility.
+ *
+ * Push-model variant of `utils/iterables/chain`. Chains observable generators in
+ * right-to-left order (each generator wraps the previous, pushing data downstream).
+ * The last generator in the array is the sink.
+ *
+ * @module utils/observables/chain
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../type.js
+ */
+import type from '../type.js';
+
+/**
+ * @param {...(function|Generator)} generators - Generator functions or instances; last is the sink
+ * @returns {Generator} - Chained generator pipeline composed right-to-left
+ */
+export default (...generators) => {
+  let lastIterator = generators.pop();
+
+  if (type(lastIterator).endsWith('GeneratorFunction')) {
+    lastIterator = lastIterator();
+    lastIterator.next();
+  }
+
+  return generators.reduceRight((prevIterator, generator) => {
+    const nextIterator = generator(prevIterator);
+    nextIterator.next();
+
+    return nextIterator;
+  }, lastIterator);
+};

package/utils/observables/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Observable (push-based) utilities barrel export.
+ *
+ * Provides generator-based push-model primitives for event-driven pipelines where
+ * data is pushed in (via `.next(value)`) rather than pulled. Used for streaming
+ * body parsing and other real-time data flows.
+ *
+ * @module utils/observables
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./buffer-split.js
+ * @requires ./chain.js
+ * @requires ./map.js
+ * @requires ./take.js
+ */
+export {default as bufferSplit} from './buffer-split.js';
+export {default as chain} from './chain.js';
+export {default as map} from './map.js';
+export {default as take} from './take.js';

package/utils/observables/map.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Observable map generator.
+ *
+ * Push-model transform generator. Each value pushed in via `.next(value)` is
+ * transformed and forwarded downstream via the iterator's `.next()`.
+ *
+ * @module utils/observables/map
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * // Used in observable chain pipelines built with utils/observables/chain
+ */
+
+/**
+ * @param {function} transform - Transform `(value, index) => newValue`
+ * @returns {function} - Generator function `(iterator) => Generator` that maps values
+ */
+export default transform => {
+  /**
+   * @param {Iterator} iterator - Source iterator to transform
+   */
+  return function* (iterator) {
+    let i = 0;
+
+    try {
+      while (true) {
+        iterator.next(transform(yield, i++));
+      }
+    } finally {
+      iterator.return();
+    }
+  };
+};

package/utils/observables/take.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Observable take generator.
+ *
+ * Push-model variant of `utils/iterables/take`. Passes at most `n` values to the
+ * downstream iterator, then calls `.return()` to signal completion.
+ *
+ * @module utils/observables/take
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * // Used in observable chain pipelines built with utils/observables/chain
+ */
+
+/**
+ * @param {number} [n=Infinity] - Maximum number of values to pass through
+ * @returns {function} - Generator function `(iterator) => Generator` that yields at most n values
+ */
+export default (n = Infinity) => {
+  /**
+   * @param {Iterator} iterator - Downstream generator receiving forwarded values via `.next()`
+   */
+  return function* (iterator) {
+    let i = 0;
+
+    try {
+      while (true) {
+        const val = yield;
+
+        if (i++ >= n) {
+          return;
+        }
+
+        iterator.next(val);
+      }
+    } finally {
+      iterator.return();
+    }
+  };
+};

package/utils/pick.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Object property picker with dot-notation and rename support.
+ *
+ * Extracts specified paths from an object into a new object. Supports:
+ * - String paths: `pick(obj, 'a.b')` extracts `obj.a.b` as `result.a.b`
+ * - Rename tuples: `pick(obj, ['a.b', 'c'])` extracts `obj.a.b` as `result.c`
+ *
+ * @module utils/pick
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./get.js
+ * @requires ./set.js
+ *
+ * @example
+ * import pick from 'ergo/utils/pick';
+ *
+ * pick({a: {b: 1}, c: 2}, 'a.b', 'c')
+ * // => {a: {b: 1}, c: 2}
+ *
+ * pick({user: {name: 'Alice'}}, ['user.name', 'name'])
+ * // => {name: 'Alice'}
+ */
+import get from './get.js';
+import set from './set.js';
+
+/**
+ * Picks values from an object at the specified dot-notation paths.
+ *
+ * @param {object} [obj={}] - Source object
+ * @param {...(string|[string, string])} paths - Paths to extract; each may be a string
+ *   or a `[readPath, setPath]` rename tuple
+ * @returns {object} - New object with the extracted (and optionally renamed) values
+ */
+export default (obj = {}, ...paths) =>
+  paths.flat().reduce((o, path) => {
+    const [readPath, setPath = path] = Array.isArray(path) ? path : [path];
+
+    set(o, setPath, get(obj, readPath));
+
+    return o;
+  }, Object.create(null));

package/utils/set.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Deep property setter with dot-notation path support.
+ *
+ * Sets a value at a dot-delimited path in an object, creating intermediate objects
+ * or arrays as needed. Uses `Object.hasOwn()` to check for existing nodes.
+ * Array nodes are created when the next path segment is a valid integer string.
+ *
+ * @module utils/set
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import set from 'ergo/utils/set';
+ *
+ * const obj = {};
+ * set(obj, 'a.b.c', 42);   // obj => {a: {b: {c: 42}}}
+ * set(obj, 'tags.0', 'x'); // obj.tags => ['x']
+ */
+
+/**
+ * @param {object} obj - Target object
+ * @param {string} [path=''] - Dot-delimited property path
+ * @param {*} val - Value to assign
+ * @returns {*} - The assigned value
+ */
+export default (obj, path = '', val) => {
+  const subPaths = path.split('.');
+
+  return (subPaths
+    .slice(0, -1)
+    .reduce(
+      (o, p, i) =>
+        Object.hasOwn(o, p)
+          ? o[p]
+          : (o[p] = Number.isNaN(Number(subPaths[i + 1])) ? Object.create(null) : []),
+      obj
+    )[subPaths.at(-1)] = val);
+};