@zenfs/core 1.11.4 → 2.1.0

package/dist/vfs/promises.d.ts

@@ -1,30 +1,57 @@
 import type * as fs from 'node:fs';
 import type * as promises from 'node:fs/promises';
-import type { Interface as ReadlineInterface } from 'node:readline';
 import type { Stream } from 'node:stream';
 import type { ReadableStream as NodeReadableStream } from 'node:stream/web';
 import type { V_Context } from '../context.js';
-import type { File } from '../internal/file.js';
-import type { Stats } from '../stats.js';
+import type { FileSystem, StreamOptions } from '../internal/filesystem.js';
+import type { InodeLike } from '../internal/inode.js';
+import type { Interface as ReadlineInterface } from '../readline.js';
 import type { FileContents, NullEnc, ReaddirOptions, ReaddirOptsI, ReaddirOptsU } from './types.js';
 import { Buffer } from 'buffer';
 import '../polyfills.js';
-import { BigIntStats } from '../stats.js';
 import { Dir, Dirent } from './dir.js';
+import { BigIntStats, Stats } from './stats.js';
 import { ReadStream, WriteStream } from './streams.js';
 export * as constants from './constants.js';
 export declare class FileHandle implements promises.FileHandle {
-    protected context?: V_Context | undefined;
+    protected context: V_Context;
+    readonly fd: number;
+    protected _buffer?: Uint8Array;
     /**
-     * The file descriptor for this file handle.
+     * Current position
      */
-    readonly fd: number;
+    protected _position: number;
     /**
-     * @internal
-     * The file for this file handle
+     * Get the current file position.
+     *
+     * We emulate the following bug mentioned in the Node documentation:
+     *
+     * On Linux, positional writes don't work when the file is opened in append mode.
+     * The kernel ignores the position argument and always appends the data to the end of the file.
+     * @returns The current file position.
+     */
+    get position(): number;
+    set position(value: number);
+    /**
+     * Whether the file has changes which have not been written to the FS
      */
-    readonly file: File;
-    constructor(fdOrFile: number | File, context?: V_Context | undefined);
+    protected dirty: boolean;
+    /**
+     * Whether the file is open or closed
+     */
+    protected closed: boolean;
+    /** The path relative to the context's root */
+    readonly path: string;
+    /** The internal FS associated with the handle */
+    protected readonly fs: FileSystem;
+    /** The path relative to the `FileSystem`'s root */
+    readonly internalPath: string;
+    /** The flag the handle was opened with */
+    readonly flag: number;
+    /** Stats for the handle */
+    readonly inode: InodeLike;
+    constructor(context: V_Context, fd: number);
+    private get _isSync();
     private _emitChange;
     /**
      * Asynchronous fchown(2) - Change ownership of a file.
@@ -47,7 +74,7 @@ export declare class FileHandle implements promises.FileHandle {
      * Asynchronous ftruncate(2) - Truncate a file to a specified length.
      * @param length If not specified, defaults to `0`.
      */
-    truncate(length?: number | null): Promise<void>;
+    truncate(length?: 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.
@@ -64,6 +91,18 @@ export declare class FileHandle implements promises.FileHandle {
      * - `flag` defaults to `'a'`.
      */
     appendFile(data: string | Uint8Array, _options?: (fs.ObjectEncodingOptions & promises.FlagAndOpenMode) | BufferEncoding): Promise<void>;
+    /**
+     * Read data from the file.
+     * @param buffer The buffer that the data will be written to.
+     * @param offset The offset within the buffer where writing will start.
+     * @param length An integer specifying the number of bytes to read.
+     * @param position An integer specifying where to begin reading from in the file.
+     * If position is unset, data will be read from the current file position.
+     */
+    protected _read<TBuffer extends ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
+        bytesRead: number;
+        buffer: TBuffer;
+    }>;
     /**
      * Asynchronously reads data from the file.
      * The `FileHandle` must have been opened for reading.
@@ -89,9 +128,19 @@ export declare class FileHandle implements promises.FileHandle {
      * Read file data using a `ReadableStream`.
      * The handle will not be closed automatically.
      */
-    readableWebStream(options?: promises.ReadableWebStreamOptions): NodeReadableStream<Uint8Array>;
+    readableWebStream(options?: promises.ReadableWebStreamOptions & StreamOptions): NodeReadableStream<Uint8Array>;
+    /**
+     * Not part of the Node.js API!
+     *
+     * Write file data using a `WritableStream`.
+     * The handle will not be closed automatically.
+     * @internal
+     */
+    writableWebStream(options?: promises.ReadableWebStreamOptions & StreamOptions): WritableStream;
     /**
-     * @todo Implement
+     * Creates a readline Interface object that allows reading the file line by line
+     * @param options Options for creating a read stream
+     * @returns A readline interface for reading the file line by line
      */
     readLines(options?: promises.CreateReadStreamOptions): ReadlineInterface;
     [Symbol.asyncDispose](): Promise<void>;
@@ -102,6 +151,15 @@ export declare class FileHandle implements promises.FileHandle {
     stat(opts?: fs.StatOptions & {
         bigint?: false;
     }): Promise<Stats>;
+    /**
+     * Write buffer to the file.
+     * @param buffer 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.
+     */
+    protected _write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
     /**
      * Asynchronously writes `string` to the file.
      * The `FileHandle` must have been opened for writing.
@@ -131,6 +189,10 @@ export declare class FileHandle implements promises.FileHandle {
      * Asynchronous close(2) - close a `FileHandle`.
      */
     close(): Promise<void>;
+    /**
+     * Cleans up. This will *not* sync the file data to the FS
+     */
+    protected dispose(force?: boolean): void;
     /**
      * Asynchronous `writev`. Writes from multiple buffers.
      * @param buffers An array of Uint8Array buffers.
@@ -181,8 +243,8 @@ export declare function truncate(this: V_Context, path: fs.PathLike, len?: numbe
 export declare function unlink(this: V_Context, path: fs.PathLike): Promise<void>;
 /**
  * Asynchronous file open.
- * @see http://www.manpagez.com/man/2/open/
- * @param flag Handles the complexity of the various file modes. See its API for more details.
+ * @see https://nodejs.org/api/fs.html#fspromisesopenpath-flags-mode
+ * @param flag {@link https://nodejs.org/api/fs.html#file-system-flags}
  * @param mode Mode to use to open the file. Can be ignored if the filesystem doesn't support permissions.
  */
 export declare function open(this: V_Context, path: fs.PathLike, flag?: fs.OpenMode, mode?: fs.Mode): Promise<FileHandle>;
@@ -260,14 +322,14 @@ export declare function readdir(this: V_Context, path: fs.PathLike, options: Rea
     withFileTypes: true;
 }>): Promise<Dirent[]>;
 export declare function readdir(this: V_Context, path: fs.PathLike, options?: ReaddirOptsU<fs.BufferEncodingOption> | NullEnc): Promise<string[] | Dirent[] | Buffer[]>;
-export declare function link(this: V_Context, targetPath: fs.PathLike, linkPath: fs.PathLike): Promise<void>;
+export declare function link(this: V_Context, path: fs.PathLike, dest: fs.PathLike): Promise<void>;
 /**
  * `symlink`.
- * @param target target path
+ * @param dest target path
  * @param path link path
  * @param type can be either `'dir'` or `'file'` (default is `'file'`)
  */
-export declare function symlink(this: V_Context, target: fs.PathLike, path: fs.PathLike, type?: fs.symlink.Type | string | null): Promise<void>;
+export declare function symlink(this: V_Context, dest: fs.PathLike, path: fs.PathLike, type?: fs.symlink.Type | string | null): Promise<void>;
 export declare function readlink(this: V_Context, path: fs.PathLike, options: fs.BufferEncodingOption): Promise<Buffer>;
 export declare function readlink(this: V_Context, path: fs.PathLike, options?: fs.EncodingOption | null): Promise<string>;
 export declare function readlink(this: V_Context, path: fs.PathLike, options?: fs.BufferEncodingOption | fs.EncodingOption | string | null): Promise<string | Buffer>;