@centralping/ergo 0.1.0-beta.1

package/utils/compose-with.js

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview Path-based compose utility for Ergo middleware pipelines (v2).
+ *
+ * Extends `utils/compose` with a two-accumulator model: a **domain accumulator** for
+ * inter-middleware data and a **response accumulator** for HTTP response construction.
+ *
+ * Each operation can be expressed as:
+ * - A plain function: `fn` (receives `(...args, domainAcc)`)
+ * - A tuple: `[fn, setPath]` where:
+ *   - `fn` — the middleware function
+ *   - `setPath` — the domain accumulator key to store the return value under
+ *
+ * Middleware returns are interpreted as `{value?, response?}`:
+ * - `value` is merged into the domain accumulator (at `setPath` for tuples, or
+ *   `Object.assign` for plain functions)
+ * - `response` is merged into the response accumulator (headers append, scalars set)
+ * - When `responseAcc.statusCode` is set, serial iteration breaks immediately
+ * - `undefined` / `null` returns skip all merges
+ *
+ * Plain return values (without `value` or `response` keys) are treated as `{value: ret}`
+ * for compatibility with simple middleware that only produce domain data.
+ *
+ * @module utils/compose-with
+ * @version 0.2.0
+ * @since 0.1.0
+ * @requires ./compose.js
+ * @requires ./set.js
+ *
+ * @example
+ * import compose, {createResponseAcc} from 'ergo/utils/compose-with';
+ *
+ * const responseAcc = createResponseAcc();
+ * const pipeline = compose(
+ *   [logger(), 'log'],
+ *   [authorization({...}), 'auth'],
+ *   [body(), 'body'],
+ *   (req, res, acc) => ({response: {body: process(acc.body), statusCode: 200}})
+ * );
+ *
+ * await pipeline(req, res, responseAcc, domainAcc);
+ * // responseAcc.statusCode, responseAcc.headers, etc.
+ */
+import {accumulator} from './compose.js';
+import set from './set.js';
+
+/**
+ * Creates a null-prototype response accumulator.
+ *
+ * The returned object has a non-enumerable `isResponseAcc` flag used by the pipeline
+ * to distinguish it from the domain accumulator in the argument list.
+ *
+ * @returns {object} - Null-prototype object with `isResponseAcc: true`
+ */
+export function createResponseAcc() {
+  const acc = Object.create(null);
+  Object.defineProperty(acc, 'isResponseAcc', {value: true});
+  return acc;
+}
+
+/**
+ * Merges a response patch into the response accumulator.
+ *
+ * - `headers` arrays are **appended** (additive across middleware)
+ * - All other properties are **assigned** (last writer wins)
+ *
+ * @param {object} responseAcc - Mutable response accumulator
+ * @param {object} patch - Response contribution from middleware
+ */
+export function mergeResponse(responseAcc, patch) {
+  if (patch.headers) {
+    responseAcc.headers ??= [];
+    responseAcc.headers.push(...patch.headers);
+  }
+
+  for (const key of Object.keys(patch)) {
+    if (key !== 'headers') responseAcc[key] = patch[key];
+  }
+}
+
+/**
+ * Extracts `{value, response}` from a middleware return value.
+ *
+ * If the return is an object with a `value` or `response` key, those are used directly.
+ * Otherwise the entire return is treated as `{value: ret}` for backward compatibility
+ * with middleware that return plain domain data.
+ *
+ * @param {*} resolved - Resolved return value from middleware
+ * @returns {{value: *, response: *}} - Extracted value and response
+ */
+function extractReturn(resolved) {
+  if (
+    resolved !== null &&
+    typeof resolved === 'object' &&
+    !Array.isArray(resolved) &&
+    ('value' in resolved || 'response' in resolved)
+  ) {
+    return resolved;
+  }
+
+  return {value: resolved};
+}
+
+/**
+ * Converts an operation spec into a normalized descriptor.
+ *
+ * @param {function|Array} op - A plain function or `[fn, setPath]` tuple
+ * @returns {{fn: function, setPath: string|undefined}} - Normalized descriptor
+ */
+function normalizeOp(op) {
+  if (!Array.isArray(op)) return {fn: op, setPath: undefined};
+  return {fn: op[0], setPath: op[1]};
+}
+
+/**
+ * Runs middleware descriptors sequentially with two-accumulator support.
+ *
+ * Uses a sync fast-path: when a middleware returns a non-thenable value, merging
+ * happens immediately without a microtask hop.
+ *
+ * @param {Array<{fn: function, setPath: string|undefined}>} descriptors - Normalized ops
+ * @param {*[]} args - Original request arguments (req, res, etc.)
+ * @param {object} domainAcc - Domain accumulator
+ * @param {object} responseAcc - Response accumulator
+ * @returns {object} - Final domain accumulator
+ */
+async function serial(descriptors, args, domainAcc, responseAcc) {
+  for (const {fn, setPath} of descriptors) {
+    const raw = fn(...args, domainAcc, responseAcc);
+    const resolved = typeof raw?.then === 'function' ? await raw : raw;
+
+    if (resolved == null) continue;
+
+    const {value, response} = extractReturn(resolved);
+
+    if (value !== undefined) {
+      if (setPath !== undefined) {
+        set(domainAcc, setPath, value);
+      } else if (typeof value === 'object') {
+        Object.assign(domainAcc, value);
+      }
+    }
+
+    if (response !== undefined) {
+      mergeResponse(responseAcc, response);
+    }
+
+    if (responseAcc.statusCode !== undefined) break;
+  }
+
+  return domainAcc;
+}
+
+/**
+ * Runs middleware descriptors concurrently with two-accumulator support.
+ *
+ * Each branch receives an isolated domain accumulator copy. After all branches
+ * complete, values and responses are merged in declaration order.
+ *
+ * @param {Array<{fn: function, setPath: string|undefined}>} descriptors - Normalized ops
+ * @param {*[]} args - Original request arguments
+ * @param {object} domainAcc - Domain accumulator
+ * @param {object} responseAcc - Response accumulator
+ * @returns {object} - Final domain accumulator
+ */
+async function concurrent(descriptors, args, domainAcc, responseAcc) {
+  const copies = descriptors.map(() => Object.assign(accumulator(), domainAcc));
+  const rets = descriptors.map(({fn}, i) => fn(...args, copies[i], responseAcc));
+  const hasAsync = rets.some(r => typeof r?.then === 'function');
+  const results = hasAsync ? await Promise.all(rets) : rets;
+
+  for (let i = 0; i < descriptors.length; i++) {
+    const resolved = results[i];
+    if (resolved == null) continue;
+
+    const {setPath} = descriptors[i];
+    const {value, response} = extractReturn(resolved);
+
+    if (value !== undefined) {
+      if (setPath !== undefined) {
+        set(domainAcc, setPath, value);
+      } else if (typeof value === 'object') {
+        Object.assign(domainAcc, value);
+      }
+    }
+
+    if (response !== undefined) {
+      mergeResponse(responseAcc, response);
+    }
+  }
+
+  return domainAcc;
+}
+
+/**
+ * Composes middleware with path-based result storage and two-accumulator support.
+ *
+ * The composed function pops the domain accumulator (last arg with `isAccumulator`)
+ * and response accumulator (last arg with `isResponseAcc`) from its arguments.
+ * If either is absent, a fresh one is created.
+ *
+ * @param {...(function|Array)} ops - Operation specs; each is a function or `[fn, setPath]`
+ * @returns {function} - Async composed pipeline
+ */
+const composeWith = (...ops) => {
+  const descriptors = ops.map(normalizeOp);
+
+  return async (...args) => {
+    const domainAcc = args.at(-1)?.isAccumulator ? args.pop() : accumulator();
+    const responseAcc = args.at(-1)?.isResponseAcc ? args.pop() : createResponseAcc();
+
+    return await serial(descriptors, args, domainAcc, responseAcc);
+  };
+};
+
+/**
+ * Concurrent variant of composeWith.
+ *
+ * @param {...(function|Array)} ops - Operation specs
+ * @returns {function} - Async composed pipeline
+ */
+composeWith.all = (...ops) => {
+  const descriptors = ops.map(normalizeOp);
+
+  return async (...args) => {
+    const domainAcc = args.at(-1)?.isAccumulator ? args.pop() : accumulator();
+    const responseAcc = args.at(-1)?.isResponseAcc ? args.pop() : createResponseAcc();
+
+    return await concurrent(descriptors, args, domainAcc, responseAcc);
+  };
+};
+
+export default composeWith;

