@zenfs/core 0.16.4 → 0.17.1

package/dist/mixins/mutexed.js

@@ -0,0 +1,465 @@
+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;
+        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 (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        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;
+        }
+        function next() {
+            while (env.stack.length) {
+                var rec = env.stack.pop();
+                try {
+                    var result = rec.dispose && rec.dispose.call(rec.value);
+                    if (rec.async) return Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            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 { ErrnoError } from '../error.js';
+import '../polyfills.js';
+export class MutexLock {
+    get isLocked() {
+        return this._isLocked;
+    }
+    constructor(path, previous) {
+        this.path = path;
+        this.previous = previous;
+        this.current = Promise.withResolvers();
+        this._isLocked = true;
+    }
+    async done() {
+        await this.previous?.done();
+        await this.current.promise;
+    }
+    unlock() {
+        this.current.resolve();
+        this._isLocked = false;
+    }
+    [Symbol.dispose]() {
+        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(FS) {
+    class MutexedFS extends FS {
+        constructor() {
+            super(...arguments);
+            /**
+             * The current locks
+             */
+            this.locks = new Map();
+            /* eslint-enable @typescript-eslint/no-unused-vars */
+        }
+        /**
+         * Adds a lock for a path
+         */
+        addLock(path) {
+            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
+         */
+        async lock(path) {
+            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
+         */
+        lockSync(path) {
+            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
+         */
+        isLocked(path) {
+            return !!this.locks.get(path)?.isLocked;
+        }
+        /* eslint-disable @typescript-eslint/no-unused-vars */
+        async rename(oldPath, newPath, cred) {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_1, await this.lock(oldPath), false);
+                // @ts-expect-error 2513
+                await super.rename(oldPath, newPath, cred);
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+        renameSync(oldPath, newPath, cred) {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_2, this.lockSync(oldPath), false);
+                // @ts-expect-error 2513
+                return super.renameSync(oldPath, newPath, cred);
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
+            }
+        }
+        async stat(path, cred) {
+            const env_3 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_3, await this.lock(path), false);
+                // @ts-expect-error 2513
+                return await super.stat(path, cred);
+            }
+            catch (e_3) {
+                env_3.error = e_3;
+                env_3.hasError = true;
+            }
+            finally {
+                __disposeResources(env_3);
+            }
+        }
+        statSync(path, cred) {
+            const env_4 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_4, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.statSync(path, cred);
+            }
+            catch (e_4) {
+                env_4.error = e_4;
+                env_4.hasError = true;
+            }
+            finally {
+                __disposeResources(env_4);
+            }
+        }
+        async openFile(path, flag, cred) {
+            const env_5 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_5, await this.lock(path), false);
+                // @ts-expect-error 2513
+                return await super.openFile(path, flag, cred);
+            }
+            catch (e_5) {
+                env_5.error = e_5;
+                env_5.hasError = true;
+            }
+            finally {
+                __disposeResources(env_5);
+            }
+        }
+        openFileSync(path, flag, cred) {
+            const env_6 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_6, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.openFileSync(path, flag, cred);
+            }
+            catch (e_6) {
+                env_6.error = e_6;
+                env_6.hasError = true;
+            }
+            finally {
+                __disposeResources(env_6);
+            }
+        }
+        async createFile(path, flag, mode, cred) {
+            const env_7 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_7, await this.lock(path), false);
+                // @ts-expect-error 2513
+                return await super.createFile(path, flag, mode, cred);
+            }
+            catch (e_7) {
+                env_7.error = e_7;
+                env_7.hasError = true;
+            }
+            finally {
+                __disposeResources(env_7);
+            }
+        }
+        createFileSync(path, flag, mode, cred) {
+            const env_8 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_8, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.createFileSync(path, flag, mode, cred);
+            }
+            catch (e_8) {
+                env_8.error = e_8;
+                env_8.hasError = true;
+            }
+            finally {
+                __disposeResources(env_8);
+            }
+        }
+        async unlink(path, cred) {
+            const env_9 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_9, await this.lock(path), false);
+                // @ts-expect-error 2513
+                await super.unlink(path, cred);
+            }
+            catch (e_9) {
+                env_9.error = e_9;
+                env_9.hasError = true;
+            }
+            finally {
+                __disposeResources(env_9);
+            }
+        }
+        unlinkSync(path, cred) {
+            const env_10 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_10, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.unlinkSync(path, cred);
+            }
+            catch (e_10) {
+                env_10.error = e_10;
+                env_10.hasError = true;
+            }
+            finally {
+                __disposeResources(env_10);
+            }
+        }
+        async rmdir(path, cred) {
+            const env_11 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_11, await this.lock(path), false);
+                // @ts-expect-error 2513
+                await super.rmdir(path, cred);
+            }
+            catch (e_11) {
+                env_11.error = e_11;
+                env_11.hasError = true;
+            }
+            finally {
+                __disposeResources(env_11);
+            }
+        }
+        rmdirSync(path, cred) {
+            const env_12 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_12, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.rmdirSync(path, cred);
+            }
+            catch (e_12) {
+                env_12.error = e_12;
+                env_12.hasError = true;
+            }
+            finally {
+                __disposeResources(env_12);
+            }
+        }
+        async mkdir(path, mode, cred) {
+            const env_13 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_13, await this.lock(path), false);
+                // @ts-expect-error 2513
+                await super.mkdir(path, mode, cred);
+            }
+            catch (e_13) {
+                env_13.error = e_13;
+                env_13.hasError = true;
+            }
+            finally {
+                __disposeResources(env_13);
+            }
+        }
+        mkdirSync(path, mode, cred) {
+            const env_14 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_14, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.mkdirSync(path, mode, cred);
+            }
+            catch (e_14) {
+                env_14.error = e_14;
+                env_14.hasError = true;
+            }
+            finally {
+                __disposeResources(env_14);
+            }
+        }
+        async readdir(path, cred) {
+            const env_15 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_15, await this.lock(path), false);
+                // @ts-expect-error 2513
+                return await super.readdir(path, cred);
+            }
+            catch (e_15) {
+                env_15.error = e_15;
+                env_15.hasError = true;
+            }
+            finally {
+                __disposeResources(env_15);
+            }
+        }
+        readdirSync(path, cred) {
+            const env_16 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_16, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.readdirSync(path, cred);
+            }
+            catch (e_16) {
+                env_16.error = e_16;
+                env_16.hasError = true;
+            }
+            finally {
+                __disposeResources(env_16);
+            }
+        }
+        async exists(path, cred) {
+            const env_17 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_17, await this.lock(path), false);
+                return await super.exists(path, cred);
+            }
+            catch (e_17) {
+                env_17.error = e_17;
+                env_17.hasError = true;
+            }
+            finally {
+                __disposeResources(env_17);
+            }
+        }
+        existsSync(path, cred) {
+            const env_18 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_18, this.lockSync(path), false);
+                return super.existsSync(path, cred);
+            }
+            catch (e_18) {
+                env_18.error = e_18;
+                env_18.hasError = true;
+            }
+            finally {
+                __disposeResources(env_18);
+            }
+        }
+        async link(srcpath, dstpath, cred) {
+            const env_19 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_19, await this.lock(srcpath), false);
+                // @ts-expect-error 2513
+                await super.link(srcpath, dstpath, cred);
+            }
+            catch (e_19) {
+                env_19.error = e_19;
+                env_19.hasError = true;
+            }
+            finally {
+                __disposeResources(env_19);
+            }
+        }
+        linkSync(srcpath, dstpath, cred) {
+            const env_20 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_20, this.lockSync(srcpath), false);
+                // @ts-expect-error 2513
+                return super.linkSync(srcpath, dstpath, cred);
+            }
+            catch (e_20) {
+                env_20.error = e_20;
+                env_20.hasError = true;
+            }
+            finally {
+                __disposeResources(env_20);
+            }
+        }
+        async sync(path, data, stats) {
+            const env_21 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_21, await this.lock(path), false);
+                // @ts-expect-error 2513
+                await super.sync(path, data, stats);
+            }
+            catch (e_21) {
+                env_21.error = e_21;
+                env_21.hasError = true;
+            }
+            finally {
+                __disposeResources(env_21);
+            }
+        }
+        syncSync(path, data, stats) {
+            const env_22 = { stack: [], error: void 0, hasError: false };
+            try {
+                const _ = __addDisposableResource(env_22, this.lockSync(path), false);
+                // @ts-expect-error 2513
+                return super.syncSync(path, data, stats);
+            }
+            catch (e_22) {
+                env_22.error = e_22;
+                env_22.hasError = true;
+            }
+            finally {
+                __disposeResources(env_22);
+            }
+        }
+    }
+    return MutexedFS;
+}

