web-streams-shim 1.0.0 → 1.0.2

package/.github/workflows/npm_publish.yml

@@ -0,0 +1,34 @@
+name: Node.js Package
+on:
+  release:
+    types: [created]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install -g npm@latest  # Ensure latest npm
+      - run: rm -f .npmrc  
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm install -g npm@latest
+      - run: npm ci
+      - run: npm publish

package/README.md

@@ -0,0 +1,50 @@
+## Web Streams Shim Library
+
+This README provides a comprehensive overview of the features and architectural strategies used in this Web Streams Shim Library, which is designed to integrate modern streams functionality into legacy JavaScript environments.
+
+This library provides essential polyfills and shims to ensure modern Web Streams functionality is available and compliant across environments where native support is missing or incomplete, particularly focusing on `ReadableStream`, `Request`, `Response`, and `Blob` objects.
+
+***
+
+## Key Features and Polyfills
+
+The library focuses on extending core browser APIs to meet the latest Web Stream and Fetch specifications.
+
+### 1. ReadableStream Async Iteration and Disposal
+
+The library adds **comprehensive support for modern JavaScript iteration and disposal patterns** to `ReadableStream` and its readers.
+
+| Target | Method/Property | Description |
+| :--- | :--- | :--- |
+| `ReadableStream.prototype` | `[Symbol.asyncIterator]` | Allows the stream to be directly iterable in `for-await-of` loops. It reuses a reader associated with the stream, managed via a `WeakMap`. |
+| `ReadableStream.prototype` | `values()` | An alias for `[Symbol.asyncIterator]` for explicit iteration. |
+| `ReadableStreamDefaultReader.prototype` | `next()` | **Delegates directly to the reader’s native `read()` method**, fulfilling the async iterator requirement. |
+| `ReadableStreamDefaultReader.prototype` | `return(reason)` | Handles early termination (e.g., `break` or `return` within iteration). It safely calls the internal **`terminate` function** to cancel the stream and release the lock. |
+| `ReadableStreamDefaultReader.prototype` | `throw(reason)` | Handles error injection into the iteration. It calls `terminate` to cancel the stream and release the lock, and logs the error. |
+| `ReadableStreamDefaultReader.prototype` | `[Symbol.asyncDispose]` | **Supports the async disposal pattern (`await using`)**. It safely cleans up resources by calling the internal `terminate` function. |
+
+### 2. Stream Construction Utility
+
+The library adds the static method for creating streams from existing data sources.
+
+| Target | Method | Description |
+| :--- | :--- | :--- |
+| `ReadableStream` | `from(obj)` | **Creates a new `ReadableStream` from any iterable or async iterable object**. It handles both synchronous and asynchronous iterators, including objects that yield `Promise`-like values. |
+
+### 3. Fetch and Body Integration Shims
+
+These shims ensure `Request` and `Response` objects (Records) consistently expose their body as a stream and provide the `bytes()` utility.
+
+| Target | Method/Property | Description |
+| :--- | :--- | :--- |
+| `Request.prototype` | `body` (Getter) | Polyfills the `body` property to return a **`ReadableStream` representation of the body content**. This is crucial for environments where `fetch` exists but streaming is absent. |
+| `Response.prototype` | `body` (Getter) | Provides the body content as a `ReadableStream`. The implementation clones the original record, converts the body to a `Blob`, gets the blob's stream, and enqueues chunks via a controller. |
+| `Request.prototype`, `Response.prototype`, `Blob.prototype` | `bytes()` | Adds the `bytes()` method, which **asynchronously returns the object's body/content as a `Uint8Array`**. It achieves this by calling the native `arrayBuffer()` and wrapping the result. |
+
+### 4. Duplex Compliance Shim
+
+To satisfy modern `fetch` specifications when streaming request bodies, the library ensures compliance for **half-duplex operations**.
+
+*   **Property Injection:** The `duplex: 'half'` property is added to the prototypes of `Request`, `Response`, `ReadableStream`, and `Blob`.
+*   **Constructor Wrapping:** The global `Request` and `Response` constructors are subclassed and **wrapped** to automatically apply the `duplexHalf` utility function to all arguments passed during instantiation.
+*   **Fetch Wrapping:** The global `fetch` function is **wrapped** to automatically apply the `duplexHalf` utility function to its arguments before execution, guaranteeing compliance when streams are used in options.

package/ReadableStream-asyncIterator.js

