@zenfs/core 0.5.12 → 0.7.0

package/dist/filesystem.js

@@ -1,4 +1,7 @@
 import { ApiError, ErrorCode } from './ApiError.js';
+import { PreloadFile, parseFlag } from './file.js';
+import { rootCred } from './cred.js';
+import { join } from './emulation/path.js';
 /**
  * Structure for a filesystem. All ZenFS FileSystems must implement this.
  *
@@ -10,11 +13,13 @@ import { ApiError, ErrorCode } from './ApiError.js';
  * - All arguments are present. Any optional arguments at the Node API level have been passed in with their default values.
  */
 export class FileSystem {
+    /**
+     * Get metadata about the current file syste,
+     */
     metadata() {
         return {
             name: this.constructor.name,
             readonly: false,
-            synchronous: false,
             supportsProperties: false,
             totalSpace: 0,
             freeSpace: 0,
@@ -57,9 +62,6 @@ export function Sync(FS) {
      * Implements the asynchronous API in terms of the synchronous API.
      */
     class _SyncFileSystem extends FS {
-        metadata() {
-            return { ...super.metadata(), synchronous: true };
-        }
         async ready() {
             return this;
         }
@@ -99,44 +101,148 @@ export function Sync(FS) {
     }
     return _SyncFileSystem;
 }
+/**
+ * Async() implements synchronous methods on an asynchronous file system
+ *
+ * Implementing classes must define a protected _sync property for the synchronous file system used as a cache.
+ * by:
+ *
+ * - Performing operations over the in-memory copy, while asynchronously pipelining them
+ *   to the backing store.
+ * - During application loading, the contents of the async file system can be reloaded into
+ *   the synchronous store, if desired.
+ *
+ */
 export function Async(FS) {
     class _AsyncFileSystem extends FS {
-        metadata() {
-            return { ...super.metadata(), synchronous: false };
+        constructor() {
+            super(...arguments);
+            /**
+             * Queue of pending asynchronous operations.
+             */
+            this._queue = [];
+            this._queueRunning = false;
+            this._isInitialized = false;
+        }
+        async ready() {
+            await this._initialize();
+            return this;
         }
-        /* eslint-disable @typescript-eslint/no-unused-vars */
         renameSync(oldPath, newPath, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+            this._sync.renameSync(oldPath, newPath, cred);
+            this.queue('rename', oldPath, newPath, cred);
         }
-        statSync(path, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+        statSync(p, cred) {
+            return this._sync.statSync(p, cred);
         }
         createFileSync(path, flag, mode, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+            const file = this._sync.createFileSync(path, flag, mode, cred);
+            this.queue('createFile', path, flag, mode, cred);
+            const stats = file.statSync();
+            const buffer = new Uint8Array(stats.size);
+            file.readSync(buffer);
+            return new PreloadFile(this, path, flag, stats, buffer);
         }
         openFileSync(path, flag, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+            return this._sync.openFileSync(path, flag, cred);
         }
-        unlinkSync(path, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+        unlinkSync(p, cred) {
+            this._sync.unlinkSync(p, cred);
+            this.queue('unlink', p, cred);
         }
-        rmdirSync(path, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+        rmdirSync(p, cred) {
+            this._sync.rmdirSync(p, cred);
+            this.queue('rmdir', p, cred);
         }
-        mkdirSync(path, mode, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+        mkdirSync(p, mode, cred) {
+            this._sync.mkdirSync(p, mode, cred);
+            this.queue('mkdir', p, mode, cred);
         }
-        readdirSync(path, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+        readdirSync(p, cred) {
+            return this._sync.readdirSync(p, cred);
         }
         linkSync(srcpath, dstpath, cred) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+            this._sync.linkSync(srcpath, dstpath, cred);
+            this.queue('link', srcpath, dstpath, cred);
         }
         syncSync(path, data, stats) {
-            throw new ApiError(ErrorCode.ENOTSUP);
+            this._sync.syncSync(path, data, stats);
+            this.queue('sync', path, data, stats);
+        }
+        existsSync(p, cred) {
+            return this._sync.existsSync(p, cred);
+        }
+        /**
+         * @internal
+         */
+        async crossCopy(p) {
+            const stats = await this.stat(p, rootCred);
+            if (stats.isDirectory()) {
+                if (p !== '/') {
+                    const stats = await this.stat(p, rootCred);
+                    this._sync.mkdirSync(p, stats.mode, stats.cred());
+                }
+                const files = await this.readdir(p, rootCred);
+                for (const file of files) {
+                    await this.crossCopy(join(p, file));
+                }
+            }
+            else {
+                const asyncFile = await this.openFile(p, parseFlag('r'), rootCred);
+                const syncFile = this._sync.createFileSync(p, parseFlag('w'), stats.mode, rootCred);
+                try {
+                    const { size } = await asyncFile.stat();
+                    const buffer = new Uint8Array(size);
+                    await asyncFile.read(buffer);
+                    syncFile.writeSync(buffer);
+                }
+                finally {
+                    await asyncFile.close();
+                    syncFile.closeSync();
+                }
+            }
+        }
+        /**
+         * Called once to load up files from async storage into sync storage.
+         */
+        async _initialize() {
+            if (this._isInitialized) {
+                return;
+            }
+            try {
+                await this.crossCopy('/');
+                this._isInitialized = true;
+            }
+            catch (e) {
+                this._isInitialized = false;
+                throw e;
+            }
+        }
+        /**
+         * @internal
+         */
+        async _next() {
+            if (this._queue.length == 0) {
+                this._queueRunning = false;
+                return;
+            }
+            const [method, ...args] = this._queue.shift();
+            // @ts-expect-error 2556 (since ...args is not correctly picked up as being a tuple)
+            await this[method](...args);
+            await this._next();
+        }
+        /**
+         * @internal
+         */
+        queue(...op) {
+            this._queue.push(op);
+            if (this._queueRunning) {
+                return;
+            }
+            this._queueRunning = true;
+            this._next();
         }
     }
-    /* eslint-enable @typescript-eslint/no-unused-vars */
     return _AsyncFileSystem;
 }
 export function Readonly(FS) {

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export * from './backends/backend.js';
-export * from './backends/AsyncMirror.js';
 export * from './backends/AsyncStore.js';
 export * from './backends/InMemory.js';
 export * from './backends/Locked.js';
@@ -15,6 +14,7 @@ export * from './inode.js';
 export * from './mutex.js';
 export * from './stats.js';
 export * from './utils.js';
+export * from './emulation/index.js';
 import * as fs from './emulation/index.js';
 export { fs };
 export default fs;

package/dist/index.js

@@ -1,5 +1,4 @@
 export * from './backends/backend.js';
-export * from './backends/AsyncMirror.js';
 export * from './backends/AsyncStore.js';
 export * from './backends/InMemory.js';
 export * from './backends/Locked.js';
@@ -15,6 +14,7 @@ export * from './inode.js';
 export * from './mutex.js';
 export * from './stats.js';
 export * from './utils.js';
+export * from './emulation/index.js';
 import * as fs from './emulation/index.js';
 export { fs };
 export default fs;

package/dist/utils.d.ts

@@ -14,7 +14,10 @@ export declare function mkdirpSync(p: string, mode: number, cred: Cred, fs: File
  * @hidden
  */
 export declare function levenshtein(a: string, b: string): number;
-/** Waits n ms.  */
+/**
+ * Waits n ms.
+ * @hidden
+ */
 export declare function wait(ms: number): Promise<void>;
 /**
  * @hidden
@@ -32,11 +35,28 @@ export declare function encode(input: string): Uint8Array;
 export declare function decode(input?: Uint8Array): string;
 /**
  * Decodes a directory listing
- * @internal
+ * @hidden
  */
 export declare function decodeDirListing(data: Uint8Array): Record<string, bigint>;
 /**
  * Encodes a directory listing
- * @internal
+ * @hidden
  */
 export declare function encodeDirListing(data: Record<string, bigint>): Uint8Array;
+/**
+ * Extracts an object of properties assignable to P from an object T
+ * @hidden
+ */
+export type ExtractProperties<T, P> = {
+    [K in keyof T as T[K] extends infer Prop ? (Prop extends P ? K : never) : never]: T[K];
+};
+/**
+ * Extract a the keys in T which are required properties
+ * @hidden
+ * @see https://stackoverflow.com/a/55247867/17637456
+ */
+export type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends {
+        [P in K]: T[K];
+    } ? never : K;
+}[keyof T];

package/dist/utils.js

@@ -83,7 +83,10 @@ export function levenshtein(a, b) {
     }
     return dd;
 }
-/** Waits n ms.  */
+/**
+ * Waits n ms.
+ * @hidden
+ */
 export function wait(ms) {
     return new Promise(resolve => {
         setTimeout(resolve, ms);
@@ -117,7 +120,7 @@ export function decode(input) {
 }
 /**
  * Decodes a directory listing
- * @internal
+ * @hidden
  */
 export function decodeDirListing(data) {
     return JSON.parse(decode(data), (k, v) => {
@@ -129,7 +132,7 @@ export function decodeDirListing(data) {
 }
 /**
  * Encodes a directory listing
- * @internal
+ * @hidden
  */
 export function encodeDirListing(data) {
     return encode(JSON.stringify(data, (k, v) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "0.5.12",
+	"version": "0.7.0",
 	"description": "A filesystem in your browser",
 	"main": "dist/index.js",
 	"types": "dist",
@@ -32,7 +32,8 @@
 	},
 	"exports": {
 		".": "./dist/index.js",
-		"./*": "./dist/*"
+		"./*": "./dist/*",
+		"./promises": "./dist/emulations/promises.js"
 	},
 	"typesVersions": {
 		"*": {

package/dist/backends/AsyncMirror.d.ts

@@ -1,126 +0,0 @@
-import { FileSystem, FileSystemMetadata } from '../filesystem.js';
-import { File, PreloadFile } from '../file.js';
-import type { Stats } from '../stats.js';
-import { Cred } from '../cred.js';
-import type { Backend } from './backend.js';
-/**
- * We define our own file to interpose on syncSync() for mirroring purposes.
- * @internal
- */
-export declare class MirrorFile extends PreloadFile<AsyncMirrorFS> {
-    constructor(fs: AsyncMirrorFS, path: string, flag: string, stat: Stats, data: Uint8Array);
-    sync(): Promise<void>;
-    syncSync(): void;
-    close(): Promise<void>;
-    closeSync(): void;
-}
-/**
- * Configuration options for the AsyncMirror file system.
- */
-export interface AsyncMirrorOptions {
-    /**
-     * The synchronous file system to mirror the asynchronous file system to.
-     */
-    sync: FileSystem;
-    /**
-     * The asynchronous file system to mirror.
-     */
-    async: FileSystem;
-}
-declare const AsyncMirrorFS_base: (abstract new (...args: any[]) => {
-    metadata(): FileSystemMetadata;
-    ready(): Promise<any>;
-    exists(path: string, cred: Cred): Promise<boolean>;
-    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
-    stat(path: string, cred: Cred): Promise<Stats>;
-    createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
-    openFile(path: string, flag: string, cred: Cred): Promise<File>;
-    unlink(path: string, cred: Cred): Promise<void>;
-    rmdir(path: string, cred: Cred): Promise<void>;
-    mkdir(path: string, mode: number, cred: Cred): Promise<void>;
-    readdir(path: string, cred: Cred): Promise<string[]>;
-    link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
-    sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
-    renameSync(oldPath: string, newPath: string, cred: Cred): void;
-    statSync(path: string, cred: Cred): Stats;
-    openFileSync(path: string, flag: string, cred: Cred): File;
-    createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
-    unlinkSync(path: string, cred: Cred): void;
-    rmdirSync(path: string, cred: Cred): void;
-    mkdirSync(path: string, mode: number, cred: Cred): void;
-    readdirSync(path: string, cred: Cred): string[];
-    existsSync(path: string, cred: Cred): boolean;
-    linkSync(srcpath: string, dstpath: string, cred: Cred): void;
-    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
-}) & typeof FileSystem;
-/**
- * AsyncMirrorFS mirrors a synchronous filesystem into an asynchronous filesystem
- * by:
- *
- * * Performing operations over the in-memory copy, while asynchronously pipelining them
- *   to the backing store.
- * * During application loading, the contents of the async file system can be reloaded into
- *   the synchronous store, if desired.
- *
- * The two stores will be kept in sync. The most common use-case is to pair a synchronous
- * in-memory filesystem with an asynchronous backing store.
- *
- */
-export declare class AsyncMirrorFS extends AsyncMirrorFS_base {
-    /**
-     * Queue of pending asynchronous operations.
-     */
-    private _queue;
-    private _queueRunning;
-    private _sync;
-    private _async;
-    private _isInitialized;
-    private _ready;
-    ready(): Promise<this>;
-    /**
-     *
-     * Mirrors the synchronous file system into the asynchronous file system.
-     *
-     * @param sync The synchronous file system to mirror the asynchronous file system to.
-     * @param async The asynchronous file system to mirror.
-     */
-    constructor({ sync, async }: AsyncMirrorOptions);
-    metadata(): FileSystemMetadata;
-    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
-    openFileSync(path: string, flag: string, cred: Cred): File;
-    createFileSync(path: string, flag: string, mode: number, cred: Cred): MirrorFile;
-    linkSync(srcpath: string, dstpath: string, cred: Cred): void;
-    renameSync(oldPath: string, newPath: string, cred: Cred): void;
-    statSync(p: string, cred: Cred): Stats;
-    unlinkSync(p: string, cred: Cred): void;
-    rmdirSync(p: string, cred: Cred): void;
-    mkdirSync(p: string, mode: number, cred: Cred): void;
-    readdirSync(p: string, cred: Cred): string[];
-    existsSync(p: string, cred: Cred): boolean;
-    /**
-     * @internal
-     */
-    protected crossCopyDirectory(p: string, mode: number): Promise<void>;
-    /**
-     * @internal
-     */
-    protected crossCopyFile(p: string, mode: number): Promise<void>;
-    /**
-     * @internal
-     */
-    protected crossCopy(p: string): Promise<void>;
-    /**
-     * Called once to load up files from async storage into sync storage.
-     */
-    protected _initialize(): Promise<void>;
-    /**
-     * @internal
-     */
-    private _next;
-    /**
-     * @internal
-     */
-    private enqueue;
-}
-export declare const AsyncMirror: Backend<AsyncMirrorFS>;
-export {};

package/dist/backends/AsyncMirror.js

@@ -1,253 +0,0 @@
-import { FileSystem, Sync } from '../filesystem.js';
-import { ApiError, ErrorCode } from '../ApiError.js';
-import { PreloadFile, parseFlag } from '../file.js';
-import { join } from '../emulation/path.js';
-import { rootCred } from '../cred.js';
-/**
- * We define our own file to interpose on syncSync() for mirroring purposes.
- * @internal
- */
-export class MirrorFile extends PreloadFile {
-    constructor(fs, path, flag, stat, data) {
-        super(fs, path, flag, stat, data);
-    }
-    async sync() {
-        this.syncSync();
-    }
-    syncSync() {
-        if (this.isDirty()) {
-            this.fs.syncSync(this.path, this._buffer, this.stats);
-            this.resetDirty();
-        }
-    }
-    async close() {
-        this.closeSync();
-    }
-    closeSync() {
-        this.syncSync();
-    }
-}
-/**
- * AsyncMirrorFS mirrors a synchronous filesystem into an asynchronous filesystem
- * by:
- *
- * * Performing operations over the in-memory copy, while asynchronously pipelining them
- *   to the backing store.
- * * During application loading, the contents of the async file system can be reloaded into
- *   the synchronous store, if desired.
- *
- * The two stores will be kept in sync. The most common use-case is to pair a synchronous
- * in-memory filesystem with an asynchronous backing store.
- *
- */
-export class AsyncMirrorFS extends Sync(FileSystem) {
-    async ready() {
-        await this._ready;
-        return this;
-    }
-    /**
-     *
-     * Mirrors the synchronous file system into the asynchronous file system.
-     *
-     * @param sync The synchronous file system to mirror the asynchronous file system to.
-     * @param async The asynchronous file system to mirror.
-     */
-    constructor({ sync, async }) {
-        super();
-        /**
-         * Queue of pending asynchronous operations.
-         */
-        this._queue = [];
-        this._queueRunning = false;
-        this._isInitialized = false;
-        this._sync = sync;
-        this._async = async;
-        this._ready = this._initialize();
-    }
-    metadata() {
-        return {
-            ...super.metadata(),
-            name: AsyncMirrorFS.name,
-            synchronous: true,
-            supportsProperties: this._sync.metadata().supportsProperties && this._async.metadata().supportsProperties,
-        };
-    }
-    syncSync(path, data, stats) {
-        this._sync.syncSync(path, data, stats);
-        this.enqueue({
-            apiMethod: 'sync',
-            arguments: [path, data, stats],
-        });
-    }
-    openFileSync(path, flag, cred) {
-        return this._sync.openFileSync(path, flag, cred);
-    }
-    createFileSync(path, flag, mode, cred) {
-        const file = this._sync.createFileSync(path, flag, mode, cred);
-        this.enqueue({
-            apiMethod: 'createFile',
-            arguments: [path, flag, mode, cred],
-        });
-        const stats = file.statSync();
-        const buffer = new Uint8Array(stats.size);
-        file.readSync(buffer);
-        return new MirrorFile(this, path, flag, stats, buffer);
-    }
-    linkSync(srcpath, dstpath, cred) {
-        this._sync.linkSync(srcpath, dstpath, cred);
-        this.enqueue({
-            apiMethod: 'link',
-            arguments: [srcpath, dstpath, cred],
-        });
-    }
-    renameSync(oldPath, newPath, cred) {
-        this._sync.renameSync(oldPath, newPath, cred);
-        this.enqueue({
-            apiMethod: 'rename',
-            arguments: [oldPath, newPath, cred],
-        });
-    }
-    statSync(p, cred) {
-        return this._sync.statSync(p, cred);
-    }
-    unlinkSync(p, cred) {
-        this._sync.unlinkSync(p, cred);
-        this.enqueue({
-            apiMethod: 'unlink',
-            arguments: [p, cred],
-        });
-    }
-    rmdirSync(p, cred) {
-        this._sync.rmdirSync(p, cred);
-        this.enqueue({
-            apiMethod: 'rmdir',
-            arguments: [p, cred],
-        });
-    }
-    mkdirSync(p, mode, cred) {
-        this._sync.mkdirSync(p, mode, cred);
-        this.enqueue({
-            apiMethod: 'mkdir',
-            arguments: [p, mode, cred],
-        });
-    }
-    readdirSync(p, cred) {
-        return this._sync.readdirSync(p, cred);
-    }
-    existsSync(p, cred) {
-        return this._sync.existsSync(p, cred);
-    }
-    /**
-     * @internal
-     */
-    async crossCopyDirectory(p, mode) {
-        if (p !== '/') {
-            const stats = await this._async.stat(p, rootCred);
-            this._sync.mkdirSync(p, mode, stats.cred());
-        }
-        const files = await this._async.readdir(p, rootCred);
-        for (const file of files) {
-            await this.crossCopy(join(p, file));
-        }
-    }
-    /**
-     * @internal
-     */
-    async crossCopyFile(p, mode) {
-        const asyncFile = await this._async.openFile(p, parseFlag('r'), rootCred);
-        const syncFile = this._sync.createFileSync(p, parseFlag('w'), mode, rootCred);
-        try {
-            const { size } = await asyncFile.stat();
-            const buffer = new Uint8Array(size);
-            await asyncFile.read(buffer);
-            syncFile.writeSync(buffer);
-        }
-        finally {
-            await asyncFile.close();
-            syncFile.closeSync();
-        }
-    }
-    /**
-     * @internal
-     */
-    async crossCopy(p) {
-        const stats = await this._async.stat(p, rootCred);
-        if (stats.isDirectory()) {
-            await this.crossCopyDirectory(p, stats.mode);
-        }
-        else {
-            await this.crossCopyFile(p, stats.mode);
-        }
-    }
-    /**
-     * Called once to load up files from async storage into sync storage.
-     */
-    async _initialize() {
-        if (this._isInitialized) {
-            return;
-        }
-        try {
-            await this.crossCopy('/');
-            this._isInitialized = true;
-        }
-        catch (e) {
-            this._isInitialized = false;
-            throw e;
-        }
-    }
-    /**
-     * @internal
-     */
-    async _next() {
-        if (this._queue.length == 0) {
-            this._queueRunning = false;
-            return;
-        }
-        const op = this._queue.shift();
-        try {
-            // @ts-expect-error 2556 (since ...args is not correctly picked up as being a tuple)
-            await this._async[op.apiMethod](...op.arguments);
-        }
-        catch (e) {
-            throw new ApiError(ErrorCode.EIO, 'AsyncMirror desync: ' + e);
-        }
-        await this._next();
-    }
-    /**
-     * @internal
-     */
-    enqueue(op) {
-        this._queue.push(op);
-        if (this._queueRunning) {
-            return;
-        }
-        this._queueRunning = true;
-        this._next();
-    }
-}
-export const AsyncMirror = {
-    name: 'AsyncMirror',
-    options: {
-        sync: {
-            type: 'object',
-            required: true,
-            description: 'The synchronous file system to mirror the asynchronous file system to.',
-            validator: async (backend) => {
-                if ('metadata' in backend && !backend.metadata().synchronous) {
-                    throw new ApiError(ErrorCode.EINVAL, '"sync" option must be a file system that supports synchronous operations');
-                }
-            },
-        },
-        async: {
-            type: 'object',
-            required: true,
-            description: 'The asynchronous file system to mirror.',
-        },
-    },
-    isAvailable() {
-        return true;
-    },
-    create(options) {
-        return new AsyncMirrorFS(options);
-    },
-};