web-streams-shim 1.0.4 → 1.0.5

package/README.md

@@ -1,28 +1,38 @@
-## Web Streams Shim Library
+## Web Streams Shim
 
-The Web Streams Shim Library is designed to create parity between the streaming interfaces within modern runtimes. This does not polyfill the interfaces if they are missing entirely. For that you will want [web-streams-polyfill](https://www.npmjs.com/package/web-streams-polyfill) which is not affiliated with the project.
+🛶 Web Streams Shim is designed to create parity between the streaming interfaces within modern runtimes. This does not polyfill the interfaces if they are missing entirely. For that you will want [web-streams-polyfill](https://www.npmjs.com/package/web-streams-polyfill) which is not affiliated with the project.
 
 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.
 
+## Install
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/web-streams-shim@1.0.4/web-streams-core.js"></script>
+```
+
 ***
 
 ## 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
+### Conditional Filling
+
+Each polyfill performs feature detection before initializing. If a feature is detected as already present then it is skipped so as not to overwrite native behavior where possible.
+
+### ReadableStream Async Iteration
 
 The library adds **comprehensive support for modern JavaScript iteration patterns** to `ReadableStream` and its readers.
 
 | Target | Method/Property | Description |
 | :--- | :--- | :--- |
-| [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) | `[Symbol.asyncIterator]` | Allows the stream to be directly iterable in `for-await-of` loops. |
+| [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) | [`[Symbol.asyncIterator]`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator) | Allows the stream to be directly iterable in `for-await-of` loops. |
 | [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) | `values()` | An alias for `[Symbol.asyncIterator]` for explicit iteration. |
 
 ![ReadableStream.asyncIterator](https://caniuse.smokestack.workers.dev/?feature=api.ReadableStream.@@asyncIterator)
 ![ReadableStream.values](https://caniuse.smokestack.workers.dev/?feature=api.ReadableStream.values)
 
-### 2. Stream Construction Utility
+### Stream Construction Utility
 
 The library adds the static method for creating streams from existing data sources.
 
@@ -32,15 +42,15 @@ The library adds the static method for creating streams from existing data sourc
 
 ![ReadableStream.from](https://caniuse.smokestack.workers.dev/?feature=api.ReadableStream.from)
 
-### 3. Fetch and Body Integration Shims
+### Body and Bytes 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` | [`body`](https://developer.mozilla.org/en-US/docs/Web/API/Request/body) | 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` | [`body`](https://developer.mozilla.org/en-US/docs/Web/API/Response/body) | 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`](https://developer.mozilla.org/en-US/docs/Web/API/Request/bytes), [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response/bytes), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/bytes) | `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. |
+| [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/body) | [`body`](https://developer.mozilla.org/en-US/docs/Web/API/Request/body) | 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`](https://developer.mozilla.org/en-US/docs/Web/API/Response/body)  | [`body`](https://developer.mozilla.org/en-US/docs/Web/API/Response/body) | Provides the body content as a `ReadableStream`. |
+| [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/bytes), [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response/bytes), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/bytes) | [`bytes()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | Adds the `bytes()` method, which **asynchronously returns the object's body/content as a `Uint8Array`**. |
 
 ![Request.body](https://caniuse.smokestack.workers.dev/?feature=api.Request.body)
 ![Response.body](https://caniuse.smokestack.workers.dev/?feature=api.Response.body)
@@ -48,9 +58,9 @@ These shims ensure `Request` and `Response` objects (Records) consistently expos
 ![Response.bytes](https://caniuse.smokestack.workers.dev/?feature=api.Response.bytes)
 ![Blob.bytes](https://caniuse.smokestack.workers.dev/?feature=api.Blob.bytes)
 
-### 4. Duplex Compliance Shim
+### Duplex Compliance Shim
 
-To satisfy modern `fetch` specifications when streaming request bodies, the library ensures compliance for **half-duplex operations**.
+To satisfy modern `fetch` specifications when streaming request bodies, the library ensures compliance for **half-duplex operations**. This is in many ways a reverse shim as it allows legacy code to continue to work in the absence of a duplex parameter that did not exist when the code was implemented.
 
 *   **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 `duplex: 'half'` utility function to all arguments passed during instantiation.
@@ -58,12 +68,12 @@ To satisfy modern `fetch` specifications when streaming request bodies, the libr
 
 ![Request.duplex](https://caniuse.smokestack.workers.dev/?feature=api.Request.duplex)
 
-### 5. ReadableStreamDefaultReader Constructor Support
+### ReadableStreamDefaultReader Constructor Support
 
 The library adds support for the `ReadableStreamDefaultReader` constructor.
 
 | Target | Method/Property | Description |
 | :--- | :--- | :--- |
-| [`ReadableStreamDefaultReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader) | [`constructor(stream)`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/ReadableStream) | **Polyfills the `ReadableStreamDefaultReader` constructor** to accept a stream directly. In environments where the native constructor doesn't support this (like Bun), it delegates to `stream.getReader()` and properly sets up the prototype chain. This allows `new ReadableStreamDefaultReader(stream)` to work consistently across all runtimes. |
+| [`ReadableStreamDefaultReader`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader) | [`constructor(stream)`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader/ReadableStreamDefaultReader) | **Polyfills the `ReadableStreamDefaultReader` constructor** to accept a stream directly. In environments where the native constructor doesn't support this (like Bun), it delegates to `stream.getReader()` and properly sets up the prototype chain. This allows `new ReadableStreamDefaultReader(stream)` to work consistently across all runtimes. |
 
 ![ReadableStreamDefaultReader.constructor](https://caniuse.smokestack.workers.dev/?feature=api.ReadableStreamDefaultReader.constructor)

package/ReadableStreamBYOBReader.js

@@ -0,0 +1,175 @@
+(() => {
+  const Q = fn => {
+    try {
+      return fn?.()
+    } catch {}
+  };
+  const $global = Q(() => globalThis) ?? Q(() => global) ?? Q(() => self) ?? Q(() => window) ?? this;
+  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
+  - @returns {Function} The modified function
+  - @private
+    */
+  const setStrings = (obj) => {
+    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 assign = (target, source) => {
+    const props = Object.getOwnPropertyDescriptors(source);
+    for (const key in props) {
+      try {
+        Object.defineProperty(target, key, props[key]);
+      } catch (e) {
+        console.warn(e, key, props[key]);
+      }
+    }
+    for (const key in source) {
+      try {
+        target[key] ??= source[key];
+      } catch (e) {
+        console.warn(e, key, props[key]);
+      }
+    }
+    return target;
+  };
+  const cloneClass = $class => {
+    const clonePrototype = assign({}, $class.prototype);
+    const clone = $class.bind(clonePrototype);
+    assign(clone, $class);
+    clone.prototype = Object.setPrototypeOf(clonePrototype, Object.getPrototypeOf($class.prototype));
+    Object.setPrototypeOf(clone, Object.getPrototypeOf($class));
+    return clone;
+  };
+  if (!$global.ReadableStreamBYOBReader) {
+    $global.ReadableStreamBYOBReader ??= cloneClass(ReadableStreamDefaultReader);
+    Object.defineProperty(ReadableStreamBYOBReader, 'name', {
+      value: 'ReadableStreamBYOBReader',
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
+    setStrings(ReadableStreamBYOBReader);
+    const _getReader = ReadableStream.prototype.getReader;
+    ReadableStream.prototype.getReader = Object.setPrototypeOf(function getReader(options) {
+      const reader = _getReader.call(this);
+      if (options?.mode == 'byob') {
+        Object.setPrototypeOf(reader, ReadableStreamBYOBReader);
+      }
+      return reader;
+    }, _getReader);
+    extend(ReadableStreamBYOBReader, ReadableStreamDefaultReader);
+    const _read = ReadableStreamBYOBReader.prototype.read;
+    ReadableStreamBYOBReader.prototype.read = extend(setStrings(async function read(view) {
+      // If no view is provided, fall back to default behavior
+      if (!view) {
+        return _read.call(this,view);
+      }
+      // Read from the underlying stream (default reader behavior)
+      const result = await _read.call(this,view);
+      // If done, return with the view and done flag
+      if (result.done != false) {
+        return {
+          value: view,
+          done: true
+        };
+      }
+      // Convert the chunk to Uint8Array if needed
+      const chunk = result.value instanceof Uint8Array ? result.value : new Uint8Array(result.value);
+      // Determine how much data we can copy
+      const bytesToCopy = Math.min(chunk.byteLength, view.byteLength);
+      // Create a temporary view to copy into the provided view
+      const targetView = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+      // Copy the data into the provided buffer
+      targetView.set(chunk.subarray(0, bytesToCopy), 0);
+      // Create a view of the filled portion
+      const filledView = new view.constructor(view.buffer, view.byteOffset, bytesToCopy);
+      return {
+        value: filledView,
+        done: false
+      };
+    }), _read);
+  }
+  const supportsReadableStreamBYOBReaderConstructor = () => {
+    try {
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new Uint8Array([0]));
+          controller.close();
+        },
+        type: 'bytes'
+      });
+      const reader = new ReadableStreamBYOBReader(stream);
+      reader.read(new Uint8Array([0]));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (!supportsReadableStreamBYOBReaderConstructor()) {
+    const _ReadableStreamBYOBReader = $global.ReadableStreamBYOBReader;
+    const $ReadableStreamBYOBReader = function ReadableStreamBYOBReader(stream) {
+      return Object.setPrototypeOf(stream.getReader(), $global.ReadableStreamBYOBReader.prototype);
+    };
+    setStrings($ReadableStreamBYOBReader);
+    extend($ReadableStreamBYOBReader, _ReadableStreamBYOBReader);
+    $global.ReadableStreamBYOBReader = new Proxy($ReadableStreamBYOBReader, Object.setPrototypeOf({
+      construct: Object.setPrototypeOf(function construct(_, [stream]) {
+        return $ReadableStreamBYOBReader(stream);
+      }, $ReadableStreamBYOBReader.prototype)
+    }, $ReadableStreamBYOBReader));
+    $global.ReadableStreamBYOBReader.prototype.constructor = $global.ReadableStreamBYOBReader;
+  }
+})();

package/ReadableStreamDefaultReader-constructor.js

@@ -4,6 +4,7 @@
             return fn?.()
         } catch {}
     };
+    const $global = Q(()=>globalThis) ?? Q(()=>global) ?? Q(()=>self) ?? Q(()=>window) ?? this;
     const constructPrototype = newClass => {
         try {
             if (newClass?.prototype) return newClass;
@@ -92,18 +93,18 @@
 
 
     if (!supportsReadableStreamDefaultReaderConstructor()) {
-        const _ReadableStreamDefaultReader = globalThis.ReadableStreamDefaultReader;
+        const _ReadableStreamDefaultReader = $global.ReadableStreamDefaultReader;
         const $ReadableStreamDefaultReader = function ReadableStreamDefaultReader(stream) {
-            return Object.setPrototypeOf(stream.getReader(), globalThis.ReadableStreamDefaultReader.prototype);
+            return Object.setPrototypeOf(stream.getReader(), $global.ReadableStreamDefaultReader.prototype);
         };
         setStrings($ReadableStreamDefaultReader);
         extend($ReadableStreamDefaultReader, _ReadableStreamDefaultReader);
-        globalThis.ReadableStreamDefaultReader = new Proxy($ReadableStreamDefaultReader, Object.setPrototypeOf({
+        $global.ReadableStreamDefaultReader = new Proxy($ReadableStreamDefaultReader, Object.setPrototypeOf({
             construct:Object.setPrototypeOf(function construct(_, [stream]) {
                 return $ReadableStreamDefaultReader(stream)
             },$ReadableStreamDefaultReader.prototype)
         },$ReadableStreamDefaultReader));
-        globalThis.ReadableStreamDefaultReader.prototype.constructor = globalThis.ReadableStreamDefaultReader
+        $global.ReadableStreamDefaultReader.prototype.constructor = $global.ReadableStreamDefaultReader
     }
 
 })();

package/Record-duplex.js

@@ -89,7 +89,7 @@
     - Creates a new Request class that extends the original but processes arguments
       */
     (() => {
-        let $Request = Request;
+        const $Request = Request;
 
 
         /**
@@ -102,13 +102,13 @@
          *   body: new ReadableStream() 
          * }); // ReadableStream automatically gets duplex: 'half'
          */
-        $Request = class Request extends $Request {
+        const _Request = class Request extends $Request {
             constructor(...args) {
                 super(...args.map(duplexHalf));
             }
         };
 
-        $global.Request = $Request;
+        $global.Request = _Request;
 
 
     })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-streams-shim",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "",
   "main": "web-streams-core.js",
   "scripts": {

package/web-streams-core.js

@@ -739,7 +739,7 @@
         - Creates a new Request class that extends the original but processes arguments
           */
         (() => {
-            let $Request = Request;
+            const $Request = Request;
 
 
             /**
@@ -752,13 +752,13 @@
              *   body: new ReadableStream() 
              * }); // ReadableStream automatically gets duplex: 'half'
              */
-            $Request = class Request extends $Request {
+            const _Request = class Request extends $Request {
                 constructor(...args) {
                     super(...args.map(duplexHalf));
                 }
             };
 
-            $global.Request = $Request;
+            $global.Request = _Request;
 
 
         })();