# patrick-ring-motive/web-streams-shim architecture

> Architecture diagram of the GitHub repository patrick-ring-motive/web-streams-shim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patrick-ring-motive/web-streams-shim
- Repository: https://github.com/patrick-ring-motive/web-streams-shim

## Overview

1. **What this repo is**
   - `web-streams-shim` is a JavaScript shim library that patches modern Web Streams / Fetch-related APIs when they exist but are incomplete.
   - It is explicitly **not** a full polyfill for missing globals; the boundary is “extend existing runtime APIs,” not “create APIs from scratch.”

2. **Primary runtime surface**
   - The main delivery artifact is `web-streams-core.js`, which is the script consumers load directly in browsers or via dynamic import.
   - The package also ships `.d.ts` files for TypeScript consumers, so the public surface is both runtime behavior and typing augmentation.

3. **Core architecture: feature-by-feature shims**
   - The codebase is organized as small, targeted modules rather than one monolithic patch layer.
   - Each top-level file corresponds to a specific compatibility concern:
     - `ReadableStream-asyncIterator.js`
     - `ReadableStream-from.js`
     - `ReadableStreamBYOBReader.js`
     - `ReadableStreamDefaultReader-constructor.js`
     - `Record-body.js`
     - `Record-bytes.js`
     - `Record-duplex.js`
   - This suggests the architecture is “install only the missing pieces,” with each shim independently feature-detecting before applying changes.

4. **ReadableStream subsystem**
   - One major subsystem is `ReadableStream` compatibility.
   - It covers:
     - async iteration support (`[Symbol.asyncIterator]` / `values()`)
     - `ReadableStream.from(...)`
     - `ReadableStreamDefaultReader` constructor behavior
     - BYOB reader-related support
   - This subsystem is centered on making stream consumption patterns behave consistently across runtimes.

5. **Fetch body subsystem**
   - Another subsystem patches body-related behavior for `Request` and `Response`.
   - Files under `Record-body.js` and `Record-bytes.js` indicate consistent stream-backed body access and byte extraction.
   - The architectural flow is from platform object (`Request`/`Response`) to normalized body access (`body`, `bytes()`), keeping body handling aligned across implementations.

6. **Duplex compliance subsystem**
   - `Record-duplex.js` addresses the fetch “half-duplex” requirement when streaming request bodies are used.
   - The README describes three places this is applied:
     - property injection onto relevant prototypes
     - constructor wrapping for `Request` and `Response`
     - `fetch` wrapping to ensure options are normalized before execution
   - This is the main “behavioral compatibility” layer because it alters call flow, not just surface APIs.

7. **Extension layer**
   - The `extensions/` directory is a second boundary: optional API/type extensions beyond the core shim.
   - It includes:
     - `web-streams-extensions.js`
     - `web-streams-extensions.d.ts`
     - `type-extensions.js`
     - `file.js`
     - `location.js`
     - stream-record helpers
   - This looks like a separate augmentation layer for environment-specific or convenience APIs, kept distinct from the core compatibility shims.

8. **Type system boundary**
   - The presence of both `.js` and `.d.ts` files in the root and `extensions/` shows the repo treats runtime patching and static typing as parallel concerns.
   - `web-streams-core.d.ts` and `extensions/web-streams-extensions.d.ts` are likely used to make the global augmentations visible to TypeScript without changing runtime semantics.

9. **Test architecture**
   - Tests live in `test/test.html` and `test/test.js`, which suggests browser-based integration testing rather than unit tests in a Node-only harness.
   - That fits the repo’s purpose: verifying global API patching in a real web runtime where `ReadableStream`, `fetch`, `Request`, and `Response` behavior matters.

10. **Distribution and release flow**
   - The GitHub Actions workflow `.github/workflows/npm_publish.yml` indicates automated package publishing to npm.
   - This means the repo is packaged as a distributable library, with CI likely responsible for release integrity rather than deploying an app or service.

11. **Operational model**
   - The library is fundamentally side-effect driven: load a script, detect missing behavior, patch globals, and leave native behavior untouched when already compliant.
   - That makes the main dependency boundary the host runtime itself; the shim adapts to the environment instead of introducing its own app-level state.

12. **How to draw the architecture**
   - A good diagram would show:
     - host runtime globals on the left (`ReadableStream`, `Request`, `Response`, `Blob`, `fetch`)
     - the shim package in the middle, split into feature modules
     - optional extensions as a separate layer
     - TypeScript declarations alongside runtime modules
     - browser tests and npm publish as supporting delivery paths
   - The key data flow is not request/response business logic, but API calls passing through patched constructors/methods and then delegating back to native implementations when possible.

Main entry points: [`web-streams-core.js`](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/web-streams-core.js) (Core entry), [`extensions/web-streams-extensions.js`](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/web-streams-extensions.js) (Extensions entry), [`Record-duplex.js`](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-duplex.js) (Duplex record), [`Record-body.js`](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-body.js) (Body record)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host runtime"]
  node_host_readable_stream["ReadableStream<br/>platform API"]
  node_host_request["Request<br/>platform API"]
  node_host_response["Response<br/>platform API"]
  node_host_fetch["fetch<br/>platform API"]
