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

package/src/core/hash.ts

@@ -0,0 +1,78 @@
+/**
+ * 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: ArrayBuffer): string {
+  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: string): Uint8Array {
+  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: string): Promise<string> {
+  // 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 as ArrayBuffer);
+    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: string): string {
+  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: string): string {
+  return fallbackHash(input);
+}

package/src/core/indexStore.ts

@@ -0,0 +1,184 @@
+import type { IStorageAdapter, TAdapterPath } from "./adapter";
+import type { ICacheIndex, ICacheEntryMeta } from "./types";
+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 {
+  private readonly _adapter: IStorageAdapter;
+  private readonly _indexPath: TAdapterPath;
+
+  constructor(adapter: IStorageAdapter, indexPath: TAdapterPath) {
+    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(): Promise<ICacheIndex> {
+    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) as unknown;
+
+      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: ICacheIndex): Promise<void> {
+    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: TAdapterPath): Promise<ICacheIndex> {
+    const entries: Record<string, ICacheEntryMeta> = {};
+    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: ICacheEntryMeta = {
+            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: ICacheIndex = {
+      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.
+   */
+  private _validateIndex(parsed: unknown): ICacheIndex {
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new CorruptIndexError("Index is not an object");
+    }
+
+    const obj = parsed as Record<string, unknown>;
+
+    // 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 as Record<string, unknown>;
+    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 as Record<string, ICacheEntryMeta>,
+      totalSizeBytes: obj.totalSizeBytes,
+      lastModifiedAt: obj.lastModifiedAt,
+    };
+  }
+
+  /**
+   * Validates that an entry has all required fields.
+   */
+  private _validateEntry(key: string, entry: unknown): void {
+    if (typeof entry !== "object" || entry === null) {
+      throw new CorruptIndexError(`Entry "${key}" is not an object`);
+    }
+
+    const obj = entry as Record<string, unknown>;
+    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}"`);
+      }
+    }
+  }
+}

package/src/core/mutex.ts

