@emdzej/bimmerz-vfs 0.1.0 → 0.2.0

package/dist/cache.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Storage backend for `CachedHttpDirectory`. Two implementations:
+ *
+ *   • **OPFS** (Origin Private File System) — preferred. Real
+ *     filesystem semantics inside the browser sandbox, no quota
+ *     prompts on writes ≤ 1 GB, and survives across tabs / refreshes.
+ *     Requires Chrome 86+ / Safari 16+ / Firefox 111+ (gated on
+ *     `navigator.storage.getDirectory`).
+ *   • **IndexedDB** — fallback. Same durability story but with the
+ *     awkward request/cursor API. Works everywhere.
+ *
+ * Each cached entry has TWO pieces:
+ *
+ *   1. The raw response bytes (one blob per key).
+ *   2. A small metadata record (`etag`, `last-modified`, `storedAt`,
+ *      `validatedAt`, `url`). Used by `CachedHttpDirectory` to make
+ *      conditional-GET requests and to surface staleness in `stats()`.
+ *
+ * The OPFS layout stores them as sibling files: `<key>` and
+ * `<key>.meta`. The IDB layout merges them into one object-store
+ * row keyed by `<key>`.
+ *
+ * Keys are origin-scoped: every backend instance is namespaced by a
+ * caller-supplied string (typically a hash of the `baseUrl`). The
+ * namespace is the OPFS subdirectory or the IDB key prefix. Clearing
+ * a namespace wipes one consumer's cache without touching anything
+ * else.
+ */
+/** Per-entry metadata persisted alongside the bytes. */
+export interface CacheMetadata {
+    /** Original request URL. Useful for telemetry / debugging. */
+    url: string;
+    /** Strong / weak ETag header value, if the server returned one. */
+    etag?: string;
+    /** `Last-Modified` header value (RFC 7231 IMF-fixdate). */
+    lastModified?: string;
+    /** Content-Type header, captured so callers can serve via Response. */
+    contentType?: string;
+    /** Bytes (length of the data blob; redundant with the blob but
+     *  cheap to keep — lets `stats()` answer without reading every file). */
+    size: number;
+    /** Wall-clock ms when the body was first stored. */
+    storedAt: number;
+    /** Wall-clock ms when the body was last confirmed fresh (200 or
+     *  304). Drives the `maxAgeMs` staleness check. */
+    validatedAt: number;
+}
+/** Combined entry returned from `get()`. */
+export interface CacheEntry {
+    bytes: ArrayBuffer;
+    meta: CacheMetadata;
+}
+/** What every backend must implement. Async by necessity — both
+ *  OPFS and IDB are Promise-only. */
+export interface CacheBackend {
+    /** Backend name, surfaced in `stats()` so consumers can show the
+     *  user which path the cache landed on. */
+    readonly kind: 'opfs' | 'idb' | 'memory';
+    get(key: string): Promise<CacheEntry | null>;
+    put(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** List keys with optional prefix filter. Order is unspecified. */
+    keys(prefix?: string): Promise<string[]>;
+    /** Remove every entry whose key starts with `prefix` (or all if
+     *  no prefix is given). */
+    clear(prefix?: string): Promise<void>;
+    /** Aggregate counts for `stats()`. */
+    size(prefix?: string): Promise<{
+        entries: number;
+        totalBytes: number;
+    }>;
+}
+/** Implementation of `CacheBackend` over OPFS. Construct via
+ *  `OpfsCacheBackend.open()` which resolves the root directory; the
+ *  promise rejects when OPFS isn't available so callers can fall
+ *  back to IDB. */
+export declare class OpfsCacheBackend implements CacheBackend {
+    #private;
+    readonly kind: "opfs";
+    private constructor();
+    static open(namespace: string): Promise<OpfsCacheBackend>;
+    get(key: string): Promise<CacheEntry | null>;
+    put(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(prefix?: string): Promise<string[]>;
+    clear(prefix?: string): Promise<void>;
+    size(prefix?: string): Promise<{
+        entries: number;
+        totalBytes: number;
+    }>;
+}
+/** Implementation of `CacheBackend` over IndexedDB. Construct via
+ *  `IdbCacheBackend.open()`; one shared connection per origin is
+ *  cached at the module level. */
+export declare class IdbCacheBackend implements CacheBackend {
+    #private;
+    readonly kind: "idb";
+    constructor(namespace: string);
+    static open(namespace: string): Promise<IdbCacheBackend>;
+    get(key: string): Promise<CacheEntry | null>;
+    put(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(prefix?: string): Promise<string[]>;
+    clear(prefix?: string): Promise<void>;
+    size(prefix?: string): Promise<{
+        entries: number;
+        totalBytes: number;
+    }>;
+}
+/** In-memory backend. Doesn't persist anything — used by tests and
+ *  as a graceful no-op when neither OPFS nor IDB is available. */
+export declare class MemoryCacheBackend implements CacheBackend {
+    #private;
+    readonly kind: "memory";
+    constructor(namespace: string);
+    get(key: string): Promise<CacheEntry | null>;
+    put(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(prefix?: string): Promise<string[]>;
+    clear(prefix?: string): Promise<void>;
+    size(prefix?: string): Promise<{
+        entries: number;
+        totalBytes: number;
+    }>;
+}
+export interface OpenCacheOptions {
+    /** Namespace for this cache instance. Typically a stable hash of
+     *  the consumer's baseUrl so different `CachedHttpDirectory`
+     *  instances don't trample each other. */
+    namespace: string;
+    /** Force a specific backend. Default: try OPFS, fall back to IDB,
+     *  fall back to memory. */
+    prefer?: 'opfs' | 'idb' | 'memory';
+}
+/** Pick the best available backend at runtime. Returns the
+ *  preferred one if it works, otherwise walks the fallback chain. */
+export declare function openCacheBackend(options: OpenCacheOptions): Promise<CacheBackend>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/cache.js

@@ -0,0 +1,368 @@
+/**
+ * Storage backend for `CachedHttpDirectory`. Two implementations:
+ *
+ *   • **OPFS** (Origin Private File System) — preferred. Real
+ *     filesystem semantics inside the browser sandbox, no quota
+ *     prompts on writes ≤ 1 GB, and survives across tabs / refreshes.
+ *     Requires Chrome 86+ / Safari 16+ / Firefox 111+ (gated on
+ *     `navigator.storage.getDirectory`).
+ *   • **IndexedDB** — fallback. Same durability story but with the
+ *     awkward request/cursor API. Works everywhere.
+ *
+ * Each cached entry has TWO pieces:
+ *
+ *   1. The raw response bytes (one blob per key).
+ *   2. A small metadata record (`etag`, `last-modified`, `storedAt`,
+ *      `validatedAt`, `url`). Used by `CachedHttpDirectory` to make
+ *      conditional-GET requests and to surface staleness in `stats()`.
+ *
+ * The OPFS layout stores them as sibling files: `<key>` and
+ * `<key>.meta`. The IDB layout merges them into one object-store
+ * row keyed by `<key>`.
+ *
+ * Keys are origin-scoped: every backend instance is namespaced by a
+ * caller-supplied string (typically a hash of the `baseUrl`). The
+ * namespace is the OPFS subdirectory or the IDB key prefix. Clearing
+ * a namespace wipes one consumer's cache without touching anything
+ * else.
+ */
+/* ── OPFS backend ──────────────────────────────────────────────── */
+/** OPFS file naming:
+ *
+ *   <root>/<namespace>/<encoded-key>        ← raw bytes
+ *   <root>/<namespace>/<encoded-key>.meta   ← JSON metadata
+ *
+ *  `root` defaults to `bimmerz-vfs-cache`. Keys are URL-encoded so
+ *  any character is safe — OPFS rejects `/` in names which we'd
+ *  otherwise hit constantly. */
+const OPFS_ROOT = 'bimmerz-vfs-cache';
+const META_SUFFIX = '.meta';
+function encodeKey(key) {
+    /* Replace forbidden OPFS characters. encodeURIComponent handles
+       most, but `:` (in URLs) is rejected on some platforms — strip
+       it explicitly. */
+    return encodeURIComponent(key).replace(/:/g, '%3A');
+}
+function decodeKey(encoded) {
+    return decodeURIComponent(encoded);
+}
+/** Implementation of `CacheBackend` over OPFS. Construct via
+ *  `OpfsCacheBackend.open()` which resolves the root directory; the
+ *  promise rejects when OPFS isn't available so callers can fall
+ *  back to IDB. */
+export class OpfsCacheBackend {
+    kind = 'opfs';
+    #root;
+    constructor(root) {
+        this.#root = root;
+    }
+    static async open(namespace) {
+        if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory) {
+            throw new Error('OPFS not available');
+        }
+        const opfs = await navigator.storage.getDirectory();
+        const cacheRoot = await opfs.getDirectoryHandle(OPFS_ROOT, { create: true });
+        const nsDir = await cacheRoot.getDirectoryHandle(encodeKey(namespace), { create: true });
+        return new OpfsCacheBackend(nsDir);
+    }
+    async get(key) {
+        const encoded = encodeKey(key);
+        try {
+            const [bodyFile, metaFile] = await Promise.all([
+                this.#root.getFileHandle(encoded),
+                this.#root.getFileHandle(encoded + META_SUFFIX),
+            ]);
+            const [bodyBlob, metaBlob] = await Promise.all([
+                bodyFile.getFile(),
+                metaFile.getFile(),
+            ]);
+            const [bytes, metaText] = await Promise.all([
+                bodyBlob.arrayBuffer(),
+                metaBlob.text(),
+            ]);
+            const meta = JSON.parse(metaText);
+            return { bytes, meta };
+        }
+        catch {
+            /* `getFileHandle` throws when the entry doesn't exist; any
+               other failure (corrupted JSON, partial write from a prior
+               crash) is also treated as a cache miss so the caller falls
+               back to a real fetch rather than serving garbage. */
+            return null;
+        }
+    }
+    async put(key, entry) {
+        const encoded = encodeKey(key);
+        /* Write metadata FIRST so a crash mid-put leaves stale meta +
+           missing body rather than fresh body + stale meta. The reader
+           handles missing files defensively, so either failure mode
+           reads as a cache miss. */
+        const [bodyHandle, metaHandle] = await Promise.all([
+            this.#root.getFileHandle(encoded, { create: true }),
+            this.#root.getFileHandle(encoded + META_SUFFIX, { create: true }),
+        ]);
+        const metaWriter = await metaHandle.createWritable();
+        await metaWriter.write(JSON.stringify(entry.meta));
+        await metaWriter.close();
+        const bodyWriter = await bodyHandle.createWritable();
+        await bodyWriter.write(entry.bytes);
+        await bodyWriter.close();
+    }
+    async delete(key) {
+        const encoded = encodeKey(key);
+        await Promise.allSettled([
+            this.#root.removeEntry(encoded),
+            this.#root.removeEntry(encoded + META_SUFFIX),
+        ]);
+    }
+    async keys(prefix) {
+        const out = [];
+        /* The iterator API isn't typed yet on FileSystemDirectoryHandle
+           in some lib targets; cast through `unknown`. */
+        const dir = this.#root;
+        for await (const handle of dir.values()) {
+            if (handle.kind !== 'file')
+                continue;
+            if (handle.name.endsWith(META_SUFFIX))
+                continue;
+            const key = decodeKey(handle.name);
+            if (prefix && !key.startsWith(prefix))
+                continue;
+            out.push(key);
+        }
+        return out;
+    }
+    async clear(prefix) {
+        const keys = await this.keys(prefix);
+        await Promise.all(keys.map((k) => this.delete(k)));
+    }
+    async size(prefix) {
+        const keys = await this.keys(prefix);
+        let totalBytes = 0;
+        /* We pull byte sizes from metadata (no full body read needed). */
+        await Promise.all(keys.map(async (key) => {
+            const meta = await this.#readMeta(key);
+            if (meta)
+                totalBytes += meta.size;
+        }));
+        return { entries: keys.length, totalBytes };
+    }
+    async #readMeta(key) {
+        try {
+            const handle = await this.#root.getFileHandle(encodeKey(key) + META_SUFFIX);
+            const blob = await handle.getFile();
+            return JSON.parse(await blob.text());
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/* ── IDB backend ───────────────────────────────────────────────── */
+/** Stable DB name. One DB per origin, one object store keyed by
+ *  `${namespace}:${key}` so all consumers share a single connection. */
+const IDB_NAME = 'bimmerz-vfs-cache';
+const IDB_STORE = 'entries';
+const IDB_VERSION = 1;
+/** Implementation of `CacheBackend` over IndexedDB. Construct via
+ *  `IdbCacheBackend.open()`; one shared connection per origin is
+ *  cached at the module level. */
+export class IdbCacheBackend {
+    kind = 'idb';
+    #namespace;
+    #dbPromise;
+    constructor(namespace) {
+        this.#namespace = namespace;
+        this.#dbPromise = openDb();
+    }
+    static async open(namespace) {
+        if (typeof indexedDB === 'undefined') {
+            throw new Error('IndexedDB not available');
+        }
+        const instance = new IdbCacheBackend(namespace);
+        /* Eagerly resolve the DB connection so a failure surfaces
+           at construction time rather than first-use. */
+        await instance.#dbPromise;
+        return instance;
+    }
+    #rowKey(key) {
+        return `${this.#namespace}:${key}`;
+    }
+    async get(key) {
+        const db = await this.#dbPromise;
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const req = tx.objectStore(IDB_STORE).get(this.#rowKey(key));
+            req.onsuccess = () => {
+                const row = req.result;
+                resolve(row ? { bytes: row.bytes, meta: row.meta } : null);
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async put(key, entry) {
+        const db = await this.#dbPromise;
+        const row = {
+            k: this.#rowKey(key),
+            ns: this.#namespace,
+            bytes: entry.bytes,
+            meta: entry.meta,
+        };
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readwrite');
+            const req = tx.objectStore(IDB_STORE).put(row);
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async delete(key) {
+        const db = await this.#dbPromise;
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readwrite');
+            const req = tx.objectStore(IDB_STORE).delete(this.#rowKey(key));
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async keys(prefix) {
+        const db = await this.#dbPromise;
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const req = tx.objectStore(IDB_STORE).index('ns').openKeyCursor(IDBKeyRange.only(this.#namespace));
+            const out = [];
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (!cursor)
+                    return resolve(out);
+                const rowKey = String(cursor.primaryKey);
+                const key = rowKey.slice(this.#namespace.length + 1);
+                if (!prefix || key.startsWith(prefix))
+                    out.push(key);
+                cursor.continue();
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async clear(prefix) {
+        const keys = await this.keys(prefix);
+        await Promise.all(keys.map((k) => this.delete(k)));
+    }
+    async size(prefix) {
+        const db = await this.#dbPromise;
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const req = tx.objectStore(IDB_STORE).index('ns').openCursor(IDBKeyRange.only(this.#namespace));
+            let entries = 0;
+            let totalBytes = 0;
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (!cursor)
+                    return resolve({ entries, totalBytes });
+                const row = cursor.value;
+                const key = row.k.slice(this.#namespace.length + 1);
+                if (!prefix || key.startsWith(prefix)) {
+                    entries += 1;
+                    totalBytes += row.meta.size;
+                }
+                cursor.continue();
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+}
+function openDb() {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open(IDB_NAME, IDB_VERSION);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            const store = db.createObjectStore(IDB_STORE, { keyPath: 'k' });
+            store.createIndex('ns', 'ns', { unique: false });
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+/* ── Memory backend (for tests + SSR) ─────────────────────────── */
+/** In-memory backend. Doesn't persist anything — used by tests and
+ *  as a graceful no-op when neither OPFS nor IDB is available. */
+export class MemoryCacheBackend {
+    kind = 'memory';
+    #store = new Map();
+    #namespace;
+    constructor(namespace) {
+        this.#namespace = namespace;
+    }
+    #ns(key) {
+        return `${this.#namespace}:${key}`;
+    }
+    async get(key) {
+        const e = this.#store.get(this.#ns(key));
+        return e ? { bytes: e.bytes, meta: { ...e.meta } } : null;
+    }
+    async put(key, entry) {
+        this.#store.set(this.#ns(key), entry);
+    }
+    async delete(key) {
+        this.#store.delete(this.#ns(key));
+    }
+    async keys(prefix) {
+        const out = [];
+        for (const k of this.#store.keys()) {
+            if (!k.startsWith(`${this.#namespace}:`))
+                continue;
+            const local = k.slice(this.#namespace.length + 1);
+            if (!prefix || local.startsWith(prefix))
+                out.push(local);
+        }
+        return out;
+    }
+    async clear(prefix) {
+        for (const k of [...this.#store.keys()]) {
+            if (!k.startsWith(`${this.#namespace}:`))
+                continue;
+            const local = k.slice(this.#namespace.length + 1);
+            if (!prefix || local.startsWith(prefix))
+                this.#store.delete(k);
+        }
+    }
+    async size(prefix) {
+        let entries = 0;
+        let totalBytes = 0;
+        for (const [k, v] of this.#store) {
+            if (!k.startsWith(`${this.#namespace}:`))
+                continue;
+            const local = k.slice(this.#namespace.length + 1);
+            if (prefix && !local.startsWith(prefix))
+                continue;
+            entries += 1;
+            totalBytes += v.meta.size;
+        }
+        return { entries, totalBytes };
+    }
+}
+/** Pick the best available backend at runtime. Returns the
+ *  preferred one if it works, otherwise walks the fallback chain. */
+export async function openCacheBackend(options) {
+    const order = options.prefer
+        ? options.prefer === 'opfs'
+            ? ['opfs', 'idb', 'memory']
+            : options.prefer === 'idb'
+                ? ['idb', 'memory']
+                : ['memory']
+        : ['opfs', 'idb', 'memory'];
+    let lastError;
+    for (const kind of order) {
+        try {
+            if (kind === 'opfs')
+                return await OpfsCacheBackend.open(options.namespace);
+            if (kind === 'idb')
+                return await IdbCacheBackend.open(options.namespace);
+            return new MemoryCacheBackend(options.namespace);
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    throw new Error(`No usable cache backend (last error: ${lastError instanceof Error ? lastError.message : String(lastError)})`);
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/cached-http.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `CachedHttpDirectory` — drop-in replacement for `HttpDirectory`
+ * that persists fetched bytes (index + files) in OPFS (preferred)
+ * or IndexedDB.
+ *
+ * Why a wrapper, not changes to `HttpDirectory`: the base class is
+ * the right minimum surface for read-only HTTP. Caching is an
+ * orthogonal concern that some consumers don't want (development,
+ * one-shot CLI tools). Keeping the two separate also means a bug in
+ * the cache layer can't poison the simple path.
+ *
+ * What gets cached:
+ *
+ *   • The `index.json` per directory.
+ *   • The body of every `file(name).arrayBuffer()` call.
+ *
+ * Staleness policy: **stale-while-revalidate.**
+ *
+ *   • First read of any URL: do a normal fetch, store body + ETag +
+ *     Last-Modified + the `Content-Type`, return.
+ *   • Subsequent reads inside `maxAgeMs` (default 5 min): serve
+ *     cached bytes immediately, no network at all.
+ *   • Subsequent reads OUTSIDE `maxAgeMs`: serve cached bytes
+ *     immediately AND kick off a background conditional GET (`If-
+ *     None-Match` / `If-Modified-Since`). When the server replies:
+ *       - `304 Not Modified` → bump `validatedAt`. Body untouched.
+ *       - `200 OK` → write the new body to cache. The next call
+ *         then sees the fresh bytes.
+ *   • Explicit `revalidate(file)` forces an immediate conditional
+ *     fetch and returns once the network response settles.
+ *
+ * The first-after-update read returns the OLD bytes. That's the
+ * standard SWR tradeoff — favours latency over freshness, lets
+ * the dashboard render instantly on every load.
+ */
+import type { VirtualFile, VirtualDirectory, VirtualEntry } from './types.js';
+import type { HttpDirectoryOptions } from './http.js';
+import { type CacheBackend } from './cache.js';
+/** Construction options for a `CachedHttpDirectory`. */
+export interface CachedHttpDirectoryOptions extends HttpDirectoryOptions {
+    /** Cache backend. If omitted, one is auto-selected from OPFS / IDB
+     *  / memory at first use. Sharing one backend across multiple
+     *  directories is fine — namespaces keep entries separate. */
+    backend?: CacheBackend;
+    /** Override the auto-selected backend kind. */
+    preferBackend?: 'opfs' | 'idb' | 'memory';
+    /**
+     * Namespace string for this directory's cached entries. Default:
+     * the baseUrl with its scheme stripped. Two `CachedHttpDirectory`
+     * instances sharing a namespace share their cache — usually fine
+     * (same baseUrl = same content) but expose the knob for testing
+     * and for the case where two CDN URLs serve the same content and
+     * you want one cache hit covering both.
+     */
+    namespace?: string;
+    /**
+     * Optional canonicaliser for cache keys. Useful when URLs carry
+     * signed-token query strings that change per request — strip the
+     * token so equivalent URLs hit the same cache entry.
+     */
+    cacheKey?: (url: string) => string;
+    /**
+     * Cache entries are served without revalidation when their age is
+     * below this threshold. Default 5 min (300 000 ms). Set to 0 for
+     * always-revalidate, or `Infinity` for never-revalidate.
+     */
+    maxAgeMs?: number;
+}
+/** Public API exposed by every `CachedHttpDirectory` for cache
+ *  management — same surface across nested subdirs. */
+export interface CacheControl {
+    /** Bytes + entry count for this directory's namespace. */
+    stats(): Promise<{
+        backend: 'opfs' | 'idb' | 'memory';
+        entries: number;
+        totalBytes: number;
+    }>;
+    /** Drop every cached entry in this namespace. */
+    clear(): Promise<void>;
+    /** Force a fresh conditional GET on the given path. Resolves once
+     *  the cache is consistent with the server. */
+    revalidate(path: string): Promise<void>;
+    /** Force-refresh the index for this directory (subset of
+     *  `revalidate(<indexFile>)` exposed for clarity). */
+    revalidateIndex(): Promise<void>;
+}
+/** `VirtualFile` backed by a cache lookup + conditional fetch. */
+export declare class CachedHttpFile implements VirtualFile {
+    #private;
+    readonly name: string;
+    readonly size: number;
+    constructor(args: {
+        name: string;
+        size: number;
+        url: string;
+        fetch: typeof globalThis.fetch;
+        backend: Promise<CacheBackend>;
+        cacheKey: string;
+        maxAgeMs: number;
+    });
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Force a fresh conditional fetch and resolve once the cache is
+     *  consistent with the server. */
+    revalidate(): Promise<void>;
+}
+export declare class CachedHttpDirectory implements VirtualDirectory, CacheControl {
+    #private;
+    readonly name: string;
+    constructor(baseUrl: string, options?: CachedHttpDirectoryOptions);
+    file(name: string): Promise<VirtualFile | null>;
+    dir(name: string): Promise<VirtualDirectory | null>;
+    entries(): Promise<VirtualEntry[]>;
+    stats(): Promise<{
+        backend: 'opfs' | 'idb' | 'memory';
+        entries: number;
+        totalBytes: number;
+    }>;
+    clear(): Promise<void>;
+    revalidate(path: string): Promise<void>;
+    revalidateIndex(): Promise<void>;
+}
+//# sourceMappingURL=cached-http.d.ts.map

package/dist/cached-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-http.d.ts","sourceRoot":"","sources":["../src/cached-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAEL,KAAK,YAAY,EAGlB,MAAM,YAAY,CAAC;AAapB,wDAAwD;AACxD,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACtE;;kEAE8D;IAC9D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;uDACuD;AACvD,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,KAAK,IAAI,OAAO,CAAC;QACf,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;QACnC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,iDAAiD;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;mDAC+C;IAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC;0DACsD;IACtD,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAwBD,kEAAkE;AAClE,qBAAa,cAAe,YAAW,WAAW;;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAOV,IAAI,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;QAC/B,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QAC/B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB;IAUK,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IAwEzC;sCACkC;IAC5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAKlC;AAID,qBAAa,mBAAoB,YAAW,gBAAgB,EAAE,YAAY;;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAcV,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B;IA6B/D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAmB/C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAkBnD,OAAO,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAelC,KAAK,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAM7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBvC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvC"}