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

package/lib/module/index.js

@@ -0,0 +1,41 @@
+/**
+ * @dynlabs/react-native-immutable-file-cache
+ *
+ * Cross-platform immutable file cache with pluggable storage adapters.
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Core Types
+// ─────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────
+// Errors
+// ─────────────────────────────────────────────────────────────────
+
+export { CacheError, UnsupportedSourceError, AdapterIOError, CorruptIndexError, ImmutableConflictError, EntryNotFoundError } from "./core/errors";
+
+// ─────────────────────────────────────────────────────────────────
+// Core Engine
+// ─────────────────────────────────────────────────────────────────
+
+export { CacheEngine } from "./core/cacheEngine";
+
+// ─────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────
+
+export { createImmutableFileCache, createCacheEngineSync } from "./factory";
+// ─────────────────────────────────────────────────────────────────
+// Adapters
+// ─────────────────────────────────────────────────────────────────
+
+export { createRnfsAdapter } from "./adapters/rnfsAdapter";
+export { createWebAdapter } from "./adapters/webAdapter";
+export { createMemoryAdapter } from "./adapters/memoryAdapter";
+// ─────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────
+
+export { hash, hashSync } from "./core/hash";
+export { Mutex, KeyedMutex } from "./core/mutex";
+//# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CacheError","UnsupportedSourceError","AdapterIOError","CorruptIndexError","ImmutableConflictError","EntryNotFoundError","CacheEngine","createImmutableFileCache","createCacheEngineSync","createRnfsAdapter","createWebAdapter","createMemoryAdapter","hash","hashSync","Mutex","KeyedMutex"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"AAAA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;;AA4BA;AACA;AACA;;AAEA,SACEA,UAAU,EACVC,sBAAsB,EACtBC,cAAc,EACdC,iBAAiB,EACjBC,sBAAsB,EACtBC,kBAAkB,QACb,eAAe;;AAEtB;AACA;AACA;;AAEA,SAASC,WAAW,QAAQ,oBAAoB;;AAEhD;AACA;AACA;;AAEA,SAASC,wBAAwB,EAAEC,qBAAqB,QAAQ,WAAW;AAI3E;AACA;AACA;;AAEA,SAASC,iBAAiB,QAAQ,wBAAwB;AAG1D,SAASC,gBAAgB,QAAQ,uBAAuB;AAGxD,SAASC,mBAAmB,QAAQ,0BAA0B;AAG9D;AACA;AACA;;AAEA,SAASC,IAAI,EAAEC,QAAQ,QAAQ,aAAa;AAC5C,SAASC,KAAK,EAAEC,UAAU,QAAQ,cAAc","ignoreList":[]}

package/lib/module/index.native.js

@@ -0,0 +1,54 @@
+/**
+ * @dynlabs/react-native-immutable-file-cache - Native entrypoint
+ * Auto-selects RNFS adapter for React Native (iOS/Android).
+ */
+
+// Re-export everything from main index
+export * from "./index";
+import { createRnfsAdapter } from "./adapters/rnfsAdapter";
+import { CacheEngine } from "./core/cacheEngine";
+
+/**
+ * Creates an immutable file cache instance for React Native.
+ * Automatically uses the RNFS adapter.
+ *
+ * @param options - Cache configuration options
+ * @returns Initialized CacheEngine instance
+ *
+ * @example
+ * ```typescript
+ * import { createImmutableFileCache } from "@dynlabs/react-native-immutable-file-cache";
+ *
+ * const cache = await createImmutableFileCache({
+ *   namespace: "images",
+ *   defaultTtlMs: 7 * 24 * 60 * 60 * 1000,
+ * });
+ *
+ * // Cache an image
+ * const result = await cache.putFromUrl("avatar", "https://example.com/avatar.jpg");
+ *
+ * // Get cached image URI
+ * const entry = await cache.get("avatar");
+ * if (entry) {
+ *   console.log("Image URI:", entry.uri);
+ * }
+ * ```
+ */
+export async function createImmutableFileCache(options) {
+  const {
+    autoInit = true,
+    adapter,
+    ...config
+  } = options ?? {};
+
+  // Use provided adapter or create RNFS adapter
+  const resolvedAdapter = adapter ?? createRnfsAdapter({
+    namespace: config.namespace
+  });
+  const engine = new CacheEngine(config, resolvedAdapter);
+  if (autoInit) {
+    await engine.init();
+  }
+  return engine;
+}
+//# sourceMappingURL=index.native.js.map