end

subgraph group_core["Core shims"]
  node_core_entry["Core entry<br/>runtime loader"]
  node_core_async_iter["Async iter<br/>ReadableStream shim"]
  node_core_from["Stream from<br/>ReadableStream shim"]
  node_core_byob["BYOB reader<br/>ReadableStream shim"]
  node_core_default_reader["Default reader<br/>ReadableStream shim"]
  node_core_body["Body record<br/>fetch body shim<br/>[Record-body.js]"]
  node_core_bytes["Bytes record<br/>fetch body shim<br/>[Record-bytes.js]"]
  node_core_duplex["Duplex record<br/>fetch shim<br/>[Record-duplex.js]"]
end

subgraph group_extensions["Extensions"]
  node_ext_bundle["Extensions entry<br/>extension bundle"]
  node_ext_type["Type extensions<br/>augmentation<br/>[type-extensions.js]"]
  node_ext_file["File helpers<br/>extension<br/>[file.js]"]
  node_ext_location["Location helpers<br/>extension<br/>[location.js]"]
  node_ext_records["Stream records<br/>extension<br/>[Record-stream.js]"]
end

subgraph group_delivery["Delivery"]
  node_types_core["Core types<br/>d.ts"]
  node_types_ext["Ext types<br/>d.ts"]
  node_test_browser["Browser tests<br/>integration tests<br/>[test.html]"]
  node_test_script["Test script<br/>integration tests<br/>[test.js]"]
  node_publish_ci["Publish CI<br/>release workflow<br/>[npm_publish.yml]"]
end

node_core_entry -->|"loads"| node_core_async_iter
node_core_entry -->|"loads"| node_core_from
node_core_entry -->|"loads"| node_core_byob
node_core_entry -->|"loads"| node_core_default_reader
node_core_entry -->|"loads"| node_core_body
node_core_entry -->|"loads"| node_core_bytes
node_core_entry -->|"loads"| node_core_duplex
node_core_async_iter -->|"patches"| node_host_readable_stream
node_core_from -->|"patches"| node_host_readable_stream
node_core_byob -->|"patches"| node_host_readable_stream
node_core_default_reader -->|"patches"| node_host_readable_stream
node_core_body -->|"patches"| node_host_request
node_core_body -->|"patches"| node_host_response
node_core_bytes -->|"patches"| node_host_request
node_core_bytes -->|"patches"| node_host_response
node_core_duplex -->|"wraps"| node_host_request
node_core_duplex -->|"wraps"| node_host_response
node_core_duplex -->|"wraps"| node_host_fetch
node_ext_bundle -->|"includes"| node_ext_type
node_ext_bundle -->|"includes"| node_ext_file
node_ext_bundle -->|"includes"| node_ext_location
node_ext_bundle -->|"includes"| node_ext_records
node_types_core -.->|"types"| node_core_entry
node_types_ext -.->|"types"| node_ext_bundle
node_test_browser -->|"loads"| node_test_script
node_test_script -.->|"verifies"| node_core_entry
node_publish_ci -.->|"packages"| node_core_entry
node_publish_ci -.->|"packages"| node_ext_bundle

