@zenfs/core 0.0.1

package/dist/filesystem.js

@@ -0,0 +1,542 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// disable no-unused-vars since BaseFileSystem uses them a lot
+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());
+    });
+};
+var _a;
+import { ApiError, ErrorCode } from './ApiError';
+import { FileFlag, ActionType } from './file';
+import * as path from 'path';
+import { Buffer } from 'buffer';
+/**
+ * Structure for a filesystem. **All** ZenFS FileSystems must implement
+ * this.
+ *
+ * ### Argument Assumptions
+ *
+ * You can assume the following about arguments passed to each API method:
+ *
+ * - Every path is an absolute path. `.`, `..`, and other items
+ *   are resolved into an absolute form.
+ * - All arguments are present. Any optional arguments at the Node API level
+ *   have been passed in with their default values.
+ */
+export class FileSystem {
+    constructor(options) {
+        // unused
+    }
+}
+/**
+ * Basic filesystem class. Most filesystems should extend this class, as it
+ * provides default implementations for a handful of methods.
+ */
+export class BaseFileSystem extends FileSystem {
+    constructor(options) {
+        super();
+        this._ready = Promise.resolve(this);
+    }
+    get metadata() {
+        return {
+            name: this.constructor.name,
+            readonly: false,
+            synchronous: false,
+            supportsProperties: false,
+            supportsLinks: false,
+            totalSpace: 0,
+            freeSpace: 0,
+        };
+    }
+    whenReady() {
+        return this._ready;
+    }
+    /**
+     * 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(p, flag, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    /**
+     * Create the file at path p with the given mode. Then, open it with the given
+     * flag.
+     */
+    createFile(p, flag, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    open(p, flag, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const stats = yield this.stat(p, cred);
+                switch (flag.pathExistsAction()) {
+                    case ActionType.THROW_EXCEPTION:
+                        throw ApiError.EEXIST(p);
+                    case ActionType.TRUNCATE_FILE:
+                        // NOTE: In a previous implementation, we deleted the file and
+                        // re-created it. However, this created a race condition if another
+                        // asynchronous request was trying to read the file, as the file
+                        // would not exist for a small period of time.
+                        const fd = yield this.openFile(p, flag, cred);
+                        if (!fd)
+                            throw new Error('BFS has reached an impossible code path; please file a bug.');
+                        yield fd.truncate(0);
+                        yield fd.sync();
+                        return fd;
+                    case ActionType.NOP:
+                        return this.openFile(p, flag, cred);
+                    default:
+                        throw new ApiError(ErrorCode.EINVAL, 'Invalid FileFlag object.');
+                }
+                // File exists.
+            }
+            catch (e) {
+                // File does not exist.
+                switch (flag.pathNotExistsAction()) {
+                    case ActionType.CREATE_FILE:
+                        // Ensure parent exists.
+                        const parentStats = yield this.stat(path.dirname(p), cred);
+                        if (parentStats && !parentStats.isDirectory()) {
+                            throw ApiError.ENOTDIR(path.dirname(p));
+                        }
+                        return this.createFile(p, flag, mode, cred);
+                    case ActionType.THROW_EXCEPTION:
+                        throw ApiError.ENOENT(p);
+                    default:
+                        throw new ApiError(ErrorCode.EINVAL, 'Invalid FileFlag object.');
+                }
+            }
+        });
+    }
+    access(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    accessSync(p, mode, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    rename(oldPath, newPath, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    renameSync(oldPath, newPath, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    stat(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    statSync(p, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    /**
+     * 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(p, flag, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    /**
+     * Create the file at path p with the given mode. Then, open it with the given
+     * flag.
+     */
+    createFileSync(p, flag, mode, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    openSync(p, flag, mode, cred) {
+        // Check if the path exists, and is a file.
+        let stats;
+        try {
+            stats = this.statSync(p, cred);
+        }
+        catch (e) {
+            // File does not exist.
+            switch (flag.pathNotExistsAction()) {
+                case ActionType.CREATE_FILE:
+                    // Ensure parent exists.
+                    const parentStats = this.statSync(path.dirname(p), cred);
+                    if (!parentStats.isDirectory()) {
+                        throw ApiError.ENOTDIR(path.dirname(p));
+                    }
+                    return this.createFileSync(p, flag, mode, cred);
+                case ActionType.THROW_EXCEPTION:
+                    throw ApiError.ENOENT(p);
+                default:
+                    throw new ApiError(ErrorCode.EINVAL, 'Invalid FileFlag object.');
+            }
+        }
+        if (!stats.hasAccess(mode, cred)) {
+            throw ApiError.EACCES(p);
+        }
+        // File exists.
+        switch (flag.pathExistsAction()) {
+            case ActionType.THROW_EXCEPTION:
+                throw ApiError.EEXIST(p);
+            case ActionType.TRUNCATE_FILE:
+                // Delete file.
+                this.unlinkSync(p, cred);
+                // Create file. Use the same mode as the old file.
+                // Node itself modifies the ctime when this occurs, so this action
+                // will preserve that behavior if the underlying file system
+                // supports those properties.
+                return this.createFileSync(p, flag, stats.mode, cred);
+            case ActionType.NOP:
+                return this.openFileSync(p, flag, cred);
+            default:
+                throw new ApiError(ErrorCode.EINVAL, 'Invalid FileFlag object.');
+        }
+    }
+    unlink(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    unlinkSync(p, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    rmdir(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    rmdirSync(p, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    mkdir(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    mkdirSync(p, mode, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    readdir(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    readdirSync(p, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    exists(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield this.stat(p, cred);
+                return true;
+            }
+            catch (e) {
+                return false;
+            }
+        });
+    }
+    existsSync(p, cred) {
+        try {
+            this.statSync(p, cred);
+            return true;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    realpath(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.metadata.supportsLinks) {
+                // The path could contain symlinks. Split up the path,
+                // resolve any symlinks, return the resolved string.
+                const splitPath = p.split(path.sep);
+                // TODO: Simpler to just pass through file, find sep and such.
+                for (let i = 0; i < splitPath.length; i++) {
+                    const addPaths = splitPath.slice(0, i + 1);
+                    splitPath[i] = path.join(...addPaths);
+                }
+                return splitPath.join(path.sep);
+            }
+            else {
+                // No symlinks. We just need to verify that it exists.
+                if (!(yield this.exists(p, cred))) {
+                    throw ApiError.ENOENT(p);
+                }
+                return p;
+            }
+        });
+    }
+    realpathSync(p, cred) {
+        if (this.metadata.supportsLinks) {
+            // The path could contain symlinks. Split up the path,
+            // resolve any symlinks, return the resolved string.
+            const splitPath = p.split(path.sep);
+            // TODO: Simpler to just pass through file, find sep and such.
+            for (let i = 0; i < splitPath.length; i++) {
+                const addPaths = splitPath.slice(0, i + 1);
+                splitPath[i] = path.join(...addPaths);
+            }
+            return splitPath.join(path.sep);
+        }
+        else {
+            // No symlinks. We just need to verify that it exists.
+            if (this.existsSync(p, cred)) {
+                return p;
+            }
+            else {
+                throw ApiError.ENOENT(p);
+            }
+        }
+    }
+    truncate(p, len, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fd = yield this.open(p, FileFlag.getFileFlag('r+'), 0o644, cred);
+            try {
+                yield fd.truncate(len);
+            }
+            finally {
+                yield fd.close();
+            }
+        });
+    }
+    truncateSync(p, len, cred) {
+        const fd = this.openSync(p, FileFlag.getFileFlag('r+'), 0o644, cred);
+        // Need to safely close FD, regardless of whether or not truncate succeeds.
+        try {
+            fd.truncateSync(len);
+        }
+        finally {
+            fd.closeSync();
+        }
+    }
+    readFile(fname, encoding, flag, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Get file.
+            const fd = yield this.open(fname, flag, 0o644, cred);
+            try {
+                const stat = yield fd.stat();
+                // Allocate buffer.
+                const buf = Buffer.alloc(stat.size);
+                yield fd.read(buf, 0, stat.size, 0);
+                yield fd.close();
+                if (encoding === null) {
+                    return buf;
+                }
+                return buf.toString(encoding);
+            }
+            finally {
+                yield fd.close();
+            }
+        });
+    }
+    readFileSync(fname, encoding, flag, cred) {
+        // Get file.
+        const fd = this.openSync(fname, flag, 0o644, cred);
+        try {
+            const stat = fd.statSync();
+            // Allocate buffer.
+            const buf = Buffer.alloc(stat.size);
+            fd.readSync(buf, 0, stat.size, 0);
+            fd.closeSync();
+            if (encoding === null) {
+                return buf;
+            }
+            return buf.toString(encoding);
+        }
+        finally {
+            fd.closeSync();
+        }
+    }
+    writeFile(fname, data, encoding, flag, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Get file.
+            const fd = yield this.open(fname, flag, mode, cred);
+            try {
+                if (typeof data === 'string') {
+                    data = Buffer.from(data, encoding);
+                }
+                // Write into file.
+                yield fd.write(data, 0, data.length, 0);
+            }
+            finally {
+                yield fd.close();
+            }
+        });
+    }
+    writeFileSync(fname, data, encoding, flag, mode, cred) {
+        // Get file.
+        const fd = this.openSync(fname, flag, mode, cred);
+        try {
+            if (typeof data === 'string') {
+                data = Buffer.from(data, encoding);
+            }
+            // Write into file.
+            fd.writeSync(data, 0, data.length, 0);
+        }
+        finally {
+            fd.closeSync();
+        }
+    }
+    appendFile(fname, data, encoding, flag, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fd = yield this.open(fname, flag, mode, cred);
+            try {
+                if (typeof data === 'string') {
+                    data = Buffer.from(data, encoding);
+                }
+                yield fd.write(data, 0, data.length, null);
+            }
+            finally {
+                yield fd.close();
+            }
+        });
+    }
+    appendFileSync(fname, data, encoding, flag, mode, cred) {
+        const fd = this.openSync(fname, flag, mode, cred);
+        try {
+            if (typeof data === 'string') {
+                data = Buffer.from(data, encoding);
+            }
+            fd.writeSync(data, 0, data.length, null);
+        }
+        finally {
+            fd.closeSync();
+        }
+    }
+    chmod(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    chmodSync(p, mode, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    chown(p, new_uid, new_gid, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    chownSync(p, new_uid, new_gid, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    utimes(p, atime, mtime, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    utimesSync(p, atime, mtime, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    link(srcpath, dstpath, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    linkSync(srcpath, dstpath, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    symlink(srcpath, dstpath, type, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    symlinkSync(srcpath, dstpath, type, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+    readlink(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new ApiError(ErrorCode.ENOTSUP);
+        });
+    }
+    readlinkSync(p, cred) {
+        throw new ApiError(ErrorCode.ENOTSUP);
+    }
+}
+_a = BaseFileSystem;
+BaseFileSystem.Name = _a.name;
+/**
+ * Implements the asynchronous API in terms of the synchronous API.
+ */
+export class SynchronousFileSystem extends BaseFileSystem {
+    get metadata() {
+        return Object.assign(Object.assign({}, super.metadata), { synchronous: true });
+    }
+    access(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.accessSync(p, mode, cred);
+        });
+    }
+    rename(oldPath, newPath, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.renameSync(oldPath, newPath, cred);
+        });
+    }
+    stat(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.statSync(p, cred);
+        });
+    }
+    open(p, flags, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.openSync(p, flags, mode, cred);
+        });
+    }
+    unlink(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.unlinkSync(p, cred);
+        });
+    }
+    rmdir(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.rmdirSync(p, cred);
+        });
+    }
+    mkdir(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.mkdirSync(p, mode, cred);
+        });
+    }
+    readdir(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.readdirSync(p, cred);
+        });
+    }
+    chmod(p, mode, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.chmodSync(p, mode, cred);
+        });
+    }
+    chown(p, new_uid, new_gid, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.chownSync(p, new_uid, new_gid, cred);
+        });
+    }
+    utimes(p, atime, mtime, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.utimesSync(p, atime, mtime, cred);
+        });
+    }
+    link(srcpath, dstpath, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.linkSync(srcpath, dstpath, cred);
+        });
+    }
+    symlink(srcpath, dstpath, type, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.symlinkSync(srcpath, dstpath, type, cred);
+        });
+    }
+    readlink(p, cred) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.readlinkSync(p, cred);
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * ZenFS's main module. This is exposed in the browser via the ZenFS global.
+ */
+import fs from './emulation/fs';
+import { FileSystem, type BFSOneArgCallback, type BFSCallback } from './filesystem';
+import { backends } from './backends';
+/**
+ * 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 | FileSystemConfiguration | keyof typeof backends;
+}
+/**
+ * A configuration for ZenFS
+ */
+export type Configuration = FileSystem | FileSystemConfiguration | ConfigMapping;
+/**
+ * Creates a file system with the given configuration, and initializes ZenFS with it.
+ * See the FileSystemConfiguration type for more info on the configuration object.
+ */
+export declare function configure(config: Configuration): Promise<void>;
+export declare function configure(config: Configuration, cb: BFSOneArgCallback): void;
+/**
+ * Asynchronously creates a file system with the given configuration, and initializes ZenFS with it.
+ * See the FileSystemConfiguration type for more info on the configuration object.
+ * Note: unlike configure, the .then is provided with the file system
+ */
+/**
+ * Specifies a file system backend type and its options.
+ *
+ * Individual options can recursively contain FileSystemConfiguration objects for
+ * option values that require file systems.
+ *
+ * For example, to mirror Dropbox to Storage with AsyncMirror, use the following
+ * object:
+ *
+ * ```javascript
+ * var config = {
+ *   fs: "AsyncMirror",
+ *   options: {
+ *     sync: {fs: "Storage"},
+ *     async: {fs: "Dropbox", options: {client: anAuthenticatedDropboxSDKClient }}
+ *   }
+ * };
+ * ```
+ *
+ * The option object for each file system corresponds to that file system's option object passed to its `Create()` method.
+ */
+export interface FileSystemConfiguration {
+    fs: string;
+    options?: object;
+}
+/**
+ * Retrieve a file system with the given configuration. Will return a promise if invoked without a callback
+ * @param config A FileSystemConfiguration object. See FileSystemConfiguration for details.
+ * @param cb Called when the file system is constructed, or when an error occurs.
+ */
+export declare function getFileSystem(config: FileSystemConfiguration): Promise<FileSystem>;
+export declare function getFileSystem(config: FileSystemConfiguration, cb: BFSCallback<FileSystem>): void;
+export * from './backends';
+export * from './backends/AsyncStore';
+export * from './backends/SyncStore';
+export * from './ApiError';
+export * from './cred';
+export * from './file';
+export * from './filesystem';
+export * from './inode';
+export * from './mutex';
+export * from './stats';
+export * from './utils';
+export { fs };
+export default fs;