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

package/src/factory.ts

@@ -0,0 +1,60 @@
+import type { ICacheConfig } from "./core/types";
+import type { IStorageAdapter } from "./core/adapter";
+import { CacheEngine } from "./core/cacheEngine";
+
+export interface ICreateCacheOptions extends ICacheConfig {
+  /**
+   * If true, auto-initializes the cache before returning.
+   * @default true
+   */
+  readonly autoInit?: boolean;
+}
+
+/**
+ * Creates an immutable file cache instance.
+ *
+ * This is the base factory function. Platform-specific entrypoints
+ * (index.native.ts, index.web.ts) wrap this to auto-select the appropriate adapter.
+ *
+ * @param options - Cache configuration options
+ * @param adapter - Storage adapter (required in base factory)
+ * @returns Initialized CacheEngine instance
+ *
+ * @example
+ * ```typescript
+ * import { createImmutableFileCache } from "react-native-immutable-file-cache";
+ *
+ * const cache = await createImmutableFileCache({
+ *   namespace: "images",
+ *   defaultTtlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+ * });
+ * ```
+ */
+export async function createImmutableFileCache(
+  options: ICreateCacheOptions & { adapter: IStorageAdapter }
+): Promise<CacheEngine> {
+  const { autoInit = true, adapter, ...config } = options;
+
+  const engine = new CacheEngine(config, adapter);
+
+  if (autoInit) {
+    await engine.init();
+  }
+
+  return engine;
+}
+
+/**
+ * Creates a cache engine without auto-initialization.
+ * Useful when you need to control initialization timing.
+ *
+ * @example
+ * ```typescript
+ * const engine = createCacheEngineSync({ namespace: "images" }, adapter);
+ * // Later...
+ * await engine.init();
+ * ```
+ */
+export function createCacheEngineSync(config: ICacheConfig, adapter: IStorageAdapter): CacheEngine {
+  return new CacheEngine(config, adapter);
+}

package/src/index.native.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 type { ICreateCacheOptions } from "./factory";
+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?: Omit<ICreateCacheOptions, "adapter"> & { adapter?: ICreateCacheOptions["adapter"] }
+): Promise<CacheEngine> {
+  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;
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @dynlabs/react-native-immutable-file-cache
+ *
+ * Cross-platform immutable file cache with pluggable storage adapters.
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Core Types
+// ─────────────────────────────────────────────────────────────────
+
+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";
+
+// ─────────────────────────────────────────────────────────────────
+// Errors
+// ─────────────────────────────────────────────────────────────────
+
+export {
+  CacheError,
+  UnsupportedSourceError,
+  AdapterIOError,
+  CorruptIndexError,
+  ImmutableConflictError,
+  EntryNotFoundError,
+} from "./core/errors";
+
+// ─────────────────────────────────────────────────────────────────
+// Core Engine
+// ─────────────────────────────────────────────────────────────────
+
+export { CacheEngine } from "./core/cacheEngine";
+
+// ─────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────
+
+export { createImmutableFileCache, createCacheEngineSync } from "./factory";
+
+export type { ICreateCacheOptions } from "./factory";
+
+// ─────────────────────────────────────────────────────────────────
+// Adapters
+// ─────────────────────────────────────────────────────────────────
+
+export { createRnfsAdapter } from "./adapters/rnfsAdapter";
+export type { IRnfsAdapterOptions } from "./adapters/rnfsAdapter";
+
+export { createWebAdapter } from "./adapters/webAdapter";
+export type { IWebAdapterOptions, IWebAdapterWithCleanup } from "./adapters/webAdapter";
+
+export { createMemoryAdapter } from "./adapters/memoryAdapter";
+export type { IMemoryAdapter } from "./adapters/memoryAdapter";
+
+// ─────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────
+
+export { hash, hashSync } from "./core/hash";
+export { Mutex, KeyedMutex } from "./core/mutex";

package/src/index.web.ts

@@ -0,0 +1,59 @@
+/**
+ * @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 type { ICreateCacheOptions } from "./factory";
+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?: Omit<ICreateCacheOptions, "adapter"> & { adapter?: ICreateCacheOptions["adapter"] }
+): Promise<CacheEngine> {
+  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;
+}

package/src/types/react-native-fs.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Type declarations for react-native-fs
+ * This is a minimal stub to satisfy TypeScript when the actual package is not installed.
+ */
+declare module "react-native-fs" {
+  export const CachesDirectoryPath: string;
+  export const DocumentDirectoryPath: string;
+
+  export interface StatResult {
+    size: number;
+    mtime: string | number | Date;
+    ctime: string | number | Date;
+    isFile: () => boolean;
+    isDirectory: () => boolean;
+  }
+
+  export interface ReadDirItem {
+    name: string;
+    path: string;
+    size: number;
+    isFile: () => boolean;
+    isDirectory: () => boolean;
+  }
+
+  export interface DownloadFileOptions {
+    fromUrl: string;
+    toFile: string;
+    headers?: Record<string, string>;
+    progress?: (res: { contentLength: number; bytesWritten: number }) => void;
+    progressDivider?: number;
+  }
+
+  export interface DownloadResult {
+    jobId: number;
+    statusCode: number;
+    bytesWritten: number;
+  }
+
+  export interface DownloadBeginCallbackResult {
+    jobId: number;
+    contentLength: number;
+    headers: Record<string, string>;
+  }
+
+  export function mkdir(path: string): Promise<void>;
+  export function exists(path: string): Promise<boolean>;
+  export function unlink(path: string): Promise<void>;
+  export function readDir(path: string): Promise<ReadDirItem[]>;
+  export function readFile(path: string, encoding?: string): Promise<string>;
+  export function writeFile(path: string, content: string, encoding?: string): Promise<void>;
+  export function moveFile(from: string, to: string): Promise<void>;
+  export function copyFile(from: string, to: string): Promise<void>;
+  export function stat(path: string): Promise<StatResult>;
+  export function downloadFile(options: DownloadFileOptions): {
+    jobId: number;
+    promise: Promise<DownloadResult>;
+  };
+
+  const RNFS: {
+    CachesDirectoryPath: string;
+    DocumentDirectoryPath: string;
+    mkdir: typeof mkdir;
+    exists: typeof exists;
+    unlink: typeof unlink;
+    readDir: typeof readDir;
+    readFile: typeof readFile;
+    writeFile: typeof writeFile;
+    moveFile: typeof moveFile;
+    copyFile: typeof copyFile;
+    stat: typeof stat;
+    downloadFile: typeof downloadFile;
+  };
+
+  export default RNFS;
+}