click node_core_entry "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/web-streams-core.js"
click node_core_async_iter "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStream-asyncIterator.js"
click node_core_from "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStream-from.js"
click node_core_byob "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStreamBYOBReader.js"
click node_core_default_reader "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStreamDefaultReader-constructor.js"
click node_core_body "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-body.js"
click node_core_bytes "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-bytes.js"
click node_core_duplex "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-duplex.js"
click node_ext_bundle "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/web-streams-extensions.js"
click node_ext_type "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/type-extensions.js"
click node_ext_file "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/file.js"
click node_ext_location "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/location.js"
click node_ext_records "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/Record-stream.js"
click node_types_core "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/web-streams-core.d.ts"
click node_types_ext "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/web-streams-extensions.d.ts"
click node_test_browser "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/test/test.html"
click node_test_script "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/test/test.js"
click node_publish_ci "https://github.com/patrick-ring-motive/web-streams-shim/blob/main/.github/workflows/npm_publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_readable_stream,node_host_request,node_host_response,node_host_fetch toneBlue
class node_core_entry,node_core_async_iter,node_core_from,node_core_byob,node_core_default_reader,node_core_body,node_core_bytes,node_core_duplex toneAmber
class node_ext_bundle,node_ext_type,node_ext_file,node_ext_location,node_ext_records toneMint
class node_types_core,node_types_ext,node_test_browser,node_test_script,node_publish_ci toneRose
```

## Components

### Host runtime

Existing platform APIs the shim patches and then delegates back to when compliant.

- **ReadableStream**: platform API · Stream primitives and consumption behavior provided by the host runtime.
- **Request**: platform API · Fetch request surface patched for body and duplex behavior.
- **Response**: platform API · Fetch response surface patched for body and byte access behavior.
- **fetch**: platform API · Network entrypoint wrapped to normalize duplex-related options.

### Core shims

Primary compatibility modules loaded by the main runtime entrypoint.

- [Core entry](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/web-streams-core.js): runtime loader · Main script consumers load to install feature patches in the current runtime. · `web-streams-core.js`
- [Async iter](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStream-asyncIterator.js): ReadableStream shim · Adds async iteration and values() support to ReadableStream. · `ReadableStream-asyncIterator.js`
- [Stream from](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStream-from.js): ReadableStream shim · Adds ReadableStream.from() support. · `ReadableStream-from.js`
- [BYOB reader](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStreamBYOBReader.js): ReadableStream shim · Adds or repairs BYOB reader behavior. · `ReadableStreamBYOBReader.js`
- [Default reader](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/ReadableStreamDefaultReader-constructor.js): ReadableStream shim · Adjusts ReadableStreamDefaultReader constructor behavior. · `ReadableStreamDefaultReader-constructor.js`
- [Body record](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-body.js): fetch body shim · Normalizes Request and Response body access. · `Record-body.js`
- [Bytes record](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-bytes.js): fetch body shim · Adds consistent byte extraction behavior for body-backed objects. · `Record-bytes.js`
- [Duplex record](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/Record-duplex.js): fetch shim · Implements half-duplex request handling and fetch option normalization. · `Record-duplex.js`

### Extensions

Optional augmentations beyond the core compatibility surface.

- [Extensions entry](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/web-streams-extensions.js): extension bundle · Optional API and typing extensions separated from the core shims. · `extensions/web-streams-extensions.js`
- [Type extensions](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/type-extensions.js): augmentation · Additional type/runtime extension support for optional APIs. · `extensions/type-extensions.js`
- [File helpers](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/file.js): extension · Environment-specific file-related extension surface. · `extensions/file.js`
- [Location helpers](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/location.js): extension · Environment-specific location-related extension surface. · `extensions/location.js`
- [Stream records](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/Record-stream.js): extension · Helper modules for record/stream extension behavior. · `extensions/Record-stream.js`

### Delivery

Type declarations, tests, and publishing automation.

- [Core types](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/web-streams-core.d.ts): d.ts · TypeScript declarations for the core runtime shim. · `web-streams-core.d.ts`
- [Ext types](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/extensions/web-streams-extensions.d.ts): d.ts · TypeScript declarations for optional extensions. · `extensions/web-streams-extensions.d.ts`
- [Browser tests](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/test/test.html): integration tests · Browser-based verification of global API patching. · `test/test.html`
- [Test script](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/test/test.js): integration tests · Test harness executed in a browser runtime. · `test/test.js`
- [Publish CI](https://github.com/patrick-ring-motive/web-streams-shim/blob/main/.github/workflows/npm_publish.yml): release workflow · Automated npm publication workflow. · `.github/workflows/npm_publish.yml`

## Connections

- Core entry → Async iter: loads · Main entry installs the feature-specific shim module.
- Core entry → Stream from: loads · Main entry installs the feature-specific shim module.
- Core entry → BYOB reader: loads · Main entry installs the feature-specific shim module.
- Core entry → Default reader: loads · Main entry installs the feature-specific shim module.
- Core entry → Body record: loads · Main entry installs the feature-specific shim module.
- Core entry → Bytes record: loads · Main entry installs the feature-specific shim module.
- Core entry → Duplex record: loads · Main entry installs the feature-specific shim module.
- Async iter → ReadableStream: patches · Extends ReadableStream with async iteration behavior.
- Stream from → ReadableStream: patches · Adds ReadableStream.from() to the host implementation.
- BYOB reader → ReadableStream: patches · Repairs BYOB reader-related stream behavior.
- Default reader → ReadableStream: patches · Adjusts default reader construction against host behavior.
- Body record → Request: patches · Normalizes body access on Request objects.
- Body record → Response: patches · Normalizes body access on Response objects.
- Bytes record → Request: patches · Adds consistent bytes extraction for Request bodies.
- Bytes record → Response: patches · Adds consistent bytes extraction for Response bodies.
- Duplex record → Request: wraps · Injects duplex-related request behavior.
- Duplex record → Response: wraps · Keeps response construction aligned with duplex handling.
- Duplex record → fetch: wraps · Normalizes fetch options before execution.
- Extensions entry → Type extensions: includes · Optional runtime extension package ships with its augmentation layer.
- Extensions entry → File helpers: includes · Optional runtime extension package ships file helpers.
- Extensions entry → Location helpers: includes · Optional runtime extension package ships location helpers.
- Extensions entry → Stream records: includes · Optional runtime extension package ships stream record helpers.
- Core types → Core entry: types · Type declarations mirror the core runtime surface.
- Ext types → Extensions entry: types · Type declarations mirror the optional extension surface.
- Browser tests → Test script: loads · Browser test page executes the test harness.
- Test script → Core entry: verifies · Tests exercise the main shim entrypoint in a real browser runtime.
- Publish CI → Core entry: packages · Release workflow publishes the distributable core artifact.
- Publish CI → Extensions entry: packages · Release workflow packages optional extensions as part of the release.