@@ -0,0 +1,350 @@
+/**
+
+- Polyfill for ReadableStream async iterator protocol support
+- Adds iterator methods to ReadableStream and ReadableStreamDefaultReader
+- to make them compatible with async iteration (for-await-of loops) and disposal patterns
+  */
+(() => {
+    // Early return if ReadableStream is not available
+    if (typeof ReadableStream === 'undefined') return;
+    const Q = fn => {
+        try {
+            return fn?.()
+        } catch {}
+    };
+    const constructPrototype = newClass => {
+        try {
+            if (newClass?.prototype) return newClass;
+            const constProto = newClass?.constructor?.prototype;
+            if (constProto) {
+                newClass.prototype = Q(() => constProto?.bind?.(constProto)) ?? Object.create(Object(constProto));
+                return newClass;
+            }
+            newClass.prototype = Q(() => newClass?.bind?.(newClass)) ?? Object.create(Object(newClass));
+        } catch (e) {
+            console.warn(e, newClass);
+        }
+    };
+    const extend = (thisClass, superClass) => {
+        try {
+            constructPrototype(thisClass);
+            constructPrototype(superClass);
+            Object.setPrototypeOf(
+                thisClass.prototype,
+                superClass?.prototype ??
+                superClass?.constructor?.prototype ??
+                superClass
+            );
+            Object.setPrototypeOf(thisClass, superClass);
+
+        } catch (e) {
+            console.warn(e, {
+                thisClass,
+                superClass
+            });
+        }
+        return thisClass;
+    };
+    /**
+
+    - Creates a function that returns a string for all string conversion methods
+    - Used to provide consistent string representations for polyfilled functions
+    - @param {string} str - The string to return
+    - @returns {Function} A function that returns the string for all conversion methods
+    - @private
+      */
+    const makeStringer = str => {
+        const stringer = () => str;
+        ['valueOf', 'toString', 'toLocaleString', Symbol.toPrimitive].forEach(x => {
+            stringer[x] = stringer;
+        });
+        stringer[Symbol.toStringTag] = str;
+        return stringer;
+    };
+
+    /**
+
+    - Sets string conversion methods on a function to indicate it’s polyfill code
+    - Provides consistent debugging experience by showing polyfill status
+    - @param {Function} obj - The function to modify
+    - @param {string} name - The function name (currently unused but kept for future use)
+    - @returns {Function} The modified function
+    - @private
+      */
+    const setStrings = (obj, name) => {
+        for (const str of ['toString', 'toLocaleString', Symbol.toStringTag]) {
+            Object.defineProperty(obj, str, {
+                value: makeStringer(`function ${obj.name}() { [polyfill code] }`),
+                configurable: true,
+                writable: true,
+                enumerable: false,
+            });
+        }
+        return obj;
+    };
+
+
+
+    /**
+
+    - Safely executes an async function and catches any errors
+    - @param {Function} fn - Async function to execute
+    - @returns {Promise<*>} The result of fn() or undefined if an error occurred
+      */
+    const asyncQ = async (fn) => {
+        try {
+            return await fn?.();
+        } catch {}
+    };
+
+    /**
+
+    - Terminates a stream/reader by calling all cleanup methods
+    - Attempts cancel, close, and releaseLock operations safely
+    - @param {ReadableStream|ReadableStreamDefaultReader} x - The stream or reader to terminate
+    - @param {*} reason - Optional reason for termination
+    - @returns {Promise} Promise that resolves to the closed state or undefined
+      */
+    const terminate = async (x, reason) => {
+        await asyncQ(async () => x.cancel(reason));
+        await asyncQ(async () => x.close(reason));
+        await asyncQ(async () => x.releaseLock(reason));
+        return await asyncQ(async () => x.closed);
+    };
+
+    /**
+
+    - Add next() method to ReadableStreamDefaultReader
+    - Makes readers compatible with async iterator protocol
+      */
+    (() => {
+        /**
+        - Iterator next() method for ReadableStreamDefaultReader
+        - Delegates to the reader’s read() method for async iterator compatibility
+        - @returns {Promise<{done: boolean, value: any}>} Iterator result object
+        - @note Sets the read method as prototype for better runtime type traceability
+        - @example
+        - const reader = stream.getReader();
+        - const { done, value } = await reader.next(); // Same as reader.read()
+          */
+        ReadableStreamDefaultReader.prototype.next ?? Object.defineProperty(ReadableStreamDefaultReader.prototype, 'next', {
+            value: extend(setStrings(function next() {
+                return this.read();
+            }), ReadableStreamDefaultReader.prototype.read),
+            configurable: true,
+            writable: true,
+            enumerable: false,
+        });
+    })();
+
+    /**
+
+    - Add Symbol.asyncIterator to ReadableStreamDefaultReader
+    - Makes readers directly iterable with for-await-of loops
+      */
+    (() => {
+        /**
+        - Async iterator method for ReadableStreamDefaultReader
+        - Returns the reader itself since it implements the async iterator protocol
+        - @returns {ReadableStreamDefaultReader} The reader itself
+        - @note Sets ReadableStreamDefaultReader as prototype for better runtime type traceability
+        - @example
+        - const reader = stream.getReader();
+        - for await (const chunk of reader) {
+        - console.log(chunk);
+        - }
+          */
+        ReadableStreamDefaultReader.prototype[Symbol.asyncIterator] ??= extend(setStrings(Object.defineProperty(function asyncIterator() {
+            return this;
+        }, 'name', {
+            value: 'Symbol.asyncIterator',
+            configurable: true,
+            writable: true,
+            enumerable: true,
+        })), ReadableStreamDefaultReader);
+    })();
+
+    /**
+
+    - Iterator completion and disposal methods for ReadableStreamDefaultReader
+    - Implements return() and throw() methods for proper async iterator protocol compliance
+      */
+    (() => {
+        /**
+        - Internal class representing the end of stream iteration
+        - Used to signal completion with optional return value
+        - @private
+          */
+        class StreamEnd {
+            /** @type {boolean} Always true to indicate iteration is complete */
+            done = true;
+            /** @type {*} The return/throw value */
+            value;
+
+            /**
+            - @param {*} value - The value to return when iteration ends
+              */
+            constructor(value) {
+                this.value = value;
+            }
+        }
+
+
+        /**
+         * Add return() method to ReadableStreamDefaultReader
+         * Handles early termination of async iteration
+         */
+        (() => {
+            /**
+             * Iterator return() method for ReadableStreamDefaultReader
+             * Called when async iteration is terminated early (break, return, etc.)
+             * Safely cancels the stream and releases the reader lock
+             * @param {*} reason - Optional reason for termination
+             * @returns {StreamEnd} Iterator result indicating completion
+             * @note Sets releaseLock as prototype for better runtime type traceability
+             * @example
+             * for await (const chunk of reader) {
+             *   if (shouldStop) break; // Calls reader.return() automatically
+             * }
+             */
+            ReadableStreamDefaultReader.prototype['return'] ?? Object.defineProperty(ReadableStreamDefaultReader.prototype, 'return', {
+                value: extend(setStrings(Object.defineProperty(function $return(reason) {
+                    terminate(this, reason);
+                    return new StreamEnd(reason);
+                }, 'name', {
+                    value: 'return',
+                    configurable: true,
+                    writable: true,
+                    enumerable: true,
+                })), ReadableStreamDefaultReader.prototype.releaseLock),
+                configurable: true,
+                writable: true,
+                enumerable: false,
+            });
+        })();
+
+        /**
+         * Add throw() method to ReadableStreamDefaultReader
+         * Handles error injection into async iteration
+         */
+        (() => {
+            /**
+             * Iterator throw() method for ReadableStreamDefaultReader
+             * Called when an error is injected into async iteration
+             * Safely cancels the stream and releases the reader lock
+             * @param {*} reason - The error/reason being thrown
+             * @returns {StreamEnd} Iterator result indicating completion with error
+             * @note Sets controller error method as prototype for better runtime type traceability
+             * @example
+             * const iterator = reader[Symbol.asyncIterator]();
+             * iterator.throw(new Error('Stop processing'));
+             */
+            ReadableStreamDefaultReader.prototype['throw'] ?? Object.defineProperty(ReadableStreamDefaultReader.prototype, 'throw', {
+                value: extend(setStrings(Object.defineProperty(function $throw(reason) {
+                    terminate(this, reason);
+                    console.error(reason);
+                    return new StreamEnd(reason);
+                }, 'name', {
+                    value: 'throw',
+                    configurable: true,
+                    writable: true,
+                    enumerable: true,
+                })), ReadableStreamDefaultController.prototype.error),
+                configurable: true,
+                writable: true,
+                enumerable: false,
+            });
+        })();
+
+        /**
+         * Add Symbol.asyncDispose method to ReadableStreamDefaultReader
+         * Supports the async disposal pattern (using/await using statements)
+         */
+        (() => {
+            // Use Symbol.asyncDispose if available, otherwise use string key as fallback
+            const $asyncDispose = Symbol.asyncDispose ?? 'Symbol.asyncDispose';
+
+            /**
+             * Async dispose method for ReadableStreamDefaultReader
+             * Called automatically when using 'await using' syntax
+             * Safely cancels the stream and releases the reader lock
+             * @param {*} reason - Optional disposal reason
+             * @returns {Promise} Promise that resolves when disposal is complete
+             * @note Sets closed property getter as prototype for better runtime type traceability
+             * @example
+             * await using reader = stream.getReader();
+             * // reader is automatically disposed when leaving scope
+             * 
+             * // Or manually:
+             * await reader[Symbol.asyncDispose]();
+             */
+            ReadableStreamDefaultReader.prototype[$asyncDispose] ?? Object.defineProperty(ReadableStreamDefaultReader.prototype, $asyncDispose, {
+                value: extend(setStrings(Object.defineProperty(async function asyncDispose(reason) {
+                    return await terminate(this, reason);
+                }, 'name', {
+                    value: 'Symbol.asyncDispose',
+                    configurable: true,
+                    writable: true,
+                    enumerable: true,
+                })), Object.getOwnPropertyDescriptor(ReadableStreamDefaultReader.prototype, 'closed').get),
+                configurable: true,
+                writable: true,
+                enumerable: false,
+            });
+        })();
+
+
+    })();
+
+    /**
+
+    - Add async iterator support to ReadableStream itself
+    - Makes streams directly iterable without needing to get a reader first
+      */
+    (() => {
+        // WeakMap to associate readers with streams for reuse
+        const $readers = new(globalThis.WeakMap ?? Map);
+
+
+        // Set prototype on getReader method for better type traceability
+        extend(ReadableStream.prototype.getReader, ReadableStreamDefaultReader);
+
+        /**
+         * Async iterator method for ReadableStream
+         * Returns a reader that can be used with for-await-of loops
+         * Reuses the same reader for multiple iteration attempts on the same stream
+         * @returns {ReadableStreamDefaultReader} A reader for async iteration
+         * @note Sets getReader as prototype for better runtime type traceability
+         * @example
+         * for await (const chunk of stream) {
+         *   console.log(chunk);
+         * }
+         */
+        ReadableStream.prototype[Symbol.asyncIterator] ??= extend(setStrings(Object.defineProperty(function asyncIterator() {
+            const $reader = $readers.get(this) ?? Q(() => this?.getReader?.());
+            $readers.set(this, $reader);
+            return $reader;
+        }, 'name', {
+            value: 'Symbol.asyncIterator',
+            configurable: true,
+            writable: true,
+            enumerable: true,
+        })), ReadableStream.prototype.getReader);
+
+        /**
+         * Values method for ReadableStream
+         * Alias for Symbol.asyncIterator for explicit iteration
+         * @returns {ReadableStreamDefaultReader} A reader for async iteration
+         * @note Sets the asyncIterator method as prototype for better runtime type traceability
+         * @example
+         * for await (const chunk of stream.values()) {
+         *   console.log(chunk);
+         * }
+         */
+        ReadableStream.prototype.values ??= extend(setStrings(function values() {
+            return this[Symbol.asyncIterator]();
+        }), ReadableStream.prototype[Symbol.asyncIterator]);
+
+
+    })();
+})();