package/utils/compose.js

@@ -0,0 +1,165 @@
+/**
+ * @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
+ */
+const compose = (...fns) => setup(serial, fns);
+compose.all = (...fns) => setup(concurrent, fns);
+
+/**
+ * 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
+ */
+compose.withOptions = (options, ...fns) => setup(serial, fns, options);
+
+/**
+ * Creates a concurrent pipeline with configuration options.
+ *
+ * @param {object} options - Pipeline options
+ * @param {...function} fns - Middleware functions to compose
+ * @returns {function} - Async composed pipeline
+ */
+compose.all.withOptions = (options, ...fns) => setup(concurrent, fns, options);
+
+export default compose;
+export {accumulator};
+
+/**
+ * Runs middleware functions sequentially, accumulating results.
+ *
+ * Uses a sync fast-path: if a function returns a non-thenable value the result
+ * is merged immediately, avoiding a microtask hop for synchronous middleware.
+ * The accumulator is passed directly (no defensive copy) because serial steps
+ * cannot observe concurrent mutations.
+ *
+ * When `breakWhen` is provided, the predicate is evaluated after each step's
+ * result is merged. If it returns a truthy value, iteration stops immediately.
+ *
+ * @param {function[]} fns - Ordered middleware functions
+ * @param {*[]} args - Original request arguments (req, res, etc.)
+ * @param {object} acc - Accumulator
+ * @param {object} [options] - Pipeline options
+ * @param {function} [options.breakWhen] - Predicate `(acc) => boolean`
+ * @returns {object} - Final accumulated state
+ */
+async function serial(fns, args, acc, {breakWhen} = {}) {
+  for (const f of fns) {
+    const ret = f(...args, acc);
+    Object.assign(acc, typeof ret?.then === 'function' ? await ret : ret);
+
+    if (breakWhen?.(acc)) break;
+  }
+
+  return acc;
+}
+
+/**
+ * Runs middleware functions concurrently, merging all results.
+ *
+ * Each branch receives an isolated accumulator copy so concurrent functions
+ * cannot observe each other's mutations. When every branch returns a
+ * non-thenable value, `Promise.all` is skipped entirely.
+ *
+ * @param {function[]} fns - Middleware functions to run concurrently
+ * @param {*[]} args - Original request arguments
+ * @param {object} acc - Accumulator
+ * @param {object} [_options] - Pipeline options (unused for concurrent; accepted for API symmetry)
+ * @returns {object} - Merged accumulated state
+ */
+async function concurrent(fns, args, acc, _options) {
+  const copies = fns.map(() => accumulator(acc));
+  const rets = fns.map((f, i) => f(...args, copies[i]));
+  const hasAsync = rets.some(r => typeof r?.then === 'function');
+
+  if (hasAsync) {
+    return Object.assign(acc, ...(await Promise.all(rets)));
+  }
+
+  return Object.assign(acc, ...rets);
+}
+
+/**
+ * Creates a composed async function with an initialized accumulator.
+ *
+ * @param {function} processor - `serial` or `concurrent`
+ * @param {function[]} fns - Middleware functions
+ * @param {object} [options] - Pipeline options forwarded to the processor
+ * @returns {function} - Async composed function `(...args) => Accumulator`
+ */
+function setup(processor, fns, options = {}) {
+  return async (...args) => {
+    const acc = args.length && args.at(-1)?.isAccumulator ? args.pop() : accumulator();
+
+    return await processor(fns, args, acc, options);
+  };
+}
+
+/**
+ * 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
+ */
+function accumulator(defaults = {}) {
+  const acc = Object.create(null);
+
+  Object.defineProperties(acc, {
+    isAccumulator: {value: true},
+    size: {
+      get() {
+        return Object.keys(this).length;
+      }
+    }
+  });
+
+  return Object.assign(acc, defaults);
+}