package/dist/mixins/readonly.d.ts

@@ -0,0 +1,25 @@
+import type { Cred } from '../cred.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`
+ */
+export declare 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;
+}>;

package/dist/mixins/readonly.js

@@ -0,0 +1,57 @@
+import { Errno, ErrnoError } from '../error.js';
+/**
+ * Implements the non-readonly methods to throw `EROFS`
+ */
+/* eslint-disable @typescript-eslint/require-await */
+export function Readonly(FS) {
+    class ReadonlyFS extends FS {
+        metadata() {
+            return { ...super.metadata(), readonly: true };
+        }
+        /* eslint-disable @typescript-eslint/no-unused-vars */
+        async rename(oldPath, newPath, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        renameSync(oldPath, newPath, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        async createFile(path, flag, mode, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        createFileSync(path, flag, mode, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        async unlink(path, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        unlinkSync(path, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        async rmdir(path, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        rmdirSync(path, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        async mkdir(path, mode, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        mkdirSync(path, mode, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        async link(srcpath, dstpath, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        linkSync(srcpath, dstpath, cred) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        async sync(path, data, stats) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+        syncSync(path, data, stats) {
+            throw new ErrnoError(Errno.EROFS);
+        }
+    }
+    return ReadonlyFS;
+}
+/* eslint-enable @typescript-eslint/require-await */

package/dist/mixins/shared.d.ts

@@ -0,0 +1,12 @@
+import type { ExtractProperties } from 'utilium';
+import type { FileSystem } from '../filesystem.js';
+/**
+ * `TBase` with `TMixin` mixed-in.
+ * @internal @experimental
+ */
+export type Mixin<TBase extends typeof FileSystem, TMixin> = (abstract new (...args: any[]) => TMixin) & TBase;
+/**
+ * Asynchronous `FileSystem` methods. This is a convience type.
+ * @internal
+ */
+export type _AsyncFSMethods = ExtractProperties<FileSystem, (...args: any[]) => Promise<unknown>>;

package/dist/mixins/shared.js

@@ -0,0 +1,4 @@
+/*
+    Code shared by various mixins
+*/
+export {};

package/dist/mixins/sync.d.ts

@@ -0,0 +1,6 @@
+import type { FileSystem } from '../filesystem.js';
+import type { Mixin, _AsyncFSMethods } from './shared.js';
+/**
+ * Implements the asynchronous API in terms of the synchronous API.
+ */
+export declare function Sync<T extends typeof FileSystem>(FS: T): Mixin<T, _AsyncFSMethods>;

package/dist/mixins/sync.js

@@ -0,0 +1,43 @@
+/**
+ * Implements the asynchronous API in terms of the synchronous API.
+ */
+/* eslint-disable @typescript-eslint/require-await */
+export function Sync(FS) {
+    class SyncFS extends FS {
+        async exists(path, cred) {
+            return this.existsSync(path, cred);
+        }
+        async rename(oldPath, newPath, cred) {
+            return this.renameSync(oldPath, newPath, cred);
+        }
+        async stat(path, cred) {
+            return this.statSync(path, cred);
+        }
+        async createFile(path, flag, mode, cred) {
+            return this.createFileSync(path, flag, mode, cred);
+        }
+        async openFile(path, flag, cred) {
+            return this.openFileSync(path, flag, cred);
+        }
+        async unlink(path, cred) {
+            return this.unlinkSync(path, cred);
+        }
+        async rmdir(path, cred) {
+            return this.rmdirSync(path, cred);
+        }
+        async mkdir(path, mode, cred) {
+            return this.mkdirSync(path, mode, cred);
+        }
+        async readdir(path, cred) {
+            return this.readdirSync(path, cred);
+        }
+        async link(srcpath, dstpath, cred) {
+            return this.linkSync(srcpath, dstpath, cred);
+        }
+        async sync(path, data, stats) {
+            return this.syncSync(path, data, stats);
+        }
+    }
+    return SyncFS;
+}
+/* eslint-enable @typescript-eslint/require-await */

package/dist/utils.d.ts

@@ -82,8 +82,3 @@ export declare function normalizeOptions(options: fs.WriteFileOptions | (fs.Enco
     flag: string;
     mode: number;
 };
-/**
- * Do nothing
- * @internal
- */
-export declare function nop(): void;

package/dist/utils.js

@@ -219,10 +219,3 @@ export function normalizeOptions(options, encoding = 'utf8', flag, mode = 0) {
         mode: normalizeMode('mode' in options ? options?.mode : null, mode),
     };
 }
-/**
- * Do nothing
- * @internal
- */
-export function nop() {
-    // do nothing
-}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "0.16.4",
+	"version": "0.17.1",
 	"description": "A filesystem, anywhere",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -40,7 +40,8 @@
 	"exports": {
 		".": "./dist/index.js",
 		"./*": "./dist/*",
-		"./promises": "./dist/emulation/promises.js"
+		"./promises": "./dist/emulation/promises.js",
+		"./mixins": "./dist/mixins/index.js"
 	},
 	"scripts": {
 		"format": "prettier --write .",

package/src/backends/backend.ts

@@ -66,12 +66,11 @@ export interface Backend<FS extends FileSystem = FileSystem, TOptions extends ob
 	/**
 	 * Whether the backend is available in the current environment.
 	 * It supports checking synchronously and asynchronously
-	 * Sync:
+	 *
 	 * Returns 'true' if this backend is available in the current
-	 * environment. For example, a `localStorage`-backed filesystem will return
-	 * 'false' if the browser does not support that API.
+	 * environment. For example, a backend using a browser API will return
+	 * 'false' if the API is unavailable
 	 *
-	 * Defaults to 'false', as the FileSystem base class isn't usable alone.
 	 */
 	isAvailable(): boolean | Promise<boolean>;
 }