@@ -0,0 +1,134 @@
+/**
+ * Async mutex for serializing critical sections.
+ * Ensures only one operation runs at a time within a critical section.
+ */
+export class Mutex {
+  private readonly _queue: Array<() => void> = [];
+  private _locked = false;
+
+  /**
+   * Acquires the mutex lock.
+   * Returns a release function that must be called when done.
+   */
+  async acquire(): Promise<() => void> {
+    return new Promise<() => void>((resolve) => {
+      const tryAcquire = (): void => {
+        if (!this._locked) {
+          this._locked = true;
+          resolve(this._createRelease());
+        } else {
+          this._queue.push(tryAcquire);
+        }
+      };
+      tryAcquire();
+    });
+  }
+
+  /**
+   * Creates a release function for the current lock holder.
+   */
+  private _createRelease(): () => void {
+    let released = false;
+    return (): void => {
+      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(): boolean {
+    return this._locked;
+  }
+
+  /**
+   * Executes a function with the mutex held.
+   * Automatically releases the mutex when done.
+   */
+  async runExclusive<T>(fn: () => Promise<T> | T): Promise<T> {
+    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 {
+  private readonly _mutexes = new Map<string, Mutex>();
+  private readonly _refCounts = new Map<string, number>();
+
+  /**
+   * Acquires lock for a specific key.
+   * Returns a release function that must be called when done.
+   */
+  async acquire(key: string): Promise<() => void> {
+    // 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 (): void => {
+      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<T>(key: string, fn: () => Promise<T> | T): Promise<T> {
+    const release = await this.acquire(key);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Returns the number of active keys with pending operations.
+   */
+  get activeKeyCount(): number {
+    return this._mutexes.size;
+  }
+}

package/src/core/prune.ts

@@ -0,0 +1,145 @@
+import type { ICacheIndex, ICacheEntryMeta } from "./types";
+
+/**
+ * Options for pruning operations.
+ */
+export interface IPruneOptions {
+  readonly maxSizeBytes?: number;
+  readonly now?: number;
+}
+
+/**
+ * Identifies entries to remove based on TTL expiration.
+ * Returns entries that have expired (expiresAt < now).
+ */
+export function getExpiredEntries(
+  index: ICacheIndex,
+  now: number = Date.now()
+): ReadonlyArray<ICacheEntryMeta> {
+  const expired: ICacheEntryMeta[] = [];
+
+  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: ICacheIndex,
+  maxSizeBytes: number
+): ReadonlyArray<ICacheEntryMeta> {
+  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: ICacheEntryMeta[] = [];
+  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: ICacheIndex,
+  keysToRemove: ReadonlyArray<string>
+): ICacheIndex {
+  const keySet = new Set(keysToRemove);
+  const newEntries: Record<string, ICacheEntryMeta> = {};
+  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: ICacheIndex, entry: ICacheEntryMeta): ICacheIndex {
+  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: ICacheIndex,
+  key: string,
+  accessedAt: number = Date.now()
+): ICacheIndex {
+  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(): ICacheIndex {
+  return {
+    version: 1,
+    entries: {},
+    totalSizeBytes: 0,
+    lastModifiedAt: Date.now(),
+  };
+}

package/src/core/types.ts

@@ -0,0 +1,165 @@
+import type { IStorageAdapter, TAdapterPath } from "./adapter";
+
+// ─────────────────────────────────────────────────────────────────
+// Cache Configuration
+// ─────────────────────────────────────────────────────────────────
+
+export interface ICacheConfig {
+  /**
+   * Namespace for cache isolation. Creates separate storage area.
+   * @default "default"
+   */
+  readonly namespace?: string;
+
+  /**
+   * Custom storage adapter. If not provided, auto-selects based on platform.
+   */
+  readonly adapter?: IStorageAdapter;
+
+  /**
+   * Default TTL in milliseconds for new entries.
+   * @default undefined (no expiration)
+   */
+  readonly defaultTtlMs?: number;
+
+  /**
+   * Maximum cache size in bytes. Triggers LRU pruning when exceeded.
+   * @default undefined (no limit)
+   */
+  readonly maxSizeBytes?: number;
+
+  /**
+   * Whether to auto-prune expired entries on cache operations.
+   * @default true
+   */
+  readonly autoPruneExpired?: boolean;
+
+  /**
+   * Custom hash function for generating cache keys from input keys.
+   * @default SHA-256 hex
+   */
+  readonly hashFn?: (input: string) => string | Promise<string>;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Cache Entry
+// ─────────────────────────────────────────────────────────────────
+
+export interface ICacheEntryMeta {
+  /** User-provided unique key. */
+  readonly key: string;
+
+  /** Hash of the key (used for filename). */
+  readonly hash: string;
+
+  /** Original file extension (e.g., ".jpg"). */
+  readonly ext: string;
+
+  /** Size in bytes. */
+  readonly sizeBytes: number;
+
+  /** MIME content type if known. */
+  readonly contentType?: string;
+
+  /** Timestamp when entry was created (ms since epoch). */
+  readonly createdAt: number;
+
+  /** Timestamp when entry was last accessed (ms since epoch). */
+  readonly lastAccessedAt: number;
+
+  /** Expiration timestamp (ms since epoch). undefined = never expires. */
+  readonly expiresAt?: number;
+
+  /** Optional user-defined metadata. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface ICacheEntry extends ICacheEntryMeta {
+  /** Adapter-relative path to the cached file. */
+  readonly path: TAdapterPath;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Cache Index
+// ─────────────────────────────────────────────────────────────────
+
+export interface ICacheIndex {
+  readonly version: 1;
+  readonly entries: Readonly<Record<string, ICacheEntryMeta>>;
+  readonly totalSizeBytes: number;
+  readonly lastModifiedAt: number;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Put Operations
+// ─────────────────────────────────────────────────────────────────
+
+export interface IPutOptions {
+  /** TTL in milliseconds. Overrides defaultTtlMs. */
+  readonly ttlMs?: number;
+
+  /** File extension to use (e.g., ".jpg"). Auto-detected if omitted. */
+  readonly ext?: string;
+
+  /** Optional user-defined metadata. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+
+  /** Progress callback for download/write operations. */
+  readonly onProgress?: (percent: number) => void;
+
+  /** Additional headers for URL fetches. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+export type TPutStatus = "created" | "exists";
+
+export interface IPutResult {
+  readonly status: TPutStatus;
+  readonly entry: ICacheEntry;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Get/List Operations
+// ─────────────────────────────────────────────────────────────────
+
+export interface IGetResult {
+  readonly entry: ICacheEntry;
+  readonly uri: string;
+}
+
+export type TSortField = "createdAt" | "lastAccessedAt" | "sizeBytes" | "key";
+export type TSortOrder = "asc" | "desc";
+
+export interface IListOptions {
+  /** Sort field. @default "createdAt" */
+  readonly sortBy?: TSortField;
+
+  /** Sort order. @default "desc" */
+  readonly order?: TSortOrder;
+
+  /** Maximum entries to return. */
+  readonly limit?: number;
+
+  /** Number of entries to skip. */
+  readonly offset?: number;
+
+  /** Filter by metadata. */
+  readonly filter?: (entry: ICacheEntryMeta) => boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Prune/Stats Operations
+// ─────────────────────────────────────────────────────────────────
+
+export interface IPruneResult {
+  readonly removedCount: number;
+  readonly freedBytes: number;
+  readonly removedKeys: ReadonlyArray<string>;
+}
+
+export interface ICacheStats {
+  readonly entryCount: number;
+  readonly totalSizeBytes: number;
+  readonly oldestEntry?: ICacheEntryMeta;
+  readonly newestEntry?: ICacheEntryMeta;
+}