@zenfs/core 0.9.7 → 0.11.0

package/dist/backends/Index.d.ts

@@ -147,11 +147,11 @@ export declare class IndexDirInode<TData> extends IndexInode<TData> {
     add(path: string, inode: IndexInode<TData>): boolean;
     /**
      * Removes the given item from the directory listing.
-     * @param p Name of item to remove from the directory listing.
+     * @param path Name of item to remove from the directory listing.
      * @return Returns the item
      *   removed, or null if the item did not exist.
      */
-    remove(p: string): IndexInode<TData> | void;
+    remove(path: string): IndexInode<TData> | void;
 }
 declare const IndexFS_base: (abstract new (...args: any[]) => {
     metadata(): import("../filesystem.js").FileSystemMetadata;
@@ -169,7 +169,7 @@ declare const IndexFS_base: (abstract new (...args: any[]) => {
     linkSync(srcpath: string, dstpath: string, cred: Cred): void;
     sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;
     syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
-    ready(): Promise<any>;
+    ready(): Promise<void>;
     stat(path: string, cred: Cred): Promise<Stats>;
     statSync(path: string, cred: Cred): Stats;
     openFile(path: string, flag: string, cred: Cred): Promise<import("../file.js").File>;

package/dist/backends/Index.js

@@ -1,4 +1,4 @@
-import { ApiError, ErrorCode } from '../ApiError.js';
+import { ErrnoError, Errno } from '../error.js';
 import { basename, dirname, join } from '../emulation/path.js';
 import { NoSyncFile, flagToMode, isWriteable } from '../file.js';
 import { FileSystem, Readonly } from '../filesystem.js';
@@ -91,10 +91,10 @@ export class FileIndex {
      */
     add(path, inode) {
         if (!inode) {
-            throw new Error('Inode must be specified');
+            throw new ErrnoError(Errno.EINVAL, 'Inode must be specified', path, 'FileIndex.add');
         }
         if (!path.startsWith('/')) {
-            throw new Error('Path must be absolute, got: ' + path);
+            throw new ErrnoError(Errno.EINVAL, 'Path not absolute', path, 'FileIndex.add');
         }
         // Check if it already exists.
         if (this._index.has(path)) {
@@ -287,16 +287,16 @@ export class IndexDirInode extends IndexInode {
     }
     /**
      * Removes the given item from the directory listing.
-     * @param p Name of item to remove from the directory listing.
+     * @param path Name of item to remove from the directory listing.
      * @return Returns the item
      *   removed, or null if the item did not exist.
      */
-    remove(p) {
-        const item = this._listing.get(p);
+    remove(path) {
+        const item = this._listing.get(path);
         if (!item) {
             return;
         }
-        this._listing.delete(p);
+        this._listing.delete(path);
         return item;
     }
 }
@@ -308,7 +308,7 @@ export class IndexFS extends Readonly(FileSystem) {
     async stat(path) {
         const inode = this._index.get(path);
         if (!inode) {
-            throw ApiError.With('ENOENT', path, 'stat');
+            throw ErrnoError.With('ENOENT', path, 'stat');
         }
         if (inode.isDirectory()) {
             return inode.stats;
@@ -316,12 +316,12 @@ export class IndexFS extends Readonly(FileSystem) {
         if (inode.isFile()) {
             return this.statFileInode(inode, path);
         }
-        throw new ApiError(ErrorCode.EINVAL, 'Invalid inode.');
+        throw new ErrnoError(Errno.EINVAL, 'Invalid inode.');
     }
     statSync(path) {
         const inode = this._index.get(path);
         if (!inode) {
-            throw ApiError.With('ENOENT', path, 'stat');
+            throw ErrnoError.With('ENOENT', path, 'stat');
         }
         if (inode.isDirectory()) {
             return inode.stats;
@@ -329,20 +329,20 @@ export class IndexFS extends Readonly(FileSystem) {
         if (inode.isFile()) {
             return this.statFileInodeSync(inode, path);
         }
-        throw new ApiError(ErrorCode.EINVAL, 'Invalid inode.');
+        throw new ErrnoError(Errno.EINVAL, 'Invalid inode.');
     }
     async openFile(path, flag, cred) {
         if (isWriteable(flag)) {
             // You can't write to files on this file system.
-            throw new ApiError(ErrorCode.EPERM, path);
+            throw new ErrnoError(Errno.EPERM, path);
         }
         // Check if the path exists, and is a file.
         const inode = this._index.get(path);
         if (!inode) {
-            throw ApiError.With('ENOENT', path, 'openFile');
+            throw ErrnoError.With('ENOENT', path, 'openFile');
         }
         if (!inode.toStats().hasAccess(flagToMode(flag), cred)) {
-            throw ApiError.With('EACCES', path, 'openFile');
+            throw ErrnoError.With('EACCES', path, 'openFile');
         }
         if (inode.isDirectory()) {
             const stats = inode.stats;
@@ -353,15 +353,15 @@ export class IndexFS extends Readonly(FileSystem) {
     openFileSync(path, flag, cred) {
         if (isWriteable(flag)) {
             // You can't write to files on this file system.
-            throw new ApiError(ErrorCode.EPERM, path);
+            throw new ErrnoError(Errno.EPERM, path);
         }
         // Check if the path exists, and is a file.
         const inode = this._index.get(path);
         if (!inode) {
-            throw ApiError.With('ENOENT', path, 'openFile');
+            throw ErrnoError.With('ENOENT', path, 'openFile');
         }
         if (!inode.toStats().hasAccess(flagToMode(flag), cred)) {
-            throw ApiError.With('EACCES', path, 'openFile');
+            throw ErrnoError.With('EACCES', path, 'openFile');
         }
         if (inode.isDirectory()) {
             const stats = inode.stats;
@@ -373,23 +373,23 @@ export class IndexFS extends Readonly(FileSystem) {
         // Check if it exists.
         const inode = this._index.get(path);
         if (!inode) {
-            throw ApiError.With('ENOENT', path, 'readdir');
+            throw ErrnoError.With('ENOENT', path, 'readdir');
         }
         if (inode.isDirectory()) {
             return inode.listing;
         }
-        throw ApiError.With('ENOTDIR', path, 'readdir');
+        throw ErrnoError.With('ENOTDIR', path, 'readdir');
     }
     readdirSync(path) {
         // Check if it exists.
         const inode = this._index.get(path);
         if (!inode) {
-            throw ApiError.With('ENOENT', path, 'readdir');
+            throw ErrnoError.With('ENOENT', path, 'readdir');
         }
         if (inode.isDirectory()) {
             return inode.listing;
         }
-        throw ApiError.With('ENOTDIR', path, 'readdir');
+        throw ErrnoError.With('ENOTDIR', path, 'readdir');
     }
 }
 export class SyncIndexFS extends IndexFS {
@@ -402,9 +402,9 @@ export class SyncIndexFS extends IndexFS {
 }
 export class AsyncIndexFS extends IndexFS {
     statFileInodeSync(inode, path) {
-        throw ApiError.With('ENOSYS', path, 'AsyncIndexFS.statFileInodeSync');
+        throw ErrnoError.With('ENOSYS', path, 'AsyncIndexFS.statFileInodeSync');
     }
     openFileInodeSync(inode, path, flag) {
-        throw ApiError.With('ENOSYS', path, 'AsyncIndexFS.openFileInodeSync');
+        throw ErrnoError.With('ENOSYS', path, 'AsyncIndexFS.openFileInodeSync');
     }
 }

package/dist/backends/backend.js

@@ -1,4 +1,4 @@
-import { ApiError, ErrorCode } from '../ApiError.js';
+import { ErrnoError, Errno } from '../error.js';
 import { levenshtein } from '../utils.js';
 /**
  * @internal
@@ -12,7 +12,7 @@ export function isBackend(arg) {
  */
 export async function checkOptions(backend, opts) {
     if (typeof opts != 'object' || opts === null) {
-        throw new ApiError(ErrorCode.EINVAL, 'Invalid options');
+        throw new ErrnoError(Errno.EINVAL, 'Invalid options');
     }
     // Check for required options.
     for (const [optName, opt] of Object.entries(backend.options)) {
@@ -31,12 +31,12 @@ export async function checkOptions(backend, opts) {
             })
                 .filter(o => o.distance < 5)
                 .sort((a, b) => a.distance - b.distance);
-            throw new ApiError(ErrorCode.EINVAL, `${backend.name}: Required option '${optName}' not provided.${incorrectOptions.length > 0 ? ` You provided '${incorrectOptions[0].str}', did you mean '${optName}'.` : ''}`);
+            throw new ErrnoError(Errno.EINVAL, `${backend.name}: Required option '${optName}' not provided.${incorrectOptions.length > 0 ? ` You provided '${incorrectOptions[0].str}', did you mean '${optName}'.` : ''}`);
         }
         // Option provided, check type.
         const typeMatches = Array.isArray(opt.type) ? opt.type.indexOf(typeof providedValue) != -1 : typeof providedValue == opt.type;
         if (!typeMatches) {
-            throw new ApiError(ErrorCode.EINVAL, `${backend.name}: 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}`);
+            throw new ErrnoError(Errno.EINVAL, `${backend.name}: 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}`);
         }
         if (opt.validator) {
             await opt.validator(providedValue);
@@ -47,7 +47,8 @@ export async function checkOptions(backend, opts) {
 export async function createBackend(backend, options = {}) {
     await checkOptions(backend, options);
     const fs = backend.create(options);
-    return fs.ready();
+    await fs.ready();
+    return fs;
 }
 /**
  * @internal

package/dist/backends/fetch.d.ts

@@ -0,0 +1,84 @@
+import { NoSyncFile } from '../file.js';
+import type { FileSystemMetadata } from '../filesystem.js';
+import { Stats } from '../stats.js';
+import { type ListingTree, type IndexFileInode, AsyncIndexFS } from './Index.js';
+/**
+ * Configuration options for FetchFS.
+ */
+export interface FetchOptions {
+    /**
+     * URL to a file index as a JSON file or the file index object itself.
+     * Defaults to `index.json`.
+     */
+    index?: string | ListingTree;
+    /** Used as the URL prefix for fetched files.
+     * Default: Fetch files relative to the index.
+     */
+    baseUrl?: string;
+}
+/**
+ * A simple filesystem backed by HTTP using the fetch API.
+ *
+ *
+ * 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 FetchFS extends AsyncIndexFS<Stats> {
+    readonly prefixUrl: string;
+    protected _init: Promise<void>;
+    protected _initialize(index: string | ListingTree): Promise<void>;
+    ready(): Promise<void>;
+    constructor({ index, baseUrl }: FetchOptions);
+    metadata(): FileSystemMetadata;
+    empty(): void;
+    /**
+     * Special function: Preload the given file into the index.
+     * @param path
+     * @param buffer
+     */
+    preloadFile(path: string, buffer: Uint8Array): void;
+    protected statFileInode(inode: IndexFileInode<Stats>, path: string): Promise<Stats>;
+    protected openFileInode(inode: IndexFileInode<Stats>, path: string, flag: string): Promise<NoSyncFile<this>>;
+    private _getRemotePath;
+    /**
+     * Asynchronously download the given file.
+     */
+    protected _fetchFile(path: string, type: 'buffer'): Promise<Uint8Array>;
+    protected _fetchFile(path: string, type: 'json'): Promise<object>;
+    protected _fetchFile(path: string, type: 'buffer' | 'json'): Promise<object>;
+    /**
+     * Only requests the HEAD content, for the file size.
+     */
+    protected _fetchSize(path: string): Promise<number>;
+}
+export declare const Fetch: {
+    readonly name: "Fetch";
+    readonly options: {
+        readonly index: {
+            readonly type: readonly ["string", "object"];
+            readonly required: false;
+            readonly 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`.";
+        };
+        readonly baseUrl: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Used as the URL prefix for fetched files. Default: Fetch files relative to the index.";
+        };
+    };
+    readonly isAvailable: () => boolean;
+    readonly create: (options: FetchOptions) => FetchFS;
+};

package/dist/backends/fetch.js

@@ -0,0 +1,170 @@
+import { ErrnoError, Errno } from '../error.js';
+import { NoSyncFile } from '../file.js';
+import { Stats } from '../stats.js';
+import { FileIndex, AsyncIndexFS } from './Index.js';
+/**
+ * @hidden
+ */
+function convertError(e) {
+    throw new ErrnoError(Errno.EIO, e.message);
+}
+async function fetchFile(path, type) {
+    const response = await fetch(path).catch(convertError);
+    if (!response.ok) {
+        throw new ErrnoError(Errno.EIO, 'fetch failed: response returned code ' + response.status);
+    }
+    switch (type) {
+        case 'buffer':
+            const arrayBuffer = await response.arrayBuffer().catch(convertError);
+            return new Uint8Array(arrayBuffer);
+        case 'json':
+            return response.json().catch(convertError);
+        default:
+            throw new ErrnoError(Errno.EINVAL, 'Invalid download type: ' + type);
+    }
+}
+/**
+ * Asynchronously retrieves the size of the given file in bytes.
+ * @hidden
+ */
+async function fetchSize(path) {
+    const response = await fetch(path, { method: 'HEAD' }).catch(convertError);
+    if (!response.ok) {
+        throw new ErrnoError(Errno.EIO, 'fetch failed: HEAD response returned code ' + response.status);
+    }
+    return parseInt(response.headers.get('Content-Length') || '-1', 10);
+}
+/**
+ * A simple filesystem backed by HTTP using the fetch API.
+ *
+ *
+ * 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 FetchFS extends AsyncIndexFS {
+    async _initialize(index) {
+        if (typeof index != 'string') {
+            this._index = FileIndex.FromListing(index);
+            return;
+        }
+        try {
+            const response = await fetch(index);
+            this._index = FileIndex.FromListing((await response.json()));
+        }
+        catch (e) {
+            throw new ErrnoError(Errno.EINVAL, 'Invalid or unavailable file listing tree');
+        }
+    }
+    async ready() {
+        await this._init;
+    }
+    constructor({ index = 'index.json', baseUrl = '' }) {
+        super({});
+        // prefix url must end in a directory separator.
+        if (baseUrl.at(-1) != '/') {
+            baseUrl += '/';
+        }
+        this.prefixUrl = baseUrl;
+        this._init = this._initialize(index);
+    }
+    metadata() {
+        return {
+            ...super.metadata(),
+            name: FetchFS.name,
+            readonly: true,
+        };
+    }
+    empty() {
+        for (const file of this._index.files()) {
+            delete file.data.fileData;
+        }
+    }
+    /**
+     * Special function: Preload the given file into the index.
+     * @param path
+     * @param buffer
+     */
+    preloadFile(path, buffer) {
+        const inode = this._index.get(path);
+        if (!inode) {
+            throw ErrnoError.With('ENOENT', path, 'preloadFile');
+        }
+        if (!inode.isFile()) {
+            throw ErrnoError.With('EISDIR', path, 'preloadFile');
+        }
+        const stats = inode.data;
+        stats.size = buffer.length;
+        stats.fileData = buffer;
+    }
+    async statFileInode(inode, path) {
+        const stats = inode.data;
+        // At this point, a non-opened file will still have default stats from the listing.
+        if (stats.size < 0) {
+            stats.size = await this._fetchSize(path);
+        }
+        return stats;
+    }
+    async openFileInode(inode, path, flag) {
+        const stats = inode.data;
+        // Use existing file contents. This maintains the previously-used flag.
+        if (stats.fileData) {
+            return new NoSyncFile(this, path, flag, new Stats(stats), stats.fileData);
+        }
+        // @todo be lazier about actually requesting the file
+        const data = await this._fetchFile(path, 'buffer');
+        // we don't initially have file sizes
+        stats.size = data.length;
+        stats.fileData = data;
+        return new NoSyncFile(this, path, flag, new Stats(stats), data);
+    }
+    _getRemotePath(filePath) {
+        if (filePath.charAt(0) === '/') {
+            filePath = filePath.slice(1);
+        }
+        return this.prefixUrl + filePath;
+    }
+    _fetchFile(path, type) {
+        return fetchFile(this._getRemotePath(path), type);
+    }
+    /**
+     * Only requests the HEAD content, for the file size.
+     */
+    _fetchSize(path) {
+        return fetchSize(this._getRemotePath(path));
+    }
+}
+export const Fetch = {
+    name: 'Fetch',
+    options: {
+        index: {
+            type: ['string', 'object'],
+            required: false,
+            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',
+            required: false,
+            description: 'Used as the URL prefix for fetched files. Default: Fetch files relative to the index.',
+        },
+    },
+    isAvailable() {
+        return typeof globalThis.fetch == 'function';
+    },
+    create(options) {
+        return new FetchFS(options);
+    },
+};

package/dist/backends/{Locked.d.ts → locked.d.ts}

@@ -16,26 +16,26 @@ export declare class LockedFS<FS extends FileSystem> implements FileSystem {
     readonly fs: FS;
     private _mu;
     constructor(fs: FS);
-    ready(): Promise<this>;
+    ready(): Promise<void>;
     metadata(): FileSystemMetadata;
     rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
     renameSync(oldPath: string, newPath: string, cred: Cred): void;
-    stat(p: string, cred: Cred): Promise<Stats>;
-    statSync(p: string, cred: Cred): Stats;
+    stat(path: string, cred: Cred): Promise<Stats>;
+    statSync(path: string, cred: Cred): Stats;
     openFile(path: string, flag: string, cred: Cred): Promise<File>;
     openFileSync(path: string, flag: string, cred: Cred): File;
     createFile(path: string, flag: string, mode: number, cred: Cred): Promise<File>;
     createFileSync(path: string, flag: string, mode: number, cred: Cred): File;
-    unlink(p: string, cred: Cred): Promise<void>;
-    unlinkSync(p: string, cred: Cred): void;
-    rmdir(p: string, cred: Cred): Promise<void>;
-    rmdirSync(p: string, cred: Cred): void;
-    mkdir(p: string, mode: number, cred: Cred): Promise<void>;
-    mkdirSync(p: string, mode: number, cred: Cred): void;
-    readdir(p: string, cred: Cred): Promise<string[]>;
-    readdirSync(p: string, cred: Cred): string[];
-    exists(p: string, cred: Cred): Promise<boolean>;
-    existsSync(p: string, cred: Cred): boolean;
+    unlink(path: string, cred: Cred): Promise<void>;
+    unlinkSync(path: string, cred: Cred): void;
+    rmdir(path: string, cred: Cred): Promise<void>;
+    rmdirSync(path: string, cred: Cred): void;
+    mkdir(path: string, mode: number, cred: Cred): Promise<void>;
+    mkdirSync(path: string, mode: number, cred: Cred): void;
+    readdir(path: string, cred: Cred): Promise<string[]>;
+    readdirSync(path: string, cred: Cred): string[];
+    exists(path: string, cred: Cred): Promise<boolean>;
+    existsSync(path: string, cred: Cred): boolean;
     link(srcpath: string, dstpath: string, cred: Cred): Promise<void>;
     linkSync(srcpath: string, dstpath: string, cred: Cred): void;
     sync(path: string, data: Uint8Array, stats: Readonly<Stats>): Promise<void>;