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

package/lib/module/core/cacheEngine.js

@@ -3,10 +3,48 @@
 import { IndexStore } from "./indexStore";
 import { Mutex, KeyedMutex } from "./mutex";
 import { hash as defaultHash } from "./hash";
-import { getExpiredEntries, getLruPruneTargets, removeEntriesFromIndex, addEntryToIndex, touchEntry, createEmptyIndex } from "./prune";
+import { getExpiredEntries, getLruPruneTargets, removeEntriesFromIndex, 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 = {
+  "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 = Object.freeze({
+  removedCount: 0,
+  freedBytes: 0,
+  removedKeys: []
+});
+
+/**
+ * Constructs the storage path for an entry.
+ */
+function buildEntryPath(hash, ext) {
+  return `${ENTRIES_DIR}/${hash}${ext}`;
+}
+
 /**
  * Main cache engine implementation.
  * Coordinates all cache operations through the storage adapter.
@@ -16,6 +54,8 @@ export class CacheEngine {
   _keyMutex = new KeyedMutex();
   _index = createEmptyIndex();
   _initialized = false;
+  _indexDirty = false;
+  _debounceTimer = null;
   constructor(config, adapter) {
     this._config = {
       namespace: "default",
@@ -25,6 +65,140 @@ 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() {
+    return this._initialized;
+  }
+
+  /**
+   * Returns the configured namespace.
+   */
+  get namespace() {
+    return this._config.namespace;
+  }
+
+  /**
+   * Returns the storage adapter.
+   */
+  get adapter() {
+    return this._adapter;
+  }
+
+  /**
+   * Returns whether there are pending index writes.
+   * Useful for checking if flush() should be called before shutdown.
+   */
+  get hasPendingWrites() {
+    return this._indexDirty;
+  }
+
+  /**
+   * Schedules an index save, respecting debounce configuration.
+   * If debounceMs is 0, saves immediately.
+   */
+  async _scheduleIndexSave() {
+    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.
+   */
+  async _flushIndex() {
+    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() {
+    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() {
+    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).
+   */
+  _emit(event) {
+    try {
+      this._config.onEvent?.(event);
+    } catch {
+      // Ignore errors in event handlers to prevent disrupting cache operations
+    }
   }
 
   /**
@@ -109,10 +283,10 @@ 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 {
@@ -131,7 +305,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, {
@@ -140,7 +314,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;
 
@@ -157,10 +331,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
@@ -190,23 +373,40 @@ export class CacheEngine {
     this._ensureInitialized();
     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
@@ -222,13 +422,7 @@ export class CacheEngine {
     if (!entryMeta) {
       return false;
     }
-
-    // Check expiration
-    const now = Date.now();
-    if (entryMeta.expiresAt !== undefined && entryMeta.expiresAt < now) {
-      return false;
-    }
-    return true;
+    return isEntryValid(entryMeta, this._now());
   }
 
   /**
@@ -240,28 +434,204 @@ export class CacheEngine {
     if (!entryMeta) {
       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) {
+    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) {
+    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, ttlMs) {
+    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 = {
+        ...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, additionalMs) {
+    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 = {
+        ...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, fetcher) {
+    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() {
+    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() {
+    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) {
     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);
 
@@ -303,8 +673,8 @@ export class CacheEngine {
    */
   async stats() {
     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 {
         entryCount: 0,
@@ -342,7 +712,15 @@ export class CacheEngine {
   async remove(key) {
     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;
     });
   }
 
@@ -354,7 +732,7 @@ export class CacheEngine {
     if (!entryMeta) {
       return false;
     }
-    const entryPath = `${ENTRIES_DIR}/${entryMeta.hash}${entryMeta.ext}`;
+    const entryPath = buildEntryPath(entryMeta.hash, entryMeta.ext);
 
     // Remove file
     await this._adapter.remove(entryPath);
@@ -362,7 +740,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;
   }
@@ -372,16 +750,21 @@ export class CacheEngine {
    */
   async removeExpired() {
     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;
+    }
+    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 this._removeEntries(expired);
+    return result;
   }
 
   /**
@@ -391,27 +774,37 @@ export class CacheEngine {
     this._ensureInitialized();
     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.
    */
-  async _removeEntries(entries) {
+  async _removeEntries(entries, reason = "expired") {
     const removedKeys = [];
     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
       }
@@ -421,7 +814,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();
       });
     }
     return {
@@ -449,7 +842,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;
     });
   }
 
@@ -466,7 +861,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}"`);
@@ -503,17 +898,28 @@ export class CacheEngine {
   // Private Helpers
   // ─────────────────────────────────────────────────────────────────
 
+  /**
+   * Throws if the engine has not been initialized.
+   */
   _ensureInitialized() {
     if (!this._initialized) {
       throw new Error("CacheEngine not initialized. Call init() first.");
     }
   }
+
+  /**
+   * Constructs a full cache entry with path from metadata.
+   */
   _entryWithPath(meta) {
     return {
       ...meta,
-      path: `${ENTRIES_DIR}/${meta.hash}${meta.ext}`
+      path: buildEntryPath(meta.hash, meta.ext)
     };
   }
+
+  /**
+   * Extracts file extension from binary source if possible.
+   */
   _extractExtension(source) {
     switch (source.type) {
       case "url":
@@ -539,20 +945,7 @@ export class CacheEngine {
         {
           // Try to extract from MIME type
           const mime = source.blob.type;
-          if (mime) {
-            const mimeToExt = {
-              "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 "";