@zenfs/core 1.5.0 → 1.6.0

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import type { Backend, BackendConfiguration, FilesystemOf, SharedConfig } from './backends/backend.js';
+import { type Device, type DeviceDriver } from './devices.js';
 /**
  * Configuration for a specific mount point
  */
@@ -85,6 +86,7 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
  * Configures ZenFS with single mount point /
  */
 export declare function configureSingle<T extends Backend>(configuration: MountConfiguration<T>): Promise<void>;
+export declare function addDevice(driver: DeviceDriver, options?: object): Device;
 /**
  * Configures ZenFS with `configuration`
  * @see Configuration

package/dist/config.js

@@ -4,6 +4,7 @@ import { DeviceFS } from './devices.js';
 import * as cache from './emulation/cache.js';
 import { config } from './emulation/config.js';
 import * as fs from './emulation/index.js';
+import { mounts } from './emulation/shared.js';
 import { Errno, ErrnoError } from './error.js';
 import { FileSystem } from './filesystem.js';
 function isMountConfig(arg) {
@@ -80,6 +81,12 @@ async function mount(path, mount) {
     }
     fs.mount(path, mount);
 }
+export function addDevice(driver, options) {
+    const devfs = mounts.get('/dev');
+    if (!(devfs instanceof DeviceFS))
+        throw new ErrnoError(Errno.ENOTSUP, '/dev does not exist or is not a device file system');
+    return devfs._createDevice(driver, options);
+}
 /**
  * Configures ZenFS with `configuration`
  * @see Configuration

package/dist/devices.d.ts

@@ -8,7 +8,7 @@ import { Stats } from './stats.js';
  * A device
  * @todo Maybe add major/minor number or some other device information, like a UUID?
  * @privateRemarks
- * UUIDs were considered, however they don't make sense without an easy mechanism for persistance
+ * UUIDs were considered, however they don't make sense without an easy mechanism for persistence
  */
 export interface Device<TData = any> {
     /**
@@ -22,17 +22,14 @@ export interface Device<TData = any> {
     /**
      * Data associated with a device.
      * This is meant to be used by device drivers.
-     * @experimental
      */
     data: TData;
     /**
      * Major device number
-     * @experimental
      */
     major: number;
     /**
      * Minor device number
-     * @experimental
      */
     minor: number;
 }
