@zenfs/core 2.5.8 → 2.6.0

package/dist/vfs/vcache.js

@@ -0,0 +1,249 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { VNode } from './vnode.js';
+/**
+ * The VFS-level cache of vnodes for a single file system. Modeled after Linux's dcache/icache.
+ *
+ * Vnodes are keyed by inode number, so hard links share a vnode.
+ * A vnode stays cached while it is referenced or dirty, and is evicted otherwise.
+ * @category VFS
+ * @todo Add LRU or something to limit memory usage
+ */
+export class VCache {
+    fs;
+    byIno = new Map();
+    byPath = new Map();
+    constructor(fs) {
+        this.fs = fs;
+    }
+    /** Get the vnode for a path, if one is cached. Note paths are relative to the FS root, not the VFS root */
+    get(path) {
+        return this.byPath.get(path);
+    }
+    /**
+     * Get or create the vnode for `path`, incrementing its reference count.
+     * Callers must `unref` the vnode when done with it.
+     */
+    ref(path, inode) {
+        let node = this.byIno.get(inode.ino);
+        if (!node) {
+            node = new VNode(this.fs, path, inode);
+            this.byIno.set(inode.ino, node);
+        }
+        else {
+            node.paths.add(path);
+            // The vnode's inode is authoritative when dirty; otherwise refresh it with the newer stats
+            if (!node.dirty && inode !== node.inode)
+                Object.assign(node.inode, inode);
+        }
+        this.byPath.set(path, node);
+        node.refs++;
+        return node;
+    }
+    /** Release a reference to a vnode, evicting it if it is unreferenced and clean */
+    unref(node) {
+        node.refs--;
+        if (node.refs > 0 || node.dirty)
+            return;
+        this.evict(node);
+    }
+    evict(node) {
+        this.byIno.delete(node.ino);
+        for (const path of node.paths)
+            this.byPath.delete(path);
+    }
+    /** Update cached paths for a rename. Handles directories, whose descendants' paths change too */
+    rename(oldPath, newPath) {
+        for (const [path, node] of this.byPath) {
+            if (path != oldPath && !path.startsWith(oldPath + '/'))
+                continue;
+            const moved = newPath + path.slice(oldPath.length);
+            this.byPath.delete(path);
+            this.byPath.set(moved, node);
+            node.paths.delete(path);
+            node.paths.add(moved);
+        }
+    }
+    /** Add a path for a newly created hard link, if the target is cached */
+    link(targetPath, linkPath) {
+        const node = this.byPath.get(targetPath);
+        if (!node)
+            return;
+        node.paths.add(linkPath);
+        this.byPath.set(linkPath, node);
+    }
+    /** Remove a path for an unlink/rmdir. The vnode is kept if other paths (hard links) refer to it */
+    remove(path) {
+        const node = this.byPath.get(path);
+        if (!node)
+            return;
+        this.byPath.delete(path);
+        node.paths.delete(path);
+        if (!node.paths.size && !node.refs)
+            this.evict(node);
+    }
+    /** Sync all dirty vnodes to the backend */
+    async sync() {
+        for (const node of this.byIno.values()) {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                if (!node.dirty)
+                    continue;
+                const _ = __addDisposableResource(env_1, await node.lock('ro'), false);
+                await node.sync();
+                if (!node.refs)
+                    this.evict(node);
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+    }
+    /** Sync all dirty vnodes to the backend synchronously */
+    syncSync() {
+        for (const node of this.byIno.values()) {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                if (!node.dirty)
+                    continue;
+                const _ = __addDisposableResource(env_2, node.lockSync('ro'), false);
+                node.syncSync();
+                if (!node.refs)
+                    this.evict(node);
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
+            }
+        }
+    }
+}
+/**
+ * All vnode caches, keyed by file system UUID.
+ * Keyed by UUID rather than the `FileSystem` object because `resolveMount`
+ * wraps file systems in a new exception-context proxy on every call.
+ * @category VFS
+ * @internal
+ */
+export const caches = new Map();
+/**
+ * Get the vnode cache for a file system, creating it if needed.
+ * @category VFS
+ * @internal
+ */
+export function cacheOf(fs) {
+    let cache = caches.get(fs.uuid);
+    if (!cache) {
+        cache = new VCache(fs);
+        caches.set(fs.uuid, cache);
+    }
+    return cache;
+}
+/**
+ * Ref and lock the vnode for a path, usually a parent directory during a namespace operation.
+ * The returned release function unlocks and unrefs the vnode.
+ * If `inode` is not provided and the vnode is not cached, the backend is `stat`ed.
+ * @category VFS
+ * @internal
+ */
+export async function lockPath(fs, path, mode, inode) {
+    const cache = cacheOf(fs);
+    inode ??= cache.get(path)?.inode ?? (await fs.stat(path));
+    const node = cache.ref(path, inode);
+    const unlock = await node.lock(mode);
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        unlock();
+        cache.unref(node);
+    };
+    release[Symbol.dispose] = release;
+    return release;
+}
+/**
+ * Synchronous version of `lockPath`.
+ * @category VFS
+ * @internal
+ */
+export function lockPathSync(fs, path, mode, inode) {
+    const cache = cacheOf(fs);
+    inode ??= cache.get(path)?.inode ?? fs.statSync(path);
+    const node = cache.ref(path, inode);
+    let unlock;
+    try {
+        unlock = node.lockSync(mode);
+    }
+    catch (e) {
+        cache.unref(node);
+        throw e;
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        unlock();
+        cache.unref(node);
+    };
+    release[Symbol.dispose] = release;
+    return release;
+}

