@zenfs/core 0.2.1 → 0.2.2

package/dist/emulation/index.d.ts

@@ -4,5 +4,5 @@ export * as promises from './promises.js';
 export * as constants from './constants.js';
 export * from './streams.js';
 export * from './dir.js';
-export { initialize, getMount, getMounts, mount, umount, _toUnixTimestamp } from './shared.js';
+export { initialize, mounts, mount, umount, _toUnixTimestamp } from './shared.js';
 export { Stats, BigIntStats } from '../stats.js';

package/dist/emulation/index.js

@@ -4,5 +4,5 @@ export * as promises from './promises.js';
 export * as constants from './constants.js';
 export * from './streams.js';
 export * from './dir.js';
-export { initialize, getMount, getMounts, mount, umount, _toUnixTimestamp } from './shared.js';
+export { initialize, mounts, mount, umount, _toUnixTimestamp } from './shared.js';
 export { Stats, BigIntStats } from '../stats.js';

package/dist/emulation/shared.d.ts

@@ -5,16 +5,38 @@ import type { File } from '../file.js';
 /**
  * converts Date or number to a integer UNIX timestamp
  * Grabbed from NodeJS sources (lib/fs.js)
+ *
+ * @internal
  */
 export declare function _toUnixTimestamp(time: Date | number): number;
+/**
+ * Normalizes a mode
+ * @internal
+ */
 export declare function normalizeMode(mode: string | number | unknown, def?: number): number;
+/**
+ * Normalizes a time
+ * @internal
+ */
 export declare function normalizeTime(time: string | number | Date): Date;
+/**
+ * Normalizes a path
+ * @internal
+ */
 export declare function normalizePath(p: string): string;
