@zenfs/core 0.11.2 → 0.12.1

package/dist/backends/backend.d.ts

@@ -4,7 +4,7 @@ type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undef
 /**
  * Resolves the type of Backend.options from the options interface
  */
-type OptionsConfig<T> = {
+export type OptionsConfig<T> = {
     [K in keyof T]: {
         /**
          * The basic JavaScript type(s) for this option.
@@ -54,7 +54,16 @@ export interface Backend<FS extends FileSystem = FileSystem, TOptions extends ob
      */
     isAvailable(): boolean | Promise<boolean>;
 }
-type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer TOptions> ? TOptions : never;
+/**
+ * Gets the options type of a backend
+ * @internal
+ */
+export type OptionsOf<T extends Backend> = T extends Backend<FileSystem, infer TOptions> ? TOptions : never;
+/**
+ * Gets the FileSystem type for a backend
+ * @internal
+ */
+export type FilesystemOf<T extends Backend> = T extends Backend<infer FS> ? FS : never;
 /**
  * @internal
  */
@@ -63,7 +72,7 @@ export declare function isBackend(arg: unknown): arg is Backend;
  * Checks that the given options object is valid for the file system options.
  * @internal
  */
-export declare function checkOptions<T extends Backend>(backend: T, opts: Partial<OptionsOf<T>> & Record<string, unknown>): Promise<void>;
+export declare function checkOptions<T extends Backend>(backend: T, opts: Record<string, unknown>): Promise<void>;
 /**
  * Specifies a file system backend type and its options.
  *
@@ -72,11 +81,12 @@ export declare function checkOptions<T extends Backend>(backend: T, opts: Partia
  *
  * The option object for each file system corresponds to that file system's option object passed to its `Create()` method.
  */
-export type BackendConfiguration<T extends Backend = Backend> = OptionsOf<T> & {
+export type BackendConfiguration<T extends Backend> = OptionsOf<T> & {
     backend: T;
+    disableAsyncCache?: boolean;
 };
 /**
  * @internal
  */
-export declare function isBackendConfig(arg: unknown): arg is BackendConfiguration;
+export declare function isBackendConfig<T extends Backend>(arg: unknown): arg is BackendConfiguration<T>;
 export {};

package/dist/backends/fetch.d.ts

@@ -1,7 +1,7 @@
-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';
+import { IndexFS } from './index/fs.js';
+import type { IndexData } from './index/index.js';
 /**
  * Configuration options for FetchFS.
  */
@@ -10,60 +10,47 @@ 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;
+    index?: string | IndexData;
     /** 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.
+ * A simple filesystem backed by HTTP using the `fetch` API.
  *
  *
- * Listings objects look like the following:
+ * Index objects look like the following:
  *
  * ```json
  * {
- *   "home": {
- *     "jvilk": {
- *       "someFile.txt": null,
- *       "someDir": {
- *         // Empty directory
- *       }
- *     }
- *   }
+ * 	"version": 1,
+ * 	"entries": {
+ * 		"/home": { ... },
+ * 		"/home/jvilk": { ... },
+ * 		"/home/james": { ... }
+ * 	}
  * }
  * ```
  *
- * This example has the folder `/home/jvilk` with subfile `someFile.txt` and subfolder `someDir`.
+ * Each entry contains the stats associated with the file.
  */
-export declare class FetchFS extends AsyncIndexFS<Stats> {
-    readonly prefixUrl: string;
-    protected _init: Promise<void>;
-    protected _initialize(index: string | ListingTree): Promise<void>;
+export declare class FetchFS extends IndexFS {
+    readonly baseUrl: string;
     ready(): Promise<void>;
     constructor({ index, baseUrl }: FetchOptions);
     metadata(): FileSystemMetadata;
-    empty(): void;
     /**
-     * Special function: Preload the given file into the index.
+     * 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;
+    preload(path: string, buffer: Uint8Array): void;
     /**
-     * Asynchronously download the given file.
+     * @todo Be lazier about actually requesting the data?
      */
-    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>;
+    protected getData(path: string, stats: Stats): Promise<Uint8Array>;
+    protected getDataSync(path: string, stats: Stats): Uint8Array;
 }
 export declare const Fetch: {
     readonly name: "Fetch";

package/dist/backends/fetch.js

@@ -1,7 +1,5 @@
-import { ErrnoError, Errno } from '../error.js';
-import { NoSyncFile } from '../file.js';
-import { Stats } from '../stats.js';
-import { FileIndex, AsyncIndexFS } from './Index.js';
+import { Errno, ErrnoError } from '../error.js';
+import { IndexFS } from './index/fs.js';
 async function fetchFile(path, type) {
     const response = await fetch(path).catch(e => {
         throw new ErrnoError(Errno.EIO, e.message);
@@ -24,64 +22,44 @@ async function fetchFile(path, type) {
     }
 }
 /**
- * Asynchronously retrieves the size of the given file in bytes.
- * @hidden
- */
-async function fetchSize(path) {
-    const response = await fetch(path, { method: 'HEAD' }).catch(e => {
-        throw new ErrnoError(Errno.EIO, e.message);
-    });
-    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.
+ * A simple filesystem backed by HTTP using the `fetch` API.
  *
  *
- * Listings objects look like the following:
+ * Index objects look like the following:
  *
  * ```json
  * {
- *   "home": {
- *     "jvilk": {
- *       "someFile.txt": null,
- *       "someDir": {
- *         // Empty directory
- *       }
- *     }
- *   }
+ * 	"version": 1,
+ * 	"entries": {
+ * 		"/home": { ... },
+ * 		"/home/jvilk": { ... },
+ * 		"/home/james": { ... }
+ * 	}
  * }
  * ```
  *
- * This example has the folder `/home/jvilk` with subfile `someFile.txt` and subfolder `someDir`.
+ * Each entry contains the stats associated with the file.
  */
-export class FetchFS extends AsyncIndexFS {
-    async _initialize(index) {
-        if (typeof index != 'string') {
-            this._index = FileIndex.FromListing(index);
+export class FetchFS extends IndexFS {
+    async ready() {
+        if (this._isInitialized) {
             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');
+        await super.ready();
+        /**
+         * Iterate over all of the files and cache their contents
+         */
+        for (const [path, stats] of this.index.files()) {
+            await this.getData(path, stats);
         }
     }
-    async ready() {
-        await this._init;
-    }
     constructor({ index = 'index.json', baseUrl = '' }) {
-        super({});
+        super(typeof index != 'string' ? index : fetchFile(index, 'json'));
         // prefix url must end in a directory separator.
         if (baseUrl.at(-1) != '/') {
             baseUrl += '/';
         }
-        this.prefixUrl = baseUrl;
-        this._init = this._initialize(index);
+        this.baseUrl = baseUrl;
     }
     metadata() {
         return {
@@ -90,63 +68,38 @@ export class FetchFS extends AsyncIndexFS {
             readonly: true,
         };
     }
-    empty() {
-        for (const file of this._index.files()) {
-            delete file.data.fileData;
-        }
-    }
     /**
-     * Special function: Preload the given file into the index.
+     * Preload the given file into the index.
      * @param path
      * @param buffer
      */
-    preloadFile(path, buffer) {
-        const inode = this._index.get(path);
-        if (!inode) {
+    preload(path, buffer) {
+        const stats = this.index.get(path);
+        if (!stats) {
             throw ErrnoError.With('ENOENT', path, 'preloadFile');
         }
-        if (!inode.isFile()) {
+        if (!stats.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.
+    /**
+     * @todo Be lazier about actually requesting the data?
+     */
+    async getData(path, stats) {
         if (stats.fileData) {
-            return new NoSyncFile(this, path, flag, new Stats(stats), stats.fileData);
+            return 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;
+        const data = await fetchFile(this.baseUrl + (path.startsWith('/') ? path.slice(1) : path), 'buffer');
         stats.fileData = data;
-        return new NoSyncFile(this, path, flag, new Stats(stats), data);
+        return data;
     }
-    _getRemotePath(filePath) {
-        if (filePath.charAt(0) === '/') {
-            filePath = filePath.slice(1);
+    getDataSync(path, stats) {
+        if (stats.fileData) {
+            return stats.fileData;
         }
-        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));
+        throw new ErrnoError(Errno.ENODATA, '', path, 'getData');
     }
 }
 export const Fetch = {

package/dist/backends/index/fs.d.ts

@@ -0,0 +1,49 @@
+import type { Cred } from '../../cred.js';
+import { NoSyncFile } from '../../file.js';
+import { FileSystem } from '../../filesystem.js';
+import type { Stats } from '../../stats.js';
+import { Index, IndexData } from './index.js';
+declare const IndexFS_base: (abstract new (...args: any[]) => {
+    metadata(): import("../../filesystem.js").FileSystemMetadata;
+    rename(oldPath: string, newPath: string, cred: Cred): Promise<void>;
+    renameSync(oldPath: string, newPath: string, cred: Cred): void;
+    createFile(path: string, flag: string, mode: number, cred: Cred): Promise<import("../../file.js").File>;
+    createFileSync(path: string, flag: string, mode: number, cred: Cred): import("../../file.js").File;
+    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;
+    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>;
+    syncSync(path: string, data: Uint8Array, stats: Readonly<Stats>): void;
+    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>;
+    openFileSync(path: string, flag: string, cred: Cred): import("../../file.js").File;
+    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;
+}) & typeof FileSystem;
+export declare abstract class IndexFS extends IndexFS_base {
+    private indexData;
+    protected index: Index;
+    protected _isInitialized: boolean;
+    ready(): Promise<void>;
+    constructor(indexData: IndexData | Promise<IndexData>);
+    reloadFiles(): Promise<void>;
+    reloadFilesSync(): void;
+    stat(path: string): Promise<Stats>;
+    statSync(path: string): Stats;
+    openFile(path: string, flag: string, cred: Cred): Promise<NoSyncFile<this>>;
+    openFileSync(path: string, flag: string, cred: Cred): NoSyncFile<this>;
+    readdir(path: string): Promise<string[]>;
+    readdirSync(path: string): string[];
+    protected abstract getData(path: string, stats: Stats): Promise<Uint8Array>;
+    protected abstract getDataSync(path: string, stats: Stats): Uint8Array;
+}
+export {};

package/dist/backends/index/fs.js

@@ -0,0 +1,86 @@
+import { ErrnoError, Errno } from '../../error.js';
+import { NoSyncFile, isWriteable, flagToMode } from '../../file.js';
+import { Readonly, FileSystem } from '../../filesystem.js';
+import { decode } from '../../utils.js';
+import { Index } from './index.js';
+export class IndexFS extends Readonly(FileSystem) {
+    async ready() {
+        await super.ready();
+        if (this._isInitialized) {
+            return;
+        }
+        this.index.fromJSON(await this.indexData);
+        this._isInitialized = true;
+    }
+    constructor(indexData) {
+        super();
+        this.indexData = indexData;
+        this.index = new Index();
+        this._isInitialized = false;
+    }
+    async reloadFiles() {
+        for (const [path, stats] of this.index.files()) {
+            delete stats.fileData;
+            stats.fileData = await this.getData(path, stats);
+        }
+    }
+    reloadFilesSync() {
+        for (const [path, stats] of this.index.files()) {
+            delete stats.fileData;
+            stats.fileData = this.getDataSync(path, stats);
+        }
+    }
+    async stat(path) {
+        return this.statSync(path);
+    }
+    statSync(path) {
+        if (!this.index.has(path)) {
+            throw ErrnoError.With('ENOENT', path, 'stat');
+        }
+        return this.index.get(path);
+    }
+    async openFile(path, flag, cred) {
+        if (isWriteable(flag)) {
+            // You can't write to files on this file system.
+            throw new ErrnoError(Errno.EPERM, path);
+        }
+        // Check if the path exists, and is a file.
+        const stats = this.index.get(path);
+        if (!stats) {
+            throw ErrnoError.With('ENOENT', path, 'openFile');
+        }
+        if (!stats.hasAccess(flagToMode(flag), cred)) {
+            throw ErrnoError.With('EACCES', path, 'openFile');
+        }
+        return new NoSyncFile(this, path, flag, stats, stats.isDirectory() ? stats.fileData : await this.getData(path, stats));
+    }
+    openFileSync(path, flag, cred) {
+        if (isWriteable(flag)) {
+            // You can't write to files on this file system.
+            throw new ErrnoError(Errno.EPERM, path);
+        }
+        // Check if the path exists, and is a file.
+        const stats = this.index.get(path);
+        if (!stats) {
+            throw ErrnoError.With('ENOENT', path, 'openFile');
+        }
+        if (!stats.hasAccess(flagToMode(flag), cred)) {
+            throw ErrnoError.With('EACCES', path, 'openFile');
+        }
+        return new NoSyncFile(this, path, flag, stats, stats.isDirectory() ? stats.fileData : this.getDataSync(path, stats));
+    }
+    async readdir(path) {
+        return this.readdirSync(path);
+    }
+    readdirSync(path) {
+        // Check if it exists.
+        const stats = this.index.get(path);
+        if (!stats) {
+            throw ErrnoError.With('ENOENT', path, 'readdir');
+        }
+        if (!stats.isDirectory()) {
+            throw ErrnoError.With('ENOTDIR', path, 'readdir');
+        }
+        return JSON.parse(decode(stats.fileData));
+    }
+}

package/dist/backends/index/index.d.ts

@@ -0,0 +1,42 @@
+import { Stats, StatsLike } from '../../stats.js';
+/**
+ * An Index in JSON form
+ * @internal
+ */
+export interface IndexData {
+    version: 1;
+    entries: Record<string, StatsLike<number>>;
+}
+export declare const version = 1;
+/**
+ * An index of files
+ * @internal
+ */
+export declare class Index extends Map<string, Stats> {
+    constructor();
+    /**
+     * Convience method
+     */
+    files(): Map<string, Stats>;
+    /**
+     * Converts the index to JSON
+     */
+    toJSON(): IndexData;
+    /**
+     * Converts the index to a string
+     */
+    toString(): string;
+    /**
+     * Returns the files in the directory `dir`.
+     * This is expensive so it is only called once per directory.
+     */
+    protected dirEntries(dir: string): string[];
+    /**
+     * Loads the index from JSON data
+     */
+    fromJSON(json: IndexData): void;
+    /**
+     * Parses an index from a string
+     */
+    static parse(data: string): Index;
+}

package/dist/backends/index/index.js

@@ -0,0 +1,83 @@
+import { isJSON } from 'utilium';
+import { Errno, ErrnoError } from '../../error.js';
+import { Stats } from '../../stats.js';
+import { encode } from '../../utils.js';
+import { basename, dirname } from '../../emulation/path.js';
+export const version = 1;
+/**
+ * An index of files
+ * @internal
+ */
+export class Index extends Map {
+    constructor() {
+        super();
+    }
+    /**
+     * Convience method
+     */
+    files() {
+        const files = new Map();
+        for (const [path, stats] of this) {
+            if (stats.isFile()) {
+                files.set(path, stats);
+            }
+        }
+        return files;
+    }
+    /**
+     * Converts the index to JSON
+     */
+    toJSON() {
+        return {
+            version,
+            entries: Object.fromEntries(this),
+        };
+    }
+    /**
+     * Converts the index to a string
+     */
+    toString() {
+        return JSON.stringify(this.toJSON());
+    }
+    /**
+     * Returns the files in the directory `dir`.
+     * This is expensive so it is only called once per directory.
+     */
+    dirEntries(dir) {
+        const entries = [];
+        for (const entry of this.keys()) {
+            if (dirname(entry) == dir) {
+                entries.push(basename(entry));
+            }
+        }
+        return entries;
+    }
+    /**
+     * Loads the index from JSON data
+     */
+    fromJSON(json) {
+        if (json.version != version) {
+            throw new ErrnoError(Errno.EINVAL, 'Index version mismatch');
+        }
+        this.clear();
+        for (const [path, data] of Object.entries(json.entries)) {
+            const stats = new Stats(data);
+            if (stats.isDirectory()) {
+                stats.fileData = encode(JSON.stringify(this.dirEntries(path)));
+            }
+            this.set(path, stats);
+        }
+    }
+    /**
+     * Parses an index from a string
+     */
+    static parse(data) {
+        if (!isJSON(data)) {
+            throw new ErrnoError(Errno.EINVAL, 'Invalid JSON');
+        }
+        const json = JSON.parse(data);
+        const index = new Index();
+        index.fromJSON(json);
+        return index;
+    }
+}

package/dist/backends/port/fs.d.ts

@@ -40,7 +40,8 @@ export declare class PortFile extends File {
 type FSMethods = ExtractProperties<FileSystem, (...args: any[]) => Promise<any> | FileSystemMetadata>;
 type FSMethod = keyof FSMethods;
 declare const PortFS_base: (abstract new (...args: any[]) => {
-    _sync: FileSystem;
+    _disableSync: boolean;
+    _sync?: FileSystem | undefined;
     queueDone(): Promise<void>;
     metadata(): FileSystemMetadata;
     ready(): Promise<void>;