package/dist/vfs/vnode.d.ts

@@ -0,0 +1,66 @@
+import { RwLockable } from 'kerium/locks';
+import { Resource, type Range } from 'utilium/cache';
+import type { FileSystem } from '../internal/filesystem.js';
+import { type InodeLike } from '../internal/inode.js';
+/**
+ * A VFS-level node, roughly equivalent to Linux's in-memory `struct inode`.
+ *
+ * A `VNode` is the single authoritative copy of an inode's metadata and cached data at the VFS level.
+ * All open `Handle`s for the same file share one `VNode`, so metadata changes are immediately visible across handles.
+ * File data written through a `VNode` is cached and only written to the backend when the vnode is synced.
+ *
+ * `VNode` methods do *not* acquire the vnode's lock. Callers are responsible for locking, since operations usually span multiple vnode calls.
+ * @category VFS
+ */
+export declare class VNode extends RwLockable {
+    readonly fs: FileSystem;
+    readonly inode: InodeLike;
+    /** Cached file data. This is a page cache, but with byte granularity */
+    readonly data: Resource<number>;
+    /** Ranges of `data` that have been written but not yet synced to the backend */
+    protected dirtyRanges: Range[];
+    /** Whether `inode` has changes that have not been synced to the backend */
+    metadataDirty: boolean;
+    /** The number of active references: open handles and in-progress VFS operations */
+    refs: number;
+    /** Paths on `fs` that refer to this vnode. Multiple paths refer to the same vnode with hard links */
+    readonly paths: Set<string>;
+    /** Fallback for when the last path is removed (i.e. the file is unlinked while open) */
+    protected _lastPath: string;
+    constructor(fs: FileSystem, path: string, inode: InodeLike);
+    get ino(): number;
+    /** A path that can be used to address the backend */
+    get path(): string;
+    /** Whether this vnode has data or metadata that has not been synced to the backend */
+    get dirty(): boolean;
+    /** Character and block devices bypass the data cache */
+    protected get bypassCache(): boolean;
+    /** Add a range to `dirtyRanges`, merging overlapping and adjacent ranges */
+    protected markDirty(start: number, end: number): void;
+    /**
+     * Copy `[start, end)` from the cache into `buffer`.
+     * Uncached spans are holes (e.g. from an extending truncate) and are zero-filled.
+     */
+    protected copyFromCache(buffer: Uint8Array, start: number, end: number): void;
+    /**
+     * Read `[start, end)` into `buffer`, fetching any missing ranges from the backend.
+     */
+    read(buffer: Uint8Array, start: number, end: number): Promise<void>;
+    readSync(buffer: Uint8Array, start: number, end: number): void;
+    /**
+     * Write `data` at `offset` into the cache and update metadata.
+     * The backend is not written to until `sync`, except for devices, which bypass the cache.
+     */
+    write(data: Uint8Array, offset: number): Promise<void>;
+    writeSync(data: Uint8Array, offset: number): void;
+    protected _writeCached(data: Uint8Array, offset: number): void;
+    protected _writeMetadata(end: number): void;
+    /**
+     * Change the size of the file.
+     * Note an extending truncate creates a hole, which reads as zeroes.
+     */
+    truncate(length: number): void;
+    /** Write all unsynced data to the backend, then metadata */
+    sync(): Promise<void>;
+    syncSync(): void;
+}

