@centralping/ergo 0.1.0-beta.1

package/utils/streams/index.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Streams utilities barrel export.
+ *
+ * @module utils/streams
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ./meter.js
+ * @requires ./tee.js
+ */
+export {default as meter} from './meter.js';
+export {default as tee} from './tee.js';

package/utils/streams/meter.js

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Byte-counting Transform stream.
+ *
+ * Passes all data through while counting received bytes. Emits an error if the
+ * byte count exceeds `limit` (TooLarge) or diverges from the expected `Content-Length`
+ * (InvalidLength). Used by `http/body.js` to enforce size constraints.
+ *
+ * @module utils/streams/meter
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:stream
+ *
+ * @example
+ * import {pipeline} from 'node:stream';
+ * import meter from 'ergo/utils/streams/meter';
+ *
+ * const m = meter({limit: 1024 * 1024, expected: 512});
+ * pipeline(readable, m, writable, err => {
+ *   if (!err) console.log('bytes received:', m.bytesRead);
+ * });
+ */
+import {Transform} from 'node:stream';
+/**
+ * Creates a byte-metering Transform stream.
+ *
+ * @param {object} [options] - Meter configuration
+ * @param {number} [options.expected] - Expected byte count (from Content-Length)
+ * @param {number} [options.limit=Infinity] - Maximum bytes allowed
+ * @returns {import('node:stream').Transform} - Transform with `bytesRead`, `limit`, `expected` properties
+ */
+export default ({expected, limit = Infinity} = {}) =>
+  Object.defineProperties(new Transform({transform, final}), {
+    limit: {
+      value: limit,
+      writable: true
+    },
+    bytesRead: {
+      value: 0,
+      writable: true
+    },
+    expected: {
+      value: expected,
+      writable: true
+    }
+  });
+
+/**
+ * Accumulates byte count and emits an error if limits are exceeded.
+ *
+ * @param {import('node:buffer').Buffer} chunk - Incoming data chunk
+ * @param {string} encoding - Encoding (unused for Buffer chunks)
+ * @param {function} cb - Node.js Transform callback
+ */
+function transform(chunk, encoding, cb) {
+  this.bytesRead += Buffer.byteLength(chunk);
+  const err =
+    this.bytesRead > this.limit
+      ? Object.assign(
+          new Error(`Body exceeded size limit: [${this.limit}]; received: [${this.bytesRead}]`),
+          {
+            type: 'TooLarge',
+            limit: this.limit,
+            length: this.bytesRead
+          }
+        )
+      : this.expected !== undefined && this.bytesRead > this.expected
+        ? Object.assign(
+            new Error(
+              `Body exceeds Content-Length: [${this.expected}]; received: [${this.bytesRead}]`
+            ),
+            {
+              type: 'InvalidLength',
+              length: this.expected,
+              received: this.bytesRead
+            }
+          )
+        : null;
+
+  cb(err, chunk);
+}
+
+/**
+ * Validates final byte count against expected Content-Length.
+ *
+ * @param {function} cb - Node.js Transform callback
+ */
+function final(cb) {
+  const err =
+    this.expected !== undefined && this.bytesRead !== this.expected
+      ? Object.assign(new Error('Body does not match Content-Length'), {
+          type: 'InvalidLength',
+          length: this.expected,
+          received: this.bytesRead
+        })
+      : null;
+
+  cb(err);
+}

package/utils/streams/tee.js

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Tee Transform stream for sidecar generator pipelines.
+ *
+ * Forwards all chunks through a generator's `next()` call, then passes them
+ * unchanged to the next stream in the pipeline. Allows intercepting stream data
+ * for side-effect processing (hashing, logging, validation) without buffering.
+ *
+ * If no generator is provided, a no-op generator is used (pure passthrough).
+ *
+ * @module utils/streams/tee
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:stream
+ *
+ * @example
+ * import {pipeline} from 'node:stream';
+ * import tee from 'ergo/utils/streams/tee';
+ *
+ * async function* inspect(gen) {
+ *   let chunk;
+ *   while ((chunk = yield) !== undefined) {
+ *     console.log('chunk size:', chunk.length);
+ *     gen.next(chunk);
+ *   }
+ *   gen.return();
+ * }
+ *
+ * pipeline(readable, tee(inspect(sink)), writable, err => {});
+ */
+import {Transform} from 'node:stream';
+
+const generatorSym = Symbol('generator');
+
+/**
+ * Creates a Transform stream that forwards each chunk to a generator as a side channel.
+ *
+ * @param {Generator} generator - Initialized generator to receive chunks via `.next(chunk)`
+ * @returns {import('node:stream').Transform} - Transform stream that passes data through while teeing to the generator
+ */
+export default generator => {
+  if (generator === undefined) {
+    /* eslint-disable-next-line no-param-reassign */
+    generator = (function* () {})();
+    generator.next();
+  }
+
+  return Object.defineProperties(new Transform({transform, final}), {
+    [generatorSym]: {
+      value: generator
+    }
+  });
+};
+
+/**
+ * @param {import('node:buffer').Buffer} chunk - Incoming data chunk
+ * @param {string} encoding - Chunk encoding
+ * @param {function} cb - Callback to signal transform completion
+ */
+async function transform(chunk, encoding, cb) {
+  let err = null;
+
+  try {
+    await this[generatorSym].next(chunk);
+  } catch (e) {
+    err = e;
+  } finally {
+    cb(err, chunk);
+  }
+}
+
+/**
+ * @param {function} cb - Callback to signal finalization is complete
+ */
+async function final(cb) {
+  let err = null;
+
+  try {
+    await this[generatorSym].return();
+  } catch (e) {
+    err = e;
+  } finally {
+    cb(err);
+  }
+}

package/utils/type.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Constructor-name-based type detection utility.
+ *
+ * Returns the constructor name of any value, handling edge cases:
+ * - `NaN` — returns `'NaN'` (not `'Number'`)
+ * - Anonymous constructors (`name === ''`) — falls back to `Object.prototype.toString`
+ * - `null`, `undefined`, primitives without constructors — falls back to `toString`
+ *
+ * Used throughout Ergo for duck-typing checks (e.g. `type(x) === 'AsyncGeneratorFunction'`).
+ *
+ * @module utils/type
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import type from 'ergo/utils/type';
+ *
+ * type(42)              // 'Number'
+ * type(NaN)             // 'NaN'
+ * type(null)            // 'Null'
+ * type([])              // 'Array'
+ * type(async function*(){}) // 'AsyncGeneratorFunction'
+ */
+
+/**
+ * @param {*} o - Value to inspect
+ * @returns {string} - Constructor name (e.g. 'String', 'Array', 'NaN')
+ */
+export default o => {
+  // Use a try in the case of `undefined`, `null` or any value that may
+  //  not have a constructor property
+  try {
+    const type = o.constructor.name;
+
+    switch (type) {
+      case 'Number':
+        // Special Case for NaN
+        return Number.isNaN(o) ? 'NaN' : type;
+      case '':
+        return {}.toString.call(o).slice(8, -1);
+      default:
+        return type;
+    }
+  } catch {
+    return {}.toString.call(o).slice(8, -1);
+  }
+};