{"_id":"web-stream-tools","_rev":"4176669","name":"web-stream-tools","description":"Utility functions for WhatWG Streams","dist-tags":{"latest":"0.0.1"},"maintainers":[{"name":"sunnyrajan","email":""}],"time":{"modified":"2026-03-01T21:35:20.000Z","created":"2018-07-25T13:54:26.140Z","0.0.1":"2018-07-25T13:54:26.140Z"},"users":{},"author":{"name":"Daniel Huigens","email":"d.huigens@protonmail.com"},"repository":{"type":"git","url":"git+https://github.com/openpgpjs/streams.git"},"versions":{"0.0.1":{"name":"web-stream-tools","version":"0.0.1","description":"Utility functions for WhatWG Streams","main":"lib/streams.js","repository":{"type":"git","url":"git+https://github.com/openpgpjs/streams.git"},"author":{"name":"Daniel Huigens","email":"d.huigens@protonmail.com"},"license":"MIT","bugs":{"url":"https://github.com/openpgpjs/streams/issues"},"homepage":"https://github.com/openpgpjs/streams#readme","devDependencies":{"jsdoc":"~3.5.5"},"scripts":{"docs":"jsdoc lib -d docs --readme README.md"},"gitHead":"99a6072da0c69960c961de35fa956f4cdc177b8c","_id":"web-stream-tools@0.0.1","_npmVersion":"6.1.0","_nodeVersion":"10.4.1","_npmUser":{"name":"sunnyrajan","email":"sunny@protonmail.com"},"dist":{"shasum":"6d2c06a6f5f46eab5e73d82285bae3c9b5ee71a0","size":434318,"noattachment":false,"key":"/web-stream-tools/-/web-stream-tools-0.0.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/web-stream-tools/download/web-stream-tools-0.0.1.tgz"},"maintainers":[{"name":"sunnyrajan","email":""}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/web-stream-tools_0.0.1_1532526865930_0.2365159091369644"},"_hasShrinkwrap":false,"publish_time":1532526866140,"_cnpm_publish_time":1532526866140,"_cnpmcore_publish_time":"2021-12-16T17:31:31.683Z"}},"readme":"# Web Stream Tools\n\nThis library contains both basic convenience functions such as `readToEnd`, `concat`, `slice`, `clone`, `webToNode` and `nodeToWeb`, and more complex functions for transforming and parsing streams. Examples of the latter can be found below.\n\n## Table of Contents\n<!-- MarkdownTOC autolink=\"true\" -->\n\n- [Usage](#usage)\n- [Documentation](#documentation)\n- [Examples](#examples)\n  - [Transforming a stream](#transforming-a-stream)\n  - [Transforming a stream in chunks of 1024 bytes](#transforming-a-stream-in-chunks-of-1024-bytes)\n  - [Parsing data on a stream which is expected to be in a specific format](#parsing-data-on-a-stream-which-is-expected-to-be-in-a-specific-format)\n  - [Cloning and slicing streams](#cloning-and-slicing-streams)\n\n<!-- /MarkdownTOC -->\n\n## Usage\n\n```bash\nnpm install --save web-stream-tools\n```\n\n```js\nimport stream from 'web-stream-tools';\n```\n\n## Documentation\n\nSee [the documentation](https://openpgpjs.org/web-stream-tools/global.html) for a full list of functions. \n\n## Examples\n\n### Transforming a stream\n\nIn this example we're encrypting a stream using an imaginary API which has `process` and `finish` methods.\n\n```js\nconst encryptor = new Encryptor();\nconst encrypted = stream.transform(input, function process(chunk) {\n  return encryptor.process(chunk);\n}, function finish() {\n  return encryptor.finish();\n});\n```\n\nBoth the `process` and `finish` functions:\n\n- are optional (by default no data is written to the transformed stream)\n- may be asynchronous\n- may throw (in which case the error is forwarded to the transformed stream)\n\n`input` can be a stream containing anything, or it can be a plain value (Uint8Array or String) in which case `transform()` will simply return `process(input)` and `finish()` concatenated together.\n\n### Transforming a stream in chunks of 1024 bytes\n\nIn this example we're encrypting a stream using an imaginary API which has a `process` method that requires us to pass in chunks of size 1024 (unless it's the last chunk).\n\n```js\nconst encrypted = stream.transformPair(input, async (readable, writable) => {\n  const reader = stream.getReader(readable);\n  const writer = stream.getWriter(writable);\n  try {\n    while (true) {\n      await writer.ready;\n      const chunk = await reader.readBytes(1024);\n        // The above will return 1024 bytes unless the stream closed before that, in which\n        // case it either returns fewer bytes or undefined if no data is available.\n      if (chunk === undefined) {\n        await writer.close();\n        break;\n      }\n      await writer.write(encryptor.process(chunk));\n    }\n  } catch(e) {\n    await writer.abort(e);\n  }\n});\n```\n\nThe above example may seem more complicated than necessary, but it correctly handles:\n\n- Backpressure (if `encrypted` gets read slowly, `input` gets read slowly as well)\n- Cancellation (if `encrypted` gets canceled, `input` gets cancelled as well)\n- Erroring (if `input` errors, `encrypted` gets errored as well)\n\nUnlike `transform`, `transformPair` will always return a stream, even if `input` is not.\n\n### Parsing data on a stream which is expected to be in a specific format\n\nThere are also helper functions for reading a specific number of bytes, or a single line, etc:\n\n```js\nstream.parse(input, reader => {\n  const byte = await reader.readByte(); // Single byte or undefined\n  const bytes = await reader.readBytes(n); // Uint8Array of up to n bytes, or undefined\n  const line = await reader.readLine(); // Returns String up to and including the first \\n, or undefined. This function is specifically for a stream of Strings.\n  // There's also peekBytes() and unshift(), which you can use to look ahead in the stream.\n\n  const stream = reader.remainder(); // New stream containing the remainder of the original stream. Only available when using a Reader from stream.parse()\n});\n```\n\nMost of the functions above are also available when getting a reader using `stream.getReader()` instead of `stream.parse()`.\n\nAll of the functions above also work when reading a stream containing Strings instead of a Uint8Arrays, and will return Strings in that case.\n\n### Cloning and slicing streams\n\nThere are also a few functions not for reading the stream, but for manipulating the stream for another function to read:\n\n```js\nstream.slice(input, begin, end); // Returns a stream pointing to part of the original stream, or a Uint8Array\nstream.clone(input); // Returns a copy of the stream so that two functions can read it. Note: this does *not* clone a Uint8Array, since this function is only meant for reading the same data twice.\nstream.passiveClone(input); // Also returns a copy of the stream, but doesn't return data immediately when you read from it, only returns data when you read from the original stream. This is meant for respecting backpressure.\n```\n\nNote: these three functions do not work well with Node streams. Please convert Node streams to Web streams with `stream.nodeToWeb` first before using them.\n","_attachments":{},"homepage":"https://github.com/openpgpjs/streams#readme","bugs":{"url":"https://github.com/openpgpjs/streams/issues"},"license":"MIT"}