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

package/src/adapters/memoryAdapter.ts

@@ -0,0 +1,307 @@
+/**
+ * In-Memory Storage Adapter
+ *
+ * For testing purposes only.
+ * Implements IStorageAdapter using in-memory storage.
+ */
+
+/* eslint-disable @typescript-eslint/require-await */
+
+import type {
+  IStorageAdapter,
+  TAdapterPath,
+  TBinarySource,
+  IBinaryWriteResult,
+  IBinaryWriteOptions,
+  IFileStat,
+} from "../core/adapter";
+import { AdapterIOError } from "../core/errors";
+
+interface IFileEntry {
+  content: Uint8Array;
+  mtime: number;
+  contentType?: string;
+}
+
+/**
+ * Extended interface for memory adapter with test utilities.
+ */
+export interface IMemoryAdapter extends IStorageAdapter {
+  /** Resets all stored data. For testing. */
+  _reset(): void;
+  /** Gets raw content for assertions. For testing. */
+  _getContent(path: string): Uint8Array | undefined;
+  /** Gets all stored paths. For testing. */
+  _getAllPaths(): string[];
+}
+
+/**
+ * Creates an in-memory storage adapter for testing.
+ */
+export function createMemoryAdapter(namespace?: string): IMemoryAdapter {
+  const ns = namespace ?? "default";
+  const rootId = `memory://${ns}`;
+
+  // In-memory storage
+  const files = new Map<string, IFileEntry>();
+  const directories = new Set<string>();
+
+  // Track blob URLs for cleanup
+  const blobUrls = new Map<string, string>();
+
+  /**
+   * Normalizes path by removing leading/trailing slashes.
+   */
+  const normalizePath = (path: TAdapterPath): string => {
+    return path.replace(/^\/+|\/+$/g, "");
+  };
+
+  /**
+   * Gets the parent directory of a path.
+   */
+  const getParentDir = (path: string): string | null => {
+    const lastSlash = path.lastIndexOf("/");
+    return lastSlash > 0 ? path.substring(0, lastSlash) : null;
+  };
+
+  const adapter: IMemoryAdapter = {
+    kind: "memory",
+    rootId,
+
+    // ─────────────────────────────────────────────────────────────────
+    // Directory Management
+    // ─────────────────────────────────────────────────────────────────
+
+    async ensureDir(path: TAdapterPath): Promise<void> {
+      const normalized = normalizePath(path);
+      if (normalized) {
+        directories.add(normalized);
+        // Also ensure parent directories
+        const parent = getParentDir(normalized);
+        if (parent) {
+          await this.ensureDir(parent);
+        }
+      }
+    },
+
+    async exists(path: TAdapterPath): Promise<boolean> {
+      const normalized = normalizePath(path);
+      return files.has(normalized) || directories.has(normalized);
+    },
+
+    async remove(path: TAdapterPath): Promise<void> {
+      const normalized = normalizePath(path);
+      files.delete(normalized);
+    },
+
+    async removeDir(path: TAdapterPath): Promise<void> {
+      const normalized = normalizePath(path);
+      const prefix = normalized + "/";
+
+      // Remove all files with this prefix
+      for (const key of files.keys()) {
+        if (key === normalized || key.startsWith(prefix)) {
+          files.delete(key);
+        }
+      }
+
+      // Remove all directories with this prefix
+      for (const dir of directories) {
+        if (dir === normalized || dir.startsWith(prefix)) {
+          directories.delete(dir);
+        }
+      }
+    },
+
+    async listDir(path: TAdapterPath): Promise<ReadonlyArray<TAdapterPath>> {
+      const normalized = normalizePath(path);
+      const prefix = normalized ? normalized + "/" : "";
+      const entries = new Set<string>();
+
+      // Find all files in this directory
+      for (const key of files.keys()) {
+        if (key.startsWith(prefix)) {
+          const relativePath = key.slice(prefix.length);
+          const firstSlash = relativePath.indexOf("/");
+          if (firstSlash === -1) {
+            // Direct child file
+            entries.add(relativePath);
+          }
+        }
+      }
+
+      return Array.from(entries);
+    },
+
+    // ─────────────────────────────────────────────────────────────────
+    // File I/O
+    // ─────────────────────────────────────────────────────────────────
+
+    async readText(path: TAdapterPath, _encoding: "utf8"): Promise<string> {
+      const normalized = normalizePath(path);
+      const entry = files.get(normalized);
+      if (!entry) {
+        throw new AdapterIOError("readText", path, new Error("File not found"));
+      }
+      const decoder = new TextDecoder("utf-8");
+      return decoder.decode(entry.content);
+    },
+
+    async writeTextAtomic(path: TAdapterPath, content: string, _encoding: "utf8"): Promise<void> {
+      const normalized = normalizePath(path);
+      const encoder = new TextEncoder();
+      const bytes = encoder.encode(content);
+
+      files.set(normalized, {
+        content: bytes,
+        mtime: Date.now(),
+        contentType: "text/plain",
+      });
+
+      // Ensure parent directory exists
+      const parent = getParentDir(normalized);
+      if (parent) {
+        directories.add(parent);
+      }
+    },
+
+    async stat(path: TAdapterPath): Promise<IFileStat> {
+      const normalized = normalizePath(path);
+      const entry = files.get(normalized);
+      if (!entry) {
+        throw new AdapterIOError("stat", path, new Error("File not found"));
+      }
+      return {
+        sizeBytes: entry.content.length,
+        mtimeMs: entry.mtime,
+      };
+    },
+
+    async writeBinaryAtomic(
+      path: TAdapterPath,
+      source: TBinarySource,
+      options?: IBinaryWriteOptions
+    ): Promise<IBinaryWriteResult> {
+      const normalized = normalizePath(path);
+      let content: Uint8Array;
+      let contentType: string | undefined;
+
+      switch (source.type) {
+        case "url": {
+          // Simulate URL fetch
+          try {
+            const response = await fetch(source.url, {
+              headers: { ...source.headers, ...options?.headers },
+            });
+            if (!response.ok) {
+              throw new Error(`Fetch failed: ${response.status}`);
+            }
+            contentType = response.headers.get("content-type") ?? undefined;
+            const buffer = await response.arrayBuffer();
+            content = new Uint8Array(buffer);
+            options?.onProgress?.(100);
+          } catch (error) {
+            throw new AdapterIOError("writeBinaryAtomic", path, error as Error);
+          }
+          break;
+        }
+
+        case "file": {
+          // Simulate file copy (just use path as content for testing)
+          const encoder = new TextEncoder();
+          content = encoder.encode(`[file:${source.filePath}]`);
+          options?.onProgress?.(100);
+          break;
+        }
+
+        case "blob": {
+          const buffer = await source.blob.arrayBuffer();
+          content = new Uint8Array(buffer);
+          contentType = source.blob.type || undefined;
+          options?.onProgress?.(100);
+          break;
+        }
+
+        case "bytes": {
+          content = source.bytes;
+          options?.onProgress?.(100);
+          break;
+        }
+
+        default: {
+          const _exhaustive: never = source;
+          throw new AdapterIOError(
+            "writeBinaryAtomic",
+            path,
+            new Error(`Unknown source type: ${(_exhaustive as TBinarySource).type}`)
+          );
+        }
+      }
+
+      files.set(normalized, {
+        content,
+        mtime: Date.now(),
+        contentType,
+      });
+
+      // Ensure parent directory exists
+      const parent = getParentDir(normalized);
+      if (parent) {
+        directories.add(parent);
+      }
+
+      return {
+        sizeBytes: content.length,
+        contentType,
+      };
+    },
+
+    async getPublicUri(path: TAdapterPath): Promise<string> {
+      const normalized = normalizePath(path);
+      const entry = files.get(normalized);
+      if (!entry) {
+        throw new AdapterIOError("getPublicUri", path, new Error("File not found"));
+      }
+
+      // Check if we already have a blob URL for this path
+      const existing = blobUrls.get(normalized);
+      if (existing) {
+        return existing;
+      }
+
+      // Create blob URL
+      const blob = new Blob([entry.content.buffer as ArrayBuffer], {
+        type: entry.contentType ?? "application/octet-stream",
+      });
+      const url = URL.createObjectURL(blob);
+      blobUrls.set(normalized, url);
+
+      return url;
+    },
+
+    // ─────────────────────────────────────────────────────────────────
+    // Test Utilities
+    // ─────────────────────────────────────────────────────────────────
+
+    _reset(): void {
+      files.clear();
+      directories.clear();
+      // Revoke all blob URLs
+      for (const url of blobUrls.values()) {
+        URL.revokeObjectURL(url);
+      }
+      blobUrls.clear();
+    },
+
+    _getContent(path: string): Uint8Array | undefined {
+      const normalized = normalizePath(path);
+      return files.get(normalized)?.content;
+    },
+
+    _getAllPaths(): string[] {
+      return Array.from(files.keys());
+    },
+  };
+
+  return adapter;
+}