package/utils/flat-array.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Variadic flat-array utility.
+ *
+ * Flattens all arguments into a single array using `Array.prototype.flat()`.
+ * Equivalent to `[...args].flat()` — accepts any mix of scalars and nested arrays.
+ *
+ * @module utils/flat-array
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import flatArray from 'ergo/utils/flat-array';
+ *
+ * flatArray('a', ['b', 'c'], 'd') // => ['a', 'b', 'c', 'd']
+ * flatArray(1, [2, 3], 4)         // => [1, 2, 3, 4]
+ */
+
+/**
+ * @param {...*} items - Values or nested arrays to flatten
+ * @returns {Array} - Single-level flattened array
+ */
+export default (...items) => {
+  return items.flat();
+};

package/utils/get.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Deep property getter with dot-notation path support.
+ *
+ * Traverses a nested object using a dot-delimited path string. Optionally:
+ * - Optionally invokes function values at each step (`invoke: false`, default)
+ * - Returns `undefined` gracefully when a step is missing (`safe: true`)
+ *
+ * @module utils/get
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import get from 'ergo/utils/get';
+ *
+ * get({a: {b: {c: 42}}}, 'a.b.c') // => 42
+ * get({a: null}, 'a.b.c', {safe: true}) // => undefined (no throw)
+ */
+
+/**
+ * @param {object} [obj={}] - Source object
+ * @param {string} [path=''] - Dot-delimited property path
+ * @param {object} [options] - Traversal options
+ * @param {boolean} [options.safe=false] - Return undefined instead of throwing on missing paths
+ * @param {boolean} [options.invoke=false] - Call function values at each path step
+ * @returns {*} - Value at the path, or undefined in safe mode
+ */
+export default (obj = {}, path = '', {safe = false, invoke = false} = {}) => {
+  let val = obj;
+
+  for (const subPath of path.split('.')) {
+    if (val == null && safe) {
+      return undefined;
+    }
+
+    val = typeof val[subPath] === 'function' && invoke ? val[subPath]() : val[subPath];
+  }
+
+  return val;
+};

