{"id":16272,"library":"web-stream-tools","title":"Web Stream Tools","description":"Web Stream Tools (available as `@openpgp/web-stream-tools` on npm) is a JavaScript utility library designed to simplify working with WhatWG Streams. It provides a comprehensive set of functions for common stream operations, including reading to completion (`readToEnd`), concatenating streams (`concat`), slicing parts of streams (`slice`), cloning streams (`clone`), and facilitating conversion between Node.js streams and Web Streams (`webToNode`, `nodeToWeb`). The library also features advanced capabilities for transforming stream data, either directly (`transform`) or in chunks with backpressure handling (`transformPair`), and for parsing structured data from streams (`parse`) with functions like `readByte`, `readBytes`, and `readLine`. The current stable version is 0.3.0. Developed by the OpenPGP.js team, it maintains an active development status, with updates generally released as needed. A key differentiator is its explicit focus on the WhatWG Streams API, providing a consistent interface across browser and modern Node.js environments, streamlining complex stream manipulations that often involve manual reader/writer management.","status":"active","version":"0.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/openpgpjs/streams","tags":["javascript"],"install":[{"cmd":"npm install web-stream-tools","lang":"bash","label":"npm"},{"cmd":"yarn add web-stream-tools","lang":"bash","label":"yarn"},{"cmd":"pnpm add web-stream-tools","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library's official package name is `@openpgp/web-stream-tools`. Older references or custom build configurations might use `web-stream-tools` which will result in import errors or `undefined` imports. The primary export pattern is a namespace import (`* as stream`).","wrong":"import stream from 'web-stream-tools';","symbol":"* as stream","correct":"import * as stream from '@openpgp/web-stream-tools';"},{"note":"Individual functions can be tree-shaken and imported directly. Ensure the correct package name `@openpgp/web-stream-tools` is used.","wrong":"import { transform } from 'web-stream-tools';","symbol":"transform","correct":"import { transform } from '@openpgp/web-stream-tools';"},{"note":"While Node.js may support CommonJS `require` for ESM packages via interoperability layers, the library is designed for modern ESM usage. Prefer `import` statements for better compatibility and tooling support.","wrong":"const { readToEnd } = require('@openpgp/web-stream-tools');","symbol":"readToEnd","correct":"import { readToEnd } from '@openpgp/web-stream-tools';"}],"quickstart":{"code":"import * as stream from '@openpgp/web-stream-tools';\n\n// Imagine an encryptor API with process and finish methods\nclass Encryptor {\n  process(chunk) {\n    console.log('Processing chunk:', chunk.byteLength, 'bytes');\n    // Simulate encryption, return a new Uint8Array\n    return new Uint8Array(chunk.map(b => b ^ 0xFF));\n  }\n  finish() {\n    console.log('Finishing encryption.');\n    // Return any final encrypted bytes, or an empty Uint8Array\n    return new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]);\n  }\n}\n\nasync function encryptDataStream() {\n  const encryptor = new new Encryptor();\n  const inputData = new TextEncoder().encode(\"This is a test string to be encrypted using web-stream-tools.\");\n  \n  // Create a ReadableStream from the input data\n  const input = new ReadableStream({\n    start(controller) {\n      controller.enqueue(inputData);\n      controller.close();\n    }\n  });\n\n  const encryptedStream = stream.transform(input, function process(chunk) {\n    return encryptor.process(chunk);\n  }, function finish() {\n    return encryptor.finish();\n  });\n\n  // Read the encrypted stream to the end and collect all chunks\n  const reader = encryptedStream.getReader();\n  let allChunks = [];\n  while (true) {\n    const { done, value } = await reader.read();\n    if (done) {\n      break;\n    }\n    allChunks.push(value);\n  }\n  const finalEncryptedData = new Uint8Array(allChunks.reduce((acc, chunk) => acc.concat(Array.from(chunk)), []));\n  console.log('Total encrypted data length:', finalEncryptedData.byteLength, 'bytes');\n  console.log('Encryption complete.');\n}\n\nencryptDataStream().catch(console.error);","lang":"typescript","description":"This example demonstrates how to use the `stream.transform` function to encrypt data flowing through a WhatWG ReadableStream, including setup for an imaginary encryptor and reading the output."},"warnings":[{"fix":"Update your `package.json` dependencies and all import statements in your code from `web-stream-tools` to `@openpgp/web-stream-tools`.","message":"The official package name for Web Stream Tools has been changed from `web-stream-tools` to `@openpgp/web-stream-tools`. Direct imports using the old package name will result in `Module not found` errors or `undefined` imports.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"For Node.js environments, ensure you are using Node.js v17+ which provides built-in utilities like `Readable.toWeb()` for converting native Node streams to Web Streams, or `Readable.fromWeb()` for the reverse. Alternatively, transform your data into `Uint8Array` or `String` before passing to functions like `transform` if stream-to-stream conversion is not feasible.","message":"As of v0.1.0, the library no longer supports native Node.js `Readable` or `Writable` streams directly as input or output for many functions. It now exclusively expects and operates on WhatWG `ReadableStream` and `WritableStream` instances (often referred to as Node's WebStreams in modern Node.js).","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Always prefer `import * as stream from '@openpgp/web-stream-tools';` or named imports in ES Modules. If CommonJS is strictly required, ensure your build tool (e.g., Webpack, Rollup) or Node.js configuration (e.g., `\"type\": \"module\"` in `package.json`) handles ESM to CJS interoperability correctly.","message":"Attempting to use CommonJS `require()` syntax with `@openpgp/web-stream-tools` might not work as expected or could lead to bundling issues. The library is primarily designed for ES Module (`import`) usage with Web Streams, especially given its browser-compatibility focus.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change the dependency in `package.json` and all import paths in your code to `@openpgp/web-stream-tools`.","cause":"The package name has changed from 'web-stream-tools' to '@openpgp/web-stream-tools'.","error":"Error: Cannot find module 'web-stream-tools'"},{"fix":"Ensure you are using `import * as stream from '@openpgp/web-stream-tools';` (for namespace import) or `import { transform } from '@openpgp/web-stream-tools';` (for named import).","cause":"Incorrect import statement or module not found, leading to 'stream' being undefined or an empty object.","error":"TypeError: stream.transform is not a function"},{"fix":"If in Node.js v17+, convert your Node stream using `myNodeStream.toWeb()` before passing it to `web-stream-tools` functions. For older Node.js versions, you may need to manually wrap the Node stream or use a polyfill.","cause":"You are passing a native Node.js `stream.Readable` object to a function that expects a WhatWG `ReadableStream`.","error":"Error: The provided stream is not a WhatWG ReadableStream."}],"ecosystem":"npm"}