diff --git a/index.d.ts b/index.d.ts index a0845bb..8961df3 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,66 +1,108 @@ /// 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 - 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 extends Options { + /** + [Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream. + + @default 'utf8' + */ + readonly encoding?: EncodingType; + } + + type MaxBufferError = MaxBufferErrorClass; } declare const getStream: { /** - * 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; + 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; /** - * 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; + 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; /** - * 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( stream: Stream, - options?: Options + options?: getStream.Options ): Promise; array( stream: Stream, - options: OptionsWithEncoding<'buffer'> + options: getStream.OptionsWithEncoding<'buffer'> ): Promise; array( stream: Stream, - options: OptionsWithEncoding + options: getStream.OptionsWithEncoding ): Promise; -}; -export default getStream; + MaxBufferError: typeof MaxBufferErrorClass; -export class MaxBufferError extends Error { - readonly name: 'MaxBufferError'; - constructor(); -} + // TODO: Remove this for the next major release + default: typeof getStream; +}; + +export = getStream; diff --git a/index.js b/index.js index cf9ef03..340ea7d 100644 --- a/index.js +++ b/index.js @@ -51,6 +51,7 @@ async function getStream(inputStream, options) { } module.exports = getStream; +// TODO: Remove this for the next major release module.exports.default = getStream; module.exports.buffer = (stream, options) => getStream(stream, {...options, encoding: 'buffer'}); module.exports.array = (stream, options) => getStream(stream, {...options, array: true}); diff --git a/index.test-d.ts b/index.test-d.ts index c40c04c..41ff487 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -1,6 +1,7 @@ import * as fs from 'fs'; -import {expectType} from 'tsd-check'; -import getStream, {MaxBufferError} from '.'; +import {expectType} from 'tsd'; +import getStream = require('.'); +import {MaxBufferError} from '.'; const stream = fs.createReadStream('foo'); @@ -24,4 +25,5 @@ expectType>( getStream.array(stream, {maxBuffer: 10, encoding: 'utf8'}) ); -expectType(MaxBufferError); +const maxBufferError = new MaxBufferError(); +expectType(maxBufferError); diff --git a/package.json b/package.json index 4c5baa2..9f0e721 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,7 @@ "node": ">=8" }, "scripts": { - "test": "xo && ava && tsd-check" + "test": "xo && ava && tsd" }, "files": [ "index.js", @@ -40,10 +40,10 @@ "pump": "^3.0.0" }, "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" } } diff --git a/test.js b/test.js index 6d1756b..ccff3cf 100644 --- a/test.js +++ b/test.js @@ -12,7 +12,7 @@ function makeSetup(intoStream) { } const setup = makeSetup(intoStream); -setup.obj = makeSetup(intoStream.obj); +setup.object = makeSetup(intoStream.object); test('get stream as a buffer', async t => { t.true((await getStream.buffer(fs.createReadStream('fixture'))).equals(Buffer.from('unicorn\n'))); @@ -25,7 +25,7 @@ test('get stream as an array', async t => { }); test('get object stream as an array', async t => { - const result = await setup.obj.array([{foo: true}, {bar: false}]); + const result = await setup.object.array([{foo: true}, {bar: false}]); t.deepEqual(result, [{foo: true}, {bar: false}]); }); @@ -55,8 +55,8 @@ test('maxBuffer throws when size is exceeded', async t => { }); test('maxBuffer applies to length of arrays when in objectMode', async t => { - await t.throwsAsync(getStream.array(intoStream.obj([{a: 1}, {b: 2}, {c: 3}, {d: 4}]), {maxBuffer: 3}), /maxBuffer exceeded/); - await t.notThrowsAsync(getStream.array(intoStream.obj([{a: 1}, {b: 2}, {c: 3}]), {maxBuffer: 3})); + await t.throwsAsync(getStream.array(intoStream.object([{a: 1}, {b: 2}, {c: 3}, {d: 4}]), {maxBuffer: 3}), /maxBuffer exceeded/); + await t.notThrowsAsync(getStream.array(intoStream.object([{a: 1}, {b: 2}, {c: 3}]), {maxBuffer: 3})); }); test('maxBuffer applies to length of data when not in objectMode', async t => {