@zenfs/core 0.4.0 → 0.4.2

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+import type { Backend, BackendConfig } from './backends/backend.js';
+import { FileSystem } from './filesystem.js';
+/**
+ * Initializes ZenFS with the given file systems.
+ */
+export declare function initialize(mounts: {
+    [point: string]: FileSystem;
+}, uid?: number, gid?: number): void;
+/**
+ * Defines a mapping of mount points to their configurations
+ */
+export interface ConfigMapping {
+    [mountPoint: string]: FileSystem | BackendConfig | Backend;
+}
+/**
+ * A configuration for ZenFS
+ */
+export type Configuration = FileSystem | BackendConfig | ConfigMapping;
+/**
+ * Creates filesystems with the given configuration, and initializes ZenFS with it.
+ * See the Configuration type for more info on the configuration object.
+ */
+export declare function configure(config: Configuration): Promise<void>;

package/dist/config.js

@@ -0,0 +1,36 @@
+import { isBackend, resolveBackendConfig } from './backends/backend.js';
+import { Cred } from './cred.js';
+import * as fs from './emulation/index.js';
+import { setCred } from './emulation/shared.js';
+import { FileSystem } from './filesystem.js';
+/**
+ * Initializes ZenFS with the given file systems.
+ */
+export function initialize(mounts, uid = 0, gid = 0) {
+    setCred(new Cred(uid, gid, uid, gid, uid, gid));
+    fs.initialize(mounts);
+}
+/**
+ * Creates filesystems with the given configuration, and initializes ZenFS with it.
+ * See the Configuration type for more info on the configuration object.
+ */
+export async function configure(config) {
+    if ('backend' in config || config instanceof FileSystem) {
+        // single FS
+        config = { '/': config };
+    }
+    for (let [point, value] of Object.entries(config)) {
+        if (typeof value == 'number') {
+            //should never happen
+            continue;
+        }
+        if (value instanceof FileSystem) {
+            continue;
+        }
+        if (isBackend(value)) {
+            value = { backend: value };
+        }
+        config[point] = await resolveBackendConfig(value);
+    }
+    initialize(config);
+}

package/dist/index.d.ts

@@ -1,31 +1,4 @@
-/**
- * ZenFS's main module. This is exposed in the browser via the ZenFS global.
- */
-import * as fs from './emulation/index.js';
-import { FileSystem } from './filesystem.js';
-import { type Backend, type BackendConfig } from './backends/backend.js';
-/**
- * Initializes ZenFS with the given file systems.
- */
-export declare function initialize(mounts: {
-    [point: string]: FileSystem;
-}, uid?: number, gid?: number): void;
-/**
- * Defines a mapping of mount points to their configurations
- */
-export interface ConfigMapping {
-    [mountPoint: string]: FileSystem | BackendConfig | Backend;
-}
-/**
- * A configuration for ZenFS
- */
-export type Configuration = FileSystem | BackendConfig | ConfigMapping;
-/**
- * Creates filesystems with the given configuration, and initializes ZenFS with it.
- * See the Configuration type for more info on the configuration object.
- */
-export declare function configure(config: Configuration): Promise<void>;
-export type { Backend, BackendConfig } from './backends/backend.js';
+export * from './backends/backend.js';
 export * from './backends/AsyncMirror.js';
 export * from './backends/AsyncStore.js';
 export * from './backends/InMemory.js';
@@ -33,6 +6,7 @@ export * from './backends/Locked.js';
 export * from './backends/Overlay.js';
 export * from './backends/SyncStore.js';
 export * from './ApiError.js';
+export * from './config.js';
 export * from './cred.js';
 export * from './file.js';
 export * from './filesystem.js';
@@ -41,5 +15,6 @@ export * from './inode.js';
 export * from './mutex.js';
 export * from './stats.js';
 export * from './utils.js';
+import * as fs from './emulation/index.js';
 export { fs };
 export default fs;

package/dist/index.js

