@centralping/ergo 0.1.0-beta.1

package/types/utils/compose.d.ts

@@ -0,0 +1,83 @@
+export default compose;
+/**
+ * @fileoverview Async pipeline composition utility.
+ *
+ * Creates an async pipeline from a list of middleware functions. Each function receives
+ * the original arguments plus the accumulated state object from prior middleware.
+ *
+ * - `compose(...fns)` — runs functions sequentially (`serial`)
+ * - `compose.all(...fns)` — runs functions concurrently and merges all results
+ * - `compose.withOptions(options, ...fns)` — sequential with options (e.g. `breakWhen`)
+ * - `compose.all.withOptions(options, ...fns)` — concurrent with options
+ *
+ * State is accumulated into a null-prototype accumulator object with an
+ * `isAccumulator: true` flag and a `size` getter. If the last argument passed to the
+ * composed pipeline is already an accumulator object, it is reused for accumulation.
+ *
+ * Serial composition uses a sync fast-path: when a middleware returns a non-thenable
+ * value, the result is merged immediately without scheduling a microtask. This
+ * eliminates unnecessary `await` overhead for synchronous middleware (the majority
+ * of ergo's built-in middleware).
+ *
+ * @module utils/compose
+ * @version 0.2.0
+ * @since 0.1.0
+ *
+ * @example
+ * import compose from 'ergo/utils/compose';
+ *
+ * const pipeline = compose(
+ *   async (req, res) => ({user: await getUser(req)}),
+ *   async (req, res, {user}) => ({role: await getRole(user)})
+ * );
+ *
+ * const result = await pipeline(req, res);
+ * // result.user, result.role
+ *
+ * @example
+ * // Early termination with breakWhen
+ * const pipeline = compose.withOptions(
+ *   {breakWhen: (acc) => acc.done},
+ *   () => ({done: true, a: 1}),
+ *   () => ({b: 2}) // never reached
+ * );
+ */
+/**
+ * Composes middleware functions into an async pipeline with result accumulation.
+ *
+ * @param {...function} fns - Middleware functions to compose
+ * @returns {function} - Async composed pipeline
+ */
+declare function compose(...fns: Function[]): Function;
+declare namespace compose {
+    function all(...fns: any[]): Function;
+    namespace all {
+        /**
+         * Creates a concurrent pipeline with configuration options.
+         *
+         * @param {object} options - Pipeline options
+         * @param {...function} fns - Middleware functions to compose
+         * @returns {function} - Async composed pipeline
+         */
+        function withOptions(options: object, ...fns: Function[]): Function;
+    }
+    /**
+     * Creates a sequential pipeline with configuration options.
+     *
+     * @param {object} options - Pipeline options
+     * @param {function} [options.breakWhen] - Predicate `(acc) => boolean`; when truthy,
+     *   serial iteration stops after the current step's result is merged
+     * @param {...function} fns - Middleware functions to compose
+     * @returns {function} - Async composed pipeline
+     */
+    function withOptions(options: {
+        breakWhen?: Function | undefined;
+    }, ...fns: Function[]): Function;
+}
+/**
+ * Creates a null-prototype accumulator object.
+ *
+ * @param {object} [defaults={}] - Initial properties to copy into the accumulator
+ * @returns {object} - Null-prototype accumulator with `isAccumulator: true` and `size` getter
+ */
+export function accumulator(defaults?: object): object;

package/types/utils/flat-array.d.ts

@@ -0,0 +1,2 @@
+declare function _default(...items: any[]): any[];
+export default _default;

package/types/utils/get.d.ts

@@ -0,0 +1,5 @@
+declare function _default(obj?: object, path?: string, { safe, invoke }?: {
+    safe?: boolean | undefined;
+    invoke?: boolean | undefined;
+}): any;
+export default _default;

package/types/utils/http-errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @param {number} [statusCode=500] - HTTP status code
+ * @param {object} [options] - RFC 9457 Problem Details fields
+ * @param {string} [options.type] - RFC 9457 `type` URI (defaults to MDN docs link)
+ * @param {string} [options.detail] - RFC 9457 `detail` (human-readable explanation)
+ * @param {string} [options.message] - Alias for `detail` (backward compat)
+ * @param {Array<[string, string]>} [options.headers] - Response headers to attach
+ * @param {string} [options.instance] - RFC 9457 `instance` URI identifying the specific occurrence
+ * @param {number|string} [options.retryAfter] - Retry-After value (seconds or HTTP-date).
+ *   Auto-appended to `headers` as `['Retry-After', String(value)]` and included in toJSON().
+ * @param {Error} [options.originalError] - Underlying error
+ * @returns {Error} - Error with RFC 9457 properties and `toJSON()` method
+ */
+export default function httpErrors(statusCode?: number, { type, message, detail: rawDetail, headers, instance, retryAfter, originalError, ...extra }?: {
+    type?: string | undefined;
+    detail?: string | undefined;
+    message?: string | undefined;
+    headers?: [string, string][] | undefined;
+    instance?: string | undefined;
+    retryAfter?: string | number | undefined;
+    originalError?: Error | undefined;
+}): Error;