package/dist/vfs/vnode.js

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { RwLockable } from 'kerium/locks';
+import { Resource } from 'utilium/cache';
+import { InodeFlags, isBlockDevice, isCharacterDevice } from '../internal/inode.js';
+/**
+ * A VFS-level node, roughly equivalent to Linux's in-memory `struct inode`.
+ *
+ * A `VNode` is the single authoritative copy of an inode's metadata and cached data at the VFS level.
+ * All open `Handle`s for the same file share one `VNode`, so metadata changes are immediately visible across handles.
+ * File data written through a `VNode` is cached and only written to the backend when the vnode is synced.
+ *
+ * `VNode` methods do *not* acquire the vnode's lock. Callers are responsible for locking, since operations usually span multiple vnode calls.
+ * @category VFS
+ */
+export class VNode extends RwLockable {
+    fs;
+    inode;
+    /** Cached file data. This is a page cache, but with byte granularity */
+    data;
+    /** Ranges of `data` that have been written but not yet synced to the backend */
+    dirtyRanges = [];
+    /** Whether `inode` has changes that have not been synced to the backend */
+    metadataDirty = false;
+    /** The number of active references: open handles and in-progress VFS operations */
+    refs = 0;
+    /** Paths on `fs` that refer to this vnode. Multiple paths refer to the same vnode with hard links */
+    paths = new Set();
+    /** Fallback for when the last path is removed (i.e. the file is unlinked while open) */
+    _lastPath;
+    constructor(fs, path, inode) {
+        super();
+        this.fs = fs;
+        this.inode = inode;
+        this.paths.add(path);
+        this._lastPath = path;
+        this.data = new Resource(inode.ino, inode.size, { sparse: true });
+    }
+    get ino() {
+        return this.inode.ino;
+    }
+    /** A path that can be used to address the backend */
+    get path() {
+        const [path] = this.paths;
+        if (path !== undefined)
+            this._lastPath = path;
+        return path ?? this._lastPath;
+    }
+    /** Whether this vnode has data or metadata that has not been synced to the backend */
+    get dirty() {
+        return this.metadataDirty || this.dirtyRanges.length > 0;
+    }
+    /** Character and block devices bypass the data cache */
+    get bypassCache() {
+        return isCharacterDevice(this.inode) || isBlockDevice(this.inode) || !!(this.inode.flags & InodeFlags.DAX);
+    }
+    /** Add a range to `dirtyRanges`, merging overlapping and adjacent ranges */
+    markDirty(start, end) {
+        this.dirtyRanges.push({ start, end });
+        this.dirtyRanges.sort((a, b) => a.start - b.start);
+        const merged = [];
+        for (const range of this.dirtyRanges) {
+            const last = merged.at(-1);
+            if (last && range.start <= last.end)
+                last.end = Math.max(last.end, range.end);
+            else
+                merged.push(range);
+        }
+        this.dirtyRanges = merged;
+    }
+    /**
+     * Copy `[start, end)` from the cache into `buffer`.
+     * Uncached spans are holes (e.g. from an extending truncate) and are zero-filled.
+     */
+    copyFromCache(buffer, start, end) {
+        let pos = start;
+        for (const region of this.data.regions) {
+            const regionEnd = region.offset + region.data.byteLength;
+            if (regionEnd <= pos)
+                continue;
+            if (region.offset >= end)
+                break;
+            if (region.offset > pos) {
+                buffer.fill(0, pos - start, region.offset - start);
+                pos = region.offset;
+            }
+            const copyEnd = Math.min(end, regionEnd);
+            buffer.set(region.data.subarray(pos - region.offset, copyEnd - region.offset), pos - start);
+            pos = copyEnd;
+        }
+        if (pos < end)
+            buffer.fill(0, pos - start, end - start);
+    }
+    /**
+     * Read `[start, end)` into `buffer`, fetching any missing ranges from the backend.
+     */
+    async read(buffer, start, end) {
+        if (this.bypassCache)
+            return await this.fs.read(this.path, buffer, start, end);
+        for (const { start: rangeStart, end: rangeEnd } of this.data.missing(start, end)) {
+            const chunk = new Uint8Array(rangeEnd - rangeStart);
+            await this.fs.read(this.path, chunk, rangeStart, rangeEnd);
+            this.data.add(chunk, rangeStart);
+        }
+        this.copyFromCache(buffer, start, end);
+    }
+    readSync(buffer, start, end) {
+        if (this.bypassCache)
+            return this.fs.readSync(this.path, buffer, start, end);
+        for (const { start: rangeStart, end: rangeEnd } of this.data.missing(start, end)) {
+            const chunk = new Uint8Array(rangeEnd - rangeStart);
+            this.fs.readSync(this.path, chunk, rangeStart, rangeEnd);
+            this.data.add(chunk, rangeStart);
+        }
+        this.copyFromCache(buffer, start, end);
+    }
+    /**
+     * Write `data` at `offset` into the cache and update metadata.
+     * The backend is not written to until `sync`, except for devices, which bypass the cache.
+     */
+    async write(data, offset) {
+        if (this.bypassCache)
+            await this.fs.write(this.path, data, offset);
+        else
+            this._writeCached(data, offset);
+        this._writeMetadata(offset + data.byteLength);
+    }
+    writeSync(data, offset) {
+        if (this.bypassCache)
+            this.fs.writeSync(this.path, data, offset);
+        else
+            this._writeCached(data, offset);
+        this._writeMetadata(offset + data.byteLength);
+    }
+    _writeCached(data, offset) {
+        const end = offset + data.byteLength;
+        // Copy since the region can keep a reference and the caller may reuse the buffer
+        this.data.add(data.slice(), offset);
+        if (end > this.data.size)
+            this.data.size = end;
+        this.markDirty(offset, end);
+    }
+    _writeMetadata(end) {
+        if (!this.bypassCache && end > this.inode.size)
+            this.inode.size = end;
+        this.inode.mtimeMs = Date.now();
+        this.inode.ctimeMs = Date.now();
+        this.metadataDirty = true;
+    }
+    /**
+     * Change the size of the file.
+     * Note an extending truncate creates a hole, which reads as zeroes.
+     */
+    truncate(length) {
+        this.data.size = length;
+        this.dirtyRanges = this.dirtyRanges
+            .filter(range => range.start < length)
+            .map(range => (range.end > length ? { start: range.start, end: length } : range));
+        this.inode.size = length;
+        this.inode.mtimeMs = Date.now();
+        this.inode.ctimeMs = Date.now();
+        this.metadataDirty = true;
+    }
+    /** Write all unsynced data to the backend, then metadata */
+    async sync() {
+        for (const range of this.dirtyRanges) {
+            for (let pos = range.start; pos < range.end;) {
+                const region = this.data.regionAt(pos);
+                if (!region)
+                    break; // should not happen since dirty ranges are always cached
+                const end = Math.min(range.end, region.offset + region.data.byteLength);
+                await this.fs.write(this.path, region.data.subarray(pos - region.offset, end - region.offset), pos);
+                pos = end;
+            }
+        }
+        this.dirtyRanges = [];
+        if (!this.metadataDirty)
+            return;
+        if (!this.fs.attributes.has('no_write'))
+            await this.fs.touch(this.path, this.inode);
+        this.metadataDirty = false;
+    }
+    syncSync() {
+        for (const range of this.dirtyRanges) {
+            for (let pos = range.start; pos < range.end;) {
+                const region = this.data.regionAt(pos);
+                if (!region)
+                    break; // should not happen since dirty ranges are always cached
+                const end = Math.min(range.end, region.offset + region.data.byteLength);
+                this.fs.writeSync(this.path, region.data.subarray(pos - region.offset, end - region.offset), pos);
+                pos = end;
+            }
+        }
+        this.dirtyRanges = [];
+        if (!this.metadataDirty)
+            return;
+        if (!this.fs.attributes.has('no_write'))
+            this.fs.touchSync(this.path, this.inode);
+        this.metadataDirty = false;
+    }
+}

