@zenfs/core 1.0.10 → 1.1.0

package/dist/file.d.ts

@@ -1,9 +1,12 @@
-/// <reference types="node" resolution-mode="require"/>
-/// <reference types="node" resolution-mode="require"/>
 import type { FileReadResult } from 'node:fs/promises';
 import type { FileSystem } from './filesystem.js';
 import { Stats, type FileType } from './stats.js';
 import './polyfills.js';
+/**
+    Typescript does not include a type declaration for resizable array buffers.
+    It has been standardized into ECMAScript though
+    @todo Remove this if TS adds them to lib declarations
+*/
 declare global {
     interface ArrayBuffer {
         readonly resizable: boolean;
@@ -41,95 +44,53 @@ export declare abstract class File {
      * The file system that created the file
      */
     fs: FileSystem;
-    /**
-     * The path to the file
-     */
     readonly path: string;
     constructor(
     /**
      * @internal
      * The file system that created the file
      */
-    fs: FileSystem, 
-    /**
-     * The path to the file
-     */
-    path: string);
+    fs: FileSystem, path: string);
     /**
      * Get the current file position.
      */
     abstract position: number;
-    /**
-     * Asynchronous `stat`.
-     */
     abstract stat(): Promise<Stats>;
-    /**
-     * Synchronous `stat`.
-     */
     abstract statSync(): Stats;
-    /**
-     * Asynchronous close.
-     */
     abstract close(): Promise<void>;
-    /**
-     * Synchronous close.
-     */
     abstract closeSync(): void;
     [Symbol.asyncDispose](): Promise<void>;
     [Symbol.dispose](): void;
-    /**
-     * Asynchronous truncate.
-     */
     abstract truncate(len: number): Promise<void>;
-    /**
-     * Synchronous truncate.
-     */
     abstract truncateSync(len: number): void;
-    /**
-     * Asynchronous sync.
-     */
     abstract sync(): Promise<void>;
-    /**
-     * Synchronous sync.
-     */
     abstract syncSync(): void;
     /**
      * Write buffer to the file.
-     * Note that it is unsafe to use fs.write multiple times on the same file
-     * without waiting for the callback.
-     * @param buffer Uint8Array containing the data to write 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.
+     * @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.
      * @returns Promise resolving to the new length of the buffer
      */
     abstract write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
     /**
      * Write buffer to the file.
-     * Note that it is unsafe to use fs.writeSync multiple times on the same file
-     * without waiting for it to return.
-     * @param buffer Uint8Array containing the data to write 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.
+     * @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.
      */
     abstract writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     /**
      * 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 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 null, data will be read from the current file
-     *   position.
+     * @param position An integer specifying where to begin reading from in the file.
+     * If position is null, data will be read from the current file position.
      * @returns Promise resolving to the new length of the buffer
      */
     abstract read<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<FileReadResult<TBuffer>>;
@@ -138,38 +99,21 @@ export declare abstract class 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 null, data will be read from the current file
-     *   position.
+     * @param position An integer specifying where to begin reading from in the file.
+     * If position is null, data will be read from the current file position.
      */
     abstract readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
     /**
-     * Asynchronous `datasync`.
-     *
      * Default implementation maps to `sync`.
      */
     datasync(): Promise<void>;
     /**
-     * Synchronous `datasync`.
-     *
      * Default implementation maps to `syncSync`.
      */
     datasyncSync(): void;
-    /**
-     * Asynchronous `chown`.
-     */
     abstract chown(uid: number, gid: number): Promise<void>;
-    /**
-     * Synchronous `chown`.
-     */
     abstract chownSync(uid: number, gid: number): void;
-    /**
-     * Asynchronous `fchmod`.
-     */
     abstract chmod(mode: number): Promise<void>;
-    /**
-     * Synchronous `fchmod`.
-     */
     abstract chmodSync(mode: number): void;
     /**
      * Change the file timestamps of the file.
@@ -191,9 +135,8 @@ export declare abstract class File {
     abstract _setTypeSync(type: FileType): void;
 }
 /**
- * An implementation of the File interface that operates on a file that is
- * completely in-memory. PreloadFiles are backed by a Uint8Array.
- *
+ * An implementation of `File` that operates completely in-memory.
+ * `PreloadFile`s are backed by a `Uint8Array`.
  */
 export declare class PreloadFile<FS extends FileSystem> extends File {
     /**
@@ -203,6 +146,9 @@ export declare class PreloadFile<FS extends FileSystem> extends File {
     fs: FS;
     readonly flag: string;
     readonly stats: Stats;
+    /**
+     * A buffer containing the entire contents of the file.
+     */
     protected _buffer: Uint8Array;
     /**
      * Current position
@@ -217,23 +163,19 @@ export declare class PreloadFile<FS extends FileSystem> extends File {
      */
     protected closed: boolean;
     /**
-     * Creates a file with the given path and, optionally, the given contents. Note
-     * that, if contents is specified, it will be mutated by the file!
-     * @param _mode The mode that the file was opened using.
-     *   Dictates permissions and where the file pointer starts.
-     * @param stats The stats object for the given file.
-     *   PreloadFile will mutate this object. Note that this object must contain
-     *   the appropriate mode that the file was opened as.
-     * @param buffer A buffer containing the entire
-     *   contents of the file. PreloadFile will mutate this buffer. If not
-     *   specified, we assume it is a new file.
+     * Creates a file with `path` and, optionally, the given contents.
+     * Note that, if contents is specified, it will be mutated by the file.
      */
     constructor(
     /**
      * The file system that created the file.
      * @internal
      */
-    fs: FS, path: string, flag: string, stats: Stats, _buffer?: Uint8Array);
+    fs: FS, path: string, flag: string, stats: Stats, 
+    /**
+     * A buffer containing the entire contents of the file.
+     */
+    _buffer?: Uint8Array);
     /**
      * Get the underlying buffer for this file. Mutating not recommended and will mess up dirty tracking.
      */
@@ -242,84 +184,54 @@ export declare class PreloadFile<FS extends FileSystem> extends File {
      * 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.
-     * @return The current file position.
+     *
+     * 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 the file position.
-     * @param newPos new position
-     */
-    set position(newPos: number);
+    set position(value: number);
     sync(): Promise<void>;
     syncSync(): void;
     close(): Promise<void>;
     closeSync(): void;
     /**
-     * Cleans up
-     * This will *not* sync the file data to the FS
+     * Cleans up. This will *not* sync the file data to the FS
      */
     protected dispose(force?: boolean): void;
-    /**
-     * Asynchronous `stat`.
-     */
     stat(): Promise<Stats>;
-    /**
-     * Synchronous `stat`.
-     */
     statSync(): Stats;
     protected _truncate(length: number): void;
-    /**
-     * Asynchronous truncate.
-     * @param length
-     */
     truncate(length: number): Promise<void>;
-    /**
-     * Synchronous truncate.
-     * @param length
-     */
     truncateSync(length: number): void;
     protected _write(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     /**
      * Write buffer to the file.
-     * Note that it is unsafe to use fs.write multiple times on the same file
-     * without waiting for the callback.
-     * @param buffer Uint8Array containing the data to write 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.
+     * @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.
      */
     write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
     /**
      * Write buffer to the file.
-     * Note that it is unsafe to use fs.writeSync multiple times on the same file
-     * without waiting for the callback.
-     * @param buffer Uint8Array containing the data to write 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.
+     * @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.
      * @returns bytes written
      */
     writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     protected _read(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
     /**
      * 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 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 null, data will be read from the current file
-     *   position.
+     * @param position An integer specifying where to begin reading from in the file.
+     * If position is null, data will be read from the current file position.
      */
     read<TBuffer extends ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
         bytesRead: number;
@@ -327,37 +239,17 @@ export declare class PreloadFile<FS extends FileSystem> extends File {
     }>;
     /**
      * Read data from the file.
-     * @param buffer The buffer that the data will be
-     *   written to.
+     * @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 null, data will be read from the current file
-     *   position.
+     * @param position An integer specifying where to begin reading from in the file.
+     * If position is null, data will be read from the current file position.
      * @returns number of bytes written
      */
     readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
-    /**
-     * Asynchronous `fchmod`.
-     * @param mode the mode
-     */
     chmod(mode: number): Promise<void>;
-    /**
-     * Synchronous `fchmod`.
-     * @param mode
-     */
     chmodSync(mode: number): void;
-    /**
-     * Asynchronous `fchown`.
-     * @param uid
-     * @param gid
-     */
     chown(uid: number, gid: number): Promise<void>;
-    /**
-     * Synchronous `fchown`.
-     * @param uid
-     * @param gid
-     */
     chownSync(uid: number, gid: number): void;
     utimes(atime: Date, mtime: Date): Promise<void>;
     utimesSync(atime: Date, mtime: Date): void;
@@ -367,24 +259,11 @@ export declare class PreloadFile<FS extends FileSystem> extends File {
     [Symbol.dispose](): void;
 }
 /**
- * For the filesystems which do not sync to anything..
+ * For the file systems which do not sync to anything.
  */
 export declare class NoSyncFile<T extends FileSystem> extends PreloadFile<T> {
-    constructor(fs: T, path: string, flag: string, stats: Stats, contents?: Uint8Array);
-    /**
-     * Asynchronous sync. Doesn't do anything, simply calls the cb.
-     */
     sync(): Promise<void>;
-    /**
-     * Synchronous sync. Doesn't do anything.
-     */
     syncSync(): void;
-    /**
-     * Asynchronous close. Doesn't do anything, simply calls the cb.
-     */
     close(): Promise<void>;
-    /**
-     * Synchronous close. Doesn't do anything.
-     */
     closeSync(): void;
 }

package/dist/file.js

@@ -1,6 +1,5 @@
-import { O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY, S_IFMT } from './emulation/constants.js';
+import { O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY, S_IFMT, size_max } from './emulation/constants.js';
 import { Errno, ErrnoError } from './error.js';
-import { size_max } from './inode.js';
 import { Stats } from './stats.js';
 import './polyfills.js';
 const validFlags = ['r', 'r+', 'rs', 'rs+', 'w', 'wx', 'w+', 'wx+', 'a', 'ax', 'a+', 'ax+'];
@@ -110,11 +109,7 @@ export class File {
      * @internal
      * The file system that created the file
      */
-    fs, 
-    /**
-     * The path to the file
-     */
-    path) {
+    fs, path) {
         this.fs = fs;
         this.path = path;
     }
@@ -125,16 +120,12 @@ export class File {
         return this.closeSync();
     }
     /**
-     * Asynchronous `datasync`.
-     *
      * Default implementation maps to `sync`.
      */
     datasync() {
         return this.sync();
     }
     /**
-     * Synchronous `datasync`.
-     *
      * Default implementation maps to `syncSync`.
      */
     datasyncSync() {
@@ -142,29 +133,24 @@ export class File {
     }
 }
 /**
- * An implementation of the File interface that operates on a file that is
- * completely in-memory. PreloadFiles are backed by a Uint8Array.
- *
+ * An implementation of `File` that operates completely in-memory.
+ * `PreloadFile`s are backed by a `Uint8Array`.
  */
 export class PreloadFile extends File {
     /**
-     * Creates a file with the given path and, optionally, the given contents. Note
-     * that, if contents is specified, it will be mutated by the file!
-     * @param _mode The mode that the file was opened using.
-     *   Dictates permissions and where the file pointer starts.
-     * @param stats The stats object for the given file.
-     *   PreloadFile will mutate this object. Note that this object must contain
-     *   the appropriate mode that the file was opened as.
-     * @param buffer A buffer containing the entire
-     *   contents of the file. PreloadFile will mutate this buffer. If not
-     *   specified, we assume it is a new file.
+     * Creates a file with `path` and, optionally, the given contents.
+     * Note that, if contents is specified, it will be mutated by the file.
      */
     constructor(
     /**
      * The file system that created the file.
      * @internal
      */
-    fs, path, flag, stats, _buffer = new Uint8Array(new ArrayBuffer(0, fs.metadata().noResizableBuffers ? {} : { maxByteLength: size_max }))) {
+    fs, path, flag, stats, 
+    /**
+     * A buffer containing the entire contents of the file.
+     */
+    _buffer = new Uint8Array(new ArrayBuffer(0, fs.metadata().noResizableBuffers ? {} : { maxByteLength: size_max }))) {
         super(fs, path);
         this.fs = fs;
         this.flag = flag;
@@ -205,10 +191,10 @@ export class PreloadFile extends File {
      * 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.
-     * @return The current file position.
+     *
+     * 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() {
         if (isAppendable(this.flag)) {
@@ -216,12 +202,8 @@ export class PreloadFile extends File {
         }
         return this._position;
     }
-    /**
-     * Set the file position.
-     * @param newPos new position
-     */
-    set position(newPos) {
-        this._position = newPos;
+    set position(value) {
+        this._position = value;
     }
     async sync() {
         if (this.closed) {
@@ -258,8 +240,7 @@ export class PreloadFile extends File {
         this.dispose();
     }
     /**
-     * Cleans up
-     * This will *not* sync the file data to the FS
+     * Cleans up. This will *not* sync the file data to the FS
      */
     dispose(force) {
         if (this.closed) {
@@ -274,18 +255,12 @@ export class PreloadFile extends File {
         delete this.stats;
         this.closed = true;
     }
-    /**
-     * Asynchronous `stat`.
-     */
     stat() {
         if (this.closed) {
             throw ErrnoError.With('EBADF', this.path, 'File.stat');
         }
         return Promise.resolve(new Stats(this.stats));
     }
-    /**
-     * Synchronous `stat`.
-     */
     statSync() {
         if (this.closed) {
             throw ErrnoError.With('EBADF', this.path, 'File.stat');
@@ -311,18 +286,10 @@ export class PreloadFile extends File {
         // Truncate.
         this._buffer = this._buffer.slice(0, length);
     }
-    /**
-     * Asynchronous truncate.
-     * @param length
-     */
     async truncate(length) {
         this._truncate(length);
         await this.sync();
     }
-    /**
-     * Synchronous truncate.
-     * @param length
-     */
     truncateSync(length) {
         this._truncate(length);
         this.syncSync();
@@ -358,15 +325,11 @@ export class PreloadFile extends File {
     }
     /**
      * Write buffer to the file.
-     * Note that it is unsafe to use fs.write multiple times on the same file
-     * without waiting for the callback.
-     * @param buffer Uint8Array containing the data to write 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.
+     * @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.
      */
     async write(buffer, offset, length, position) {
         const bytesWritten = this._write(buffer, offset, length, position);
@@ -375,15 +338,11 @@ export class PreloadFile extends File {
     }
     /**
      * Write buffer to the file.
-     * Note that it is unsafe to use fs.writeSync multiple times on the same file
-     * without waiting for the callback.
-     * @param buffer Uint8Array containing the data to write 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.
+     * @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.
      * @returns bytes written
      */
     writeSync(buffer, offset = 0, length = this.stats.size, position = this.position) {
@@ -416,14 +375,11 @@ export class PreloadFile extends File {
     }
     /**
      * 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 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 null, data will be read from the current file
-     *   position.
+     * @param position An integer specifying where to begin reading from in the file.
+     * If position is null, data will be read from the current file position.
      */
     async read(buffer, offset, length, position) {
         const bytesRead = this._read(buffer, offset, length, position);
@@ -432,13 +388,11 @@ export class PreloadFile extends File {
     }
     /**
      * Read data from the file.
-     * @param buffer The buffer that the data will be
-     *   written to.
+     * @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 null, data will be read from the current file
-     *   position.
+     * @param position An integer specifying where to begin reading from in the file.
+     * If position is null, data will be read from the current file position.
      * @returns number of bytes written
      */
     readSync(buffer, offset, length, position) {
@@ -446,10 +400,6 @@ export class PreloadFile extends File {
         this.statSync();
         return bytesRead;
     }
-    /**
-     * Asynchronous `fchmod`.
-     * @param mode the mode
-     */
     async chmod(mode) {
         if (this.closed) {
             throw ErrnoError.With('EBADF', this.path, 'File.chmod');
@@ -458,10 +408,6 @@ export class PreloadFile extends File {
         this.stats.chmod(mode);
         await this.sync();
     }
-    /**
-     * Synchronous `fchmod`.
-     * @param mode
-     */
     chmodSync(mode) {
         if (this.closed) {
             throw ErrnoError.With('EBADF', this.path, 'File.chmod');
@@ -470,11 +416,6 @@ export class PreloadFile extends File {
         this.stats.chmod(mode);
         this.syncSync();
     }
-    /**
-     * Asynchronous `fchown`.
-     * @param uid
-     * @param gid
-     */
     async chown(uid, gid) {
         if (this.closed) {
             throw ErrnoError.With('EBADF', this.path, 'File.chown');
@@ -483,11 +424,6 @@ export class PreloadFile extends File {
         this.stats.chown(uid, gid);
         await this.sync();
     }
-    /**
-     * Synchronous `fchown`.
-     * @param uid
-     * @param gid
-     */
     chownSync(uid, gid) {
         if (this.closed) {
             throw ErrnoError.With('EBADF', this.path, 'File.chown');
@@ -538,34 +474,15 @@ export class PreloadFile extends File {
     }
 }
 /**
- * For the filesystems which do not sync to anything..
+ * For the file systems which do not sync to anything.
  */
 export class NoSyncFile extends PreloadFile {
-    constructor(fs, path, flag, stats, contents) {
-        super(fs, path, flag, stats, contents);
-    }
-    /**
-     * Asynchronous sync. Doesn't do anything, simply calls the cb.
-     */
     sync() {
         return Promise.resolve();
     }
-    /**
-     * Synchronous sync. Doesn't do anything.
-     */
-    syncSync() {
-        // NOP.
-    }
-    /**
-     * Asynchronous close. Doesn't do anything, simply calls the cb.
-     */
+    syncSync() { }
     close() {
         return Promise.resolve();
     }
-    /**
-     * Synchronous close. Doesn't do anything.
-     */
-    closeSync() {
-        // NOP.
-    }
+    closeSync() { }
 }