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

package/src/core/cacheEngine.ts

@@ -0,0 +1,634 @@
+/* eslint-disable @typescript-eslint/require-await */
+
+import type { IStorageAdapter, TBinarySource } from "./adapter";
+import type {
+  ICacheConfig,
+  ICacheEntry,
+  ICacheEntryMeta,
+  IPutOptions,
+  IPutResult,
+  IGetResult,
+  IListOptions,
+  IPruneResult,
+  ICacheStats,
+  ICacheIndex,
+} from "./types";
+import { IndexStore } from "./indexStore";
+import { Mutex, KeyedMutex } from "./mutex";
+import { hash as defaultHash } from "./hash";
+import {
+  getExpiredEntries,
+  getLruPruneTargets,
+  removeEntriesFromIndex,
+  addEntryToIndex,
+  touchEntry,
+  createEmptyIndex,
+} from "./prune";
+
+const ENTRIES_DIR = "entries";
+const INDEX_FILE = "index.json";
+
+/**
+ * Main cache engine implementation.
+ * Coordinates all cache operations through the storage adapter.
+ */
+export class CacheEngine {
+  private readonly _config: Required<Pick<ICacheConfig, "namespace" | "autoPruneExpired">> &
+    ICacheConfig;
+  private readonly _adapter: IStorageAdapter;
+  private readonly _indexStore: IndexStore;
+  private readonly _indexMutex = new Mutex();
+  private readonly _keyMutex = new KeyedMutex();
+  private readonly _hashFn: (input: string) => string | Promise<string>;
+
+  private _index: ICacheIndex = createEmptyIndex();
+  private _initialized = false;
+
+  constructor(config: ICacheConfig, adapter: IStorageAdapter) {
+    this._config = {
+      namespace: "default",
+      autoPruneExpired: true,
+      ...config,
+    };
+    this._adapter = adapter;
+    this._indexStore = new IndexStore(adapter, INDEX_FILE);
+    this._hashFn = config.hashFn ?? defaultHash;
+  }
+
+  /**
+   * Initialize cache (ensure directories, load index).
+   */
+  async init(): Promise<void> {
+    if (this._initialized) {
+      return;
+    }
+
+    await this._indexMutex.runExclusive(async () => {
+      // Ensure entries directory exists
+      await this._adapter.ensureDir(ENTRIES_DIR);
+
+      // Load or rebuild index
+      try {
+        this._index = await this._indexStore.load();
+      } catch {
+        // Index is corrupt, rebuild from filesystem
+        this._index = await this._indexStore.rebuild(ENTRIES_DIR);
+      }
+
+      this._initialized = true;
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Put Operations (Immutable - no overwrites)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Store content from URL.
+   * Returns {status: "exists"} if key already exists.
+   */
+  async putFromUrl(key: string, url: string, options?: IPutOptions): Promise<IPutResult> {
+    const source: TBinarySource = {
+      type: "url",
+      url,
+      headers: options?.headers,
+    };
+    return this._put(key, source, options);
+  }
+
+  /**
+   * Store content from local file path (native only).
+   */
+  async putFromFile(key: string, filePath: string, options?: IPutOptions): Promise<IPutResult> {
+    const source: TBinarySource = {
+      type: "file",
+      filePath,
+    };
+    return this._put(key, source, options);
+  }
+
+  /**
+   * Store content from Blob (web only).
+   */
+  async putFromBlob(key: string, blob: Blob, options?: IPutOptions): Promise<IPutResult> {
+    const source: TBinarySource = {
+      type: "blob",
+      blob,
+    };
+    return this._put(key, source, options);
+  }
+
+  /**
+   * Store content from raw bytes.
+   */
+  async putFromBytes(key: string, bytes: Uint8Array, options?: IPutOptions): Promise<IPutResult> {
+    const source: TBinarySource = {
+      type: "bytes",
+      bytes,
+    };
+    return this._put(key, source, options);
+  }
+
+  /**
+   * Internal put implementation.
+   */
+  private async _put(
+    key: string,
+    source: TBinarySource,
+    options?: IPutOptions
+  ): Promise<IPutResult> {
+    this._ensureInitialized();
+
+    // Use keyed mutex to serialize operations on the same key
+    return this._keyMutex.runExclusive(key, async () => {
+      // Check if key already exists
+      const existingEntry = this._index.entries[key];
+      if (existingEntry) {
+        // Check if expired
+        const now = Date.now();
+        if (existingEntry.expiresAt === undefined || existingEntry.expiresAt >= now) {
+          // Entry exists and is not expired, return exists
+          const entry = this._entryWithPath(existingEntry);
+          return { status: "exists" as const, entry };
+        }
+        // Entry is expired, remove it first
+        await this._removeEntry(key);
+      }
+
+      // Compute hash
+      const hashValue = await this._hashFn(key);
+
+      // Determine extension
+      const ext = options?.ext ?? this._extractExtension(source);
+
+      // Build entry path
+      const entryPath = `${ENTRIES_DIR}/${hashValue}${ext}`;
+
+      // Write binary content
+      const writeResult = await this._adapter.writeBinaryAtomic(entryPath, source, {
+        onProgress: options?.onProgress,
+        headers: options?.headers,
+      });
+
+      // Calculate expiration
+      const now = Date.now();
+      const ttlMs = options?.ttlMs ?? this._config.defaultTtlMs;
+      const expiresAt = ttlMs !== undefined ? now + ttlMs : undefined;
+
+      // Create entry metadata
+      const entryMeta: ICacheEntryMeta = {
+        key,
+        hash: hashValue,
+        ext,
+        sizeBytes: writeResult.sizeBytes,
+        contentType: writeResult.contentType,
+        createdAt: now,
+        lastAccessedAt: now,
+        expiresAt,
+        metadata: options?.metadata,
+      };
+
+      // Update index atomically
+      await this._indexMutex.runExclusive(async () => {
+        this._index = addEntryToIndex(this._index, entryMeta);
+        await this._indexStore.save(this._index);
+      });
+
+      // Auto-prune if configured
+      if (this._config.autoPruneExpired) {
+        // Don't await - run in background
+        this._autoPrune().catch(() => {
+          // Ignore prune errors
+        });
+      }
+
+      const entry = this._entryWithPath(entryMeta);
+      return { status: "created" as const, entry };
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Get Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get entry by key. Returns null if not found or expired.
+   * Updates lastAccessedAt.
+   */
+  async get(key: string): Promise<IGetResult | null> {
+    this._ensureInitialized();
+
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return null;
+    }
+
+    // Check expiration
+    const now = Date.now();
+    if (entryMeta.expiresAt !== undefined && entryMeta.expiresAt < now) {
+      // Entry is expired
+      return null;
+    }
+
+    // Update lastAccessedAt
+    await this._indexMutex.runExclusive(async () => {
+      this._index = touchEntry(this._index, key, now);
+      await this._indexStore.save(this._index);
+    });
+
+    const entry = this._entryWithPath(entryMeta);
+    const uri = await this._adapter.getPublicUri(entry.path);
+
+    return { entry, uri };
+  }
+
+  /**
+   * Check if key exists and is not expired.
+   */
+  async has(key: string): Promise<boolean> {
+    this._ensureInitialized();
+
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return false;
+    }
+
+    // Check expiration
+    const now = Date.now();
+    if (entryMeta.expiresAt !== undefined && entryMeta.expiresAt < now) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get entry metadata without updating lastAccessedAt.
+   */
+  async peek(key: string): Promise<ICacheEntry | null> {
+    this._ensureInitialized();
+
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return null;
+    }
+
+    // Check expiration
+    const now = Date.now();
+    if (entryMeta.expiresAt !== undefined && entryMeta.expiresAt < now) {
+      return null;
+    }
+
+    return this._entryWithPath(entryMeta);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List/Query Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * List entries with sorting, filtering, pagination.
+   */
+  async list(options?: IListOptions): Promise<ReadonlyArray<ICacheEntry>> {
+    this._ensureInitialized();
+
+    const now = Date.now();
+    let entries = Object.values(this._index.entries)
+      // Filter out expired entries
+      .filter((e) => e.expiresAt === undefined || e.expiresAt >= now)
+      // Apply custom filter if provided
+      .filter((e) => (options?.filter ? options.filter(e) : true));
+
+    // Sort
+    const sortBy = options?.sortBy ?? "createdAt";
+    const order = options?.order ?? "desc";
+    const multiplier = order === "desc" ? -1 : 1;
+
+    entries.sort((a, b) => {
+      let comparison = 0;
+      switch (sortBy) {
+        case "createdAt":
+          comparison = a.createdAt - b.createdAt;
+          break;
+        case "lastAccessedAt":
+          comparison = a.lastAccessedAt - b.lastAccessedAt;
+          break;
+        case "sizeBytes":
+          comparison = a.sizeBytes - b.sizeBytes;
+          break;
+        case "key":
+          comparison = a.key.localeCompare(b.key);
+          break;
+      }
+      return comparison * multiplier;
+    });
+
+    // Pagination
+    if (options?.offset !== undefined) {
+      entries = entries.slice(options.offset);
+    }
+    if (options?.limit !== undefined) {
+      entries = entries.slice(0, options.limit);
+    }
+
+    return entries.map((e) => this._entryWithPath(e));
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  async stats(): Promise<ICacheStats> {
+    this._ensureInitialized();
+
+    const now = Date.now();
+    const validEntries = Object.values(this._index.entries).filter(
+      (e) => e.expiresAt === undefined || e.expiresAt >= now
+    );
+
+    if (validEntries.length === 0) {
+      return {
+        entryCount: 0,
+        totalSizeBytes: 0,
+      };
+    }
+
+    // Find oldest and newest by createdAt
+    let oldest = validEntries[0];
+    let newest = validEntries[0];
+
+    for (const entry of validEntries) {
+      if (entry.createdAt < oldest.createdAt) {
+        oldest = entry;
+      }
+      if (entry.createdAt > newest.createdAt) {
+        newest = entry;
+      }
+    }
+
+    const totalSizeBytes = validEntries.reduce((sum, e) => sum + e.sizeBytes, 0);
+
+    return {
+      entryCount: validEntries.length,
+      totalSizeBytes,
+      oldestEntry: oldest,
+      newestEntry: newest,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Remove/Prune Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Remove specific entry by key.
+   */
+  async remove(key: string): Promise<boolean> {
+    this._ensureInitialized();
+
+    return this._keyMutex.runExclusive(key, async () => {
+      return this._removeEntry(key);
+    });
+  }
+
+  /**
+   * Internal remove implementation (must be called within keyed mutex).
+   */
+  private async _removeEntry(key: string): Promise<boolean> {
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return false;
+    }
+
+    const entryPath = `${ENTRIES_DIR}/${entryMeta.hash}${entryMeta.ext}`;
+
+    // Remove file
+    await this._adapter.remove(entryPath);
+
+    // Update index
+    await this._indexMutex.runExclusive(async () => {
+      this._index = removeEntriesFromIndex(this._index, [key]);
+      await this._indexStore.save(this._index);
+    });
+
+    return true;
+  }
+
+  /**
+   * Remove all expired entries.
+   */
+  async removeExpired(): Promise<IPruneResult> {
+    this._ensureInitialized();
+
+    const now = Date.now();
+    const expired = getExpiredEntries(this._index, now);
+
+    if (expired.length === 0) {
+      return {
+        removedCount: 0,
+        freedBytes: 0,
+        removedKeys: [],
+      };
+    }
+
+    return this._removeEntries(expired);
+  }
+
+  /**
+   * Prune to fit within size limit using LRU.
+   */
+  async pruneLru(maxSizeBytes: number): Promise<IPruneResult> {
+    this._ensureInitialized();
+
+    const targets = getLruPruneTargets(this._index, maxSizeBytes);
+
+    if (targets.length === 0) {
+      return {
+        removedCount: 0,
+        freedBytes: 0,
+        removedKeys: [],
+      };
+    }
+
+    return this._removeEntries(targets);
+  }
+
+  /**
+   * Remove multiple entries.
+   */
+  private async _removeEntries(entries: ReadonlyArray<ICacheEntryMeta>): Promise<IPruneResult> {
+    const removedKeys: string[] = [];
+    let freedBytes = 0;
+
+    for (const entry of entries) {
+      const entryPath = `${ENTRIES_DIR}/${entry.hash}${entry.ext}`;
+      try {
+        await this._adapter.remove(entryPath);
+        removedKeys.push(entry.key);
+        freedBytes += entry.sizeBytes;
+      } catch {
+        // Ignore removal errors
+      }
+    }
+
+    // Update index atomically
+    if (removedKeys.length > 0) {
+      await this._indexMutex.runExclusive(async () => {
+        this._index = removeEntriesFromIndex(this._index, removedKeys);
+        await this._indexStore.save(this._index);
+      });
+    }
+
+    return {
+      removedCount: removedKeys.length,
+      freedBytes,
+      removedKeys,
+    };
+  }
+
+  /**
+   * Clear all entries.
+   */
+  async clear(): Promise<void> {
+    this._ensureInitialized();
+
+    await this._indexMutex.runExclusive(async () => {
+      // Remove all entry files
+      try {
+        await this._adapter.removeDir(ENTRIES_DIR);
+      } catch {
+        // Ignore errors
+      }
+
+      // Recreate entries directory
+      await this._adapter.ensureDir(ENTRIES_DIR);
+
+      // Clear index
+      this._index = createEmptyIndex();
+      await this._indexStore.save(this._index);
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Maintenance
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Validate index against filesystem and rebuild if needed.
+   */
+  async validateAndRepair(): Promise<{ repaired: boolean; issues: string[] }> {
+    this._ensureInitialized();
+
+    const issues: string[] = [];
+
+    await this._indexMutex.runExclusive(async () => {
+      // Check each entry in index exists on filesystem
+      for (const entry of Object.values(this._index.entries)) {
+        const entryPath = `${ENTRIES_DIR}/${entry.hash}${entry.ext}`;
+        const exists = await this._adapter.exists(entryPath);
+        if (!exists) {
+          issues.push(`Missing file for entry "${entry.key}"`);
+        }
+      }
+
+      // Check for orphan files not in index
+      try {
+        const files = await this._adapter.listDir(ENTRIES_DIR);
+        const indexedHashes = new Set(
+          Object.values(this._index.entries).map((e) => `${e.hash}${e.ext}`)
+        );
+
+        for (const file of files) {
+          if (!indexedHashes.has(file)) {
+            issues.push(`Orphan file "${file}" not in index`);
+          }
+        }
+      } catch {
+        issues.push("Could not list entries directory");
+      }
+    });
+
+    // If there are issues, rebuild index
+    if (issues.length > 0) {
+      await this._indexMutex.runExclusive(async () => {
+        this._index = await this._indexStore.rebuild(ENTRIES_DIR);
+      });
+    }
+
+    return {
+      repaired: issues.length > 0,
+      issues,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Private Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  private _ensureInitialized(): void {
+    if (!this._initialized) {
+      throw new Error("CacheEngine not initialized. Call init() first.");
+    }
+  }
+
+  private _entryWithPath(meta: ICacheEntryMeta): ICacheEntry {
+    return {
+      ...meta,
+      path: `${ENTRIES_DIR}/${meta.hash}${meta.ext}`,
+    };
+  }
+
+  private _extractExtension(source: TBinarySource): string {
+    switch (source.type) {
+      case "url": {
+        const url = new URL(source.url);
+        const pathname = url.pathname;
+        const lastDot = pathname.lastIndexOf(".");
+        if (lastDot > 0 && lastDot > pathname.lastIndexOf("/")) {
+          return pathname.substring(lastDot);
+        }
+        return "";
+      }
+      case "file": {
+        const lastDot = source.filePath.lastIndexOf(".");
+        const lastSlash = Math.max(
+          source.filePath.lastIndexOf("/"),
+          source.filePath.lastIndexOf("\\")
+        );
+        if (lastDot > 0 && lastDot > lastSlash) {
+          return source.filePath.substring(lastDot);
+        }
+        return "";
+      }
+      case "blob": {
+        // Try to extract from MIME type
+        const mime = source.blob.type;
+        if (mime) {
+          const mimeToExt: Record<string, string> = {
+            "image/jpeg": ".jpg",
+            "image/png": ".png",
+            "image/gif": ".gif",
+            "image/webp": ".webp",
+            "application/json": ".json",
+            "text/plain": ".txt",
+            "text/html": ".html",
+            "application/pdf": ".pdf",
+          };
+          return mimeToExt[mime] ?? "";
+        }
+        return "";
+      }
+      case "bytes":
+        return "";
+    }
+  }
+
+  private async _autoPrune(): Promise<void> {
+    // Remove expired entries
+    await this.removeExpired();
+
+    // LRU prune if max size configured
+    if (this._config.maxSizeBytes !== undefined) {
+      await this.pruneLru(this._config.maxSizeBytes);
+    }
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,82 @@
+import type { TBinarySource } from "./adapter";
+
+/**
+ * Base error class for cache operations.
+ */
+export abstract class CacheError extends Error {
+  abstract readonly code: string;
+
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when an adapter receives a TBinarySource type it cannot handle.
+ */
+export class UnsupportedSourceError extends CacheError {
+  readonly code = "UNSUPPORTED_SOURCE" as const;
+
+  constructor(
+    public readonly sourceType: TBinarySource["type"],
+    public readonly adapterKind: string
+  ) {
+    super(`Adapter "${adapterKind}" does not support source type "${sourceType}"`);
+  }
+}
+
+/**
+ * Thrown when an adapter I/O operation fails.
+ */
+export class AdapterIOError extends CacheError {
+  readonly code = "ADAPTER_IO_ERROR" as const;
+
+  constructor(
+    public readonly operation: string,
+    public readonly path: string,
+    public readonly cause?: Error
+  ) {
+    super(
+      `Adapter I/O error during "${operation}" at path "${path}": ${cause?.message ?? "unknown"}`
+    );
+  }
+}
+
+/**
+ * Thrown when the cache index is corrupt and cannot be parsed.
+ */
+export class CorruptIndexError extends CacheError {
+  readonly code = "CORRUPT_INDEX" as const;
+
+  constructor(
+    public readonly reason: string,
+    public readonly cause?: Error
+  ) {
+    super(`Cache index is corrupt: ${reason}`);
+  }
+}
+
+/**
+ * Internal error when attempting to overwrite an immutable entry.
+ * Public API converts this to {status: "exists"} response.
+ */
+export class ImmutableConflictError extends CacheError {
+  readonly code = "IMMUTABLE_CONFLICT" as const;
+
+  constructor(public readonly key: string) {
+    super(`Cannot overwrite immutable entry with key "${key}"`);
+  }
+}
+
+/**
+ * Thrown when a required entry is not found.
+ */
+export class EntryNotFoundError extends CacheError {
+  readonly code = "ENTRY_NOT_FOUND" as const;
+
+  constructor(public readonly key: string) {
+    super(`Cache entry not found for key "${key}"`);
+  }
+}