streams.d.ts

// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
// Copyright DefinitelyTyped contributors. All rights reserved. MIT license.
// deno-lint-ignore-file no-explicit-any

import * as stream from "../../_stream.d.ts";
import * as promises from "../../fs/promises.ts";

import { Buffer } from "../../buffer.ts";
import { BufferEncoding, ErrnoException } from "../../_global.d.ts";

type PathLike = string | Buffer | URL;

/**
 * Instances of `fs.ReadStream` are created and returned using the {@link createReadStream} function.
 * @since v0.1.93
 */
export class ReadStream extends stream.Readable {
  close(callback?: (err?: ErrnoException | null) => void): void;
  /**
   * The number of bytes that have been read so far.
   * @since v6.4.0
   */
  bytesRead: number;
  /**
   * The path to the file the stream is reading from as specified in the first
   * argument to `fs.createReadStream()`. If `path` is passed as a string, then`readStream.path` will be a string. If `path` is passed as a `Buffer`, then`readStream.path` will be a
   * `Buffer`. If `fd` is specified, then`readStream.path` will be `undefined`.
   * @since v0.1.93
   */
  path: string | Buffer;
  /**
   * This property is `true` if the underlying file has not been opened yet,
   * i.e. before the `'ready'` event is emitted.
   * @since v11.2.0, v10.16.0
   */
  pending: boolean;
  /**
   * events.EventEmitter
   *   1. open
   *   2. close
   *   3. ready
   */
  addListener(event: "close", listener: () => void): this;
  addListener(event: "data", listener: (chunk: Buffer | string) => void): this;
  addListener(event: "end", listener: () => void): this;
  addListener(event: "error", listener: (err: Error) => void): this;
  addListener(event: "open", listener: (fd: number) => void): this;
  addListener(event: "pause", listener: () => void): this;
  addListener(event: "readable", listener: () => void): this;
  addListener(event: "ready", listener: () => void): this;
  addListener(event: "resume", listener: () => void): this;
  addListener(event: string | symbol, listener: (...args: any[]) => void): this;
  on(event: "close", listener: () => void): this;
  on(event: "data", listener: (chunk: Buffer | string) => void): this;
  on(event: "end", listener: () => void): this;
  on(event: "error", listener: (err: Error) => void): this;
  on(event: "open", listener: (fd: number) => void): this;
  on(event: "pause", listener: () => void): this;
  on(event: "readable", listener: () => void): this;
  on(event: "ready", listener: () => void): this;
  on(event: "resume", listener: () => void): this;
  on(event: string | symbol, listener: (...args: any[]) => void): this;
  once(event: "close", listener: () => void): this;
  once(event: "data", listener: (chunk: Buffer | string) => void): this;
  once(event: "end", listener: () => void): this;
  once(event: "error", listener: (err: Error) => void): this;
  once(event: "open", listener: (fd: number) => void): this;
  once(event: "pause", listener: () => void): this;
  once(event: "readable", listener: () => void): this;
  once(event: "ready", listener: () => void): this;
  once(event: "resume", listener: () => void): this;
  once(event: string | symbol, listener: (...args: any[]) => void): this;
  prependListener(event: "close", listener: () => void): this;
  prependListener(
    event: "data",
    listener: (chunk: Buffer | string) => void,
  ): this;
  prependListener(event: "end", listener: () => void): this;
  prependListener(event: "error", listener: (err: Error) => void): this;
  prependListener(event: "open", listener: (fd: number) => void): this;
  prependListener(event: "pause", listener: () => void): this;
  prependListener(event: "readable", listener: () => void): this;
  prependListener(event: "ready", listener: () => void): this;
  prependListener(event: "resume", listener: () => void): this;
  prependListener(
    event: string | symbol,
    listener: (...args: any[]) => void,
  ): this;
  prependOnceListener(event: "close", listener: () => void): this;
  prependOnceListener(
    event: "data",
    listener: (chunk: Buffer | string) => void,
  ): this;
  prependOnceListener(event: "end", listener: () => void): this;
  prependOnceListener(event: "error", listener: (err: Error) => void): this;
  prependOnceListener(event: "open", listener: (fd: number) => void): this;
  prependOnceListener(event: "pause", listener: () => void): this;
  prependOnceListener(event: "readable", listener: () => void): this;
  prependOnceListener(event: "ready", listener: () => void): this;
  prependOnceListener(event: "resume", listener: () => void): this;
  prependOnceListener(
    event: string | symbol,
    listener: (...args: any[]) => void,
  ): this;
}
/**
 * * Extends `stream.Writable`
 *
 * Instances of `fs.WriteStream` are created and returned using the {@link createWriteStream} function.
 * @since v0.1.93
 */
