@idlebox/stripe-node-types 24.0.14 → 24.0.15

package/fs/promises.d.ts

@@ -25,9 +25,9 @@
  */
 
 declare module "node:fs/promises" {
+    import { NonSharedBuffer } from 'node:buffer';
     import { Abortable } from 'node:events';
-    import { Stream } from 'node:stream';
-    import { ReadableStream } from 'node:stream/web';
+    import { Interface as ReadlineInterface } from '_not-use-node-type_readline';
     import {
         BigIntStats,
         BigIntStatsFs,
@@ -36,6 +36,7 @@ declare module "node:fs/promises" {
         CopyOptions,
         Dir,
         Dirent,
+        EncodingOption,
         GlobOptions,
         GlobOptionsWithFileTypes,
         GlobOptionsWithoutFileTypes,
@@ -45,10 +46,11 @@ declare module "node:fs/promises" {
         OpenDirOptions,
         OpenMode,
         PathLike,
+        ReadOptions,
+        ReadOptionsWithBuffer,
         ReadPosition,
         ReadStream,
         ReadVResult,
-        RmDirOptions,
         RmOptions,
         StatFsOptions,
         StatOptions,
@@ -56,11 +58,12 @@ declare module "node:fs/promises" {
         StatsFs,
         TimeLike,
         WatchEventType,
-        WatchOptions,
+        WatchOptions as _WatchOptions,
         WriteStream,
         WriteVResult,
     } from '_not-use-node-type_fs';
-    import { Interface as ReadlineInterface } from '_not-use-node-type_readline';
+    import { Stream } from 'node:stream';
+    import { ReadableStream } from 'node:stream/web';
     interface FileChangeInfo<T extends string | Buffer> {
         eventType: WatchEventType;
         filename: T | null;
@@ -73,6 +76,7 @@ declare module "node:fs/promises" {
         bytesRead: number;
         buffer: T;
     }
+    /** @deprecated This interface will be removed in a future version. Use `import { ReadOptionsWithBuffer } from "node:fs"` instead. */
     interface FileReadOptions<T extends NodeJS.ArrayBufferView = Buffer> {
         /**
          * @default `Buffer.alloc(0xffff)`
@@ -104,6 +108,9 @@ declare module "node:fs/promises" {
         highWaterMark?: number | undefined;
         flush?: boolean | undefined;
     }
+    interface ReadableWebStreamOptions {
+        autoClose?: boolean | undefined;
+    }
     // TODO: Add `EventEmitter` close
     interface FileHandle {
         /**
@@ -248,11 +255,13 @@ declare module "node:fs/promises" {
             length?: number | null,
             position?: ReadPosition | null,
         ): Promise<FileReadResult<T>>;
-        read<T extends NodeJS.ArrayBufferView = Buffer>(
+        read<T extends NodeJS.ArrayBufferView>(
             buffer: T,
-            options?: FileReadOptions<T>,
+            options?: ReadOptions,
+        ): Promise<FileReadResult<T>>;
+        read<T extends NodeJS.ArrayBufferView = NonSharedBuffer>(
+            options?: ReadOptionsWithBuffer<T>,
         ): Promise<FileReadResult<T>>;
-        read<T extends NodeJS.ArrayBufferView = Buffer>(options?: FileReadOptions<T>): Promise<FileReadResult<T>>;
         /**
          * Returns a byte-oriented `ReadableStream` that may be used to read the file's
          * contents.
@@ -277,7 +286,7 @@ declare module "node:fs/promises" {
          * close the `FileHandle` automatically. User code must still call the`fileHandle.close()` method.
          * @since v17.0.0
          */
-        readableWebStream(): ReadableStream;
+        readableWebStream(options?: ReadableWebStreamOptions): ReadableStream;
         /**
          * Asynchronously reads the entire contents of a file.
          *
@@ -296,7 +305,7 @@ declare module "node:fs/promises" {
             options?:
                 | ({ encoding?: null | undefined } & Abortable)
                 | null,
-        ): Promise<Buffer>;
+        ): Promise<NonSharedBuffer>;
         /**
          * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
          * The `FileHandle` must have been opened for reading.
@@ -315,7 +324,7 @@ declare module "node:fs/promises" {
                 | (ObjectEncodingOptions & Abortable)
                 | BufferEncoding
                 | null,
-        ): Promise<string | Buffer>;
+        ): Promise<string | NonSharedBuffer>;
         /**
          * Convenience method to create a `readline` interface and stream over the file.
          * See `filehandle.createReadStream()` for the options.
@@ -424,7 +433,7 @@ declare module "node:fs/promises" {
          * @param [position='null'] The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current
          * position. See the POSIX pwrite(2) documentation for more detail.
          */
-        write<TBuffer extends Uint8Array>(
+        write<TBuffer extends NodeJS.ArrayBufferView>(
             buffer: TBuffer,
             offset?: number | null,
             length?: number | null,
@@ -463,14 +472,20 @@ declare module "node:fs/promises" {
          * @param [position='null'] The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current
          * position.
          */
-        writev(buffers: readonly NodeJS.ArrayBufferView[], position?: number): Promise<WriteVResult>;
+        writev<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
+            buffers: TBuffers,
+            position?: number,
+        ): Promise<WriteVResult<TBuffers>>;
         /**
          * Read from a file and write to an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s
          * @since v13.13.0, v12.17.0
          * @param [position='null'] The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position.
          * @return Fulfills upon success an object containing two properties:
          */
-        readv(buffers: readonly NodeJS.ArrayBufferView[], position?: number): Promise<ReadVResult>;
+        readv<TBuffers extends readonly NodeJS.ArrayBufferView[]>(
+            buffers: TBuffers,
+            position?: number,
+        ): Promise<ReadVResult<TBuffers>>;
         /**
          * Closes the file handle after waiting for any pending operation on the handle to
          * complete.
@@ -490,8 +505,9 @@ declare module "node:fs/promises" {
          */
         close(): Promise<void>;
         /**
-         * An alias for {@link FileHandle.close()}.
-         * @since v20.4.0
+         * Calls `filehandle.close()` and returns a promise that fulfills when the
+         * filehandle is closed.
+         * @since v20.4.0, v18.8.0
          */
         [Symbol.asyncDispose](): Promise<void>;
     }
@@ -600,7 +616,7 @@ declare module "node:fs/promises" {
      * @since v10.0.0
      * @return Fulfills with `undefined` upon success.
      */
-    function rmdir(path: PathLike, options?: RmDirOptions): Promise<void>;
+    function rmdir(path: PathLike): Promise<void>;
     /**
      * Removes files and directories (modeled on the standard POSIX `rm` utility).
      * @since v14.14.0
@@ -706,7 +722,7 @@ declare module "node:fs/promises" {
                 recursive?: boolean | undefined;
             }
             | "buffer",
-    ): Promise<Buffer[]>;
+    ): Promise<NonSharedBuffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -721,7 +737,7 @@ declare module "node:fs/promises" {
             })
             | BufferEncoding
             | null,
-    ): Promise<string[] | Buffer[]>;
+    ): Promise<string[] | NonSharedBuffer[]>;
     /**
      * Asynchronous readdir(3) - read a directory.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -746,7 +762,7 @@ declare module "node:fs/promises" {
             withFileTypes: true;
             recursive?: boolean | undefined;
         },
-    ): Promise<Dirent<Buffer>[]>;
+    ): Promise<Dirent<NonSharedBuffer>[]>;
     /**
      * Reads the contents of the symbolic link referred to by `path`. See the POSIX [`readlink(2)`](http://man7.org/linux/man-pages/man2/readlink.2.html) documentation for more detail. The promise is
      * fulfilled with the`linkString` upon success.
@@ -764,13 +780,16 @@ declare module "node:fs/promises" {
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
-    function readlink(path: PathLike, options: BufferEncodingOption): Promise<Buffer>;
+    function readlink(path: PathLike, options: BufferEncodingOption): Promise<NonSharedBuffer>;
     /**
      * Asynchronous readlink(2) - read value of a symbolic link.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
-    function readlink(path: PathLike, options?: ObjectEncodingOptions | string | null): Promise<string | Buffer>;
+    function readlink(
+        path: PathLike,
+        options?: ObjectEncodingOptions | string | null,
+    ): Promise<string | NonSharedBuffer>;
     /**
      * Creates a symbolic link.
      *
@@ -921,7 +940,7 @@ declare module "node:fs/promises" {
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
-    function realpath(path: PathLike, options: BufferEncodingOption): Promise<Buffer>;
+    function realpath(path: PathLike, options: BufferEncodingOption): Promise<NonSharedBuffer>;
     /**
      * Asynchronous realpath(3) - return the canonicalized absolute pathname.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -930,7 +949,7 @@ declare module "node:fs/promises" {
     function realpath(
         path: PathLike,
         options?: ObjectEncodingOptions | BufferEncoding | null,
-    ): Promise<string | Buffer>;
+    ): Promise<string | NonSharedBuffer>;
     /**
      * Creates a unique temporary directory. A unique directory name is generated by
      * appending six random characters to the end of the provided `prefix`. Due to
@@ -966,13 +985,50 @@ declare module "node:fs/promises" {
      * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
-    function mkdtemp(prefix: string, options: BufferEncodingOption): Promise<Buffer>;
+    function mkdtemp(prefix: string, options: BufferEncodingOption): Promise<NonSharedBuffer>;
     /**
      * Asynchronously creates a unique temporary directory.
      * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory.
      * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
      */
-    function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
+    function mkdtemp(
+        prefix: string,
+        options?: ObjectEncodingOptions | BufferEncoding | null,
+    ): Promise<string | NonSharedBuffer>;
+    interface DisposableTempDir extends AsyncDisposable {
+        /**
+         * The path of the created directory.
+         */
+        path: string;
+        /**
+         * A function which removes the created directory.
+         */
+        remove(): Promise<void>;
+        /**
+         * The same as `remove`.
+         */
+        [Symbol.asyncDispose](): Promise<void>;
+    }
+    /**
+     * The resulting Promise holds an async-disposable object whose `path` property
+     * holds the created directory path. When the object is disposed, the directory
+     * and its contents will be removed asynchronously if it still exists. If the
+     * directory cannot be deleted, disposal will throw an error. The object has an
+     * async `remove()` method which will perform the same task.
+     *
+     * Both this function and the disposal function on the resulting object are
+     * async, so it should be used with `await` + `await using` as in
+     * `await using dir = await fsPromises.mkdtempDisposable('prefix')`.
+     *
+     * <!-- TODO: link MDN docs for disposables once https://github.com/mdn/content/pull/38027 lands -->
+     *
+     * For detailed information, see the documentation of `fsPromises.mkdtemp()`.
+     *
+     * The optional `options` argument can be a string specifying an encoding, or an
+     * object with an `encoding` property specifying the character encoding to use.
+     * @since v24.4.0
+     */
+    function mkdtempDisposable(prefix: PathLike, options?: EncodingOption): Promise<DisposableTempDir>;
     /**
      * Asynchronously writes data to a file, replacing the file if it already exists. `data` can be a string, a buffer, an
      * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an
@@ -1128,7 +1184,7 @@ declare module "node:fs/promises" {
                 flag?: OpenMode | undefined;
             } & Abortable)
             | null,
-    ): Promise<Buffer>;
+    ): Promise<NonSharedBuffer>;
     /**
      * Asynchronously reads the entire contents of a file.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
@@ -1164,7 +1220,7 @@ declare module "node:fs/promises" {
             )
             | BufferEncoding
             | null,
-    ): Promise<string | Buffer>;
+    ): Promise<string | NonSharedBuffer>;
     /**
      * Asynchronously open a directory for iterative scanning. See the POSIX [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html) documentation for more detail.
      *
@@ -1194,6 +1250,16 @@ declare module "node:fs/promises" {
      * @return Fulfills with an {fs.Dir}.
      */
     function opendir(path: PathLike, options?: OpenDirOptions): Promise<Dir>;
+    interface WatchOptions extends _WatchOptions {
+        maxQueue?: number | undefined;
+        overflow?: "ignore" | "throw" | undefined;
+    }
+    interface WatchOptionsWithBufferEncoding extends WatchOptions {
+        encoding: "buffer";
+    }
+    interface WatchOptionsWithStringEncoding extends WatchOptions {
+        encoding?: BufferEncoding | undefined;
+    }
     /**
      * Returns an async iterator that watches for changes on `filename`, where `filename`is either a file or a directory.
      *
@@ -1226,33 +1292,16 @@ declare module "node:fs/promises" {
      */
     function watch(
         filename: PathLike,
-        options:
-            | (WatchOptions & {
-                encoding: "buffer";
-            })
-            | "buffer",
-    ): AsyncIterable<FileChangeInfo<Buffer>>;
-    /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the encoding for the filename provided to the listener, or an object optionally specifying encoding, persistent, and recursive options.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `persistent` is not supplied, the default of `true` is used.
-     * If `recursive` is not supplied, the default of `false` is used.
-     */
-    function watch(filename: PathLike, options?: WatchOptions | BufferEncoding): AsyncIterable<FileChangeInfo<string>>;
-    /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the encoding for the filename provided to the listener, or an object optionally specifying encoding, persistent, and recursive options.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `persistent` is not supplied, the default of `true` is used.
-     * If `recursive` is not supplied, the default of `false` is used.
-     */
+        options?: WatchOptionsWithStringEncoding | BufferEncoding,
+    ): NodeJS.AsyncIterator<FileChangeInfo<string>>;
+    function watch(
+        filename: PathLike,
+        options: WatchOptionsWithBufferEncoding | "buffer",
+    ): NodeJS.AsyncIterator<FileChangeInfo<NonSharedBuffer>>;
     function watch(
         filename: PathLike,
-        options: WatchOptions | string,
-    ): AsyncIterable<FileChangeInfo<string>> | AsyncIterable<FileChangeInfo<Buffer>>;
+        options: WatchOptions | BufferEncoding | "buffer",
+    ): NodeJS.AsyncIterator<FileChangeInfo<string | NonSharedBuffer>>;
     /**
      * Asynchronously copies the entire directory structure from `src` to `dest`,
      * including subdirectories and files.