@zenfs/core 0.0.1

package/dist/utils.d.ts

@@ -0,0 +1,52 @@
+/// <reference types="node" />
+/**
+ * Grab bag of utility functions used across the code.
+ */
+import { FileSystem } from './filesystem';
+import { Cred } from './cred';
+import type { BaseBackendConstructor } from './backends/backend';
+/**
+ * Synchronous recursive makedir.
+ * @internal
+ */
+export declare function mkdirpSync(p: string, mode: number, cred: Cred, fs: FileSystem): void;
+/**
+ * Copies a slice of the given buffer
+ * @internal
+ */
+export declare function copyingSlice(buff: Buffer, start?: number, end?: number): Buffer;
+/**
+ * Option validator for a Buffer file system option.
+ * @internal
+ */
+export declare function bufferValidator(v: object): Promise<void>;
+/**
+ * Checks that the given options object is valid for the file system options.
+ * @internal
+ */
+export declare function checkOptions(backend: BaseBackendConstructor, opts: object): Promise<void>;
+/** Waits n ms.  */
+export declare function wait(ms: number): Promise<void>;
+/**
+ * Converts a callback into a promise. Assumes last parameter is the callback
+ * @todo Look at changing resolve value from cbArgs[0] to include other callback arguments?
+ */
+export declare function toPromise(fn: (...fnArgs: unknown[]) => unknown): (...args: unknown[]) => Promise<unknown>;
+/**
+ * @internal
+ */
+export declare const setImmediate: typeof globalThis.setImmediate | ((cb: any) => NodeJS.Timeout);
+/**
+ * @internal
+ */
+export declare const ROOT_NODE_ID: string;
+/**
+ * Returns an empty directory node.
+ * @internal
+ */
+export declare function getEmptyDirNode(): Buffer;
+/**
+ * Generates a random ID.
+ * @internal
+ */
+export declare function randomUUID(): string;

package/dist/utils.js