export class WriteStream extends stream.Writable {
  /**
   * Closes `writeStream`. Optionally accepts a
   * callback that will be executed once the `writeStream`is closed.
   * @since v0.9.4
   */
  close(callback?: (err?: ErrnoException | null) => void): void;
  /**
   * The number of bytes written so far. Does not include data that is still queued
   * for writing.
   * @since v0.4.7
   */
  bytesWritten: number;
  /**
   * The path to the file the stream is writing to as specified in the first
   * argument to {@link createWriteStream}. If `path` is passed as a string, then`writeStream.path` will be a string. If `path` is passed as a `Buffer`, then`writeStream.path` will be a
   * `Buffer`.
   * @since v0.1.93
   */
  path: string | Buffer;
  /**
   * This property is `true` if the underlying file has not been opened yet,
   * i.e. before the `'ready'` event is emitted.
   * @since v11.2.0
   */
  pending: boolean;
  /**
   * events.EventEmitter
   *   1. open
   *   2. close
   *   3. ready
   */
  addListener(event: "close", listener: () => void): this;
  addListener(event: "drain", listener: () => void): this;
  addListener(event: "error", listener: (err: Error) => void): this;
  addListener(event: "finish", listener: () => void): this;
  addListener(event: "open", listener: (fd: number) => void): this;
  addListener(event: "pipe", listener: (src: stream.Readable) => void): this;
  addListener(event: "ready", listener: () => void): this;
  addListener(event: "unpipe", listener: (src: stream.Readable) => void): this;
  addListener(event: string | symbol, listener: (...args: any[]) => void): this;
  on(event: "close", listener: () => void): this;
  on(event: "drain", listener: () => void): this;
  on(event: "error", listener: (err: Error) => void): this;
  on(event: "finish", listener: () => void): this;
  on(event: "open", listener: (fd: number) => void): this;
  on(event: "pipe", listener: (src: stream.Readable) => void): this;
  on(event: "ready", listener: () => void): this;
  on(event: "unpipe", listener: (src: stream.Readable) => void): this;
  on(event: string | symbol, listener: (...args: any[]) => void): this;
  once(event: "close", listener: () => void): this;
  once(event: "drain", listener: () => void): this;
  once(event: "error", listener: (err: Error) => void): this;
  once(event: "finish", listener: () => void): this;
  once(event: "open", listener: (fd: number) => void): this;
  once(event: "pipe", listener: (src: stream.Readable) => void): this;
  once(event: "ready", listener: () => void): this;
  once(event: "unpipe", listener: (src: stream.Readable) => void): this;
  once(event: string | symbol, listener: (...args: any[]) => void): this;
  prependListener(event: "close", listener: () => void): this;
  prependListener(event: "drain", listener: () => void): this;
  prependListener(event: "error", listener: (err: Error) => void): this;
  prependListener(event: "finish", listener: () => void): this;
  prependListener(event: "open", listener: (fd: number) => void): this;
  prependListener(
    event: "pipe",
    listener: (src: stream.Readable) => void,
  ): this;
  prependListener(event: "ready", listener: () => void): this;
  prependListener(
    event: "unpipe",
    listener: (src: stream.Readable) => void,
  ): this;
  prependListener(
    event: string | symbol,
    listener: (...args: any[]) => void,
  ): this;
  prependOnceListener(event: "close", listener: () => void): this;
  prependOnceListener(event: "drain", listener: () => void): this;
  prependOnceListener(event: "error", listener: (err: Error) => void): this;
  prependOnceListener(event: "finish", listener: () => void): this;
  prependOnceListener(event: "open", listener: (fd: number) => void): this;
  prependOnceListener(
    event: "pipe",
    listener: (src: stream.Readable) => void,
  ): this;
  prependOnceListener(event: "ready", listener: () => void): this;
  prependOnceListener(
    event: "unpipe",
    listener: (src: stream.Readable) => void,
  ): this;
  prependOnceListener(
    event: string | symbol,
    listener: (...args: any[]) => void,
  ): this;
}
interface StreamOptions {
  flags?: string | undefined;
  encoding?: BufferEncoding | undefined;
  // @ts-ignore promises.FileHandle is not implemented
  fd?: number | promises.FileHandle | undefined;
  mode?: number | undefined;
  autoClose?: boolean | undefined;
  /**
   * @default false
   */
  emitClose?: boolean | undefined;
  start?: number | undefined;
  highWaterMark?: number | undefined;
}
interface ReadStreamOptions extends StreamOptions {
  end?: number | undefined;
}
/**
 * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream
 * returned by this method has a default `highWaterMark` of 64 kb.
 *
 * `options` can include `start` and `end` values to read a range of bytes from
 * the file instead of the entire file. Both `start` and `end` are inclusive and
 * start counting at 0, allowed values are in the
 * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. If `fd` is specified and `start` is
 * omitted or `undefined`, `fs.createReadStream()` reads sequentially from the
 * current file position. The `encoding` can be any one of those accepted by `Buffer`.
 *
 * If `fd` is specified, `ReadStream` will ignore the `path` argument and will use
 * the specified file descriptor. This means that no `'open'` event will be
 * emitted. `fd` should be blocking; non-blocking `fd`s should be passed to `net.Socket`.
 *
 * If `fd` points to a character device that only supports blocking reads
 * (such as keyboard or sound card), read operations do not finish until data is
 * available. This can prevent the process from exiting and the stream from
 * closing naturally.
 *
 * By default, the stream will emit a `'close'` event after it has been
 * destroyed.  Set the `emitClose` option to `false` to change this behavior.
 *
 * By providing the `fs` option, it is possible to override the corresponding `fs`implementations for `open`, `read`, and `close`. When providing the `fs` option,
 * an override for `read` is required. If no `fd` is provided, an override for`open` is also required. If `autoClose` is `true`, an override for `close` is
 * also required.
 *
 * ```js
 * import { createReadStream } from 'fs';
 *
 * // Create a stream from some character device.
 * const stream = createReadStream('/dev/input/event0');
 * setTimeout(() => {
 *   stream.close(); // This may not close the stream.
 *   // Artificially marking end-of-stream, as if the underlying resource had
 *   // indicated end-of-file by itself, allows the stream to close.
 *   // This does not cancel pending read operations, and if there is such an
 *   // operation, the process may still not be able to exit successfully
 *   // until it finishes.
 *   stream.push(null);
 *   stream.read(0);
 * }, 100);
 * ```
 *
 * If `autoClose` is false, then the file descriptor won't be closed, even if
 * there's an error. It is the application's responsibility to close it and make
 * sure there's no file descriptor leak. If `autoClose` is set to true (default
 * behavior), on `'error'` or `'end'` the file descriptor will be closed
 * automatically.
 *
 * `mode` sets the file mode (permission and sticky bits), but only if the
 * file was created.
 *
 * An example to read the last 10 bytes of a file which is 100 bytes long:
 *
 * ```js
 * import { createReadStream } from 'fs';
 *
 * createReadStream('sample.txt', { start: 90, end: 99 });
 * ```
 *
 * If `options` is a string, then it specifies the encoding.
 * @since v0.1.31
 */
