@zenfs/core 0.9.6 → 0.10.0

package/dist/backends/AsyncStore.d.ts

@@ -11,7 +11,7 @@ declare class LRUCache<K, V> {
     private cache;
     constructor(limit: number);
     set(key: K, value: V): void;
-    get(key: K): V | null;
+    get(key: K): V | void;
     remove(key: K): void;
     reset(): void;
 }
@@ -113,7 +113,8 @@ declare const AsyncStoreFS_base: (abstract new (...args: any[]) => {
  */
 export declare class AsyncStoreFS extends AsyncStoreFS_base {
     protected _options: AsyncStoreOptions;
-    protected store: AsyncStore;
+    protected _store?: AsyncStore;
+    protected get store(): AsyncStore;
     protected _cache?: LRUCache<string, Ino>;
     private _initialized;
     _sync: FileSystem;

package/dist/backends/AsyncStore.js

@@ -1,5 +1,5 @@
 import { dirname, basename, join, resolve } from '../emulation/path.js';
-import { ApiError, ErrorCode } from '../ApiError.js';
+import { ErrnoError, Errno } from '../error.js';
 import { W_OK, R_OK } from '../emulation/constants.js';
 import { PreloadFile, flagToMode } from '../file.js';
 import { Async, FileSystem } from '../filesystem.js';
@@ -51,16 +51,22 @@ class LRUCache {
  * @internal
  */
 export class AsyncStoreFS extends Async(FileSystem) {
+    get store() {
+        if (!this._store) {
+            throw new ErrnoError(Errno.ENODATA, 'No store attached');
+        }
+        return this._store;
+    }
     async ready() {
         if (this._initialized) {
             return this;
         }
         this._initialized = true;
-        if (this._options.lruCacheSize > 0) {
+        if (this._options.lruCacheSize) {
             this._cache = new LRUCache(this._options.lruCacheSize);
         }
-        this.store = await this._options.store;
-        this._sync = this._options.sync || InMemory.create({ name: 'test' });
+        this._store = await this._options.store;
+        this._sync = this._options.sync || this._sync;
         await this.makeRootDirectory();
         await super.ready();
         return this;
@@ -75,6 +81,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
         super();
         this._options = _options;
         this._initialized = false;
+        this._sync = InMemory.create({ name: 'test' });
     }
     /**
      * Delete all contents stored in the file system.
@@ -95,18 +102,18 @@ export class AsyncStoreFS extends Async(FileSystem) {
         const c = this._cache;
         if (this._cache) {
             // Clear and disable cache during renaming process.
-            this._cache = null;
-            c.reset();
+            delete this._cache;
+            c?.reset();
         }
         try {
             const tx = this.store.beginTransaction(), oldParent = dirname(oldPath), oldName = basename(oldPath), newParent = dirname(newPath), newName = basename(newPath), 
             // Remove oldPath from parent's directory listing.
             oldDirNode = await this.findINode(tx, oldParent), oldDirList = await this.getDirListing(tx, oldDirNode, oldParent);
             if (!oldDirNode.toStats().hasAccess(W_OK, cred)) {
-                throw ApiError.With('EACCES', oldPath, 'rename');
+                throw ErrnoError.With('EACCES', oldPath, 'rename');
             }
             if (!oldDirList[oldName]) {
-                throw ApiError.With('ENOENT', oldPath, 'rename');
+                throw ErrnoError.With('ENOENT', oldPath, 'rename');
             }
             const nodeId = oldDirList[oldName];
             delete oldDirList[oldName];
@@ -115,7 +122,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
             // is a subpath of newParent. We append '/' to avoid matching folders that
             // are a substring of the bottom-most folder in the path.
             if ((newParent + '/').indexOf(oldPath + '/') === 0) {
-                throw new ApiError(ErrorCode.EBUSY, oldParent);
+                throw new ErrnoError(Errno.EBUSY, oldParent);
             }
             // Add newPath to parent's directory listing.
             let newDirNode, newDirList;
@@ -144,7 +151,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
                 }
                 else {
                     // If it's a directory, throw a permissions error.
-                    throw ApiError.With('EPERM', newPath, 'rename');
+                    throw ErrnoError.With('EPERM', newPath, 'rename');
                 }
             }
             newDirList[newName] = nodeId;
@@ -170,11 +177,11 @@ export class AsyncStoreFS extends Async(FileSystem) {
         const tx = this.store.beginTransaction();
         const inode = await this.findINode(tx, p);
         if (!inode) {
-            throw ApiError.With('ENOENT', p, 'stat');
+            throw ErrnoError.With('ENOENT', p, 'stat');
         }
         const stats = inode.toStats();
         if (!stats.hasAccess(R_OK, cred)) {
-            throw ApiError.With('EACCES', p, 'stat');
+            throw ErrnoError.With('EACCES', p, 'stat');
         }
         return stats;
     }
@@ -188,10 +195,10 @@ export class AsyncStoreFS extends Async(FileSystem) {
         await this.queueDone();
         const tx = this.store.beginTransaction(), node = await this.findINode(tx, p), data = await tx.get(node.ino);
         if (!node.toStats().hasAccess(flagToMode(flag), cred)) {
-            throw ApiError.With('EACCES', p, 'openFile');
+            throw ErrnoError.With('EACCES', p, 'openFile');
         }
         if (!data) {
-            throw ApiError.With('ENOENT', p, 'openFile');
+            throw ErrnoError.With('ENOENT', p, 'openFile');
         }
         return new PreloadFile(this, p, flag, node.toStats(), data);
     }
@@ -204,7 +211,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
         // Check first if directory is empty.
         const list = await this.readdir(p, cred);
         if (list.length > 0) {
-            throw ApiError.With('ENOTEMPTY', p, 'rmdir');
+            throw ErrnoError.With('ENOTEMPTY', p, 'rmdir');
         }
         await this.removeEntry(p, true, cred);
     }
@@ -218,7 +225,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
         const tx = this.store.beginTransaction();
         const node = await this.findINode(tx, p);
         if (!node.toStats().hasAccess(R_OK, cred)) {
-            throw ApiError.With('EACCES', p, 'readdur');
+            throw ErrnoError.With('EACCES', p, 'readdur');
         }
         return Object.keys(await this.getDirListing(tx, node, p));
     }
@@ -249,16 +256,16 @@ export class AsyncStoreFS extends Async(FileSystem) {
         await this.queueDone();
         const tx = this.store.beginTransaction(), existingDir = dirname(existing), existingDirNode = await this.findINode(tx, existingDir);
         if (!existingDirNode.toStats().hasAccess(R_OK, cred)) {
-            throw ApiError.With('EACCES', existingDir, 'link');
+            throw ErrnoError.With('EACCES', existingDir, 'link');
         }
         const newDir = dirname(newpath), newDirNode = await this.findINode(tx, newDir), newListing = await this.getDirListing(tx, newDirNode, newDir);
         if (!newDirNode.toStats().hasAccess(W_OK, cred)) {
-            throw ApiError.With('EACCES', newDir, 'link');
+            throw ErrnoError.With('EACCES', newDir, 'link');
         }
         const ino = await this._findINode(tx, existingDir, basename(existing));
         const node = await this.getINode(tx, ino, existing);
         if (!node.toStats().hasAccess(W_OK, cred)) {
-            throw ApiError.With('EACCES', newpath, 'link');
+            throw ErrnoError.With('EACCES', newpath, 'link');
         }
         node.nlink++;
         newListing[basename(newpath)] = ino;
@@ -296,7 +303,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
     async _findINode(tx, parent, filename, visited = new Set()) {
         const currentPath = join(parent, filename);
         if (visited.has(currentPath)) {
-            throw new ApiError(ErrorCode.EIO, 'Infinite loop detected while finding inode', currentPath);
+            throw new ErrnoError(Errno.EIO, 'Infinite loop detected while finding inode', currentPath);
         }
         visited.add(currentPath);
         if (this._cache) {
@@ -325,7 +332,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
                     return id;
                 }
                 else {
-                    throw ApiError.With('ENOENT', resolve(parent, filename), '_findINode');
+                    throw ErrnoError.With('ENOENT', resolve(parent, filename), '_findINode');
                 }
             }
         }
@@ -342,7 +349,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
                 return id;
             }
             else {
-                throw ApiError.With('ENOENT', resolve(parent, filename), '_findINode');
+                throw ErrnoError.With('ENOENT', resolve(parent, filename), '_findINode');
             }
         }
     }
@@ -364,7 +371,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
     async getINode(tx, id, p) {
         const data = await tx.get(id);
         if (!data) {
-            throw ApiError.With('ENOENT', p, 'getINode');
+            throw ErrnoError.With('ENOENT', p, 'getINode');
         }
         return new Inode(data.buffer);
     }
@@ -374,7 +381,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
      */
     async getDirListing(tx, inode, p) {
         if (!inode.toStats().isDirectory()) {
-            throw ApiError.With('ENOTDIR', p, 'getDirListing');
+            throw ErrnoError.With('ENOTDIR', p, 'getDirListing');
         }
         const data = await tx.get(inode.ino);
         if (!data) {
@@ -383,7 +390,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
                 than a directory listing. The latter should never occur unless
                 the file system is corrupted.
              */
-            throw ApiError.With('ENOENT', p, 'getDirListing');
+            throw ErrnoError.With('ENOENT', p, 'getDirListing');
         }
         return decodeDirListing(data);
     }
@@ -394,7 +401,7 @@ export class AsyncStoreFS extends Async(FileSystem) {
     async addNewNode(tx, data, _maxAttempts = 5) {
         if (_maxAttempts <= 0) {
             // Max retries hit. Return with an error.
-            throw new ApiError(ErrorCode.EIO, 'Unable to commit data to key-value store.');
+            throw new ErrnoError(Errno.EIO, 'Unable to commit data to key-value store.');
         }
         // Make an attempt
         const ino = randomIno();
@@ -418,18 +425,18 @@ export class AsyncStoreFS extends Async(FileSystem) {
         const parentDir = dirname(p), fname = basename(p), parentNode = await this.findINode(tx, parentDir), dirListing = await this.getDirListing(tx, parentNode, parentDir);
         //Check that the creater has correct access
         if (!parentNode.toStats().hasAccess(W_OK, cred)) {
-            throw ApiError.With('EACCES', p, 'commitNewFile');
+            throw ErrnoError.With('EACCES', p, 'commitNewFile');
         }
         // Invariant: The root always exists.
         // If we don't check this prior to taking steps below, we will create a
         // file with name '' in root should p == '/'.
         if (p === '/') {
-            throw ApiError.With('EEXIST', p, 'commitNewFile');
+            throw ErrnoError.With('EEXIST', p, 'commitNewFile');
         }
         // Check if file already exists.
         if (dirListing[fname]) {
             await tx.abort();
-            throw ApiError.With('EEXIST', p, 'commitNewFile');
+            throw ErrnoError.With('EEXIST', p, 'commitNewFile');
         }
         try {
             // Commit data.
@@ -468,21 +475,21 @@ export class AsyncStoreFS extends Async(FileSystem) {
         }
         const tx = this.store.beginTransaction(), parent = dirname(p), parentNode = await this.findINode(tx, parent), parentListing = await this.getDirListing(tx, parentNode, parent), fileName = basename(p);
         if (!parentListing[fileName]) {
-            throw ApiError.With('ENOENT', p, 'removeEntry');
+            throw ErrnoError.With('ENOENT', p, 'removeEntry');
         }
         const fileIno = parentListing[fileName];
         // Get file inode.
         const fileNode = await this.getINode(tx, fileIno, p);
         if (!fileNode.toStats().hasAccess(W_OK, cred)) {
-            throw ApiError.With('EACCES', p, 'removeEntry');
+            throw ErrnoError.With('EACCES', p, 'removeEntry');
         }
         // Remove from directory listing of parent.
         delete parentListing[fileName];
         if (!isDir && fileNode.toStats().isDirectory()) {
-            throw ApiError.With('EISDIR', p, 'removeEntry');
+            throw ErrnoError.With('EISDIR', p, 'removeEntry');
         }
         if (isDir && !fileNode.toStats().isDirectory()) {
-            throw ApiError.With('ENOTDIR', p, 'removeEntry');
+            throw ErrnoError.With('ENOTDIR', p, 'removeEntry');
         }
         try {
             await tx.put(parentNode.ino, encodeDirListing(parentListing), true);

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<this>;
+    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(p: string, type: 'buffer'): Promise<Uint8Array>;
+    protected _fetchFile(p: string, type: 'json'): Promise<object>;
+    protected _fetchFile(p: 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,171 @@
+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(p, type) {
+    const response = await fetch(p).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(p) {
+    const response = await fetch(p, { 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;
+        return this;
+    }
+    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(p, type) {
+        return fetchFile(this._getRemotePath(p), 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/InMemory.d.ts

@@ -9,7 +9,7 @@ export declare class InMemoryStore implements SyncStore, SimpleSyncStore {
     constructor(name?: string);
     clear(): void;
     beginTransaction(): SyncTransaction;
-    get(key: Ino): Uint8Array;
+    get(key: Ino): Uint8Array | undefined;
     put(key: Ino, data: Uint8Array, overwrite: boolean): boolean;
     remove(key: Ino): void;
 }

package/dist/backends/Index.d.ts

@@ -68,25 +68,25 @@ export declare class FileIndex<TData> {
      * @return The removed item,
      *   or null if it did not exist.
      */
-    remove(path: string): IndexInode<TData> | null;
+    remove(path: string): IndexInode<TData> | void;
     /**
      * Retrieves the directory listing of the given path.
      * @return An array of files in the given path, or 'null' if it does not exist.
      */
-    ls(path: string): string[] | null;
+    ls(path: string): string[] | void;
     /**
      * Returns the inode of the given item.
      * @return Returns null if the item does not exist.
      */
-    get(path: string): IndexInode<TData> | null;
+    get(path: string): IndexInode<TData> | void | null;
 }
 /**
  * Generic interface for file/directory inodes.
  * Note that Stats objects are what we use for file inodes.
  */
 export declare abstract class IndexInode<TData> {
-    data?: TData;
-    constructor(data?: TData);
+    data?: TData | undefined;
+    constructor(data?: TData | undefined);
     /**
      * Whether this inode is for a file
      */
@@ -135,7 +135,7 @@ export declare class IndexDirInode<TData> extends IndexInode<TData> {
      * Returns the inode for the indicated item, or null if it does not exist.
      * @param path Name of item in this directory.
      */
-    get(path: string): IndexInode<TData> | null;
+    get(path: string): IndexInode<TData> | void;
     /**
      * Add the given item to the directory listing. Note that the given inode is
      * not copied, and will be mutated by the DirInode if it is a DirInode.
@@ -151,7 +151,7 @@ export declare class IndexDirInode<TData> extends IndexInode<TData> {
      * @return Returns the item
      *   removed, or null if the item did not exist.
      */
-    remove(p: string): IndexInode<TData> | null;
+    remove(p: string): IndexInode<TData> | void;
 }
 declare const IndexFS_base: (abstract new (...args: any[]) => {
     metadata(): import("../filesystem.js").FileSystemMetadata;
@@ -173,9 +173,6 @@ declare const IndexFS_base: (abstract new (...args: any[]) => {
     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>;
-    /**
-     * Constructs a new FileIndex.
-     */
     openFileSync(path: string, flag: string, cred: Cred): import("../file.js").File;
     readdir(path: string, cred: Cred): Promise<string[]>;
     readdirSync(path: string, cred: Cred): string[];