package/lib/module/index.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createRnfsAdapter","CacheEngine","createImmutableFileCache","options","autoInit","adapter","config","resolvedAdapter","namespace","engine","init"],"sourceRoot":"../../src","sources":["index.native.ts"],"mappings":"AAAA;AACA;AACA;AACA;;AAEA;AACA,cAAc,SAAS;AAEvB,SAASA,iBAAiB,QAAQ,wBAAwB;AAE1D,SAASC,WAAW,QAAQ,oBAAoB;;AAEhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeC,wBAAwBA,CAC5CC,OAA6F,EACvE;EACtB,MAAM;IAAEC,QAAQ,GAAG,IAAI;IAAEC,OAAO;IAAE,GAAGC;EAAO,CAAC,GAAGH,OAAO,IAAI,CAAC,CAAC;;EAE7D;EACA,MAAMI,eAAe,GACnBF,OAAO,IACPL,iBAAiB,CAAC;IAChBQ,SAAS,EAAEF,MAAM,CAACE;EACpB,CAAC,CAAC;EAEJ,MAAMC,MAAM,GAAG,IAAIR,WAAW,CAACK,MAAM,EAAEC,eAAe,CAAC;EAEvD,IAAIH,QAAQ,EAAE;IACZ,MAAMK,MAAM,CAACC,IAAI,CAAC,CAAC;EACrB;EAEA,OAAOD,MAAM;AACf","ignoreList":[]}

package/lib/module/index.web.js

@@ -0,0 +1,55 @@
+/**
+ * @dynlabs/react-native-immutable-file-cache - Web entrypoint
+ * Auto-selects Web adapter for browser environments.
+ */
+
+// Re-export everything from main index
+export * from "./index";
+import { createWebAdapter } from "./adapters/webAdapter";
+import { CacheEngine } from "./core/cacheEngine";
+
+/**
+ * Creates an immutable file cache instance for web browsers.
+ * Automatically uses the Web adapter (Cache Storage + IndexedDB).
+ *
+ * @param options - Cache configuration options
+ * @returns Initialized CacheEngine instance
+ *
+ * @example
+ * ```typescript
+ * import { createImmutableFileCache } from "@dynlabs/react-native-immutable-file-cache/web";
+ *
+ * const cache = await createImmutableFileCache({
+ *   namespace: "images",
+ *   defaultTtlMs: 7 * 24 * 60 * 60 * 1000,
+ * });
+ *
+ * // Cache an image
+ * const result = await cache.putFromUrl("avatar", "https://example.com/avatar.jpg");
+ *
+ * // Get cached image URI (blob: URL)
+ * const entry = await cache.get("avatar");
+ * if (entry) {
+ *   // Use entry.uri as image source
+ *   // Remember to revoke blob URL when done to free memory
+ * }
+ * ```
+ */
+export async function createImmutableFileCache(options) {
+  const {
+    autoInit = true,
+    adapter,
+    ...config
+  } = options ?? {};
+
+  // Use provided adapter or create Web adapter
+  const resolvedAdapter = adapter ?? createWebAdapter({
+    namespace: config.namespace
+  });
+  const engine = new CacheEngine(config, resolvedAdapter);
+  if (autoInit) {
+    await engine.init();
+  }
+  return engine;
+}
+//# sourceMappingURL=index.web.js.map

