{"id":13396654,"url":"https://github.com/sindresorhus/get-stream","last_synced_at":"2025-05-14T16:14:11.063Z","repository":{"id":52886195,"uuid":"44264225","full_name":"sindresorhus/get-stream","owner":"sindresorhus","description":"Get a stream as a string, Buffer, ArrayBuffer or array","archived":false,"fork":false,"pushed_at":"2024-10-28T05:15:33.000Z","size":155,"stargazers_count":348,"open_issues_count":1,"forks_count":32,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-27T09:03:30.505Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sindresorhus.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"sindresorhus","open_collective":"sindresorhus","buy_me_a_coffee":"sindresorhus","custom":"https://sindresorhus.com/donate"}},"created_at":"2015-10-14T17:22:22.000Z","updated_at":"2025-04-20T07:24:39.000Z","dependencies_parsed_at":"2024-02-20T16:07:05.555Z","dependency_job_id":"d83b3e89-018c-4804-90c3-414324d861e2","html_url":"https://github.com/sindresorhus/get-stream","commit_stats":{"total_commits":123,"total_committers":19,"mean_commits":6.473684210526316,"dds":0.5040650406504066,"last_synced_commit":"cdbd77bebf332f28a2949613fc1534d8a7a04c95"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-stream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-stream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-stream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Fget-stream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sindresorhus","download_url":"https://codeload.github.com/sindresorhus/get-stream/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252405970,"owners_count":21742690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T18:00:58.963Z","updated_at":"2025-05-14T16:14:11.002Z","avatar_url":"https://github.com/sindresorhus.png","language":"JavaScript","funding_links":["https://github.com/sponsors/sindresorhus","https://opencollective.com/sindresorhus","https://buymeacoffee.com/sindresorhus","https://sindresorhus.com/donate"],"categories":["stream","Packages","Repository","JavaScript","包","Streams","目录","Modules","Works with AVA"],"sub_categories":["Streams","文件流","流处理","流"],"readme":"# get-stream\n\n\u003e Get a stream as a string, Buffer, ArrayBuffer or array\n\n## Features\n\n- Works in any JavaScript environment ([Node.js](#nodejs-streams), [browsers](#browser-support), etc.).\n- Supports [text streams](#getstreamstream-options), [binary streams](#getstreamasbufferstream-options) and [object streams](#getstreamasarraystream-options).\n- Supports [async iterables](#async-iterables).\n- Can set a [maximum stream size](#maxbuffer).\n- Returns [partially read data](#errors) when the stream errors.\n- [Fast](#benchmarks).\n\n## Install\n\n```sh\nnpm install get-stream\n```\n\n## Usage\n\n### Node.js streams\n\n```js\nimport fs from 'node:fs';\nimport getStream from 'get-stream';\n\nconst stream = fs.createReadStream('unicorn.txt');\n\nconsole.log(await getStream(stream));\n/*\n              ,,))))))));,\n           __)))))))))))))),\n\\|/       -\\(((((''''((((((((.\n-*-==//////((''  .     `)))))),\n/|\\      ))| o    ;-.    '(((((                                  ,(,\n         ( `|    /  )    ;))))'                               ,_))^;(~\n            |   |   |   ,))((((_     _____------~~~-.        %,;(;(\u003e';'~\n            o_);   ;    )))(((` ~---~  `::           \\      %%~~)(v;(`('~\n                  ;    ''''````         `:       `:::|\\,__,%%    );`'; ~\n                 |   _                )     /      `:|`----'     `-'\n           ______/\\/~    |                 /        /\n         /~;;.____/;;'  /          ___--,-(   `;;;/\n        / //  _;______;'------~~~~~    /;;/\\    /\n       //  | |                        / ;   \\;;,\\\n      (\u003c_  | ;                      /',/-----'  _\u003e\n       \\_| ||_                     //~;~~~~~~~~~\n           `\\_|                   (,~~\n                                   \\~\\\n                                    ~~\n*/\n```\n\n### Web streams\n\n```js\nimport getStream from 'get-stream';\n\nconst {body: readableStream} = await fetch('https://example.com');\nconsole.log(await getStream(readableStream));\n```\n\nThis works in any browser, even [the ones](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream#browser_compatibility) not supporting `ReadableStream.values()` yet.\n\n### Async iterables\n\n```js\nimport {opendir} from 'node:fs/promises';\nimport {getStreamAsArray} from 'get-stream';\n\nconst asyncIterable = await opendir(directory);\nconsole.log(await getStreamAsArray(asyncIterable));\n```\n\n## API\n\nThe following methods read the stream's contents and return it as a promise.\n\n### getStream(stream, options?)\n\n`stream`: [`stream.Readable`](https://nodejs.org/api/stream.html#class-streamreadable), [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream), or [`AsyncIterable\u003cstring | Buffer | ArrayBuffer | DataView | TypedArray\u003e`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols)\\\n`options`: [`Options`](#options)\n\nGet the given `stream` as a string.\n\n### getStreamAsBuffer(stream, options?)\n\nGet the given `stream` as a Node.js [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer).\n\n```js\nimport {getStreamAsBuffer} from 'get-stream';\n\nconst stream = fs.createReadStream('unicorn.png');\nconsole.log(await getStreamAsBuffer(stream));\n```\n\n### getStreamAsArrayBuffer(stream, options?)\n\nGet the given `stream` as an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer).\n\n```js\nimport {getStreamAsArrayBuffer} from 'get-stream';\n\nconst {body: readableStream} = await fetch('https://example.com');\nconsole.log(await getStreamAsArrayBuffer(readableStream));\n```\n\n### getStreamAsArray(stream, options?)\n\nGet the given `stream` as an array. Unlike [other methods](#api), this supports [streams of objects](https://nodejs.org/api/stream.html#object-mode).\n\n```js\nimport {getStreamAsArray} from 'get-stream';\n\nconst {body: readableStream} = await fetch('https://example.com');\nconsole.log(await getStreamAsArray(readableStream));\n```\n\n#### options\n\nType: `object`\n\n##### maxBuffer\n\nType: `number`\\\nDefault: `Infinity`\n\nMaximum length of the stream. If exceeded, the promise will be rejected with a `MaxBufferError`.\n\nDepending on the [method](#api), the length is measured with [`string.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length), [`buffer.length`](https://nodejs.org/api/buffer.html#buflength), [`arrayBuffer.byteLength`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/byteLength) or [`array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length).\n\n## Errors\n\nIf the stream errors, the returned promise will be rejected with the `error`. Any contents already read from the stream will be set to `error.bufferedData`, which is a `string`, a `Buffer`, an `ArrayBuffer` or an array depending on the [method used](#api).\n\n```js\nimport getStream from 'get-stream';\n\ntry {\n\tawait getStream(streamThatErrorsAtTheEnd('unicorn'));\n} catch (error) {\n\tconsole.log(error.bufferedData);\n\t//=\u003e 'unicorn'\n}\n```\n\n## Browser support\n\nFor this module to work in browsers, a bundler must be used that either:\n- Supports the [`exports.browser`](https://nodejs.org/api/packages.html#community-conditions-definitions) field in `package.json`\n- Strips or ignores `node:*` imports\n\nMost bundlers (such as [Webpack](https://webpack.js.org/guides/package-exports/#target-environment)) support either of these.\n\nAdditionally, browsers support [web streams](#web-streams) and [async iterables](#async-iterables), but not [Node.js streams](#nodejs-streams).\n\n## Tips\n\n### Alternatives\n\nIf you do not need the [`maxBuffer`](#maxbuffer) option, [`error.bufferedData`](#errors), nor browser support, you can use the following methods instead of this package.\n\n#### [`streamConsumers.text()`](https://nodejs.org/api/webstreams.html#streamconsumerstextstream)\n\n```js\nimport fs from 'node:fs';\nimport {text} from 'node:stream/consumers';\n\nconst stream = fs.createReadStream('unicorn.txt', {encoding: 'utf8'});\nconsole.log(await text(stream))\n```\n\n#### [`streamConsumers.buffer()`](https://nodejs.org/api/webstreams.html#streamconsumersbufferstream)\n\n```js\nimport {buffer} from 'node:stream/consumers';\n\nconsole.log(await buffer(stream))\n```\n\n#### [`streamConsumers.arrayBuffer()`](https://nodejs.org/api/webstreams.html#streamconsumersarraybufferstream)\n\n```js\nimport {arrayBuffer} from 'node:stream/consumers';\n\nconsole.log(await arrayBuffer(stream))\n```\n\n#### [`readable.toArray()`](https://nodejs.org/api/stream.html#readabletoarrayoptions)\n\n```js\nconsole.log(await stream.toArray())\n```\n\n#### [`Array.fromAsync()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fromAsync)\n\nIf your [environment supports it](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fromAsync#browser_compatibility):\n\n```js\nconsole.log(await Array.fromAsync(stream))\n```\n\n### Non-UTF-8 encoding\n\nWhen all of the following conditions apply:\n  - [`getStream()`](#getstreamstream-options) is used (as opposed to [`getStreamAsBuffer()`](#getstreamasbufferstream-options) or [`getStreamAsArrayBuffer()`](#getstreamasarraybufferstream-options))\n  - The stream is binary (not text)\n  - The stream's encoding is not UTF-8 (for example, it is UTF-16, hexadecimal, or Base64)\n\nThen the stream must be decoded using a transform stream like [`TextDecoderStream`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream) or [`b64`](https://github.com/hapijs/b64).\n\n```js\nimport getStream from 'get-stream';\n\nconst textDecoderStream = new TextDecoderStream('utf-16le');\nconst {body: readableStream} = await fetch('https://example.com');\nconsole.log(await getStream(readableStream.pipeThrough(textDecoderStream)));\n```\n\n### Blobs\n\n[`getStreamAsArrayBuffer()`](#getstreamasarraybufferstream-options) can be used to create [Blobs](https://developer.mozilla.org/en-US/docs/Web/API/Blob).\n\n```js\nimport {getStreamAsArrayBuffer} from 'get-stream';\n\nconst stream = fs.createReadStream('unicorn.txt');\nconsole.log(new Blob([await getStreamAsArrayBuffer(stream)]));\n```\n\n### JSON streaming\n\n[`getStreamAsArray()`](#getstreamasarraystream-options) can be combined with JSON streaming utilities to parse JSON incrementally.\n\n```js\nimport fs from 'node:fs';\nimport {compose as composeStreams} from 'node:stream';\nimport {getStreamAsArray} from 'get-stream';\nimport streamJson from 'stream-json';\nimport streamJsonArray from 'stream-json/streamers/StreamArray.js';\n\nconst stream = fs.createReadStream('big-array-of-objects.json');\nconsole.log(await getStreamAsArray(\n\tcomposeStreams(stream, streamJson.parser(), streamJsonArray.streamArray()),\n));\n```\n\n## Benchmarks\n\n### Node.js stream (100 MB, binary)\n\n- `getStream()`: 142ms\n- `text()`: 139ms\n- `getStreamAsBuffer()`: 106ms\n- `buffer()`: 83ms\n- `getStreamAsArrayBuffer()`: 105ms\n- `arrayBuffer()`: 81ms\n- `getStreamAsArray()`: 24ms\n- `stream.toArray()`: 21ms\n\n### Node.js stream (100 MB, text)\n\n- `getStream()`: 90ms\n- `text()`: 89ms\n- `getStreamAsBuffer()`: 127ms\n- `buffer()`: 192ms\n- `getStreamAsArrayBuffer()`: 129ms\n- `arrayBuffer()`: 195ms\n- `getStreamAsArray()`: 89ms\n- `stream.toArray()`: 90ms\n\n### Web ReadableStream (100 MB, binary)\n\n- `getStream()`: 223ms\n- `text()`: 221ms\n- `getStreamAsBuffer()`: 182ms\n- `buffer()`: 153ms\n- `getStreamAsArrayBuffer()`: 171ms\n- `arrayBuffer()`: 155ms\n- `getStreamAsArray()`: 83ms\n\n### Web ReadableStream (100 MB, text)\n\n- `getStream()`: 141ms\n- `text()`: 139ms\n- `getStreamAsBuffer()`: 91ms\n- `buffer()`: 80ms\n- `getStreamAsArrayBuffer()`: 89ms\n- `arrayBuffer()`: 81ms\n- `getStreamAsArray()`: 21ms\n\n[Benchmarks' source file](benchmarks/index.js).\n\n## FAQ\n\n### How is this different from [`concat-stream`](https://github.com/maxogden/concat-stream)?\n\nThis module accepts a stream instead of being one and returns a promise instead of using a callback. The API is simpler and it only supports returning a string, `Buffer`, an `ArrayBuffer` or an array. It doesn't have a fragile type inference. You explicitly choose what you want. And it doesn't depend on the huge `readable-stream` package.\n\n## Related\n\n- [get-stdin](https://github.com/sindresorhus/get-stdin) - Get stdin as a string or buffer\n- [into-stream](https://github.com/sindresorhus/into-stream) - The opposite of this package\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Fget-stream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsindresorhus%2Fget-stream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Fget-stream/lists"}