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

package/src/core/cacheEngine.ts

@@ -8,10 +8,13 @@ import type {
   IPutOptions,
   IPutResult,
   IGetResult,
+  IGetOrPutResult,
+  TFetcher,
   IListOptions,
   IPruneResult,
   ICacheStats,
   ICacheIndex,
+  TCacheEvent,
 } from "./types";
 import { IndexStore } from "./indexStore";
 import { Mutex, KeyedMutex } from "./mutex";
@@ -23,11 +26,51 @@ import {
   addEntryToIndex,
   touchEntry,
   createEmptyIndex,
+  isEntryExpired,
+  isEntryValid,
 } from "./prune";
 
 const ENTRIES_DIR = "entries";
 const INDEX_FILE = "index.json";
 
+/**
+ * Common MIME type to file extension mapping.
+ */
+const MIME_TO_EXT: Readonly<Record<string, string>> = {
+  "image/jpeg": ".jpg",
+  "image/png": ".png",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/svg+xml": ".svg",
+  "application/json": ".json",
+  "text/plain": ".txt",
+  "text/html": ".html",
+  "text/css": ".css",
+  "text/javascript": ".js",
+  "application/pdf": ".pdf",
+  "application/xml": ".xml",
+  "video/mp4": ".mp4",
+  "video/webm": ".webm",
+  "audio/mpeg": ".mp3",
+  "audio/wav": ".wav",
+};
+
+/**
+ * Creates an empty prune result.
+ */
+const EMPTY_PRUNE_RESULT: IPruneResult = Object.freeze({
+  removedCount: 0,
+  freedBytes: 0,
+  removedKeys: [],
+});
+
+/**
+ * Constructs the storage path for an entry.
+ */
+function buildEntryPath(hash: string, ext: string): string {
+  return `${ENTRIES_DIR}/${hash}${ext}`;
+}
+
 /**
  * Main cache engine implementation.
  * Coordinates all cache operations through the storage adapter.
@@ -40,9 +83,13 @@ export class CacheEngine {
   private readonly _indexMutex = new Mutex();
   private readonly _keyMutex = new KeyedMutex();
   private readonly _hashFn: (input: string) => string | Promise<string>;
+  private readonly _now: () => number;
+  private readonly _debounceMs: number;
 
   private _index: ICacheIndex = createEmptyIndex();
   private _initialized = false;
+  private _indexDirty = false;
+  private _debounceTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(config: ICacheConfig, adapter: IStorageAdapter) {
     this._config = {
@@ -53,6 +100,141 @@ export class CacheEngine {
     this._adapter = adapter;
     this._indexStore = new IndexStore(adapter, INDEX_FILE);
     this._hashFn = config.hashFn ?? defaultHash;
+    this._now = config.now ?? Date.now;
+    this._debounceMs = config.indexWriteDebounceMs ?? 0;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Public Properties
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns whether the cache has been initialized.
+   * Use this to check initialization state without throwing.
+   */
+  get isInitialized(): boolean {
+    return this._initialized;
+  }
+
+  /**
+   * Returns the configured namespace.
+   */
+  get namespace(): string {
+    return this._config.namespace;
+  }
+
+  /**
+   * Returns the storage adapter.
+   */
+  get adapter(): IStorageAdapter {
+    return this._adapter;
+  }
+
+  /**
+   * Returns whether there are pending index writes.
+   * Useful for checking if flush() should be called before shutdown.
+   */
+  get hasPendingWrites(): boolean {
+    return this._indexDirty;
+  }
+
+  /**
+   * Schedules an index save, respecting debounce configuration.
+   * If debounceMs is 0, saves immediately.
+   */
+  private async _scheduleIndexSave(): Promise<void> {
+    if (this._debounceMs <= 0) {
+      // Immediate save
+      await this._indexStore.save(this._index);
+      return;
+    }
+
+    // Mark index as dirty
+    this._indexDirty = true;
+
+    // Clear existing timer
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+    }
+
+    // Schedule new save
+    this._debounceTimer = setTimeout(() => {
+      void this._flushIndex();
+    }, this._debounceMs);
+  }
+
+  /**
+   * Internal flush implementation.
+   */
+  private async _flushIndex(): Promise<void> {
+    if (!this._indexDirty) {
+      return;
+    }
+
+    // Clear timer
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+
+    // Save index
+    await this._indexStore.save(this._index);
+    this._indexDirty = false;
+  }
+
+  /**
+   * Flushes any pending index writes immediately.
+   * Call this before app shutdown or when you need to ensure persistence.
+   */
+  async flush(): Promise<void> {
+    if (!this._initialized) {
+      return;
+    }
+
+    await this._indexMutex.runExclusive(async () => {
+      await this._flushIndex();
+    });
+  }
+
+  /**
+   * Destroys the cache engine, releasing resources.
+   * - Flushes any pending index writes
+   * - Clears debounce timers
+   * - Marks engine as uninitialized
+   *
+   * After calling destroy(), the engine cannot be used until init() is called again.
+   */
+  async destroy(): Promise<void> {
+    if (!this._initialized) {
+      return;
+    }
+
+    // Flush pending writes
+    await this._indexMutex.runExclusive(async () => {
+      await this._flushIndex();
+    });
+
+    // Clear debounce timer
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+
+    // Reset state
+    this._index = createEmptyIndex();
+    this._indexDirty = false;
+    this._initialized = false;
+  }
+
+  /**
+   * Emits an event to the configured event handler (if any).
+   */
+  private _emit(event: TCacheEvent): void {
+    try {
+      this._config.onEvent?.(event);
+    } catch {
+      // Ignore errors in event handlers to prevent disrupting cache operations
+    }
   }
 
   /**
@@ -143,13 +325,14 @@ export class CacheEngine {
     return this._keyMutex.runExclusive(key, async () => {
       // Check if key already exists
       const existingEntry = this._index.entries[key];
+      const startTime = this._now();
+
       if (existingEntry) {
         // Check if expired
-        const now = Date.now();
-        if (existingEntry.expiresAt === undefined || existingEntry.expiresAt >= now) {
+        if (isEntryValid(existingEntry, startTime)) {
           // Entry exists and is not expired, return exists
           const entry = this._entryWithPath(existingEntry);
-          return { status: "exists" as const, entry };
+          return { status: "exists", entry };
         }
         // Entry is expired, remove it first
         await this._removeEntry(key);
@@ -162,7 +345,7 @@ export class CacheEngine {
       const ext = options?.ext ?? this._extractExtension(source);
 
       // Build entry path
-      const entryPath = `${ENTRIES_DIR}/${hashValue}${ext}`;
+      const entryPath = buildEntryPath(hashValue, ext);
 
       // Write binary content
       const writeResult = await this._adapter.writeBinaryAtomic(entryPath, source, {
@@ -171,7 +354,7 @@ export class CacheEngine {
       });
 
       // Calculate expiration
-      const now = Date.now();
+      const now = this._now();
       const ttlMs = options?.ttlMs ?? this._config.defaultTtlMs;
       const expiresAt = ttlMs !== undefined ? now + ttlMs : undefined;
 
@@ -188,10 +371,19 @@ export class CacheEngine {
         metadata: options?.metadata,
       };
 
+      // Emit write event
+      this._emit({
+        type: "cache_write",
+        key,
+        sizeBytes: writeResult.sizeBytes,
+        source: source.type,
+        durationMs: now - startTime,
+      });
+
       // Update index atomically
       await this._indexMutex.runExclusive(async () => {
         this._index = addEntryToIndex(this._index, entryMeta);
-        await this._indexStore.save(this._index);
+        await this._scheduleIndexSave();
       });
 
       // Auto-prune if configured
@@ -203,7 +395,7 @@ export class CacheEngine {
       }
 
       const entry = this._entryWithPath(entryMeta);
-      return { status: "created" as const, entry };
+      return { status: "created", entry };
     });
   }
 
@@ -220,25 +412,34 @@ export class CacheEngine {
 
     const entryMeta = this._index.entries[key];
     if (!entryMeta) {
+      this._emit({ type: "cache_miss", key, reason: "not_found" });
       return null;
     }
 
     // Check expiration
-    const now = Date.now();
-    if (entryMeta.expiresAt !== undefined && entryMeta.expiresAt < now) {
-      // Entry is expired
+    const now = this._now();
+    if (isEntryExpired(entryMeta, now)) {
+      this._emit({ type: "cache_miss", key, reason: "expired" });
       return null;
     }
 
     // Update lastAccessedAt
     await this._indexMutex.runExclusive(async () => {
       this._index = touchEntry(this._index, key, now);
-      await this._indexStore.save(this._index);
+      await this._scheduleIndexSave();
     });
 
     const entry = this._entryWithPath(entryMeta);
     const uri = await this._adapter.getPublicUri(entry.path);
 
+    // Emit hit event
+    this._emit({
+      type: "cache_hit",
+      key,
+      sizeBytes: entry.sizeBytes,
+      ageMs: now - entry.createdAt,
+    });
+
     return { entry, uri };
   }
 
@@ -253,13 +454,7 @@ export class CacheEngine {
       return false;
     }
 
-    // Check expiration
-    const now = Date.now();
-    if (entryMeta.expiresAt !== undefined && entryMeta.expiresAt < now) {
-      return false;
-    }
-
-    return true;
+    return isEntryValid(entryMeta, this._now());
   }
 
   /**
@@ -273,29 +468,230 @@ export class CacheEngine {
       return null;
     }
 
-    // Check expiration
-    const now = Date.now();
-    if (entryMeta.expiresAt !== undefined && entryMeta.expiresAt < now) {
+    if (isEntryExpired(entryMeta, this._now())) {
       return null;
     }
 
     return this._entryWithPath(entryMeta);
   }
 
+  /**
+   * Get the public URI for a cached entry without updating lastAccessedAt.
+   * Useful for scenarios where you need the URI but don't want to affect LRU ordering.
+   * Returns null if entry doesn't exist or is expired.
+   */
+  async getUri(key: string): Promise<string | null> {
+    this._ensureInitialized();
+
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return null;
+    }
+
+    if (isEntryExpired(entryMeta, this._now())) {
+      return null;
+    }
+
+    const entry = this._entryWithPath(entryMeta);
+    return this._adapter.getPublicUri(entry.path);
+  }
+
+  /**
+   * Manually update the lastAccessedAt timestamp for an entry.
+   * Useful for refreshing LRU ordering without reading the entry.
+   * Returns true if entry was touched, false if not found or expired.
+   */
+  async touch(key: string): Promise<boolean> {
+    this._ensureInitialized();
+
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return false;
+    }
+
+    const now = this._now();
+    if (isEntryExpired(entryMeta, now)) {
+      return false;
+    }
+
+    await this._indexMutex.runExclusive(async () => {
+      this._index = touchEntry(this._index, key, now);
+      await this._scheduleIndexSave();
+    });
+
+    return true;
+  }
+
+  /**
+   * Set the TTL for an existing entry.
+   * @param key - The cache key
+   * @param ttlMs - TTL in milliseconds from now. Use undefined to remove expiration.
+   * @returns true if entry was updated, false if not found or already expired
+   */
+  async setTtl(key: string, ttlMs: number | undefined): Promise<boolean> {
+    this._ensureInitialized();
+
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return false;
+    }
+
+    const now = this._now();
+    if (isEntryExpired(entryMeta, now)) {
+      return false;
+    }
+
+    const newExpiresAt = ttlMs !== undefined ? now + ttlMs : undefined;
+
+    await this._indexMutex.runExclusive(async () => {
+      const updatedEntry: ICacheEntryMeta = {
+        ...entryMeta,
+        expiresAt: newExpiresAt,
+      };
+      this._index = addEntryToIndex(this._index, updatedEntry, now);
+      await this._scheduleIndexSave();
+    });
+
+    return true;
+  }
+
+  /**
+   * Extend the TTL of an existing entry by an additional duration.
+   * If the entry has no expiration, this is a no-op (returns true).
+   * @param key - The cache key
+   * @param additionalMs - Additional milliseconds to add to current expiration
+   * @returns true if entry was updated, false if not found or already expired
+   */
+  async extendTtl(key: string, additionalMs: number): Promise<boolean> {
+    this._ensureInitialized();
+
+    const entryMeta = this._index.entries[key];
+    if (!entryMeta) {
+      return false;
+    }
+
+    const now = this._now();
+    if (isEntryExpired(entryMeta, now)) {
+      return false;
+    }
+
+    // If no expiration, nothing to extend
+    if (entryMeta.expiresAt === undefined) {
+      return true;
+    }
+
+    const newExpiresAt = entryMeta.expiresAt + additionalMs;
+
+    await this._indexMutex.runExclusive(async () => {
+      const updatedEntry: ICacheEntryMeta = {
+        ...entryMeta,
+        expiresAt: newExpiresAt,
+      };
+      this._index = addEntryToIndex(this._index, updatedEntry, now);
+      await this._scheduleIndexSave();
+    });
+
+    return true;
+  }
+
+  /**
+   * Read-through cache helper: get from cache or fetch and store.
+   *
+   * This implements the common pattern:
+   * 1. Try to get from cache
+   * 2. If not found/expired, call fetcher to get data
+   * 3. Store the fetched data in cache
+   * 4. Return the entry
+   *
+   * @param key - The cache key
+   * @param fetcher - Async function that returns bytes to cache if key doesn't exist
+   * @returns The cached entry with URI and whether it was fetched
+   *
+   * @example
+   * ```typescript
+   * const result = await cache.getOrPut("user:123:avatar", async (key) => {
+   *   const response = await fetch(`https://api.example.com/avatar/${key}`);
+   *   const bytes = new Uint8Array(await response.arrayBuffer());
+   *   return { bytes, ext: ".png", ttlMs: 86400000 };
+   * });
+   * console.log(result.uri, result.fetched);
+   * ```
+   */
+  async getOrPut(key: string, fetcher: TFetcher): Promise<IGetOrPutResult> {
+    this._ensureInitialized();
+
+    // Try to get from cache first
+    const existing = await this.get(key);
+    if (existing) {
+      return {
+        entry: existing.entry,
+        uri: existing.uri,
+        fetched: false,
+      };
+    }
+
+    // Not in cache, fetch and store
+    const fetchResult = await fetcher(key);
+
+    const putResult = await this.putFromBytes(key, fetchResult.bytes, {
+      ttlMs: fetchResult.ttlMs,
+      ext: fetchResult.ext,
+      metadata: fetchResult.metadata,
+    });
+
+    const uri = await this._adapter.getPublicUri(putResult.entry.path);
+
+    return {
+      entry: putResult.entry,
+      uri,
+      fetched: true,
+    };
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // List/Query Operations
   // ─────────────────────────────────────────────────────────────────
 
+  /**
+   * Get all valid (non-expired) cache keys.
+   * More efficient than list() when you only need keys.
+   */
+  async keys(): Promise<ReadonlyArray<string>> {
+    this._ensureInitialized();
+
+    const now = this._now();
+    return Object.values(this._index.entries)
+      .filter((e) => isEntryValid(e, now))
+      .map((e) => e.key);
+  }
+
+  /**
+   * Get the count of valid (non-expired) entries.
+   * More efficient than list().length when you only need the count.
+   */
+  async count(): Promise<number> {
+    this._ensureInitialized();
+
+    const now = this._now();
+    let validCount = 0;
+    for (const entry of Object.values(this._index.entries)) {
+      if (isEntryValid(entry, now)) {
+        validCount++;
+      }
+    }
+    return validCount;
+  }
+
   /**
    * List entries with sorting, filtering, pagination.
    */
   async list(options?: IListOptions): Promise<ReadonlyArray<ICacheEntry>> {
     this._ensureInitialized();
 
-    const now = Date.now();
+    const now = this._now();
     let entries = Object.values(this._index.entries)
       // Filter out expired entries
-      .filter((e) => e.expiresAt === undefined || e.expiresAt >= now)
+      .filter((e) => isEntryValid(e, now))
       // Apply custom filter if provided
       .filter((e) => (options?.filter ? options.filter(e) : true));
 
@@ -340,10 +736,8 @@ export class CacheEngine {
   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
-    );
+    const now = this._now();
+    const validEntries = Object.values(this._index.entries).filter((e) => isEntryValid(e, now));
 
     if (validEntries.length === 0) {
       return {
@@ -386,7 +780,11 @@ export class CacheEngine {
     this._ensureInitialized();
 
     return this._keyMutex.runExclusive(key, async () => {
-      return this._removeEntry(key);
+      const removed = await this._removeEntry(key);
+      if (removed) {
+        this._emit({ type: "cache_remove", key, reason: "explicit" });
+      }
+      return removed;
     });
   }
 
@@ -399,7 +797,7 @@ export class CacheEngine {
       return false;
     }
 
-    const entryPath = `${ENTRIES_DIR}/${entryMeta.hash}${entryMeta.ext}`;
+    const entryPath = buildEntryPath(entryMeta.hash, entryMeta.ext);
 
     // Remove file
     await this._adapter.remove(entryPath);
@@ -407,7 +805,7 @@ export class CacheEngine {
     // Update index
     await this._indexMutex.runExclusive(async () => {
       this._index = removeEntriesFromIndex(this._index, [key]);
-      await this._indexStore.save(this._index);
+      await this._scheduleIndexSave();
     });
 
     return true;
@@ -419,18 +817,25 @@ export class CacheEngine {
   async removeExpired(): Promise<IPruneResult> {
     this._ensureInitialized();
 
-    const now = Date.now();
+    const now = this._now();
     const expired = getExpiredEntries(this._index, now);
 
     if (expired.length === 0) {
-      return {
-        removedCount: 0,
-        freedBytes: 0,
-        removedKeys: [],
-      };
+      return EMPTY_PRUNE_RESULT;
     }
 
-    return this._removeEntries(expired);
+    const result = await this._removeEntries(expired, "expired");
+
+    if (result.removedCount > 0) {
+      this._emit({
+        type: "cache_prune",
+        reason: "expired",
+        removedCount: result.removedCount,
+        freedBytes: result.freedBytes,
+      });
+    }
+
+    return result;
   }
 
   /**
@@ -442,29 +847,40 @@ export class CacheEngine {
     const targets = getLruPruneTargets(this._index, maxSizeBytes);
 
     if (targets.length === 0) {
-      return {
-        removedCount: 0,
-        freedBytes: 0,
-        removedKeys: [],
-      };
+      return EMPTY_PRUNE_RESULT;
     }
 
-    return this._removeEntries(targets);
+    const result = await this._removeEntries(targets, "lru");
+
+    if (result.removedCount > 0) {
+      this._emit({
+        type: "cache_prune",
+        reason: "lru",
+        removedCount: result.removedCount,
+        freedBytes: result.freedBytes,
+      });
+    }
+
+    return result;
   }
 
   /**
    * Remove multiple entries.
    */
-  private async _removeEntries(entries: ReadonlyArray<ICacheEntryMeta>): Promise<IPruneResult> {
+  private async _removeEntries(
+    entries: ReadonlyArray<ICacheEntryMeta>,
+    reason: "expired" | "lru" = "expired"
+  ): Promise<IPruneResult> {
     const removedKeys: string[] = [];
     let freedBytes = 0;
 
     for (const entry of entries) {
-      const entryPath = `${ENTRIES_DIR}/${entry.hash}${entry.ext}`;
+      const entryPath = buildEntryPath(entry.hash, entry.ext);
       try {
         await this._adapter.remove(entryPath);
         removedKeys.push(entry.key);
         freedBytes += entry.sizeBytes;
+        this._emit({ type: "cache_remove", key: entry.key, reason });
       } catch {
         // Ignore removal errors
       }
@@ -474,7 +890,7 @@ export class CacheEngine {
     if (removedKeys.length > 0) {
       await this._indexMutex.runExclusive(async () => {
         this._index = removeEntriesFromIndex(this._index, removedKeys);
-        await this._indexStore.save(this._index);
+        await this._scheduleIndexSave();
       });
     }
 
@@ -504,7 +920,9 @@ export class CacheEngine {
 
       // Clear index
       this._index = createEmptyIndex();
+      // Always save immediately on clear (not debounced)
       await this._indexStore.save(this._index);
+      this._indexDirty = false;
     });
   }
 
@@ -523,7 +941,7 @@ export class CacheEngine {
     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 entryPath = buildEntryPath(entry.hash, entry.ext);
         const exists = await this._adapter.exists(entryPath);
         if (!exists) {
           issues.push(`Missing file for entry "${entry.key}"`);
@@ -564,19 +982,28 @@ export class CacheEngine {
   // Private Helpers
   // ─────────────────────────────────────────────────────────────────
 
+  /**
+   * Throws if the engine has not been initialized.
+   */
   private _ensureInitialized(): void {
     if (!this._initialized) {
       throw new Error("CacheEngine not initialized. Call init() first.");
     }
   }
 
+  /**
+   * Constructs a full cache entry with path from metadata.
+   */
   private _entryWithPath(meta: ICacheEntryMeta): ICacheEntry {
     return {
       ...meta,
-      path: `${ENTRIES_DIR}/${meta.hash}${meta.ext}`,
+      path: buildEntryPath(meta.hash, meta.ext),
     };
   }
 
+  /**
+   * Extracts file extension from binary source if possible.
+   */
   private _extractExtension(source: TBinarySource): string {
     switch (source.type) {
       case "url": {
@@ -602,20 +1029,7 @@ export class CacheEngine {
       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 "";
+        return mime ? (MIME_TO_EXT[mime] ?? "") : "";
       }
       case "bytes":
         return "";