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

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

@@ -3,18 +3,21 @@
  *
  * 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";
 export type { ICreateCacheOptions } from "./factory";
 export { createRnfsAdapter } from "./adapters/rnfsAdapter";
-export type { IRnfsAdapterOptions } from "./adapters/rnfsAdapter";
+export type { IRnfsAdapterOptions, IRnfsLike } 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";
 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,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAE7E,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.2",
+  "version": "1.0.0-alpha.4",
   "description": "Cross-platform immutable file cache with pluggable storage adapters for React Native and Web",
   "author": "dienp",
   "license": "MIT",
@@ -63,7 +63,8 @@
     "prepublishOnly": "npm run build && npm run lint && npm run typecheck && npm test",
     "release:patch": "npm version patch",
     "release:minor": "npm version minor",
-    "release:major": "npm version major"
+    "release:major": "npm version major",
+    "prepare": "husky"
   },
   "keywords": [
     "react-native",
@@ -98,7 +99,9 @@
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.1.3",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
+    "lint-staged": "^16.2.7",
     "prettier": "^3.2.5",
     "react-native-builder-bob": "^0.23.2",
     "rimraf": "^5.0.5",
@@ -121,5 +124,14 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "__tests__/**/*.ts": [
+      "prettier --write"
+    ]
   }
 }

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

@@ -1,8 +1,11 @@
 /**
  * React Native FS Adapter
  *
- * This is the ONLY file that imports react-native-fs.
+ * This is the ONLY file that imports react-native-fs by default.
  * Implements IStorageAdapter using RNFS APIs.
+ *
+ * Users can provide their own RNFS-compatible instance (e.g., a fork)
+ * via the `rnfs` option.
  */
 
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
@@ -13,7 +16,7 @@
 /* eslint-disable @typescript-eslint/require-await */
 
 // RNFS types are not fully typed, disable unsafe rules for this adapter
-import RNFS, { type DownloadResult } from "react-native-fs";
+import DefaultRNFS, { type DownloadResult } from "react-native-fs";
 import type {
   IStorageAdapter,
   TAdapterPath,
@@ -24,17 +27,86 @@ import type {
 } from "../core/adapter";
 import { UnsupportedSourceError, AdapterIOError } from "../core/errors";
 
+/**
+ * Minimal interface for RNFS-compatible libraries.
+ * Allows users to provide alternative implementations or forks.
+ */
+export interface IRnfsLike {
+  /** Path to the caches directory. */
+  readonly CachesDirectoryPath: string;
+
+  /** Check if a file/directory exists. */
+  exists(path: string): Promise<boolean>;
+
+  /** Create a directory (and parents). */
+  mkdir(path: string): Promise<void>;
+
+  /** Delete a file or directory. */
+  unlink(path: string): Promise<void>;
+
+  /** Read directory contents. */
+  readDir(path: string): Promise<ReadonlyArray<{ name: string }>>;
+
+  /** Read file as text. */
+  readFile(path: string, encoding: "utf8" | "base64"): Promise<string>;
+
+  /** Write file. */
+  writeFile(path: string, content: string, encoding: "utf8" | "base64"): Promise<void>;
+
+  /** Move/rename a file. */
+  moveFile(from: string, to: string): Promise<void>;
+
+  /** Copy a file. */
+  copyFile(from: string, to: string): Promise<void>;
+
+  /** Get file stats. */
+  stat(path: string): Promise<{ size: number; mtime: string | number | Date }>;
+
+  /** Download a file from URL. */
+  downloadFile(options: {
+    fromUrl: string;
+    toFile: string;
+    headers?: Record<string, string>;
+    progress?: (res: { contentLength: number; bytesWritten: number }) => void;
+    progressDivider?: number;
+  }): { promise: Promise<DownloadResult> };
+}
+
 export interface IRnfsAdapterOptions {
   /** Base directory. @default RNFS.CachesDirectoryPath */
   readonly baseDir?: string;
   /** Namespace subdirectory. */
   readonly namespace?: string;
+  /**
+   * Custom RNFS-compatible instance.
+   * Use this to provide a fork or alternative implementation of react-native-fs.
+   * @default The default react-native-fs import
+   *
+   * @example
+   * ```typescript
+   * import CustomRNFS from 'react-native-fs-turbo';
+   *
+   * const adapter = createRnfsAdapter({
+   *   rnfs: CustomRNFS,
+   *   namespace: 'my-cache',
+   * });
+   * ```
+   */
+  readonly rnfs?: IRnfsLike;
 }
 
 /**
  * Creates a storage adapter backed by react-native-fs.
+ *
+ * @param options - Configuration options
+ * @param options.baseDir - Base directory for cache storage
+ * @param options.namespace - Namespace subdirectory for isolation
+ * @param options.rnfs - Custom RNFS-compatible instance (for forks)
  */
 export function createRnfsAdapter(options?: IRnfsAdapterOptions): IStorageAdapter {
+  // Use provided RNFS instance or fall back to default import
+  const RNFS: IRnfsLike = options?.rnfs ?? DefaultRNFS;
+
   const baseDir = options?.baseDir ?? RNFS.CachesDirectoryPath;
   const namespace = options?.namespace ?? "default";
   const rootPath = `${baseDir}/immutable-cache/${namespace}`;
@@ -56,6 +128,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 +346,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

package/src/core/adapter.ts

@@ -4,6 +4,11 @@
  */
 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.
@@ -59,6 +64,14 @@ export interface IStorageAdapter {
   /** 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>;
+
   // ─────────────────────────────────────────────────────────────────
   // Directory Management
   // ─────────────────────────────────────────────────────────────────
@@ -126,3 +139,18 @@ 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 function adapterSupportsSource(
+  adapter: IStorageAdapter,
+  sourceType: TBinarySourceType
+): boolean {
+  if (!adapter.supportedSources) {
+    // No capability declaration - assume all types potentially supported
+    return true;
+  }
+  return adapter.supportedSources.has(sourceType);
+}