@zenfs/dom 0.0.5 → 0.1.0

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-export * from './backends/FileSystemAccess.js';
-export * from './backends/HTTPRequest.js';
-export * from './backends/IndexedDB.js';
-export * from './backends/Storage.js';
-export * from './backends/Worker.js';
+export * from './FileSystemAccess.js';
+export * from './IndexedDB.js';
+export * from './Storage.js';

package/dist/index.js

@@ -1,5 +1,3 @@
-export * from './backends/FileSystemAccess.js';
-export * from './backends/HTTPRequest.js';
-export * from './backends/IndexedDB.js';
-export * from './backends/Storage.js';
-export * from './backends/Worker.js';
+export * from './FileSystemAccess.js';
+export * from './IndexedDB.js';
+export * from './Storage.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenfs/dom",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "DOM backends for ZenFS",
   "main": "dist/index.js",
   "types": "dist",
@@ -10,15 +10,15 @@
     "storage"
   ],
   "type": "module",
-  "homepage": "https://github.com/zen-fs/fs-dom",
+  "homepage": "https://github.com/zen-fs/dom",
   "author": "James P. <jp@drvortex.dev> (https://drvortex.dev)",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zen-fs/fs-dom.git"
+    "url": "git+https://github.com/zen-fs/dom.git"
   },
   "bugs": {
-    "url": "https://github.com/zen-fs/fs-dom/issues"
+    "url": "https://github.com/zen-fs/dom/issues"
   },
   "engines": {
     "node": ">= 18"
@@ -36,7 +36,7 @@
   "scripts": {
     "format": "prettier --write src",
     "format:check": "prettier --check src",
-    "lint": "eslint src",
+    "lint": "tsc -p tsconfig.json --noEmit && eslint src",
     "build": "node scripts/build.mjs",
     "build:docs": "typedoc --out docs --name 'ZenFS DOM' src/index.ts",
     "prepublishOnly": "npm run build"
@@ -50,7 +50,7 @@
     "typedoc": "^0.25.1",
     "typescript": "5.2.2"
   },
-  "dependencies": {
-    "@zenfs/core": "^0.1.0"
+  "peerDependencies": {
+    "@zenfs/core": "^0.3.2"
   }
 }

package/readme.md

@@ -1,36 +1,28 @@
 # ZenFS DOM Backends
 
-[ZenFS](https://github.com/zen-fs/core) backends for DOM APIs. DOM APIs are *only* available natively in browsers.
+[ZenFS](https://github.com/zen-fs/core) backends for DOM APIs. DOM APIs are _only_ available natively in browsers.
 
-Please read the ZenFS documentation!
+> [!IMPORTANT]
+> Please read the ZenFS documentation!
 
 ## Backends
 
-- `HTTPRequest`: Downloads files on-demand from a webserver using `fetch`.
-- `Storage`: Stores files in a `Storage` object, like `localStorage` and `seesionStorage`.
-- `IndexedDB`: Stores files into an `IndexedDB` object database.
-- `WorkerFS`: Lets you mount the ZenFS file system configured in the main thread in a WebWorker, or the other way around!
+-   `Storage`: Stores files in a `Storage` object, like `localStorage` and `sessionStorage`.
+-   `IndexedDB`: Stores files into an `IndexedDB` object database.
+-   `FileSystemAccess`: Store files using the [Web File System API](https://developer.mozilla.org/Web/API/File_System_API).
 
-For more information, see the [API documentation](https://zen-fs.github.io/fs-dom).
-
-## Installing
-
-```sh
-npm install @zenfs/fs-dom
-```
+For more information, see the [API documentation](https://zen-fs.github.io/dom).
 
 ## 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 DOM via the global `ZenFS_DOM` object.
-
-You can use DOM backends, though you must register them if you plan on using `configure`:
+> [!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 DOM via the global `ZenFS_DOM` object.
 
 ```js
-import { configure, fs, registerBackend } from '@zenfs/core';
-import { Storage } from '@zenfs/fs-dom';
+import { configure, fs } from '@zenfs/core';
+import { Storage } from '@zenfs/dom';
 
-registerBackend(Storage);
-await configure({ fs: 'Storage', options: { storage: localStorage } });
+await configure({ backend: Storage, storage: localStorage });
 
 if (!fs.existsSync('/test.txt')) {
 	fs.writeFileSync('/test.txt', 'This will persist across reloads!');

package/dist/backends/FileSystemAccess.d.ts

@@ -1,44 +0,0 @@
-import { Cred } from '@zenfs/core/cred.js';
-import { FileFlag, PreloadFile } from '@zenfs/core/file.js';
-import { BaseFileSystem, FileSystemMetadata } from '@zenfs/core/filesystem.js';
-import { Stats } from '@zenfs/core/stats.js';
-import { type BackendOptions } from '@zenfs/core/backends/backend.js';
-declare global {
-    interface FileSystemDirectoryHandle {
-        [Symbol.iterator](): IterableIterator<[string, FileSystemHandle]>;
-        entries(): IterableIterator<[string, FileSystemHandle]>;
-        keys(): IterableIterator<string>;
-        values(): IterableIterator<FileSystemHandle>;
-    }
-}
-interface FileSystemAccessFileSystemOptions {
-    handle: FileSystemDirectoryHandle;
-}
-export declare class FileSystemAccessFile extends PreloadFile<FileSystemAccessFileSystem> {
-    constructor(_fs: FileSystemAccessFileSystem, _path: string, _flag: FileFlag, _stat: Stats, contents?: Uint8Array);
-    sync(): Promise<void>;
-    close(): Promise<void>;
-}
-export declare class FileSystemAccessFileSystem extends BaseFileSystem {
-    static readonly Name = "FileSystemAccess";
-    static Create: any;
-    static readonly Options: BackendOptions;
-    static isAvailable(): boolean;
-    private _handles;
-    constructor({ handle }: FileSystemAccessFileSystemOptions);
-    get metadata(): FileSystemMetadata;
-    _sync(p: string, data: Uint8Array, stats: Stats, cred: Cred): Promise<void>;
-    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
-    writeFile(fname: string, data: Uint8Array, flag: FileFlag, mode: number, cred: Cred, createFile?: boolean): Promise<void>;
-    createFile(p: string, flag: FileFlag, mode: number, cred: Cred): Promise<FileSystemAccessFile>;
-    stat(path: string, cred: Cred): Promise<Stats>;
-    exists(p: string, cred: Cred): Promise<boolean>;
-    openFile(path: string, flags: FileFlag, cred: Cred): Promise<FileSystemAccessFile>;
-    unlink(path: string, cred: Cred): Promise<void>;
-    rmdir(path: string, cred: Cred): Promise<void>;
-    mkdir(p: string, mode: any, cred: Cred): Promise<void>;
-    readdir(path: string, cred: Cred): Promise<string[]>;
-    private newFile;
-    private getHandle;
-}
-export {};

package/dist/backends/FileSystemAccess.js

@@ -1,208 +0,0 @@
-var _a;
-import { basename, dirname, join } from '@zenfs/core/emulation/path.js';
-import { ApiError, ErrorCode } from '@zenfs/core/ApiError.js';
-import { Cred } from '@zenfs/core/cred.js';
-import { FileFlag, PreloadFile } from '@zenfs/core/file.js';
-import { BaseFileSystem } from '@zenfs/core/filesystem.js';
-import { Stats, FileType } from '@zenfs/core/stats.js';
-import { CreateBackend } from '@zenfs/core/backends/backend.js';
-const handleError = (path = '', error) => {
-    if (error.name === 'NotFoundError') {
-        throw ApiError.ENOENT(path);
-    }
-    throw error;
-};
-export class FileSystemAccessFile extends PreloadFile {
-    constructor(_fs, _path, _flag, _stat, contents) {
-        super(_fs, _path, _flag, _stat, contents);
-    }
-    async sync() {
-        if (this.isDirty()) {
-            await this._fs._sync(this.getPath(), this.getBuffer(), this.getStats(), Cred.Root);
-            this.resetDirty();
-        }
-    }
-    async close() {
-        await this.sync();
-    }
-}
-export class FileSystemAccessFileSystem extends BaseFileSystem {
-    static isAvailable() {
-        return typeof FileSystemHandle === 'function';
-    }
-    constructor({ handle }) {
-        super();
-        this._handles = new Map();
-        this._handles.set('/', handle);
-    }
-    get metadata() {
-        return {
-            ...super.metadata,
-            name: _a.Name,
-        };
-    }
-    async _sync(p, data, stats, cred) {
-        const currentStats = await this.stat(p, cred);
-        if (stats.mtime !== currentStats.mtime) {
-            await this.writeFile(p, data, FileFlag.getFileFlag('w'), currentStats.mode, cred);
-        }
-    }
-    async rename(oldPath, newPath, cred) {
-        try {
-            const handle = await this.getHandle(oldPath);
-            if (handle instanceof FileSystemDirectoryHandle) {
-                const files = await this.readdir(oldPath, cred);
-                await this.mkdir(newPath, 'wx', cred);
-                if (files.length === 0) {
-                    await this.unlink(oldPath, cred);
-                }
-                else {
-                    for (const file of files) {
-                        await this.rename(join(oldPath, file), join(newPath, file), cred);
-                        await this.unlink(oldPath, cred);
-                    }
-                }
-            }
-            if (handle instanceof FileSystemFileHandle) {
-                const oldFile = await handle.getFile(), destFolder = await this.getHandle(dirname(newPath));
-                if (destFolder instanceof FileSystemDirectoryHandle) {
-                    const newFile = await destFolder.getFileHandle(basename(newPath), { create: true });
-                    const writable = await newFile.createWritable();
-                    const buffer = await oldFile.arrayBuffer();
-                    await writable.write(buffer);
-                    writable.close();
-                    await this.unlink(oldPath, cred);
-                }
-            }
-        }
-        catch (err) {
-            handleError(oldPath, err);
-        }
-    }
-    async writeFile(fname, data, flag, mode, cred, createFile) {
-        const handle = await this.getHandle(dirname(fname));
-        if (handle instanceof FileSystemDirectoryHandle) {
-            const file = await handle.getFileHandle(basename(fname), { create: true });
-            const writable = await file.createWritable();
-            await writable.write(data);
-            await writable.close();
-            //return createFile ? this.newFile(fname, flag, data) : undefined;
-        }
-    }
-    async createFile(p, flag, mode, cred) {
-        await this.writeFile(p, new Uint8Array(), flag, mode, cred, true);
-        return this.openFile(p, flag, cred);
-    }
-    async stat(path, cred) {
-        const handle = await this.getHandle(path);
-        if (!handle) {
-            throw ApiError.FileError(ErrorCode.EINVAL, path);
-        }
-        if (handle instanceof FileSystemDirectoryHandle) {
-            return new Stats(FileType.DIRECTORY, 4096);
-        }
-        if (handle instanceof FileSystemFileHandle) {
-            const { lastModified, size } = await handle.getFile();
-            return new Stats(FileType.FILE, size, undefined, undefined, lastModified);
-        }
-    }
-    async exists(p, cred) {
-        try {
-            await this.getHandle(p);
-            return true;
-        }
-        catch (e) {
-            return false;
-        }
-    }
-    async openFile(path, flags, cred) {
-        const handle = await this.getHandle(path);
-        if (handle instanceof FileSystemFileHandle) {
-            const file = await handle.getFile();
-            const buffer = await file.arrayBuffer();
-            return this.newFile(path, flags, buffer, file.size, file.lastModified);
-        }
-    }
-    async unlink(path, cred) {
-        const handle = await this.getHandle(dirname(path));
-        if (handle instanceof FileSystemDirectoryHandle) {
-            try {
-                await handle.removeEntry(basename(path), { recursive: true });
-            }
-            catch (e) {
-                handleError(path, e);
-            }
-        }
-    }
-    async rmdir(path, cred) {
-        return this.unlink(path, cred);
-    }
-    async mkdir(p, mode, cred) {
-        const overwrite = mode && mode.flag && mode.flag.includes('w') && !mode.flag.includes('x');
-        const existingHandle = await this.getHandle(p);
-        if (existingHandle && !overwrite) {
-            throw ApiError.EEXIST(p);
-        }
-        const handle = await this.getHandle(dirname(p));
-        if (handle instanceof FileSystemDirectoryHandle) {
-            await handle.getDirectoryHandle(basename(p), { create: true });
-        }
-    }
-    async readdir(path, cred) {
-        const handle = await this.getHandle(path);
-        if (!(handle instanceof FileSystemDirectoryHandle)) {
-            throw ApiError.ENOTDIR(path);
-        }
-        const _keys = [];
-        for await (const key of handle.keys()) {
-            _keys.push(join(path, key));
-        }
-        return _keys;
-    }
-    newFile(path, flag, data, size, lastModified) {
-        return new FileSystemAccessFile(this, path, flag, new Stats(FileType.FILE, size || 0, undefined, undefined, lastModified || new Date().getTime()), new Uint8Array(data));
-    }
-    async getHandle(path) {
-        if (this._handles.has(path)) {
-            return this._handles.get(path);
-        }
-        let walkedPath = '/';
-        const [, ...pathParts] = path.split('/');
-        const getHandleParts = async ([pathPart, ...remainingPathParts]) => {
-            const walkingPath = join(walkedPath, pathPart);
-            const continueWalk = (handle) => {
-                walkedPath = walkingPath;
-                this._handles.set(walkedPath, handle);
-                if (remainingPathParts.length === 0) {
-                    return this._handles.get(path);
-                }
-                getHandleParts(remainingPathParts);
-            };
-            const handle = this._handles.get(walkedPath);
-            try {
-                return await continueWalk(await handle.getDirectoryHandle(pathPart));
-            }
-            catch (error) {
-                if (error.name === 'TypeMismatchError') {
-                    try {
-                        return await continueWalk(await handle.getFileHandle(pathPart));
-                    }
-                    catch (err) {
-                        handleError(walkingPath, err);
-                    }
-                }
-                else if (error.message === 'Name is not allowed.') {
-                    throw new ApiError(ErrorCode.ENOENT, error.message, walkingPath);
-                }
-                else {
-                    handleError(walkingPath, error);
-                }
-            }
-        };
-        await getHandleParts(pathParts);
-    }
-}
-_a = FileSystemAccessFileSystem;
-FileSystemAccessFileSystem.Name = 'FileSystemAccess';
-FileSystemAccessFileSystem.Create = CreateBackend.bind(_a);
-FileSystemAccessFileSystem.Options = {};

package/dist/backends/HTTPRequest.d.ts

@@ -1,85 +0,0 @@
-import { BaseFileSystem, FileSystemMetadata } from '@zenfs/core/filesystem.js';
-import { FileFlag, NoSyncFile } from '@zenfs/core/file.js';
-import { Stats } from '@zenfs/core/stats.js';
-import { Cred } from '@zenfs/core/cred.js';
-import { type BackendOptions } from '@zenfs/core/backends/backend.js';
-export interface HTTPRequestIndex {
-    [key: string]: string;
-}
-export declare namespace HTTPRequest {
-    /**
-     * Configuration options for a HTTPRequest file system.
-     */
-    interface Options {
-        /**
-         * URL to a file index as a JSON file or the file index object itself, generated with the make_http_index script.
-         * Defaults to `index.json`.
-         */
-        index?: string | HTTPRequestIndex;
-        /** Used as the URL prefix for fetched files.
-         * Default: Fetch files relative to the index.
-         */
-        baseUrl?: string;
-    }
-}
-/**
- * A simple filesystem backed by HTTP downloads. You must create a directory listing using the
- * `make_http_index` tool provided by ZenFS.
- *
- * If you install ZenFS globally with `npm i -g zenfs`, you can generate a listing by
- * running `make_http_index` in your terminal in the directory you would like to index:
- *
- * ```
- * make_http_index > index.json
- * ```
- *
- * Listings objects look like the following:
- *
- * ```json
- * {
- *   "home": {
- *     "jvilk": {
- *       "someFile.txt": null,
- *       "someDir": {
- *         // Empty directory
- *       }
- *     }
- *   }
- * }
- * ```
- *
- * *This example has the folder `/home/jvilk` with subfile `someFile.txt` and subfolder `someDir`.*
- */
-export declare class HTTPRequest extends BaseFileSystem {
-    static readonly Name = "HTTPRequest";
-    static Create: any;
-    static readonly Options: BackendOptions;
-    static isAvailable(): boolean;
-    readonly prefixUrl: string;
-    private _index;
-    constructor({ index, baseUrl }: HTTPRequest.Options);
-    get metadata(): FileSystemMetadata;
-    empty(): void;
-    /**
-     * Special HTTPFS function: Preload the given file into the index.
-     * @param path
-     * @param buffer
-     */
-    preloadFile(path: string, buffer: Uint8Array): void;
-    stat(path: string, cred: Cred): Promise<Stats>;
-    open(path: string, flags: FileFlag, mode: number, cred: Cred): Promise<NoSyncFile<this>>;
-    readdir(path: string, cred: Cred): Promise<string[]>;
-    /**
-     * We have the entire file as a buffer; optimize readFile.
-     */
-    readFile(fname: string, flag: FileFlag, cred: Cred): Promise<Uint8Array>;
-    private _getHTTPPath;
-    /**
-     * Asynchronously download the given file.
-     */
-    private _requestFile;
-    /**
-     * Only requests the HEAD content, for the file size.
-     */
-    private _requestFileSize;
-}

package/dist/backends/HTTPRequest.js

@@ -1,202 +0,0 @@
-var _a;
-import { BaseFileSystem } from '@zenfs/core/filesystem.js';
-import { ApiError, ErrorCode } from '@zenfs/core/ApiError.js';
-import { ActionType, NoSyncFile } from '@zenfs/core/file.js';
-import { Stats } from '@zenfs/core/stats.js';
-import { fetchIsAvailable, fetchFile, fetchFileSize } from '../fetch.js';
-import { FileIndex, isIndexFileInode, isIndexDirInode } from '@zenfs/core/FileIndex.js';
-import { CreateBackend } from '@zenfs/core/backends/backend.js';
-import { R_OK } from '@zenfs/core/emulation/constants.js';
-/**
- * A simple filesystem backed by HTTP downloads. You must create a directory listing using the
- * `make_http_index` tool provided by ZenFS.
- *
- * If you install ZenFS globally with `npm i -g zenfs`, you can generate a listing by
- * running `make_http_index` in your terminal in the directory you would like to index:
- *
- * ```
- * make_http_index > index.json
- * ```
- *
- * Listings objects look like the following:
- *
- * ```json
- * {
- *   "home": {
- *     "jvilk": {
- *       "someFile.txt": null,
- *       "someDir": {
- *         // Empty directory
- *       }
- *     }
- *   }
- * }
- * ```
- *
- * *This example has the folder `/home/jvilk` with subfile `someFile.txt` and subfolder `someDir`.*
- */
-export class HTTPRequest extends BaseFileSystem {
-    static isAvailable() {
-        return fetchIsAvailable;
-    }
-    constructor({ index, baseUrl = '' }) {
-        super();
-        if (!index) {
-            index = 'index.json';
-        }
-        const indexRequest = typeof index == 'string' ? fetchFile(index, 'json') : Promise.resolve(index);
-        this._ready = indexRequest.then(data => {
-            this._index = FileIndex.fromListing(data);
-            return this;
-        });
-        // prefix_url must end in a directory separator.
-        if (baseUrl.length > 0 && baseUrl.charAt(baseUrl.length - 1) !== '/') {
-            baseUrl = baseUrl + '/';
-        }
-        this.prefixUrl = baseUrl;
-    }
-    get metadata() {
-        return {
-            ...super.metadata,
-            name: _a.Name,
-            readonly: true,
-        };
-    }
-    empty() {
-        this._index.fileIterator(function (file) {
-            file.fileData = null;
-        });
-    }
-    /**
-     * Special HTTPFS function: Preload the given file into the index.
-     * @param path
-     * @param buffer
-     */
-    preloadFile(path, buffer) {
-        const inode = this._index.getInode(path);
-        if (isIndexFileInode(inode)) {
-            if (inode === null) {
-                throw ApiError.ENOENT(path);
-            }
-            const stats = inode.getData();
-            stats.size = buffer.length;
-            stats.fileData = buffer;
-        }
-        else {
-            throw ApiError.EISDIR(path);
-        }
-    }
-    async stat(path, cred) {
-        const inode = this._index.getInode(path);
-        if (inode === null) {
-            throw ApiError.ENOENT(path);
-        }
-        if (!inode.toStats().hasAccess(R_OK, cred)) {
-            throw ApiError.EACCES(path);
-        }
-        let stats;
-        if (isIndexFileInode(inode)) {
-            stats = inode.getData();
-            // At this point, a non-opened file will still have default stats from the listing.
-            if (stats.size < 0) {
-                stats.size = await this._requestFileSize(path);
-            }
-        }
-        else if (isIndexDirInode(inode)) {
-            stats = inode.getStats();
-        }
-        else {
-            throw ApiError.FileError(ErrorCode.EINVAL, path);
-        }
-        return stats;
-    }
-    async open(path, flags, mode, cred) {
-        // INVARIANT: You can't write to files on this file system.
-        if (flags.isWriteable()) {
-            throw new ApiError(ErrorCode.EPERM, path);
-        }
-        // Check if the path exists, and is a file.
-        const inode = this._index.getInode(path);
-        if (inode === null) {
-            throw ApiError.ENOENT(path);
-        }
-        if (!inode.toStats().hasAccess(flags.getMode(), cred)) {
-            throw ApiError.EACCES(path);
-        }
-        if (isIndexFileInode(inode) || isIndexDirInode(inode)) {
-            switch (flags.pathExistsAction()) {
-                case ActionType.THROW_EXCEPTION:
-                case ActionType.TRUNCATE_FILE:
-                    throw ApiError.EEXIST(path);
-                case ActionType.NOP:
-                    if (isIndexDirInode(inode)) {
-                        const stats = inode.getStats();
-                        return new NoSyncFile(this, path, flags, stats, stats.fileData || undefined);
-                    }
-                    const stats = inode.getData();
-                    // Use existing file contents.
-                    // XXX: Uh, this maintains the previously-used flag.
-                    if (stats.fileData) {
-                        return new NoSyncFile(this, path, flags, Stats.clone(stats), stats.fileData);
-                    }
-                    // @todo be lazier about actually requesting the file
-                    const buffer = await this._requestFile(path, 'buffer');
-                    // we don't initially have file sizes
-                    stats.size = buffer.length;
-                    stats.fileData = buffer;
-                    return new NoSyncFile(this, path, flags, Stats.clone(stats), buffer);
-                default:
-                    throw new ApiError(ErrorCode.EINVAL, 'Invalid FileMode object.');
-            }
-        }
-        else {
-            throw ApiError.EPERM(path);
-        }
-    }
-    async readdir(path, cred) {
-        return this.readdirSync(path, cred);
-    }
-    /**
-     * We have the entire file as a buffer; optimize readFile.
-     */
-    async readFile(fname, flag, cred) {
-        // Get file.
-        const fd = await this.open(fname, flag, 0o644, cred);
-        try {
-            return fd.getBuffer();
-        }
-        finally {
-            await fd.close();
-        }
-    }
-    _getHTTPPath(filePath) {
-        if (filePath.charAt(0) === '/') {
-            filePath = filePath.slice(1);
-        }
-        return this.prefixUrl + filePath;
-    }
-    _requestFile(p, type) {
-        return fetchFile(this._getHTTPPath(p), type);
-    }
-    /**
-     * Only requests the HEAD content, for the file size.
-     */
-    _requestFileSize(path) {
-        return fetchFileSize(this._getHTTPPath(path));
-    }
-}
-_a = HTTPRequest;
-HTTPRequest.Name = 'HTTPRequest';
-HTTPRequest.Create = CreateBackend.bind(_a);
-HTTPRequest.Options = {
-    index: {
-        type: ['string', 'object'],
-        optional: true,
-        description: 'URL to a file index as a JSON file or the file index object itself, generated with the make_http_index script. Defaults to `index.json`.',
-    },
-    baseUrl: {
-        type: 'string',
-        optional: true,
-        description: 'Used as the URL prefix for fetched files. Default: Fetch files relative to the index.',
-    },
-};