{"id":11442,"library":"node-readable-to-web-readable-stream","title":"Node.js Readable to Web ReadableStream Conversion Utility","description":"node-readable-to-web-readable-stream is a focused utility library designed to bridge the gap between Node.js `stream.Readable` and the Web API `ReadableStream`. It provides functions to convert Node.js readable streams into either byte-mode (BYOB-compliant) or default-mode WHATWG ReadableStreams, enabling seamless integration with web-native streaming APIs. The current stable version is `0.4.2`, with releases occurring relatively frequently to address bug fixes and introduce enhancements, such as improved backpressure mechanisms and default stream support. Key differentiators include its explicit support for BYOB readers, robust backpressure handling, and cross-platform compatibility across Node.js (>=18), Bun (>=1.2), and modern web browsers. It is distributed as an ECMAScript Module (ESM).","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/Borewit/node-readable-to-web-readable-stream","tags":["javascript","Readable","Stream","Node.js","Node","ReadableStream","convert","WHATWG","BYOB","typescript"],"install":[{"cmd":"npm install node-readable-to-web-readable-stream","lang":"bash","label":"npm"},{"cmd":"yarn add node-readable-to-web-readable-stream","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-readable-to-web-readable-stream","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily an ESM. CommonJS `require()` is only officially supported for Node.js >= 22.","wrong":"const makeByteReadableStreamFromNodeReadable = require('node-readable-to-web-readable-stream').makeByteReadableStreamFromNodeReadable;","symbol":"makeByteReadableStreamFromNodeReadable","correct":"import { makeByteReadableStreamFromNodeReadable } from 'node-readable-to-web-readable-stream';"},{"note":"Added in v0.4.0. For converting to a default-mode Web ReadableStream, often used with ReadableStreamDefaultReader.","wrong":"const { makeDefaultReadableStreamFromNodeReadable } = require('node-readable-to-web-readable-stream');","symbol":"makeDefaultReadableStreamFromNodeReadable","correct":"import { makeDefaultReadableStreamFromNodeReadable } from 'node-readable-to-web-readable-stream';"},{"note":"A general conversion function documented in the API. The `makeByteReadableStreamFromNodeReadable` and `makeDefaultReadableStreamFromNodeReadable` functions are generally preferred for explicit stream type conversion.","wrong":"const toWebReadableStream = require('node-readable-to-web-readable-stream').toWebReadableStream;","symbol":"toWebReadableStream","correct":"import { toWebReadableStream } from 'node-readable-to-web-readable-stream';"},{"note":"When providing a Node.js Readable stream, import its type from `node:stream` for type safety.","symbol":"NodeJS.ReadableStream","correct":"import type { Readable } from 'node:stream';"}],"quickstart":{"code":"import { createReadStream } from 'node:fs';\nimport { makeByteReadableStreamFromNodeReadable } from 'node-readable-to-web-readable-stream';\n\n// Imagine 'large-file.bin' is a large binary file\n// Create a Node.js Readable stream\nconst nodeReadable = createReadStream('large-file.bin');\n\n// Convert to a web ReadableStream, specifically a byte stream for BYOB support\nconst webReadable = makeByteReadableStreamFromNodeReadable(nodeReadable);\n\n// Example: Consume the webReadable using a BYOB reader\nasync function readStream(stream: ReadableStream<Uint8Array>) {\n  const reader = stream.getReader({ mode: 'byob' });\n  try {\n    while (true) {\n      const { value, done } = await reader.read(new Uint8Array(1024)); // Read into a pre-allocated buffer\n      if (done) {\n        console.log('Stream finished.');\n        break;\n      }\n      if (value) {\n        console.log(`Read ${value.byteLength} bytes.`);\n        // Process the chunk here\n      }\n    }\n  } catch (error) {\n    console.error('Error reading stream:', error);\n  } finally {\n    reader.releaseLock();\n  }\n}\n\n// In a real application, you'd ensure 'large-file.bin' exists or create it.\n// For demonstration, we'll create a dummy file if it doesn't exist.\nimport { promises as fsPromises } from 'node:fs';\nasync function setupAndRun() {\n  try {\n    await fsPromises.access('large-file.bin');\n  } catch (error) {\n    await fsPromises.writeFile('large-file.bin', Buffer.alloc(1024 * 1024, 'A')); // 1MB dummy file\n    console.log('Created dummy large-file.bin');\n  }\n  readStream(webReadable);\n}\nsetupAndRun();","lang":"typescript","description":"Demonstrates converting a Node.js `fs.createReadStream` into a Web API `ReadableStream` (byte mode) and consuming it with a BYOB reader."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<=21.x"},{"fix":"Upgrade to version `0.4.1` or newer to resolve stream hanging issues. The fix was applied in v0.4.1.","message":"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.","severity":"gotcha","affected_versions":"<0.4.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: makeByteReadableStreamFromNodeReadable is not a function"},{"fix":"Upgrade the package to version `0.4.1` or newer. This version specifically addressed issues causing converted byte ReadableStreams to hang.","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.","error":"Web ReadableStream stops emitting data unexpectedly or seems to freeze."}],"ecosystem":"npm"}