Node.js Readable to Web ReadableStream Conversion Utility

Common errors

• TypeError: makeByteReadableStreamFromNodeReadable is not a function

  cause Attempting to `require()` the module in a Node.js version older than 22, or in a CommonJS context where ESM imports are not correctly transpiled or handled.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import { makeByteReadableStreamFromNodeReadable } from 'node-readable-to-web-readable-stream';`. If using Node.js < 22, you cannot reliably use `require()` for this package.

• Web ReadableStream stops emitting data unexpectedly or seems to freeze.

  cause This is often a symptom of the stream hanging bug fixed in earlier versions, where the converted stream would not properly signal completion or handle cancellation.
  fix Upgrade the package to version `0.4.1` or newer. This version specifically addressed issues causing converted byte ReadableStreams to hang.

Warnings

• gotcha This package is an ECMAScript Module (ESM). While it can be loaded with `require()` in Node.js, this functionality is officially supported only for Node.js versions 22 and higher. For older Node.js versions or mixed CJS/ESM projects, direct `import` statements are required.
  Fix: Use `import` statements: `import { ... } from 'node-readable-to-web-readable-stream';` or ensure your project's `package.json` specifies `"type": "module"` and uses Node.js >= 22 for `require()` interoperability.
• gotcha Versions prior to `0.4.1` contained a bug that could cause the converted byte `ReadableStream` to hang, especially when reading the remainder of the stream or after cancellation.
  Fix: Upgrade to version `0.4.1` or newer to resolve stream hanging issues. The fix was applied in v0.4.1.
• gotcha The documentation for the general `toWebReadableStream` function exists, but the primary usage examples and recent enhancements (like `makeDefaultReadableStreamFromNodeReadable` in v0.4.0) heavily emphasize the more explicit `makeByteReadableStreamFromNodeReadable` and `makeDefaultReadableStreamFromNodeReadable` functions. Relying on the `make*` functions provides clearer intent.
  Fix: Prefer `makeByteReadableStreamFromNodeReadable` for BYOB-compatible byte streams or `makeDefaultReadableStreamFromNodeReadable` for default-mode streams, as these are the idiomatic and most actively developed conversion paths.

Install

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

Imports

• makeByteReadableStreamFromNodeReadable
  wrong:

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

  correct:

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

  This package is primarily an ESM. CommonJS `require()` is only officially supported for Node.js >= 22.
• makeDefaultReadableStreamFromNodeReadable
  wrong:

  const { makeDefaultReadableStreamFromNodeReadable } = require('node-readable-to-web-readable-stream');

  correct:

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

  Added in v0.4.0. For converting to a default-mode Web ReadableStream, often used with ReadableStreamDefaultReader.
• toWebReadableStream
  wrong:

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

  correct:

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

  A general conversion function documented in the API. The `makeByteReadableStreamFromNodeReadable` and `makeDefaultReadableStreamFromNodeReadable` functions are generally preferred for explicit stream type conversion.
• NodeJS.ReadableStream

  import type { Readable } from 'node:stream';

  When providing a Node.js Readable stream, import its type from `node:stream` for type safety.

Quickstart

Demonstrates converting a Node.js `fs.createReadStream` into a Web API `ReadableStream` (byte mode) and consuming it with a BYOB reader.

import { createReadStream } from 'node:fs';
import { makeByteReadableStreamFromNodeReadable } from 'node-readable-to-web-readable-stream';

// Imagine 'large-file.bin' is a large binary file
// Create a Node.js Readable stream
const nodeReadable = createReadStream('large-file.bin');

// Convert to a web ReadableStream, specifically a byte stream for BYOB support
const webReadable = makeByteReadableStreamFromNodeReadable(nodeReadable);

// Example: Consume the webReadable using a BYOB reader
async function readStream(stream: ReadableStream<Uint8Array>) {
  const reader = stream.getReader({ mode: 'byob' });
  try {
    while (true) {
      const { value, done } = await reader.read(new Uint8Array(1024)); // Read into a pre-allocated buffer
      if (done) {
        console.log('Stream finished.');
        break;
      }
      if (value) {
        console.log(`Read ${value.byteLength} bytes.`);
        // Process the chunk here
      }
    }
  } catch (error) {
    console.error('Error reading stream:', error);
  } finally {
    reader.releaseLock();
  }
}

// In a real application, you'd ensure 'large-file.bin' exists or create it.
// For demonstration, we'll create a dummy file if it doesn't exist.
import { promises as fsPromises } from 'node:fs';
async function setupAndRun() {
  try {
    await fsPromises.access('large-file.bin');
  } catch (error) {
    await fsPromises.writeFile('large-file.bin', Buffer.alloc(1024 * 1024, 'A')); // 1MB dummy file
    console.log('Created dummy large-file.bin');
  }
  readStream(webReadable);
}
setupAndRun();