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

package/src/core/errors.ts

@@ -2,12 +2,13 @@ import type { TBinarySource } from "./adapter";
 
 /**
  * Base error class for cache operations.
+ * Supports ES2022 Error.cause for proper error chaining.
  */
 export abstract class CacheError extends Error {
   abstract readonly code: string;
 
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: { cause?: Error }) {
+    super(message, options);
     this.name = this.constructor.name;
     Object.setPrototypeOf(this, new.target.prototype);
   }
@@ -36,10 +37,11 @@ export class AdapterIOError extends CacheError {
   constructor(
     public readonly operation: string,
     public readonly path: string,
-    public readonly cause?: Error
+    cause?: Error
   ) {
     super(
-      `Adapter I/O error during "${operation}" at path "${path}": ${cause?.message ?? "unknown"}`
+      `Adapter I/O error during "${operation}" at path "${path}": ${cause?.message ?? "unknown"}`,
+      cause ? { cause } : undefined
     );
   }
 }
@@ -52,9 +54,9 @@ export class CorruptIndexError extends CacheError {
 
   constructor(
     public readonly reason: string,
-    public readonly cause?: Error
+    cause?: Error
   ) {
-    super(`Cache index is corrupt: ${reason}`);
+    super(`Cache index is corrupt: ${reason}`, cause ? { cause } : undefined);
   }
 }
 

package/src/core/hash.ts

@@ -8,11 +8,11 @@
  */
 function arrayBufferToHex(buffer: ArrayBuffer): string {
   const bytes = new Uint8Array(buffer);
-  let hex = "";
+  const hexParts: string[] = new Array<string>(bytes.length);
   for (let i = 0; i < bytes.length; i++) {
-    hex += bytes[i].toString(16).padStart(2, "0");
+    hexParts[i] = bytes[i].toString(16).padStart(2, "0");
   }
-  return hex;
+  return hexParts.join("");
 }
 
 /**

package/src/core/indexStore.ts

@@ -3,7 +3,42 @@ import type { ICacheIndex, ICacheEntryMeta } from "./types";
 import { CorruptIndexError, AdapterIOError } from "./errors";
 import { createEmptyIndex } from "./prune";
 
-const INDEX_VERSION = 1;
+/**
+ * Current index schema version.
+ * Increment when making breaking changes to ICacheIndex structure.
+ */
+const CURRENT_INDEX_VERSION = 1;
+
+/**
+ * Minimum supported version for migration.
+ * Versions below this will be rebuilt from scratch.
+ */
+const MIN_SUPPORTED_VERSION = 1;
+
+/**
+ * Migration function type.
+ * Takes an index at version N and returns an index at version N+1.
+ */
+type TIndexMigrator = (index: unknown) => unknown;
+
+/**
+ * Registry of migration functions.
+ * Key is the source version, value migrates to source version + 1.
+ *
+ * Example: When upgrading from v1 to v2, add:
+ * ```
+ * 1: (index) => {
+ *   // Transform v1 index to v2 format
+ *   return { ...index, version: 2, newField: defaultValue };
+ * }
+ * ```
+ */
+const INDEX_MIGRATIONS: Record<number, TIndexMigrator> = {
+  // No migrations yet - v1 is the initial version
+  // Future migrations will be added here:
+  // 1: (index) => migrateV1ToV2(index),
+  // 2: (index) => migrateV2ToV3(index),
+};
 
 /**
  * Manages persistence of the cache index via the storage adapter.
@@ -101,7 +136,7 @@ export class IndexStore {
     }
 
     const rebuiltIndex: ICacheIndex = {
-      version: INDEX_VERSION,
+      version: CURRENT_INDEX_VERSION,
       entries,
       totalSizeBytes,
       lastModifiedAt: Date.now(),
@@ -114,18 +149,71 @@ export class IndexStore {
   }
 
   /**
-   * Validates that the parsed object is a valid ICacheIndex.
+   * Applies migrations to upgrade an index from an older version to current.
+   * @param parsed - The parsed index object (may be any version)
+   * @returns The migrated index at current version
+   * @throws CorruptIndexError if version is unsupported or migration fails
    */