@@ -1,42 +1,4 @@
-/**
- * ZenFS's main module. This is exposed in the browser via the ZenFS global.
- */
-import * as fs from './emulation/index.js';
-import { FileSystem } from './filesystem.js';
-import { Cred } from './cred.js';
-import { isBackend, resolveBackendConfig } from './backends/backend.js';
-import { setCred } from './emulation/shared.js';
-/**
- * Initializes ZenFS with the given file systems.
- */
-export function initialize(mounts, uid = 0, gid = 0) {
-    setCred(new Cred(uid, gid, uid, gid, uid, gid));
-    fs.initialize(mounts);
-}
-/**
- * Creates filesystems with the given configuration, and initializes ZenFS with it.
- * See the Configuration type for more info on the configuration object.
- */
-export async function configure(config) {
-    if ('backend' in config || config instanceof FileSystem) {
-        // single FS
-        config = { '/': config };
-    }
-    for (let [point, value] of Object.entries(config)) {
-        if (typeof value == 'number') {
-            //should never happen
-            continue;
-        }
-        if (value instanceof FileSystem) {
-            continue;
-        }
-        if (isBackend(value)) {
-            value = { backend: value };
-        }
-        config[point] = await resolveBackendConfig(value);
-    }
-    initialize(config);
-}
+export * from './backends/backend.js';
 export * from './backends/AsyncMirror.js';
 export * from './backends/AsyncStore.js';
 export * from './backends/InMemory.js';
@@ -44,6 +6,7 @@ export * from './backends/Locked.js';
 export * from './backends/Overlay.js';
 export * from './backends/SyncStore.js';
 export * from './ApiError.js';
+export * from './config.js';
 export * from './cred.js';
 export * from './file.js';
 export * from './filesystem.js';
@@ -52,5 +15,6 @@ export * from './inode.js';
 export * from './mutex.js';
 export * from './stats.js';
 export * from './utils.js';
+import * as fs from './emulation/index.js';
 export { fs };
 export default fs;

package/dist/stats.d.ts

@@ -202,3 +202,19 @@ export declare class BigIntStats extends StatsCommon<bigint> implements Node.Big
      */
     static clone(stats: BigIntStats | Stats): BigIntStats;
 }
+/**
+ * @returns true if stats is a file.
+ */
+export declare function isFile(stats: StatsLike): boolean;
+/**
+ * @returns True if stats is a directory.
+ */
+export declare function isDirectory(stats: StatsLike): boolean;
+/**
+ * @returns true if stats is a symbolic link
+ */
+export declare function isSymbolicLink(stats: StatsLike): boolean;
+export declare function isSocket(): boolean;
+export declare function isBlockDevice(): boolean;
+export declare function isCharacterDevice(): boolean;
+export declare function isFIFO(): boolean;

package/dist/stats.js

@@ -246,3 +246,33 @@ export class BigIntStats extends StatsCommon {
     }
 }
 BigIntStats;
+/**
+ * @returns true if stats is a file.
+ */
+export function isFile(stats) {
+    return (Number(stats.mode) & S_IFMT) === S_IFREG;
+}
+/**
+ * @returns True if stats is a directory.
+ */
+export function isDirectory(stats) {
+    return (Number(stats.mode) & S_IFMT) === S_IFDIR;
+}
+/**
+ * @returns true if stats is a symbolic link
+ */
+export function isSymbolicLink(stats) {
+    return (Number(stats.mode) & S_IFMT) === S_IFLNK;
+}
+export function isSocket() {
+    return false;
+}
+export function isBlockDevice() {
+    return false;
+}
+export function isCharacterDevice() {
+    return false;
+}
+export function isFIFO() {
+    return false;
+}

package/license.md

@@ -1,8 +1,6 @@
-ZenFS's license follows:
+Copyright (c) 2023-2024 James P. and other ZenFS contributors.
 
-====
-
-Copyright (c) 2013-2023 John Vilk and other ZenFS contributors.
+Copyright (c) 2013-2023 John Vilk and other BrowserFS contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in
@@ -22,12 +20,10 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-====
-
 This license applies to all parts of ZenFS, except for the following items:
 
-- The test fixtures located in `test/fixtures/files/node`. Their license follows:
-  """
+-   The test fixtures located in `test/fixtures/node`. Their license follows:
+    """
     Copyright Joyent, Inc. and other Node contributors. All rights reserved.
     Permission is hereby granted, free of charge, to any person obtaining a copy
     of this software and associated documentation files (the "Software"), to