@@ -0,0 +1,261 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ErrorCode, ApiError } from './ApiError';
+import * as path from 'path';
+import { Buffer } from 'buffer';
+/**
+ * Synchronous recursive makedir.
+ * @internal
+ */
+export function mkdirpSync(p, mode, cred, fs) {
+    if (!fs.existsSync(p, cred)) {
+        mkdirpSync(path.dirname(p), mode, cred, fs);
+        fs.mkdirSync(p, mode, cred);
+    }
+}
+/**
+ * Copies a slice of the given buffer
+ * @internal
+ */
+export function copyingSlice(buff, start = 0, end = buff.length) {
+    if (start < 0 || end < 0 || end > buff.length || start > end) {
+        throw new TypeError(`Invalid slice bounds on buffer of length ${buff.length}: [${start}, ${end}]`);
+    }
+    if (buff.length === 0) {
+        // Avoid s0 corner case in ArrayBuffer case.
+        return Buffer.alloc(0);
+    }
+    else {
+        return buff.subarray(start, end);
+    }
+}
+/**
+ * Option validator for a Buffer file system option.
+ * @internal
+ */
+export function bufferValidator(v) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!Buffer.isBuffer(v)) {
+            throw new ApiError(ErrorCode.EINVAL, 'option must be a Buffer.');
+        }
+    });
+}
+/*
+ * Levenshtein distance, from the `js-levenshtein` NPM module.
+ * Copied here to avoid complexity of adding another CommonJS module dependency.
+ */
+function _min(d0, d1, d2, bx, ay) {
+    return Math.min(d0 + 1, d1 + 1, d2 + 1, bx === ay ? d1 : d1 + 1);
+}
+/**
+ * Calculates levenshtein distance.
+ * @param a
+ * @param b
+ */
+function levenshtein(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length > b.length) {
+        [a, b] = [b, a]; // Swap a and b
+    }
+    let la = a.length;
+    let lb = b.length;
+    // Trim common suffix
+    while (la > 0 && a.charCodeAt(la - 1) === b.charCodeAt(lb - 1)) {
+        la--;
+        lb--;
+    }
+    let offset = 0;
+    // Trim common prefix
+    while (offset < la && a.charCodeAt(offset) === b.charCodeAt(offset)) {
+        offset++;
+    }
+    la -= offset;
+    lb -= offset;
+    if (la === 0 || lb === 1) {
+        return lb;
+    }
+    const vector = new Array(la << 1);
+    for (let y = 0; y < la;) {
+        vector[la + y] = a.charCodeAt(offset + y);
+        vector[y] = ++y;
+    }
+    let x;
+    let d0;
+    let d1;
+    let d2;
+    let d3;
+    for (x = 0; x + 3 < lb;) {
+        const bx0 = b.charCodeAt(offset + (d0 = x));
+        const bx1 = b.charCodeAt(offset + (d1 = x + 1));
+        const bx2 = b.charCodeAt(offset + (d2 = x + 2));
+        const bx3 = b.charCodeAt(offset + (d3 = x + 3));
+        let dd = (x += 4);
+        for (let y = 0; y < la;) {
+            const ay = vector[la + y];
+            const dy = vector[y];
+            d0 = _min(dy, d0, d1, bx0, ay);
+            d1 = _min(d0, d1, d2, bx1, ay);
+            d2 = _min(d1, d2, d3, bx2, ay);
+            dd = _min(d2, d3, dd, bx3, ay);
+            vector[y++] = dd;
+            d3 = d2;
+            d2 = d1;
+            d1 = d0;
+            d0 = dy;
+        }
+    }
+    let dd = 0;
+    for (; x < lb;) {
+        const bx0 = b.charCodeAt(offset + (d0 = x));
+        dd = ++x;
+        for (let y = 0; y < la; y++) {
+            const dy = vector[y];
+            vector[y] = dd = dy < d0 || dd < d0 ? (dy > dd ? dd + 1 : dy + 1) : bx0 === vector[la + y] ? d0 : d0 + 1;
+            d0 = dy;
+        }
+    }
+    return dd;
+}
+/**
+ * Checks that the given options object is valid for the file system options.
+ * @internal
+ */
+export function checkOptions(backend, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const optsInfo = backend.Options;
+        const fsName = backend.Name;
+        let pendingValidators = 0;
+        let callbackCalled = false;
+        let loopEnded = false;
+        // Check for required options.
+        for (const optName in optsInfo) {
+            if (Object.prototype.hasOwnProperty.call(optsInfo, optName)) {
+                const opt = optsInfo[optName];
+                const providedValue = opts && opts[optName];
+                if (providedValue === undefined || providedValue === null) {
+                    if (!opt.optional) {
+                        // Required option, not provided.
+                        // Any incorrect options provided? Which ones are close to the provided one?
+                        // (edit distance 5 === close)
+                        const incorrectOptions = Object.keys(opts)
+                            .filter(o => !(o in optsInfo))
+                            .map((a) => {
+                            return { str: a, distance: levenshtein(optName, a) };
+                        })
+                            .filter(o => o.distance < 5)
+                            .sort((a, b) => a.distance - b.distance);
+                        // Validators may be synchronous.
+                        if (callbackCalled) {
+                            return;
+                        }
+                        callbackCalled = true;
+                        throw new ApiError(ErrorCode.EINVAL, `[${fsName}] Required option '${optName}' not provided.${incorrectOptions.length > 0 ? ` You provided unrecognized option '${incorrectOptions[0].str}'; perhaps you meant to type '${optName}'.` : ''}\nOption description: ${opt.description}`);
+                    }
+                    // Else: Optional option, not provided. That is OK.
+                }
+                else {
+                    // Option provided! Check type.
+                    let typeMatches = false;
+                    if (Array.isArray(opt.type)) {
+                        typeMatches = opt.type.indexOf(typeof providedValue) !== -1;
+                    }
+                    else {
+                        typeMatches = typeof providedValue === opt.type;
+                    }
+                    if (!typeMatches) {
+                        // Validators may be synchronous.
+                        if (callbackCalled) {
+                            return;
+                        }
+                        callbackCalled = true;
+                        throw new ApiError(ErrorCode.EINVAL, `[${fsName}] Value provided for option ${optName} is not the proper type. Expected ${Array.isArray(opt.type) ? `one of {${opt.type.join(', ')}}` : opt.type}, but received ${typeof providedValue}\nOption description: ${opt.description}`);
+                    }
+                    else if (opt.validator) {
+                        pendingValidators++;
+                        try {
+                            yield opt.validator(providedValue);
+                        }
+                        catch (e) {
+                            if (!callbackCalled) {
+                                if (e) {
+                                    callbackCalled = true;
+                                    throw e;
+                                }
+                                pendingValidators--;
+                                if (pendingValidators === 0 && loopEnded) {
+                                    return;
+                                }
+                            }
+                        }
+                    }
+                    // Otherwise: All good!
+                }
+            }
+        }
+        loopEnded = true;
+        if (pendingValidators === 0 && !callbackCalled) {
+            return;
+        }
+    });
+}
+/** Waits n ms.  */
+export function wait(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Converts a callback into a promise. Assumes last parameter is the callback
+ * @todo Look at changing resolve value from cbArgs[0] to include other callback arguments?
+ */
+export function toPromise(fn) {
+    return function (...args) {
+        return new Promise((resolve, reject) => {
+            args.push((e, ...cbArgs) => {
+                if (e) {
+                    reject(e);
+                }
+                else {
+                    resolve(cbArgs[0]);
+                }
+            });
+            fn(...args);
+        });
+    };
+}
+/**
+ * @internal
+ */
+export const setImmediate = typeof globalThis.setImmediate == 'function' ? globalThis.setImmediate : cb => setTimeout(cb, 0);
+/**
+ * @internal
+ */
+export const ROOT_NODE_ID = '/';
+/**
+ * Returns an empty directory node.
+ * @internal
+ */
+export function getEmptyDirNode() {
+    return Buffer.from('{}');
+}
+/**
+ * Generates a random ID.
+ * @internal
+ */
+export function randomUUID() {
+    // From http://stackoverflow.com/questions/105034/how-to-create-a-guid-uuid-in-javascript
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}

package/license.md

@@ -0,0 +1,122 @@
+ZenFS's license follows:
+
+====
+
+Copyright (c) 2013-2023 John Vilk and other ZenFS 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
+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.
+
+====
+
+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:
+  """
+    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
+    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.
+  """
+
+- 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

@@ -0,0 +1,61 @@
+{
+  "name": "@zenfs/core",
+  "version": "0.0.1",
+  "description": "A filesystem in your browser",
+  "main": "dist/index.js",
+  "types": "dist",
+  "keywords": [
+    "filesystem",
+    "node",
+    "storage"
+  ],
+  "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/*"
+  },
+  "scripts": {
+    "format": "prettier --write src test",
+    "format:check": "prettier --check src test",
+    "lint": "eslint src test",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules npx jest",
+    "build": "node scripts/build.mjs",
+    "build:docs": "typedoc --out docs --name ZenFS src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/archiver": "~2.1.2",
+    "@types/jest": "^29.5.1",
+    "@types/node": "^14.18.62",
+    "@typescript-eslint/eslint-plugin": "^5.55.0",
+    "@typescript-eslint/parser": "^5.55.0",
+    "archiver": "~2.1.1",
+    "bfs-path": "~0.1.2",
+    "bfs-process": "~0.1.6",
+    "buffer": "~5.1.0",
+    "cross-env": "^7.0.3",
+    "esbuild": "^0.17.18",
+    "esbuild-plugin-polyfill-node": "^0.3.0",
+    "eslint": "^8.36.0",
+    "jest": "^29.5.0",
+    "path": "^0.12.7",
+    "prettier": "^2.8.7",
+    "source-map-loader": "~0.2.3",
+    "ts-jest": "^29.1.0",
+    "typedoc": "^0.25.1",
+    "typescript": "^4.9.5"
+  }
+}