package/dist/vfs/watchers.js

@@ -5,6 +5,8 @@ import { isStatsEqual } from '../node/stats.js';
 import { statSync } from '../node/sync.js';
 import { basename, dirname, join, relative } from '../path.js';
 import { normalizePath } from '../utils.js';
+/** Alias so `.call` resolves to the non-bigint overload */
+const _statSync = statSync;
 /**
  * Base class for file system watchers.
  * Provides event handling capabilities for watching file system changes.
@@ -90,7 +92,7 @@ export class StatWatcher extends Watcher {
     }
     onInterval() {
         try {
-            const current = statSync(this.path);
+            const current = _statSync.call(this._context, this.path);
             if (!isStatsEqual(this.previous, current)) {
                 this.emit('change', current, this.previous);
                 this.previous = current;
@@ -103,7 +105,7 @@ export class StatWatcher extends Watcher {
     start() {
         const interval = this.options.interval || 5000;
         try {
-            this.previous = statSync(this.path);
+            this.previous = _statSync.call(this._context, this.path);
         }
         catch (e) {
             this.emit('error', e);

package/dist/vfs/xattr.js

@@ -172,7 +172,7 @@ export async function list(path) {
     const inode = await fs.stat(resolved).catch(rethrow('xattr.list', path));
     if (!inode.attributes)
         return [];
-    return inode.attributes.keys().toArray();
+    return [...inode.attributes.keys()];
 }
 /**
  * Synchronously lists all extended attributes of a file.
@@ -192,5 +192,5 @@ export function listSync(path) {
     }
     if (!inode.attributes)
         return [];
-    return inode.attributes.keys().toArray();
+    return [...inode.attributes.keys()];
 }

package/eslint.shared.js

@@ -23,7 +23,7 @@ export default [
 			'prefer-rest-params': 'warn',
 			'prefer-spread': 'warn',
 			'no-unused-vars': 'off',
-			'@typescript-eslint/no-unused-vars': 'warn',
+			'@typescript-eslint/no-unused-vars': ['warn', { varsIgnorePattern: '^_', argsIgnorePattern: '^_' }],
 			'@typescript-eslint/no-inferrable-types': 'off',
 			'@typescript-eslint/no-this-alias': 'off',
 			'@typescript-eslint/no-unsafe-function-type': 'warn',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.5.8",
+	"version": "2.6.0",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",
@@ -64,7 +64,7 @@
 		"spdx:check": "npx lice -a src tests/*.ts tests/**/*.test.ts",
 		"spdx:fix": "npx lice -aw src tests/*.ts tests/**/*.test.ts",
 		"lint": "eslint src tests",