export function createReadStream(
  path: PathLike,
  options?: BufferEncoding | ReadStreamOptions,
): ReadStream;
/**
 * `options` may also include a `start` option to allow writing data at some
 * position past the beginning of the file, allowed values are in the
 * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than
 * replacing it may require the `flags` option to be set to `r+` rather than the
 * default `w`. The `encoding` can be any one of those accepted by `Buffer`.
 *
 * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false,
 * then the file descriptor won't be closed, even if there's an error.
 * It is the application's responsibility to close it and make sure there's no
 * file descriptor leak.
 *
 * By default, the stream will emit a `'close'` event after it has been
 * destroyed.  Set the `emitClose` option to `false` to change this behavior.
 *
 * By providing the `fs` option it is possible to override the corresponding `fs`implementations for `open`, `write`, `writev` and `close`. Overriding `write()`without `writev()` can reduce
 * performance as some optimizations (`_writev()`)
 * will be disabled. When providing the `fs` option, overrides for at least one of`write` and `writev` are required. If no `fd` option is supplied, an override
 * for `open` is also required. If `autoClose` is `true`, an override for `close`is also required.
 *
 * Like `fs.ReadStream`, if `fd` is specified, `fs.WriteStream` will ignore the`path` argument and will use the specified file descriptor. This means that no`'open'` event will be
 * emitted. `fd` should be blocking; non-blocking `fd`s
 * should be passed to `net.Socket`.
 *
 * If `options` is a string, then it specifies the encoding.
 * @since v0.1.31
 */
export function createWriteStream(
  path: PathLike,
  options?: BufferEncoding | StreamOptions,
): WriteStream;