package/src/adapters/rnfsAdapter.ts

@@ -0,0 +1,283 @@
+/**
+ * React Native FS Adapter
+ *
+ * This is the ONLY file that imports react-native-fs.
+ * Implements IStorageAdapter using RNFS APIs.
+ */
+
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-unsafe-call */
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+/* eslint-disable @typescript-eslint/require-await */
+
+// RNFS types are not fully typed, disable unsafe rules for this adapter
+import RNFS, { type DownloadResult } from "react-native-fs";
+import type {
+  IStorageAdapter,
+  TAdapterPath,
+  TBinarySource,
+  IBinaryWriteResult,
+  IBinaryWriteOptions,
+  IFileStat,
+} from "../core/adapter";
+import { UnsupportedSourceError, AdapterIOError } from "../core/errors";
+
+export interface IRnfsAdapterOptions {
+  /** Base directory. @default RNFS.CachesDirectoryPath */
+  readonly baseDir?: string;
+  /** Namespace subdirectory. */
+  readonly namespace?: string;
+}
+
+/**
+ * Creates a storage adapter backed by react-native-fs.
+ */
+export function createRnfsAdapter(options?: IRnfsAdapterOptions): IStorageAdapter {
+  const baseDir = options?.baseDir ?? RNFS.CachesDirectoryPath;
+  const namespace = options?.namespace ?? "default";
+  const rootPath = `${baseDir}/immutable-cache/${namespace}`;
+
+  /**
+   * Converts adapter-relative path to absolute filesystem path.
+   */
+  const toAbsolute = (path: TAdapterPath): string => {
+    return `${rootPath}/${path}`;
+  };
+
+  /**
+   * Generates a unique temp file path for atomic writes.
+   */
+  const getTempPath = (path: TAdapterPath): string => {
+    return `${toAbsolute(path)}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+  };
+
+  const adapter: IStorageAdapter = {
+    kind: "native-fs",
+    rootId: rootPath,
+
+    // ─────────────────────────────────────────────────────────────────
+    // Directory Management
+    // ─────────────────────────────────────────────────────────────────
+
+    async ensureDir(path: TAdapterPath): Promise<void> {
+      try {
+        const absPath = toAbsolute(path);
+        await RNFS.mkdir(absPath);
+      } catch (error) {
+        throw new AdapterIOError("ensureDir", path, error as Error);
+      }
+    },
+
+    async exists(path: TAdapterPath): Promise<boolean> {
+      try {
+        const absPath = toAbsolute(path);
+        return await RNFS.exists(absPath);
+      } catch {
+        return false;
+      }
+    },
+
+    async remove(path: TAdapterPath): Promise<void> {
+      try {
+        const absPath = toAbsolute(path);
+        const exists = await RNFS.exists(absPath);
+        if (exists) {
+          await RNFS.unlink(absPath);
+        }
+      } catch (error) {
+        throw new AdapterIOError("remove", path, error as Error);
+      }
+    },
+
+    async removeDir(path: TAdapterPath): Promise<void> {
+      try {
+        const absPath = toAbsolute(path);
+        const exists = await RNFS.exists(absPath);
+        if (exists) {
+          // RNFS.unlink can remove directories recursively
+          await RNFS.unlink(absPath);
+        }
+      } catch (error) {
+        throw new AdapterIOError("removeDir", path, error as Error);
+      }
+    },
+
+    async listDir(path: TAdapterPath): Promise<ReadonlyArray<TAdapterPath>> {
+      try {
+        const absPath = toAbsolute(path);
+        const exists = await RNFS.exists(absPath);
+        if (!exists) {
+          return [];
+        }
+        const items = await RNFS.readDir(absPath);
+        return items.map((item: { name: string }) => item.name);
+      } catch (error) {
+        throw new AdapterIOError("listDir", path, error as Error);
+      }
+    },
+
+    // ─────────────────────────────────────────────────────────────────
+    // File I/O
+    // ─────────────────────────────────────────────────────────────────
+
+    async readText(path: TAdapterPath, _encoding: "utf8"): Promise<string> {
+      try {
+        const absPath = toAbsolute(path);
+        return await RNFS.readFile(absPath, "utf8");
+      } catch (error) {
+        throw new AdapterIOError("readText", path, error as Error);
+      }
+    },
+
+    async writeTextAtomic(path: TAdapterPath, content: string, _encoding: "utf8"): Promise<void> {
+      const tempPath = getTempPath(path);
+      const absPath = toAbsolute(path);
+
+      try {
+        // Ensure parent directory exists
+        const parentDir = absPath.substring(0, absPath.lastIndexOf("/"));
+        await RNFS.mkdir(parentDir);
+
+        // Write to temp file
+        await RNFS.writeFile(tempPath, content, "utf8");
+
+        // Atomic move
+        await RNFS.moveFile(tempPath, absPath);
+      } catch (error) {
+        // Clean up temp file on error
+        try {
+          await RNFS.unlink(tempPath);
+        } catch {
+          // Ignore cleanup errors
+        }
+        throw new AdapterIOError("writeTextAtomic", path, error as Error);
+      }
+    },
+
+    async stat(path: TAdapterPath): Promise<IFileStat> {
+      try {
+        const absPath = toAbsolute(path);
+        const statResult = await RNFS.stat(absPath);
+        return {
+          sizeBytes: statResult.size,
+          mtimeMs: new Date(statResult.mtime).getTime(),
+        };
+      } catch (error) {
+        throw new AdapterIOError("stat", path, error as Error);
+      }
+    },
+
+    async writeBinaryAtomic(
+      path: TAdapterPath,
+      source: TBinarySource,
+      options?: IBinaryWriteOptions
+    ): Promise<IBinaryWriteResult> {
+      const tempPath = getTempPath(path);
+      const absPath = toAbsolute(path);
+
+      try {
+        // Ensure parent directory exists
+        const parentDir = absPath.substring(0, absPath.lastIndexOf("/"));
+        await RNFS.mkdir(parentDir);
+
+        let contentType: string | undefined;
+
+        switch (source.type) {
+          case "url": {
+            // Download file with progress
+            const downloadResult = await new Promise<DownloadResult>((resolve, reject) => {
+              const { promise } = RNFS.downloadFile({
+                fromUrl: source.url,
+                toFile: tempPath,
+                headers: { ...source.headers, ...options?.headers },
+                progress: (res: { contentLength: number; bytesWritten: number }) => {
+                  if (options?.onProgress && res.contentLength > 0) {
+                    const pct = (res.bytesWritten / res.contentLength) * 100;
+                    options.onProgress(pct);
+                  }
+                },
+                progressDivider: 1,
+              });
+              promise.then(resolve).catch(reject);
+            });
+
+            if (downloadResult.statusCode < 200 || downloadResult.statusCode >= 300) {
+              throw new Error(`Download failed with status ${downloadResult.statusCode}`);
+            }
+            break;
+          }
+
+          case "file": {
+            // Copy file
+            await RNFS.copyFile(source.filePath, tempPath);
+            break;
+          }
+
+          case "bytes": {
+            // Convert Uint8Array to base64 and write
+            const base64 = uint8ArrayToBase64(source.bytes);
+            await RNFS.writeFile(tempPath, base64, "base64");
+            break;
+          }
+
+          case "blob": {
+            // Blob is not supported on native
+            throw new UnsupportedSourceError("blob", "native-fs");
+          }
+
+          default: {
+            const _exhaustive: never = source;
+            throw new UnsupportedSourceError((_exhaustive as TBinarySource).type, "native-fs");
+          }
+        }
+
+        // Get size before moving
+        const statResult = await RNFS.stat(tempPath);
+
+        // Atomic move
+        await RNFS.moveFile(tempPath, absPath);
+
+        // Report 100% progress
+        options?.onProgress?.(100);
+
+        return {
+          sizeBytes: statResult.size,
+          contentType,
+        };
+      } catch (error) {
+        // Clean up temp file on error
+        try {
+          await RNFS.unlink(tempPath);
+        } catch {
+          // Ignore cleanup errors
+        }
+
+        if (error instanceof UnsupportedSourceError) {
+          throw error;
+        }
+        throw new AdapterIOError("writeBinaryAtomic", path, error as Error);
+      }
+    },
+
+    async getPublicUri(path: TAdapterPath): Promise<string> {
+      const absPath = toAbsolute(path);
+      // Return file:// URI for native platforms
+      return `file://${absPath}`;
+    },
+  };
+
+  return adapter;
+}
+
+/**
+ * Converts Uint8Array to base64 string.
+ */
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}