index.d.ts 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545
  1. import { EventEmitter } from 'node:events';
  2. import { StringDecoder } from 'node:string_decoder';
  3. /**
  4. * Same as StringDecoder, but exposing the `lastNeed` flag on the type
  5. */
  6. type SD = StringDecoder & {
  7. lastNeed: boolean;
  8. };
  9. export type { SD, Pipe, PipeProxyErrors };
  10. /**
  11. * Return true if the argument is a Minipass stream, Node stream, or something
  12. * else that Minipass can interact with.
  13. */
  14. export declare const isStream: (s: any) => s is Minipass<any, any, any> | NodeJS.ReadStream | NodeJS.WriteStream | (EventEmitter<any> & {
  15. end(): any;
  16. write(chunk: any, ...args: any[]): any;
  17. }) | (EventEmitter<any> & {
  18. pause(): any;
  19. resume(): any;
  20. pipe(...destArgs: any[]): any;
  21. }) | (NodeJS.ReadStream & {
  22. fd: number;
  23. }) | (NodeJS.WriteStream & {
  24. fd: number;
  25. });
  26. /**
  27. * Return true if the argument is a valid {@link Minipass.Readable}
  28. */
  29. export declare const isReadable: (s: any) => s is Minipass.Readable;
  30. /**
  31. * Return true if the argument is a valid {@link Minipass.Writable}
  32. */
  33. export declare const isWritable: (s: any) => s is Minipass.Readable;
  34. declare const EOF: unique symbol;
  35. declare const MAYBE_EMIT_END: unique symbol;
  36. declare const EMITTED_END: unique symbol;
  37. declare const EMITTING_END: unique symbol;
  38. declare const EMITTED_ERROR: unique symbol;
  39. declare const CLOSED: unique symbol;
  40. declare const READ: unique symbol;
  41. declare const FLUSH: unique symbol;
  42. declare const FLUSHCHUNK: unique symbol;
  43. declare const ENCODING: unique symbol;
  44. declare const DECODER: unique symbol;
  45. declare const FLOWING: unique symbol;
  46. declare const PAUSED: unique symbol;
  47. declare const RESUME: unique symbol;
  48. declare const BUFFER: unique symbol;
  49. declare const PIPES: unique symbol;
  50. declare const BUFFERLENGTH: unique symbol;
  51. declare const BUFFERPUSH: unique symbol;
  52. declare const BUFFERSHIFT: unique symbol;
  53. declare const OBJECTMODE: unique symbol;
  54. declare const DESTROYED: unique symbol;
  55. declare const ERROR: unique symbol;
  56. declare const EMITDATA: unique symbol;
  57. declare const EMITEND: unique symbol;
  58. declare const EMITEND2: unique symbol;
  59. declare const ASYNC: unique symbol;
  60. declare const ABORT: unique symbol;
  61. declare const ABORTED: unique symbol;
  62. declare const SIGNAL: unique symbol;
  63. declare const DATALISTENERS: unique symbol;
  64. declare const DISCARDED: unique symbol;
  65. /**
  66. * Options that may be passed to stream.pipe()
  67. */
  68. export interface PipeOptions {
  69. /**
  70. * end the destination stream when the source stream ends
  71. */
  72. end?: boolean;
  73. /**
  74. * proxy errors from the source stream to the destination stream
  75. */
  76. proxyErrors?: boolean;
  77. }
  78. /**
  79. * Internal class representing a pipe to a destination stream.
  80. *
  81. * @internal
  82. */
  83. declare class Pipe<T extends unknown> {
  84. src: Minipass<T>;
  85. dest: Minipass<any, T>;
  86. opts: PipeOptions;
  87. ondrain: () => any;
  88. constructor(src: Minipass<T>, dest: Minipass.Writable, opts: PipeOptions);
  89. unpipe(): void;
  90. proxyErrors(_er: any): void;
  91. end(): void;
  92. }
  93. /**
  94. * Internal class representing a pipe to a destination stream where
  95. * errors are proxied.
  96. *
  97. * @internal
  98. */
  99. declare class PipeProxyErrors<T> extends Pipe<T> {
  100. unpipe(): void;
  101. constructor(src: Minipass<T>, dest: Minipass.Writable, opts: PipeOptions);
  102. }
  103. export declare namespace Minipass {
  104. /**
  105. * Encoding used to create a stream that outputs strings rather than
  106. * Buffer objects.
  107. */
  108. export type Encoding = BufferEncoding | 'buffer' | null;
  109. /**
  110. * Any stream that Minipass can pipe into
  111. */
  112. export type Writable = Minipass<any, any, any> | NodeJS.WriteStream | (NodeJS.WriteStream & {
  113. fd: number;
  114. }) | (EventEmitter & {
  115. end(): any;
  116. write(chunk: any, ...args: any[]): any;
  117. });
  118. /**
  119. * Any stream that can be read from
  120. */
  121. export type Readable = Minipass<any, any, any> | NodeJS.ReadStream | (NodeJS.ReadStream & {
  122. fd: number;
  123. }) | (EventEmitter & {
  124. pause(): any;
  125. resume(): any;
  126. pipe(...destArgs: any[]): any;
  127. });
  128. /**
  129. * Utility type that can be iterated sync or async
  130. */
  131. export type DualIterable<T> = Iterable<T> & AsyncIterable<T>;
  132. type EventArguments = Record<string | symbol, unknown[]>;
  133. /**
  134. * The listing of events that a Minipass class can emit.
  135. * Extend this when extending the Minipass class, and pass as
  136. * the third template argument. The key is the name of the event,
  137. * and the value is the argument list.
  138. *
  139. * Any undeclared events will still be allowed, but the handler will get
  140. * arguments as `unknown[]`.
  141. */
  142. export interface Events<RType extends any = Buffer> extends EventArguments {
  143. readable: [];
  144. data: [chunk: RType];
  145. error: [er: unknown];
  146. abort: [reason: unknown];
  147. drain: [];
  148. resume: [];
  149. end: [];
  150. finish: [];
  151. prefinish: [];
  152. close: [];
  153. [DESTROYED]: [er?: unknown];
  154. [ERROR]: [er: unknown];
  155. }
  156. /**
  157. * String or buffer-like data that can be joined and sliced
  158. */
  159. export type ContiguousData = Buffer | ArrayBufferLike | ArrayBufferView | string;
  160. export type BufferOrString = Buffer | string;
  161. /**
  162. * Options passed to the Minipass constructor.
  163. */
  164. export type SharedOptions = {
  165. /**
  166. * Defer all data emission and other events until the end of the
  167. * current tick, similar to Node core streams
  168. */
  169. async?: boolean;
  170. /**
  171. * A signal which will abort the stream
  172. */
  173. signal?: AbortSignal;
  174. /**
  175. * Output string encoding. Set to `null` or `'buffer'` (or omit) to
  176. * emit Buffer objects rather than strings.
  177. *
  178. * Conflicts with `objectMode`
  179. */
  180. encoding?: BufferEncoding | null | 'buffer';
  181. /**
  182. * Output data exactly as it was written, supporting non-buffer/string
  183. * data (such as arbitrary objects, falsey values, etc.)
  184. *
  185. * Conflicts with `encoding`
  186. */
  187. objectMode?: boolean;
  188. };
  189. /**
  190. * Options for a string encoded output
  191. */
  192. export type EncodingOptions = SharedOptions & {
  193. encoding: BufferEncoding;
  194. objectMode?: false;
  195. };
  196. /**
  197. * Options for contiguous data buffer output
  198. */
  199. export type BufferOptions = SharedOptions & {
  200. encoding?: null | 'buffer';
  201. objectMode?: false;
  202. };
  203. /**
  204. * Options for objectMode arbitrary output
  205. */
  206. export type ObjectModeOptions = SharedOptions & {
  207. objectMode: true;
  208. encoding?: null;
  209. };
  210. /**
  211. * Utility type to determine allowed options based on read type
  212. */
  213. export type Options<T> = ObjectModeOptions | (T extends string ? EncodingOptions : T extends Buffer ? BufferOptions : SharedOptions);
  214. export {};
  215. }
  216. /**
  217. * Main export, the Minipass class
  218. *
  219. * `RType` is the type of data emitted, defaults to Buffer
  220. *
  221. * `WType` is the type of data to be written, if RType is buffer or string,
  222. * then any {@link Minipass.ContiguousData} is allowed.
  223. *
  224. * `Events` is the set of event handler signatures that this object
  225. * will emit, see {@link Minipass.Events}
  226. */
  227. export declare class Minipass<RType extends unknown = Buffer, WType extends unknown = RType extends Minipass.BufferOrString ? Minipass.ContiguousData : RType, Events extends Minipass.Events<RType> = Minipass.Events<RType>> extends EventEmitter implements Minipass.DualIterable<RType> {
  228. [FLOWING]: boolean;
  229. [PAUSED]: boolean;
  230. [PIPES]: Pipe<RType>[];
  231. [BUFFER]: RType[];
  232. [OBJECTMODE]: boolean;
  233. [ENCODING]: BufferEncoding | null;
  234. [ASYNC]: boolean;
  235. [DECODER]: SD | null;
  236. [EOF]: boolean;
  237. [EMITTED_END]: boolean;
  238. [EMITTING_END]: boolean;
  239. [CLOSED]: boolean;
  240. [EMITTED_ERROR]: unknown;
  241. [BUFFERLENGTH]: number;
  242. [DESTROYED]: boolean;
  243. [SIGNAL]?: AbortSignal;
  244. [ABORTED]: boolean;
  245. [DATALISTENERS]: number;
  246. [DISCARDED]: boolean;
  247. /**
  248. * true if the stream can be written
  249. */
  250. writable: boolean;
  251. /**
  252. * true if the stream can be read
  253. */
  254. readable: boolean;
  255. /**
  256. * If `RType` is Buffer, then options do not need to be provided.
  257. * Otherwise, an options object must be provided to specify either
  258. * {@link Minipass.SharedOptions.objectMode} or
  259. * {@link Minipass.SharedOptions.encoding}, as appropriate.
  260. */
  261. constructor(...args: [Minipass.ObjectModeOptions] | (RType extends Buffer ? [] | [Minipass.Options<RType>] : [Minipass.Options<RType>]));
  262. /**
  263. * The amount of data stored in the buffer waiting to be read.
  264. *
  265. * For Buffer strings, this will be the total byte length.
  266. * For string encoding streams, this will be the string character length,
  267. * according to JavaScript's `string.length` logic.
  268. * For objectMode streams, this is a count of the items waiting to be
  269. * emitted.
  270. */
  271. get bufferLength(): number;
  272. /**
  273. * The `BufferEncoding` currently in use, or `null`
  274. */
  275. get encoding(): BufferEncoding | null;
  276. /**
  277. * @deprecated - This is a read only property
  278. */
  279. set encoding(_enc: BufferEncoding | null);
  280. /**
  281. * @deprecated - Encoding may only be set at instantiation time
  282. */
  283. setEncoding(_enc: Minipass.Encoding): void;
  284. /**
  285. * True if this is an objectMode stream
  286. */
  287. get objectMode(): boolean;
  288. /**
  289. * @deprecated - This is a read-only property
  290. */
  291. set objectMode(_om: boolean);
  292. /**
  293. * true if this is an async stream
  294. */
  295. get ['async'](): boolean;
  296. /**
  297. * Set to true to make this stream async.
  298. *
  299. * Once set, it cannot be unset, as this would potentially cause incorrect
  300. * behavior. Ie, a sync stream can be made async, but an async stream
  301. * cannot be safely made sync.
  302. */
  303. set ['async'](a: boolean);
  304. [ABORT](): void;
  305. /**
  306. * True if the stream has been aborted.
  307. */
  308. get aborted(): boolean;
  309. /**
  310. * No-op setter. Stream aborted status is set via the AbortSignal provided
  311. * in the constructor options.
  312. */
  313. set aborted(_: boolean);
  314. /**
  315. * Write data into the stream
  316. *
  317. * If the chunk written is a string, and encoding is not specified, then
  318. * `utf8` will be assumed. If the stream encoding matches the encoding of
  319. * a written string, and the state of the string decoder allows it, then
  320. * the string will be passed through to either the output or the internal
  321. * buffer without any processing. Otherwise, it will be turned into a
  322. * Buffer object for processing into the desired encoding.
  323. *
  324. * If provided, `cb` function is called immediately before return for
  325. * sync streams, or on next tick for async streams, because for this
  326. * base class, a chunk is considered "processed" once it is accepted
  327. * and either emitted or buffered. That is, the callback does not indicate
  328. * that the chunk has been eventually emitted, though of course child
  329. * classes can override this function to do whatever processing is required
  330. * and call `super.write(...)` only once processing is completed.
  331. */
  332. write(chunk: WType, cb?: () => void): boolean;
  333. write(chunk: WType, encoding?: Minipass.Encoding, cb?: () => void): boolean;
  334. /**
  335. * Low-level explicit read method.
  336. *
  337. * In objectMode, the argument is ignored, and one item is returned if
  338. * available.
  339. *
  340. * `n` is the number of bytes (or in the case of encoding streams,
  341. * characters) to consume. If `n` is not provided, then the entire buffer
  342. * is returned, or `null` is returned if no data is available.
  343. *
  344. * If `n` is greater that the amount of data in the internal buffer,
  345. * then `null` is returned.
  346. */
  347. read(n?: number | null): RType | null;
  348. [READ](n: number | null, chunk: RType): RType;
  349. /**
  350. * End the stream, optionally providing a final write.
  351. *
  352. * See {@link Minipass#write} for argument descriptions
  353. */
  354. end(cb?: () => void): this;
  355. end(chunk: WType, cb?: () => void): this;
  356. end(chunk: WType, encoding?: Minipass.Encoding, cb?: () => void): this;
  357. [RESUME](): void;
  358. /**
  359. * Resume the stream if it is currently in a paused state
  360. *
  361. * If called when there are no pipe destinations or `data` event listeners,
  362. * this will place the stream in a "discarded" state, where all data will
  363. * be thrown away. The discarded state is removed if a pipe destination or
  364. * data handler is added, if pause() is called, or if any synchronous or
  365. * asynchronous iteration is started.
  366. */
  367. resume(): void;
  368. /**
  369. * Pause the stream
  370. */
  371. pause(): void;
  372. /**
  373. * true if the stream has been forcibly destroyed
  374. */
  375. get destroyed(): boolean;
  376. /**
  377. * true if the stream is currently in a flowing state, meaning that
  378. * any writes will be immediately emitted.
  379. */
  380. get flowing(): boolean;
  381. /**
  382. * true if the stream is currently in a paused state
  383. */
  384. get paused(): boolean;
  385. [BUFFERPUSH](chunk: RType): void;
  386. [BUFFERSHIFT](): RType;
  387. [FLUSH](noDrain?: boolean): void;
  388. [FLUSHCHUNK](chunk: RType): boolean;
  389. /**
  390. * Pipe all data emitted by this stream into the destination provided.
  391. *
  392. * Triggers the flow of data.
  393. */
  394. pipe<W extends Minipass.Writable>(dest: W, opts?: PipeOptions): W;
  395. /**
  396. * Fully unhook a piped destination stream.
  397. *
  398. * If the destination stream was the only consumer of this stream (ie,
  399. * there are no other piped destinations or `'data'` event listeners)
  400. * then the flow of data will stop until there is another consumer or
  401. * {@link Minipass#resume} is explicitly called.
  402. */
  403. unpipe<W extends Minipass.Writable>(dest: W): void;
  404. /**
  405. * Alias for {@link Minipass#on}
  406. */
  407. addListener<Event extends keyof Events>(ev: Event, handler: (...args: Events[Event]) => any): this;
  408. /**
  409. * Mostly identical to `EventEmitter.on`, with the following
  410. * behavior differences to prevent data loss and unnecessary hangs:
  411. *
  412. * - Adding a 'data' event handler will trigger the flow of data
  413. *
  414. * - Adding a 'readable' event handler when there is data waiting to be read
  415. * will cause 'readable' to be emitted immediately.
  416. *
  417. * - Adding an 'endish' event handler ('end', 'finish', etc.) which has
  418. * already passed will cause the event to be emitted immediately and all
  419. * handlers removed.
  420. *
  421. * - Adding an 'error' event handler after an error has been emitted will
  422. * cause the event to be re-emitted immediately with the error previously
  423. * raised.
  424. */
  425. on<Event extends keyof Events>(ev: Event, handler: (...args: Events[Event]) => any): this;
  426. /**
  427. * Alias for {@link Minipass#off}
  428. */
  429. removeListener<Event extends keyof Events>(ev: Event, handler: (...args: Events[Event]) => any): this;
  430. /**
  431. * Mostly identical to `EventEmitter.off`
  432. *
  433. * If a 'data' event handler is removed, and it was the last consumer
  434. * (ie, there are no pipe destinations or other 'data' event listeners),
  435. * then the flow of data will stop until there is another consumer or
  436. * {@link Minipass#resume} is explicitly called.
  437. */
  438. off<Event extends keyof Events>(ev: Event, handler: (...args: Events[Event]) => any): this;
  439. /**
  440. * Mostly identical to `EventEmitter.removeAllListeners`
  441. *
  442. * If all 'data' event handlers are removed, and they were the last consumer
  443. * (ie, there are no pipe destinations), then the flow of data will stop
  444. * until there is another consumer or {@link Minipass#resume} is explicitly
  445. * called.
  446. */
  447. removeAllListeners<Event extends keyof Events>(ev?: Event): this;
  448. /**
  449. * true if the 'end' event has been emitted
  450. */
  451. get emittedEnd(): boolean;
  452. [MAYBE_EMIT_END](): void;
  453. /**
  454. * Mostly identical to `EventEmitter.emit`, with the following
  455. * behavior differences to prevent data loss and unnecessary hangs:
  456. *
  457. * If the stream has been destroyed, and the event is something other
  458. * than 'close' or 'error', then `false` is returned and no handlers
  459. * are called.
  460. *
  461. * If the event is 'end', and has already been emitted, then the event
  462. * is ignored. If the stream is in a paused or non-flowing state, then
  463. * the event will be deferred until data flow resumes. If the stream is
  464. * async, then handlers will be called on the next tick rather than
  465. * immediately.
  466. *
  467. * If the event is 'close', and 'end' has not yet been emitted, then
  468. * the event will be deferred until after 'end' is emitted.
  469. *
  470. * If the event is 'error', and an AbortSignal was provided for the stream,
  471. * and there are no listeners, then the event is ignored, matching the
  472. * behavior of node core streams in the presense of an AbortSignal.
  473. *
  474. * If the event is 'finish' or 'prefinish', then all listeners will be
  475. * removed after emitting the event, to prevent double-firing.
  476. */
  477. emit<Event extends keyof Events>(ev: Event, ...args: Events[Event]): boolean;
  478. [EMITDATA](data: RType): boolean;
  479. [EMITEND](): boolean;
  480. [EMITEND2](): boolean;
  481. /**
  482. * Return a Promise that resolves to an array of all emitted data once
  483. * the stream ends.
  484. */
  485. collect(): Promise<RType[] & {
  486. dataLength: number;
  487. }>;
  488. /**
  489. * Return a Promise that resolves to the concatenation of all emitted data
  490. * once the stream ends.
  491. *
  492. * Not allowed on objectMode streams.
  493. */
  494. concat(): Promise<RType>;
  495. /**
  496. * Return a void Promise that resolves once the stream ends.
  497. */
  498. promise(): Promise<void>;
  499. /**
  500. * Asynchronous `for await of` iteration.
  501. *
  502. * This will continue emitting all chunks until the stream terminates.
  503. */
  504. [Symbol.asyncIterator](): AsyncGenerator<RType, void, void>;
  505. /**
  506. * Synchronous `for of` iteration.
  507. *
  508. * The iteration will terminate when the internal buffer runs out, even
  509. * if the stream has not yet terminated.
  510. */
  511. [Symbol.iterator](): Generator<RType, void, void>;
  512. /**
  513. * Destroy a stream, preventing it from being used for any further purpose.
  514. *
  515. * If the stream has a `close()` method, then it will be called on
  516. * destruction.
  517. *
  518. * After destruction, any attempt to write data, read data, or emit most
  519. * events will be ignored.
  520. *
  521. * If an error argument is provided, then it will be emitted in an
  522. * 'error' event.
  523. */
  524. destroy(er?: unknown): this;
  525. /**
  526. * Alias for {@link isStream}
  527. *
  528. * Former export location, maintained for backwards compatibility.
  529. *
  530. * @deprecated
  531. */
  532. static get isStream(): (s: any) => s is Minipass<any, any, any> | NodeJS.ReadStream | NodeJS.WriteStream | (EventEmitter<any> & {
  533. end(): any;
  534. write(chunk: any, ...args: any[]): any;
  535. }) | (EventEmitter<any> & {
  536. pause(): any;
  537. resume(): any;
  538. pipe(...destArgs: any[]): any;
  539. }) | (NodeJS.ReadStream & {
  540. fd: number;
  541. }) | (NodeJS.WriteStream & {
  542. fd: number;
  543. });
  544. }
  545. //# sourceMappingURL=index.d.ts.map