@@ -46,77 +42,4 @@ This license applies to all parts of ZenFS, except for the following items:
     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
     IN THE SOFTWARE.
-  """
-
-- The Emscripten file system in src/generic/emscripten_fs.ts is a modified
-  version of Emscripten's NODEFS. Emscripten's license follows:
-  """
-    Emscripten is available under 2 licenses, the MIT license and the
-    University of Illinois/NCSA Open Source License.
-
-    Both are permissive open source licenses, with little if any
-    practical difference between them.
-
-    The reason for offering both is that (1) the MIT license is
-    well-known, while (2) the University of Illinois/NCSA Open Source
-    License allows Emscripten's code to be integrated upstream into
-    LLVM, which uses that license, should the opportunity arise.
-
-    The full text of both licenses follows.
-
-    ==============================================================================
-
-    Copyright (c) 2010-2011 Emscripten authors, see AUTHORS file.
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in
-    all copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-    THE SOFTWARE.
-
-    ==============================================================================
-
-    Copyright (c) 2010-2011 Emscripten authors, see AUTHORS file.
-    All rights reserved.
-
-    Permission is hereby granted, free of charge, to any person obtaining a
-    copy of this software and associated documentation files (the
-    "Software"), to deal with the Software without restriction, including
-    without limitation the rights to use, copy, modify, merge, publish,
-    distribute, sublicense, and/or sell copies of the Software, and to
-    permit persons to whom the Software is furnished to do so, subject to
-    the following conditions:
-
-        Redistributions of source code must retain the above copyright
-        notice, this list of conditions and the following disclaimers.
-
-        Redistributions in binary form must reproduce the above
-        copyright notice, this list of conditions and the following disclaimers
-        in the documentation and/or other materials provided with the
-        distribution.
-
-        Neither the names of Mozilla,
-        nor the names of its contributors may be used to endorse
-        or promote products derived from this Software without specific prior
-        written permission.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-    IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR
-    ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-    SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE.
-  """
+    """

package/package.json

@@ -1,69 +1,73 @@
 {
-  "name": "@zenfs/core",
-  "version": "0.4.0",
-  "description": "A filesystem in your browser",
-  "main": "dist/index.js",
-  "types": "dist",
-  "keywords": [
-    "filesystem",
-    "node",
-    "storage"
-  ],
-  "bin": {
-    "make-index": "./scripts/make-index.js"
-  },
-  "type": "module",
-  "homepage": "https://github.com/zen-fs/core",
-  "author": "James P. <jp@drvortex.dev> (https://drvortex.dev)",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zen-fs/core.git"
-  },
-  "bugs": {
-    "url": "https://github.com/zen-fs/core/issues"
-  },
-  "engines": {
-    "node": ">= 18"
-  },
-  "exports": {
-    "./*": "./dist/*"
-  },
-  "typesVersions": {
-    "*": {
-      "*": [
-        "./dist/*"
-      ]
-    }
-  },
-  "scripts": {
-    "format": "prettier --write src test",
-    "format:check": "prettier --check src test",
-    "lint": "eslint src test && tsc -p tsconfig.json --noEmit",
-    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules npx jest",
-    "build": "node scripts/build.js",
-    "build:docs": "typedoc --out docs --name ZenFS src/index.ts",
-    "dev": "node scripts/build.js --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@types/node": "^14.0.0",
-    "@types/readable-stream": "^4.0.10",
-    "minimatch": "^9.0.3",
-    "readable-stream": "^4.5.2"
-  },
-  "devDependencies": {
-    "@jest/globals": "^29.5.0",
-    "@types/jest": "^29.5.1",
-    "@typescript-eslint/eslint-plugin": "^5.55.0",
-    "@typescript-eslint/parser": "^5.55.0",
-    "cross-env": "^7.0.3",
-    "esbuild": "^0.17.18",
-    "eslint": "^8.36.0",
-    "jest": "^29.5.0",
-    "prettier": "^2.8.7",
-    "ts-jest": "^29.1.0",
-    "typedoc": "^0.25.1",
-    "typescript": "^4.9.5"
-  }
+	"name": "@zenfs/core",
+	"version": "0.4.2",
+	"description": "A filesystem in your browser",
+	"main": "dist/index.js",
+	"types": "dist",
+	"keywords": [
+		"filesystem",
+		"node",
+		"storage"
+	],
+	"bin": {
+		"make-index": "scripts/make-index.js"
+	},
+	"type": "module",
+	"homepage": "https://github.com/zen-fs/core",
+	"author": "James P. <jp@drvortex.dev> (https://drvortex.dev)",
+	"contributors": [
+		"John Vilk <jvilk@cs.umass.edu>"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/zen-fs/core.git"
+	},
+	"bugs": {
+		"url": "https://github.com/zen-fs/core/issues"
+	},
+	"engines": {
+		"node": ">= 18"
+	},
+	"exports": {
+		".": "./dist/index.js",
+		"./*": "./dist/*"
+	},
+	"typesVersions": {
+		"*": {
+			"*": [
+				"./dist/*"
+			]
+		}
+	},
+	"scripts": {
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"lint": "eslint src tests && tsc -p tsconfig.json --noEmit",
+		"test": "cross-env NODE_OPTIONS=--experimental-vm-modules npx jest",
+		"build": "node scripts/build.js",
+		"build:docs": "typedoc --out docs --name ZenFS src/index.ts",
+		"dev": "node scripts/build.js --watch",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"@types/node": "^14.0.0",
+		"@types/readable-stream": "^4.0.10",
+		"minimatch": "^9.0.3",
+		"readable-stream": "^4.5.2"
+	},
+	"devDependencies": {
+		"@jest/globals": "^29.5.0",
+		"@types/jest": "^29.5.1",
+		"@typescript-eslint/eslint-plugin": "^5.55.0",
+		"@typescript-eslint/parser": "^5.55.0",
+		"cross-env": "^7.0.3",
+		"esbuild": "^0.17.18",
+		"eslint": "^8.36.0",
+		"jest": "^29.5.0",
+		"prettier": "^3.2.5",
+		"ts-jest": "^29.1.0",
+		"typedoc": "^0.25.1",
+		"typescript": "^4.9.5"
+	}
 }

