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

package/lib/typescript/src/adapters/memoryAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memoryAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memoryAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AASzB;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,2CAA2C;IAC3C,MAAM,IAAI,IAAI,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAClD,0CAA0C;IAC1C,YAAY,IAAI,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,CA0QtE"}
+{"version":3,"file":"memoryAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memoryAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AASzB;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,2CAA2C;IAC3C,MAAM,IAAI,IAAI,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAClD,0CAA0C;IAC1C,YAAY,IAAI,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,CA6QtE"}

package/lib/typescript/src/adapters/rnfsAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rnfsAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/rnfsAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,eAAe,CA2OhF"}
+{"version":3,"file":"rnfsAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/rnfsAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,eAAe,CA4OhF"}

package/lib/typescript/src/adapters/webAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/webAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB;IACjB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAUD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,eAAe,CA+a9E;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,kDAAkD;IAClD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qCAAqC;IACrC,aAAa,IAAI,IAAI,CAAC;CACvB"}
+{"version":3,"file":"webAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/webAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB;IACjB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAUD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,eAAe,CAgb9E;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,kDAAkD;IAClD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qCAAqC;IACrC,aAAa,IAAI,IAAI,CAAC;CACvB"}

package/lib/typescript/src/core/adapter.d.ts

@@ -3,6 +3,10 @@
  * All paths are relative to the adapter's root.
  */
 export type TAdapterPath = string;
+/**
+ * Binary source type identifier.
+ */
+export type TBinarySourceType = TBinarySource["type"];
 /**
  * Discriminated union for binary content sources.
  * Adapters support the subset they can handle; throw UnsupportedSourceError otherwise.
@@ -56,6 +60,13 @@ export interface IStorageAdapter {
     readonly kind: string;
     /** A stable root identifier (e.g., absolute cache root on native, cache name on web). */
     readonly rootId: string;
+    /**
+     * Set of binary source types this adapter supports.
+     * Used for capability checking before attempting operations.
+     * If not provided, all source types are assumed to be potentially supported
+     * (with UnsupportedSourceError thrown at runtime for unsupported types).
+     */
+    readonly supportedSources?: ReadonlySet<TBinarySourceType>;
     /**
      * Ensures a directory exists at the given path, creating it recursively if needed.
      */
@@ -102,4 +113,9 @@ export interface IStorageAdapter {
      */
     getPublicUri(path: TAdapterPath): Promise<string>;
 }
+/**
+ * Checks if an adapter supports a given binary source type.
+ * Returns true if the adapter declares support or if no capability declaration exists.
+ */
+export declare function adapterSupportsSource(adapter: IStorageAdapter, sourceType: TBinarySourceType): boolean;
 //# sourceMappingURL=adapter.d.ts.map

package/lib/typescript/src/core/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/core/adapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAMxB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7C;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;IAMlE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhE;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtF;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAE7C;;;;OAIG;IACH,iBAAiB,CACf,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/core/adapter.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/core/cacheEngine.d.ts

@@ -1,5 +1,5 @@
 import type { IStorageAdapter } from "./adapter";
-import type { ICacheConfig, ICacheEntry, IPutOptions, IPutResult, IGetResult, IListOptions, IPruneResult, ICacheStats } from "./types";
+import type { ICacheConfig, ICacheEntry, IPutOptions, IPutResult, IGetResult, IGetOrPutResult, TFetcher, IListOptions, IPruneResult, ICacheStats } from "./types";
 /**
  * Main cache engine implementation.
  * Coordinates all cache operations through the storage adapter.
@@ -11,9 +11,58 @@ export declare class CacheEngine {
     private readonly _indexMutex;
     private readonly _keyMutex;
     private readonly _hashFn;
+    private readonly _now;
+    private readonly _debounceMs;
     private _index;
     private _initialized;
+    private _indexDirty;
+    private _debounceTimer;
     constructor(config: ICacheConfig, adapter: IStorageAdapter);
+    /**
+     * Returns whether the cache has been initialized.
+     * Use this to check initialization state without throwing.
+     */
+    get isInitialized(): boolean;
+    /**
+     * Returns the configured namespace.
+     */
+    get namespace(): string;
+    /**
+     * Returns the storage adapter.
+     */
+    get adapter(): IStorageAdapter;
+    /**
+     * Returns whether there are pending index writes.
+     * Useful for checking if flush() should be called before shutdown.
+     */
+    get hasPendingWrites(): boolean;
+    /**
+     * Schedules an index save, respecting debounce configuration.
+     * If debounceMs is 0, saves immediately.
+     */
+    private _scheduleIndexSave;
+    /**
+     * Internal flush implementation.
+     */
+    private _flushIndex;
+    /**
+     * Flushes any pending index writes immediately.
+     * Call this before app shutdown or when you need to ensure persistence.
+     */
+    flush(): Promise<void>;
+    /**
+     * 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.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Emits an event to the configured event handler (if any).
+     */
+    private _emit;
     /**
      * Initialize cache (ensure directories, load index).
      */
