@zenfs/core 0.3.0 → 0.3.2

package/dist/file.js

@@ -296,7 +296,7 @@ export class PreloadFile extends File {
      */
     truncate(len) {
         this.truncateSync(len);
-        if (this.flag.isSynchronous() && !this.fs.metadata.synchronous) {
+        if (this.flag.isSynchronous() && !this.fs.metadata().synchronous) {
             return this.sync();
         }
     }
@@ -314,7 +314,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 (this.flag.isSynchronous() && this.fs.metadata.synchronous) {
+            if (this.flag.isSynchronous() && this.fs.metadata().synchronous) {
                 this.syncSync();
             }
             return;
@@ -322,7 +322,7 @@ export class PreloadFile extends File {
         this.stats.size = len;
         // Truncate buffer to 'len'.
         this._buffer = this._buffer.subarray(0, len);
-        if (this.flag.isSynchronous() && this.fs.metadata.synchronous) {
+        if (this.flag.isSynchronous() && this.fs.metadata().synchronous) {
             this.syncSync();
         }
     }
@@ -441,7 +441,7 @@ export class PreloadFile extends File {
      * @param mode
      */
     chmodSync(mode) {
-        if (!this.fs.metadata.supportsProperties) {
+        if (!this.fs.metadata().supportsProperties) {
             throw new ApiError(ErrorCode.ENOTSUP);
         }
         this._dirty = true;
@@ -462,7 +462,7 @@ export class PreloadFile extends File {
      * @param gid
      */
     chownSync(uid, gid) {
-        if (!this.fs.metadata.supportsProperties) {
+        if (!this.fs.metadata().supportsProperties) {
             throw new ApiError(ErrorCode.ENOTSUP);
         }
         this._dirty = true;
@@ -473,7 +473,7 @@ export class PreloadFile extends File {
         this.utimesSync(atime, mtime);
     }
     utimesSync(atime, mtime) {
-        if (!this.fs.metadata.supportsProperties) {
+        if (!this.fs.metadata().supportsProperties) {
             throw new ApiError(ErrorCode.ENOTSUP);
         }
         this._dirty = true;

package/dist/filesystem.d.ts

@@ -46,7 +46,7 @@ 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(): FileSystemMetadata;
+    metadata(): FileSystemMetadata;
     constructor(options?: object);
     abstract ready(): Promise<this>;
     /**
@@ -154,15 +154,11 @@ export declare abstract class FileSystem {
     abstract syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }
 /**
- * Implements the asynchronous API in terms of the synchronous API.
- *
- * @example ```ts
- * class SyncFS extends Sync(FileSystem) {}
- * ```
+ * @internal
  */
-export declare function Sync<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => {
-    readonly metadata: FileSystemMetadata;
-    ready(): Promise<any>;
+declare abstract class SyncFileSystem extends FileSystem {
+    metadata(): FileSystemMetadata;
+    ready(): Promise<this>;
     exists(path: string, cred: Cred): Promise<boolean>;
     rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
     stat(path: string, cred: Cred): Promise<Stats>;
@@ -174,58 +170,16 @@ export declare function Sync<T extends abstract new (...args: any[]) => FileSyst
     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>;
-    /**
-     * Synchronous rename.
-     */
-    renameSync(oldPath: string, newPath: string, cred: Cred): void;
-    /**
-     * Synchronous `stat`.
-     */
-    statSync(path: string, cred: Cred): Stats;
-    /**
-     * Opens the file at path p with the given flag. The file must exist.
-     * @param p The path to open.
-     * @param flag The flag to use when opening the file.
-     * @return A File object corresponding to the opened file.
-     */
-    openFileSync(path: string, flag: FileFlag, cred: Cred): File;
-    /**
-     * Create the file at path p with the given mode. Then, open it with the given
-     * flag.
-     */
-    createFileSync(path: string, flag: FileFlag, mode: number, cred: Cred): File;
-    /**
-     * Synchronous `unlink`.
-     */
-    unlinkSync(path: string, cred: Cred): void;
-    /**
-     * Synchronous `rmdir`.
-     */
-    rmdirSync(path: string, cred: Cred): void;
-    /**
-     * Synchronous `mkdir`.
-     * @param mode Mode to make the directory using. Can be ignored if
-     *   the filesystem doesn't support permissions.
-     */
-    mkdirSync(path: string, mode: number, cred: Cred): void;
-    /**
-     * Synchronous `readdir`. Reads the contents of a directory.
-     */
-    readdirSync(path: string, cred: Cred): string[];
-    /**
-     * Test whether or not the given path exists by checking with the file system.
-     */
-    existsSync(path: string, cred: Cred): boolean;
-    /**
-     * Synchronous `link`.
-     */
-    linkSync(srcpath: string, dstpath: string, cred: Cred): void;
-    /**
-     * Synchronize the data and stats for path synchronously
-     */
-    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
-}) & T;
-export declare function Async<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => {
+}
+/**
+ * Implements the asynchronous API in terms of the synchronous API.
+ */
+export declare function Sync<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => SyncFileSystem) & T;
+/**
+ * @internal
+ */
+declare abstract class AsyncFileSystem {
+    metadata(): FileSystemMetadata;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
     statSync(path: string, cred: Cred): Stats;
     createFileSync(path: string, flag: FileFlag, mode: number, cred: Cred): File;
@@ -236,67 +190,13 @@ export declare function Async<T extends abstract new (...args: any[]) => FileSys
     readdirSync(path: string, cred: Cred): string[];
     linkSync(srcpath: string, dstpath: string, cred: Cred): void;
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
-    readonly metadata: FileSystemMetadata;
-    ready(): Promise<any>;
-    /**
-     * Asynchronous rename. No arguments other than a possible exception
-     * are given to the completion callback.
-     */
-    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
-    /**
-     * Asynchronous `stat`.
-     */
-    stat(path: string, cred: Cred): Promise<Stats>;
-    /**
-     * Opens the file at path p with the given flag. The file must exist.
-     * @param p The path to open.
-     * @param flag The flag to use when opening the file.
-     */
-    openFile(path: string, flag: FileFlag, cred: Cred): Promise<File>;
-    /**
-     * Create the file at path p with the given mode. Then, open it with the given
-     * flag.
-     */
-    createFile(path: string, flag: FileFlag, mode: number, cred: Cred): Promise<File>;
-    /**
-     * Asynchronous `unlink`.
-     */
-    unlink(path: string, cred: Cred): Promise<void>;
-    /**
-     * Asynchronous `rmdir`.
-     */
-    rmdir(path: string, cred: Cred): Promise<void>;
-    /**
-     * Asynchronous `mkdir`.
-     * @param mode Mode to make the directory using. Can be ignored if
-     *   the filesystem doesn't support permissions.
-     */
-    mkdir(path: string, mode: number, cred: Cred): Promise<void>;
-    /**
-     * Asynchronous `readdir`. Reads the contents of a directory.
-     *
-     * The callback gets two arguments `(err, files)` where `files` is an array of
-     * the names of the files in the directory excluding `'.'` and `'..'`.
-     */
-    readdir(path: string, cred: Cred): Promise<string[]>;
-    /**
-     * Test whether or not the given path exists by checking with the file system.
-     */
-    exists(path: string, cred: Cred): Promise<boolean>;
-    /**
-     * Test whether or not the given path exists by checking with the file system.
-     */
-    existsSync(path: string, cred: Cred): boolean;
-    /**
-     * Asynchronous `link`.
-     */
-    link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
-    /**
-     * Synchronize the data and stats for path asynchronously
-     */
-    sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
-}) & T;
-export declare function Readonly<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => {
+}
+export declare function Async<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => AsyncFileSystem) & T;
+/**
+ * @internal
+ */
+declare abstract class ReadonlyFileSystem {
+    metadata(): FileSystemMetadata;
     rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
     createFile(path: string, flag: FileFlag, mode: number, cred: Cred): Promise<File>;
@@ -311,46 +211,6 @@ export declare function Readonly<T extends abstract new (...args: any[]) => File
     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;
-    readonly metadata: FileSystemMetadata;
-    ready(): Promise<any>;
-    /**
-     * Asynchronous `stat`.
-     */
-    stat(path: string, cred: Cred): Promise<Stats>;
-    /**
-     * Synchronous `stat`.
-     */
-    statSync(path: string, cred: Cred): Stats;
-    /**
-     * Opens the file at path p with the given flag. The file must exist.
-     * @param p The path to open.
-     * @param flag The flag to use when opening the file.
-     */
-    openFile(path: string, flag: FileFlag, cred: Cred): Promise<File>;
-    /**
-     * Opens the file at path p with the given flag. The file must exist.
-     * @param p The path to open.
-     * @param flag The flag to use when opening the file.
-     * @return A File object corresponding to the opened file.
-     */
-    openFileSync(path: string, flag: FileFlag, cred: Cred): File;
-    /**
-     * Asynchronous `readdir`. Reads the contents of a directory.
-     *
-     * The callback gets two arguments `(err, files)` where `files` is an array of
-     * the names of the files in the directory excluding `'.'` and `'..'`.
-     */
-    readdir(path: string, cred: Cred): Promise<string[]>;
-    /**
-     * Synchronous `readdir`. Reads the contents of a directory.
-     */
-    readdirSync(path: string, cred: Cred): string[];
-    /**
-     * Test whether or not the given path exists by checking with the file system.
-     */
-    exists(path: string, cred: Cred): Promise<boolean>;
-    /**
-     * Test whether or not the given path exists by checking with the file system.
-     */
-    existsSync(path: string, cred: Cred): boolean;
-}) & T;
+}
+export declare function Readonly<T extends abstract new (...args: any[]) => FileSystem>(FS: T): (abstract new (...args: any[]) => ReadonlyFileSystem) & T;
+export {};

package/dist/filesystem.js

@@ -10,7 +10,7 @@ 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() {
+    metadata() {
         return {
             name: this.constructor.name,
             readonly: false,
@@ -51,18 +51,14 @@ export class FileSystem {
 }
 /**
  * Implements the asynchronous API in terms of the synchronous API.
- *
- * @example ```ts
- * class SyncFS extends Sync(FileSystem) {}
- * ```
  */
 export function Sync(FS) {
     /**
      * Implements the asynchronous API in terms of the synchronous API.
      */
-    class SyncFileSystem extends FS {
-        get metadata() {
-            return { ...super.metadata, synchronous: true };
+    class _SyncFileSystem extends FS {
+        metadata() {
+            return { ...super.metadata(), synchronous: true };
         }
         async ready() {
             return this;
@@ -101,10 +97,13 @@ export function Sync(FS) {
             return this.syncSync(path, data, stats);
         }
     }
-    return SyncFileSystem;
+    return _SyncFileSystem;
 }
 export function Async(FS) {
-    class AsyncFileSystem extends FS {
+    class _AsyncFileSystem extends FS {
+        metadata() {
+            return { ...super.metadata(), synchronous: false };
+        }
         /* eslint-disable @typescript-eslint/no-unused-vars */
         renameSync(oldPath, newPath, cred) {
             throw new ApiError(ErrorCode.ENOTSUP);
@@ -138,10 +137,13 @@ export function Async(FS) {
         }
     }
     /* eslint-enable @typescript-eslint/no-unused-vars */
-    return AsyncFileSystem;
+    return _AsyncFileSystem;
 }
 export function Readonly(FS) {
-    class ReadonlyFileSystem extends FS {
+    class _ReadonlyFileSystem extends FS {
+        metadata() {
+            return { ...super.metadata(), readonly: true };
+        }
         /* eslint-disable @typescript-eslint/no-unused-vars */
         async rename(oldPath, newPath, cred) {
             throw new ApiError(ErrorCode.EROFS);
@@ -186,5 +188,5 @@ export function Readonly(FS) {
             throw new ApiError(ErrorCode.EROFS);
         }
     }
-    return ReadonlyFileSystem;
+    return _ReadonlyFileSystem;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenfs/core",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A filesystem in your browser",
   "main": "dist/index.js",
   "types": "dist",

package/readme.md

@@ -4,14 +4,16 @@ ZenFS is an in-browser file system that emulates the [Node JS file system API](h
 
 ## Backends
 
-ZenFS is highly extensible, and includes many builtin filesystem backends:
+ZenFS is highly extensible, and includes a few built-in backends:
 
 -   `InMemory`: Stores files in-memory. It is a temporary file store that clears when the user navigates away.
 -   `Overlay`: Mount a read-only file system as read-write by overlaying a writable file system on top of it. Like Docker's overlayfs, it will only write changed files to the writable file system.
 -   `AsyncMirror`: Use an asynchronous backend synchronously. Invaluable for Emscripten; let your Emscripten applications write to larger file stores with no additional effort!
-    -   `AsyncMirror` loads the entire contents of the async file system into a synchronous backend during construction. It performs operations synchronous file system and then queues them to be mirrored onto the asynchronous backend.
 
-More backends can be defined by separate libraries, so long as they extend they implement `ZenFS.FileSystem`. Multiple backends can be active at once at different locations in the directory hierarchy.
+> [!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.
+
+More backends can be defined by separate libraries, as long as they implement `FileSystem`.
 
 ZenFS supports a number of other backends (many are provided as seperate packages under `@zenfs`).
 
@@ -25,7 +27,8 @@ npm install @zenfs/core
 
 ## Usage
 
-> 🛈 The examples are written in ESM. If you are using CJS, you can `require` the package. If running in a browser you can add a script tag to your HTML pointing to the `browser.min.js` and use ZenFS via the global `ZenFS` object.
+> [!NOTE]
+> The examples are written in ESM. If you are using CJS, you can `require` the package. If running in a browser you can add a script tag to your HTML pointing to the `browser.min.js` and use ZenFS via the global `ZenFS` object.
 
 ```js
 import fs from '@zenfs/core';
@@ -36,27 +39,15 @@ const contents = fs.readFileSync('/test.txt', 'utf-8');
 console.log(contents);
 ```
 
-#### Using different backends
+#### Using different and/or different backends
 
-A `InMemory` backend is created by default. If you would like to use a different one, you must configure ZenFS. It is recommended to do so using the `configure` function. Here is an example using the `Storage` backend from `@zenfs/dom`:
+A single `InMemory` backend is created by default, mounted on `/`.
 
-```js
-import { configure, fs } from '@zenfs/core';
-import { StorageStore } from '@zenfs/dom';
+You can configure ZenFS to use a different backend and mount multiple backends. It is strongly recommended to do so using the `configure` function.
 
-await configure({ backend: StorageStore });
+You can use multiple backends by passing an object to `configure` which maps paths to file systems.
 
-if (!fs.existsSync('/test.txt')) {
-	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
-}
-
-const contents = fs.readFileSync('/test.txt', 'utf-8');
-console.log(contents);
-```
-
-#### Using multiple backends
-
-You can use multiple backends by passing an object to `configure` which maps paths to file systems. The following example mounts a zip file to `/zip`, in-memory storage to `/tmp`, and IndexedDB storage to `/home` (note that `/` has the default in-memory backend):
+The following example mounts a zip file to `/zip`, in-memory storage to `/tmp`, and IndexedDB to `/home`. Note that `/` has the default in-memory backend.
 
 ```js
 import { configure } from '@zenfs/core';
@@ -66,16 +57,32 @@ import { Zip } from '@zenfs/zip';
 const zipData = await (await fetch('mydata.zip')).arrayBuffer();
 
 await configure({
-	'/mnt/zip': {
-		backend: Zip,
-		zipData: zipData,
-	},
+	'/mnt/zip': { backend: Zip, zipData },
 	'/tmp': 'InMemory',
 	'/home': IndexedDB,
 };
 ```
 
-#### FS Promises API
+> [!TIP]
+> When configuring a mount point, you can pass in 1. A string that maps to a built-in backend 2. A `Backend` object, if the backend has no required options 3. An object that has a `backend` property which is a `Backend` or a string that maps to a built-in backend and the options accepted by the backend
+
+Here is an example that mounts the `Storage` backend from `@zenfs/dom` on `/`:
+
+```js
+import { configure, fs } from '@zenfs/core';
+import { Storage } from '@zenfs/dom';
+
+await configure({ backend: Storage });
+
+if (!fs.existsSync('/test.txt')) {
+	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
+}
+
+const contents = fs.readFileSync('/test.txt', 'utf-8');
+console.log(contents);
+```
+
+#### FS Promises
 
 The FS promises API is exposed as `promises`.
 
@@ -91,11 +98,15 @@ if (!exists) {
 }
 ```
 
-ZenFS does _not_ provide a seperate public import for importing promises in its built form. If you are using ESM, you can import promises functions from `dist/emulation/promises`, though this may change at any time and is not recommended.
+> [!NOTE]
+> You can import the promises API using `promises`, or using `fs.promises` on the exported `fs`.
+
+> [!IMPORTANT]
+> ZenFS does _not_ provide a seperate 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 wish to use an asynchronous backend synchronously you need to wrap it in an `AsyncMirror`:
+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 } from '@zenfs/core';
@@ -109,55 +120,23 @@ await configure({
 	},
 });
 
-fs.writeFileSync('/persistant.txt', 'My persistant data'); // This fails if you configure with only IndexedDB
+fs.writeFileSync('/persistant.txt', 'My persistant data');
 ```
 
-### Advanced usage
+#### Mounting and unmounting, creating backends
 
-#### 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, you may do so by importing the backend and calling `createBackend` with it. You can import the backend directly or with `backends`:
-
-```js
-import { configure, backends, InMemory } from '@zenfs/core';
-
-console.log(backends.InMemory === InMemory); // they are the same
-
-const internalInMemoryFS = await createBackend(InMemory);
-```
-
-> ⚠ Instances of backends follow the **_internal_** ZenFS API. You should never use a backend's methods unless you are extending a backend.
-
-```js
-import { configure, InMemory } from '@zenfs/core';
-
-const internalInMemoryFS = new InMemory();
-await internalInMemoryFS.ready();
-```
-
-#### Mounting
-
-If you would like to mount and unmount backends, you can do so using the `mount` and `umount` functions:
-
-```js
-import { fs, InMemory } from '@zenfs/core';
-
-const internalInMemoryFS = await createBackend(InMemory); // create an FS instance
-
-fs.mount('/tmp', internalInMemoryFS); // mount
-
-fs.umount('/tmp'); // unmount /tmp
-```
-
-This could be used in the "multiple backends" example like so:
+You can then mount and unmount the backend instance by using `mount` and `umount`.
 
 ```js
+import { configure, createBackend } from '@zenfs/core';
 import { IndexedDB  } from '@zenfs/dom';
 import { Zip } from '@zenfs/zip';
 
 await configure({
 	'/tmp': 'InMemory',
-	'/home': 'IndexedDB',
+	'/home': IndexedDB,
 };
 
 fs.mkdirSync('/mnt');
@@ -171,6 +150,9 @@ fs.mount('/mnt/zip', zipFs);
 fs.umount('/mnt/zip'); // finished using the zip
 ```
 
+> [!WARNING]
+> Instances of backends follow the **internal** ZenFS API. You should never use a backend's methods unless you are extending a backend.
+
 ## Using with bundlers
 
 ZenFS exports a drop-in for Node's `fs` module (up to the version of `@types/node` in package.json), so you can use it for your bundler of preference using the default export.
@@ -185,7 +167,3 @@ ZenFS exports a drop-in for Node's `fs` module (up to the version of `@types/nod
 ### Testing
 
 Run unit tests with `npm test`.
-
-### License
-
-ZenFS is licensed under the MIT License.

package/dist/backends/FolderAdapter.d.ts

@@ -1,52 +0,0 @@
-import { BaseFileSystem, type FileSystem } from '../filesystem.js';
-import { type BackendOptions } from './backend.js';
-export declare namespace FolderAdapter {
-    /**
-     * Configuration options for a FolderAdapter file system.
-     */
-    interface Options {
-        folder: string;
-        wrapped: FileSystem;
-    }
-}
-/**
- * The FolderAdapter file system wraps a file system, and scopes all interactions to a subfolder of that file system.
- *
- * Example: Given a file system `foo` with folder `bar` and file `bar/baz`...
- *
- * ```javascript
- * ZenFS.configure({
- *   fs: "FolderAdapter",
- *   options: {
- *     folder: "bar",
- *     wrapped: foo
- *   }
- * }, function(e) {
- *   var fs = ZenFS.BFSRequire('fs');
- *   fs.readdirSync('/'); // ['baz']
- * });
- * ```
- */
-export declare class FolderAdapter extends BaseFileSystem {
-    static readonly Name = "FolderAdapter";
-    static Create: any;
-    static readonly Options: BackendOptions;
-    static isAvailable(): boolean;
-    _wrapped: FileSystem;
-    _folder: string;
-    constructor({ folder, wrapped }: FolderAdapter.Options);
-    get metadata(): {
-        supportsLinks: boolean;
-        name: string;
-        readonly: boolean;
-        synchronous: boolean;
-        supportsProperties: boolean;
-        totalSpace: number;
-        freeSpace: number;
-    };
-    /**
-     * Initialize the file system. Ensures that the wrapped file system
-     * has the given folder.
-     */
-    private _initialize;
-}