@zenfs/core 0.9.6 → 0.9.7

package/dist/emulation/promises.d.ts

@@ -4,17 +4,18 @@
 /// <reference types="node" resolution-mode="require"/>
 /// <reference types="node" resolution-mode="require"/>
 /// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
 import { Buffer } from 'buffer';
-import type * as Node from 'node:fs';
+import type * as fs from 'node:fs';
 import type * as promises from 'node:fs/promises';
 import type { CreateReadStreamOptions, CreateWriteStreamOptions, FileChangeInfo, FileReadResult, FlagAndOpenMode } from 'node:fs/promises';
+import type { Stream } from 'node:stream';
 import type { ReadableStream as TReadableStream } from 'node:stream/web';
 import type { Interface as ReadlineInterface } from 'readline';
 import { File } from '../file.js';
 import { FileContents } from '../filesystem.js';
 import { BigIntStats, type BigIntStatsFs, type Stats, type StatsFs } from '../stats.js';
 import { Dir, Dirent } from './dir.js';
-import type { PathLike } from './shared.js';
 import { ReadStream, WriteStream } from './streams.js';
 export * as constants from './constants.js';
 export declare class FileHandle implements promises.FileHandle {
@@ -39,7 +40,7 @@ export declare class FileHandle implements promises.FileHandle {
      * Asynchronous fchmod(2) - Change permissions of a file.
      * @param mode A file mode. If a string is passed, it is parsed as an octal integer.
      */
-    chmod(mode: Node.Mode): Promise<void>;
+    chmod(mode: fs.Mode): Promise<void>;
     /**
      * Asynchronous fdatasync(2) - synchronize a file's in-core state with storage device.
      */
@@ -52,7 +53,7 @@ export declare class FileHandle implements promises.FileHandle {
      * Asynchronous ftruncate(2) - Truncate a file to a specified length.
      * @param len If not specified, defaults to `0`.
      */
-    truncate(len?: number): Promise<void>;
+    truncate(len?: number | null): Promise<void>;
     /**
      * Asynchronously change file timestamps of the file.
      * @param atime The last access time. If a string is provided, it will be coerced to number.
@@ -69,7 +70,7 @@ export declare class FileHandle implements promises.FileHandle {
      * If `mode` is a string, it is parsed as an octal integer.
      * If `flag` is not supplied, the default of `'a'` is used.
      */
-    appendFile(data: string | Uint8Array, _options?: (Node.ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding): Promise<void>;
+    appendFile(data: string | Uint8Array, _options?: (fs.ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding): Promise<void>;
     /**
      * Asynchronously reads data from the file.
      * The `FileHandle` must have been opened for reading.
@@ -78,7 +79,7 @@ export declare class FileHandle implements promises.FileHandle {
      * @param length The number of bytes to read.
      * @param position The offset from the beginning of the file from which data should be read. If `null`, data will be read from the current position.
      */
-    read<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<FileReadResult<TBuffer>>;
+    read<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number | null): Promise<FileReadResult<TBuffer>>;
     /**
      * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
      * The `FileHandle` must have been opened for reading.
@@ -86,9 +87,9 @@ export declare class FileHandle implements promises.FileHandle {
      * If a flag is not provided, it defaults to `'r'`.
      */
     readFile(_options?: {
-        flag?: Node.OpenMode;
+        flag?: fs.OpenMode;
     }): Promise<Buffer>;
-    readFile(_options: (Node.ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding): Promise<string>;
+    readFile(_options: (fs.ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding): Promise<string>;
     /**
      * Returns a `ReadableStream` that may be used to read the files data.
      *
@@ -106,35 +107,24 @@ export declare class FileHandle implements promises.FileHandle {
     /**
      * Asynchronous fstat(2) - Get file status.
      */
-    stat(opts: Node.BigIntOptions): Promise<BigIntStats>;
-    stat(opts?: Node.StatOptions & {
+    stat(opts: fs.BigIntOptions): Promise<BigIntStats>;
+    stat(opts?: fs.StatOptions & {
         bigint?: false;
     }): Promise<Stats>;
-    write(data: FileContents, posOrOff?: number, lenOrEnc?: BufferEncoding | number, position?: number): Promise<{
-        bytesWritten: number;
-        buffer: FileContents;
-    }>;
     /**
-     * Asynchronously writes `buffer` to the file.
+     * Asynchronously writes `string` to the file.
      * The `FileHandle` must have been opened for writing.
-     * @param buffer The buffer that the data will be written to.
-     * @param offset The part of the buffer to be written. If not supplied, defaults to `0`.
-     * @param length The number of bytes to write. If not supplied, defaults to `buffer.length - offset`.
-     * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position.
+     * It is unsafe to call `write()` multiple times on the same file without waiting for the `Promise`
+     * to be resolved (or rejected). For this scenario, `fs.createWriteStream` is strongly recommended.
      */
+    write(data: FileContents, posOrOff?: number | null, lenOrEnc?: BufferEncoding | number, position?: number | null): Promise<{
+        bytesWritten: number;
+        buffer: FileContents;
+    }>;
     write<TBuffer extends Uint8Array>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
         bytesWritten: number;
         buffer: TBuffer;
     }>;
-    /**
-     * Asynchronously writes `string` to the file.
-     * The `FileHandle` must have been opened for writing.
-     * It is unsafe to call `write()` multiple times on the same file without waiting for the `Promise`
-     * to be resolved (or rejected). For this scenario, `fs.createWriteStream` is strongly recommended.
-     * @param string A string to write.
-     * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position.
-     * @param encoding The expected string encoding.
-     */
     write(data: string, position?: number, encoding?: BufferEncoding): Promise<{
         bytesWritten: number;
         buffer: string;
@@ -150,7 +140,7 @@ export declare class FileHandle implements promises.FileHandle {
      * If `mode` is a string, it is parsed as an octal integer.
      * If `flag` is not supplied, the default of `'w'` is used.
      */
-    writeFile(data: string | Uint8Array, _options?: Node.WriteFileOptions): Promise<void>;
+    writeFile(data: string | Uint8Array, _options?: fs.WriteFileOptions): Promise<void>;
     /**
      * Asynchronous close(2) - close a `FileHandle`.
      */
@@ -161,14 +151,14 @@ export declare class FileHandle implements promises.FileHandle {
      * @param position The position in the file where to begin writing.
      * @returns The number of bytes written.
      */
-    writev(buffers: Uint8Array[], position?: number): Promise<Node.WriteVResult>;
+    writev(buffers: Uint8Array[], position?: number): Promise<fs.WriteVResult>;
     /**
      * Asynchronous `readv`. Reads into multiple buffers.
      * @param buffers An array of Uint8Array buffers.
      * @param position The position in the file where to begin reading.
      * @returns The number of bytes read.
      */
-    readv(buffers: NodeJS.ArrayBufferView[], position?: number): Promise<Node.ReadVResult>;
+    readv(buffers: NodeJS.ArrayBufferView[], position?: number): Promise<fs.ReadVResult>;
     /**
      * Creates a `ReadStream` for reading from the file.
      *
@@ -189,22 +179,22 @@ export declare class FileHandle implements promises.FileHandle {
  * @param oldPath
  * @param newPath
  */
-export declare function rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
+export declare function rename(oldPath: fs.PathLike, newPath: fs.PathLike): Promise<void>;
 /**
  * Test whether or not the given path exists by checking with the file system.
  * @param _path
  */
-export declare function exists(_path: PathLike): Promise<boolean>;
+export declare function exists(_path: fs.PathLike): Promise<boolean>;
 /**
  * `stat`.
  * @param path
  * @returns Stats
  */
-export declare function stat(path: PathLike, options: Node.BigIntOptions): Promise<BigIntStats>;
-export declare function stat(path: PathLike, options?: {
+export declare function stat(path: fs.PathLike, options: fs.BigIntOptions): Promise<BigIntStats>;
+export declare function stat(path: fs.PathLike, options?: {
     bigint?: false;
 }): Promise<Stats>;
-export declare function stat(path: PathLike, options?: Node.StatOptions): Promise<Stats | BigIntStats>;
+export declare function stat(path: fs.PathLike, options?: fs.StatOptions): Promise<Stats | BigIntStats>;
 /**
  * `lstat`.
  * `lstat()` is identical to `stat()`, except that if path is a symbolic link,
@@ -212,10 +202,10 @@ export declare function stat(path: PathLike, options?: Node.StatOptions): Promis
  * @param path
  * @return
  */
-export declare function lstat(path: PathLike, options?: {
-    bigint?: false;
+export declare function lstat(path: fs.PathLike, options?: {
+    bigint?: boolean;
 }): Promise<Stats>;
-export declare function lstat(path: PathLike, options: {
+export declare function lstat(path: fs.PathLike, options: {
     bigint: true;
 }): Promise<BigIntStats>;
 /**
@@ -223,24 +213,19 @@ export declare function lstat(path: PathLike, options: {
  * @param path
  * @param len
  */
-export declare function truncate(path: PathLike, len?: number): Promise<void>;
+export declare function truncate(path: fs.PathLike, len?: number): Promise<void>;
 /**
  * `unlink`.
  * @param path
  */
-export declare function unlink(path: PathLike): Promise<void>;
+export declare function unlink(path: fs.PathLike): Promise<void>;
 /**
  * Asynchronous file open.
  * @see http://www.manpagez.com/man/2/open/
  * @param flags Handles the complexity of the various file modes. See its API for more details.
  * @param mode Mode to use to open the file. Can be ignored if the filesystem doesn't support permissions.
  */
-export declare function open(path: PathLike, flag: string, mode?: Node.Mode): Promise<FileHandle>;
-/**
- * Opens a file without resolving symlinks
- * @internal
- */
-export declare function lopen(path: PathLike, flag: string, mode?: Node.Mode): Promise<FileHandle>;
+export declare function open(path: fs.PathLike, flag?: fs.OpenMode, mode?: fs.Mode): Promise<FileHandle>;
 /**
  * Asynchronously reads the entire contents of a file.
  * @param filename
@@ -249,126 +234,146 @@ export declare function lopen(path: PathLike, flag: string, mode?: Node.Mode): P
  * options.flag Defaults to `'r'`.
  * @returns file data
  */
-export declare function readFile(filename: PathLike, options?: {
-    flag?: Node.OpenMode;
-}): Promise<Buffer>;
-export declare function readFile(filename: PathLike, options: (Node.EncodingOption & {
-    flag?: Node.OpenMode;
-}) | BufferEncoding): Promise<string>;
+export declare function readFile(path: fs.PathLike | promises.FileHandle, options?: {
+    encoding?: null;
+    flag?: fs.OpenMode;
+} | null): Promise<Buffer>;
+export declare function readFile(path: fs.PathLike | promises.FileHandle, options: {
+    encoding: BufferEncoding;
+    flag?: fs.OpenMode;
+} | BufferEncoding): Promise<string>;
+export declare function readFile(path: fs.PathLike | promises.FileHandle, options?: (fs.ObjectEncodingOptions & {
+    flag?: fs.OpenMode;
+}) | BufferEncoding | null): Promise<string | Buffer>;
 /**
  * Asynchronously writes data to a file, replacing the file if it already exists.
  *
  * The encoding option is ignored if data is a buffer.
- * @param filename
- * @param data
+ * @param path
+ * @param data Note:
  * @param _options
  * @option options encoding Defaults to `'utf8'`.
  * @option options mode Defaults to `0644`.
  * @option options flag Defaults to `'w'`.
  */
-export declare function writeFile(filename: PathLike, data: FileContents, _options?: Node.WriteFileOptions): Promise<void>;
+export declare function writeFile(path: fs.PathLike | promises.FileHandle, data: FileContents | Stream | Iterable<string | ArrayBufferView> | AsyncIterable<string | ArrayBufferView>, _options?: (fs.ObjectEncodingOptions & {
+    mode?: fs.Mode;
+    flag?: fs.OpenMode;
+    flush?: boolean;
+}) | BufferEncoding | null): Promise<void>;
 /**
  * Asynchronously append data to a file, creating the file if it not yet
  * exists.
- * @param filename
+ * @param path
  * @param data
  * @param options
  * @option options encoding Defaults to `'utf8'`.
  * @option options mode Defaults to `0644`.
  * @option options flag Defaults to `'a'`.
  */
-export declare function appendFile(filename: PathLike, data: FileContents, _options?: BufferEncoding | (Node.EncodingOption & {
-    mode?: Node.Mode;
-    flag?: Node.OpenMode;
-})): Promise<void>;
+export declare function appendFile(path: fs.PathLike | promises.FileHandle, data: FileContents, _options?: BufferEncoding | (fs.EncodingOption & {
+    mode?: fs.Mode;
+    flag?: fs.OpenMode;
+}) | null): Promise<void>;
 /**
  * `rmdir`.
  * @param path
  */
-export declare function rmdir(path: PathLike): Promise<void>;
+export declare function rmdir(path: fs.PathLike): Promise<void>;
 /**
- * `mkdir`.
- * @param path
- * @param mode defaults to `0777`
+ * Asynchronous mkdir(2) - create a directory.
+ * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+ * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders
+ * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`.
  */
-export declare function mkdir(path: PathLike, mode?: Node.Mode | (Node.MakeDirectoryOptions & {
-    recursive?: false;
-})): Promise<void>;
-export declare function mkdir(path: PathLike, mode: Node.MakeDirectoryOptions & {
+export declare function mkdir(path: fs.PathLike, options: fs.MakeDirectoryOptions & {
     recursive: true;
-}): Promise<string>;
+}): Promise<string | undefined>;
+export declare function mkdir(path: fs.PathLike, options?: fs.Mode | (fs.MakeDirectoryOptions & {
+    recursive?: false | undefined;
+}) | null): Promise<void>;
+export declare function mkdir(path: fs.PathLike, options?: fs.Mode | fs.MakeDirectoryOptions | null): Promise<string | undefined>;
 /**
- * `readdir`. Reads the contents of a directory.
- * @param path
+ * Asynchronous readdir(3) - read a directory.
+ * @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.
  */
-export declare function readdir(path: PathLike, options?: (Node.EncodingOption & {
+export declare function readdir(path: fs.PathLike, options?: (fs.ObjectEncodingOptions & {
     withFileTypes?: false;
-}) | BufferEncoding): Promise<string[]>;
-export declare function readdir(path: PathLike, options: Node.BufferEncodingOption & {
+    recursive?: boolean;
+}) | BufferEncoding | null): Promise<string[]>;
+export declare function readdir(path: fs.PathLike, options: fs.BufferEncodingOption & {
     withFileTypes?: false;
+    recursive?: boolean;
 }): Promise<Buffer[]>;
-export declare function readdir(path: PathLike, options: Node.EncodingOption & {
+export declare function readdir(path: fs.PathLike, options?: (fs.ObjectEncodingOptions & {
+    withFileTypes?: false;
+    recursive?: boolean;
+}) | BufferEncoding | null): Promise<string[] | Buffer[]>;
+export declare function readdir(path: fs.PathLike, options: fs.ObjectEncodingOptions & {
     withFileTypes: true;
+    recursive?: boolean;
 }): Promise<Dirent[]>;
 /**
  * `link`.
  * @param existing
  * @param newpath
  */
-export declare function link(existing: PathLike, newpath: PathLike): Promise<void>;
+export declare function link(existing: fs.PathLike, newpath: fs.PathLike): Promise<void>;
 /**
  * `symlink`.
  * @param target target path
  * @param path link path
  * @param type can be either `'dir'` or `'file'` (default is `'file'`)
  */
-export declare function symlink(target: PathLike, path: PathLike, type?: Node.symlink.Type): Promise<void>;
+export declare function symlink(target: fs.PathLike, path: fs.PathLike, type?: fs.symlink.Type | string | null): Promise<void>;
 /**
  * readlink.
  * @param path
  */
-export declare function readlink(path: PathLike, options: Node.BufferEncodingOption): Promise<Buffer>;
-export declare function readlink(path: PathLike, options?: Node.EncodingOption | BufferEncoding): Promise<string>;
+export declare function readlink(path: fs.PathLike, options: fs.BufferEncodingOption): Promise<Buffer>;
+export declare function readlink(path: fs.PathLike, options?: fs.EncodingOption | null): Promise<string>;
+export declare function readlink(path: fs.PathLike, options?: fs.BufferEncodingOption | fs.EncodingOption | string | null): Promise<string | Buffer>;
 /**
  * `chown`.
  * @param path
  * @param uid
  * @param gid
  */
-export declare function chown(path: PathLike, uid: number, gid: number): Promise<void>;
+export declare function chown(path: fs.PathLike, uid: number, gid: number): Promise<void>;
 /**
  * `lchown`.
  * @param path
  * @param uid
  * @param gid
  */
-export declare function lchown(path: PathLike, uid: number, gid: number): Promise<void>;
+export declare function lchown(path: fs.PathLike, uid: number, gid: number): Promise<void>;
 /**
  * `chmod`.
  * @param path
  * @param mode
  */
-export declare function chmod(path: PathLike, mode: Node.Mode): Promise<void>;
+export declare function chmod(path: fs.PathLike, mode: fs.Mode): Promise<void>;
 /**
  * `lchmod`.
  * @param path
  * @param mode
  */
-export declare function lchmod(path: PathLike, mode: Node.Mode): Promise<void>;
+export declare function lchmod(path: fs.PathLike, mode: fs.Mode): Promise<void>;
 /**
  * Change file timestamps of the file referenced by the supplied path.
  * @param path
  * @param atime
  * @param mtime
  */
-export declare function utimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise<void>;
+export declare function utimes(path: fs.PathLike, atime: string | number | Date, mtime: string | number | Date): Promise<void>;
 /**
  * Change file timestamps of the file referenced by the supplied path.
  * @param path
  * @param atime
  * @param mtime
  */
-export declare function lutimes(path: PathLike, atime: number | Date, mtime: number | Date): Promise<void>;
+export declare function lutimes(path: fs.PathLike, atime: fs.TimeLike, mtime: fs.TimeLike): Promise<void>;
 /**
  * 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.
@@ -376,34 +381,33 @@ export declare function lutimes(path: PathLike, atime: number | Date, mtime: num
  *
  * Note: This *Can not* use doOp since doOp depends on it
  */
-export declare function realpath(path: PathLike, options: Node.BufferEncodingOption): Promise<Buffer>;
-export declare function realpath(path: PathLike, options?: Node.EncodingOption | BufferEncoding): Promise<string>;
+export declare function realpath(path: fs.PathLike, options: fs.BufferEncodingOption): Promise<Buffer>;
+export declare function realpath(path: fs.PathLike, options?: fs.EncodingOption | BufferEncoding): Promise<string>;
 /**
  * @todo Implement
  */
-export declare function watch(filename: PathLike, options: (Node.WatchOptions & {
-    encoding: 'buffer';
-}) | 'buffer'): AsyncIterable<FileChangeInfo<Buffer>>;
-export declare function watch(filename: PathLike, options?: Node.WatchOptions | BufferEncoding): AsyncIterable<FileChangeInfo<string>>;
+export declare function watch(filename: fs.PathLike, options?: fs.WatchOptions | BufferEncoding): AsyncIterable<FileChangeInfo<string>>;
+export declare function watch(filename: fs.PathLike, options: fs.WatchOptions | fs.BufferEncodingOption): AsyncIterable<FileChangeInfo<Buffer>>;
+export declare function watch(filename: fs.PathLike, options?: fs.WatchOptions | string): AsyncIterable<FileChangeInfo<string>> | AsyncIterable<FileChangeInfo<Buffer>>;
 /**
  * `access`.
  * @param path
  * @param mode
  */
-export declare function access(path: PathLike, mode?: number): Promise<void>;
+export declare function access(path: fs.PathLike, mode?: number): Promise<void>;
 /**
  * Asynchronous `rm`. Removes files or directories (recursively).
  * @param path The path to the file or directory to remove.
  */
-export declare function rm(path: PathLike, options?: Node.RmOptions): Promise<void>;
+export declare function rm(path: fs.PathLike, options?: fs.RmOptions): Promise<void>;
 /**
  * Asynchronous `mkdtemp`. Creates a unique temporary directory.
  * @param prefix The directory prefix.
  * @param options The encoding (or an object including `encoding`).
  * @returns The path to the created temporary directory, encoded as a string or buffer.
  */
-export declare function mkdtemp(prefix: string, options?: Node.EncodingOption): Promise<string>;
-export declare function mkdtemp(prefix: string, options?: Node.BufferEncodingOption): Promise<Buffer>;
+export declare function mkdtemp(prefix: string, options?: fs.EncodingOption): Promise<string>;
+export declare function mkdtemp(prefix: string, options?: fs.BufferEncodingOption): Promise<Buffer>;
 /**
  * Asynchronous `copyFile`. Copies a file.
  * @param src The source file.
@@ -411,14 +415,14 @@ export declare function mkdtemp(prefix: string, options?: Node.BufferEncodingOpt
  * @param mode Optional flags for the copy operation. Currently supports these flags:
  *    * `fs.constants.COPYFILE_EXCL`: If the destination file already exists, the operation fails.
  */
-export declare function copyFile(src: PathLike, dest: PathLike, mode?: number): Promise<void>;
+export declare function copyFile(src: fs.PathLike, dest: fs.PathLike, mode?: number): Promise<void>;
 /**
  * Asynchronous `opendir`. Opens a directory.
  * @param path The path to the directory.
  * @param options Options for opening the directory.
  * @returns A `Dir` object representing the opened directory.
  */
-export declare function opendir(path: PathLike, options?: Node.OpenDirOptions): Promise<Dir>;
+export declare function opendir(path: fs.PathLike, options?: fs.OpenDirOptions): Promise<Dir>;
 /**
  * Asynchronous `cp`. Recursively copies a file or directory.
  * @param source The source file or directory.
@@ -431,15 +435,15 @@ export declare function opendir(path: PathLike, options?: Node.OpenDirOptions):
  *   * `preserveTimestamps`: Preserve file timestamps.
  *   * `recursive`: If `true`, copies directories recursively.
  */
-export declare function cp(source: PathLike, destination: PathLike, opts?: Node.CopyOptions): Promise<void>;
+export declare function cp(source: fs.PathLike, destination: fs.PathLike, opts?: fs.CopyOptions): Promise<void>;
 /**
  * @since v18.15.0
  * @return Fulfills with an {fs.StatFs} for the file system.
  */
-export declare function statfs(path: PathLike, opts?: Node.StatFsOptions & {
+export declare function statfs(path: fs.PathLike, opts?: fs.StatFsOptions & {
     bigint?: false;
 }): Promise<StatsFs>;
-export declare function statfs(path: PathLike, opts: Node.StatFsOptions & {
+export declare function statfs(path: fs.PathLike, opts: fs.StatFsOptions & {
     bigint: true;
 }): Promise<BigIntStatsFs>;
-export declare function statfs(path: PathLike, opts?: Node.StatFsOptions): Promise<StatsFs | BigIntStatsFs>;
+export declare function statfs(path: fs.PathLike, opts?: fs.StatFsOptions): Promise<StatsFs | BigIntStatsFs>;