Web ReadableStream to Node.js Readable Stream Converter

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... is not supported. Instead change the require of index.js in ... to a dynamic import() call.

  cause Attempting to import the `readable-web-to-node-stream` package (which is pure ESM since v4.0.0) using CommonJS `require()` syntax in a Node.js environment older than v22 or without explicit ESM configuration.
  fix Replace `const { ReadableWebToNodeStream } = require('readable-web-to-node-stream');` with `import { ReadableWebToNodeStream } from 'readable-web-to-node-stream';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) or upgrade to Node.js v22+ if you need CJS compatibility with ESM packages.

• ReferenceError: ReadableStream is not defined

  cause The Web-API `ReadableStream` class is not available in the global scope where the code is executed. This typically happens in a pure Node.js environment without a browser-like global `fetch` API or a polyfill for web streams.
  fix Ensure you are running in a browser environment or in a Node.js environment where a global `fetch` API (which commonly provides `ReadableStream` on its response bodies) is available or explicitly polyfilled. For Node.js < 18, or if `fetch` is not globally available, you might need to use a package like `node-fetch` and/or `web-streams-polyfill`.

Warnings

• breaking The package migrated to a pure ECMAScript Module (ESM) in version 4.0.0. CommonJS `require()` is no longer directly supported in Node.js versions below 22, requiring changes to import statements.
  Fix: Update all CommonJS `require()` statements to ESM `import` statements. For older Node.js versions, consider using dynamic `import()` or migrating your project to ESM. Node.js >= 22 provides experimental CJS compatibility for ESM packages.
• breaking The constructor option `propagateDestroy` was introduced in v5.0.0. Its default value is `false`. If set to `true`, destroying the Node.js stream will also cancel the underlying Web-API `ReadableStream`.
  Fix: Explicitly set `{ propagateDestroy: true }` in the `ReadableWebToNodeStream` constructor options if you want the Node.js stream's `destroy` method to also cancel the source Web-API stream, matching behavior of some previous stream implementations or expectations.
• gotcha The Node.js engine requirement was updated to `>= 18` starting from version 4.0.0. This package will not run on older Node.js versions.
  Fix: Upgrade your Node.js environment to version 18 or higher to use versions 4.0.0 and above of this package.
• gotcha Multiple security vulnerabilities were addressed in dependencies (e.g., elliptic, y18n, ssri, lodash) in version 3.0.2. Older versions `<=3.0.1` may contain known vulnerabilities.
  Fix: Upgrade to version 3.0.2 or higher to patch known security vulnerabilities in your project's dependency tree.

Install

• npm install readable-web-to-node-stream npm
• yarn add readable-web-to-node-stream yarn
• pnpm add readable-web-to-node-stream pnpm

Imports

• ReadableWebToNodeStream
  wrong:

  const ReadableWebToNodeStream = require('readable-web-to-node-stream');

  correct:

  import { ReadableWebToNodeStream } from 'readable-web-to-node-stream';

  Since v4.0.0, the package is pure ESM. Use 'import' syntax. CommonJS 'require()' is only compatible in Node.js >= 22 or with specific loader configurations. Prior to v4, `require` was the standard.
• ReadableWebToNodeStream (Type)

  import type { ReadableWebToNodeStream } from 'readable-web-to-node-stream';

  For TypeScript, use 'import type' for the class constructor if you only need the type definition without bundling the runtime implementation. This is often an optimization, though `ReadableWebToNodeStream` is typically instantiated at runtime.
• All exports (namespace import)
  wrong:

  import WebToNodeStream from 'readable-web-to-node-stream';

  correct:

  import * as WebToNodeStream from 'readable-web-to-node-stream';

  Imports all named exports (in this case, primarily `ReadableWebToNodeStream`) into a namespace object. The package does not provide a default export, so attempting to use a default import will fail.

Quickstart

Demonstrates converting a `fetch` response's Web-API ReadableStream into a Node.js Readable stream and piping it to a file, including error handling.

import { ReadableWebToNodeStream } from 'readable-web-to-node-stream';
import { createWriteStream } from 'fs';
import { pipeline } from 'stream/promises';

async function downloadAndSave(url: string, filePath: string) {
    console.log(`Downloading ${url} and saving to ${filePath}`);
    // Ensure 'fetch' is available (global in browsers, or polyfilled/imported in Node.js < 18 or for specific use cases)
    const response = await fetch(url);
    if (!response.body) {
        throw new Error('Response body is null. Cannot convert an empty body.');
    }
    const webReadableStream = response.body;
    
    // Convert the Web-API ReadableStream to a Node.js Readable stream
    const nodeStream = new ReadableWebToNodeStream(webReadableStream, { propagateDestroy: true });

    // Pipe the Node.js stream to a file using stream.pipeline for robust error handling and cleanup
    await pipeline(
        nodeStream,
        createWriteStream(filePath)
    );
    console.log(`Download complete: ${filePath}`);
}

// Example usage: Downloads a small dummy file from a public URL
// Replace with a suitable URL for actual testing. For local testing, a simple text file is good.
const exampleUrl = 'https://raw.githubusercontent.com/Borewit/readable-web-to-node-stream/master/package.json';
const outputFilePath = './downloaded-package.json';

downloadAndSave(exampleUrl, outputFilePath)
    .catch(error => console.error('An error occurred during download:', error));