@zenfs/core 0.6.0 → 0.7.1

package/dist/config.d.ts

@@ -3,12 +3,12 @@ import { FileSystem } from './filesystem.js';
 /**
  * Configuration for a specific mount point
  */
-export type MountConfiguration<FS extends FileSystem = FileSystem> = FS | BackendConfiguration<FS> | Backend<FS>;
+export type MountConfiguration<FS extends FileSystem = FileSystem, TOptions extends object = object> = FS | BackendConfiguration<FS, TOptions> | Backend<FS, TOptions>;
 /**
  * Retrieve a file system with the given configuration.
  * @param config A BackendConfig object.
  */
-export declare function resolveMountConfig<FS extends FileSystem>(config: MountConfiguration<FS>, _depth?: number): Promise<FS>;
+export declare function resolveMountConfig<FS extends FileSystem, TOptions extends object = object>(config: MountConfiguration<FS, TOptions>, _depth?: number): Promise<FS>;
 /**
  *A mapping of mount points to their configurations
  */

package/dist/file.d.ts

@@ -187,12 +187,9 @@ export declare abstract class File {
  * An implementation of the File interface that operates on a file that is
  * completely in-memory. PreloadFiles are backed by a Uint8Array.
  *
- * This is also an abstract class, as it lacks an implementation of 'sync' and
- * 'close'. Each filesystem that wishes to use this file representation must
- * extend this class and implement those two methods.
  * @todo 'close' lever that disables functionality once closed.
  */
-export declare abstract class PreloadFile<FS extends FileSystem> extends File {
+export declare class PreloadFile<FS extends FileSystem> extends File {
     /**
      * The file system that created the file.
      */
@@ -246,6 +243,10 @@ export declare abstract class PreloadFile<FS extends FileSystem> extends File {
      * @param newPos new position
      */
     set position(newPos: number);
+    sync(): Promise<void>;
+    syncSync(): void;
+    close(): Promise<void>;
+    closeSync(): void;
     /**
      * Asynchronous `stat`.
      */
@@ -350,16 +351,6 @@ export declare abstract class PreloadFile<FS extends FileSystem> extends File {
     _setType(type: FileType): Promise<void>;
     _setTypeSync(type: FileType): void;
 }
-/**
- * For synchronous file systems
- */
-export declare class SyncFile<FS extends FileSystem> extends PreloadFile<FS> {
-    constructor(_fs: FS, _path: string, _flag: string, _stat: Stats, contents?: Uint8Array);
-    sync(): Promise<void>;
-    syncSync(): void;
-    close(): Promise<void>;
-    closeSync(): void;
-}
 /**
  * For the filesystems which do not sync to anything..
  */

package/dist/file.js

@@ -154,9 +154,6 @@ export class File {
  * An implementation of the File interface that operates on a file that is
  * completely in-memory. PreloadFiles are backed by a Uint8Array.
  *
- * This is also an abstract class, as it lacks an implementation of 'sync' and
- * 'close'. Each filesystem that wishes to use this file representation must
- * extend this class and implement those two methods.
  * @todo 'close' lever that disables functionality once closed.
  */
 export class PreloadFile extends File {
@@ -230,6 +227,26 @@ export class PreloadFile extends File {
     set position(newPos) {
         this._position = newPos;
     }
+    async sync() {
+        if (!this.isDirty()) {
+            return;
+        }
+        await this.fs.sync(this.path, this._buffer, this.stats);
+        this._dirty = false;
+    }
+    syncSync() {
+        if (!this.isDirty()) {
+            return;
+        }
+        this.fs.syncSync(this.path, this._buffer, this.stats);
+        this._dirty = false;
+    }
+    async close() {
+        await this.sync();
+    }
+    closeSync() {
+        this.syncSync();
+    }
     /**
      * Asynchronous `stat`.
      */
@@ -248,7 +265,7 @@ export class PreloadFile extends File {
      */
     truncate(len) {
         this.truncateSync(len);
-        if (isSynchronous(this.flag) && !this.fs.metadata().synchronous) {
+        if (isSynchronous(this.flag)) {
             return this.sync();
         }
     }
@@ -266,7 +283,7 @@ export class PreloadFile extends File {
             const buf = new Uint8Array(len - this._buffer.length);
             // Write will set stats.size for us.
             this.writeSync(buf, 0, buf.length, this._buffer.length);
-            if (isSynchronous(this.flag) && this.fs.metadata().synchronous) {
+            if (isSynchronous(this.flag)) {
                 this.syncSync();
             }
             return;
@@ -274,7 +291,7 @@ export class PreloadFile extends File {
         this.stats.size = len;
         // Truncate buffer to 'len'.
         this._buffer = this._buffer.subarray(0, len);
-        if (isSynchronous(this.flag) && this.fs.metadata().synchronous) {
+        if (isSynchronous(this.flag)) {
             this.syncSync();
         }
     }
@@ -445,29 +462,6 @@ export class PreloadFile extends File {
         this.syncSync();
     }
 }
-/**
- * For synchronous file systems
- */
-export class SyncFile extends PreloadFile {
-    constructor(_fs, _path, _flag, _stat, contents) {
-        super(_fs, _path, _flag, _stat, contents);
-    }
-    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();
-    }
-}
 /**
  * For the filesystems which do not sync to anything..
  */

package/dist/filesystem.d.ts

@@ -1,7 +1,7 @@
 import { ApiError } from './ApiError.js';
 import type { Stats } from './stats.js';
-import type { File } from './file.js';
-import type { Cred } from './cred.js';
+import { type File } from './file.js';
+import { type Cred } from './cred.js';
 export type NoArgCallback = (e?: ApiError) => unknown;
 export type TwoArgCallback<T> = (e?: ApiError, rv?: T) => unknown;
 export type ThreeArgCallback<T, U> = (e?: ApiError, arg1?: T, arg2?: U) => unknown;
@@ -18,10 +18,6 @@ export interface FileSystemMetadata {
      * Wheter the FS is readonly or not
      */
     readonly: boolean;
-    /**
-     * Does the FS support synchronous operations
-     */
-    synchronous: boolean;
     /**
      * Does the FS support properties
      */
@@ -46,6 +42,9 @@ export interface FileSystemMetadata {
  * - All arguments are present. Any optional arguments at the Node API level have been passed in with their default values.
  */
 export declare abstract class FileSystem {
+    /**
+     * Get metadata about the current file syste,
+     */
     metadata(): FileSystemMetadata;
     constructor(options?: object);
     abstract ready(): Promise<this>;
@@ -178,8 +177,13 @@ export declare function Sync<T extends abstract new (...args: any[]) => FileSyst
 /**
  * @internal
  */
-declare abstract class AsyncFileSystem {
+declare abstract class AsyncFileSystem extends FileSystem {
+    /**
+     * @hidden
+     */
+    abstract _sync: FileSystem;
     metadata(): FileSystemMetadata;
+    ready(): Promise<this>;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
     statSync(path: string, cred: Cred): Stats;
     createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
@@ -191,11 +195,23 @@ declare abstract class AsyncFileSystem {
     linkSync(srcpath: string, dstpath: string, cred: Cred): void;
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }
+/**
+ * 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 declare function Async<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => AsyncFileSystem) & T;
 /**
  * @internal
  */
-declare abstract class ReadonlyFileSystem {
+declare abstract class ReadonlyFileSystem extends FileSystem {
     metadata(): FileSystemMetadata;
     rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;

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';

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';

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.6.0",
+	"version": "0.7.1",
 	"description": "A filesystem in your browser",
 	"main": "dist/index.js",
 	"types": "dist",

package/readme.md

@@ -8,14 +8,10 @@ ZenFS is a fork of [BrowserFS](https://github.com/jvilk/BrowserFS).
 
 ## Backends
 
-ZenFS is modular and extensible. The core includes a few built-in backends:
+ZenFS is modular and extensible. The core includes two built-in backends:
 
 -   `InMemory`: Stores files in-memory. This is cleared when the runtime ends (e.g. a user navigating away from a web page or a Node process exiting)
--   `Overlay`: Use read-only file system as read-write by overlaying a writable file system on top of it.
--   `AsyncMirror`: Use an asynchronous backend synchronously. This is very helpful for asynchronous backends
-
-> [!NOTE]
-> When constructed, `AsyncMirror` loads the entire contents of the async file system into a synchronous backend. It performs operations on the synchronous file system and then queues them to be mirrored onto the asynchronous backend.
+-   `Overlay`: Use read-only file system as read-write by overlaying a writable file system on top of it. ([copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write))
 
 ZenFS supports a number of other backends. Many are provided as separate packages under `@zenfs`. More backends can be defined by separate libraries by extending the `FileSystem` class and/or providing a `Backend` object.
 
@@ -74,13 +70,13 @@ await configure({
 > 2. An object that has the options accepted by the backend and a `backend` property which is a `Backend` object
 > 3. A `FileSystem` instance (_not recommended_)
 
-Here is an example that mounts the `Storage` backend from `@zenfs/dom` on `/`:
+Here is an example that mounts the `WebStorage` backend from `@zenfs/dom` on `/`:
 
 ```js
 import { configure, fs } from '@zenfs/core';
-import { Storage } from '@zenfs/dom';
+import { WebStorage } from '@zenfs/dom';
 
-await configure({ backend: Storage });
+await configure({ backend: WebStorage });
 
 if (!fs.existsSync('/test.txt')) {
 	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
@@ -95,50 +91,33 @@ console.log(contents);
 The FS promises API is exposed as `promises`.
 
 ```js
-import { configure, promises } from '@zenfs/core';
+import { configure } from '@zenfs/core';
+import { exists, writeFile } from '@zenfs/core/promises';
 import { IndexedDB } from '@zenfs/dom';
 
 await configure({ '/': IndexedDB });
 
-const exists = await promises.exists('/myfile.txt');
+const exists = await exists('/myfile.txt');
 if (!exists) {
-	await promises.write('/myfile.txt', 'Lots of persistant data');
+	await writeFile('/myfile.txt', 'Lots of persistant data');
 }
 ```
 
 > [!NOTE]
-> You can import the promises API using `promises`, or using `fs.promises` on the exported `fs`.
-
-> [!IMPORTANT]
-> ZenFS does _not_ provide a separate public import for importing promises like `fs/promises`. If you are using ESM, you can import promises functions like `fs/promises` from the `dist/emulation/promises.ts` file, though this may change at any time and is **not recommended**.
-
-#### Using asynchronous backends synchronously
-
-You may have noticed that attempting to use a synchronous function on an asynchronous backend (e.g. `IndexedDB`) results in a "not supplied" error (`ENOTSUP`). If you would like to use an asynchronous backend synchronously you need to wrap it in an `AsyncMirror`:
-
-```js
-import { configure, fs, AsyncMirror, InMemory } from '@zenfs/core';
-import { IndexedDB } from '@zenfs/dom';
-
-await configure({
-	'/': {
-		backend: AsyncMirror,
-		sync: InMemory,
-		async: IndexedDB,
-	},
-});
-
-fs.writeFileSync('/persistant.txt', 'My persistant data');
-```
+> You can import the promises API using:
+>
+> 1. Exports from `@zenfs/core/promises`
+> 2. The `promises` export from `@zenfs/core`
+> 3. `fs.promises` on the exported `fs` from `@zenfs/core`.
 
 #### Mounting and unmounting, creating backends
 
-If you would like to create backends without configure (e.g. to do something dynamic at runtime), you may do so by importing the backend and calling `createBackend` with it.
+If you would like to create backends without configure (e.g. to do something dynamic at runtime), you may do so by importing the backend and calling `resolveMountConfig` with it.
 
 You can then mount and unmount the backend instance by using `mount` and `umount`.
 
 ```js
-import { configure, createBackend, InMemory } from '@zenfs/core';
+import { configure, resolveMountConfig, InMemory } from '@zenfs/core';
 import { IndexedDB  } from '@zenfs/dom';
 import { Zip } from '@zenfs/zip';
 
@@ -150,8 +129,8 @@ await configure({
 fs.mkdirSync('/mnt');
 
 const res = await fetch('mydata.zip');
-const zipFs = await createBackend(Zip, { zipData: await res.arrayBuffer() });
-fs.mount('/mnt/zip', zipFs);
+const zipfs = await resolveMountConfig({ backend: Zip, zipData: await res.arrayBuffer() });
+fs.mount('/mnt/zip', zipfs);
 
 // do stuff with the mounted zip