package/ReadableStream-from.js

@@ -0,0 +1,166 @@
+/**
+
+- Polyfill for ReadableStream.from() method
+- Creates a ReadableStream from an iterable object (sync or async)
+- @see https://streams.spec.whatwg.org/#rs-from
+  */
+(() => {
+    // Early return if ReadableStream is not available
+    if (typeof ReadableStream === 'undefined') return;
+    const Q = fn => {
+        try {
+            return fn?.()
+        } catch {}
+    };
+    const constructPrototype = newClass => {
+        try {
+            if (newClass?.prototype) return newClass;
+            const constProto = newClass?.constructor?.prototype;
+            if (constProto) {
+                newClass.prototype = Q(() => constProto?.bind?.(constProto)) ?? Object.create(Object(constProto));
+                return newClass;
+            }
+            newClass.prototype = Q(() => newClass?.bind?.(newClass)) ?? Object.create(Object(newClass));
+        } catch (e) {
+            console.warn(e, newClass);
+        }
+    };
+    const extend = (thisClass, superClass) => {
+        try {
+            constructPrototype(thisClass);
+            constructPrototype(superClass);
+            Object.setPrototypeOf(
+                thisClass.prototype,
+                superClass?.prototype ??
+                superClass?.constructor?.prototype ??
+                superClass
+            );
+            Object.setPrototypeOf(thisClass, superClass);
+
+        } catch (e) {
+            console.warn(e, {
+                thisClass,
+                superClass
+            });
+        }
+        return thisClass;
+    };
+    const makeStringer = str => {
+        const stringer = () => str;
+        ['valueOf', 'toString', 'toLocaleString', Symbol.toPrimitive].forEach(x => {
+            stringer[x] = stringer;
+        });
+        stringer[Symbol.toStringTag] = str;
+        return stringer;
+    };
+    const setStrings = (obj, name) => {
+        for (const str of ['toString', 'toLocaleString', Symbol.toStringTag]) {
+            Object.defineProperty(obj, str, {
+                value: makeStringer(`function ${obj.name}() { [polyfill code] }`),
+                configurable: true,
+                writable: true,
+                enumerable: false,
+            });
+        }
+        return obj;
+    };
+
+    const instanceOf = (x, y) => Q(() => x instanceof y);
+    /**
+
+    - Safely closes a ReadableStream controller
+    - @param {ReadableStreamDefaultController} ctrl - The controller to close
+      */
+    const close = ctrl => Q(() => ctrl.close());
+
+    /**
+
+    - Safely cancels a ReadableStream or ReadableStreamReader
+    - @param {ReadableStream|ReadableStreamDefaultReader} readable - The stream or reader to cancel
+      */
+    const cancel = readable => Q(() => readable.cancel());
+
+    /**
+
+    - Checks if a value is a Promise-like object
+    - @param {*} x - Value to check
+    - @returns {boolean} True if the value appears to be a Promise
+      */
+    const isPromise = x => instanceOf(x, Promise) ||
+        instanceOf(Promise.prototype, x?.constructor) ||
+        x?.constructor?.name === 'Promise' ||
+        typeof x?.then === 'function';
+    /**
+
+    - Creates a ReadableStream from an iterable object
+    - Polyfill implementation for ReadableStream.from()
+    - @param {Iterable|AsyncIterable} obj - An iterable or async iterable object
+    - @returns {ReadableStream} A new ReadableStream that yields values from the iterable
+    - @note Sets ReadableStream as the prototype of the from function for better runtime type traceability
+    - @example
+    - // From array
+    - const stream = ReadableStream.from([1, 2, 3]);
+    - 
+    - // From generator
+    - function* gen() { yield 1; yield 2; yield 3; }
+    - const stream2 = ReadableStream.from(gen());
+    - 
+    - // From async generator
+    - async function* asyncGen() { yield Promise.resolve(1); }
+    - const stream3 = ReadableStream.from(asyncGen());
+      */
+    ReadableStream.from ??= extend(setStrings(function from(obj) {
+        let $iter, $readableStream;
+
+
+        $readableStream = new ReadableStream({
+            /**
+             * Pull method for the ReadableStream
+             * Retrieves the next value from the iterator and enqueues it
+             * @param {ReadableStreamDefaultController} controller - Stream controller
+             */
+            pull: extend(setStrings(async function pull(controller) {
+                try {
+                    if (isPromise(obj)) {
+                        obj = await obj;
+                    }
+                    // Initialize iterator if not already done
+                    // Try sync iterator first, then async iterator, then convert to array and get iterator as last resort
+                    $iter ??= obj?.[Symbol.iterator]?.() ??
+                        obj?.[Symbol.asyncIterator]?.() ?? [][Symbol.iterator].call(obj);
+
+                    // Get next chunk from iterator
+                    let chunk = $iter.next();
+
+                    // Await if chunk is a promise
+                    if (isPromise(chunk)) {
+                        chunk = await chunk;
+                    }
+
+                    // If iterator is not done, enqueue the value
+                    if (chunk?.done === false) {
+                        let value = chunk?.value;
+
+                        // Await value if it's a promise
+                        if (isPromise(value)) {
+                            value = await value;
+                        }
+
+                        controller.enqueue(value);
+                    } else {
+                        // Iterator is done, close the stream
+                        close(controller);
+                    }
+                } catch (e) {
+                    // On error, close controller and cancel stream
+                    close(controller);
+                    cancel($readableStream);
+                    throw e;
+                }
+            }), ReadableStreamDefaultController),
+        });
+
+        return $readableStream;
+
+    }), ReadableStream);
+})();