@zenfs/core 0.16.4 → 0.17.1

package/src/mixins/mutexed.ts

@@ -0,0 +1,245 @@
+import type { Cred } from '../cred.js';
+import { ErrnoError } from '../error.js';
+import type { File } from '../file.js';
+import type { FileSystem } from '../filesystem.js';
+import '../polyfills.js';
+import type { Stats } from '../stats.js';
+import type { Mixin } from './shared.js';
+
+export class MutexLock {
+	protected current = Promise.withResolvers<void>();
+
+	protected _isLocked: boolean = true;
+	public get isLocked(): boolean {
+		return this._isLocked;
+	}
+
+	public constructor(
+		public readonly path: string,
+		protected readonly previous?: MutexLock
+	) {}
+
+	public async done(): Promise<void> {
+		await this.previous?.done();
+		await this.current.promise;
+	}
+
+	public unlock(): void {
+		this.current.resolve();
+		this._isLocked = false;
+	}
+
+	public [Symbol.dispose](): void {
+		this.unlock();
+	}
+}
+
+/**
+ * This serializes access to an underlying async filesystem.
+ * For example, on an OverlayFS instance with an async lower
+ * directory operations like rename and rmdir may involve multiple
+ * requests involving both the upper and lower filesystems -- they
+ * are not executed in a single atomic step. OverlayFS uses this
+ * to avoid having to reason about the correctness of
+ * multiple requests interleaving.
+ *
+ * Note: `@ts-expect-error 2513` is needed because `FS` is not properly detected as being concrete
+ *
+ * @todo Change `using _` to `using void` pending https://github.com/tc39/proposal-discard-binding
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function Mutexed<T extends new (...args: any[]) => FileSystem>(
+	FS: T
+): Mixin<
+	T,
+	{
+		lock(path: string): Promise<MutexLock>;
+		lockSync(path: string): MutexLock;
+		isLocked(path: string): boolean;
+	}
+> {
+	class MutexedFS extends FS {
+		/**
+		 * The current locks
+		 */
+		private locks: Map<string, MutexLock> = new Map();
+
+		/**
+		 * Adds a lock for a path
+		 */
+		protected addLock(path: string): MutexLock {
+			const previous = this.locks.get(path);
+			const lock = new MutexLock(path, previous?.isLocked ? previous : undefined);
+			this.locks.set(path, lock);
+			return lock;
+		}
+
+		/**
+		 * Locks `path` asynchronously.
+		 * If the path is currently locked, waits for it to be unlocked.
+		 * @internal
+		 */
+		public async lock(path: string): Promise<MutexLock> {
+			const previous = this.locks.get(path);
+			const lock = this.addLock(path);
+			await previous?.done();
+			return lock;
+		}
+
+		/**
+		 * Locks `path` asynchronously.
+		 * If the path is currently locked, an error will be thrown
+		 * @internal
+		 */
+		public lockSync(path: string): MutexLock {
+			if (this.locks.has(path)) {
+				// Non-null assertion: we already checked locks has path
+				throw ErrnoError.With('EBUSY', path, 'lockSync');
+			}
+
+			return this.addLock(path);
+		}
+
+		/**
+		 * Whether `path` is locked
+		 * @internal
+		 */
+		public isLocked(path: string): boolean {
+			return !!this.locks.get(path)?.isLocked;
+		}
+
+		/* eslint-disable @typescript-eslint/no-unused-vars */
+		public async rename(oldPath: string, newPath: string, cred: Cred): Promise<void> {
+			using _ = await this.lock(oldPath);
+			// @ts-expect-error 2513
+			await super.rename(oldPath, newPath, cred);
+		}
+
+		public renameSync(oldPath: string, newPath: string, cred: Cred): void {
+			using _ = this.lockSync(oldPath);
+			// @ts-expect-error 2513
+			return super.renameSync(oldPath, newPath, cred);
+		}
+
+		public async stat(path: string, cred: Cred): Promise<Stats> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			return await super.stat(path, cred);
+		}
+
+		public statSync(path: string, cred: Cred): Stats {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.statSync(path, cred);
+		}
+
+		public async openFile(path: string, flag: string, cred: Cred): Promise<File> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			return await super.openFile(path, flag, cred);
+		}
+
+		public openFileSync(path: string, flag: string, cred: Cred): File {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.openFileSync(path, flag, cred);
+		}
+
+		public async createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			return await super.createFile(path, flag, mode, cred);
+		}
+
+		public createFileSync(path: string, flag: string, mode: number, cred: Cred): File {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.createFileSync(path, flag, mode, cred);
+		}
+
+		public async unlink(path: string, cred: Cred): Promise<void> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			await super.unlink(path, cred);
+		}
+
+		public unlinkSync(path: string, cred: Cred): void {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.unlinkSync(path, cred);
+		}
+
+		public async rmdir(path: string, cred: Cred): Promise<void> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			await super.rmdir(path, cred);
+		}
+
+		public rmdirSync(path: string, cred: Cred): void {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.rmdirSync(path, cred);
+		}
+
+		public async mkdir(path: string, mode: number, cred: Cred): Promise<void> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			await super.mkdir(path, mode, cred);
+		}
+
+		public mkdirSync(path: string, mode: number, cred: Cred): void {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.mkdirSync(path, mode, cred);
+		}
+
+		public async readdir(path: string, cred: Cred): Promise<string[]> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			return await super.readdir(path, cred);
+		}
+
+		public readdirSync(path: string, cred: Cred): string[] {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.readdirSync(path, cred);
+		}
+
+		public async exists(path: string, cred: Cred): Promise<boolean> {
+			using _ = await this.lock(path);
+			return await super.exists(path, cred);
+		}
+
+		public existsSync(path: string, cred: Cred): boolean {
+			using _ = this.lockSync(path);
+			return super.existsSync(path, cred);
+		}
+
+		public async link(srcpath: string, dstpath: string, cred: Cred): Promise<void> {
+			using _ = await this.lock(srcpath);
+			// @ts-expect-error 2513
+			await super.link(srcpath, dstpath, cred);
+		}
+
+		public linkSync(srcpath: string, dstpath: string, cred: Cred): void {
+			using _ = this.lockSync(srcpath);
+			// @ts-expect-error 2513
+			return super.linkSync(srcpath, dstpath, cred);
+		}
+
+		public async sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void> {
+			using _ = await this.lock(path);
+			// @ts-expect-error 2513
+			await super.sync(path, data, stats);
+		}
+
+		public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
+			using _ = this.lockSync(path);
+			// @ts-expect-error 2513
+			return super.syncSync(path, data, stats);
+		}
+		/* eslint-enable @typescript-eslint/no-unused-vars */
+	}
+	return MutexedFS;
+}