package/lib/module/index.web.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createWebAdapter","CacheEngine","createImmutableFileCache","options","autoInit","adapter","config","resolvedAdapter","namespace","engine","init"],"sourceRoot":"../../src","sources":["index.web.ts"],"mappings":"AAAA;AACA;AACA;AACA;;AAEA;AACA,cAAc,SAAS;AAEvB,SAASA,gBAAgB,QAAQ,uBAAuB;AAExD,SAASC,WAAW,QAAQ,oBAAoB;;AAEhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeC,wBAAwBA,CAC5CC,OAA6F,EACvE;EACtB,MAAM;IAAEC,QAAQ,GAAG,IAAI;IAAEC,OAAO;IAAE,GAAGC;EAAO,CAAC,GAAGH,OAAO,IAAI,CAAC,CAAC;;EAE7D;EACA,MAAMI,eAAe,GACnBF,OAAO,IACPL,gBAAgB,CAAC;IACfQ,SAAS,EAAEF,MAAM,CAACE;EACpB,CAAC,CAAC;EAEJ,MAAMC,MAAM,GAAG,IAAIR,WAAW,CAACK,MAAM,EAAEC,eAAe,CAAC;EAEvD,IAAIH,QAAQ,EAAE;IACZ,MAAMK,MAAM,CAACC,IAAI,CAAC,CAAC;EACrB;EAEA,OAAOD,MAAM;AACf","ignoreList":[]}

package/lib/module/types/react-native-fs.d.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=react-native-fs.d.js.map

package/lib/module/types/react-native-fs.d.js.map

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

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

