get-stream
Advanced tools
Comparing version 5.0.0 to 5.1.0
126
index.d.ts
/// <reference types="node"/> | ||
import {Stream} from 'stream'; | ||
export interface Options { | ||
/** | ||
* Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `MaxBufferError` error. | ||
* | ||
* @default Infinity | ||
*/ | ||
readonly maxBuffer?: number; | ||
declare class MaxBufferErrorClass extends Error { | ||
readonly name: 'MaxBufferError'; | ||
constructor(); | ||
} | ||
export interface OptionsWithEncoding<EncodingType = BufferEncoding> | ||
extends Options { | ||
/** | ||
* [Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream. | ||
* | ||
* @default 'utf8' | ||
*/ | ||
readonly encoding?: EncodingType; | ||
declare namespace getStream { | ||
interface Options { | ||
/** | ||
Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `MaxBufferError` error. | ||
@default Infinity | ||
*/ | ||
readonly maxBuffer?: number; | ||
} | ||
interface OptionsWithEncoding<EncodingType = BufferEncoding> extends Options { | ||
/** | ||
[Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream. | ||
@default 'utf8' | ||
*/ | ||
readonly encoding?: EncodingType; | ||
} | ||
type MaxBufferError = MaxBufferErrorClass; | ||
} | ||
@@ -25,43 +33,77 @@ | ||
/** | ||
* Get the `stream` as a string. | ||
* | ||
* @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. | ||
*/ | ||
(stream: Stream, options?: OptionsWithEncoding): Promise<string>; | ||
Get the `stream` as a string. | ||
@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. | ||
@example | ||
``` | ||
import * as fs from 'fs'; | ||
import getStream = require('get-stream'); | ||
(async () => { | ||
const stream = fs.createReadStream('unicorn.txt'); | ||
console.log(await getStream(stream)); | ||
// ,,))))))));, | ||
// __)))))))))))))), | ||
// \|/ -\(((((''''((((((((. | ||
// -*-==//////(('' . `)))))), | ||
// /|\ ))| o ;-. '((((( ,(, | ||
// ( `| / ) ;))))' ,_))^;(~ | ||
// | | | ,))((((_ _____------~~~-. %,;(;(>';'~ | ||
// o_); ; )))(((` ~---~ `:: \ %%~~)(v;(`('~ | ||
// ; ''''```` `: `:::|\,__,%% );`'; ~ | ||
// | _ ) / `:|`----' `-' | ||
// ______/\/~ | / / | ||
// /~;;.____/;;' / ___--,-( `;;;/ | ||
// / // _;______;'------~~~~~ /;;/\ / | ||
// // | | / ; \;;,\ | ||
// (<_ | ; /',/-----' _> | ||
// \_| ||_ //~;~~~~~~~~~ | ||
// `\_| (,~~ | ||
// \~\ | ||
// ~~ | ||
})(); | ||
``` | ||
*/ | ||
(stream: Stream, options?: getStream.OptionsWithEncoding): Promise<string>; | ||
/** | ||
* Get the `stream` as a buffer. | ||
* | ||
* It honors the `maxBuffer` option as above, but it refers to byte length rather than string length. | ||
*/ | ||
buffer(stream: Stream, options?: OptionsWithEncoding): Promise<Buffer>; | ||
Get the `stream` as a buffer. | ||
It honors the `maxBuffer` option as above, but it refers to byte length rather than string length. | ||
*/ | ||
buffer( | ||
stream: Stream, | ||
options?: getStream.OptionsWithEncoding | ||
): Promise<Buffer>; | ||
/** | ||
* 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](https://nodesource.com/blog/understanding-object-streams/) 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. | ||
*/ | ||
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](https://nodesource.com/blog/understanding-object-streams/) 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. | ||
*/ | ||
array<StreamObjectModeType = unknown>( | ||
stream: Stream, | ||
options?: Options | ||
options?: getStream.Options | ||
): Promise<StreamObjectModeType[]>; | ||
array( | ||
stream: Stream, | ||
options: OptionsWithEncoding<'buffer'> | ||
options: getStream.OptionsWithEncoding<'buffer'> | ||
): Promise<Buffer[]>; | ||
array( | ||
stream: Stream, | ||
options: OptionsWithEncoding<BufferEncoding> | ||
options: getStream.OptionsWithEncoding<BufferEncoding> | ||
): Promise<string[]>; | ||
MaxBufferError: typeof MaxBufferErrorClass; | ||
// TODO: Remove this for the next major release | ||
default: typeof getStream; | ||
}; | ||
export default getStream; | ||
export class MaxBufferError extends Error { | ||
readonly name: 'MaxBufferError'; | ||
constructor(); | ||
} | ||
export = getStream; |
@@ -54,2 +54,3 @@ 'use strict'; | ||
module.exports = getStream; | ||
// TODO: Remove this for the next major release | ||
module.exports.default = getStream; | ||
@@ -56,0 +57,0 @@ module.exports.buffer = (stream, options) => getStream(stream, {...options, encoding: 'buffer'}); |
{ | ||
"name": "get-stream", | ||
"version": "5.0.0", | ||
"version": "5.1.0", | ||
"description": "Get a stream as a string, buffer, or array", | ||
@@ -16,3 +16,3 @@ "license": "MIT", | ||
"scripts": { | ||
"test": "xo && ava && tsd-check" | ||
"test": "xo && ava && tsd" | ||
}, | ||
@@ -44,8 +44,8 @@ "files": [ | ||
"devDependencies": { | ||
"@types/node": "^11.10.5", | ||
"ava": "^1.3.1", | ||
"into-stream": "^4.0.0", | ||
"tsd-check": "^0.3.0", | ||
"@types/node": "^11.13.0", | ||
"ava": "^1.4.1", | ||
"into-stream": "^5.0.0", | ||
"tsd": "^0.7.2", | ||
"xo": "^0.24.0" | ||
} | ||
} |
11825
175