@zenfs/core 0.1.0 → 0.2.0

package/dist/emulation/promises.d.ts

@@ -1,12 +1,151 @@
 /// <reference types="node" resolution-mode="require"/>
 /// <reference types="node" resolution-mode="require"/>
-import type { ReadStream, WriteStream, FSWatcher, symlink as _symlink, BaseEncodingOptions, BufferEncodingOption, BigIntOptions } from 'node:fs';
-import * as constants from './constants.js';
-export { constants };
-import { PathLike } from './shared.js';
+/// <reference types="node" resolution-mode="require"/>
+import type * as Node from 'node:fs';
+export * as constants from './constants.js';
+import type { PathLike, BufferToUint8Array } from './shared.js';
 import { FileContents } from '../filesystem.js';
 import { BigIntStats, Stats } from '../stats.js';
 import { Dirent } from './dir.js';
+export declare class FileHandle implements BufferToUint8Array<Node.promises.FileHandle> {
+    /**
+     * Gets the file descriptor for this file handle.
+     */
+    readonly fd: number;
+    constructor(
+    /**
+     * Gets the file descriptor for this file handle.
+     */
+    fd: number);
+    /**
+     * Asynchronous fchown(2) - Change ownership of a file.
+     */
+    chown(uid: number, gid: number): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Asynchronous fdatasync(2) - synchronize a file's in-core state with storage device.
+     */
+    datasync(): Promise<void>;
+    /**
+     * Asynchronous fsync(2) - synchronize a file's in-core state with the underlying storage device.
+     */
+    sync(): Promise<void>;
+    /**
+     * Asynchronous ftruncate(2) - Truncate a file to a specified length.
+     * @param len If not specified, defaults to `0`.
+     */
+    truncate(len?: number): 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.
+     * @param mtime The last modified time. If a string is provided, it will be coerced to number.
+     */
+    utimes(atime: string | number | Date, mtime: string | number | Date): Promise<void>;
+    /**
+     * Asynchronously append data to a file, creating the file if it does not exist. The underlying file will _not_ be closed automatically.
+     * The `FileHandle` must have been opened for appending.
+     * @param data The data to write. If something other than a `Buffer` or `Uint8Array` is provided, the value is coerced to a string.
+     * @param options Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.
+     * If `encoding` is not supplied, the default of `'utf8'` is used.
+     * If `mode` is not supplied, the default of `0o666` is used.
+     * 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?: {
+        encoding?: BufferEncoding;
+        mode?: Node.Mode;
+        flag?: Node.OpenMode;
+    } | BufferEncoding): Promise<void>;
+    /**
+     * Asynchronously reads data from the file.
+     * The `FileHandle` must have been opened for reading.
+     * @param buffer The buffer that the data will be written to.
+     * @param offset The offset in the buffer at which to start writing.
+     * @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 Uint8Array>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
+        bytesRead: number;
+        buffer: 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.
+     * @param options An object that may contain an optional flag.
+     * If a flag is not provided, it defaults to `'r'`.
+     */
+    readFile(options?: {
+        flag?: Node.OpenMode;
+    }): Promise<Uint8Array>;
+    readFile(options: {
+        encoding: BufferEncoding;
+        flag?: Node.OpenMode;
+    } | BufferEncoding): Promise<string>;
+    /**
+     * Asynchronous fstat(2) - Get file status.
+     */
+    stat(opts: Node.BigIntOptions): Promise<BigIntStats>;
+    stat(opts?: Node.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.
+     * 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.
+     */
+    write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<{
+        bytesWritten: number;
+        buffer: Uint8Array;
+    }>;
+    /**
+     * 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;
+    }>;
+    /**
+     * Asynchronously writes data to a file, replacing the file if it already exists. The underlying file will _not_ be closed automatically.
+     * The `FileHandle` must have been opened for writing.
+     * It is unsafe to call `writeFile()` multiple times on the same file without waiting for the `Promise` to be resolved (or rejected).
+     * @param data The data to write. If something other than a `Buffer` or `Uint8Array` is provided, the value is coerced to a string.
+     * @param options Either the encoding for the file, or an object optionally specifying the encoding, file mode, and flag.
+     * If `encoding` is not supplied, the default of `'utf8'` is used.
+     * If `mode` is not supplied, the default of `0o666` is used.
+     * 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>;
+    /**
+     * See `fs.writev` promisified version.
+     */
+    writev(buffers: ReadonlyArray<Uint8Array>, position?: number): Promise<Node.WriteVResult>;
+    /**
+     * See `fs.readv` promisified version.
+     */
+    readv(buffers: ReadonlyArray<Uint8Array>, position?: number): Promise<Node.ReadVResult>;
+    /**
+     * Asynchronous close(2) - close a `FileHandle`.
+     */
+    close(): Promise<void>;
+}
 /**
  * Renames a file
  * @param oldPath
@@ -15,24 +154,25 @@ import { Dirent } from './dir.js';
 export declare function rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
 /**
  * Test whether or not the given path exists by checking with the file system.
- * @param path
+ * @param _path
  */
-export declare function exists(path: PathLike): Promise<boolean>;
+export declare function exists(_path: PathLike): Promise<boolean>;
 /**
  * `stat`.
  * @param path
  * @returns Stats
  */
-export declare function stat(path: PathLike, options: BigIntOptions): Promise<BigIntStats>;
+export declare function stat(path: PathLike, options: Node.BigIntOptions): Promise<BigIntStats>;
 export declare function stat(path: PathLike, options?: {
     bigint?: false;
 }): Promise<Stats>;
+export declare function stat(path: PathLike, options?: Node.StatOptions): Promise<Stats | BigIntStats>;
 /**
  * `lstat`.
  * `lstat()` is identical to `stat()`, except that if path is a symbolic link,
  * then the link itself is stat-ed, not the file that it refers to.
  * @param path
- * @return [ZenFS.node.fs.Stats]
+ * @return
  */
 export declare function lstat(path: PathLike, options?: {
     bigint?: false;
@@ -52,126 +192,78 @@ export declare function truncate(path: PathLike, len?: number): Promise<void>;
  */
 export declare function unlink(path: PathLike): Promise<void>;
 /**
- * file open.
+ * Asynchronous file open.
  * @see http://www.manpagez.com/man/2/open/
- * @param path
- * @param flags
- * @param mode defaults to `0644`
+ * @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 open(path: PathLike, flag: string, mode?: number | string): Promise<number>;
+export declare function lopen(path: PathLike, flag: string, mode?: Node.Mode): Promise<FileHandle>;
 /**
- * Synchronously reads the entire contents of a file.
+ * Asynchronously reads the entire contents of a file.
  * @param filename
  * @param options
  * options.encoding The string encoding for the file contents. Defaults to `null`.
  * options.flag Defaults to `'r'`.
- * @return Uint8Array
+ * @returns file data
  */
 export declare function readFile(filename: PathLike, options?: {
-    flag?: string;
+    flag?: Node.OpenMode;
 }): Promise<Uint8Array>;
 export declare function readFile(filename: PathLike, options: {
-    encoding: string;
-    flag?: string;
-}): Promise<string>;
-export declare function readFile(filename: PathLike, encoding: string): Promise<string>;
+    encoding?: BufferEncoding;
+    flag?: Node.OpenMode;
+} | BufferEncoding): Promise<string>;
 /**
- * Synchronously writes data to a file, replacing the file if it already
- * exists.
+ * Synchronously 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 options
- * @option options [String] encoding Defaults to `'utf8'`.
- * @option options [Number] mode Defaults to `0644`.
- * @option options [String] flag Defaults to `'w'`.
+ * @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?: {
-    encoding?: string;
-    mode?: number | string;
-    flag?: string;
-}): Promise<void>;
-export declare function writeFile(filename: PathLike, data: FileContents, encoding?: string): Promise<void>;
-export declare function writeFile(filename: PathLike, data: FileContents, options?: {
-    encoding?: string;
-    mode?: number | string;
-    flag?: string;
-} | string): Promise<void>;
+export declare function writeFile(filename: PathLike, data: FileContents, _options?: Node.WriteFileOptions): Promise<void>;
 /**
  * Asynchronously append data to a file, creating the file if it not yet
  * exists.
- *
- * @example Usage example
- *   fs.appendFile('message.txt', 'data to append', function (err) {
- *     if (err) throw err;
- *     console.log('The "data to append" was appended to file!');
- *   });
  * @param filename
  * @param data
  * @param options
- * @option options [String] encoding Defaults to `'utf8'`.
- * @option options [Number] mode Defaults to `0644`.
- * @option options [String] flag Defaults to `'a'`.
- */
-export declare function appendFile(filename: PathLike, data: FileContents, options?: {
-    encoding?: string;
-    mode?: number | string;
-    flag?: string;
-}): Promise<void>;
-export declare function appendFile(filename: PathLike, data: FileContents, encoding?: string): Promise<void>;
-/**
- * `fstat`.
- * `fstat()` is identical to `stat()`, except that the file to be stat-ed is
- * specified by the file descriptor `fd`.
- * @param fd
- * @return [ZenFS.node.fs.Stats]
- */
-export declare function fstat(fd: number, options?: {
-    bigint?: false;
-}): Promise<Stats>;
-export declare function fstat(fd: number, options: {
-    bigint: true;
-}): Promise<BigIntStats>;
-/**
- * close.
- * @param fd
+ * @option options encoding Defaults to `'utf8'`.
+ * @option options mode Defaults to `0644`.
+ * @option options flag Defaults to `'a'`.
  */
-export declare function close(fd: number): Promise<void>;
-/**
- * ftruncate.
- * @param fd
- * @param len
- */
-export declare function ftruncate(fd: number, len?: number): Promise<void>;
-/**
- * fsync.
- * @param fd
- */
-export declare function fsync(fd: number): Promise<void>;
-/**
- * fdatasync.
- * @param fd
- */
-export declare function fdatasync(fd: number): Promise<void>;
+export declare function appendFile(filename: PathLike, data: FileContents, _options?: BufferEncoding | (Node.BaseEncodingOptions & {
+    mode?: Node.Mode;
+    flag?: Node.OpenMode;
+})): Promise<void>;
 /**
  * Write buffer to the file specified by `fd`.
- * Note that it is unsafe to use fs.write multiple times on the same file
- * without waiting for it to return.
- * @param fd
- * @param buffer Uint8Array containing the data to write to
- *   the file.
+ * Note that it is unsafe to use fs.write multiple times on the same file without waiting for it to return.
+ * @param handle
+ * @param data Uint8Array containing the data to write to the file.
  * @param offset Offset in the buffer to start reading data from.
  * @param length The amount of bytes to write to the file.
- * @param position Offset from the beginning of the file where this
- *   data should be written. If position is null, the data will be written at
- *   the current position.
+ * @param position Offset from the beginning of the file where this data should be written. If position is null, the data will be written at the current position.
  */
-export declare function write(fd: number, buffer: Uint8Array, offset: number, length: number, position?: number): Promise<number>;
-export declare function write(fd: number, data: string, position?: number | null, encoding?: BufferEncoding): Promise<number>;
+export declare function write(handle: FileHandle, data: Uint8Array, offset: number, length: number, position?: number): Promise<{
+    bytesWritten: number;
+    buffer: Uint8Array;
+}>;
+export declare function write(handle: FileHandle, data: string, position?: number, encoding?: BufferEncoding): Promise<{
+    bytesWritten: number;
+    buffer: string;
+}>;
 /**
  * Read data from the file specified by `fd`.
- * @param fd
+ * @param handle
  * @param buffer The buffer that the data will be
  *   written to.
  * @param offset The offset within the buffer where writing will
@@ -181,31 +273,31 @@ export declare function write(fd: number, data: string, position?: number | null
  *   in the file. If position is null, data will be read from the current file
  *   position.
  */
-export declare function read(fd: number, buffer: Uint8Array, offset: number, length: number, position?: number): Promise<{
+export declare function read(handle: FileHandle, buffer: Uint8Array, offset: number, length: number, position?: number): Promise<{
     bytesRead: number;
     buffer: Uint8Array;
 }>;
 /**
  * `fchown`.
- * @param fd
+ * @param handle
  * @param uid
  * @param gid
  */
-export declare function fchown(fd: number, uid: number, gid: number): Promise<void>;
+export declare function fchown(handle: FileHandle, uid: number, gid: number): Promise<void>;
 /**
  * `fchmod`.
- * @param fd
+ * @param handle
  * @param mode
  */
-export declare function fchmod(fd: number, mode: number | string): Promise<void>;
+export declare function fchmod(handle: FileHandle, mode: Node.Mode): Promise<void>;
 /**
  * Change the file timestamps of a file referenced by the supplied file
  * descriptor.
- * @param fd
+ * @param handle
  * @param atime
  * @param mtime
  */
-export declare function futimes(fd: number, atime: number | Date, mtime: number | Date): Promise<void>;
+export declare function futimes(handle: FileHandle, atime: string | number | Date, mtime: string | number | Date): Promise<void>;
 /**
  * `rmdir`.
  * @param path
@@ -216,37 +308,44 @@ export declare function rmdir(path: PathLike): Promise<void>;
  * @param path
  * @param mode defaults to `0777`
  */
-export declare function mkdir(path: PathLike, mode?: number | string): Promise<void>;
+export declare function mkdir(path: PathLike, mode?: Node.Mode | (Node.MakeDirectoryOptions & {
+    recursive?: false;
+})): Promise<void>;
+export declare function mkdir(path: PathLike, mode: Node.MakeDirectoryOptions & {
+    recursive: true;
+}): Promise<string>;
 /**
  * `readdir`. Reads the contents of a directory.
  * @param path
  */
-export declare function readdir(path: PathLike, options: {
+export declare function readdir(path: PathLike, options?: (Node.BaseEncodingOptions & {
+    withFileTypes?: false;
+}) | BufferEncoding): Promise<string[]>;
+export declare function readdir(path: PathLike, options: Node.BufferEncodingOption & {
     withFileTypes?: false;
-}): Promise<string[]>;
-export declare function readdir(path: PathLike, options: {
+}): Promise<Uint8Array[]>;
+export declare function readdir(path: PathLike, options: Node.BaseEncodingOptions & {
     withFileTypes: true;
 }): Promise<Dirent[]>;
 /**
  * `link`.
- * @param srcpath
- * @param dstpath
+ * @param existing
+ * @param newpath
  */
-export declare function link(srcpath: PathLike, dstpath: PathLike): Promise<void>;
+export declare function link(existing: PathLike, newpath: PathLike): Promise<void>;
 /**
  * `symlink`.
- * @param srcpath
- * @param dstpath
+ * @param target target path
+ * @param path link path
  * @param type can be either `'dir'` or `'file'` (default is `'file'`)
  */
-export declare function symlink(srcpath: PathLike, dstpath: PathLike, type?: _symlink.Type): Promise<void>;
+export declare function symlink(target: PathLike, path: PathLike, type?: Node.symlink.Type): Promise<void>;
 /**
  * readlink.
  * @param path
  */
-export declare function readlink(path: PathLike, options?: BaseEncodingOptions | BufferEncoding): Promise<string>;
-export declare function readlink(path: PathLike, options: BufferEncodingOption): Promise<Uint8Array>;
-export declare function readlink(path: PathLike, options?: BaseEncodingOptions | string): Promise<string | Uint8Array>;
+export declare function readlink(path: PathLike, options: Node.BufferEncodingOption): Promise<Uint8Array>;
+export declare function readlink(path: PathLike, options?: Node.BaseEncodingOptions | BufferEncoding): Promise<string>;
 /**
  * `chown`.
  * @param path
@@ -266,20 +365,20 @@ export declare function lchown(path: PathLike, uid: number, gid: number): Promis
  * @param path
  * @param mode
  */
-export declare function chmod(path: PathLike, mode: string | number): Promise<void>;
+export declare function chmod(path: PathLike, mode: Node.Mode): Promise<void>;
 /**
  * `lchmod`.
  * @param path
  * @param mode
  */
-export declare function lchmod(path: PathLike, mode: number | string): Promise<void>;
+export declare function lchmod(path: PathLike, mode: Node.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: number | Date, mtime: number | Date): Promise<void>;
+export declare function utimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise<void>;
 /**
  * Change file timestamps of the file referenced by the supplied path.
  * @param path
@@ -288,24 +387,24 @@ export declare function utimes(path: PathLike, atime: number | Date, mtime: numb
  */
 export declare function lutimes(path: PathLike, atime: number | Date, mtime: number | Date): Promise<void>;
 /**
- * `realpath`.
- * @param path
- * @param options
- * @return resolved path
+ * 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.
+ * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
  *
  * Note: This *Can not* use doOp since doOp depends on it
  */
-export declare function realpath(path: PathLike, options?: BaseEncodingOptions): Promise<string>;
+export declare function realpath(path: PathLike, options: Node.BufferEncodingOption): Promise<Uint8Array>;
+export declare function realpath(path: PathLike, options?: Node.BaseEncodingOptions | BufferEncoding): Promise<string>;
 export declare function watchFile(filename: PathLike, listener: (curr: Stats, prev: Stats) => void): Promise<void>;
 export declare function watchFile(filename: PathLike, options: {
     persistent?: boolean;
     interval?: number;
 }, listener: (curr: Stats, prev: Stats) => void): Promise<void>;
 export declare function unwatchFile(filename: PathLike, listener?: (curr: Stats, prev: Stats) => void): Promise<void>;
-export declare function watch(filename: PathLike, listener?: (event: string, filename: PathLike) => any): Promise<FSWatcher>;
+export declare function watch(filename: PathLike, listener?: (event: string, filename: PathLike) => any): Promise<Node.FSWatcher>;
 export declare function watch(filename: PathLike, options: {
     persistent?: boolean;
-}, listener?: (event: string, filename: string) => any): Promise<FSWatcher>;
+}, listener?: (event: string, filename: string) => any): Promise<Node.FSWatcher>;
 /**
  * `access`.
  * @param path
@@ -318,13 +417,13 @@ export declare function createReadStream(path: PathLike, options?: {
     fd?: number;
     mode?: number;
     autoClose?: boolean;
-}): Promise<ReadStream>;
+}): Promise<Node.ReadStream>;
 export declare function createWriteStream(path: PathLike, options?: {
     flags?: string;
     encoding?: string;
     fd?: number;
     mode?: number;
-}): Promise<WriteStream>;
+}): Promise<Node.WriteStream>;
 export declare function rm(path: PathLike): Promise<void>;
 export declare function mkdtemp(path: PathLike): Promise<void>;
 export declare function copyFile(path: PathLike): Promise<void>;