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

package/lib/module/core/errors.js

@@ -0,0 +1,71 @@
+/**
+ * Base error class for cache operations.
+ */
+export class CacheError extends Error {
+  constructor(message) {
+    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 {
+  code = "UNSUPPORTED_SOURCE";
+  constructor(sourceType, adapterKind) {
+    super(`Adapter "${adapterKind}" does not support source type "${sourceType}"`);
+    this.sourceType = sourceType;
+    this.adapterKind = adapterKind;
+  }
+}
+
+/**
+ * Thrown when an adapter I/O operation fails.
+ */
+export class AdapterIOError extends CacheError {
+  code = "ADAPTER_IO_ERROR";
+  constructor(operation, path, cause) {
+    super(`Adapter I/O error during "${operation}" at path "${path}": ${cause?.message ?? "unknown"}`);
+    this.operation = operation;
+    this.path = path;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Thrown when the cache index is corrupt and cannot be parsed.
+ */
+export class CorruptIndexError extends CacheError {
+  code = "CORRUPT_INDEX";
+  constructor(reason, cause) {
+    super(`Cache index is corrupt: ${reason}`);
+    this.reason = reason;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Internal error when attempting to overwrite an immutable entry.
+ * Public API converts this to {status: "exists"} response.
+ */
+export class ImmutableConflictError extends CacheError {
+  code = "IMMUTABLE_CONFLICT";
+  constructor(key) {
+    super(`Cannot overwrite immutable entry with key "${key}"`);
+    this.key = key;
+  }
+}
+
+/**
+ * Thrown when a required entry is not found.
+ */
+export class EntryNotFoundError extends CacheError {
+  code = "ENTRY_NOT_FOUND";
+  constructor(key) {
+    super(`Cache entry not found for key "${key}"`);
+    this.key = key;
+  }
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CacheError","Error","constructor","message","name","Object","setPrototypeOf","new","target","prototype","UnsupportedSourceError","code","sourceType","adapterKind","AdapterIOError","operation","path","cause","CorruptIndexError","reason","ImmutableConflictError","key","EntryNotFoundError"],"sourceRoot":"../../../src","sources":["core/errors.ts"],"mappings":"AAEA;AACA;AACA;AACA,OAAO,MAAeA,UAAU,SAASC,KAAK,CAAC;EAG7CC,WAAWA,CAACC,OAAe,EAAE;IAC3B,KAAK,CAACA,OAAO,CAAC;IACd,IAAI,CAACC,IAAI,GAAG,IAAI,CAACF,WAAW,CAACE,IAAI;IACjCC,MAAM,CAACC,cAAc,CAAC,IAAI,EAAEC,GAAG,CAACC,MAAM,CAACC,SAAS,CAAC;EACnD;AACF;;AAEA;AACA;AACA;AACA,OAAO,MAAMC,sBAAsB,SAASV,UAAU,CAAC;EAC5CW,IAAI,GAAG,oBAAoB;EAEpCT,WAAWA,CACOU,UAAiC,EACjCC,WAAmB,EACnC;IACA,KAAK,CAAC,YAAYA,WAAW,mCAAmCD,UAAU,GAAG,CAAC;IAAC,KAH/DA,UAAiC,GAAjCA,UAAiC;IAAA,KACjCC,WAAmB,GAAnBA,WAAmB;EAGrC;AACF;;AAEA;AACA;AACA;AACA,OAAO,MAAMC,cAAc,SAASd,UAAU,CAAC;EACpCW,IAAI,GAAG,kBAAkB;EAElCT,WAAWA,CACOa,SAAiB,EACjBC,IAAY,EACZC,KAAa,EAC7B;IACA,KAAK,CACH,6BAA6BF,SAAS,cAAcC,IAAI,MAAMC,KAAK,EAAEd,OAAO,IAAI,SAAS,EAC3F,CAAC;IAAC,KANcY,SAAiB,GAAjBA,SAAiB;IAAA,KACjBC,IAAY,GAAZA,IAAY;IAAA,KACZC,KAAa,GAAbA,KAAa;EAK/B;AACF;;AAEA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,SAASlB,UAAU,CAAC;EACvCW,IAAI,GAAG,eAAe;EAE/BT,WAAWA,CACOiB,MAAc,EACdF,KAAa,EAC7B;IACA,KAAK,CAAC,2BAA2BE,MAAM,EAAE,CAAC;IAAC,KAH3BA,MAAc,GAAdA,MAAc;IAAA,KACdF,KAAa,GAAbA,KAAa;EAG/B;AACF;;AAEA;AACA;AACA;AACA;AACA,OAAO,MAAMG,sBAAsB,SAASpB,UAAU,CAAC;EAC5CW,IAAI,GAAG,oBAAoB;EAEpCT,WAAWA,CAAiBmB,GAAW,EAAE;IACvC,KAAK,CAAC,8CAA8CA,GAAG,GAAG,CAAC;IAAC,KADlCA,GAAW,GAAXA,GAAW;EAEvC;AACF;;AAEA;AACA;AACA;AACA,OAAO,MAAMC,kBAAkB,SAAStB,UAAU,CAAC;EACxCW,IAAI,GAAG,iBAAiB;EAEjCT,WAAWA,CAAiBmB,GAAW,EAAE;IACvC,KAAK,CAAC,kCAAkCA,GAAG,GAAG,CAAC;IAAC,KADtBA,GAAW,GAAXA,GAAW;EAEvC;AACF","ignoreList":[]}

package/lib/module/core/hash.js

@@ -0,0 +1,76 @@
+/**
+ * Cross-platform SHA-256 hashing utility.
+ * Uses SubtleCrypto on web and native platforms that support it.
+ */
+
+/**
+ * Converts an ArrayBuffer to a lowercase hex string.
+ */
+function arrayBufferToHex(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+/**
+ * Converts a string to a Uint8Array using UTF-8 encoding.
+ */
+function stringToUint8Array(str) {
+  const encoder = new TextEncoder();
+  return encoder.encode(str);
+}
+
+/**
+ * Computes SHA-256 hash of the input string.
+ * Returns lowercase hex string.
+ *
+ * Uses SubtleCrypto API which is available in:
+ * - Modern browsers
+ * - React Native (via Hermes or polyfill)
+ * - Node.js 15+
+ */
+export async function hash(input) {
+  // Use SubtleCrypto (available in browsers and modern RN)
+  if (typeof globalThis.crypto?.subtle?.digest === "function") {
+    const data = stringToUint8Array(input);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", data.buffer);
+    return arrayBufferToHex(hashBuffer);
+  }
+
+  // Fallback: Simple hash for environments without crypto
+  // This is a basic djb2-based hash - NOT cryptographically secure
+  // Should only be used as last resort fallback
+  return fallbackHash(input);
+}
+
+/**
+ * Simple non-cryptographic hash fallback.
+ * Used only when SubtleCrypto is unavailable.
+ */
+function fallbackHash(input) {
+  let h1 = 0xdeadbeef;
+  let h2 = 0x41c6ce57;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+  h1 ^= Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507);
+  h2 ^= Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  const result = 4294967296 * (2097151 & h2) + (h1 >>> 0);
+  return result.toString(16).padStart(16, "0");
+}
+
+/**
+ * Synchronous hash for cases where async is not possible.
+ * Uses fallback algorithm - prefer async hash() when possible.
+ */
+export function hashSync(input) {
+  return fallbackHash(input);
+}
+//# sourceMappingURL=hash.js.map

package/lib/module/core/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["arrayBufferToHex","buffer","bytes","Uint8Array","hex","i","length","toString","padStart","stringToUint8Array","str","encoder","TextEncoder","encode","hash","input","globalThis","crypto","subtle","digest","data","hashBuffer","fallbackHash","h1","h2","ch","charCodeAt","Math","imul","result","hashSync"],"sourceRoot":"../../../src","sources":["core/hash.ts"],"mappings":"AAAA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA,SAASA,gBAAgBA,CAACC,MAAmB,EAAU;EACrD,MAAMC,KAAK,GAAG,IAAIC,UAAU,CAACF,MAAM,CAAC;EACpC,IAAIG,GAAG,GAAG,EAAE;EACZ,KAAK,IAAIC,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGH,KAAK,CAACI,MAAM,EAAED,CAAC,EAAE,EAAE;IACrCD,GAAG,IAAIF,KAAK,CAACG,CAAC,CAAC,CAACE,QAAQ,CAAC,EAAE,CAAC,CAACC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;EAC/C;EACA,OAAOJ,GAAG;AACZ;;AAEA;AACA;AACA;AACA,SAASK,kBAAkBA,CAACC,GAAW,EAAc;EACnD,MAAMC,OAAO,GAAG,IAAIC,WAAW,CAAC,CAAC;EACjC,OAAOD,OAAO,CAACE,MAAM,CAACH,GAAG,CAAC;AAC5B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeI,IAAIA,CAACC,KAAa,EAAmB;EACzD;EACA,IAAI,OAAOC,UAAU,CAACC,MAAM,EAAEC,MAAM,EAAEC,MAAM,KAAK,UAAU,EAAE;IAC3D,MAAMC,IAAI,GAAGX,kBAAkB,CAACM,KAAK,CAAC;IACtC,MAAMM,UAAU,GAAG,MAAML,UAAU,CAACC,MAAM,CAACC,MAAM,CAACC,MAAM,CAAC,SAAS,EAAEC,IAAI,CAACnB,MAAqB,CAAC;IAC/F,OAAOD,gBAAgB,CAACqB,UAAU,CAAC;EACrC;;EAEA;EACA;EACA;EACA,OAAOC,YAAY,CAACP,KAAK,CAAC;AAC5B;;AAEA;AACA;AACA;AACA;AACA,SAASO,YAAYA,CAACP,KAAa,EAAU;EAC3C,IAAIQ,EAAE,GAAG,UAAU;EACnB,IAAIC,EAAE,GAAG,UAAU;EAEnB,KAAK,IAAInB,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGU,KAAK,CAACT,MAAM,EAAED,CAAC,EAAE,EAAE;IACrC,MAAMoB,EAAE,GAAGV,KAAK,CAACW,UAAU,CAACrB,CAAC,CAAC;IAC9BkB,EAAE,GAAGI,IAAI,CAACC,IAAI,CAACL,EAAE,GAAGE,EAAE,EAAE,UAAU,CAAC;IACnCD,EAAE,GAAGG,IAAI,CAACC,IAAI,CAACJ,EAAE,GAAGC,EAAE,EAAE,UAAU,CAAC;EACrC;EAEAF,EAAE,GAAGI,IAAI,CAACC,IAAI,CAACL,EAAE,GAAIA,EAAE,KAAK,EAAG,EAAE,UAAU,CAAC;EAC5CA,EAAE,IAAII,IAAI,CAACC,IAAI,CAACJ,EAAE,GAAIA,EAAE,KAAK,EAAG,EAAE,UAAU,CAAC;EAC7CA,EAAE,GAAGG,IAAI,CAACC,IAAI,CAACJ,EAAE,GAAIA,EAAE,KAAK,EAAG,EAAE,UAAU,CAAC;EAC5CA,EAAE,IAAIG,IAAI,CAACC,IAAI,CAACL,EAAE,GAAIA,EAAE,KAAK,EAAG,EAAE,UAAU,CAAC;EAE7C,MAAMM,MAAM,GAAG,UAAU,IAAI,OAAO,GAAGL,EAAE,CAAC,IAAID,EAAE,KAAK,CAAC,CAAC;EACvD,OAAOM,MAAM,CAACtB,QAAQ,CAAC,EAAE,CAAC,CAACC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;AAC9C;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASsB,QAAQA,CAACf,KAAa,EAAU;EAC9C,OAAOO,YAAY,CAACP,KAAK,CAAC;AAC5B","ignoreList":[]}

package/lib/module/core/indexStore.js

@@ -0,0 +1,168 @@
+import { CorruptIndexError, AdapterIOError } from "./errors";
+import { createEmptyIndex } from "./prune";
+const INDEX_VERSION = 1;
+
+/**
+ * Manages persistence of the cache index via the storage adapter.
+ */
+export class IndexStore {
+  constructor(adapter, indexPath) {
+    this._adapter = adapter;
+    this._indexPath = indexPath;
+  }
+
+  /**
+   * Load index from storage.
+   * Returns empty index if file doesn't exist.
+   * Throws CorruptIndexError if index is malformed.
+   */
+  async load() {
+    try {
+      const exists = await this._adapter.exists(this._indexPath);
+      if (!exists) {
+        return createEmptyIndex();
+      }
+      const content = await this._adapter.readText(this._indexPath, "utf8");
+      const parsed = JSON.parse(content);
+      return this._validateIndex(parsed);
+    } catch (error) {
+      if (error instanceof CorruptIndexError) {
+        throw error;
+      }
+      if (error instanceof SyntaxError) {
+        throw new CorruptIndexError("Invalid JSON", error);
+      }
+      // File doesn't exist or other read error - return empty
+      if (error instanceof AdapterIOError) {
+        return createEmptyIndex();
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Save index atomically via the adapter.
+   */
+  async save(index) {
+    const content = JSON.stringify(index, null, 2);
+    await this._adapter.writeTextAtomic(this._indexPath, content, "utf8");
+  }
+
+  /**
+   * Validate and rebuild index from filesystem if corrupt.
+   * Scans the entries directory and reconstructs metadata.
+   */
+  async rebuild(entriesDir) {
+    const entries = {};
+    let totalSizeBytes = 0;
+    try {
+      const files = await this._adapter.listDir(entriesDir);
+      for (const file of files) {
+        try {
+          const filePath = `${entriesDir}/${file}`;
+          const stat = await this._adapter.stat(filePath);
+
+          // Extract hash and extension from filename
+          const lastDot = file.lastIndexOf(".");
+          const hash = lastDot > 0 ? file.substring(0, lastDot) : file;
+          const ext = lastDot > 0 ? file.substring(lastDot) : "";
+
+          // Create minimal entry metadata
+          // Note: We lose the original key during rebuild
+          const entry = {
+            key: hash,
+            // Use hash as key since original is lost
+            hash,
+            ext,
+            sizeBytes: stat.sizeBytes,
+            createdAt: stat.mtimeMs,
+            lastAccessedAt: stat.mtimeMs
+          };
+          entries[hash] = entry;
+          totalSizeBytes += stat.sizeBytes;
+        } catch {
+          // Skip files that can't be stat'd
+          continue;
+        }
+      }
+    } catch {
+      // If we can't list the directory, return empty index
+      return createEmptyIndex();
+    }
+    const rebuiltIndex = {
+      version: INDEX_VERSION,
+      entries,
+      totalSizeBytes,
+      lastModifiedAt: Date.now()
+    };
+
+    // Save the rebuilt index
+    await this.save(rebuiltIndex);
+    return rebuiltIndex;
+  }
+
+  /**
+   * Validates that the parsed object is a valid ICacheIndex.
+   */
+  _validateIndex(parsed) {
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new CorruptIndexError("Index is not an object");
+    }
+    const obj = parsed;
+
+    // Check version
+    if (obj.version !== INDEX_VERSION) {
+      throw new CorruptIndexError(`Unsupported version: ${String(obj.version)}`);
+    }
+
+    // Check entries
+    if (typeof obj.entries !== "object" || obj.entries === null) {
+      throw new CorruptIndexError("Entries is not an object");
+    }
+
+    // Validate each entry has required fields
+    const entries = obj.entries;
+    for (const [key, entry] of Object.entries(entries)) {
+      this._validateEntry(key, entry);
+    }
+
+    // Check totalSizeBytes
+    if (typeof obj.totalSizeBytes !== "number" || obj.totalSizeBytes < 0) {
+      throw new CorruptIndexError("Invalid totalSizeBytes");
+    }
+
+    // Check lastModifiedAt
+    if (typeof obj.lastModifiedAt !== "number") {
+      throw new CorruptIndexError("Invalid lastModifiedAt");
+    }
+    return {
+      version: INDEX_VERSION,
+      entries: entries,
+      totalSizeBytes: obj.totalSizeBytes,
+      lastModifiedAt: obj.lastModifiedAt
+    };
+  }
+
+  /**
+   * Validates that an entry has all required fields.
+   */
+  _validateEntry(key, entry) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new CorruptIndexError(`Entry "${key}" is not an object`);
+    }
+    const obj = entry;
+    const requiredStrings = ["key", "hash", "ext"];
+    const requiredNumbers = ["sizeBytes", "createdAt", "lastAccessedAt"];
+    for (const field of requiredStrings) {
+      if (typeof obj[field] !== "string") {
+        throw new CorruptIndexError(`Entry "${key}" missing string field "${field}"`);
+      }
+    }
+    for (const field of requiredNumbers) {
+      if (typeof obj[field] !== "number") {
+        throw new CorruptIndexError(`Entry "${key}" missing number field "${field}"`);
+      }
+    }
+  }
+}
+//# sourceMappingURL=indexStore.js.map

package/lib/module/core/indexStore.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CorruptIndexError","AdapterIOError","createEmptyIndex","INDEX_VERSION","IndexStore","constructor","adapter","indexPath","_adapter","_indexPath","load","exists","content","readText","parsed","JSON","parse","_validateIndex","error","SyntaxError","save","index","stringify","writeTextAtomic","rebuild","entriesDir","entries","totalSizeBytes","files","listDir","file","filePath","stat","lastDot","lastIndexOf","hash","substring","ext","entry","key","sizeBytes","createdAt","mtimeMs","lastAccessedAt","rebuiltIndex","version","lastModifiedAt","Date","now","obj","String","Object","_validateEntry","requiredStrings","requiredNumbers","field"],"sourceRoot":"../../../src","sources":["core/indexStore.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/core/mutex.js

@@ -0,0 +1,135 @@
+/**
+ * Async mutex for serializing critical sections.
+ * Ensures only one operation runs at a time within a critical section.
+ */
+export class Mutex {
+  _queue = [];
+  _locked = false;
+
+  /**
+   * Acquires the mutex lock.
+   * Returns a release function that must be called when done.
+   */
+  async acquire() {
+    return new Promise(resolve => {
+      const tryAcquire = () => {
+        if (!this._locked) {
+          this._locked = true;
+          resolve(this._createRelease());
+        } else {
+          this._queue.push(tryAcquire);
+        }
+      };
+      tryAcquire();
+    });
+  }
+
+  /**
+   * Creates a release function for the current lock holder.
+   */
+  _createRelease() {
+    let released = false;
+    return () => {
+      if (released) {
+        return; // Prevent double-release
+      }
+      released = true;
+      this._locked = false;
+      const next = this._queue.shift();
+      if (next) {
+        next();
+      }
+    };
+  }
+
+  /**
+   * Returns whether the mutex is currently locked.
+   */
+  get isLocked() {
+    return this._locked;
+  }
+
+  /**
+   * Executes a function with the mutex held.
+   * Automatically releases the mutex when done.
+   */
+  async runExclusive(fn) {
+    const release = await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+}
+
+/**
+ * Keyed mutex for per-key locking.
+ * Allows concurrent operations on different keys while serializing same-key operations.
+ */
+export class KeyedMutex {
+  _mutexes = new Map();
+  _refCounts = new Map();
+
+  /**
+   * Acquires lock for a specific key.
+   * Returns a release function that must be called when done.
+   */
+  async acquire(key) {
+    // Get or create mutex for this key
+    let mutex = this._mutexes.get(key);
+    if (!mutex) {
+      mutex = new Mutex();
+      this._mutexes.set(key, mutex);
+      this._refCounts.set(key, 0);
+    }
+
+    // Increment ref count
+    this._refCounts.set(key, (this._refCounts.get(key) ?? 0) + 1);
+
+    // Acquire the mutex
+    const innerRelease = await mutex.acquire();
+
+    // Return wrapped release that cleans up when ref count hits 0
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+
+      // Release the inner mutex
+      innerRelease();
+
+      // Decrement ref count and clean up if zero
+      const count = (this._refCounts.get(key) ?? 1) - 1;
+      if (count <= 0) {
+        this._mutexes.delete(key);
+        this._refCounts.delete(key);
+      } else {
+        this._refCounts.set(key, count);
+      }
+    };
+  }
+
+  /**
+   * Executes a function with the keyed mutex held.
+   * Automatically releases the mutex when done.
+   */
+  async runExclusive(key, fn) {
+    const release = await this.acquire(key);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Returns the number of active keys with pending operations.
+   */
+  get activeKeyCount() {
+    return this._mutexes.size;
+  }
+}
+//# sourceMappingURL=mutex.js.map

package/lib/module/core/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Mutex","_queue","_locked","acquire","Promise","resolve","tryAcquire","_createRelease","push","released","next","shift","isLocked","runExclusive","fn","release","KeyedMutex","_mutexes","Map","_refCounts","key","mutex","get","set","innerRelease","count","delete","activeKeyCount","size"],"sourceRoot":"../../../src","sources":["core/mutex.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/core/prune.js

@@ -0,0 +1,116 @@
+/**
+ * Options for pruning operations.
+ */
+
+/**
+ * Identifies entries to remove based on TTL expiration.
+ * Returns entries that have expired (expiresAt < now).
+ */
+export function getExpiredEntries(index, now = Date.now()) {
+  const expired = [];
+  for (const entry of Object.values(index.entries)) {
+    if (entry.expiresAt !== undefined && entry.expiresAt < now) {
+      expired.push(entry);
+    }
+  }
+  return expired;
+}
+
+/**
+ * Identifies entries to remove based on LRU policy to meet size limit.
+ * Sorts entries by lastAccessedAt (oldest first) and returns entries
+ * that need to be removed to get under maxSizeBytes.
+ */
+export function getLruPruneTargets(index, maxSizeBytes) {
+  if (index.totalSizeBytes <= maxSizeBytes) {
+    return [];
+  }
+
+  // Sort entries by lastAccessedAt ascending (oldest first = LRU candidates)
+  const sortedEntries = Object.values(index.entries).sort((a, b) => a.lastAccessedAt - b.lastAccessedAt);
+  const toRemove = [];
+  let currentSize = index.totalSizeBytes;
+  for (const entry of sortedEntries) {
+    if (currentSize <= maxSizeBytes) {
+      break;
+    }
+    toRemove.push(entry);
+    currentSize -= entry.sizeBytes;
+  }
+  return toRemove;
+}
+
+/**
+ * Creates a new index with the specified entries removed.
+ * Returns a new ICacheIndex without mutating the original.
+ */
+export function removeEntriesFromIndex(index, keysToRemove) {
+  const keySet = new Set(keysToRemove);
+  const newEntries = {};
+  let newTotalSize = 0;
+  for (const [key, entry] of Object.entries(index.entries)) {
+    if (!keySet.has(key)) {
+      newEntries[key] = entry;
+      newTotalSize += entry.sizeBytes;
+    }
+  }
+  return {
+    version: 1,
+    entries: newEntries,
+    totalSizeBytes: newTotalSize,
+    lastModifiedAt: Date.now()
+  };
+}
+
+/**
+ * Adds or updates an entry in the index.
+ * Returns a new ICacheIndex without mutating the original.
+ */
+export function addEntryToIndex(index, entry) {
+  const existingEntry = index.entries[entry.key];
+  const sizeDelta = entry.sizeBytes - (existingEntry?.sizeBytes ?? 0);
+  return {
+    version: 1,
+    entries: {
+      ...index.entries,
+      [entry.key]: entry
+    },
+    totalSizeBytes: index.totalSizeBytes + sizeDelta,
+    lastModifiedAt: Date.now()
+  };
+}
+
+/**
+ * Updates the lastAccessedAt timestamp for an entry.
+ * Returns a new ICacheIndex without mutating the original.
+ */
+export function touchEntry(index, key, accessedAt = Date.now()) {
+  const entry = index.entries[key];
+  if (!entry) {
+    return index;
+  }
+  return {
+    ...index,
+    entries: {
+      ...index.entries,
+      [key]: {
+        ...entry,
+        lastAccessedAt: accessedAt
+      }
+    },
+    lastModifiedAt: accessedAt
+  };
+}
+
+/**
+ * Creates an empty cache index.
+ */
+export function createEmptyIndex() {
+  return {
+    version: 1,
+    entries: {},
+    totalSizeBytes: 0,
+    lastModifiedAt: Date.now()
+  };
+}
+//# sourceMappingURL=prune.js.map

package/lib/module/core/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["getExpiredEntries","index","now","Date","expired","entry","Object","values","entries","expiresAt","undefined","push","getLruPruneTargets","maxSizeBytes","totalSizeBytes","sortedEntries","sort","a","b","lastAccessedAt","toRemove","currentSize","sizeBytes","removeEntriesFromIndex","keysToRemove","keySet","Set","newEntries","newTotalSize","key","has","version","lastModifiedAt","addEntryToIndex","existingEntry","sizeDelta","touchEntry","accessedAt","createEmptyIndex"],"sourceRoot":"../../../src","sources":["core/prune.ts"],"mappings":"AAEA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA,OAAO,SAASA,iBAAiBA,CAC/BC,KAAkB,EAClBC,GAAW,GAAGC,IAAI,CAACD,GAAG,CAAC,CAAC,EACQ;EAChC,MAAME,OAA0B,GAAG,EAAE;EAErC,KAAK,MAAMC,KAAK,IAAIC,MAAM,CAACC,MAAM,CAACN,KAAK,CAACO,OAAO,CAAC,EAAE;IAChD,IAAIH,KAAK,CAACI,SAAS,KAAKC,SAAS,IAAIL,KAAK,CAACI,SAAS,GAAGP,GAAG,EAAE;MAC1DE,OAAO,CAACO,IAAI,CAACN,KAAK,CAAC;IACrB;EACF;EAEA,OAAOD,OAAO;AAChB;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASQ,kBAAkBA,CAChCX,KAAkB,EAClBY,YAAoB,EACY;EAChC,IAAIZ,KAAK,CAACa,cAAc,IAAID,YAAY,EAAE;IACxC,OAAO,EAAE;EACX;;EAEA;EACA,MAAME,aAAa,GAAGT,MAAM,CAACC,MAAM,CAACN,KAAK,CAACO,OAAO,CAAC,CAACQ,IAAI,CACrD,CAACC,CAAC,EAAEC,CAAC,KAAKD,CAAC,CAACE,cAAc,GAAGD,CAAC,CAACC,cACjC,CAAC;EAED,MAAMC,QAA2B,GAAG,EAAE;EACtC,IAAIC,WAAW,GAAGpB,KAAK,CAACa,cAAc;EAEtC,KAAK,MAAMT,KAAK,IAAIU,aAAa,EAAE;IACjC,IAAIM,WAAW,IAAIR,YAAY,EAAE;MAC/B;IACF;IACAO,QAAQ,CAACT,IAAI,CAACN,KAAK,CAAC;IACpBgB,WAAW,IAAIhB,KAAK,CAACiB,SAAS;EAChC;EAEA,OAAOF,QAAQ;AACjB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASG,sBAAsBA,CACpCtB,KAAkB,EAClBuB,YAAmC,EACtB;EACb,MAAMC,MAAM,GAAG,IAAIC,GAAG,CAACF,YAAY,CAAC;EACpC,MAAMG,UAA2C,GAAG,CAAC,CAAC;EACtD,IAAIC,YAAY,GAAG,CAAC;EAEpB,KAAK,MAAM,CAACC,GAAG,EAAExB,KAAK,CAAC,IAAIC,MAAM,CAACE,OAAO,CAACP,KAAK,CAACO,OAAO,CAAC,EAAE;IACxD,IAAI,CAACiB,MAAM,CAACK,GAAG,CAACD,GAAG,CAAC,EAAE;MACpBF,UAAU,CAACE,GAAG,CAAC,GAAGxB,KAAK;MACvBuB,YAAY,IAAIvB,KAAK,CAACiB,SAAS;IACjC;EACF;EAEA,OAAO;IACLS,OAAO,EAAE,CAAC;IACVvB,OAAO,EAAEmB,UAAU;IACnBb,cAAc,EAAEc,YAAY;IAC5BI,cAAc,EAAE7B,IAAI,CAACD,GAAG,CAAC;EAC3B,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAAS+B,eAAeA,CAAChC,KAAkB,EAAEI,KAAsB,EAAe;EACvF,MAAM6B,aAAa,GAAGjC,KAAK,CAACO,OAAO,CAACH,KAAK,CAACwB,GAAG,CAAC;EAC9C,MAAMM,SAAS,GAAG9B,KAAK,CAACiB,SAAS,IAAIY,aAAa,EAAEZ,SAAS,IAAI,CAAC,CAAC;EAEnE,OAAO;IACLS,OAAO,EAAE,CAAC;IACVvB,OAAO,EAAE;MACP,GAAGP,KAAK,CAACO,OAAO;MAChB,CAACH,KAAK,CAACwB,GAAG,GAAGxB;IACf,CAAC;IACDS,cAAc,EAAEb,KAAK,CAACa,cAAc,GAAGqB,SAAS;IAChDH,cAAc,EAAE7B,IAAI,CAACD,GAAG,CAAC;EAC3B,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASkC,UAAUA,CACxBnC,KAAkB,EAClB4B,GAAW,EACXQ,UAAkB,GAAGlC,IAAI,CAACD,GAAG,CAAC,CAAC,EAClB;EACb,MAAMG,KAAK,GAAGJ,KAAK,CAACO,OAAO,CAACqB,GAAG,CAAC;EAChC,IAAI,CAACxB,KAAK,EAAE;IACV,OAAOJ,KAAK;EACd;EAEA,OAAO;IACL,GAAGA,KAAK;IACRO,OAAO,EAAE;MACP,GAAGP,KAAK,CAACO,OAAO;MAChB,CAACqB,GAAG,GAAG;QACL,GAAGxB,KAAK;QACRc,cAAc,EAAEkB;MAClB;IACF,CAAC;IACDL,cAAc,EAAEK;EAClB,CAAC;AACH;;AAEA;AACA;AACA;AACA,OAAO,SAASC,gBAAgBA,CAAA,EAAgB;EAC9C,OAAO;IACLP,OAAO,EAAE,CAAC;IACVvB,OAAO,EAAE,CAAC,CAAC;IACXM,cAAc,EAAE,CAAC;IACjBkB,cAAc,EAAE7B,IAAI,CAACD,GAAG,CAAC;EAC3B,CAAC;AACH","ignoreList":[]}

package/lib/module/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/module/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["core/types.ts"],"mappings":"","ignoreList":[]}

package/lib/module/factory.js

@@ -0,0 +1,49 @@
+import { CacheEngine } from "./core/cacheEngine";
+/**
+ * Creates an immutable file cache instance.
+ *
+ * This is the base factory function. Platform-specific entrypoints
+ * (index.native.ts, index.web.ts) wrap this to auto-select the appropriate adapter.
+ *
+ * @param options - Cache configuration options
+ * @param adapter - Storage adapter (required in base factory)
+ * @returns Initialized CacheEngine instance
+ *
+ * @example
+ * ```typescript
+ * import { createImmutableFileCache } from "react-native-immutable-file-cache";
+ *
+ * const cache = await createImmutableFileCache({
+ *   namespace: "images",
+ *   defaultTtlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+ * });
+ * ```
+ */
+export async function createImmutableFileCache(options) {
+  const {
+    autoInit = true,
+    adapter,
+    ...config
+  } = options;
+  const engine = new CacheEngine(config, adapter);
+  if (autoInit) {
+    await engine.init();
+  }
+  return engine;
+}
+
+/**
+ * Creates a cache engine without auto-initialization.
+ * Useful when you need to control initialization timing.
+ *
+ * @example
+ * ```typescript
+ * const engine = createCacheEngineSync({ namespace: "images" }, adapter);
+ * // Later...
+ * await engine.init();
+ * ```
+ */
+export function createCacheEngineSync(config, adapter) {
+  return new CacheEngine(config, adapter);
+}
+//# sourceMappingURL=factory.js.map

package/lib/module/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CacheEngine","createImmutableFileCache","options","autoInit","adapter","config","engine","init","createCacheEngineSync"],"sourceRoot":"../../src","sources":["factory.ts"],"mappings":"AAEA,SAASA,WAAW,QAAQ,oBAAoB;AAUhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeC,wBAAwBA,CAC5CC,OAA2D,EACrC;EACtB,MAAM;IAAEC,QAAQ,GAAG,IAAI;IAAEC,OAAO;IAAE,GAAGC;EAAO,CAAC,GAAGH,OAAO;EAEvD,MAAMI,MAAM,GAAG,IAAIN,WAAW,CAACK,MAAM,EAAED,OAAO,CAAC;EAE/C,IAAID,QAAQ,EAAE;IACZ,MAAMG,MAAM,CAACC,IAAI,CAAC,CAAC;EACrB;EAEA,OAAOD,MAAM;AACf;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,qBAAqBA,CAACH,MAAoB,EAAED,OAAwB,EAAe;EACjG,OAAO,IAAIJ,WAAW,CAACK,MAAM,EAAED,OAAO,CAAC;AACzC","ignoreList":[]}