@zenfs/core 1.7.2 → 1.8.1

package/dist/devices.d.ts

@@ -1,8 +1,9 @@
-import type { FileReadResult } from 'node:fs/promises';
+import { Inode } from './backends/index.js';
 import { InMemoryStore } from './backends/memory.js';
 import { StoreFS } from './backends/store/fs.js';
+import type { FileReadResult } from './file.js';
 import { File } from './file.js';
-import type { StatsLike } from './stats.js';
+import type { CreationOptions } from './filesystem.js';
 import { Stats } from './stats.js';
 /**
  * A device
@@ -14,11 +15,11 @@ export interface Device<TData = any> {
     /**
      * The device's driver
      */
-    driver: DeviceDriver;
+    driver: DeviceDriver<TData>;
     /**
      * Which inode the device is assigned
      */
-    ino: bigint;
+    ino: number;
     /**
      * Data associated with a device.
      * This is meant to be used by device drivers.
@@ -33,6 +34,12 @@ export interface Device<TData = any> {
      */
     minor: number;
 }
+export interface DeviceInit<TData = any> {
+    data?: TData;
+    minor?: number;
+    major?: number;
+    name?: string;
+}
 /**
  * A device driver
  */
@@ -55,22 +62,36 @@ export interface DeviceDriver<TData = any> {
      * Initializes a new device.
      * @returns `Device.data`
      */
-    init?(ino: bigint, options: object): {
-        data?: TData;
-        minor?: number;
-        major?: number;
-        name?: string;
-    };
+    init?(ino: number, options: object): DeviceInit<TData>;
     /**
-     * Synchronously read from the device
+     * Synchronously read from a device file
      * @group File operations
+     * @deprecated
+     * @todo [BREAKING] Remove
      */
     read(file: DeviceFile<TData>, buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
     /**
-     * Synchronously write to the device
+     * Synchronously read from a device.
+     * @privateRemarks
+     * For many devices there is no concept of an offset or end.
+     * For example, /dev/random will be "the same" regardless of where you read from- random data.
      * @group File operations
+     * @todo [BREAKING] Rename to `read`
+     */
+    readD(device: Device<TData>, buffer: Uint8Array, offset: number, end: number): void;
+    /**
+     * Synchronously write to a device file
+     * @group File operations
+     * @deprecated
+     * @todo [BREAKING] Remove
      */
     write(file: DeviceFile<TData>, buffer: Uint8Array, offset: number, length: number, position?: number): number;
+    /**
+     * Synchronously write to a device
+     * @group File operations
+     * @todo [BREAKING] Rename to `write`
+     */
+    writeD(device: Device<TData>, buffer: Uint8Array, offset: number): void;
     /**
      * Sync the device
      * @group File operations
@@ -94,11 +115,11 @@ export declare class DeviceFile<TData = any> extends File {
     position: number;
     constructor(fs: DeviceFS, path: string, device: Device<TData>);
     get driver(): DeviceDriver<TData>;
-    protected get stats(): Partial<StatsLike>;
+    protected stats: Inode;
     stat(): Promise<Stats>;
     statSync(): Stats;
     readSync(buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
-    read<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number): Promise<FileReadResult<TBuffer>>;
+    read<TBuffer extends ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number): Promise<FileReadResult<TBuffer>>;
     writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
     write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
     truncate(length: number): Promise<void>;
@@ -113,8 +134,6 @@ export declare class DeviceFile<TData = any> extends File {
     chmodSync(): void;
     utimes(): Promise<void>;
     utimesSync(): void;
-    _setType(): Promise<void>;
-    _setTypeSync(): void;
 }
 /**
  * A temporary file system that manages and interfaces with devices
@@ -142,20 +161,24 @@ export declare class DeviceFS extends StoreFS<InMemoryStore> {
     statSync(path: string): Stats;
     openFile(path: string, flag: string): Promise<File>;
     openFileSync(path: string, flag: string): File;
-    createFile(path: string, flag: string, mode: number): Promise<File>;
-    createFileSync(path: string, flag: string, mode: number): File;
+    createFile(path: string, flag: string, mode: number, options: CreationOptions): Promise<File>;
+    createFileSync(path: string, flag: string, mode: number, options: CreationOptions): File;
     unlink(path: string): Promise<void>;
     unlinkSync(path: string): void;
     rmdir(path: string): Promise<void>;
     rmdirSync(path: string): void;
-    mkdir(path: string, mode: number): Promise<void>;
-    mkdirSync(path: string, mode: number): void;
+    mkdir(path: string, mode: number, options: CreationOptions): Promise<void>;
+    mkdirSync(path: string, mode: number, options: CreationOptions): void;
     readdir(path: string): Promise<string[]>;
     readdirSync(path: string): string[];
     link(target: string, link: string): Promise<void>;
     linkSync(target: string, link: string): void;
     sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+    read(path: string, buffer: Uint8Array, offset: number, end: number): Promise<void>;
+    readSync(path: string, buffer: Uint8Array, offset: number, end: number): void;
+    write(path: string, data: Uint8Array, offset: number): Promise<void>;
+    writeSync(path: string, data: Uint8Array, offset: number): void;
 }
 /**
  * Simulates the `/dev/null` device.
@@ -198,6 +221,6 @@ export declare const devices: {
     full: DeviceDriver<any>;
     random: DeviceDriver<any>;
     console: DeviceDriver<{
-        output: (text: string) => unknown;
+        output: (text: string, offset: number) => unknown;
     }>;
 };

package/dist/devices.js

@@ -53,12 +53,13 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
+import { Inode } from './backends/index.js';
 import { InMemoryStore } from './backends/memory.js';
 import { StoreFS } from './backends/store/fs.js';
 import { Errno, ErrnoError } from './error.js';
 import { File } from './file.js';
 import { Stats } from './stats.js';
-import { decodeUTF8 } from './utils.js';
+import { canary, decodeUTF8 } from './utils.js';
 import { S_IFBLK, S_IFCHR } from './vfs/constants.js';
 import { basename, dirname } from './vfs/path.js';
 /**
@@ -73,28 +74,40 @@ export class DeviceFile extends File {
         this.fs = fs;
         this.device = device;
         this.position = 0;
+        this.stats = new Inode({
+            mode: (this.driver.isBuffered ? S_IFBLK : S_IFCHR) | 0o666,
+        });
     }
     get driver() {
         return this.device.driver;
     }
-    get stats() {
-        return { mode: (this.driver.isBuffered ? S_IFBLK : S_IFCHR) | 0o666 };
-    }
     async stat() {
         return Promise.resolve(new Stats(this.stats));
     }
     statSync() {
         return new Stats(this.stats);
     }
-    readSync(buffer, offset, length, position) {
-        return this.driver.read(this, buffer, offset, length, position);
+    readSync(buffer, offset = 0, length = buffer.byteLength - offset, position = this.position) {
+        this.stats.atimeMs = Date.now();
+        const end = position + length;
+        this.position = end;
+        const uint8 = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+        this.driver.readD(this.device, uint8.subarray(offset, length), position, end);
+        return length;
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async read(buffer, offset, length) {
         return { bytesRead: this.readSync(buffer, offset, length), buffer };
     }
-    writeSync(buffer, offset = 0, length = buffer.length, position) {
-        return this.driver.write(this, buffer, offset, length, position);
+    writeSync(buffer, offset = 0, length = buffer.byteLength - offset, position = this.position) {
+        const end = position + length;
+        if (end > this.stats.size)
+            this.stats.size = end;
+        this.stats.mtimeMs = Date.now();
+        this.position = end;
+        const data = buffer.subarray(offset, offset + length);
+        this.driver.writeD(this.device, data, position);
+        return length;
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async write(buffer, offset, length, position) {
@@ -144,12 +157,6 @@ export class DeviceFile extends File {
     utimesSync() {
         throw ErrnoError.With('ENOTSUP', this.path, 'utimes');
     }
-    _setType() {
-        throw ErrnoError.With('ENOTSUP', this.path, '_setType');
-    }
-    _setTypeSync() {
-        throw ErrnoError.With('ENOTSUP', this.path, '_setType');
-    }
 }
 /**
  * A temporary file system that manages and interfaces with devices
@@ -159,14 +166,17 @@ export class DeviceFS extends StoreFS {
      * Creates a new device at `path` relative to the `DeviceFS` root.
      * @deprecated
      */
+    /* node:coverage disable */
     createDevice(path, driver, options = {}) {
         var _a;
         if (this.existsSync(path)) {
             throw ErrnoError.With('EEXIST', path, 'mknod');
         }
-        let ino = BigInt(1);
+        let ino = 1;
+        const silence = canary(path, 'mknod');
         while (this.store.has(ino))
             ino++;
+        silence();
         const dev = {
             driver,
             ino,
@@ -178,6 +188,7 @@ export class DeviceFS extends StoreFS {
         this.devices.set(path, dev);
         return dev;
     }
+    /* node:coverage enable */
     devicesWithDriver(driver, forceIdentity) {
         if (forceIdentity && typeof driver == 'string') {
             throw new ErrnoError(Errno.EINVAL, 'Can not fetch devices using only a driver name');
@@ -197,7 +208,7 @@ export class DeviceFS extends StoreFS {
      */
     _createDevice(driver, options = {}) {
         var _a;
-        let ino = BigInt(1);
+        let ino = 1;
         while (this.store.has(ino))
             ino++;
         const dev = {
@@ -295,17 +306,17 @@ export class DeviceFS extends StoreFS {
         }
         return super.openFileSync(path, flag);
     }
-    async createFile(path, flag, mode) {
+    async createFile(path, flag, mode, options) {
         if (this.devices.has(path)) {
             throw ErrnoError.With('EEXIST', path, 'createFile');
         }
-        return super.createFile(path, flag, mode);
+        return super.createFile(path, flag, mode, options);
     }
-    createFileSync(path, flag, mode) {
+    createFileSync(path, flag, mode, options) {
         if (this.devices.has(path)) {
             throw ErrnoError.With('EEXIST', path, 'createFile');
         }
-        return super.createFileSync(path, flag, mode);
+        return super.createFileSync(path, flag, mode, options);
     }
     async unlink(path) {
         if (this.devices.has(path)) {
@@ -325,17 +336,17 @@ export class DeviceFS extends StoreFS {
     rmdirSync(path) {
         return super.rmdirSync(path);
     }
-    async mkdir(path, mode) {
+    async mkdir(path, mode, options) {
         if (this.devices.has(path)) {
             throw ErrnoError.With('EEXIST', path, 'mkdir');
         }
-        return super.mkdir(path, mode);
+        return super.mkdir(path, mode, options);
     }
-    mkdirSync(path, mode) {
+    mkdirSync(path, mode, options) {
         if (this.devices.has(path)) {
             throw ErrnoError.With('EEXIST', path, 'mkdir');
         }
-        return super.mkdirSync(path, mode);
+        return super.mkdirSync(path, mode, options);
     }
     async readdir(path) {
         const entries = await super.readdir(path);
@@ -385,11 +396,56 @@ export class DeviceFS extends StoreFS {
         }
         return super.syncSync(path, data, stats);
     }
+    async read(path, buffer, offset, end) {
+        const device = this.devices.get(path);
+        if (!device) {
+            await super.read(path, buffer, offset, end);
+            return;
+        }
+        device.driver.readD(device, buffer, offset, end);
+    }
+    readSync(path, buffer, offset, end) {
+        const device = this.devices.get(path);
+        if (!device) {
+            super.readSync(path, buffer, offset, end);
+            return;
+        }
+        device.driver.readD(device, buffer, offset, end);
+    }
+    async write(path, data, offset) {
+        const device = this.devices.get(path);
+        if (!device) {
+            return await super.write(path, data, offset);
+        }
+        device.driver.writeD(device, data, offset);
+    }
+    writeSync(path, data, offset) {
+        const device = this.devices.get(path);
+        if (!device) {
+            return super.writeSync(path, data, offset);
+        }
+        device.driver.writeD(device, data, offset);
+    }
+}
+function defaultWrite(file, buffer, offset, length, position) {
+    return file.writeSync(buffer, offset, length, position);
 }
-function defaultWrite(file, buffer, offset, length) {
-    file.position += length;
-    return length;
+function defaultWriteD(device, data, offset) {
+    return;
 }
+function defaultRead(file, buffer, offset, length, position) {
+    return file.readSync(buffer, offset, length, position);
+}
+// 512 bytes.
+const blockSize = 0x200;
+function alloc(bytesNeeded, existing) {
+    const blocksNeeded = bytesNeeded / blockSize;
+    const currentBocks = existing ? existing.byteLength / blockSize : 0;
+    if (blocksNeeded <= currentBocks && existing)
+        return existing;
+    return new Uint8Array(Math.ceil(blocksNeeded));
+}
+const emptyBuffer = new Uint8Array();
 /**
  * Simulates the `/dev/null` device.
  * - Reads return 0 bytes (EOF).
@@ -405,7 +461,11 @@ export const nullDevice = {
     read() {
         return 0;
     },
+    readD() {
+        return emptyBuffer;
+    },
     write: defaultWrite,
+    writeD: defaultWriteD,
 };
 /**
  * Simulates the `/dev/zero` device
@@ -423,15 +483,12 @@ export const zeroDevice = {
     init() {
         return { major: 1, minor: 5 };
     },
-    read(file, buffer, offset = 0, length = buffer.byteLength) {
-        const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-        for (let i = offset; i < offset + length; i++) {
-            data[i] = 0;
-        }
-        file.position += length;
-        return length;
+    read: defaultRead,
+    readD(device, buffer, offset, end) {
+        buffer.fill(0, offset, end);
     },
     write: defaultWrite,
+    writeD: defaultWriteD,
 };
 /**
  * Simulates the `/dev/full` device.
@@ -445,17 +502,16 @@ export const fullDevice = {
     init() {
         return { major: 1, minor: 7 };
     },
-    read(file, buffer, offset = 0, length = buffer.byteLength) {
-        const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-        for (let i = offset; i < offset + length; i++) {
-            data[i] = 0;
-        }
-        file.position += length;
-        return length;
+    read: defaultRead,
+    readD(device, buffer, offset, end) {
+        buffer.fill(0, offset, end);
     },
     write(file) {
         throw ErrnoError.With('ENOSPC', file.path, 'write');
     },
+    writeD() {
+        throw ErrnoError.With('ENOSPC', undefined, 'write');
+    },
 };
 /**
  * Simulates the `/dev/random` device.
@@ -469,15 +525,14 @@ export const randomDevice = {
     init() {
         return { major: 1, minor: 8 };
     },
-    read(file, buffer, offset = 0, length = buffer.byteLength) {
-        const data = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-        for (let i = offset; i < offset + length; i++) {
-            data[i] = Math.floor(Math.random() * 256);
+    read: defaultRead,
+    readD(device, buffer) {
+        for (let i = 0; i < buffer.length; i++) {
+            buffer[i] = Math.floor(Math.random() * 256);
         }
-        file.position += length;
-        return length;
     },
     write: defaultWrite,
+    writeD: defaultWriteD,
 };
 /**
  * Simulates the `/dev/console` device.
@@ -486,17 +541,17 @@ export const randomDevice = {
 const consoleDevice = {
     name: 'console',
     singleton: true,
-    init(ino, { output = console.log } = {}) {
+    init(ino, { output = text => console.log(text) } = {}) {
         return { major: 5, minor: 1, data: { output } };
     },
-    read() {
-        return 0;
+    read: defaultRead,
+    readD() {
+        return emptyBuffer;
     },
-    write(file, buffer, offset, length) {
-        const text = decodeUTF8(buffer.slice(offset, offset + length));
-        file.device.data.output(text);
-        file.position += length;
-        return length;
+    write: defaultWrite,
+    writeD(device, buffer, offset) {
+        const text = decodeUTF8(buffer);
+        device.data.output(text, offset);
     },
 };
 /**

package/dist/file.d.ts

@@ -1,7 +1,6 @@
-import type { FileReadResult } from 'node:fs/promises';
 import type { FileSystem } from './filesystem.js';
 import './polyfills.js';
-import { Stats } from './stats.js';
+import { Stats, type StatsLike } from './stats.js';
 export declare function parseFlag(flag: string | number): string;
 export declare function flagToString(flag: number): string;
 export declare function flagToNumber(flag: string): number;
@@ -16,6 +15,10 @@ export declare function isTruncating(flag: string): boolean;
 export declare function isAppendable(flag: string): boolean;
 export declare function isSynchronous(flag: string): boolean;
 export declare function isExclusive(flag: string): boolean;
+export interface FileReadResult<T extends ArrayBufferView> {
+    bytesRead: number;
+    buffer: T;
+}
 export declare abstract class File<FS extends FileSystem = FileSystem> {
     /**
      * @internal
@@ -71,7 +74,7 @@ export declare abstract class File<FS extends FileSystem = FileSystem> {
      * 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>>;
+    abstract read<TBuffer extends ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<FileReadResult<TBuffer>>;
     /**
      * Read data from the file.
      * @param buffer The buffer that the data will be written to.
@@ -96,11 +99,11 @@ export declare abstract class File<FS extends FileSystem = FileSystem> {
     /**
      * Change the file timestamps of the file.
      */
-    abstract utimes(atime: Date, mtime: Date): Promise<void>;
+    abstract utimes(atime: number, mtime: number): Promise<void>;
     /**
      * Change the file timestamps of the file.
      */
-    abstract utimesSync(atime: Date, mtime: Date): void;
+    abstract utimesSync(atime: number, mtime: number): void;
 }
 /**
  * An implementation of `File` that operates completely in-memory.
@@ -209,11 +212,12 @@ export declare class PreloadFile<FS extends FileSystem> extends File<FS> {
     chmodSync(mode: number): void;
     chown(uid: number, gid: number): Promise<void>;
     chownSync(uid: number, gid: number): void;
-    utimes(atime: Date, mtime: Date): Promise<void>;
-    utimesSync(atime: Date, mtime: Date): void;
+    utimes(atime: number, mtime: number): Promise<void>;
+    utimesSync(atime: number, mtime: number): void;
 }
 /**
  * For the file systems which do not sync to anything.
+ * @deprecated
  */
 export declare class NoSyncFile<T extends FileSystem> extends PreloadFile<T> {
     sync(): Promise<void>;
@@ -221,3 +225,103 @@ export declare class NoSyncFile<T extends FileSystem> extends PreloadFile<T> {
     close(): Promise<void>;
     closeSync(): void;
 }
+/**
+ * An implementation of `File` that uses the FS
+ */
+export declare class LazyFile<FS extends FileSystem> extends File<FS> {
+    readonly flag: string;
+    readonly stats: StatsLike<number>;
+    protected _buffer?: Uint8Array;
+    /**
+     * Current position
+     */
+    protected _position: number;
+    /**
+     * 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
+     */
+    protected dirty: boolean;
+    /**
+     * Whether the file is open or closed
+     */
+    protected closed: boolean;
+    /**
+     * Creates a file with `path` and, optionally, the given contents.
+     * Note that, if contents is specified, it will be mutated by the file.
+     */
+    constructor(fs: FS, path: string, flag: string, stats: StatsLike<number>);
+    sync(): Promise<void>;
+    syncSync(): void;
+    close(): Promise<void>;
+    closeSync(): void;
+    /**
+     * Cleans up. This will *not* sync the file data to the FS
+     */
+    protected dispose(force?: boolean): void;
+    stat(): Promise<Stats>;
+    statSync(): Stats;
+    truncate(length: number): Promise<void>;
+    truncateSync(length: number): void;
+    protected prepareWrite(buffer: Uint8Array, offset: number, length: number, position: number): Uint8Array;
+    /**
+     * 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.
+     */
+    write(buffer: Uint8Array, offset?: number, length?: number, position?: number): Promise<number>;
+    /**
+     * 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.
+     * @returns bytes written
+     */
+    writeSync(buffer: Uint8Array, offset?: number, length?: number, position?: number): number;
+    /**
+     * Computes position information for reading
+     */
+    protected prepareRead(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 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.
+     */
+    read<TBuffer extends ArrayBufferView>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
+        bytesRead: number;
+        buffer: TBuffer;
+    }>;
+    /**
+     * 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 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;
+    chmod(mode: number): Promise<void>;
+    chmodSync(mode: number): void;
+    chown(uid: number, gid: number): Promise<void>;
+    chownSync(uid: number, gid: number): void;
+    utimes(atime: number, mtime: number): Promise<void>;
+    utimesSync(atime: number, mtime: number): void;
+}