package/utils/http-errors.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview HTTP error factory producing RFC 9457 Problem Details errors.
+ *
+ * Creates `Error`-prototype objects with RFC 9457 (Problem Details for HTTP APIs)
+ * properties: `type`, `title`, `status`, `detail`, plus internal properties `headers`
+ * and `originalError`. Uses `Object.create(Error.prototype)` instead of `new Error()`
+ * to avoid V8's automatic stack trace capture (~10 µs overhead per call). This is
+ * critical in hot paths like rate-limit rejections where errors are expected control
+ * flow, not exceptional conditions. The objects pass `instanceof Error` checks.
+ *
+ * The `toJSON()` method serializes to RFC 9457 format automatically when
+ * `JSON.stringify()` is called (e.g. by `send()`).
+ *
+ * All Ergo middleware throws these errors directly. The `handler()` middleware
+ * catches them and forwards to `send()` for serialization.
+ *
+ * @module utils/http-errors
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:http
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9457 RFC 9457 - Problem Details for HTTP APIs}
+ *
+ * @example
+ * import httpErrors from 'ergo/utils/http-errors';
+ *
+ * throw httpErrors(404);
+ * // Error { name: 'NotFound', status: 404, type: 'https://...', title: 'Not Found', detail: 'Not Found' }
+ * // JSON.stringify → {"type":"https://...","title":"Not Found","status":404,"detail":"Not Found"}
+ *
+ * throw httpErrors(422, {detail: 'Invalid email', details: errors});
+ * // Error { name: 'UnprocessableEntity', status: 422, detail: 'Invalid email', details: [...] }
+ */
+import {STATUS_CODES} from 'node:http';
+
+const baseUrl = 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/';
+
+/**
+ * @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 = 500,
+  {
+    type = STATUS_CODES[statusCode] ? `${baseUrl}${statusCode}` : undefined,
+    message,
+    detail: rawDetail = message,
+    headers,
+    instance,
+    retryAfter,
+    originalError,
+    ...extra
+  } = {}
+) {
+  const title = STATUS_CODES[statusCode] ?? STATUS_CODES[500];
+  const detail = rawDetail ?? title;
+  const name = title.replace(/\s/g, '');
+
+  const effectiveHeaders =
+    retryAfter != null ? [...(headers ?? []), ['Retry-After', String(retryAfter)]] : headers;
+
+  if (retryAfter != null) {
+    extra.retryAfter = retryAfter;
+  }
+
+  const err = Object.create(Error.prototype);
+  err.message = detail;
+  err.name = name;
+  err.statusCode = statusCode;
+  err.status = statusCode;
+  err.type = type;
+  err.title = title;
+  err.detail = detail;
+  err.instance = instance;
+  err.headers = effectiveHeaders;
+  err.originalError = originalError;
+  if (extra) Object.assign(err, extra);
+  err.message = detail;
+  err.name = name;
+  err.statusCode = statusCode;
+  err.status = statusCode;
+  err.type = type;
+  err.title = title;
+  err.detail = detail;
+
+  const extraKeys = Object.keys(extra);
+
+  Object.defineProperty(err, 'toJSON', {
+    value() {
+      const json = {};
+      for (const key of extraKeys) {
+        json[key] = this[key];
+      }
+      json.type = this.type;
+      json.title = this.title;
+      json.status = this.status;
+      json.detail = this.detail;
+      if (this.instance !== undefined) json.instance = this.instance;
+      return json;
+    }
+  });
+
+  return err;
+}

package/utils/iterables/buffer-split.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Streaming Buffer split generator for async iterable pipelines.
+ *
+ * Creates a generator function that consumes an iterable of Buffer chunks and yields
+ * `[index, buffer]` pairs split by the given separator. Handles partial matches across
+ * chunk boundaries by carrying over unmatched bytes to the next iteration.
+ *
+ * Used by `lib/body/multiparse.js` for multipart boundary splitting.
+ *
+ * @module utils/iterables/buffer-split
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../buffers/split.js
+ *
+ * @example
+ * import {chain, bufferSplit, reduce} from 'ergo/utils/iterables';
+ *
+ * const chunks = [Buffer.from('a--b--c')];
+ * const result = chain(chunks, bufferSplit('--'), reduce((acc, [, b]) => [...acc, b.toString()], []));
+ * // => ['a', 'b', 'c']
+ */
+import split from '../buffers/split.js';
+/**
+ * Creates a Buffer-splitting generator.
+ *
+ * @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} - Generator function `(iterable) => Generator<[number, import('node:buffer').Buffer]>`
+ */
+export default (separator = Buffer.from(''), limit = Infinity) => {
+  const sepBuffer = Buffer.isBuffer(separator) ? separator : Buffer.from(separator);
+
+  /**
+   * @param {Iterable} iterable - Source iterable of Buffers to split
+   */
+  return function* (iterable) {
+    let partialCarryover = Buffer.from('');
+    let partialCarryoverIndexInc = false;
+    let index = 0;
+
+    try {
+      let buffers;
+      let lookup;
+      let partial;
+
+      for (let chunk of iterable) {
+        if (index >= limit) {
+          return;
+        }
+
+        // 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}));
+        /*
+        buffers:
+          A: [n] no matches
+          B: [0, 0] one match, entire chunk
+          C: [0, x[, ...]] one match at beginning and at least one more match after
+          D: [x[, ...], 0] one match at end and at least one more match before
+          E: [x[, ...], y] at least one match in the middle
+
+        index increment:
+          A: none
+          B: on second element
+          C: on second element and beyond
+          D: on second element and beyond
+          E: on second element and beyond
+        */
+
+        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];
+
+          yield [index, buffer];
+        }
+      }
+    } finally {
+      if (partialCarryoverIndexInc) {
+        index++;
+      }
+
+      // Push the carryover if a buffer ends with a partial match
+      if (partialCarryover.length && index < limit) {
+        yield [index, partialCarryover];
+      }
+    }
+  };
+};