package/src/mixins/readonly.ts

@@ -0,0 +1,97 @@
+import type { Cred } from '../cred.js';
+import { Errno, ErrnoError } from '../error.js';
+import type { File } from '../file.js';
+import type { FileSystem, FileSystemMetadata } from '../filesystem.js';
+import type { Stats } from '../stats.js';
+import type { Mixin } from './shared.js';
+
+/**
+ * Implements the non-readonly methods to throw `EROFS`
+ */
+/* eslint-disable @typescript-eslint/require-await */
+export function Readonly<T extends typeof FileSystem>(
+	FS: T
+): Mixin<
+	T,
+	{
+		metadata(): FileSystemMetadata;
+		rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
+		renameSync(oldPath: string, newPath: string, cred: Cred): void;
+		createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
+		createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
+		unlink(path: string, cred: Cred): Promise<void>;
+		unlinkSync(path: string, cred: Cred): void;
+		rmdir(path: string, cred: Cred): Promise<void>;
+		rmdirSync(path: string, cred: Cred): void;
+		mkdir(path: string, mode: number, cred: Cred): Promise<void>;
+		mkdirSync(path: string, mode: number, cred: Cred): void;
+		link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
+		linkSync(srcpath: string, dstpath: string, cred: Cred): void;
+		sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
+		syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+	}
+> {
+	abstract class ReadonlyFS extends FS {
+		public metadata(): FileSystemMetadata {
+			return { ...super.metadata(), readonly: true };
+		}
+		/* eslint-disable @typescript-eslint/no-unused-vars */
+		public async rename(oldPath: string, newPath: string, cred: Cred): Promise<void> {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public renameSync(oldPath: string, newPath: string, cred: Cred): void {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public async createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File> {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public createFileSync(path: string, flag: string, mode: number, cred: Cred): File {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public async unlink(path: string, cred: Cred): Promise<void> {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public unlinkSync(path: string, cred: Cred): void {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public async rmdir(path: string, cred: Cred): Promise<void> {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public rmdirSync(path: string, cred: Cred): void {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public async mkdir(path: string, mode: number, cred: Cred): Promise<void> {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public mkdirSync(path: string, mode: number, cred: Cred): void {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public async link(srcpath: string, dstpath: string, cred: Cred): Promise<void> {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public linkSync(srcpath: string, dstpath: string, cred: Cred): void {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public async sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void> {
+			throw new ErrnoError(Errno.EROFS);
+		}
+
+		public syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void {
+			throw new ErrnoError(Errno.EROFS);
+		}
+	}
+	return ReadonlyFS;
+}
+/* eslint-enable @typescript-eslint/require-await */

package/src/mixins/shared.ts

@@ -0,0 +1,20 @@
+/*
+	Code shared by various mixins
+*/
+
+import type { ExtractProperties } from 'utilium';
+import type { FileSystem } from '../filesystem.js';
+
+/**
+ * `TBase` with `TMixin` mixed-in.
+ * @internal @experimental
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Mixin<TBase extends typeof FileSystem, TMixin> = (abstract new (...args: any[]) => TMixin) & TBase;
+
+/**
+ * Asynchronous `FileSystem` methods. This is a convience type.
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type _AsyncFSMethods = ExtractProperties<FileSystem, (...args: any[]) => Promise<unknown>>;

package/src/mixins/sync.ts

@@ -0,0 +1,59 @@
+import type { Cred } from '../cred.js';
+import type { File } from '../file.js';
+import type { Stats } from '../stats.js';
+import type { FileSystem } from '../filesystem.js';
+import type { Mixin, _AsyncFSMethods } from './shared.js';
+
+/**
+ * Implements the asynchronous API in terms of the synchronous API.
+ */
+/* eslint-disable @typescript-eslint/require-await */
+export function Sync<T extends typeof FileSystem>(FS: T): Mixin<T, _AsyncFSMethods> {
+	abstract class SyncFS extends FS implements _AsyncFSMethods {
+		public async exists(path: string, cred: Cred): Promise<boolean> {
+			return this.existsSync(path, cred);
+		}
+
+		public async rename(oldPath: string, newPath: string, cred: Cred): Promise<void> {
+			return this.renameSync(oldPath, newPath, cred);
+		}
+
+		public async stat(path: string, cred: Cred): Promise<Stats> {
+			return this.statSync(path, cred);
+		}
+
+		public async createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File> {
+			return this.createFileSync(path, flag, mode, cred);
+		}
+
+		public async openFile(path: string, flag: string, cred: Cred): Promise<File> {
+			return this.openFileSync(path, flag, cred);
+		}
+
+		public async unlink(path: string, cred: Cred): Promise<void> {
+			return this.unlinkSync(path, cred);
+		}
+
+		public async rmdir(path: string, cred: Cred): Promise<void> {
+			return this.rmdirSync(path, cred);
+		}
+
+		public async mkdir(path: string, mode: number, cred: Cred): Promise<void> {
+			return this.mkdirSync(path, mode, cred);
+		}
+
+		public async readdir(path: string, cred: Cred): Promise<string[]> {
+			return this.readdirSync(path, cred);
+		}
+
+		public async link(srcpath: string, dstpath: string, cred: Cred): Promise<void> {
+			return this.linkSync(srcpath, dstpath, cred);
+		}
+
+		public async sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void> {
+			return this.syncSync(path, data, stats);
+		}
+	}
+	return SyncFS;
+}
+/* eslint-enable @typescript-eslint/require-await */

package/src/utils.ts

@@ -279,11 +279,3 @@ export function normalizeOptions(
 		mode: normalizeMode('mode' in options ? options?.mode : null, mode),
 	};
 }
-
-/**
- * Do nothing
- * @internal
- */
-export function nop() {
-	// do nothing
-}

package/dist/backends/index/index.d.ts

@@ -1,43 +0,0 @@
-import type { StatsLike } from '../../stats.js';
-import { Stats } from '../../stats.js';
-/**
- * An Index in JSON form
- * @internal
- */
-export interface IndexData {
-    version: 1;
-    entries: Record<string, StatsLike<number>>;
-}
-export declare const version = 1;
-/**
- * An index of files
- * @internal
- */
-export declare class Index extends Map<string, Stats> {
-    constructor();
-    /**
-     * Convience method
-     */
-    files(): Map<string, Stats>;
-    /**
-     * Converts the index to JSON
-     */
-    toJSON(): IndexData;
-    /**
-     * Converts the index to a string
-     */
-    toString(): string;
-    /**
-     * Returns the files in the directory `dir`.
-     * This is expensive so it is only called once per directory.
-     */
-    protected dirEntries(dir: string): string[];
-    /**
-     * Loads the index from JSON data
-     */
-    fromJSON(json: IndexData): void;
-    /**
-     * Parses an index from a string
-     */
-    static parse(data: string): Index;
-}

package/dist/backends/index/index.js

@@ -1,83 +0,0 @@
-import { isJSON } from 'utilium';
-import { Errno, ErrnoError } from '../../error.js';
-import { Stats } from '../../stats.js';
-import { encode } from '../../utils.js';
-import { basename, dirname } from '../../emulation/path.js';
-export const version = 1;
-/**
- * An index of files
- * @internal
- */
-export class Index extends Map {
-    constructor() {
-        super();
-    }
-    /**
-     * Convience method
-     */
-    files() {
-        const files = new Map();
-        for (const [path, stats] of this) {
-            if (stats.isFile()) {
-                files.set(path, stats);
-            }
-        }
-        return files;
-    }
-    /**
-     * Converts the index to JSON
-     */
-    toJSON() {
-        return {
-            version,
-            entries: Object.fromEntries(this),
-        };
-    }
-    /**
-     * Converts the index to a string
-     */
-    toString() {
-        return JSON.stringify(this.toJSON());
-    }
-    /**
-     * Returns the files in the directory `dir`.
-     * This is expensive so it is only called once per directory.
-     */
-    dirEntries(dir) {
-        const entries = [];
-        for (const entry of this.keys()) {
-            if (dirname(entry) == dir) {
-                entries.push(basename(entry));
-            }
-        }
-        return entries;
-    }
-    /**
-     * Loads the index from JSON data
-     */
-    fromJSON(json) {
-        if (json.version != version) {
-            throw new ErrnoError(Errno.EINVAL, 'Index version mismatch');
-        }
-        this.clear();
-        for (const [path, data] of Object.entries(json.entries)) {
-            const stats = new Stats(data);
-            if (stats.isDirectory()) {
-                stats.fileData = encode(JSON.stringify(this.dirEntries(path)));
-            }
-            this.set(path, stats);
-        }
-    }
-    /**
-     * Parses an index from a string
-     */
-    static parse(data) {
-        if (!isJSON(data)) {
-            throw new ErrnoError(Errno.EINVAL, 'Invalid JSON');
-        }
-        const json = JSON.parse(data);
-        const index = new Index();
-        index.fromJSON(json);
-        return index;
-    }
-}

package/dist/backends/locked.d.ts

@@ -1,92 +0,0 @@
-import type { Cred } from '../cred.js';
-import type { File } from '../file.js';
-import type { FileSystemMetadata } from '../filesystem.js';
-import { FileSystem } from '../filesystem.js';
-import type { Stats } from '../stats.js';
-import '../polyfills.js';
-export interface MutexLock extends PromiseWithResolvers<void> {
-    [Symbol.dispose](): void;
-}
-/**
- * This class serializes access to an underlying async filesystem.
- * For example, on an OverlayFS instance with an async lower
- * directory operations like rename and rmdir may involve multiple
- * requests involving both the upper and lower filesystems -- they
- * are not executed in a single atomic step.  OverlayFS uses this
- * LockedFS to avoid having to reason about the correctness of
- * multiple requests interleaving.
- * @internal
- */
-export declare class LockedFS<FS extends FileSystem> implements FileSystem {
-    readonly fs: FS;
-    constructor(fs: FS);
-    /**
-     * The current locks
-     */
-    private locks;
-    protected addLock(path: string): MutexLock;
-    /**
-     * Locks `path` asynchronously.
-     * If the path is currently locked, waits for it to be unlocked.
-     * @internal
-     */
-    lock(path: string): Promise<MutexLock>;
-    /**
-     * Locks `path` asynchronously.
-     * If the path is currently locked, an error will be thrown
-     * @internal
-     */
-    lockSync(path: string): MutexLock;
-    /**
-     * Unlocks a path
-     * @param path The path to lock
-     * @param noThrow If true, an error will not be thrown if the path is already unlocked
-     * @returns Whether the path was unlocked
-     * @internal
-     */
-    unlock(path: string, noThrow?: boolean): boolean;
-    /**
-     * Whether `path` is locked
-     * @internal
-     */
-    isLocked(path: string): boolean;
-    ready(): Promise<void>;
-    metadata(): FileSystemMetadata;
-    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
-    renameSync(oldPath: string, newPath: string, cred: Cred): void;
-    stat(path: string, cred: Cred): Promise<Stats>;
-    statSync(path: string, cred: Cred): Stats;
-    openFile(path: string, flag: string, cred: Cred): Promise<File>;
-    openFileSync(path: string, flag: string, cred: Cred): File;
-    createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
-    createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
-    unlink(path: string, cred: Cred): Promise<void>;
-    unlinkSync(path: string, cred: Cred): void;
-    rmdir(path: string, cred: Cred): Promise<void>;
-    rmdirSync(path: string, cred: Cred): void;
-    mkdir(path: string, mode: number, cred: Cred): Promise<void>;
-    mkdirSync(path: string, mode: number, cred: Cred): void;
-    readdir(path: string, cred: Cred): Promise<string[]>;
-    readdirSync(path: string, cred: Cred): string[];
-    exists(path: string, cred: Cred): Promise<boolean>;
-    existsSync(path: string, cred: Cred): boolean;
-    link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
-    linkSync(srcpath: string, dstpath: string, cred: Cred): void;
-    sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
-    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
-}
-export declare const Locked: {
-    name: string;
-    options: {
-        fs: {
-            type: "object";
-            required: true;
-            description: string;
-            validator(fs: FileSystem): void;
-        };
-    };
-    isAvailable(): true;
-    create({ fs }: {
-        fs: FileSystem;
-    } & Partial<import("./backend.js").SharedConfig>): LockedFS<FileSystem>;
-};