-  private _validateIndex(parsed: unknown): ICacheIndex {
+  private _migrateIndex(parsed: unknown): unknown {
     if (typeof parsed !== "object" || parsed === null) {
       throw new CorruptIndexError("Index is not an object");
     }
 
     const obj = parsed as Record<string, unknown>;
+    let version = obj.version;
+
+    // Validate version is a number
+    if (typeof version !== "number") {
+      throw new CorruptIndexError(`Invalid version type: ${typeof version}`);
+    }
+
+    // Check if version is too old to migrate
+    if (version < MIN_SUPPORTED_VERSION) {
+      throw new CorruptIndexError(
+        `Version ${version} is too old. Minimum supported: ${MIN_SUPPORTED_VERSION}`
+      );
+    }
+
+    // Check if version is from the future
+    if (version > CURRENT_INDEX_VERSION) {
+      throw new CorruptIndexError(
+        `Version ${version} is newer than current (${CURRENT_INDEX_VERSION}). ` +
+          `Please upgrade the package.`
+      );
+    }
+
+    // Apply migrations sequentially
+    let migrated: unknown = parsed;
+    while (version < CURRENT_INDEX_VERSION) {
+      const migrator = INDEX_MIGRATIONS[version];
+      if (!migrator) {
+        throw new CorruptIndexError(`No migration path from version ${version} to ${version + 1}`);
+      }
+      migrated = migrator(migrated);
+      version++;
+    }
+
+    return migrated;
+  }
+
+  /**
+   * Validates that the parsed object is a valid ICacheIndex.
+   */
+  private _validateIndex(parsed: unknown): ICacheIndex {
+    // First, migrate to current version if needed
+    const migrated = this._migrateIndex(parsed);
+
+    if (typeof migrated !== "object" || migrated === null) {
+      throw new CorruptIndexError("Index is not an object");
+    }
+
+    const obj = migrated as Record<string, unknown>;
 
-    // Check version
-    if (obj.version !== INDEX_VERSION) {
-      throw new CorruptIndexError(`Unsupported version: ${String(obj.version)}`);
+    // Verify version is current after migration
+    if (obj.version !== CURRENT_INDEX_VERSION) {
+      throw new CorruptIndexError(
+        `Migration failed: expected version ${CURRENT_INDEX_VERSION}, got ${String(obj.version)}`
+      );
     }
 
     // Check entries
@@ -150,7 +238,7 @@ export class IndexStore {
     }
 
     return {
-      version: INDEX_VERSION,
+      version: CURRENT_INDEX_VERSION,
       entries: entries as Record<string, ICacheEntryMeta>,
       totalSizeBytes: obj.totalSizeBytes,
       lastModifiedAt: obj.lastModifiedAt,
@@ -160,14 +248,14 @@ export class IndexStore {
   /**
    * Validates that an entry has all required fields.
    */
-  private _validateEntry(key: string, entry: unknown): void {
+  private _validateEntry(key: string, entry: unknown): asserts entry is ICacheEntryMeta {
     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"];
+    const requiredStrings = ["key", "hash", "ext"] as const;
+    const requiredNumbers = ["sizeBytes", "createdAt", "lastAccessedAt"] as const;
 
     for (const field of requiredStrings) {
       if (typeof obj[field] !== "string") {

package/src/core/prune.ts

@@ -1,11 +1,29 @@
 import type { ICacheIndex, ICacheEntryMeta } from "./types";
 
 /**
- * Options for pruning operations.
+ * Current index schema version.
+ * Keep in sync with indexStore.ts CURRENT_INDEX_VERSION.
  */
-export interface IPruneOptions {
-  readonly maxSizeBytes?: number;
-  readonly now?: number;
+const INDEX_VERSION = 1;
+
+/**
+ * Checks if a cache entry has expired.
+ * @param entry - The cache entry to check
+ * @param now - Current timestamp in milliseconds (defaults to Date.now())
+ * @returns true if the entry has expired, false otherwise
+ */
+export function isEntryExpired(entry: ICacheEntryMeta, now: number = Date.now()): boolean {
+  return entry.expiresAt !== undefined && entry.expiresAt < now;
+}
+
+/**
+ * Checks if a cache entry is valid (not expired).
+ * @param entry - The cache entry to check
+ * @param now - Current timestamp in milliseconds (defaults to Date.now())
+ * @returns true if the entry is valid, false if expired
+ */
+export function isEntryValid(entry: ICacheEntryMeta, now: number = Date.now()): boolean {
+  return entry.expiresAt === undefined || entry.expiresAt >= now;
 }
 
 /**
@@ -19,7 +37,7 @@ export function getExpiredEntries(
   const expired: ICacheEntryMeta[] = [];
 
   for (const entry of Object.values(index.entries)) {
-    if (entry.expiresAt !== undefined && entry.expiresAt < now) {
+    if (isEntryExpired(entry, now)) {
       expired.push(entry);
     }
   }
@@ -62,10 +80,14 @@ export function getLruPruneTargets(
 /**
  * Creates a new index with the specified entries removed.
  * Returns a new ICacheIndex without mutating the original.
+ * @param index - The source index
+ * @param keysToRemove - Keys to remove from the index
+ * @param now - Optional timestamp for lastModifiedAt (defaults to Date.now())
  */
 export function removeEntriesFromIndex(
   index: ICacheIndex,
-  keysToRemove: ReadonlyArray<string>
+  keysToRemove: ReadonlyArray<string>,
+  now: number = Date.now()
 ): ICacheIndex {
   const keySet = new Set(keysToRemove);
   const newEntries: Record<string, ICacheEntryMeta> = {};
@@ -79,29 +101,36 @@ export function removeEntriesFromIndex(
   }
 
   return {
-    version: 1,
+    version: INDEX_VERSION,
     entries: newEntries,
     totalSizeBytes: newTotalSize,
-    lastModifiedAt: Date.now(),
+    lastModifiedAt: now,
   };
 }
 
 /**
  * Adds or updates an entry in the index.
  * Returns a new ICacheIndex without mutating the original.
+ * @param index - The source index
+ * @param entry - The entry to add or update
+ * @param now - Optional timestamp for lastModifiedAt (defaults to Date.now())
  */
-export function addEntryToIndex(index: ICacheIndex, entry: ICacheEntryMeta): ICacheIndex {
+export function addEntryToIndex(
+  index: ICacheIndex,
+  entry: ICacheEntryMeta,
+  now: number = Date.now()
+): ICacheIndex {
   const existingEntry = index.entries[entry.key];
   const sizeDelta = entry.sizeBytes - (existingEntry?.sizeBytes ?? 0);
 
   return {
-    version: 1,
+    version: INDEX_VERSION,
     entries: {
       ...index.entries,
       [entry.key]: entry,
     },
     totalSizeBytes: index.totalSizeBytes + sizeDelta,
-    lastModifiedAt: Date.now(),
+    lastModifiedAt: now,
   };
 }
 
@@ -134,12 +163,13 @@ export function touchEntry(
 
 /**
  * Creates an empty cache index.
+ * @param now - Optional timestamp for lastModifiedAt (defaults to Date.now())
  */
-export function createEmptyIndex(): ICacheIndex {
+export function createEmptyIndex(now: number = Date.now()): ICacheIndex {
   return {
-    version: 1,
+    version: INDEX_VERSION,
     entries: {},
     totalSizeBytes: 0,
-    lastModifiedAt: Date.now(),
+    lastModifiedAt: now,
   };
 }

package/src/core/types.ts

@@ -1,5 +1,138 @@
 import type { IStorageAdapter, TAdapterPath } from "./adapter";
 
+// ─────────────────────────────────────────────────────────────────
+// Result Type (for internal use)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Represents a successful result.
+ */
+export interface IOk<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+/**
+ * Represents a failure result.
+ */
+export interface IErr<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+
+/**
+ * Discriminated union for operation results.
+ * Enables explicit error handling without exceptions.
+ *
+ * @example
+ * ```typescript
+ * function divide(a: number, b: number): TResult<number, string> {
+ *   if (b === 0) return { ok: false, error: "Division by zero" };
+ *   return { ok: true, value: a / b };
+ * }
+ *
+ * const result = divide(10, 2);
+ * if (result.ok) {
+ *   console.log(result.value); // 5
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+export type TResult<T, E = Error> = IOk<T> | IErr<E>;
+
+/**
+ * Helper to create a success result.
+ */
+export function ok<T>(value: T): IOk<T> {
+  return { ok: true, value };
+}
+
+/**
+ * Helper to create a failure result.
+ */
+export function err<E>(error: E): IErr<E> {
+  return { ok: false, error };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Cache Events (Observability)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Event emitted when a cache hit occurs.
+ */
+export interface ICacheHitEvent {
+  readonly type: "cache_hit";
+  readonly key: string;
+  readonly sizeBytes: number;
+  readonly ageMs: number;
+}
+
+/**
+ * Event emitted when a cache miss occurs.
+ */
+export interface ICacheMissEvent {
+  readonly type: "cache_miss";
+  readonly key: string;
+  readonly reason: "not_found" | "expired";
+}
+
+/**
+ * Event emitted when an entry is created.
+ */
+export interface ICacheWriteEvent {
+  readonly type: "cache_write";
+  readonly key: string;
+  readonly sizeBytes: number;
+  readonly source: "url" | "file" | "blob" | "bytes";
+  readonly durationMs: number;
+}
+
+/**
+ * Event emitted when an entry is removed.
+ */
+export interface ICacheRemoveEvent {
+  readonly type: "cache_remove";
+  readonly key: string;
+  readonly reason: "explicit" | "expired" | "lru";
+}
+
+/**
+ * Event emitted during pruning operations.
+ */
+export interface ICachePruneEvent {
+  readonly type: "cache_prune";
+  readonly reason: "expired" | "lru";
+  readonly removedCount: number;
+  readonly freedBytes: number;
+}
+
+/**
+ * Event emitted on errors (non-fatal).
+ */
+export interface ICacheErrorEvent {
+  readonly type: "cache_error";
+  readonly operation: string;
+  readonly error: Error;
+}
+
+/**
+ * Union of all cache events.
+ */
+export type TCacheEvent =
+  | ICacheHitEvent
+  | ICacheMissEvent
+  | ICacheWriteEvent
+  | ICacheRemoveEvent
+  | ICachePruneEvent
+  | ICacheErrorEvent;
+
+/**
+ * Callback for receiving cache events.
+ */
+export type TCacheEventHandler = (event: TCacheEvent) => void;
+
 // ─────────────────────────────────────────────────────────────────
 // Cache Configuration
 // ─────────────────────────────────────────────────────────────────
@@ -39,6 +172,29 @@ export interface ICacheConfig {
    * @default SHA-256 hex
    */
   readonly hashFn?: (input: string) => string | Promise<string>;
+
+  /**
+   * Event handler for observability/instrumentation.
+   * Called on cache hits, misses, writes, removes, and errors.
+   * @default undefined (no events emitted)
+   */
+  readonly onEvent?: TCacheEventHandler;
+
+  /**
+   * Custom time source function for testing.
+   * Returns current time in milliseconds since epoch.
+   * @default Date.now
+   */
+  readonly now?: () => number;
+
+  /**
+   * Debounce time for index writes in milliseconds.
+   * When > 0, index writes are batched and written after this delay.
+   * Use 0 for immediate writes (default behavior).
+   * Call flush() to force immediate persistence when using debounce.
+   * @default 0 (immediate writes)
+   */
+  readonly indexWriteDebounceMs?: number;
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -163,3 +319,41 @@ export interface ICacheStats {
   readonly oldestEntry?: ICacheEntryMeta;
   readonly newestEntry?: ICacheEntryMeta;
 }
+
+// ─────────────────────────────────────────────────────────────────
+// Read-Through Cache (getOrPut)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Fetcher result for getOrPut operations.
+ * Provides the data to cache along with optional configuration.
+ */
+export interface IFetcherResult {
+  /** The data to cache, as Uint8Array bytes. */
+  readonly bytes: Uint8Array;
+  /** Optional TTL override for this entry. */
+  readonly ttlMs?: number;
+  /** Optional file extension (e.g., ".json"). */
+  readonly ext?: string;
+  /** Optional user metadata. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Fetcher function type for getOrPut.
+ * Called when the key doesn't exist in cache.
+ * Should return the data to be cached, or throw to skip caching.
+ */
+export type TFetcher = (key: string) => Promise<IFetcherResult>;
+
+/**
+ * Result of a getOrPut operation.
+ */
+export interface IGetOrPutResult {
+  /** The cached entry. */
+  readonly entry: ICacheEntry;
+  /** The public URI for accessing the entry. */
+  readonly uri: string;
+  /** Whether the entry was fetched (true) or already cached (false). */
+  readonly fetched: boolean;
+}

package/src/index.ts

@@ -12,12 +12,15 @@ export type {
   IStorageAdapter,
   TAdapterPath,
   TBinarySource,
+  TBinarySourceType,
   IBinaryWriteResult,
   IBinaryWriteOptions,
   IFileStat,
   TProgressCallback,
 } from "./core/adapter";
 
+export { adapterSupportsSource } from "./core/adapter";
+
 export type {
   ICacheConfig,
   ICacheEntry,
@@ -26,14 +29,32 @@ export type {
   IPutOptions,
   IPutResult,
   IGetResult,
+  IGetOrPutResult,
+  TFetcher,
+  IFetcherResult,
   IListOptions,
   IPruneResult,
   ICacheStats,
   TPutStatus,
   TSortField,
   TSortOrder,
+  // Result type utilities
+  TResult,
+  IOk,
+  IErr,
+  // Event types for observability
+  TCacheEvent,
+  TCacheEventHandler,
+  ICacheHitEvent,
+  ICacheMissEvent,
+  ICacheWriteEvent,
+  ICacheRemoveEvent,
+  ICachePruneEvent,
+  ICacheErrorEvent,
 } from "./core/types";
 
+export { ok, err } from "./core/types";
+
 // ─────────────────────────────────────────────────────────────────
 // Errors
 // ─────────────────────────────────────────────────────────────────
@@ -80,3 +101,4 @@ export type { IMemoryAdapter } from "./adapters/memoryAdapter";
 
 export { hash, hashSync } from "./core/hash";
 export { Mutex, KeyedMutex } from "./core/mutex";
+export { isEntryExpired, isEntryValid } from "./core/prune";