package/readme.md

@@ -1,23 +1,25 @@
 # ZenFS
 
-ZenFS is an in-browser file system that emulates the [Node JS file system API](http://nodejs.org/api/fs.html) and supports storing and retrieving files from various backends. ZenFS also integrates nicely with other tools.
+ZenFS is a file system that emulates the [NodeJS filesystem API](http://nodejs.org/api/fs.html).
+
+It works using a system of backends, which are used by ZenFS to store and retrieve data. ZenFS can also integrate with other tools.
+
+ZenFS is a fork of [BrowserFS](https://github.com/jvilk/BrowserFS).
 
 ## Backends
 
-ZenFS is highly extensible, and includes a few built-in backends:
+ZenFS is modular and extensible. The core 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!
+-   `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.
 
-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`.
+ZenFS supports a number of other backends. Many are provided as seperate packages under `@zenfs`. More backends can be defined by separate libraries by extending the `FileSystem` class and/or providing a `Backend` object.
 
-For more information, see the [API documentation for ZenFS](https://zen-fs.github.io/core).
+For more information, see the [docs](https://zen-fs.github.io/core).
 
 ## Installing
 
@@ -28,12 +30,14 @@ npm install @zenfs/core
 ## Usage
 
 > [!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.
+> The examples are written in ESM.  
+> If you are using CJS, you can `require` the package.  
+> If using a browser environment without support for `type=module` in `script` tags, you can add a `script` tag to your HTML pointing to the `browser.min.js` and use ZenFS with the global `ZenFS` object.
 
 ```js
-import fs from '@zenfs/core';
+import fs from '@zenfs/core'; // You can also use the named export, `fs`
 
-fs.writeFileSync('/test.txt', 'Cool, I can do this in the browser!');
+fs.writeFileSync('/test.txt', 'Cool, I can do this in any JS environment (including browsers)!');
 
 const contents = fs.readFileSync('/test.txt', 'utf-8');
 console.log(contents);
@@ -66,9 +70,9 @@ await configure({
 > [!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 the options accepted by the backend and a `backend` property which is (1) or (2)
+> 1. A `Backend` object, if the backend has no required options
+> 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 `/`: