@dynlabs/react-native-immutable-file-cache 1.0.0-alpha.1

package/src/adapters/webAdapter.ts

@@ -0,0 +1,480 @@
+/**
+ * Web Storage Adapter
+ *
+ * Implements IStorageAdapter using:
+ * - Cache Storage API for binary file storage
+ * - IndexedDB for metadata and index storage
+ */
+
+import type {
+  IStorageAdapter,
+  TAdapterPath,
+  TBinarySource,
+  IBinaryWriteResult,
+  IBinaryWriteOptions,
+  IFileStat,
+} from "../core/adapter";
+import { UnsupportedSourceError, AdapterIOError } from "../core/errors";
+
+export interface IWebAdapterOptions {
+  /** Cache name for Cache Storage. @default "immutable-file-cache" */
+  readonly cacheName?: string;
+  /** IDB database name. @default "immutable-file-cache-meta" */
+  readonly idbName?: string;
+  /** Namespace. */
+  readonly namespace?: string;
+}
+
+interface IFileMetadata {
+  readonly sizeBytes: number;
+  readonly mtimeMs: number;
+  readonly contentType?: string;
+}
+
+const CACHE_URL_PREFIX = "https://cache.local";
+
+/**
+ * Creates a storage adapter for web platforms using Cache Storage and IndexedDB.
+ */
+export function createWebAdapter(options?: IWebAdapterOptions): IStorageAdapter {
+  const cacheName = options?.cacheName ?? "immutable-file-cache";
+  const idbName = options?.idbName ?? "immutable-file-cache-meta";
+  const namespace = options?.namespace ?? "default";
+  const rootId = `${cacheName}/${namespace}`;
+
+  // Track created blob URLs for cleanup
+  const blobUrls = new Set<string>();
+
+  /**
+   * Converts adapter path to cache URL key.
+   */
+  const toCacheKey = (path: TAdapterPath): string => {
+    return `${CACHE_URL_PREFIX}/${namespace}/${path}`;
+  };
+
+  /**
+   * Converts cache URL key back to adapter path.
+   */
+  const fromCacheKey = (url: string): TAdapterPath => {
+    const prefix = `${CACHE_URL_PREFIX}/${namespace}/`;
+    return url.startsWith(prefix) ? url.slice(prefix.length) : url;
+  };
+
+  /**
+   * Gets the IDB object store key for metadata.
+   */
+  const toMetaKey = (path: TAdapterPath): string => {
+    return `${namespace}/${path}`;
+  };
+
+  /**
+   * Opens or creates the IndexedDB database.
+   */
+  const openDB = (): Promise<IDBDatabase> => {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(idbName, 1);
+
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result);
+
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains("metadata")) {
+          db.createObjectStore("metadata");
+        }
+        if (!db.objectStoreNames.contains("directories")) {
+          db.createObjectStore("directories");
+        }
+      };
+    });
+  };
+
+  /**
+   * Gets metadata from IDB.
+   */
+  const getMetadata = async (path: TAdapterPath): Promise<IFileMetadata | null> => {
+    const db = await openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction("metadata", "readonly");
+      const store = tx.objectStore("metadata");
+      const request = store.get(toMetaKey(path));
+
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve((request.result as IFileMetadata | undefined) ?? null);
+
+      tx.oncomplete = () => db.close();
+    });
+  };
+
+  /**
+   * Sets metadata in IDB.
+   */
+  const setMetadata = async (path: TAdapterPath, meta: IFileMetadata): Promise<void> => {
+    const db = await openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction("metadata", "readwrite");
+      const store = tx.objectStore("metadata");
+      const request = store.put(meta, toMetaKey(path));
+
+      request.onerror = () => reject(request.error);
+      tx.oncomplete = () => {
+        db.close();
+        resolve();
+      };
+    });
+  };
+
+  /**
+   * Deletes metadata from IDB.
+   */
+  const deleteMetadata = async (path: TAdapterPath): Promise<void> => {
+    const db = await openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction("metadata", "readwrite");
+      const store = tx.objectStore("metadata");
+      const request = store.delete(toMetaKey(path));
+
+      request.onerror = () => reject(request.error);
+      tx.oncomplete = () => {
+        db.close();
+        resolve();
+      };
+    });
+  };
+
+  /**
+   * Marks a directory as existing in IDB.
+   */
+  const markDirectory = async (path: TAdapterPath): Promise<void> => {
+    const db = await openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction("directories", "readwrite");
+      const store = tx.objectStore("directories");
+      const request = store.put(true, toMetaKey(path));
+
+      request.onerror = () => reject(request.error);
+      tx.oncomplete = () => {
+        db.close();
+        resolve();
+      };
+    });
+  };
+
+  /**
+   * Checks if directory exists in IDB.
+   */
+  const hasDirectory = async (path: TAdapterPath): Promise<boolean> => {
+    const db = await openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction("directories", "readonly");
+      const store = tx.objectStore("directories");
+      const request = store.get(toMetaKey(path));
+
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result === true);
+
+      tx.oncomplete = () => db.close();
+    });
+  };
+
+  const adapter: IStorageAdapter = {
+    kind: "web",
+    rootId,
+
+    // ─────────────────────────────────────────────────────────────────
+    // Directory Management
+    // ─────────────────────────────────────────────────────────────────
+
+    async ensureDir(path: TAdapterPath): Promise<void> {
+      try {
+        await markDirectory(path);
+      } catch (error) {
+        throw new AdapterIOError("ensureDir", path, error as Error);
+      }
+    },
+
+    async exists(path: TAdapterPath): Promise<boolean> {
+      try {
+        // Check if it's a file in cache storage
+        const cache = await caches.open(cacheName);
+        const response = await cache.match(toCacheKey(path));
+        if (response) {
+          return true;
+        }
+
+        // Check if it's a directory
+        return await hasDirectory(path);
+      } catch {
+        return false;
+      }
+    },
+
+    async remove(path: TAdapterPath): Promise<void> {
+      try {
+        const cache = await caches.open(cacheName);
+        await cache.delete(toCacheKey(path));
+        await deleteMetadata(path);
+      } catch (error) {
+        throw new AdapterIOError("remove", path, error as Error);
+      }
+    },
+
+    async removeDir(path: TAdapterPath): Promise<void> {
+      try {
+        const cache = await caches.open(cacheName);
+        const keys = await cache.keys();
+        const prefix = toCacheKey(path + "/");
+
+        // Delete all entries with this prefix
+        for (const request of keys) {
+          if (request.url.startsWith(prefix) || request.url === toCacheKey(path)) {
+            await cache.delete(request);
+            const entryPath = fromCacheKey(request.url);
+            await deleteMetadata(entryPath);
+          }
+        }
+
+        // Remove directory marker
+        const db = await openDB();
+        await new Promise<void>((resolve, reject) => {
+          const tx = db.transaction("directories", "readwrite");
+          const store = tx.objectStore("directories");
+          store.delete(toMetaKey(path));
+          tx.oncomplete = () => {
+            db.close();
+            resolve();
+          };
+          tx.onerror = () => reject(tx.error);
+        });
+      } catch (error) {
+        throw new AdapterIOError("removeDir", path, error as Error);
+      }
+    },
+
+    async listDir(path: TAdapterPath): Promise<ReadonlyArray<TAdapterPath>> {
+      try {
+        const cache = await caches.open(cacheName);
+        const keys = await cache.keys();
+        const prefix = toCacheKey(path + "/");
+        const entries: TAdapterPath[] = [];
+
+        for (const request of keys) {
+          if (request.url.startsWith(prefix)) {
+            // Extract the relative path from this directory
+            const relativePath = request.url.slice(prefix.length);
+            // Only include direct children (no further slashes)
+            if (!relativePath.includes("/")) {
+              entries.push(relativePath);
+            }
+          }
+        }
+
+        return entries;
+      } catch (error) {
+        throw new AdapterIOError("listDir", path, error as Error);
+      }
+    },
+
+    // ─────────────────────────────────────────────────────────────────
+    // File I/O
+    // ─────────────────────────────────────────────────────────────────
+
+    async readText(path: TAdapterPath, _encoding: "utf8"): Promise<string> {
+      try {
+        const cache = await caches.open(cacheName);
+        const response = await cache.match(toCacheKey(path));
+        if (!response) {
+          throw new Error("File not found");
+        }
+        return await response.text();
+      } catch (error) {
+        throw new AdapterIOError("readText", path, error as Error);
+      }
+    },
+
+    async writeTextAtomic(path: TAdapterPath, content: string, _encoding: "utf8"): Promise<void> {
+      try {
+        const cache = await caches.open(cacheName);
+        const blob = new Blob([content], { type: "text/plain; charset=utf-8" });
+        const response = new Response(blob);
+
+        // Cache Storage puts are atomic by nature
+        await cache.put(toCacheKey(path), response);
+
+        // Store metadata
+        await setMetadata(path, {
+          sizeBytes: blob.size,
+          mtimeMs: Date.now(),
+          contentType: "text/plain",
+        });
+      } catch (error) {
+        throw new AdapterIOError("writeTextAtomic", path, error as Error);
+      }
+    },
+
+    async stat(path: TAdapterPath): Promise<IFileStat> {
+      try {
+        const meta = await getMetadata(path);
+        if (!meta) {
+          throw new Error("File not found");
+        }
+        return {
+          sizeBytes: meta.sizeBytes,
+          mtimeMs: meta.mtimeMs,
+        };
+      } catch (error) {
+        throw new AdapterIOError("stat", path, error as Error);
+      }
+    },
+
+    async writeBinaryAtomic(
+      path: TAdapterPath,
+      source: TBinarySource,
+      options?: IBinaryWriteOptions
+    ): Promise<IBinaryWriteResult> {
+      try {
+        const cache = await caches.open(cacheName);
+        let blob: Blob;
+        let contentType: string | undefined;
+
+        switch (source.type) {
+          case "url": {
+            // Fetch with progress tracking
+            const response = await fetch(source.url, {
+              headers: { ...source.headers, ...options?.headers },
+            });
+
+            if (!response.ok) {
+              throw new Error(`Fetch failed with status ${response.status}`);
+            }
+
+            contentType = response.headers.get("content-type") ?? undefined;
+
+            // Try to track progress if content-length is available
+            const contentLength = response.headers.get("content-length");
+            if (contentLength && options?.onProgress && response.body) {
+              const total = parseInt(contentLength, 10);
+              let loaded = 0;
+              const reader = response.body.getReader();
+              const chunks: Uint8Array[] = [];
+
+              // eslint-disable-next-line no-constant-condition
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                  break;
+                }
+                chunks.push(value);
+                loaded += value.length;
+                options.onProgress((loaded / total) * 100);
+              }
+
+              blob = new Blob(
+                chunks.map((c) => c.buffer as ArrayBuffer),
+                { type: contentType }
+              );
+            } else {
+              blob = await response.blob();
+              options?.onProgress?.(100);
+            }
+            break;
+          }
+
+          case "blob": {
+            blob = source.blob;
+            contentType = source.blob.type || undefined;
+            options?.onProgress?.(100);
+            break;
+          }
+
+          case "bytes": {
+            blob = new Blob([source.bytes.buffer as ArrayBuffer]);
+            options?.onProgress?.(100);
+            break;
+          }
+
+          case "file": {
+            // File paths not supported on web
+            throw new UnsupportedSourceError("file", "web");
+          }
+
+          default: {
+            const _exhaustive: never = source;
+            throw new UnsupportedSourceError((_exhaustive as TBinarySource).type, "web");
+          }
+        }
+
+        // Store in cache
+        const response = new Response(blob, {
+          headers: contentType ? { "Content-Type": contentType } : {},
+        });
+        await cache.put(toCacheKey(path), response);
+
+        // Store metadata
+        const meta: IFileMetadata = {
+          sizeBytes: blob.size,
+          mtimeMs: Date.now(),
+          contentType,
+        };
+        await setMetadata(path, meta);
+
+        return {
+          sizeBytes: blob.size,
+          contentType,
+        };
+      } catch (error) {
+        if (error instanceof UnsupportedSourceError) {
+          throw error;
+        }
+        throw new AdapterIOError("writeBinaryAtomic", path, error as Error);
+      }
+    },
+
+    async getPublicUri(path: TAdapterPath): Promise<string> {
+      try {
+        const cache = await caches.open(cacheName);
+        const response = await cache.match(toCacheKey(path));
+        if (!response) {
+          throw new Error("File not found");
+        }
+
+        const blob = await response.blob();
+        const blobUrl = URL.createObjectURL(blob);
+
+        // Track for cleanup
+        blobUrls.add(blobUrl);
+
+        return blobUrl;
+      } catch (error) {
+        throw new AdapterIOError("getPublicUri", path, error as Error);
+      }
+    },
+  };
+
+  // Add cleanup method (non-standard, for internal use)
+  (adapter as IWebAdapterWithCleanup).revokeUri = (uri: string): void => {
+    if (blobUrls.has(uri)) {
+      URL.revokeObjectURL(uri);
+      blobUrls.delete(uri);
+    }
+  };
+
+  (adapter as IWebAdapterWithCleanup).revokeAllUris = (): void => {
+    for (const uri of blobUrls) {
+      URL.revokeObjectURL(uri);
+    }
+    blobUrls.clear();
+  };
+
+  return adapter;
+}
+
+/**
+ * Extended interface for web adapter with cleanup methods.
+ */
+export interface IWebAdapterWithCleanup extends IStorageAdapter {
+  /** Revokes a specific blob URL to free memory. */
+  revokeUri(uri: string): void;
+  /** Revokes all created blob URLs. */
+  revokeAllUris(): void;
+}

package/src/core/adapter.ts

@@ -0,0 +1,128 @@
+/**
+ * Adapter-relative path. Core never constructs absolute OS paths.
+ * All paths are relative to the adapter's root.
+ */
+export type TAdapterPath = string;
+
+/**
+ * Discriminated union for binary content sources.
+ * Adapters support the subset they can handle; throw UnsupportedSourceError otherwise.
+ */
+export type TBinarySource =
+  | {
+      readonly type: "url";
+      readonly url: string;
+      readonly headers?: Readonly<Record<string, string>>;
+    }
+  | { readonly type: "file"; readonly filePath: string } // Native only
+  | { readonly type: "blob"; readonly blob: Blob } // Web only
+  | { readonly type: "bytes"; readonly bytes: Uint8Array }; // Universal fallback
+
+/**
+ * Result of a binary write operation.
+ */
+export interface IBinaryWriteResult {
+  readonly sizeBytes: number;
+  readonly contentType?: string;
+}
+
+/**
+ * File/entry stat information.
+ */
+export interface IFileStat {
+  readonly sizeBytes: number;
+  readonly mtimeMs: number;
+}
+
+/**
+ * Progress callback for binary operations.
+ */
+export type TProgressCallback = (percent: number) => void;
+
+/**
+ * Options for binary write operations.
+ */
+export interface IBinaryWriteOptions {
+  readonly onProgress?: TProgressCallback;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Storage adapter interface.
+ * Represents a key-addressed "filesystem-like" store with atomic write support.
+ * All paths are adapter-relative. Core never constructs absolute OS paths.
+ */
+export interface IStorageAdapter {
+  /** Adapter kind identifier. */
+  readonly kind: string;
+
+  /** A stable root identifier (e.g., absolute cache root on native, cache name on web). */
+  readonly rootId: string;
+
+  // ─────────────────────────────────────────────────────────────────
+  // Directory Management
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Ensures a directory exists at the given path, creating it recursively if needed.
+   */
+  ensureDir(path: TAdapterPath): Promise<void>;
+
+  /**
+   * Checks if a file or directory exists at the given path.
+   */
+  exists(path: TAdapterPath): Promise<boolean>;
+
+  /**
+   * Removes a file at the given path. No-op if file doesn't exist.
+   */
+  remove(path: TAdapterPath): Promise<void>;
+
+  /**
+   * Removes a directory and all its contents recursively.
+   */
+  removeDir(path: TAdapterPath): Promise<void>;
+
+  /**
+   * Lists all entries (files/directories) in a directory.
+   * Returns relative paths from the listed directory.
+   */
+  listDir(path: TAdapterPath): Promise<ReadonlyArray<TAdapterPath>>;
+
+  // ─────────────────────────────────────────────────────────────────
+  // File I/O
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Reads text content from a file.
+   */
+  readText(path: TAdapterPath, encoding: "utf8"): Promise<string>;
+
+  /**
+   * Writes text content atomically (write to temp, then rename).
+   */
+  writeTextAtomic(path: TAdapterPath, content: string, encoding: "utf8"): Promise<void>;
+
+  /**
+   * Gets file statistics.
+   */
+  stat(path: TAdapterPath): Promise<IFileStat>;
+
+  /**
+   * Writes binary content atomically.
+   * Source may be URL, blob, file path, or raw bytes depending on adapter.
+   * Adapter must throw UnsupportedSourceError for unsupported source types.
+   */
+  writeBinaryAtomic(
+    path: TAdapterPath,
+    source: TBinarySource,
+    options?: IBinaryWriteOptions
+  ): Promise<IBinaryWriteResult>;
+
+  /**
+   * Returns a URI that the app can use to read/view the stored file.
+   * - Native: file:// URI
+   * - Web: blob: URL (caller responsible for revoking)
+   */
+  getPublicUri(path: TAdapterPath): Promise<string>;
+}