-		"test": "npx zenfs-test --clean; npx zenfs-test -abcp; tests/fetch/run.sh; npx zenfs-test --report",
+		"test": "npx --silent zenfs-test --clean; npx --silent zenfs-test -abcp; tests/fetch/run.sh; npx --silent zenfs-test --report",
 		"build": "tsc -p tsconfig.json",
 		"build:docs": "typedoc",
 		"dev": "tsc -p tsconfig.json --watch",
@@ -74,7 +74,7 @@
 		"@types/node": "^25.2.0",
 		"buffer": "^6.0.3",
 		"eventemitter3": "^5.0.1",
-		"kerium": "^1.3.4",
+		"kerium": "^1.4.2",
 		"memium": "^0.4.0",
 		"readable-stream": "^4.5.2",
 		"utilium": "^3.0.0"

package/scripts/make-index.js

@@ -36,6 +36,9 @@ if (options.quiet && options.verbose) {
 	process.exit();
 }
 
+/**
+ * @param {string} path
+ */
 function fixSlash(path) {
 	return path.replaceAll('\\', '/');
 }
@@ -44,6 +47,9 @@ const resolvedRoot = root || '.';
 
 const entries = new Map();
 
+/**
+ * @param {string} path
+ */
 function computeEntries(path) {
 	try {
 		if (options.ignore.some(pattern => matchesGlob(path, pattern))) {
@@ -68,7 +74,7 @@ function computeEntries(path) {
 		if (options.verbose) {
 			console.log(`${styleText('greenBright', ' dir')} ${path}`);
 		}
-	} catch (e) {
+	} catch (/** @type {any} */ e) {
 		if (!options.quiet) {
 			console.log(`${styleText('red', 'fail')} ${path}: ${e.message}`);
 		}