get-stream

What is get-stream?

The get-stream npm package is a utility that allows you to get a stream as a string, buffer, or array. It is useful for converting streams into a more usable form in Node.js applications.

What are get-stream's main functionalities?

Get stream as a string

This feature allows you to convert a readable stream into a string. It is useful when you want to process the contents of a file or any readable stream as a string.

const getStream = require('get-stream');
const fs = require('fs');

(async () => {
  const stream = fs.createReadStream('file.txt');
  const data = await getStream(stream);
  console.log(data);
})();

Get stream as a buffer

This feature allows you to convert a readable stream into a buffer. It is useful when you need to handle binary data from streams.

const getStream = require('get-stream');
const fs = require('fs');

(async () => {
  const stream = fs.createReadStream('file.txt');
  const data = await getStream.buffer(stream);
  console.log(data);
})();

Get stream as an array

This feature allows you to convert a readable stream into an array of values. It is useful when you want to process data from a stream in chunks or lines.

const getStream = require('get-stream');
const fs = require('fs');

(async () => {
  const stream = fs.createReadStream('file.txt');
  const data = await getStream.array(stream);
  console.log(data);
})();

Other packages similar to get-stream

concat-stream

concat-stream is a writable stream that concatenates data and calls a callback with the result. It is similar to get-stream but uses a callback pattern instead of promises.

bl

Buffer List (bl) is a storage object for collections of Node Buffers, which can be easily read and written. It is similar to get-stream's buffer functionality but offers more features for manipulating the buffer list.

stream-to-promise

stream-to-promise converts a Node.js stream into a promise, which is resolved when the 'finish' event is emitted. It is similar to get-stream but focuses on the 'finish' event rather than collecting the stream's data.

README

get-stream

Get a stream as a string, buffer, or array

Install

$ npm install get-stream

Usage

const fs = require('fs');
const getStream = require('get-stream');

(async () => {
	const stream = fs.createReadStream('unicorn.txt');

	console.log(await getStream(stream));
	/*
	              ,,))))))));,
	           __)))))))))))))),
	\|/       -\(((((''''((((((((.
	-*-==//////((''  .     `)))))),
	/|\      ))| o    ;-.    '(((((                                  ,(,
	         ( `|    /  )    ;))))'                               ,_))^;(~
	            |   |   |   ,))((((_     _____------~~~-.        %,;(;(>';'~
	            o_);   ;    )))(((` ~---~  `::           \      %%~~)(v;(`('~
	                  ;    ''''````         `:       `:::|\,__,%%    );`'; ~
	                 |   _                )     /      `:|`----'     `-'
	           ______/\/~    |                 /        /
	         /~;;.____/;;'  /          ___--,-(   `;;;/
	        / //  _;______;'------~~~~~    /;;/\    /
	       //  | |                        / ;   \;;,\
	      (<_  | ;                      /',/-----'  _>
	       \_| ||_                     //~;~~~~~~~~~
	           `\_|                   (,~~
	                                   \~\
	                                    ~~
	*/
})();

API

The methods returns a promise that resolves when the end event fires on the stream, indicating that there is no more data to be read. The stream is switched to flowing mode.

getStream(stream, [options])

Get the stream as a string.

options

Type: Object

encoding

Type: string
Default: utf8

Encoding of the incoming stream.

maxBuffer

Type: number
Default: Infinity

Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a getStream.MaxBufferError error.

getStream.buffer(stream, [options])

Get the stream as a buffer.

It honors the maxBuffer option as above, but it refers to byte length rather than string length.

getStream.array(stream, [options])

Get the stream as an array of values.

It honors both the maxBuffer and encoding options. The behavior changes slightly based on the encoding chosen:

• When encoding is unset, it assumes an object mode stream and collects values emitted from stream unmodified. In this case maxBuffer refers to the number of items in the array (not the sum of their sizes).

• When encoding is set to buffer, it collects an array of buffers. maxBuffer refers to the summed byte lengths of every buffer in the array.

• When encoding is set to anything else, it collects an array of strings. maxBuffer refers to the summed character lengths of every string in the array.

Errors

If the input stream emits an error event, the promise will be rejected with the error. The buffered data will be attached to the bufferedData property of the error.

(async () => {
	try {
		await getStream(streamThatErrorsAtTheEnd('unicorn'));
	} catch (error) {
		console.log(error.bufferedData);
		//=> 'unicorn'
	}
})()

FAQ

How is this different from concat-stream?

This 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, or 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.

Related

• get-stdin - Get stdin as a string or buffer

License

MIT © Sindre Sorhus