package/types/utils/iterables/buffer-split.d.ts

@@ -0,0 +1,2 @@
+declare function _default(separator?: any | string, limit?: number): Function;
+export default _default;

package/types/utils/iterables/chain.d.ts

@@ -0,0 +1,2 @@
+declare function _default(...generators: (Iterable<any> | Function)[]): any;
+export default _default;

package/types/utils/iterables/exec-all.d.ts

@@ -0,0 +1,2 @@
+declare function _default(re: RegExp): Function;
+export default _default;

package/types/utils/iterables/filter.d.ts

@@ -0,0 +1,2 @@
+declare function _default(predicate: Function): Function;
+export default _default;

package/types/utils/iterables/for-each.d.ts

@@ -0,0 +1,2 @@
+declare function _default(cb: Function): Function;
+export default _default;

package/types/utils/iterables/from-stream.d.ts

@@ -0,0 +1,2 @@
+declare function _default(stream: any): AsyncIterable<any>;
+export default _default;

package/types/utils/iterables/index.d.ts

@@ -0,0 +1,10 @@
+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/types/utils/iterables/map.d.ts

@@ -0,0 +1,2 @@
+declare function _default(transform: Function): Function;
+export default _default;

package/types/utils/iterables/range.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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
+ */
+export default function _default(start: number, stop?: number, step?: number): Generator<number>;

package/types/utils/iterables/reduce.d.ts

@@ -0,0 +1,2 @@
+declare function _default(reducer: Function, initialValue?: any): Function;
+export default _default;

package/types/utils/iterables/take.d.ts

@@ -0,0 +1,2 @@
+declare function _default(n?: number): Function;
+export default _default;

package/types/utils/observables/buffer-split.d.ts

@@ -0,0 +1,2 @@
+declare function _default(separator?: any | string, limit?: number): Function;
+export default _default;

package/types/utils/observables/chain.d.ts

@@ -0,0 +1,2 @@
+declare function _default(...generators: (Function | Generator)[]): Generator;
+export default _default;

package/types/utils/observables/index.d.ts

@@ -0,0 +1,4 @@
+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/types/utils/observables/map.d.ts

@@ -0,0 +1,2 @@
+declare function _default(transform: Function): Function;
+export default _default;

package/types/utils/observables/take.d.ts

@@ -0,0 +1,2 @@
+declare function _default(n?: number): Function;
+export default _default;

package/types/utils/pick.d.ts

@@ -0,0 +1,2 @@
+declare function _default(obj?: object, ...paths: (string | [string, string])[]): object;
+export default _default;

package/types/utils/set.d.ts

@@ -0,0 +1,2 @@
+declare function _default(obj: object, path?: string, val: any): any;
+export default _default;

package/types/utils/streams/index.d.ts

@@ -0,0 +1,2 @@
+export { default as meter } from "./meter.js";
+export { default as tee } from "./tee.js";

package/types/utils/streams/meter.d.ts

@@ -0,0 +1,5 @@
+declare function _default({ expected, limit }?: {
+    expected?: number | undefined;
+    limit?: number | undefined;
+}): any;
+export default _default;

package/types/utils/streams/tee.d.ts

@@ -0,0 +1,2 @@
+declare function _default(generator: Generator): any;
+export default _default;

package/types/utils/type.d.ts

@@ -0,0 +1,2 @@
+declare function _default(o: any): string;
+export default _default;

package/utils/attempt.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Try/catch wrapper for async functions.
+ *
+ * Wraps an async `fn` so that if it throws, the `fail` function is called with
+ * the original arguments plus the caught error appended. Both functions are awaited.
+ *
+ * Used by `http/handler.js` to wrap the try pipeline with an error handler pipeline.
+ *
+ * @module utils/attempt
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import attempt from 'ergo/utils/attempt';
+ *
+ * const safe = attempt(
+ *   async (req, res) => { throw new Error('oops'); },
+ *   async (req, res, err) => { res.writeHead(500); res.end(err.message); }
+ * );
+ *
+ * await safe(req, res); // calls the fail function with (req, res, err)
+ */
+
+/**
+ * @param {function} fn - Primary async function to execute
+ * @param {function} fail - Error handler called with (...originalArgs, error)
+ * @returns {function} - Wrapped async function with try/catch behavior
+ */
+export default (fn, fail) => {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } catch (e) {
+      return await fail(...args, e);
+    }
+  };
+};

package/utils/buffers/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Buffer utilities barrel export.
+ *
+ * Provides `match` (KMP substring search in Buffers) and `split` (Buffer split by separator).
+ *
+ * @module utils/buffers
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./match.js
+ * @requires ./split.js
+ */
+export {default as match} from './match.js';
+export {default as split} from './split.js';