@@ -52,6 +101,67 @@ export declare class CacheEngine {
      * Get entry metadata without updating lastAccessedAt.
      */
     peek(key: string): Promise<ICacheEntry | null>;
+    /**
+     * 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.
+     */
+    getUri(key: string): Promise<string | null>;
+    /**
+     * 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.
+     */
+    touch(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    setTtl(key: string, ttlMs: number | undefined): Promise<boolean>;
+    /**
+     * 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
+     */
+    extendTtl(key: string, additionalMs: number): Promise<boolean>;
+    /**
+     * 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);
+     * ```
+     */
+    getOrPut(key: string, fetcher: TFetcher): Promise<IGetOrPutResult>;
+    /**
+     * Get all valid (non-expired) cache keys.
+     * More efficient than list() when you only need keys.
+     */
+    keys(): Promise<ReadonlyArray<string>>;
+    /**
+     * Get the count of valid (non-expired) entries.
+     * More efficient than list().length when you only need the count.
+     */
+    count(): Promise<number>;
     /**
      * List entries with sorting, filtering, pagination.
      */
@@ -91,8 +201,17 @@ export declare class CacheEngine {
         repaired: boolean;
         issues: string[];
     }>;
+    /**
+     * Throws if the engine has not been initialized.
+     */
     private _ensureInitialized;
+    /**
+     * Constructs a full cache entry with path from metadata.
+     */
     private _entryWithPath;
+    /**
+     * Extracts file extension from binary source if possible.
+     */
     private _extractExtension;
     private _autoPrune;
 }

package/lib/typescript/src/core/cacheEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cacheEngine.d.ts","sourceRoot":"","sources":["../../../../src/core/cacheEngine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,WAAW,CAAC;AAChE,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAEX,WAAW,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EAEZ,MAAM,SAAS,CAAC;AAgBjB;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CACT;IACf,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IAEtE,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe;IAW1D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB3B;;;OAGG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAStF;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ5F;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQtF;;OAEG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ9F;;OAEG;YACW,IAAI;IA+ElB;;;OAGG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA2BlD;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBxC;;OAEG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAqBpD;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;IA6CvE;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IA0CnC;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3C;;OAEG;YACW,YAAY;IAoB1B;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC;IAiB5C;;OAEG;IACG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgB3D;;OAEG;YACW,cAAc;IA8B5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAiD3E,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,iBAAiB;YA6CX,UAAU;CASzB"}
+{"version":3,"file":"cacheEngine.d.ts","sourceRoot":"","sources":["../../../../src/core/cacheEngine.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/core/errors.d.ts

@@ -1,10 +1,13 @@
 import type { TBinarySource } from "./adapter";
 /**
  * Base error class for cache operations.
+ * Supports ES2022 Error.cause for proper error chaining.
  */
 export declare abstract class CacheError extends Error {
     abstract readonly code: string;
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
 }
 /**
  * Thrown when an adapter receives a TBinarySource type it cannot handle.
@@ -21,18 +24,16 @@ export declare class UnsupportedSourceError extends CacheError {
 export declare class AdapterIOError extends CacheError {
     readonly operation: string;
     readonly path: string;
-    readonly cause?: Error | undefined;
     readonly code: "ADAPTER_IO_ERROR";
-    constructor(operation: string, path: string, cause?: Error | undefined);
+    constructor(operation: string, path: string, cause?: Error);
 }
 /**
  * Thrown when the cache index is corrupt and cannot be parsed.
  */
 export declare class CorruptIndexError extends CacheError {
     readonly reason: string;
-    readonly cause?: Error | undefined;
     readonly code: "CORRUPT_INDEX";
-    constructor(reason: string, cause?: Error | undefined);
+    constructor(reason: string, cause?: Error);
 }
 /**
  * Internal error when attempting to overwrite an immutable entry.

package/lib/typescript/src/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;GAEG;AACH,8BAAsB,UAAW,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEnB,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;aAIlC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC;aACjC,WAAW,EAAE,MAAM;IAJrC,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAG5B,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,EACjC,WAAW,EAAE,MAAM;CAItC;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,UAAU;aAI1B,SAAS,EAAE,MAAM;aACjB,IAAI,EAAE,MAAM;aACZ,KAAK,CAAC,EAAE,KAAK;IAL/B,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAU;gBAG1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,KAAK,YAAA;CAMhC;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;aAI7B,MAAM,EAAE,MAAM;aACd,KAAK,CAAC,EAAE,KAAK;IAJ/B,QAAQ,CAAC,IAAI,EAAG,eAAe,CAAU;gBAGvB,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,KAAK,YAAA;CAIhC;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;aAGxB,GAAG,EAAE,MAAM;IAFvC,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAElB,GAAG,EAAE,MAAM;CAGxC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;aAGpB,GAAG,EAAE,MAAM;IAFvC,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAEf,GAAG,EAAE,MAAM;CAGxC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;;GAGG;AACH,8BAAsB,UAAW,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEnB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAKzD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;aAIlC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC;aACjC,WAAW,EAAE,MAAM;IAJrC,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAG5B,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,EACjC,WAAW,EAAE,MAAM;CAItC;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,UAAU;aAI1B,SAAS,EAAE,MAAM;aACjB,IAAI,EAAE,MAAM;IAJ9B,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAU;gBAG1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EAC5B,KAAK,CAAC,EAAE,KAAK;CAOhB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;aAI7B,MAAM,EAAE,MAAM;IAHhC,QAAQ,CAAC,IAAI,EAAG,eAAe,CAAU;gBAGvB,MAAM,EAAE,MAAM,EAC9B,KAAK,CAAC,EAAE,KAAK;CAIhB;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;aAGxB,GAAG,EAAE,MAAM;IAFvC,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAElB,GAAG,EAAE,MAAM;CAGxC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;aAGpB,GAAG,EAAE,MAAM;IAFvC,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAEf,GAAG,EAAE,MAAM;CAGxC"}

package/lib/typescript/src/core/indexStore.d.ts

@@ -22,6 +22,13 @@ export declare class IndexStore {
      * Scans the entries directory and reconstructs metadata.
      */
     rebuild(entriesDir: TAdapterPath): Promise<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 _migrateIndex;
     /**
      * Validates that the parsed object is a valid ICacheIndex.
      */

package/lib/typescript/src/core/indexStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexStore.d.ts","sourceRoot":"","sources":["../../../../src/core/indexStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,SAAS,CAAC;AAM5D;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;gBAE9B,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY;IAK7D;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;IA0BlC;;OAEG;IACG,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAqD7D;;OAEG;IACH,OAAO,CAAC,cAAc;IAyCtB;;OAEG;IACH,OAAO,CAAC,cAAc;CAqBvB"}
+{"version":3,"file":"indexStore.d.ts","sourceRoot":"","sources":["../../../../src/core/indexStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,SAAS,CAAC;AAyC5D;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;gBAE9B,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY;IAK7D;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;IA0BlC;;OAEG;IACG,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAqD7D;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA0CrB;;OAEG;IACH,OAAO,CAAC,cAAc;IA8CtB;;OAEG;IACH,OAAO,CAAC,cAAc;CAqBvB"}

package/lib/typescript/src/core/prune.d.ts

@@ -1,11 +1,18 @@
 import type { ICacheIndex, ICacheEntryMeta } from "./types";
 /**
- * Options for pruning operations.
+ * 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 interface IPruneOptions {
-    readonly maxSizeBytes?: number;
-    readonly now?: number;
-}
+export declare function isEntryExpired(entry: ICacheEntryMeta, now?: number): boolean;
+/**
+ * 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 declare function isEntryValid(entry: ICacheEntryMeta, now?: number): boolean;
 /**
  * Identifies entries to remove based on TTL expiration.
  * Returns entries that have expired (expiresAt < now).
@@ -20,13 +27,19 @@ export declare function getLruPruneTargets(index: ICacheIndex, maxSizeBytes: num
 /**
  * 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 declare function removeEntriesFromIndex(index: ICacheIndex, keysToRemove: ReadonlyArray<string>): ICacheIndex;
+export declare function removeEntriesFromIndex(index: ICacheIndex, keysToRemove: ReadonlyArray<string>, now?: number): ICacheIndex;
 /**
  * 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 declare function addEntryToIndex(index: ICacheIndex, entry: ICacheEntryMeta): ICacheIndex;
+export declare function addEntryToIndex(index: ICacheIndex, entry: ICacheEntryMeta, now?: number): ICacheIndex;
 /**
  * Updates the lastAccessedAt timestamp for an entry.
  * Returns a new ICacheIndex without mutating the original.
@@ -34,6 +47,7 @@ export declare function addEntryToIndex(index: ICacheIndex, entry: ICacheEntryMe
 export declare function touchEntry(index: ICacheIndex, key: string, accessedAt?: number): ICacheIndex;
 /**
  * Creates an empty cache index.
+ * @param now - Optional timestamp for lastModifiedAt (defaults to Date.now())
  */
-export declare function createEmptyIndex(): ICacheIndex;
+export declare function createEmptyIndex(now?: number): ICacheIndex;
 //# sourceMappingURL=prune.d.ts.map

package/lib/typescript/src/core/prune.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../../../src/core/prune.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,GAAG,GAAE,MAAmB,GACvB,aAAa,CAAC,eAAe,CAAC,CAUhC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,GACnB,aAAa,CAAC,eAAe,CAAC,CAsBhC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,GAClC,WAAW,CAkBb;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG,WAAW,CAavF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAmB,GAC9B,WAAW,CAiBb;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAO9C"}
+{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../../../src/core/prune.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAQ5D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAExF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAEtF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,GAAG,GAAE,MAAmB,GACvB,aAAa,CAAC,eAAe,CAAC,CAUhC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,GACnB,aAAa,CAAC,eAAe,CAAC,CAsBhC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,EACnC,GAAG,GAAE,MAAmB,GACvB,WAAW,CAkBb;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,eAAe,EACtB,GAAG,GAAE,MAAmB,GACvB,WAAW,CAab;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAmB,GAC9B,WAAW,CAiBb;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAmB,GAAG,WAAW,CAOtE"}

package/lib/typescript/src/core/types.d.ts

@@ -1,4 +1,106 @@
 import type { IStorageAdapter, TAdapterPath } from "./adapter";
+/**
+ * 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 declare function ok<T>(value: T): IOk<T>;
+/**
+ * Helper to create a failure result.
+ */
+export declare function err<E>(error: E): IErr<E>;
+/**
+ * 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;
 export interface ICacheConfig {
     /**
      * Namespace for cache isolation. Creates separate storage area.
@@ -29,6 +131,26 @@ 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;
 }
 export interface ICacheEntryMeta {
     /** User-provided unique key. */
@@ -106,4 +228,35 @@ export interface ICacheStats {
     readonly oldestEntry?: ICacheEntryMeta;
     readonly newestEntry?: ICacheEntryMeta;
 }
+/**
+ * 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;
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/index.d.ts

@@ -3,8 +3,10 @@
  *
  * Cross-platform immutable file cache with pluggable storage adapters.
  */
-export type { IStorageAdapter, TAdapterPath, TBinarySource, IBinaryWriteResult, IBinaryWriteOptions, IFileStat, TProgressCallback, } from "./core/adapter";
-export type { ICacheConfig, ICacheEntry, ICacheEntryMeta, ICacheIndex, IPutOptions, IPutResult, IGetResult, IListOptions, IPruneResult, ICacheStats, TPutStatus, TSortField, TSortOrder, } from "./core/types";
+export type { IStorageAdapter, TAdapterPath, TBinarySource, TBinarySourceType, IBinaryWriteResult, IBinaryWriteOptions, IFileStat, TProgressCallback, } from "./core/adapter";
+export { adapterSupportsSource } from "./core/adapter";
+export type { ICacheConfig, ICacheEntry, ICacheEntryMeta, ICacheIndex, IPutOptions, IPutResult, IGetResult, IGetOrPutResult, TFetcher, IFetcherResult, IListOptions, IPruneResult, ICacheStats, TPutStatus, TSortField, TSortOrder, TResult, IOk, IErr, TCacheEvent, TCacheEventHandler, ICacheHitEvent, ICacheMissEvent, ICacheWriteEvent, ICacheRemoveEvent, ICachePruneEvent, ICacheErrorEvent, } from "./core/types";
+export { ok, err } from "./core/types";
 export { CacheError, UnsupportedSourceError, AdapterIOError, CorruptIndexError, ImmutableConflictError, EntryNotFoundError, } from "./core/errors";
 export { CacheEngine } from "./core/cacheEngine";
 export { createImmutableFileCache, createCacheEngineSync } from "./factory";
@@ -17,4 +19,5 @@ export { createMemoryAdapter } from "./adapters/memoryAdapter";
 export type { IMemoryAdapter } from "./adapters/memoryAdapter";
 export { hash, hashSync } from "./core/hash";
 export { Mutex, KeyedMutex } from "./core/mutex";
+export { isEntryExpired, isEntryValid } from "./core/prune";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,YAAY,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,SAAS,EACT,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,WAAW,EACX,WAAW,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,GACX,MAAM,cAAc,CAAC;AAMtB,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE5E,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAMrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM/D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,YAAY,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,SAAS,EACT,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,WAAW,EACX,WAAW,EACX,UAAU,EACV,UAAU,EACV,eAAe,EACf,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EAEV,OAAO,EACP,GAAG,EACH,IAAI,EAEJ,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAMvC,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE5E,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAMrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM/D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynlabs/react-native-immutable-file-cache",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "description": "Cross-platform immutable file cache with pluggable storage adapters for React Native and Web",
   "author": "dienp",
   "license": "MIT",

package/src/adapters/memoryAdapter.ts

@@ -67,6 +67,9 @@ export function createMemoryAdapter(namespace?: string): IMemoryAdapter {
   const adapter: IMemoryAdapter = {
     kind: "memory",
     rootId,
+    supportedSources: new Set(["url", "file", "blob", "bytes"]) as ReadonlySet<
+      TBinarySource["type"]
+    >,
 
     // ─────────────────────────────────────────────────────────────────
     // Directory Management

package/src/adapters/rnfsAdapter.ts

@@ -56,6 +56,7 @@ export function createRnfsAdapter(options?: IRnfsAdapterOptions): IStorageAdapte
   const adapter: IStorageAdapter = {
     kind: "native-fs",
     rootId: rootPath,
+    supportedSources: new Set(["url", "file", "bytes"]) as ReadonlySet<TBinarySource["type"]>,
 
     // ─────────────────────────────────────────────────────────────────
     // Directory Management
@@ -273,11 +274,17 @@ export function createRnfsAdapter(options?: IRnfsAdapterOptions): IStorageAdapte
 
 /**
  * Converts Uint8Array to base64 string.
+ * Uses chunked approach for better performance with large arrays.
  */
 function uint8ArrayToBase64(bytes: Uint8Array): string {
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
+  // Process in chunks to avoid call stack issues with large arrays
+  const CHUNK_SIZE = 0x8000; // 32KB chunks
+  const chunks: string[] = [];
+
+  for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+    const chunk = bytes.subarray(i, i + CHUNK_SIZE);
+    chunks.push(String.fromCharCode.apply(null, chunk as unknown as number[]));
   }
-  return btoa(binary);
+
+  return btoa(chunks.join(""));
 }

package/src/adapters/webAdapter.ts

@@ -180,6 +180,7 @@ export function createWebAdapter(options?: IWebAdapterOptions): IStorageAdapter
   const adapter: IStorageAdapter = {
     kind: "web",
     rootId,
+    supportedSources: new Set(["url", "blob", "bytes"]) as ReadonlySet<TBinarySource["type"]>,
 
     // ─────────────────────────────────────────────────────────────────
     // Directory Management