{"_id":"web-stream-tools","_rev":"1-9767db2eb2f4a21c5c0a4bf2ac9cc397","name":"web-stream-tools","dist-tags":{"latest":"0.0.1"},"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":{"integrity":"sha512-MZUYhvTAMMy1u07OJL2pyp/tdrIu15fRJlGgnfvCQVXBS4cBNbIV1+6veYfVhTfnq0ZLispgx4nv17QxpuX+6w==","shasum":"6d2c06a6f5f46eab5e73d82285bae3c9b5ee71a0","tarball":"https://registry.npmjs.org/web-stream-tools/-/web-stream-tools-0.0.1.tgz","fileCount":38,"unpackedSize":1140044,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJbWIESCRA9TVsSAnZWagAA50kP/2dU50mXFtRpDOhlGGrC\nMMCOeV9+eJbj+8G9vrJOgVR41Z6LIoguyH01DQWv2tlt4tY0M+56YvWSQDkj\nDPXnimlYHPz7SkvJbUOnjgwDBMxBja793aXhFM7kxXV2EAey+9H1I9mml+ep\n+1jKWS8Vit6rTTpcZqMnFhwhjngx2QPbe9EAvQWgnOn9Wb8oZR3W/445bJyo\neGzPdKhzk3ecLsk2EhTLGMF54TmbPkJ7uk9mz0b0Z8vHoZedtj608aNKmEb0\nmjAg9OKabxD8VMNP7uNLk86G9LFImNSqIx92V/2O1QsNK8LWYAROGEa91jIb\nwsZWDiHqSzBWlVPkRpjZjXSjtQ+ylip6DdBKmYEzqt0AKeZ66GLPyiNuEocN\nVH3W1+7dkoFTtUsZmG8SWE9XGsvT+7y24rke//KIrGK6Q5stEduMqPg4B0uO\niQ2qjf14z3SD+Y/rrcbo2Jp3avwgWUtWYOHqkE6AkplQCLxvBh4h8M/RQJD/\npjONOyniRQNwctg3LD1XfkTAn+biDYxYkguI0U3EBTrVq/MmRB7KAouMdMEm\n/NBXGgs4RvlZ9ce0zhyzpg5Uc6INMIceFMFVf/vPl2GyMqeIies1IiY7IpfM\npyAg5J/p5JhznViIFnMd2vxxnx2fRJakJrC36sLUk+QVwMNYLsau+Foad+Ue\nSGTC\r\n=oauW\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDjWsit378utPAmtvcCPmHATECO8R3hnWiGu8wPw61JAAiEA3h4lzA+wp4y+Fj45ClwAmBX1rwL7t4llc5dLaifNQLU="}]},"maintainers":[{"name":"sunnyrajan","email":"sunny@protonmail.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/web-stream-tools_0.0.1_1532526865930_0.2365159091369644"},"_hasShrinkwrap":false}},"time":{"created":"2018-07-25T13:54:25.930Z","0.0.1":"2018-07-25T13:54:26.140Z","modified":"2022-05-24T04:49:01.112Z"},"maintainers":[{"name":"sunnyrajan","email":"sunny@protonmail.com"}],"description":"Utility functions for WhatWG Streams","homepage":"https://github.com/openpgpjs/streams#readme","repository":{"type":"git","url":"git+https://github.com/openpgpjs/streams.git"},"author":{"name":"Daniel Huigens","email":"d.huigens@protonmail.com"},"bugs":{"url":"https://github.com/openpgpjs/streams/issues"},"license":"MIT","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","readmeFilename":"README.md"}