package/utils/buffers/match.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview KMP (Knuth-Morris-Pratt) substring search for Node.js Buffers.
+ *
+ * Finds all occurrences of a byte pattern in a Buffer using the KMP algorithm.
+ * Supports incremental/streaming search by accepting and returning a `partial` counter
+ * and pre-computed `lookup` table, enabling multi-chunk searches without re-scanning.
+ *
+ * Returns match start indices, the KMP failure function (`lookup`), and the unfinished
+ * match state (`partial`) for the next chunk.
+ *
+ * @module utils/buffers/match
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import bufferMatch from 'ergo/utils/buffers/match';
+ *
+ * const {matches} = bufferMatch(Buffer.from('hello world'), Buffer.from('l'));
+ * // matches => [2, 3, 9]
+ */
+/**
+ * Searches for all occurrences of `searchBuffer` in `buffer` using KMP.
+ *
+ * @param {import('node:buffer').Buffer} [buffer=Buffer.from('')] - The buffer to search within
+ * @param {import('node:buffer').Buffer} [searchBuffer] - The byte pattern to search for
+ * @param {object} [options] - KMP search options
+ * @param {number} [options.limit=Infinity] - Maximum matches to return
+ * @param {number} [options.partial=0] - KMP partial match state from a prior chunk
+ * @param {number[]} [options.lookup] - Pre-computed KMP failure function table
+ * @returns {{matches: number[], partial: number, lookup: number[]}} - Match result with indices, partial state, and lookup table
+ */
+export default (
+  buffer = Buffer.from(''),
+  searchBuffer,
+  {limit = Infinity, partial = 0, lookup} = {}
+) => {
+  /* eslint-disable no-param-reassign */
+  const matches = [];
+
+  if (lookup === undefined) {
+    lookup = makeLookup(searchBuffer);
+  }
+
+  if (lookup.length === 0) {
+    return {matches, partial, lookup};
+  }
+
+  for (let i = partial; i < buffer.length; i++) {
+    while (partial >= 0 && buffer[i] !== searchBuffer[partial]) {
+      if (partial > 0) {
+        partial = lookup[partial - 1];
+      } else {
+        partial = -1;
+      }
+    }
+
+    partial += 1;
+    if (partial === searchBuffer.length) {
+      matches.push(i - partial + 1);
+      partial = 0;
+
+      if (matches.length >= limit) {
+        break;
+      }
+    }
+  }
+
+  return {matches, partial, lookup};
+  /* eslint-enable no-param-reassign */
+};
+
+/**
+ * Builds the KMP failure function (partial match table) for a byte pattern.
+ *
+ * @param {import('node:buffer').Buffer|string} [searchBuffer=''] - The pattern to pre-process
+ * @returns {number[]} - The KMP failure function table
+ */
+function makeLookup(searchBuffer = '') {
+  const lookup = [];
+  let pos = -1;
+
+  for (let i = 0; i < searchBuffer.length; i++) {
+    while (pos >= 0 && searchBuffer[i] !== searchBuffer[pos]) {
+      pos -= 1;
+
+      if (pos >= 0) {
+        pos = lookup[pos];
+      }
+    }
+
+    pos += 1;
+    lookup.push(pos);
+  }
+
+  return lookup;
+}

package/utils/buffers/split.js

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Buffer split utility using KMP-based pattern matching.
+ *
+ * Splits a Buffer by a separator pattern, analogous to `String.prototype.split()`.
+ * Supports incremental/streaming operation by threading `partial` and `lookup`
+ * state across chunks.
+ *
+ * Returns `{buffers, partial, lookup}` where `buffers` is the array of Buffer slices.
+ *
+ * @module utils/buffers/split
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./match.js
+ * @requires ../get.js
+ *
+ * @example
+ * import bufferSplit from 'ergo/utils/buffers/split';
+ *
+ * const {buffers} = bufferSplit(Buffer.from('a--b--c'), Buffer.from('--'));
+ * // buffers => [Buffer<'a'>, Buffer<'b'>, Buffer<'c'>]
+ */
+import bufferMatch from './match.js';
+import get from '../get.js';
+
+/**
+ * Splits a Buffer by a separator pattern.
+ *
+ * @param {import('node:buffer').Buffer|string} buffer - Source buffer to split
+ * @param {import('node:buffer').Buffer} [separator] - Byte pattern to split on
+ * @param {object} [options] - KMP split options
+ * @param {number} [options.limit=Infinity] - Maximum splits to produce
+ * @param {number} [options.partial=0] - Partial KMP match state from prior chunk
+ * @param {number[]} [options.lookup] - Pre-computed KMP failure function table
+ * @returns {{buffers: import('node:buffer').Buffer[], partial: number, lookup: number[]}} - Split result with buffer slices, partial state, and lookup table
+ */
+export default (buffer = Buffer.from(''), separator, {limit = Infinity, ...options} = {}) => {
+  const sepLen = get(separator, 'length', {safe: true}) ?? 0;
+  const {matches, ...rest} = bufferMatch(buffer, separator, {limit, ...options});
+
+  matches.push(buffer.length);
+
+  const splitsLength = Math.min(limit, matches.length);
+
+  let start = 0;
+  const buffers = Array.from({length: splitsLength}, (v, i) => {
+    const offset = matches[i];
+    const split = buffer.slice(start, offset);
+
+    start = offset + sepLen;
+
+    return split;
+  });
+
+  return {buffers, ...rest};
+};