index.d.ts 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  1. /// <reference types="node"/>
  2. import {Stream} from 'stream';
  3. declare class MaxBufferErrorClass extends Error {
  4. readonly name: 'MaxBufferError';
  5. constructor();
  6. }
  7. declare namespace getStream {
  8. interface Options {
  9. /**
  10. Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `MaxBufferError` error.
  11. @default Infinity
  12. */
  13. readonly maxBuffer?: number;
  14. }
  15. interface OptionsWithEncoding<EncodingType = BufferEncoding> extends Options {
  16. /**
  17. [Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream.
  18. @default 'utf8'
  19. */
  20. readonly encoding?: EncodingType;
  21. }
  22. type MaxBufferError = MaxBufferErrorClass;
  23. }
  24. declare const getStream: {
  25. /**
  26. Get the `stream` as a string.
  27. @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.
  28. @example
  29. ```
  30. import * as fs from 'fs';
  31. import getStream = require('get-stream');
  32. (async () => {
  33. const stream = fs.createReadStream('unicorn.txt');
  34. console.log(await getStream(stream));
  35. // ,,))))))));,
  36. // __)))))))))))))),
  37. // \|/ -\(((((''''((((((((.
  38. // -*-==//////(('' . `)))))),
  39. // /|\ ))| o ;-. '((((( ,(,
  40. // ( `| / ) ;))))' ,_))^;(~
  41. // | | | ,))((((_ _____------~~~-. %,;(;(>';'~
  42. // o_); ; )))(((` ~---~ `:: \ %%~~)(v;(`('~
  43. // ; ''''```` `: `:::|\,__,%% );`'; ~
  44. // | _ ) / `:|`----' `-'
  45. // ______/\/~ | / /
  46. // /~;;.____/;;' / ___--,-( `;;;/
  47. // / // _;______;'------~~~~~ /;;/\ /
  48. // // | | / ; \;;,\
  49. // (<_ | ; /',/-----' _>
  50. // \_| ||_ //~;~~~~~~~~~
  51. // `\_| (,~~
  52. // \~\
  53. // ~~
  54. })();
  55. ```
  56. */
  57. (stream: Stream, options?: getStream.OptionsWithEncoding): Promise<string>;
  58. /**
  59. Get the `stream` as a buffer.
  60. It honors the `maxBuffer` option as above, but it refers to byte length rather than string length.
  61. */
  62. buffer(
  63. stream: Stream,
  64. options?: getStream.Options
  65. ): Promise<Buffer>;
  66. /**
  67. Get the `stream` as an array of values.
  68. It honors both the `maxBuffer` and `encoding` options. The behavior changes slightly based on the encoding chosen:
  69. - 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).
  70. - 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.
  71. - 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.
  72. */
  73. array<StreamObjectModeType>(
  74. stream: Stream,
  75. options?: getStream.Options
  76. ): Promise<StreamObjectModeType[]>;
  77. array(
  78. stream: Stream,
  79. options: getStream.OptionsWithEncoding<'buffer'>
  80. ): Promise<Buffer[]>;
  81. array(
  82. stream: Stream,
  83. options: getStream.OptionsWithEncoding<BufferEncoding>
  84. ): Promise<string[]>;
  85. MaxBufferError: typeof MaxBufferErrorClass;
  86. };
  87. export = getStream;