@zenfs/core 2.4.4 → 2.5.1

package/README.md

@@ -163,6 +163,19 @@ fs.umount('/mnt/zip'); // finished using the zip
 
 ZenFS includes support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. Check out the [Devices and Device Drivers](https://zenfs.dev/core/documents/Devices_and_Device_Drivers) documentation for more information.
 
+## `node:*` emulation
+
+ZenFS also includes emulation of some other `node:` modules for various reasons, importable from `@zenfs/core/<name>`:
+
+- `node:path`
+- `node:readline`
+
+For example:
+
+```ts
+import * as path from '@zenfs/core/path';
+```
+
 ## Bundling
 
 ZenFS exports a drop-in for Node's `fs` module, so you can use it for your bundler of preference using the default export.

package/dist/backends/backend.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
-/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-redundant-type-constituents */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents */
 import { withErrno } from 'kerium';
 import { debug, err } from 'kerium/log';
 /**

package/dist/backends/cow.d.ts

@@ -1,5 +1,6 @@
 import type { CreationOptions, StreamOptions, UsageInfo } from '../internal/filesystem.js';
 import type { InodeLike } from '../internal/inode.js';
+import type { Backend } from './backend.js';
 import { EventEmitter } from 'eventemitter3';
 import { type MountConfiguration } from '../config.js';
 import { FileSystem } from '../internal/filesystem.js';
@@ -9,18 +10,17 @@ import { FileSystem } from '../internal/filesystem.js';
  */
 export interface CopyOnWriteOptions {
     /** The file system that initially populates this file system. */
-    readable: MountConfiguration<any>;
+    readable: MountConfiguration<Backend>;
     /** The file system to write modified files to. */
-    writable: MountConfiguration<any>;
+    writable: MountConfiguration<Backend>;
     /** @see {@link Journal} */
     journal?: Journal;
 }
-declare const journalOperations: readonly ["delete"];
 /**
  * @category Internals
  * @internal
  */
-export type JournalOperation = (typeof journalOperations)[number];
+export type JournalOperation = 'delete';
 /**
  * @category Internals
  * @internal
@@ -61,6 +61,7 @@ export declare class CopyOnWriteFS extends FileSystem {
     /** The journal to use for persisting deletions */
     readonly journal: Journal;
     ready(): Promise<void>;
+    readySync(): void;
     constructor(
     /** The file system that initially populates this file system. */
     readable: FileSystem, 

package/dist/backends/cow.js

@@ -6,12 +6,12 @@ import { resolveMountConfig } from '../config.js';
 import { FileSystem } from '../internal/filesystem.js';
 import { isDirectory } from '../internal/inode.js';
 import { dirname, join } from '../path.js';
-const journalOperations = ['delete'];
+const journalOperations = new Set(['delete']);
 /** Because TS doesn't work right w/o it */
 function isJournalOp(op) {
-    return journalOperations.includes(op);
+    return journalOperations.has(op);
 }
-const maxOpLength = Math.max(...journalOperations.map(op => op.length));
+const maxOpLength = Math.max(...journalOperations.values().map(op => op.length));
 const journalMagicString = '#journal@v0\n';
 /**
  * Tracks various operations for the CoW backend
@@ -79,6 +79,10 @@ export class CopyOnWriteFS extends FileSystem {
         await this.readable.ready();
         await this.writable.ready();
     }
+    readySync() {
+        this.readable.readySync();
+        this.writable.readySync();
+    }
     constructor(
     /** The file system that initially populates this file system. */
     readable, 

package/dist/backends/passthrough.js

@@ -54,7 +54,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 import { err, warn } from 'kerium/log';
 import { FileSystem } from '../internal/filesystem.js';
 import { isDirectory } from '../internal/inode.js';
-import { resolve } from '../path.js';
 export class PassthroughFS extends FileSystem {
     nodeFS;
     prefix;
@@ -306,7 +305,7 @@ const _Passthrough = {
         prefix: { type: 'string', required: true },
     },
     create({ fs, prefix }) {
-        return new PassthroughFS(fs, resolve(prefix));
+        return new PassthroughFS(fs, prefix);
     },
 };
 /**

package/dist/backends/store/fs.d.ts

@@ -40,6 +40,7 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
     _move(from: string, to: string): void;
     protected _initialized: boolean;
     ready(): Promise<void>;
+    readySync(): void;
     constructor(store: T);
     /**
      * @experimental
@@ -107,6 +108,7 @@ export declare class StoreFS<T extends Store = Store> extends FileSystem {
      * Populates the `_ids` and `_paths` maps with all existing files stored in the underlying `Store`.
      */
     private _populate;
+    private _populateSync;
     /**
      * Find an inode without using the ID tables
      */

package/dist/backends/store/fs.js

@@ -144,6 +144,16 @@ export class StoreFS extends FileSystem {
         await this._populate();
         this._initialized = true;
     }
+    readySync() {
+        if (this._initialized)
+            return;
+        if (!this.attributes.has('no_async_preload')) {
+            this.checkRootSync();
+        }
+        this.checkRootSync();
+        this._populateSync();
+        this._initialized = true;
+    }
     constructor(store) {
         super(store.type ?? 0x6b766673, store.name);
         this.store = store;
@@ -781,6 +791,70 @@ export class StoreFS extends FileSystem {
                 await result_11;
         }
     }
+    _populateSync() {
+        const env_22 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (this._initialized) {
+                warn('Attempted to populate tables after initialization');
+                return;
+            }
+            debug('Populating tables with existing store metadata');
+            const tx = __addDisposableResource(env_22, this.transaction(), false);
+            const rootData = tx.getSync(rootIno);
+            if (!rootData) {
+                notice('Store does not have a root inode');
+                const inode = new Inode({ ino: rootIno, data: 1, mode: 0o777 | S_IFDIR });
+                tx.setSync(inode.data, encodeUTF8('{}'));
+                this._add(rootIno, '/');
+                tx.setSync(rootIno, inode);
+                tx.commitSync();
+                return;
+            }
+            if (rootData.length < sizeof(Inode)) {
+                crit('Store contains an invalid root inode. Refusing to populate tables');
+                return;
+            }
+            const visitedDirectories = new Set();
+            let i = 0;
+            const queue = [['/', rootIno]];
+            while (queue.length > 0) {
+                i++;
+                const [path, ino] = queue.shift();
+                this._add(ino, path);
+                const inodeData = tx.getSync(ino);
+                if (!inodeData) {
+                    warn('Store is missing data for inode: ' + ino);
+                    continue;
+                }
+                if (inodeData.length < sizeof(Inode)) {
+                    warn(`Invalid inode size for ino ${ino}: ${inodeData.length}`);
+                    continue;
+                }
+                const inode = new Inode(inodeData);
+                if ((inode.mode & S_IFDIR) != S_IFDIR || visitedDirectories.has(ino)) {
+                    continue;
+                }
+                visitedDirectories.add(ino);
+                const dirData = tx.getSync(inode.data);
+                if (!dirData) {
+                    warn('Store is missing directory data: ' + inode.data);
+                    continue;
+                }
+                const dirListing = decodeDirListing(dirData);
+                for (const [entryName, childIno] of Object.entries(dirListing)) {
+                    queue.push([join(path, entryName), childIno]);
+                }
+            }
+            debug(`Added ${i} existing inode(s) from store`);
+        }
+        catch (e_22) {
+            env_22.error = e_22;
+            env_22.hasError = true;
+        }
+        finally {
+            __disposeResources(env_22);
+        }
+    }
     /**
      * Find an inode without using the ID tables
      */
@@ -859,7 +933,7 @@ export class StoreFS extends FileSystem {
      * @param data The data to store at the file's data node.
      */
     async commitNew(path, options, data) {
-        const env_22 = { stack: [], error: void 0, hasError: false };
+        const env_23 = { stack: [], error: void 0, hasError: false };
         try {
             /*
                 The root always exists.
@@ -868,7 +942,7 @@ export class StoreFS extends FileSystem {
             */
             if (path == '/')
                 throw withErrno('EEXIST');
-            const tx = __addDisposableResource(env_22, this.transaction(), true);
+            const tx = __addDisposableResource(env_23, this.transaction(), true);
             const { dir: parentPath, base: fname } = parse(path);
             const parent = await this.findInode(tx, parentPath);
             const listing = decodeDirListing((await tx.get(parent.data)) ?? _throw(withErrno('ENOENT')));
@@ -892,12 +966,12 @@ export class StoreFS extends FileSystem {
             await tx.commit();
             return inode;
         }
-        catch (e_22) {
-            env_22.error = e_22;
-            env_22.hasError = true;
+        catch (e_23) {
+            env_23.error = e_23;
+            env_23.hasError = true;
         }
         finally {
-            const result_12 = __disposeResources(env_22);
+            const result_12 = __disposeResources(env_23);
             if (result_12)
                 await result_12;
         }
@@ -911,7 +985,7 @@ export class StoreFS extends FileSystem {
      * @return The Inode for the new file.
      */
     commitNewSync(path, options, data) {
-        const env_23 = { stack: [], error: void 0, hasError: false };
+        const env_24 = { stack: [], error: void 0, hasError: false };
         try {
             /*
                 The root always exists.
@@ -920,7 +994,7 @@ export class StoreFS extends FileSystem {
             */
             if (path == '/')
                 throw withErrno('EEXIST');
-            const tx = __addDisposableResource(env_23, this.transaction(), false);
+            const tx = __addDisposableResource(env_24, this.transaction(), false);
             const { dir: parentPath, base: fname } = parse(path);
             const parent = this.findInodeSync(tx, parentPath);
             const listing = decodeDirListing(tx.getSync(parent.data) ?? _throw(withErrno('ENOENT')));
@@ -942,12 +1016,12 @@ export class StoreFS extends FileSystem {
             tx.commitSync();
             return inode;
         }
-        catch (e_23) {
-            env_23.error = e_23;
-            env_23.hasError = true;
+        catch (e_24) {
+            env_24.error = e_24;
+            env_24.hasError = true;
         }
         finally {
-            __disposeResources(env_23);
+            __disposeResources(env_24);
         }
     }
     /**
@@ -956,9 +1030,9 @@ export class StoreFS extends FileSystem {
      * @param isDir Does the path belong to a directory, or a file?
      */
     async remove(path, isDir) {
-        const env_24 = { stack: [], error: void 0, hasError: false };
+        const env_25 = { stack: [], error: void 0, hasError: false };
         try {
-            const tx = __addDisposableResource(env_24, this.transaction(), true);
+            const tx = __addDisposableResource(env_25, this.transaction(), true);
             const { dir: parent, base: fileName } = parse(path), parentNode = await this.findInode(tx, parent), listing = decodeDirListing((await tx.get(parentNode.data)) ?? _throw(withErrno('ENOENT')));
             if (!listing[fileName])
                 throw withErrno('ENOENT');
@@ -979,12 +1053,12 @@ export class StoreFS extends FileSystem {
             }
             await tx.commit();
         }
-        catch (e_24) {
-            env_24.error = e_24;
-            env_24.hasError = true;
+        catch (e_25) {
+            env_25.error = e_25;
+            env_25.hasError = true;
         }
         finally {
-            const result_13 = __disposeResources(env_24);
+            const result_13 = __disposeResources(env_25);
             if (result_13)
                 await result_13;
         }
@@ -995,9 +1069,9 @@ export class StoreFS extends FileSystem {
      * @param isDir Does the path belong to a directory, or a file?
      */
     removeSync(path, isDir) {
-        const env_25 = { stack: [], error: void 0, hasError: false };
+        const env_26 = { stack: [], error: void 0, hasError: false };
         try {
-            const tx = __addDisposableResource(env_25, this.transaction(), false);
+            const tx = __addDisposableResource(env_26, this.transaction(), false);
             const { dir: parent, base: fileName } = parse(path), parentNode = this.findInodeSync(tx, parent), listing = decodeDirListing(tx.getSync(parentNode.data) ?? _throw(withErrno('ENOENT'))), ino = listing[fileName];
             if (!ino)
                 throw withErrno('ENOENT');
@@ -1017,12 +1091,12 @@ export class StoreFS extends FileSystem {
             }
             tx.commitSync();
         }
-        catch (e_25) {
-            env_25.error = e_25;
-            env_25.hasError = true;
+        catch (e_26) {
+            env_26.error = e_26;
+            env_26.hasError = true;
         }
         finally {
-            __disposeResources(env_25);
+            __disposeResources(env_26);
         }
     }
 }

package/dist/config.d.ts

@@ -18,6 +18,13 @@ export type MountConfiguration<T extends Backend> = FilesystemOf<T> | BackendCon
  * @see MountConfiguration
  */
 export declare function resolveMountConfig<T extends Backend>(configuration: MountConfiguration<T>, _depth?: number): Promise<FilesystemOf<T>>;
+/**
+ * @experimental
+ * Retrieve a file system with `configuration`.
+ * @category Backends and Configuration
+ * @see MountConfiguration
+ */
+export declare function resolveMountConfigSync<T extends Backend>(configuration: MountConfiguration<T>, _depth?: number): FilesystemOf<T>;
 /**
  * An object mapping mount points to backends
  * @category Backends and Configuration
@@ -82,6 +89,12 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
  * @category Backends and Configuration
  */
 export declare function configureSingle<T extends Backend>(configuration: MountConfiguration<T>): Promise<void>;
+/**
+ * @experimental
+ * Configures ZenFS with single mount point /
+ * @category Backends and Configuration
+ */
+export declare function configureSingleSync<T extends Backend>(configuration: MountConfiguration<T>): void;
 /**
  * @category Backends and Configuration
  */
@@ -92,4 +105,11 @@ export declare function addDevice(driver: DeviceDriver, options?: object): Devic
  * @see Configuration
  */
 export declare function configure<T extends ConfigMounts>(configuration: Partial<Configuration<T>>): Promise<void>;
+/**
+ * @experimental
+ * Configures ZenFS with `configuration`
+ * @category Backends and Configuration
+ * @see Configuration
+ */
+export declare function configureSync<T extends ConfigMounts>(configuration: Partial<Configuration<T>>): void;
 export declare function sync(): Promise<void>;

package/dist/config.js

@@ -5,6 +5,7 @@ import { createCredentials } from './internal/credentials.js';
 import { DeviceFS } from './internal/devices.js';
 import { FileSystem } from './internal/filesystem.js';
 import { exists, mkdir, stat } from './node/promises.js';
+import { existsSync, mkdirSync, statSync } from './node/sync.js';
 import { _setAccessChecks } from './vfs/config.js';
 import { mount, mounts, umount } from './vfs/shared.js';
 /**
@@ -20,6 +21,9 @@ export function configureFileSystem(fs, config) {
 function isMountConfig(arg) {
     return isBackendConfig(arg) || isBackend(arg) || arg instanceof FileSystem;
 }
+function isThenable(value) {
+    return typeof value?.then == 'function';
+}
 /**
  * Retrieve a file system with `configuration`.
  * @category Backends and Configuration
@@ -60,6 +64,57 @@ export async function resolveMountConfig(configuration, _depth = 0) {
     await mount.ready();
     return mount;
 }
+/**
+ * @experimental
+ * Retrieve a file system with `configuration`.
+ * @category Backends and Configuration
+ * @see MountConfiguration
+ */
+export function resolveMountConfigSync(configuration, _depth = 0) {
+    if (typeof configuration !== 'object' || configuration == null) {
+        throw log.err(withErrno('EINVAL', 'Invalid options on mount configuration'));
+    }
+    if (!isMountConfig(configuration)) {
+        throw log.err(withErrno('EINVAL', 'Invalid mount configuration'));
+    }
+    if (configuration instanceof FileSystem) {
+        configuration.readySync();
+        return configuration;
+    }
+    if (isBackend(configuration)) {
+        configuration = { backend: configuration };
+    }
+    for (const [key, value] of Object.entries(configuration)) {
+        if (key == 'backend')
+            continue;
+        if (!isMountConfig(value))
+            continue;
+        log.info('Resolving nested mount configuration: ' + key);
+        if (_depth > 10) {
+            throw log.err(withErrno('EINVAL', 'Invalid configuration, too deep and possibly infinite'));
+        }
+        configuration[key] = resolveMountConfigSync(value, ++_depth);
+    }
+    const { backend } = configuration;
+    if (typeof backend.isAvailable == 'function') {
+        const available = backend.isAvailable(configuration);
+        if (isThenable(available)) {
+            throw log.err(withErrno('EAGAIN', 'Backend availability check would block: ' + backend.name));
+        }
+        if (!available) {
+            throw log.err(withErrno('EPERM', 'Backend not available: ' + backend.name));
+        }
+    }
+    checkOptions(backend, configuration);
+    const mountFs = backend.create(configuration);
+    if (isThenable(mountFs)) {
+        throw log.err(withErrno('EAGAIN', 'Backend initialization would block: ' + backend.name));
+    }
+    const resolved = mountFs;
+    configureFileSystem(resolved, configuration);
+    resolved.readySync();
+    return resolved;
+}
 /**
  * Configures ZenFS with single mount point /
  * @category Backends and Configuration
@@ -72,6 +127,19 @@ export async function configureSingle(configuration) {
     umount('/');
     mount('/', resolved);
 }
+/**
+ * @experimental
+ * Configures ZenFS with single mount point /
+ * @category Backends and Configuration
+ */
+export function configureSingleSync(configuration) {
+    if (!isMountConfig(configuration)) {
+        throw new TypeError('Invalid single mount point configuration');
+    }
+    const resolved = resolveMountConfigSync(configuration);
+    umount('/');
+    mount('/', resolved);
+}
 /**
  * Like `fs.mount`, but it also creates missing directories.
  * @privateRemarks
@@ -92,6 +160,33 @@ async function mountWithMkdir(path, fs) {
     }
     mount(path, fs);
 }
+/**
+ * Like `fs.mount`, but it also creates missing directories.
+ * @privateRemarks
+ * This is implemented as a separate function to avoid a circular dependency between vfs/shared.ts and other vfs layer files.
+ * @internal
+ */
+function mountWithMkdirSync(path, fs) {
+    if (path == '/') {
+        mount(path, fs);
+        return;
+    }
+    let stats = null;
+    try {
+        stats = statSync(path);
+    }
+    catch (error) {
+        if (error?.code != 'ENOENT')
+            throw error;
+    }
+    if (!stats) {
+        mkdirSync(path, { recursive: true });
+    }
+    else if (!stats.isDirectory()) {
+        throw withErrno('ENOTDIR', 'Missing directory at mount point: ' + path);
+    }
+    mount(path, fs);
+}
 /**
  * @category Backends and Configuration
  */
@@ -149,6 +244,53 @@ export async function configure(configuration) {
         }
     }
 }
+/**
+ * @experimental
+ * Configures ZenFS with `configuration`
+ * @category Backends and Configuration
+ * @see Configuration
+ */
+export function configureSync(configuration) {
+    Object.assign(defaultContext.credentials, createCredentials({
+        uid: configuration.uid || 0,
+        gid: configuration.gid || 0,
+    }));
+    _setAccessChecks(!configuration.disableAccessChecks);
+    if (configuration.log)
+        log.configure(configuration.log);
+    if (configuration.mounts) {
+        for (const [_point, mountConfig] of Object.entries(configuration.mounts).sort(([a], [b]) => (a.length > b.length ? 1 : -1))) {
+            const point = _point.startsWith('/') ? _point : '/' + _point;
+            if (isBackendConfig(mountConfig)) {
+                mountConfig.disableAsyncCache ??= configuration.disableAsyncCache || false;
+                mountConfig.caseFold ??= configuration.caseFold;
+            }
+            if (point == '/')
+                umount('/');
+            mountWithMkdirSync(point, resolveMountConfigSync(mountConfig));
+        }
+    }
+    for (const fs of mounts.values()) {
+        configureFileSystem(fs, configuration);
+    }
+    if (configuration.addDevices && !mounts.has('/dev')) {
+        const devfs = new DeviceFS();
+        devfs.addDefaults();
+        devfs.readySync();
+        mountWithMkdirSync('/dev', devfs);
+    }
+    if (configuration.defaultDirectories) {
+        for (const dir of _defaultDirectories) {
+            if (existsSync(dir)) {
+                const stats = statSync(dir);
+                if (!stats.isDirectory())
+                    log.warn('Default directory exists but is not a directory: ' + dir);
+                continue;
+            }
+            mkdirSync(dir);
+        }
+    }
+}
 export async function sync() {
     for (const fs of mounts.values())
         await fs.sync();

package/dist/internal/filesystem.d.ts

@@ -171,6 +171,7 @@ export declare abstract class FileSystem {
      */
     usage(): UsageInfo;
     ready(): Promise<void>;
+    readySync(): void;
     abstract rename(oldPath: string, newPath: string): Promise<void>;
     abstract renameSync(oldPath: string, newPath: string): void;
     abstract stat(path: string): Promise<InodeLike>;

package/dist/internal/filesystem.js

@@ -1,3 +1,4 @@
+import { withErrno } from 'kerium';
 const _chunkSize = 0x1000;
 /**
  * Provides a consistent and easy to use internal API.
@@ -61,6 +62,10 @@ export class FileSystem {
         };
     }
     async ready() { }
+    readySync() {
+        if (this.ready !== FileSystem.prototype.ready)
+            throw withErrno('EAGAIN');
+    }
     /**
      * Test whether or not `path` exists.
      */

package/dist/internal/rpc.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
 import { Errno, Exception, withErrno } from 'kerium';
 import { err, info, warn } from 'kerium/log';
 import { isJSON, pick } from 'utilium';

package/dist/mixins/async.js

@@ -30,7 +30,6 @@ export function Async(FS) {
         }
         _promise = Promise.resolve();
         _async(thunk) {
-            // eslint-disable-next-line @typescript-eslint/no-misused-promises
             this._promise = this._promise.finally(() => thunk());
         }
         _isInitialized = false;

package/dist/mixins/mutexed.d.ts

@@ -35,6 +35,7 @@ export declare class _MutexedFS<T extends FileSystem> implements FileSystem {
     set _uuid(value: UUID);
     get uuid(): UUID;
     ready(): Promise<void>;
+    readySync(): void;
     usage(): UsageInfo;
     /**
      * The current locks

package/dist/mixins/mutexed.js

@@ -115,6 +115,9 @@ export class _MutexedFS {
     async ready() {
         return await this._fs.ready();
     }
+    readySync() {
+        return this._fs.readySync();
+    }
     usage() {
         return this._fs.usage();
     }

package/dist/mixins/shared.js

@@ -1,8 +1,4 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/*
-    Code shared by various mixins
-*/
 export const _asyncFSKeys = [
     'rename',
     'stat',

package/dist/node/promises.d.ts

@@ -72,11 +72,11 @@ export declare class FileHandle implements promises.FileHandle {
     read<T extends NodeJS.ArrayBufferView = Buffer>(options?: promises.FileReadOptions<T>): Promise<promises.FileReadResult<T>>;
     readFile(options?: ({
         encoding?: null;
-    } & Abortable) | null): Promise<Buffer>;
+    } & Abortable) | null): Promise<NonSharedBuffer>;
     readFile(options: ({
         encoding: BufferEncoding;
     } & Abortable) | BufferEncoding): Promise<string>;
-    readFile(_options?: (fs.ObjectEncodingOptions & Abortable) | BufferEncoding | null): Promise<string | Buffer>;
+    readFile(_options?: (fs.ObjectEncodingOptions & Abortable) | BufferEncoding | null): Promise<string | NonSharedBuffer>;
     /**
      * Read file data using a `ReadableStream`.
      * The handle will not be closed automatically.
@@ -139,14 +139,14 @@ export declare class FileHandle implements promises.FileHandle {
      * @param position The position in the file where to begin writing.
      * @returns The number of bytes written.
      */
-    writev(buffers: Uint8Array[], position?: number): Promise<fs.WriteVResult>;
+    writev<TBuffers extends readonly NodeJS.ArrayBufferView[]>(buffers: TBuffers, position?: number): Promise<fs.WriteVResult<TBuffers>>;
     /**
      * Asynchronous `readv`. Reads into multiple buffers.
      * @param buffers An array of Uint8Array buffers.
      * @param position The position in the file where to begin reading.
      * @returns The number of bytes read.
      */
-    readv(buffers: NodeJS.ArrayBufferView[], position?: number): Promise<fs.ReadVResult>;
+    readv<TBuffers extends readonly NodeJS.ArrayBufferView[]>(buffers: TBuffers, position?: number): Promise<fs.ReadVResult<TBuffers>>;
     /**
      * Creates a stream for reading from the file.
      * @param options Options for the readable stream
@@ -197,14 +197,14 @@ export declare function open(this: V_Context, path: fs.PathLike, flag?: fs.OpenM
 export declare function readFile(this: V_Context, path: fs.PathLike | promises.FileHandle, options?: ({
     encoding?: null;
     flag?: fs.OpenMode;
-} & Abortable) | null): Promise<Buffer>;
+} & Abortable) | null): Promise<NonSharedBuffer>;
 export declare function readFile(this: V_Context, path: fs.PathLike | promises.FileHandle, options: ({
     encoding: BufferEncoding;
     flag?: fs.OpenMode;
 } & Abortable) | BufferEncoding): Promise<string>;
 export declare function readFile(this: V_Context, path: fs.PathLike | promises.FileHandle, _options?: (fs.ObjectEncodingOptions & Abortable & {
     flag?: fs.OpenMode;
-}) | BufferEncoding | null): Promise<string | Buffer>;
+}) | BufferEncoding | null): Promise<string | NonSharedBuffer>;
 /**
  * Asynchronously writes data to a file, replacing the file if it already exists.
  *
@@ -257,11 +257,11 @@ export declare function readdir(this: V_Context, path: fs.PathLike, options: {
     encoding: 'buffer';
     withFileTypes?: false;
     recursive?: boolean;
-} | 'buffer'): Promise<Buffer[]>;
+} | 'buffer'): Promise<NonSharedBuffer[]>;
 export declare function readdir(this: V_Context, path: fs.PathLike, options?: (fs.ObjectEncodingOptions & {
     withFileTypes?: false;
     recursive?: boolean;
-}) | BufferEncoding | null): Promise<string[] | Buffer[]>;
+}) | BufferEncoding | null): Promise<string[] | NonSharedBuffer[]>;
 export declare function readdir(this: V_Context, path: fs.PathLike, options: fs.ObjectEncodingOptions & {
     withFileTypes: true;
     recursive?: boolean;
@@ -270,7 +270,7 @@ export declare function readdir(this: V_Context, path: fs.PathLike, options: {
     encoding: 'buffer';
     withFileTypes: true;
     recursive?: boolean;
-}): Promise<Dirent<Buffer>[]>;
+}): Promise<Dirent<NonSharedBuffer>[]>;
 export declare function readdir(this: V_Context, path: fs.PathLike, options?: NodeReaddirOptions): Promise<string[] | Dirent<any>[] | Buffer[]>;
 export declare function link(this: V_Context, path: fs.PathLike, dest: fs.PathLike): Promise<void>;
 /**
@@ -280,9 +280,9 @@ export declare function link(this: V_Context, path: fs.PathLike, dest: fs.PathLi
  * @param type can be either `'dir'` or `'file'` (default is `'file'`)
  */
 export declare function symlink(this: V_Context, dest: fs.PathLike, path: fs.PathLike, type?: fs.symlink.Type | string | null): Promise<void>;
-export declare function readlink(this: V_Context, path: fs.PathLike, options: fs.BufferEncodingOption): Promise<Buffer>;
+export declare function readlink(this: V_Context, path: fs.PathLike, options: fs.BufferEncodingOption): Promise<NonSharedBuffer>;
 export declare function readlink(this: V_Context, path: fs.PathLike, options?: fs.EncodingOption | null): Promise<string>;
-export declare function readlink(this: V_Context, path: fs.PathLike, options?: fs.BufferEncodingOption | fs.EncodingOption | string | null): Promise<string | Buffer>;
+export declare function readlink(this: V_Context, path: fs.PathLike, options?: fs.BufferEncodingOption | fs.EncodingOption | string | null): Promise<string | NonSharedBuffer>;
 export declare function chown(this: V_Context, path: fs.PathLike, uid: number, gid: number): Promise<void>;
 export declare function lchown(this: V_Context, path: fs.PathLike, uid: number, gid: number): Promise<void>;
 export declare function chmod(this: V_Context, path: fs.PathLike, mode: fs.Mode): Promise<void>;
@@ -301,11 +301,11 @@ export declare function lutimes(this: V_Context, path: fs.PathLike, atime: fs.Ti
  * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. Defaults to `'utf8'`.
  * @todo handle options
  */
-export declare function realpath(this: V_Context, path: fs.PathLike, options: fs.BufferEncodingOption): Promise<Buffer>;
+export declare function realpath(this: V_Context, path: fs.PathLike, options: fs.BufferEncodingOption): Promise<NonSharedBuffer>;
 export declare function realpath(this: V_Context, path: fs.PathLike, options?: fs.EncodingOption | BufferEncoding): Promise<string>;
 export declare function watch(this: V_Context, filename: fs.PathLike, options?: fs.WatchOptions | BufferEncoding): AsyncIteratorObject<promises.FileChangeInfo<string>, undefined>;
-export declare function watch(this: V_Context, filename: fs.PathLike, options: fs.WatchOptions | fs.BufferEncodingOption): AsyncIteratorObject<promises.FileChangeInfo<Buffer>, undefined>;
-export declare function watch(this: V_Context, filename: fs.PathLike, options?: fs.WatchOptions | string): AsyncIteratorObject<promises.FileChangeInfo<string>, undefined> | AsyncIteratorObject<promises.FileChangeInfo<Buffer>, undefined>;
+export declare function watch(this: V_Context, filename: fs.PathLike, options: fs.WatchOptions | fs.BufferEncodingOption): AsyncIteratorObject<promises.FileChangeInfo<NonSharedBuffer>, undefined>;
+export declare function watch(this: V_Context, filename: fs.PathLike, options?: fs.WatchOptions | string): AsyncIteratorObject<promises.FileChangeInfo<string>, undefined> | AsyncIteratorObject<promises.FileChangeInfo<NonSharedBuffer>, undefined>;
 export declare function access(this: V_Context, path: fs.PathLike, mode?: number): Promise<void>;
 /**
  * Asynchronous `rm`. Removes files or directories (recursively).
@@ -319,7 +319,7 @@ export declare function rm(this: V_Context, path: fs.PathLike, options?: fs.RmOp
  * @returns The path to the created temporary directory, encoded as a string or buffer.
  */
 export declare function mkdtemp(this: V_Context, prefix: string, options?: fs.EncodingOption): Promise<string>;
-export declare function mkdtemp(this: V_Context, prefix: string, options?: fs.BufferEncodingOption): Promise<Buffer>;
+export declare function mkdtemp(this: V_Context, prefix: string, options?: fs.BufferEncodingOption): Promise<NonSharedBuffer>;
 /**
  * The resulting Promise holds an async-disposable object whose `path` property holds the created directory path.
  * When the object is disposed, the directory and its contents will be removed asynchronously if it still exists.

package/dist/node/readline.js

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
-/* eslint-disable @typescript-eslint/no-explicit-any */
 // A cross-platform node:readline implementation
 import { EventEmitter } from 'eventemitter3';
 import { warn } from 'kerium/log';

package/dist/node/sync.d.ts

@@ -122,11 +122,11 @@ export declare function readdirSync(this: V_Context, path: fs.PathLike, options:
     encoding: 'buffer';
     withFileTypes?: false;
     recursive?: boolean;
-} | 'buffer'): Buffer[];
+} | 'buffer'): NonSharedBuffer[];
 export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: (fs.ObjectEncodingOptions & {
     withFileTypes?: false;
     recursive?: boolean;
-}) | BufferEncoding | null): string[] | Buffer[];
+}) | BufferEncoding | null): string[] | NonSharedBuffer[];
 export declare function readdirSync(this: V_Context, path: fs.PathLike, options: fs.ObjectEncodingOptions & {
     withFileTypes: true;
     recursive?: boolean;
@@ -135,7 +135,7 @@ export declare function readdirSync(this: V_Context, path: fs.PathLike, options:
     encoding: 'buffer';
     withFileTypes: true;
     recursive?: boolean;
-}): Dirent<Buffer>[];
+}): Dirent<NonSharedBuffer>[];
 export declare function readdirSync(this: V_Context, path: fs.PathLike, options?: NodeReaddirOptions): string[] | Dirent<any>[] | Buffer[];
 export declare function linkSync(this: V_Context, targetPath: fs.PathLike, linkPath: fs.PathLike): void;
 /**
@@ -145,9 +145,9 @@ export declare function linkSync(this: V_Context, targetPath: fs.PathLike, linkP
  * @param type can be either `'dir'` or `'file'` (default is `'file'`)
  */
 export declare function symlinkSync(this: V_Context, target: fs.PathLike, path: fs.PathLike, type?: fs.symlink.Type | null): void;
-export declare function readlinkSync(this: V_Context, path: fs.PathLike, options?: fs.BufferEncodingOption): Buffer;
+export declare function readlinkSync(this: V_Context, path: fs.PathLike, options?: fs.BufferEncodingOption): NonSharedBuffer;
 export declare function readlinkSync(this: V_Context, path: fs.PathLike, options: fs.EncodingOption | BufferEncoding): string;
-export declare function readlinkSync(this: V_Context, path: fs.PathLike, options?: fs.EncodingOption | BufferEncoding | fs.BufferEncodingOption): Buffer | string;
+export declare function readlinkSync(this: V_Context, path: fs.PathLike, options?: fs.EncodingOption | BufferEncoding | fs.BufferEncodingOption): NonSharedBuffer | string;
 export declare function chownSync(this: V_Context, path: fs.PathLike, uid: number, gid: number): void;
 export declare function lchownSync(this: V_Context, path: fs.PathLike, uid: number, gid: number): void;
 export declare function chmodSync(this: V_Context, path: fs.PathLike, mode: fs.Mode): void;
@@ -174,7 +174,7 @@ export declare function rmSync(this: V_Context, path: fs.PathLike, options?: fs.
  * @param options The encoding (or an object including `encoding`).
  * @returns The path to the created temporary directory, encoded as a string or buffer.
  */
-export declare function mkdtempSync(this: V_Context, prefix: fs.PathLike, options: fs.BufferEncodingOption): Buffer;
+export declare function mkdtempSync(this: V_Context, prefix: fs.PathLike, options: fs.BufferEncodingOption): NonSharedBuffer;
 export declare function mkdtempSync(this: V_Context, prefix: fs.PathLike, options?: fs.EncodingOption): string;
 /**
  * Returns a disposable object whose `path` property holds the created directory path.

package/dist/polyfills.js

@@ -5,9 +5,7 @@ import { warn } from 'kerium/log';
 Promise.withResolvers ??=
     (warn('Using a polyfill of Promise.withResolvers'),
         function () {
-            let _resolve, 
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            _reject;
+            let _resolve, _reject;
             const promise = new Promise((resolve, reject) => {
                 _resolve = resolve;
                 _reject = reject;

package/dist/vfs/watchers.js

@@ -14,14 +14,12 @@ import { normalizePath } from '../utils.js';
 class Watcher extends EventEmitter {
     _context;
     path;
-    /* eslint-disable @typescript-eslint/no-explicit-any */
     off(event, fn, context, once) {
         return super.off(event, fn, context, once);
     }
     removeListener(event, fn, context, once) {
         return super.removeListener(event, fn, context, once);
     }
-    /* eslint-enable @typescript-eslint/no-explicit-any */
     constructor(
     /**
      * @internal

package/eslint.shared.js

@@ -1,12 +1,12 @@
 /* Shared eslint rules */
 import eslint from '@eslint/js';
 import globals from 'globals';
-import tseslint from 'typescript-eslint';
+import { configs } from 'typescript-eslint';
 
 export default [
 	{
 		name: 'ZenFS',
-		extends: [eslint.configs.recommended, ...tseslint.configs.recommendedTypeChecked],
+		extends: [eslint.configs.recommended, ...configs.recommendedTypeChecked],
 		files: ['src/**/*.ts', 'tests/**/*.ts'],
 		languageOptions: {
 			globals: { ...globals.browser, ...globals.node },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.4.4",
+	"version": "2.5.1",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -71,7 +71,7 @@
 		"prepublishOnly": "npm run build"
 	},
 	"dependencies": {
-		"@types/node": "^24.1.0",
+		"@types/node": "^25.2.0",
 		"buffer": "^6.0.3",
 		"eventemitter3": "^5.0.1",
 		"kerium": "^1.3.4",
@@ -80,12 +80,10 @@
 		"utilium": "^2.5.0"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.8.0",
-		"@octokit/action": "^7.0.0",
-		"@types/eslint__js": "^8.42.3",
-		"c8": "^10.1.2",
+		"@octokit/action": "^8.0.4",
+		"c8": "^10.1.3",
 		"eslint": "^9.15.0",
-		"globals": "^16.0.0",
+		"globals": "^17.3.0",
 		"prettier": "^3.2.5",
 		"tsx": "^4.19.1",
 		"typedoc": "^0.28.0",

package/scripts/test.js

@@ -87,9 +87,19 @@ if (options.clean) {
 	process.exit();
 }
 
+function report() {
+	try {
+		execSync('npx c8 report --reporter=text', { stdio: 'inherit' });
+	} catch (e) {
+		console.error('Failed to generate coverage report!');
+		console.error(e);
+	} finally {
+		rmSync(options.coverage, { recursive: true });
+	}
+}
+
 if (options.report) {
-	execSync('npx c8 report --reporter=text', { stdio: 'inherit' });
-	rmSync(options.coverage, { recursive: true, force: true });
+	report();
 	process.exit();
 }
 
@@ -237,7 +247,4 @@ for (const setupFile of positionals) {
 	}
 }
 
-if (!options.preserve) {
-	execSync('npx c8 report --reporter=text', { stdio: 'inherit' });
-	rmSync(options.coverage, { recursive: true });
-}
+if (!options.preserve) report();

package/tests/backend/single-buffer.test.ts

@@ -64,7 +64,7 @@ await suite('SingleBuffer', () => {
 		const growthSizes = [0, 1, 17, 512, 8192, 65535, 262144, 524288];
 		const shrinkSizes = [262144, 4096, 128, 0];
 
-		const verifySnapshot = async (expected: Buffer, size: number) => {
+		const verifySnapshot = (expected: Buffer, size: number) => {
 			mount(verifyMountPoint, writable);
 			try {
 				const reopened = fs.readFileSync(`${verifyMountPoint}/payload.bin`);
@@ -82,7 +82,7 @@ await suite('SingleBuffer', () => {
 				const direct = fs.readFileSync(filePath);
 				assert.strictEqual(direct.byteLength, size, `direct size mismatch for ${size} bytes`);
 				assert.deepStrictEqual(direct, payload, `direct content mismatch for ${size} bytes`);
-				await verifySnapshot(direct, size);
+				verifySnapshot(direct, size);
 			}
 
 			for (const size of shrinkSizes) {
@@ -91,7 +91,7 @@ await suite('SingleBuffer', () => {
 				const direct = fs.readFileSync(filePath);
 				assert.strictEqual(direct.byteLength, size, `direct size mismatch after shrink to ${size} bytes`);
 				assert.deepStrictEqual(direct, payload, `direct content mismatch after shrink to ${size} bytes`);
-				await verifySnapshot(direct, size);
+				verifySnapshot(direct, size);
 			}
 		} finally {
 			if (fs.existsSync(filePath)) fs.unlinkSync(filePath);

package/tests/common/config.test.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { configureSingleSync, configureSync, fs, InMemory, mounts, SingleBuffer, type Backend } from '@zenfs/core';
+import { Errno } from 'kerium';
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+
+const AsyncBackend = {
+	name: 'AsyncBackend',
+	options: {},
+	async create() {
+		await Promise.resolve();
+		return InMemory.create({ label: 'async-backend' });
+	},
+} satisfies Backend;
+
+suite('Sync configuration', () => {
+	test('configureSingleSync mounts root synchronously', () => {
+		configureSingleSync({ backend: InMemory, label: 'sync-root' });
+		assert.equal(mounts.get('/')?.label, 'sync-root');
+
+		fs.writeFileSync('/sync-file', 'sync');
+		assert.equal(fs.readFileSync('/sync-file', 'utf8'), 'sync');
+	});
+
+	test('configureSync mounts additional directories', () => {
+		configureSync({
+			mounts: {
+				tmp: { backend: InMemory, label: 'sync-tmp' },
+			},
+		});
+
+		assert.ok(mounts.has('/tmp'));
+		fs.writeFileSync('/tmp/sync.txt', 'ok');
+		assert.equal(fs.readFileSync('/tmp/sync.txt', 'utf8'), 'ok');
+
+		fs.umount('/tmp');
+		fs.rmSync('/tmp', { recursive: true, force: true });
+	});
+
+	test('configureSync rejects asynchronous backends', () => {
+		assert.throws(
+			() =>
+				configureSync({
+					mounts: { '/': { backend: AsyncBackend } },
+				}),
+			{ errno: Errno.EAGAIN }
+		);
+	});
+
+	test('configureSingleSync works with SingleBuffer', () => {
+		const buffer = new ArrayBuffer(0x20000);
+		configureSingleSync({ backend: SingleBuffer, buffer });
+
+		fs.writeFileSync('/sb.txt', 'single-buffer');
+		assert.equal(fs.readFileSync('/sb.txt', 'utf8'), 'single-buffer');
+	});
+});