@@ -0,0 +1,23 @@
+/**
+ * In-Memory Storage Adapter
+ *
+ * For testing purposes only.
+ * Implements IStorageAdapter using in-memory storage.
+ */
+import type { IStorageAdapter } from "../core/adapter";
+/**
+ * Extended interface for memory adapter with test utilities.
+ */
+export interface IMemoryAdapter extends IStorageAdapter {
+    /** Resets all stored data. For testing. */
+    _reset(): void;
+    /** Gets raw content for assertions. For testing. */
+    _getContent(path: string): Uint8Array | undefined;
+    /** Gets all stored paths. For testing. */
+    _getAllPaths(): string[];
+}
+/**
+ * Creates an in-memory storage adapter for testing.
+ */
+export declare function createMemoryAdapter(namespace?: string): IMemoryAdapter;
+//# sourceMappingURL=memoryAdapter.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,18 @@
+/**
+ * React Native FS Adapter
+ *
+ * This is the ONLY file that imports react-native-fs.
+ * Implements IStorageAdapter using RNFS APIs.
+ */
+import type { IStorageAdapter } from "../core/adapter";
+export interface IRnfsAdapterOptions {
+    /** Base directory. @default RNFS.CachesDirectoryPath */
+    readonly baseDir?: string;
+    /** Namespace subdirectory. */
+    readonly namespace?: string;
+}
+/**
+ * Creates a storage adapter backed by react-native-fs.
+ */
+export declare function createRnfsAdapter(options?: IRnfsAdapterOptions): IStorageAdapter;
+//# sourceMappingURL=rnfsAdapter.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,30 @@
+/**
+ * Web Storage Adapter
+ *
+ * Implements IStorageAdapter using:
+ * - Cache Storage API for binary file storage
+ * - IndexedDB for metadata and index storage
+ */
+import type { IStorageAdapter } from "../core/adapter";
+export interface IWebAdapterOptions {
+    /** Cache name for Cache Storage. @default "immutable-file-cache" */
+    readonly cacheName?: string;
+    /** IDB database name. @default "immutable-file-cache-meta" */
+    readonly idbName?: string;
+    /** Namespace. */
+    readonly namespace?: string;
+}
+/**
+ * Creates a storage adapter for web platforms using Cache Storage and IndexedDB.
+ */
+export declare function createWebAdapter(options?: IWebAdapterOptions): IStorageAdapter;
+/**
+ * Extended interface for web adapter with cleanup methods.
+ */
+export interface IWebAdapterWithCleanup extends IStorageAdapter {
+    /** Revokes a specific blob URL to free memory. */
+    revokeUri(uri: string): void;
+    /** Revokes all created blob URLs. */
+    revokeAllUris(): void;
+}
+//# sourceMappingURL=webAdapter.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,105 @@
+/**
+ * Adapter-relative path. Core never constructs absolute OS paths.
+ * All paths are relative to the adapter's root.
+ */
+export type TAdapterPath = string;
+/**
+ * Discriminated union for binary content sources.
+ * Adapters support the subset they can handle; throw UnsupportedSourceError otherwise.
+ */
+export type TBinarySource = {
+    readonly type: "url";
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+} | {
+    readonly type: "file";
+    readonly filePath: string;
+} | {
+    readonly type: "blob";
+    readonly blob: Blob;
+} | {
+    readonly type: "bytes";
+    readonly bytes: Uint8Array;
+};
+/**
+ * Result of a binary write operation.
+ */
+export interface IBinaryWriteResult {
+    readonly sizeBytes: number;
+    readonly contentType?: string;
+}
+/**
+ * File/entry stat information.
+ */
+export interface IFileStat {
+    readonly sizeBytes: number;
+    readonly mtimeMs: number;
+}
+/**
+ * Progress callback for binary operations.
+ */
+export type TProgressCallback = (percent: number) => void;
+/**
+ * Options for binary write operations.
+ */
+export interface IBinaryWriteOptions {
+    readonly onProgress?: TProgressCallback;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Storage adapter interface.
+ * Represents a key-addressed "filesystem-like" store with atomic write support.
+ * All paths are adapter-relative. Core never constructs absolute OS paths.
+ */
+export interface IStorageAdapter {
+    /** Adapter kind identifier. */
+    readonly kind: string;
+    /** A stable root identifier (e.g., absolute cache root on native, cache name on web). */
+    readonly rootId: string;
+    /**
+     * Ensures a directory exists at the given path, creating it recursively if needed.
+     */
+    ensureDir(path: TAdapterPath): Promise<void>;
+    /**
+     * Checks if a file or directory exists at the given path.
+     */
+    exists(path: TAdapterPath): Promise<boolean>;
+    /**
+     * Removes a file at the given path. No-op if file doesn't exist.
+     */
+    remove(path: TAdapterPath): Promise<void>;
+    /**
+     * Removes a directory and all its contents recursively.
+     */
+    removeDir(path: TAdapterPath): Promise<void>;
+    /**
+     * Lists all entries (files/directories) in a directory.
+     * Returns relative paths from the listed directory.
+     */
+    listDir(path: TAdapterPath): Promise<ReadonlyArray<TAdapterPath>>;
+    /**
+     * Reads text content from a file.
+     */
+    readText(path: TAdapterPath, encoding: "utf8"): Promise<string>;
+    /**
+     * Writes text content atomically (write to temp, then rename).
+     */
+    writeTextAtomic(path: TAdapterPath, content: string, encoding: "utf8"): Promise<void>;
+    /**
+     * Gets file statistics.
+     */
+    stat(path: TAdapterPath): Promise<IFileStat>;
+    /**
+     * Writes binary content atomically.
+     * Source may be URL, blob, file path, or raw bytes depending on adapter.
+     * Adapter must throw UnsupportedSourceError for unsupported source types.
+     */
+    writeBinaryAtomic(path: TAdapterPath, source: TBinarySource, options?: IBinaryWriteOptions): Promise<IBinaryWriteResult>;
+    /**
+     * Returns a URI that the app can use to read/view the stored file.
+     * - Native: file:// URI
+     * - Web: blob: URL (caller responsible for revoking)
+     */
+    getPublicUri(path: TAdapterPath): Promise<string>;
+}
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,99 @@
+import type { IStorageAdapter } from "./adapter";
+import type { ICacheConfig, ICacheEntry, IPutOptions, IPutResult, IGetResult, IListOptions, IPruneResult, ICacheStats } from "./types";
+/**
+ * Main cache engine implementation.
+ * Coordinates all cache operations through the storage adapter.
+ */
+export declare class CacheEngine {
+    private readonly _config;
+    private readonly _adapter;
+    private readonly _indexStore;
+    private readonly _indexMutex;
+    private readonly _keyMutex;
+    private readonly _hashFn;
+    private _index;
+    private _initialized;
+    constructor(config: ICacheConfig, adapter: IStorageAdapter);
+    /**
+     * Initialize cache (ensure directories, load index).
+     */
+    init(): Promise<void>;
+    /**
+     * Store content from URL.
+     * Returns {status: "exists"} if key already exists.
+     */
+    putFromUrl(key: string, url: string, options?: IPutOptions): Promise<IPutResult>;
+    /**
+     * Store content from local file path (native only).
+     */
+    putFromFile(key: string, filePath: string, options?: IPutOptions): Promise<IPutResult>;
+    /**
+     * Store content from Blob (web only).
+     */
+    putFromBlob(key: string, blob: Blob, options?: IPutOptions): Promise<IPutResult>;
+    /**
+     * Store content from raw bytes.
+     */
+    putFromBytes(key: string, bytes: Uint8Array, options?: IPutOptions): Promise<IPutResult>;
+    /**
+     * Internal put implementation.
+     */
+    private _put;
+    /**
+     * Get entry by key. Returns null if not found or expired.
+     * Updates lastAccessedAt.
+     */
+    get(key: string): Promise<IGetResult | null>;
+    /**
+     * Check if key exists and is not expired.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get entry metadata without updating lastAccessedAt.
+     */
+    peek(key: string): Promise<ICacheEntry | null>;
+    /**
+     * List entries with sorting, filtering, pagination.
+     */
+    list(options?: IListOptions): Promise<ReadonlyArray<ICacheEntry>>;
+    /**
+     * Get cache statistics.
+     */
+    stats(): Promise<ICacheStats>;
+    /**
+     * Remove specific entry by key.
+     */
+    remove(key: string): Promise<boolean>;
+    /**
+     * Internal remove implementation (must be called within keyed mutex).
+     */
+    private _removeEntry;
+    /**
+     * Remove all expired entries.
+     */
+    removeExpired(): Promise<IPruneResult>;
+    /**
+     * Prune to fit within size limit using LRU.
+     */
+    pruneLru(maxSizeBytes: number): Promise<IPruneResult>;
+    /**
+     * Remove multiple entries.
+     */
+    private _removeEntries;
+    /**
+     * Clear all entries.
+     */
+    clear(): Promise<void>;
+    /**
+     * Validate index against filesystem and rebuild if needed.
+     */
+    validateAndRepair(): Promise<{
+        repaired: boolean;
+        issues: string[];
+    }>;
+    private _ensureInitialized;
+    private _entryWithPath;
+    private _extractExtension;
+    private _autoPrune;
+}
+//# sourceMappingURL=cacheEngine.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,54 @@
+import type { TBinarySource } from "./adapter";
+/**
+ * Base error class for cache operations.
+ */
+export declare abstract class CacheError extends Error {
+    abstract readonly code: string;
+    constructor(message: string);
+}
+/**
+ * Thrown when an adapter receives a TBinarySource type it cannot handle.
+ */
+export declare class UnsupportedSourceError extends CacheError {
+    readonly sourceType: TBinarySource["type"];
+    readonly adapterKind: string;
+    readonly code: "UNSUPPORTED_SOURCE";
+    constructor(sourceType: TBinarySource["type"], adapterKind: string);
+}
+/**
+ * Thrown when an adapter I/O operation fails.
+ */
+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);
+}
+/**
+ * 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);
+}
+/**
+ * Internal error when attempting to overwrite an immutable entry.
+ * Public API converts this to {status: "exists"} response.
+ */
+export declare class ImmutableConflictError extends CacheError {
+    readonly key: string;
+    readonly code: "IMMUTABLE_CONFLICT";
+    constructor(key: string);
+}
+/**
+ * Thrown when a required entry is not found.
+ */
+export declare class EntryNotFoundError extends CacheError {
+    readonly key: string;
+    readonly code: "ENTRY_NOT_FOUND";
+    constructor(key: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,20 @@
+/**
+ * Cross-platform SHA-256 hashing utility.
+ * Uses SubtleCrypto on web and native platforms that support it.
+ */
+/**
+ * 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 declare function hash(input: string): Promise<string>;
+/**
+ * Synchronous hash for cases where async is not possible.
+ * Uses fallback algorithm - prefer async hash() when possible.
+ */
+export declare function hashSync(input: string): string;
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../../src/core/hash.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsBH;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYzD;AAyBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C"}

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

@@ -0,0 +1,34 @@
+import type { IStorageAdapter, TAdapterPath } from "./adapter";
+import type { ICacheIndex } from "./types";
+/**
+ * Manages persistence of the cache index via the storage adapter.
+ */
+export declare class IndexStore {
+    private readonly _adapter;
+    private readonly _indexPath;
+    constructor(adapter: IStorageAdapter, indexPath: TAdapterPath);
+    /**
+     * Load index from storage.
+     * Returns empty index if file doesn't exist.
+     * Throws CorruptIndexError if index is malformed.
+     */
+    load(): Promise<ICacheIndex>;
+    /**
+     * Save index atomically via the adapter.
+     */
+    save(index: ICacheIndex): Promise<void>;
+    /**
+     * Validate and rebuild index from filesystem if corrupt.
+     * Scans the entries directory and reconstructs metadata.
+     */
+    rebuild(entriesDir: TAdapterPath): Promise<ICacheIndex>;
+    /**
+     * Validates that the parsed object is a valid ICacheIndex.
+     */
+    private _validateIndex;
+    /**
+     * Validates that an entry has all required fields.
+     */
+    private _validateEntry;
+}
+//# sourceMappingURL=indexStore.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,49 @@
+/**
+ * Async mutex for serializing critical sections.
+ * Ensures only one operation runs at a time within a critical section.
+ */
+export declare class Mutex {
+    private readonly _queue;
+    private _locked;
+    /**
+     * Acquires the mutex lock.
+     * Returns a release function that must be called when done.
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Creates a release function for the current lock holder.
+     */
+    private _createRelease;
+    /**
+     * Returns whether the mutex is currently locked.
+     */
+    get isLocked(): boolean;
+    /**
+     * Executes a function with the mutex held.
+     * Automatically releases the mutex when done.
+     */
+    runExclusive<T>(fn: () => Promise<T> | T): Promise<T>;
+}
+/**
+ * Keyed mutex for per-key locking.
+ * Allows concurrent operations on different keys while serializing same-key operations.
+ */
+export declare class KeyedMutex {
+    private readonly _mutexes;
+    private readonly _refCounts;
+    /**
+     * Acquires lock for a specific key.
+     * Returns a release function that must be called when done.
+     */
+    acquire(key: string): Promise<() => void>;
+    /**
+     * Executes a function with the keyed mutex held.
+     * Automatically releases the mutex when done.
+     */
+    runExclusive<T>(key: string, fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Returns the number of active keys with pending operations.
+     */
+    get activeKeyCount(): number;
+}
+//# sourceMappingURL=mutex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../../../src/core/mutex.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,OAAO,CAAS;IAExB;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;IAcpC;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACG,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAQ5D;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAExD;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAqC/C;;;OAGG;IACG,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASxE;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;CACF"}