@@ -44,6 +41,11 @@ export interface DeviceDriver<TData = any> {
      * The name of the device driver
      */
     name: string;
+    /**
+     * If true, only a single device can exist per device FS.
+     * Note that if this is unset or false, auto-named devices will have a number suffix
+     */
+    singleton?: boolean;
     /**
      * Whether the device is buffered (a "block" device) or unbuffered (a "character" device)
      * @default false
@@ -52,33 +54,33 @@ export interface DeviceDriver<TData = any> {
     /**
      * Initializes a new device.
      * @returns `Device.data`
-     * @experimental
      */
-    init?(ino: bigint): {
+    init?(ino: bigint, options: object): {
         data?: TData;
         minor?: number;
         major?: number;
+        name?: string;
     };
     /**
      * Synchronously read from the device
      * @group File operations
      */
-    read(file: DeviceFile, buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
+    read(file: DeviceFile<TData>, buffer: ArrayBufferView, offset?: number, length?: number, position?: number): number;
     /**
      * Synchronously write to the device
      * @group File operations
      */
-    write(file: DeviceFile, buffer: Uint8Array, offset: number, length: number, position?: number): number;
+    write(file: DeviceFile<TData>, buffer: Uint8Array, offset: number, length: number, position?: number): number;
     /**
      * Sync the device
      * @group File operations
      */
-    sync?(file: DeviceFile): void;
+    sync?(file: DeviceFile<TData>): void;
     /**
      * Close the device
      * @group File operations
      */
-    close?(file: DeviceFile): void;
+    close?(file: DeviceFile<TData>): void;
 }
 /**
  * The base class for device files
@@ -86,12 +88,12 @@ export interface DeviceDriver<TData = any> {
  * It implements `truncate` using `write` and it has non-device methods throw.
  * It is up to device drivers to implement the rest of the functionality.
  */
-export declare class DeviceFile extends File {
+export declare class DeviceFile<TData = any> extends File {
     fs: DeviceFS;
-    readonly device: Device;
+    readonly device: Device<TData>;
     position: number;
-    constructor(fs: DeviceFS, path: string, device: Device);
-    get driver(): DeviceDriver;
+    constructor(fs: DeviceFS, path: string, device: Device<TData>);
+    get driver(): DeviceDriver<TData>;
     protected get stats(): Partial<StatsLike>;
     stat(): Promise<Stats>;
     statSync(): Stats;
@@ -121,8 +123,14 @@ export declare class DeviceFS extends StoreFS<InMemoryStore> {
     protected readonly devices: Map<string, Device<any>>;
     /**
      * Creates a new device at `path` relative to the `DeviceFS` root.
+     * @deprecated
+     */
+    createDevice<TData = any>(path: string, driver: DeviceDriver<TData>, options?: object): Device<TData | Record<string, never>>;
+    protected devicesWithDriver(driver: DeviceDriver<unknown> | string, forceIdentity?: boolean): Device[];
+    /**
+     * @internal
      */
-    createDevice<TData = any>(path: string, driver: DeviceDriver<TData>): Device<TData | Record<string, never>>;
+    _createDevice<TData = any>(driver: DeviceDriver<TData>, options?: object): Device<TData | Record<string, never>>;
     /**
      * Adds default devices
      */
@@ -153,7 +161,7 @@ export declare class DeviceFS extends StoreFS<InMemoryStore> {
  * Simulates the `/dev/null` device.
  * - Reads return 0 bytes (EOF).
  * - Writes discard data, advancing the file position.
- * @experimental
+ * @internal
  */
 export declare const nullDevice: DeviceDriver;
 /**
@@ -164,31 +172,32 @@ export declare const nullDevice: DeviceDriver;
  * - Reads fill the buffer with zeroes.
  * - Writes discard data but update the file position.
  * - Provides basic file metadata, treating it as a character device.
- * @experimental
+ * @internal
  */
 export declare const zeroDevice: DeviceDriver;
 /**
  * Simulates the `/dev/full` device.
  * - Reads behave like `/dev/zero` (returns zeroes).
  * - Writes always fail with ENOSPC (no space left on device).
- * @experimental
+ * @internal
  */
 export declare const fullDevice: DeviceDriver;
 /**
  * Simulates the `/dev/random` device.
  * - Reads return random bytes.
  * - Writes discard data, advancing the file position.
- * @experimental
+ * @internal
  */
 export declare const randomDevice: DeviceDriver;
 /**
  * Shortcuts for importing.
- * @experimental
  */
-declare const _default: {
+export declare const devices: {
     null: DeviceDriver<any>;
     zero: DeviceDriver<any>;
     full: DeviceDriver<any>;
     random: DeviceDriver<any>;
+    console: DeviceDriver<{
+        output: (text: string) => unknown;
+    }>;
 };
-export default _default;

package/dist/devices.js

@@ -60,6 +60,7 @@ import { Errno, ErrnoError } from './error.js';
 import { File } from './file.js';
 import { Stats } from './stats.js';
 import { basename, dirname } from './emulation/path.js';
+import { decodeUTF8 } from './utils.js';
 /**
  * The base class for device files
  * This class only does some simple things:
@@ -154,8 +155,9 @@ export class DeviceFile extends File {
 export class DeviceFS extends StoreFS {
     /**
      * Creates a new device at `path` relative to the `DeviceFS` root.
+     * @deprecated
      */
-    createDevice(path, driver) {
+    createDevice(path, driver, options = {}) {
         if (this.existsSync(path)) {
             throw ErrnoError.With('EEXIST', path, 'mknod');
         }
@@ -168,19 +170,56 @@ export class DeviceFS extends StoreFS {
             data: {},
             minor: 0,
             major: 0,
-            ...driver.init?.(ino),
+            ...driver.init?.(ino, options),
         };
         this.devices.set(path, dev);
         return dev;
     }
+    devicesWithDriver(driver, forceIdentity) {
+        if (forceIdentity && typeof driver == 'string') {
+            throw new ErrnoError(Errno.EINVAL, 'Can not fetch devices using only a driver name');
+        }
+        const devs = [];
+        for (const device of this.devices.values()) {
+            if (forceIdentity && device.driver != driver)
+                continue;
+            const name = typeof driver == 'string' ? driver : driver.name;
+            if (name == device.driver.name)
+                devs.push(device);
+        }
+        return devs;
+    }
+    /**
+     * @internal
+     */
+    _createDevice(driver, options = {}) {
+        let ino = 1n;
+        while (this.store.has(ino))
+            ino++;
+        const dev = {
+            driver,
+            ino,
+            data: {},
+            minor: 0,
+            major: 0,
+            ...driver.init?.(ino, options),
+        };
+        const path = '/' + (dev.name || driver.name) + (driver.singleton ? '' : this.devicesWithDriver(driver).length);
+        if (this.existsSync(path)) {
+            throw ErrnoError.With('EEXIST', path, 'mknod');
+        }
+        this.devices.set(path, dev);
+        return dev;
+    }
     /**
      * Adds default devices
      */
     addDefaults() {
-        this.createDevice('/null', nullDevice);
-        this.createDevice('/zero', zeroDevice);
-        this.createDevice('/full', fullDevice);
-        this.createDevice('/random', randomDevice);
+        this._createDevice(nullDevice);
+        this._createDevice(zeroDevice);
+        this._createDevice(fullDevice);
+        this._createDevice(randomDevice);
+        this._createDevice(consoleDevice);
     }
     constructor() {
         super(new InMemoryStore('devfs'));
@@ -351,10 +390,11 @@ function defaultWrite(file, buffer, offset, length) {
  * Simulates the `/dev/null` device.
  * - Reads return 0 bytes (EOF).
  * - Writes discard data, advancing the file position.
- * @experimental
+ * @internal
  */
 export const nullDevice = {
     name: 'null',
+    singleton: true,
     init() {
         return { major: 1, minor: 3 };
     },
@@ -371,10 +411,11 @@ export const nullDevice = {
  * - Reads fill the buffer with zeroes.
  * - Writes discard data but update the file position.
  * - Provides basic file metadata, treating it as a character device.
- * @experimental
+ * @internal
  */
 export const zeroDevice = {
     name: 'zero',
+    singleton: true,
     init() {
         return { major: 1, minor: 5 };
     },
@@ -392,10 +433,11 @@ export const zeroDevice = {
  * Simulates the `/dev/full` device.
  * - Reads behave like `/dev/zero` (returns zeroes).
  * - Writes always fail with ENOSPC (no space left on device).
- * @experimental
+ * @internal
  */
 export const fullDevice = {
     name: 'full',
+    singleton: true,
     init() {
         return { major: 1, minor: 7 };
     },
@@ -415,10 +457,11 @@ export const fullDevice = {
  * Simulates the `/dev/random` device.
  * - Reads return random bytes.
  * - Writes discard data, advancing the file position.
- * @experimental
+ * @internal
  */
 export const randomDevice = {
     name: 'random',
+    singleton: true,
     init() {
         return { major: 1, minor: 8 };
     },
@@ -432,13 +475,33 @@ export const randomDevice = {
     },
     write: defaultWrite,
 };
+/**
+ * Simulates the `/dev/console` device.
+ * @experimental @internal
+ */
+const consoleDevice = {
+    name: 'console',
+    singleton: true,
+    init(ino, { output = console.log } = {}) {
+        return { major: 5, minor: 1, data: { output } };
+    },
+    read() {
+        return 0;
+    },
+    write(file, buffer, offset, length) {
+        const text = decodeUTF8(buffer.slice(offset, offset + length));
+        file.device.data.output(text);
+        file.position += length;
+        return length;
+    },
+};
 /**
  * Shortcuts for importing.
- * @experimental
  */
-export default {
+export const devices = {
     null: nullDevice,
     zero: zeroDevice,
     full: fullDevice,
     random: randomDevice,
+    console: consoleDevice,
 };

package/dist/emulation/async.d.ts

@@ -1,5 +1,6 @@
 import { Buffer } from 'buffer';
 import type * as fs from 'node:fs';
+import { ErrnoError } from '../error.js';
 import type { FileContents } from '../filesystem.js';
 import { BigIntStats, type Stats } from '../stats.js';
 import { type Callback } from '../utils.js';
@@ -309,4 +310,12 @@ export declare function statfs(this: V_Context, path: fs.PathLike, options: fs.S
     bigint: true;
 }, callback: Callback<[fs.BigIntStatsFs]>): void;
 export declare function openAsBlob(this: V_Context, path: fs.PathLike, options?: fs.OpenAsBlobOptions): Promise<Blob>;
+type GlobCallback<Args extends unknown[]> = (e: ErrnoError | null, ...args: Args) => unknown;
+/**
+ * Retrieves the files matching the specified pattern.
+ */
+export declare function glob(this: V_Context, pattern: string | string[], callback: GlobCallback<[string[]]>): void;
+export declare function glob(this: V_Context, pattern: string | string[], options: fs.GlobOptionsWithFileTypes, callback: GlobCallback<[Dirent[]]>): void;
+export declare function glob(this: V_Context, pattern: string | string[], options: fs.GlobOptionsWithoutFileTypes, callback: GlobCallback<[string[]]>): void;
+export declare function glob(this: V_Context, pattern: string | string[], options: fs.GlobOptions, callback: GlobCallback<[Dirent[] | string[]]>): void;
 export {};

package/dist/emulation/async.js

@@ -8,6 +8,16 @@ import { fd2file, fdMap } from './shared.js';
 import { ReadStream, WriteStream } from './streams.js';
 import { FSWatcher, StatWatcher } from './watchers.js';
 const nop = () => { };
+/**
+ * Helper to collect an async iterator into an array
+ */
+async function collectAsyncIterator(it) {
+    const results = [];
+    for await (const result of it) {
+        results.push(result);
+    }
+    return results;
+}
 /**
  * Asynchronous rename. No arguments other than a possible exception are given to the completion callback.
  */
@@ -556,3 +566,11 @@ export async function openAsBlob(path, options) {
     return new Blob([buffer], options);
 }
 openAsBlob;
+export function glob(pattern, options, callback = nop) {
+    callback = typeof options == 'function' ? options : callback;
+    const it = promises.glob.call(this, pattern, typeof options === 'function' ? undefined : options);
+    collectAsyncIterator(it)
+        .then(results => callback(null, results ?? []))
+        .catch((e) => callback(e));
+}
+glob;

package/dist/emulation/dir.d.ts

@@ -19,7 +19,7 @@ export declare class Dirent implements _Dirent {
 /**
  * A class representing a directory stream.
  */
-export declare class Dir implements _Dir {
+export declare class Dir implements _Dir, AsyncIterator<Dirent> {
     readonly path: string;
     protected readonly context: V_Context;
     protected closed: boolean;
@@ -55,5 +55,6 @@ export declare class Dir implements _Dir {
     /**
      * Asynchronously iterates over the directory via `readdir(3)` until all entries have been read.
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<Dirent>;
+    [Symbol.asyncIterator](): this;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/emulation/dir.js

@@ -102,4 +102,7 @@ export class Dir {
     [Symbol.asyncIterator]() {
         return this;
     }
+    [Symbol.asyncDispose]() {
+        return Promise.resolve();
+    }
 }

package/dist/emulation/index.d.ts

@@ -4,5 +4,6 @@ export * as promises from './promises.js';
 export * as constants from './constants.js';
 export * from './streams.js';
 export * from './dir.js';
-export { mountObject, mounts, mount, umount, _synced, chroot } from './shared.js';
+export { mount, umount, chroot, mountObject } from './shared.js';
+export { /** @deprecated security */ mounts } from './shared.js';
 export { Stats, StatsFs, BigIntStatsFs } from '../stats.js';

package/dist/emulation/index.js

@@ -4,5 +4,6 @@ export * as promises from './promises.js';
 export * as constants from './constants.js';
 export * from './streams.js';
 export * from './dir.js';
-export { mountObject, mounts, mount, umount, _synced, chroot } from './shared.js';
+export { mount, umount, chroot, mountObject } from './shared.js';
+export { /** @deprecated security */ mounts } from './shared.js';
 export { Stats, StatsFs, BigIntStatsFs } from '../stats.js';

package/dist/emulation/promises.d.ts

@@ -10,8 +10,8 @@ import type { FileContents } from '../filesystem.js';
 import '../polyfills.js';
 import { BigIntStats, type Stats } from '../stats.js';
 import { Dir, Dirent } from './dir.js';
-import { type InternalOptions, type ReaddirOptions } from './shared.js';
 import { ReadStream, WriteStream } from './streams.js';
+import type { InternalOptions, NullEnc, ReaddirOptions, ReaddirOptsI, ReaddirOptsU } from './types.js';
 export * as constants from './constants.js';
 export declare class FileHandle implements promises.FileHandle {
     protected context?: V_Context | undefined;
@@ -71,7 +71,9 @@ 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 | null): Promise<promises.FileReadResult<TBuffer>>;
+    read<T extends NodeJS.ArrayBufferView>(buffer: T, offset?: number, length?: number, position?: number | null): Promise<promises.FileReadResult<T>>;
+    read<T extends NodeJS.ArrayBufferView = Buffer>(buffer: T, options?: promises.FileReadOptions<T>): Promise<promises.FileReadResult<T>>;
+    read<T extends NodeJS.ArrayBufferView = Buffer>(options?: promises.FileReadOptions<T>): Promise<promises.FileReadResult<T>>;
     /**
      * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
      * The `FileHandle` must have been opened for reading.
@@ -90,9 +92,6 @@ export declare class FileHandle implements promises.FileHandle {
      * While the `ReadableStream` will read the file to completion,
      * it will not close the `FileHandle` automatically.
      * User code must still call the `fileHandle.close()` method.
-     *
-     * @since v17.0.0
-     * @experimental
      */
     readableWebStream(options?: promises.ReadableWebStreamOptions): TReadableStream<Uint8Array>;
     /**
@@ -113,17 +112,13 @@ export declare class FileHandle implements promises.FileHandle {
      * 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<{
+    write<T extends FileContents>(data: T, options?: number | null | {
+        offset?: number;
+        length?: number;
+        position?: number;
+    }, lenOrEnc?: BufferEncoding | number | null, position?: number | null): Promise<{
         bytesWritten: number;
-        buffer: TBuffer;
-    }>;
-    write(data: string, position?: number, encoding?: BufferEncoding): Promise<{
-        bytesWritten: number;
-        buffer: string;
+        buffer: T;
     }>;
     /**
      * Asynchronously writes data to a file, replacing the file if it already exists. The underlying file will _not_ be closed automatically.
@@ -256,19 +251,19 @@ export declare function mkdir(this: V_Context, path: fs.PathLike, options?: fs.M
  * @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'`.
  */
-export declare function readdir(this: V_Context, path: fs.PathLike, options?: (fs.ObjectEncodingOptions & ReaddirOptions & {
+export declare function readdir(this: V_Context, path: fs.PathLike, options?: ReaddirOptsI<{
     withFileTypes?: false;
-}) | BufferEncoding | null): Promise<string[]>;
+}> | NullEnc): Promise<string[]>;
 export declare function readdir(this: V_Context, path: fs.PathLike, options: fs.BufferEncodingOption & ReaddirOptions & {
     withFileTypes?: false;
 }): Promise<Buffer[]>;
-export declare function readdir(this: V_Context, path: fs.PathLike, options?: (fs.ObjectEncodingOptions & ReaddirOptions & {
+export declare function readdir(this: V_Context, path: fs.PathLike, options?: ReaddirOptsI<{
     withFileTypes?: false;
-}) | BufferEncoding | null): Promise<string[] | Buffer[]>;
-export declare function readdir(this: V_Context, path: fs.PathLike, options: fs.ObjectEncodingOptions & ReaddirOptions & {
+}> | NullEnc): Promise<string[] | Buffer[]>;
+export declare function readdir(this: V_Context, path: fs.PathLike, options: ReaddirOptsI<{
     withFileTypes: true;
-}): Promise<Dirent[]>;
-export declare function readdir(this: V_Context, path: fs.PathLike, options?: (ReaddirOptions & (fs.ObjectEncodingOptions | fs.BufferEncodingOption)) | BufferEncoding | null): Promise<string[] | Dirent[] | Buffer[]>;
+}>): 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>;
 /**
  * `symlink`.
@@ -357,3 +352,11 @@ export declare function statfs(this: V_Context, path: fs.PathLike, opts: fs.Stat
     bigint: true;
 }): Promise<fs.BigIntStatsFs>;
 export declare function statfs(this: V_Context, path: fs.PathLike, opts?: fs.StatFsOptions): Promise<fs.StatsFs | fs.BigIntStatsFs>;
+/**
+ * Retrieves the files matching the specified pattern.
+ * @todo Implement
+ */
+export declare function glob(this: V_Context, pattern: string | string[]): NodeJS.AsyncIterator<string>;
+export declare function glob(this: V_Context, pattern: string | string[], opt: fs.GlobOptionsWithFileTypes): NodeJS.AsyncIterator<Dirent>;
+export declare function glob(this: V_Context, pattern: string | string[], opt: fs.GlobOptionsWithoutFileTypes): NodeJS.AsyncIterator<string>;
+export declare function glob(this: V_Context, pattern: string | string[], opt: fs.GlobOptions): NodeJS.AsyncIterator<Dirent | string>;

package/dist/emulation/promises.js

@@ -147,19 +147,23 @@ export class FileHandle {
         await this.file.write(encodedData, 0, encodedData.length);
         emitChange('change', this.file.path);
     }
-    /**
-     * 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(buffer, offset, length, position) {
+    async read(buffer, offset, length, position) {
+        if (typeof offset == 'object' && offset != null) {
+            position = offset.position;
+            length = offset.length;
+            offset = offset.offset;
+        }
+        if (!ArrayBuffer.isView(buffer) && typeof buffer == 'object') {
+            position = buffer.position;
+            length = buffer.length;
+            offset = buffer.offset;
+            buffer = buffer.buffer;
+        }
         if (isNaN(+position)) {
             position = this.file.position;
         }
-        return this.file.read(buffer, offset, length, position);
+        buffer || (buffer = new Uint8Array((await this.file.stat()).size));
+        return this.file.read(buffer, offset ?? undefined, length ?? undefined, position ?? undefined);
     }
     async readFile(_options) {
         const options = normalizeOptions(_options, null, 'r', 0o444);
@@ -180,9 +184,6 @@ export class FileHandle {
      * While the `ReadableStream` will read the file to completion,
      * it will not close the `FileHandle` automatically.
      * User code must still call the `fileHandle.close()` method.
-     *
-     * @since v17.0.0
-     * @experimental
      */
     readableWebStream(options = {}) {
         // Note: using an arrow function to preserve `this`
@@ -230,27 +231,36 @@ export class FileHandle {
         }
         return opts?.bigint ? new BigIntStats(stats) : stats;
     }
-    async write(data, posOrOff, lenOrEnc, position) {
+    /**
+     * 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.
+     */
+    async write(data, options, lenOrEnc, position) {
         let buffer, offset, length;
+        if (typeof options == 'object') {
+            lenOrEnc = options?.length;
+            position = options?.position;
+            options = options?.offset;
+        }
         if (typeof data === 'string') {
-            // Signature 1: (fd, string, [position?, [encoding?]])
-            position = typeof posOrOff === 'number' ? posOrOff : null;
+            position = typeof options === 'number' ? options : null;
             const encoding = typeof lenOrEnc === 'string' ? lenOrEnc : 'utf8';
             offset = 0;
             buffer = Buffer.from(data, encoding);
             length = buffer.length;
         }
         else {
-            // Signature 2: (fd, buffer, offset, length, position?)
             buffer = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-            offset = posOrOff;
+            offset = options;
             length = lenOrEnc;
             position = typeof position === 'number' ? position : null;
         }
         position ?? (position = this.file.position);
         const bytesWritten = await this.file.write(buffer, offset, length, position);
         emitChange('change', this.file.path);
-        return { buffer, bytesWritten };
+        return { buffer: data, bytesWritten };
     }
     /**
      * Asynchronously writes data to a file, replacing the file if it already exists. The underlying file will _not_ be closed automatically.
@@ -938,6 +948,9 @@ export function watch(filename, options = {}) {
                 },
                 return: cleanup,
                 throw: cleanup,
+                [Symbol.asyncDispose]() {
+                    return Promise.resolve();
+                },
             };
         },
     };
@@ -1088,3 +1101,35 @@ export async function statfs(path, opts) {
     const { fs } = resolveMount(path, this);
     return Promise.resolve(_statfs(fs, opts?.bigint));
 }
+export function glob(pattern, opt) {
+    pattern = Array.isArray(pattern) ? pattern : [pattern];
+    const { cwd = '/', withFileTypes = false, exclude = () => false } = opt || {};
+    // Escape special characters in pattern
+    const regexPatterns = pattern.map(p => {
+        p = p
+            .replace(/([.?+^$(){}|[\]/])/g, '$1')
+            .replace(/\*\*/g, '.*')
+            .replace(/\*/g, '[^/]*')
+            .replace(/\?/g, '.');
+        return new RegExp(`^${p}$`);
+    });
+    async function* recursiveList(dir) {
+        const entries = await readdir(dir, { withFileTypes, encoding: 'utf8' });
+        for (const entry of entries) {
+            const fullPath = withFileTypes ? entry.path : dir + '/' + entry;
+            if (exclude((withFileTypes ? entry : fullPath)))
+                continue;
+            /**
+             * @todo it the pattern.source check correct?
+             */
+            if ((await stat(fullPath)).isDirectory() && regexPatterns.some(pattern => pattern.source.includes('.*'))) {
+                yield* recursiveList(fullPath);
+            }
+            if (regexPatterns.some(pattern => pattern.test(fullPath.replace(/^\/+/g, '')))) {
+                yield withFileTypes ? entry : fullPath.replace(/^\/+/g, '');
+            }
+        }
+    }
+    return recursiveList(cwd);
+}
+glob;

package/dist/emulation/shared.d.ts

@@ -1,4 +1,4 @@
-import type { BigIntStatsFs, StatsFs } from 'node:fs';
+import type * as fs from 'node:fs';
 import { type BoundContext, type V_Context } from '../context.js';
 import { ErrnoError } from '../error.js';
 import type { File } from '../file.js';
@@ -48,12 +48,6 @@ export interface ResolvedMount {
  * @internal @hidden
  */
 export declare function resolveMount(path: string, ctx: V_Context): ResolvedMount;
-/**
- * Wait for all file systems to be ready and synced.
- * May be removed at some point.
- * @experimental @internal
- */
-export declare function _synced(): Promise<void>;
 /**
  * Reverse maps the paths in text from the mounted FileSystem to the global path
  * @internal @hidden
@@ -71,23 +65,7 @@ export declare function mountObject(mounts: MountObject): void;
 /**
  * @internal @hidden
  */
-export declare function _statfs<const T extends boolean>(fs: FileSystem, bigint?: T): T extends true ? BigIntStatsFs : StatsFs;
-/**
- * Options used for caching, among other things.
- * @internal @hidden *UNSTABLE*
- */
-export interface InternalOptions {
-    /**
-     * If true, then this readdir was called from another function.
-     * In this case, don't clear the cache when done.
-     * @internal *UNSTABLE*
-     */
-    _isIndirect?: boolean;
-}
-export interface ReaddirOptions extends InternalOptions {
-    withFileTypes?: boolean;
-    recursive?: boolean;
-}
+export declare function _statfs<const T extends boolean>(fs: FileSystem, bigint?: T): T extends true ? fs.BigIntStatsFs : fs.StatsFs;
 /**
  * Change the root path
  * @param inPlace if true, this changes the root for the current context instead of creating a new one (if associated with a context).

package/dist/emulation/shared.js

@@ -85,15 +85,6 @@ export function resolveMount(path, ctx) {
     }
     throw new ErrnoError(Errno.EIO, 'No file system');
 }
-/**
- * Wait for all file systems to be ready and synced.
- * May be removed at some point.
- * @experimental @internal
- */
-export async function _synced() {
-    await Promise.all([...mounts.values()].map(m => m.ready()));
-    return;
-}
 /**
  * Reverse maps the paths in text from the mounted FileSystem to the global path
  * @internal @hidden

package/dist/emulation/streams.d.ts

@@ -2,13 +2,14 @@ import type * as Node from 'node:fs';
 import { Readable, Writable } from 'readable-stream';
 import type { Callback } from '../utils.js';
 export declare class ReadStream extends Readable implements Node.ReadStream {
-    close(callback?: Callback): void;
+    close(callback?: Callback<[void], null>): void;
+    wrap(oldStream: NodeJS.ReadableStream): this;
     bytesRead: number;
     path: string | Buffer;
     pending: boolean;
 }
 export declare class WriteStream extends Writable implements Node.WriteStream {
-    close(callback?: Callback): void;
+    close(callback?: Callback<[void], null>): void;
     bytesWritten: number;
     path: string | Buffer;
     pending: boolean;

package/dist/emulation/streams.js

@@ -5,19 +5,23 @@ export class ReadStream extends Readable {
         try {
             super.destroy();
             super.emit('close');
-            callback();
+            callback(null);
         }
         catch (err) {
             callback(new ErrnoError(Errno.EIO, err.toString()));
         }
     }
+    wrap(oldStream) {
+        super.wrap(oldStream);
+        return this;
+    }
 }
 export class WriteStream extends Writable {
     close(callback = () => null) {
         try {
             super.destroy();
             super.emit('close');
-            callback();
+            callback(null);
         }
         catch (err) {
             callback(new ErrnoError(Errno.EIO, err.toString()));

package/dist/emulation/sync.d.ts

@@ -3,8 +3,8 @@ import type * as fs from 'node:fs';
 import type { FileContents } from '../filesystem.js';
 import { BigIntStats, type Stats } from '../stats.js';
 import { Dir, Dirent } from './dir.js';
-import { type InternalOptions, type ReaddirOptions } from './shared.js';
 import type { V_Context } from '../context.js';
+import type { ReaddirOptsI, ReaddirOptsU, InternalOptions, ReaddirOptions, NullEnc } from './types.js';
 export declare function renameSync(this: V_Context, oldPath: fs.PathLike, newPath: fs.PathLike): void;
 /**
  * Test whether or not `path` exists by checking with the file system.
@@ -112,19 +112,19 @@ export declare function mkdirSync(this: V_Context, path: fs.PathLike, options?:
     recursive?: false;
 }) | null): void;
 export declare function mkdirSync(this: V_Context, path: fs.PathLike, options?: fs.Mode | fs.MakeDirectoryOptions | null): string | undefined;
-export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: (fs.ObjectEncodingOptions & ReaddirOptions & {
+export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: ReaddirOptsI<{
     withFileTypes?: false;
-}) | BufferEncoding | null): string[];
+}> | NullEnc): string[];
 export declare function readdirSync(this: V_Context, path: fs.PathLike, options: fs.BufferEncodingOption & ReaddirOptions & {
     withFileTypes?: false;
 }): Buffer[];
-export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: (fs.ObjectEncodingOptions & ReaddirOptions & {
+export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: ReaddirOptsI<{
     withFileTypes?: false;
-}) | BufferEncoding | null): string[] | Buffer[];
-export declare function readdirSync(this: V_Context, path: fs.PathLike, options: fs.ObjectEncodingOptions & ReaddirOptions & {
+}> | NullEnc): string[] | Buffer[];
+export declare function readdirSync(this: V_Context, path: fs.PathLike, options: ReaddirOptsI<{
     withFileTypes: true;
-}): Dirent[];
-export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: (ReaddirOptions & (fs.ObjectEncodingOptions | fs.BufferEncodingOption)) | BufferEncoding | null): string[] | Dirent[] | Buffer[];
+}>): Dirent[];
+export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: ReaddirOptsU<fs.BufferEncodingOption> | NullEnc): string[] | Dirent[] | Buffer[];
 export declare function linkSync(this: V_Context, targetPath: fs.PathLike, linkPath: fs.PathLike): void;
 /**
  * Synchronous `symlink`.
@@ -219,3 +219,10 @@ export declare function statfsSync(this: V_Context, path: fs.PathLike, options:
     bigint: true;
 }): fs.BigIntStatsFs;
 export declare function statfsSync(this: V_Context, path: fs.PathLike, options?: fs.StatFsOptions): fs.StatsFs | fs.BigIntStatsFs;
+/**
+ * Retrieves the files matching the specified pattern.
+ */
+export declare function globSync(pattern: string | string[]): string[];
+export declare function globSync(pattern: string | string[], options: fs.GlobOptionsWithFileTypes): Dirent[];
+export declare function globSync(pattern: string | string[], options: fs.GlobOptionsWithoutFileTypes): string[];
+export declare function globSync(pattern: string | string[], options: fs.GlobOptions): Dirent[] | string[];

package/dist/emulation/sync.js

@@ -796,3 +796,37 @@ export function statfsSync(path, options) {
     const { fs } = resolveMount(path, this);
     return _statfs(fs, options?.bigint);
 }
+export function globSync(pattern, options = {}) {
+    pattern = Array.isArray(pattern) ? pattern : [pattern];
+    const { cwd = '/', withFileTypes = false, exclude = () => false } = options;
+    // Escape special characters in pattern
+    const regexPatterns = pattern.map(p => {
+        p = p
+            .replace(/([.?+^$(){}|[\]/])/g, '\\$1')
+            .replace(/\*\*/g, '.*')
+            .replace(/\*/g, '[^/]*')
+            .replace(/\?/g, '.');
+        return new RegExp(`^${p}$`);
+    });
+    const results = [];
+    function recursiveList(dir) {
+        const entries = readdirSync(dir, { withFileTypes, encoding: 'utf8' });
+        for (const entry of entries) {
+            const fullPath = withFileTypes ? entry.path : dir + '/' + entry;
+            if (exclude((withFileTypes ? entry : fullPath)))
+                continue;
+            /**
+             * @todo it the pattern.source check correct?
+             */
+            if (statSync(fullPath).isDirectory() && regexPatterns.some(pattern => pattern.source.includes('.*'))) {
+                recursiveList(fullPath);
+            }
+            if (regexPatterns.some(pattern => pattern.test(fullPath.replace(/^\/+/g, '')))) {
+                results.push(withFileTypes ? entry.path : fullPath.replace(/^\/+/g, ''));
+            }
+        }
+    }
+    recursiveList(cwd);
+    return results;
+}
+globSync;

package/dist/index.d.ts

@@ -12,7 +12,6 @@ export * from './config.js';
 export * from './context.js';
 export * from './credentials.js';
 export * from './devices.js';
-export { default as devices } from './devices.js';
 export * from './file.js';
 export * from './filesystem.js';
 export * from './inode.js';

package/dist/index.js

@@ -12,7 +12,6 @@ export * from './config.js';
 export * from './context.js';
 export * from './credentials.js';
 export * from './devices.js';
-export { default as devices } from './devices.js';
 export * from './file.js';
 export * from './filesystem.js';
 export * from './inode.js';

package/dist/utils.d.ts

@@ -49,7 +49,7 @@ export declare function decodeDirListing(data: Uint8Array): Record<string, bigin
  * @hidden
  */
 export declare function encodeDirListing(data: Record<string, bigint>): Uint8Array;
-export type Callback<Args extends unknown[] = []> = (e?: ErrnoError, ...args: OptionalTuple<Args>) => unknown;
+export type Callback<Args extends unknown[] = [], NoError = undefined | void> = (e: ErrnoError | NoError, ...args: OptionalTuple<Args>) => unknown;
 /**
  * Normalizes a mode
  * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "1.5.0",
+	"version": "1.6.0",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -58,7 +58,8 @@
 		"build": "tsc -p tsconfig.json",
 		"build:docs": "typedoc",
 		"dev": "npm run build -- --watch",
-		"prepublishOnly": "npm run build"
+		"prepublishOnly": "npm run build",
+		"postinstall": "patch-package"
 	},
 	"lint-staged": {
 		"*": [
@@ -66,7 +67,7 @@
 		]
 	},
 	"dependencies": {
-		"@types/node": "^20.16.10",
+		"@types/node": "^22.10.1",
 		"@types/readable-stream": "^4.0.10",
 		"buffer": "^6.0.3",
 		"eventemitter3": "^5.0.1",
@@ -83,6 +84,7 @@
 		"eslint": "^9.15.0",
 		"globals": "^15.9.0",
 		"lint-staged": "^15.2.7",
+		"patch-package": "^8.0.0",
 		"prettier": "^3.2.5",
 		"tsx": "^4.19.1",
 		"typedoc": "^0.27.1",

package/readme.md

@@ -174,31 +174,31 @@ You can create your own devices by implementing a `DeviceDriver`. For example, t
 ```ts
 const customNullDevice = {
 	name: 'custom_null',
+	// only 1 can exist per DeviceFS
+	singleton: true,
+	// optional if false
 	isBuffered: false,
 	read() {
 		return 0;
 	},
-	write() {},
+	write() {
+		return 0;
+	},
 };
 ```
 
 Note the actual implementation's write is slightly more complicated since it adds to the file position. You can find more information on the docs.
 
-Finally, if you'd like to use your custom device with the file system, you can use so through the aptly named `DeviceFS`.
+Finally, if you'd like to use your custom device with the file system:
 
 ```ts
-const devfs = fs.mounts.get('/dev') as DeviceFS;
-devfs.createDevice('/custom', customNullDevice);
+import { addDevice, fs } from '@zenfs/core';
+
+addDevice(customNullDevice);
 
 fs.writeFileSync('/dev/custom', 'This gets discarded.');
 ```
 
-In the above example, `createDevice` works relative to the `DeviceFS` mount point.
-
-Additionally, a type assertion (` as ...`) is used since `fs.mounts` does not keep track of which file system type is mapped to which mount point. Doing so would create significant maintenance costs due to the complexity of implementing it.
-
-If you would like to see a more intuitive way adding custom devices (e.g. `fs.mknod`), please feel free to open an issue for a feature request.
-
 ## Using with bundlers
 
 ZenFS exports a drop-in for Node's `fs` module (up to the version of `@types/node` in package.json), so you can use it for your bundler of preference using the default export.

package/tests/fs/dir.test.ts

@@ -13,8 +13,6 @@ for (const file of testFiles) {
 	fs.writeFileSync(`${testDirPath}/${file}`, 'Sample content');
 }
 
-await fs._synced();
-
 suite('Dirent', () => {
 	test('name and parentPath getters', async () => {
 		const stats = await fs.promises.lstat(testFile);

package/tests/fs/directory.test.ts

@@ -18,8 +18,6 @@ for (const dir of testDirectories) {
 	}
 }
 
-await fs._synced();
-
 suite('Directories', () => {
 	test('mkdir', async () => {
 		await fs.promises.mkdir('/one', 0o755);

package/tests/fs/streams.test.ts

@@ -33,7 +33,7 @@ suite('ReadStream', () => {
 			closed = true;
 		});
 		readStream.close(err => {
-			assert.strictEqual(err, undefined);
+			assert.equal(err, null);
 			assert(closed);
 			done();
 		});
@@ -58,10 +58,10 @@ suite('ReadStream', () => {
 	test('ReadStream close method can be called multiple times', (_, done) => {
 		const readStream = new fs.ReadStream();
 		readStream.close(err => {
-			assert.strictEqual(err, undefined);
+			assert.equal(err, null);
 			// Call close again
 			readStream.close(err2 => {
-				assert.strictEqual(err2, undefined);
+				assert.equal(err2, null);
 				done();
 			});
 		});
@@ -94,7 +94,7 @@ suite('WriteStream', () => {
 			closed = true;
 		});
 		writeStream.close(err => {
-			assert.strictEqual(err, undefined);
+			assert.equal(err, null);
 			assert(closed);
 			done();
 		});
@@ -119,10 +119,10 @@ suite('WriteStream', () => {
 	test('WriteStream close method can be called multiple times', (_, done) => {
 		const writeStream = new fs.WriteStream();
 		writeStream.close(err => {
-			assert.strictEqual(err, undefined);
+			assert.equal(err, null);
 			// Call close again
 			writeStream.close(err2 => {
-				assert.strictEqual(err2, undefined);
+				assert.equal(err2, null);
 				done();
 			});
 		});