-export declare function normalizeOptions(options: any, defEnc: string | null, defFlag: string, defMode: number | null): {
+/**
+ * Normalizes options
+ * @internal
+ */
+export declare function normalizeOptions(options: unknown, defEnc: string | null, defFlag: string, defMode: number | null): {
     encoding: BufferEncoding;
     flag: string;
     mode: number;
 };
+/**
+ * Do nothing
+ * @internal
+ */
 export declare function nop(): void;
 export declare let cred: Cred;
 export declare function setCred(val: Cred): void;
@@ -24,15 +46,11 @@ export declare function fd2file(fd: number): File;
 export interface MountMapping {
     [point: string]: FileSystem;
 }
-export declare const mounts: Map<string, FileSystem>;
-/**
- * Gets the file system mounted at `mountPoint`
- */
-export declare function getMount(mountPoint: string): FileSystem;
 /**
- * Gets an object of mount points (keys) and filesystems (values)
+ * The map of mount points
+ * @internal
  */
-export declare function getMounts(): MountMapping;
+export declare const mounts: Map<string, FileSystem>;
 /**
  * Mounts the file system at the given mount point.
  */

package/dist/emulation/shared.js

@@ -6,6 +6,8 @@ import { InMemory } from '../backends/InMemory.js';
 /**
  * converts Date or number to a integer UNIX timestamp
  * Grabbed from NodeJS sources (lib/fs.js)
+ *
+ * @internal
  */
 export function _toUnixTimestamp(time) {
     if (typeof time === 'number') {
@@ -16,6 +18,10 @@ export function _toUnixTimestamp(time) {
     }
     throw new Error('Cannot parse time: ' + time);
 }
+/**
+ * Normalizes a mode
+ * @internal
+ */
 export function normalizeMode(mode, def) {
     switch (typeof mode) {
         case 'number':
@@ -33,6 +39,10 @@ export function normalizeMode(mode, def) {
     }
     throw new ApiError(ErrorCode.EINVAL, 'Invalid mode: ' + mode?.toString());
 }
+/**
+ * Normalizes a time
+ * @internal
+ */
 export function normalizeTime(time) {
     if (time instanceof Date) {
         return time;
@@ -45,6 +55,10 @@ export function normalizeTime(time) {
     }
     throw new ApiError(ErrorCode.EINVAL, 'Invalid time.');
 }
+/**
+ * Normalizes a path
+ * @internal
+ */
 export function normalizePath(p) {
     // Node doesn't allow null characters in paths.
     if (p.indexOf('\u0000') >= 0) {
@@ -56,6 +70,10 @@ export function normalizePath(p) {
     p = p.replaceAll(/\/+/g, '/');
     return resolve(p);
 }
+/**
+ * Normalizes options
+ * @internal
+ */
 export function normalizeOptions(options, defEnc, defFlag, defMode) {
     // typeof null === 'object' so special-case handing is needed.
     switch (options === null ? 'null' : typeof options) {
@@ -83,6 +101,10 @@ export function normalizeOptions(options, defEnc, defFlag, defMode) {
             throw new TypeError(`"options" must be a string or an object, got ${typeof options} instead.`);
     }
 }
+/**
+ * Do nothing
+ * @internal
+ */
 export function nop() {
     // do nothing
 }
@@ -105,23 +127,15 @@ export function fd2file(fd) {
     }
     return fdMap.get(fd);
 }
+/**
+ * The map of mount points
+ * @internal
+ */
 export const mounts = new Map();
 /*
 Set a default root.
 */
 mount('/', InMemory.create({ name: 'root' }));
-/**
- * Gets the file system mounted at `mountPoint`
- */
-export function getMount(mountPoint) {
-    return mounts.get(mountPoint);
-}
-/**
- * Gets an object of mount points (keys) and filesystems (values)
- */
-export function getMounts() {
-    return Object.fromEntries(mounts.entries());
-}
 /**
  * Mounts the file system at the given mount point.
  */

package/dist/filesystem.d.ts

@@ -171,6 +171,15 @@ export declare abstract class SyncFileSystem extends FileSystem {
     link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
     sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
 }
+export declare abstract class ReadonlySyncFileSystem extends SyncFileSystem {
+    renameSync(oldPath: string, newPath: string, cred: Cred): void;
+    createFileSync(path: string, flag: FileFlag, 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;
+    linkSync(srcpath: string, dstpath: string, cred: Cred): void;
+    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+}
 export declare abstract class AsyncFileSystem extends FileSystem {
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
     statSync(path: string, cred: Cred): Stats;
@@ -184,3 +193,12 @@ export declare abstract class AsyncFileSystem extends FileSystem {
     linkSync(srcpath: string, dstpath: string, cred: Cred): void;
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
 }
+export declare abstract class ReadonlyAsyncFileSystem extends AsyncFileSystem {
+    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
+    createFile(path: string, flag: FileFlag, mode: number, 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>;
+    link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
+    sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
+}

package/dist/filesystem.js

@@ -94,6 +94,29 @@ export class SyncFileSystem extends FileSystem {
         return this.syncSync(path, data, stats);
     }
 }
+export class ReadonlySyncFileSystem extends SyncFileSystem {
+    renameSync(oldPath, newPath, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    createFileSync(path, flag, mode, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    unlinkSync(path, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    rmdirSync(path, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    mkdirSync(path, mode, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    linkSync(srcpath, dstpath, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    syncSync(path, data, stats) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+}
 export class AsyncFileSystem extends FileSystem {
     renameSync(oldPath, newPath, cred) {
         throw new ApiError(ErrorCode.ENOTSUP);
@@ -129,3 +152,26 @@ export class AsyncFileSystem extends FileSystem {
         throw new ApiError(ErrorCode.ENOTSUP);
     }
 }
+export class ReadonlyAsyncFileSystem extends AsyncFileSystem {
+    async rename(oldPath, newPath, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    async createFile(path, flag, mode, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    async unlink(path, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    async rmdir(path, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    async mkdir(path, mode, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    async link(srcpath, dstpath, cred) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+    async sync(path, data, stats) {
+        throw new ApiError(ErrorCode.EROFS);
+    }
+}

package/dist/index.d.ts

@@ -31,7 +31,6 @@ export * from './backends/AsyncStore.js';
 export * from './backends/SyncStore.js';
 export * from './ApiError.js';
 export * from './cred.js';
-export * from './FileIndex.js';
 export * from './file.js';
 export * from './filesystem.js';
 export * from './inode.js';

package/dist/index.js

@@ -12,7 +12,7 @@ import { setCred } from './emulation/shared.js';
  */
 export function initialize(mounts, uid = 0, gid = 0) {
     setCred(new Cred(uid, gid, uid, gid, uid, gid));
-    return fs.initialize(mounts);
+    fs.initialize(mounts);
 }
 /**
  * Creates filesystems with the given configuration, and initializes ZenFS with it.
@@ -39,14 +39,13 @@ export async function configure(config) {
         }
         config[point] = await resolveBackendConfig(value);
     }
-    return initialize(config);
+    initialize(config);
 }
 export * from './backends/index.js';
 export * from './backends/AsyncStore.js';
 export * from './backends/SyncStore.js';
 export * from './ApiError.js';
 export * from './cred.js';
-export * from './FileIndex.js';
 export * from './file.js';
 export * from './filesystem.js';
 export * from './inode.js';

package/dist/utils.d.ts

@@ -1,8 +1,5 @@
 /// <reference types="node" resolution-mode="require"/>
 /// <reference types="node" resolution-mode="require"/>
-/**
- * Grab bag of utility functions used across the code.
- */
 import { FileSystem } from './filesystem.js';
 import { Cred } from './cred.js';
 import type { TextDecoder as _TextDecoder, TextEncoder as _TextEncoder } from 'node:util';

package/package.json

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

package/readme.md

@@ -7,14 +7,13 @@ ZenFS is an in-browser file system that emulates the [Node JS file system API](h
 ZenFS is highly extensible, and includes many builtin filesystem backends:
 
 -   `InMemory`: Stores files in-memory. It is a temporary file store that clears when the user navigates away.
--   `OverlayFS`: 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.
+-   `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.
--   `FolderAdapter`: Wraps a file system, and scopes all interactions to a subfolder of that file system.
 
 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.
 
-ZenFS supports a number of other backends (as `@zenfs/fs-[name]`).
+ZenFS supports a number of other backends (many are provided as seperate packages under `@zenfs`).
 
 For more information, see the [API documentation for ZenFS](https://zen-fs.github.io/core).
 
@@ -24,13 +23,6 @@ For more information, see the [API documentation for ZenFS](https://zen-fs.githu
 npm install @zenfs/core
 ```
 
-## Building
-
--   Make sure you have Node and NPM installed. You must have Node v18 or newer.
--   Install dependencies with `npm install`
--   Build using `npm run build`
--   You can find the built code in `dist`.
-
 ## 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.
@@ -46,15 +38,13 @@ console.log(contents);
 
 #### Using 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/fs-dom`:
+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`:
 
 ```js
-import { configure, fs, registerBackend } from '@zenfs/core';
-import { StorageFileSystem } from '@zenfs/fs-dom';
-registerBackend(StorageFileSystem);
+import { configure, fs } from '@zenfs/core';
+import { StorageStore } from '@zenfs/dom';
 
-// you can also add a callback as the last parameter instead of using promises
-await configure({ fs: 'Storage' });
+await configure({ backend: StorageStore });
 
 if (!fs.existsSync('/test.txt')) {
 	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
@@ -69,23 +59,19 @@ console.log(contents);
 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):
 
 ```js
-import { configure, registerBackend } from '@zenfs/core';
-import { IndexedDBFileSystem } from '@zenfs/fs-dom';
-import { ZipFS } from '@zenfs/fs-zip';
-import Buffer from 'buffer';
-registerBackend(IndexedDBFileSystem, ZipFS);
+import { configure } from '@zenfs/core';
+import { IndexedDB } from '@zenfs/dom';
+import { Zip } from '@zenfs/zip';
 
 const zipData = await (await fetch('mydata.zip')).arrayBuffer();
 
 await configure({
 	'/mnt/zip': {
-		fs: 'ZipFS',
-		options: {
-			zipData: Buffer.from(zipData)
-		}
+		backend: Zip,
+		zipData: zipData,
 	},
 	'/tmp': 'InMemory',
-	'/home': 'IndexedDB',
+	'/home': IndexedDB,
 };
 ```
 
@@ -94,11 +80,10 @@ await configure({
 The FS promises API is exposed as `promises`.
 
 ```js
-import { configure, promises, registerBackend } from '@zenfs/core';
-import { IndexedDBFileSystem } from '@zenfs/fs-dom';
-registerBackend(IndexedDBFileSystem);
+import { configure, promises } from '@zenfs/core';
+import { IndexedDB } from '@zenfs/dom';
 
-await configure({ '/': 'IndexedDB' });
+await configure({ '/': IndexedDB });
 
 const exists = await promises.exists('/myfile.txt');
 if (!exists) {
@@ -106,46 +91,48 @@ if (!exists) {
 }
 ```
 
-ZenFS does _not_ provide a seperate method for importing promises in its built form. If you are using Typescript, you can import the promises API from source code (perhaps to reduce you bundle size). Doing so it not recommended as the files may be moved without notice.
+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.
 
 #### Using asynchronous backends synchronously
 
-You may have noticed that attempting to use a synchronous method 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 wish to use an asynchronous backend synchronously you need to wrap it in an `AsyncMirror`:
 
 ```js
 import { configure, fs } from '@zenfs/core';
-import { IndexedDBFileSystem } from '@zenfs/fs-dom';
-registerBackend(IndexedDBFileSystem);
+import { IndexedDB } from '@zenfs/dom';
 
 await configure({
-	'/': { fs: 'AsyncMirror', options: { sync: { fs: 'InMemory' }, async: { fs: 'IndexedDB' } } }
+	'/': {
+		backend: 'AsyncMirror',
+		sync: 'InMemory',
+		async: IndexedDB,
+	},
 });
 
-fs.writeFileSync('/persistant.txt', 'My persistant data'); // This fails if you configure the FS as IndexedDB
+fs.writeFileSync('/persistant.txt', 'My persistant data'); // This fails if you configure with only IndexedDB
 ```
 
 ### Advanced usage
 
 #### Creating backends
 
-If you would like to create backends without configure, you may do so by importing the backend's class and calling its `Create` method. You can import the backend directly or with `backends`:
+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
+console.log(backends.InMemory === InMemory); // they are the same
 
-const inMemoryFS = await InMemory.Create();
+const internalInMemoryFS = await createBackend(InMemory);
 ```
 
-> ⚠ Instances of backends follow the ***internal*** ZenFS API. You should never use a backend's method unless you are extending a backend.
+> ⚠ Instances of backends follow the **_internal_** ZenFS API. You should never use a backend's methods unless you are extending a backend.
 
-Coming soon:
 ```js
 import { configure, InMemory } from '@zenfs/core';
 
-const inMemoryFS = new InMemory();
-await inMemoryFS.whenReady();
+const internalInMemoryFS = new InMemory();
+await internalInMemoryFS.ready();
 ```
 
 #### Mounting
@@ -155,9 +142,9 @@ If you would like to mount and unmount backends, you can do so using the `mount`
 ```js
 import { fs, InMemory } from '@zenfs/core';
 
-const inMemoryFS = await InMemory.Create(); // create an FS instance
+const internalInMemoryFS = await createBackend(InMemory); // create an FS instance
 
-fs.mount('/tmp', inMemoryFS); // mount
+fs.mount('/tmp', internalInMemoryFS); // mount
 
 fs.umount('/tmp'); // unmount /tmp
 ```
@@ -165,10 +152,8 @@ fs.umount('/tmp'); // unmount /tmp
 This could be used in the "multiple backends" example like so:
 
 ```js
-import { IndexedDBFileSystem } from '@zenfs/fs-dom';
-import { ZipFS } from '@zenfs/fs-zip';
-import Buffer from 'buffer';
-registerBackend(IndexedDBFileSystem);
+import { IndexedDB  } from '@zenfs/dom';
+import { Zip } from '@zenfs/zip';
 
 await configure({
 	'/tmp': 'InMemory',
@@ -178,8 +163,7 @@ await configure({
 fs.mkdirSync('/mnt');
 
 const res = await fetch('mydata.zip');
-const zipData = Buffer.from(await res.arrayBuffer());
-const zipFs = await ZipFS.Create({ zipData });
+const zipFs = await createBackend(Zip, { zipData: await res.arrayBuffer() });
 fs.mount('/mnt/zip', zipFs);
 
 // do stuff with the mounted zip
@@ -191,64 +175,12 @@ fs.umount('/mnt/zip'); // finished using the zip
 
 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.
 
-#### ESBuild
-
-tsconfig.json
-
-```json
-{
-	...
-	"paths": {
-		"fs": ["node_modules/zenfs/dist/index.js"]
-	}
-	...
-}
-```
-
-[Why tsconfig.json?](https://stackoverflow.com/a/71935037/17637456)
-
-Webpack:
-
-```js
-module.exports = {
-	// ...
-	resolve: {
-		alias: {
-			fs: require.resolve('zenfs'),
-		},
-	},
-	// ...
-};
-```
-
-Rollup:
-
-```js
-import alias from '@rollup/plugin-alias';
-
-export default {
-	// ...
-	plugins: [
-		alias({
-			entries: [{ find: 'fs', replacement: 'zenfs' }],
-		}),
-	],
-	// ...
-};
-```
-
-## Using with Emscripten
-
-You can use any _synchronous_ ZenFS file systems with Emscripten.
-
-```js
-import { EmscriptenFSPlugin } from '@zenfs/fs-emscripten';
-const BFS = new EmscriptenFSPlugin(); // Create a ZenFS Emscripten FS plugin.
-FS.createFolder(FS.root, 'data', true, true); // Create the folder to turn into a mount point.
-FS.mount(BFS, { root: '/' }, '/data'); // Mount BFS's root folder into /data.
-```
+## Building
 
-If you want to use an asynchronous backend, you must wrap it in an `AsyncMirror`.
+-   Make sure you have Node and NPM installed. You must have Node v18 or newer.
+-   Install dependencies with `npm install`
+-   Build using `npm run build`
+-   You can find the built code in `dist`.
 
 ### Testing