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

package/README.md

@@ -1,19 +1,41 @@
-# @dynlabs/react-native-immutable-file-cache
-
-[![CI](https://github.com/dienp/react-native-immutable-file-cache/actions/workflows/ci.yml/badge.svg)](https://github.com/dienp/react-native-immutable-file-cache/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@dynlabs/react-native-immutable-file-cache.svg)](https://www.npmjs.com/package/@dynlabs/react-native-immutable-file-cache)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A cross-platform immutable file cache for React Native and Web with pluggable storage adapters.
+<p align="center">
+  <h1 align="center">react-native-immutable-file-cache</h1>
+</p>
+
+<p align="center">
+  <strong>Cross-platform immutable file cache for React Native and Web</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/dienp/react-native-immutable-file-cache/actions/workflows/ci.yml">
+    <img src="https://github.com/dienp/react-native-immutable-file-cache/actions/workflows/ci.yml/badge.svg" alt="CI" />
+  </a>
+  <a href="https://www.npmjs.com/package/@dynlabs/react-native-immutable-file-cache">
+    <img src="https://img.shields.io/npm/v/@dynlabs/react-native-immutable-file-cache.svg" alt="npm version" />
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api">API</a> •
+  <a href="#adapters">Adapters</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
 
 ## Features
 
-- **Immutable entries** - Once cached, entries cannot be overwritten
-- **Cross-platform** - Works on iOS, Android, and Web
-- **Pluggable adapters** - Swap storage backends without changing application code
-- **TTL & LRU pruning** - Automatic cache management
-- **Atomic writes** - Crash-safe file operations
-- **TypeScript first** - Full type safety with strict types
+- **Immutable entries** — Once cached, entries cannot be overwritten
+- **Cross-platform** — iOS, Android, and Web support
+- **Pluggable adapters** — Swap storage backends without code changes
+- **TTL & LRU pruning** — Automatic cache management
+- **Atomic writes** — Crash-safe file operations
+- **TypeScript first** — Full type safety
 
 ## Installation
 
@@ -21,328 +43,222 @@ A cross-platform immutable file cache for React Native and Web with pluggable st
 npm install @dynlabs/react-native-immutable-file-cache
 ```
 
-### React Native (iOS/Android)
-
-Also install the filesystem dependency:
+#### React Native
 
 ```bash
 npm install react-native-fs
 cd ios && pod install
 ```
 
-### Web
+#### Web
 
-No additional dependencies required - uses Cache Storage and IndexedDB.
+No additional dependencies required — uses Cache Storage and IndexedDB.
 
 ## Quick Start
 
 ```typescript
 import { createImmutableFileCache } from "@dynlabs/react-native-immutable-file-cache";
 
-// Create cache instance
 const cache = await createImmutableFileCache({
   namespace: "images",
   defaultTtlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
   maxSizeBytes: 100 * 1024 * 1024, // 100 MB
 });
 
-// Cache an image from URL
-const result = await cache.putFromUrl(
-  "avatar-123",
-  "https://example.com/avatar.jpg"
-);
+// Cache from URL
+const result = await cache.putFromUrl("avatar-123", "https://example.com/avatar.jpg");
 
 if (result.status === "created") {
-  console.log("Cached new image:", result.entry.sizeBytes, "bytes");
-} else {
-  console.log("Image already cached");
+  console.log("Cached:", result.entry.sizeBytes, "bytes");
 }
 
-// Retrieve cached entry
+// Retrieve
 const entry = await cache.get("avatar-123");
 if (entry) {
-  // Use entry.uri in Image component
   <Image source={{ uri: entry.uri }} />
 }
 ```
 
-## Architecture
-
-The package uses a three-layer architecture:
-
-```
-src/
-├── core/           # Platform-agnostic cache engine
-├── adapters/       # Platform-specific storage adapters
-└── index.*.ts      # Platform entrypoints
-```
-
-### Core Layer
+## API
 
-Contains all cache logic (immutability rules, TTL, LRU pruning, indexing) without any platform-specific code. The core depends only on the `IStorageAdapter` interface.
-
-### Adapters Layer
-
-Platform-specific implementations of `IStorageAdapter`:
-
-- **RNFS Adapter** - Uses `react-native-fs` for native platforms
-- **Web Adapter** - Uses Cache Storage + IndexedDB for browsers
-- **Memory Adapter** - In-memory storage for testing
-
-### Public API
-
-Platform entrypoints automatically select the appropriate adapter:
-
-- `index.native.ts` - React Native (iOS/Android)
-- `index.web.ts` - Web browsers
-
-## Adapters
-
-### Using the Default Adapter
-
-```typescript
-// React Native - automatically uses RNFS adapter
-import { createImmutableFileCache } from "@dynlabs/react-native-immutable-file-cache";
-
-// Web - automatically uses Web adapter
-import { createImmutableFileCache } from "@dynlabs/react-native-immutable-file-cache/web";
-```
-
-### Injecting a Custom Adapter
+### Configuration
 
 ```typescript
-import { createImmutableFileCache, createRnfsAdapter } from "@dynlabs/react-native-immutable-file-cache";
-
-const customAdapter = createRnfsAdapter({
-  baseDir: "/custom/path",
-  namespace: "my-app",
-});
-
-const cache = await createImmutableFileCache({
-  adapter: customAdapter,
+createImmutableFileCache({
+  namespace: "default",        // Cache isolation namespace
+  defaultTtlMs: undefined,     // Default TTL (ms), undefined = no expiry
+  maxSizeBytes: undefined,     // Max size, triggers LRU when exceeded
+  autoPruneExpired: true,      // Auto-remove expired entries
+  adapter: undefined,          // Custom storage adapter
+  hashFn: undefined,           // Custom hash function (default: SHA-256)
+  onEvent: undefined,          // Event handler for observability
 });
 ```
 
-### Building a Custom Adapter
-
-Implement the `IStorageAdapter` interface:
-
-```typescript
-import type { IStorageAdapter, TBinarySource, IBinaryWriteResult } from "@dynlabs/react-native-immutable-file-cache";
-
-const myAdapter: IStorageAdapter = {
-  kind: "my-storage",
-  rootId: "my-root",
-
-  async ensureDir(path) { /* Create directory */ },
-  async exists(path) { /* Check if exists */ },
-  async remove(path) { /* Remove file */ },
-  async removeDir(path) { /* Remove directory recursively */ },
-  async listDir(path) { /* List directory contents */ },
-  async readText(path, encoding) { /* Read text file */ },
-  async writeTextAtomic(path, content, encoding) { /* Write text atomically */ },
-  async stat(path) { /* Get file stats */ },
-  async writeBinaryAtomic(path, source, options) { /* Write binary atomically */ },
-  async getPublicUri(path) { /* Get URI for file */ },
-};
-```
-
-### Supported Binary Sources by Adapter
-
-| Source Type | RNFS Adapter | Web Adapter | Memory Adapter |
-|-------------|--------------|-------------|----------------|
-| `url`       | ✅           | ✅          | ✅             |
-| `file`      | ✅           | ❌          | ✅ (simulated) |
-| `blob`      | ❌           | ✅          | ✅             |
-| `bytes`     | ✅           | ✅          | ✅             |
-
-## API Reference
-
-### `createImmutableFileCache(options?)`
-
-Creates a new cache instance.
-
-#### Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `namespace` | `string` | `"default"` | Cache namespace for isolation |
-| `adapter` | `IStorageAdapter` | auto-detected | Custom storage adapter |
-| `defaultTtlMs` | `number` | `undefined` | Default TTL for entries |
-| `maxSizeBytes` | `number` | `undefined` | Max cache size (triggers LRU) |
-| `autoPruneExpired` | `boolean` | `true` | Auto-prune on operations |
-| `hashFn` | `(input: string) => string \| Promise<string>` | SHA-256 | Custom hash function |
-
 ### Put Operations
 
-All put operations are immutable - they return `{ status: "exists" }` if the key already exists.
-
-#### `putFromUrl(key, url, options?)`
-
-Cache content from a URL.
-
-```typescript
-const result = await cache.putFromUrl("image-key", "https://example.com/image.jpg", {
-  ttlMs: 86400000, // 1 day
-  ext: ".jpg",
-  metadata: { source: "cdn" },
-  onProgress: (pct) => console.log(`${pct}% downloaded`),
-  headers: { Authorization: "Bearer token" },
-});
-```
-
-#### `putFromFile(key, filePath, options?)` (Native only)
-
-Cache content from a local file.
+All put operations are immutable — returns `{ status: "exists" }` if the key already exists.
 
 ```typescript
-const result = await cache.putFromFile("doc-key", "/path/to/document.pdf", {
-  ext: ".pdf",
-});
-```
+// From URL
+await cache.putFromUrl(key, url, { ttlMs, ext, metadata, headers, onProgress });
 
-#### `putFromBlob(key, blob, options?)` (Web only)
+// From file (Native only)
+await cache.putFromFile(key, filePath, options);
 
-Cache content from a Blob.
+// From Blob (Web only)
+await cache.putFromBlob(key, blob, options);
 
-```typescript
-const blob = await response.blob();
-const result = await cache.putFromBlob("data-key", blob);
-```
-
-#### `putFromBytes(key, bytes, options?)`
-
-Cache raw bytes.
-
-```typescript
-const result = await cache.putFromBytes("raw-key", new Uint8Array([1, 2, 3]));
+// From bytes
+await cache.putFromBytes(key, new Uint8Array([...]), options);
 ```
 
 ### Get Operations
 
-#### `get(key)`
-
-Get entry with URI. Updates `lastAccessedAt`.
-
 ```typescript
-const result = await cache.get("image-key");
-if (result) {
-  console.log("URI:", result.uri);
-  console.log("Size:", result.entry.sizeBytes);
-}
-```
+// Get with URI (updates lastAccessedAt)
+const result = await cache.get(key);
+// => { entry, uri } | null
 
-#### `has(key)`
+// Check existence
+const exists = await cache.has(key);
 
-Check if key exists and is not expired.
+// Peek without updating access time
+const entry = await cache.peek(key);
 
-```typescript
-if (await cache.has("image-key")) {
-  // Entry exists
-}
-```
+// Get URI only
+const uri = await cache.getUri(key);
 
-#### `peek(key)`
-
-Get entry metadata without updating `lastAccessedAt`.
-
-```typescript
-const entry = await cache.peek("image-key");
+// Read-through cache
+const result = await cache.getOrPut(key, async (k) => ({
+  bytes: new Uint8Array([...]),
+  ttlMs: 86400000,
+  ext: ".json",
+}));
 ```
 
-### List/Query Operations
-
-#### `list(options?)`
-
-List entries with sorting, filtering, and pagination.
+### List & Stats
 
 ```typescript
+// List entries
 const entries = await cache.list({
-  sortBy: "createdAt",      // "createdAt" | "lastAccessedAt" | "sizeBytes" | "key"
-  order: "desc",            // "asc" | "desc"
+  sortBy: "createdAt",  // "createdAt" | "lastAccessedAt" | "sizeBytes" | "key"
+  order: "desc",        // "asc" | "desc"
   limit: 10,
   offset: 0,
-  filter: (entry) => entry.sizeBytes > 1000,
+  filter: (e) => e.sizeBytes > 1000,
 });
-```
 
-#### `stats()`
+// Get all keys
+const keys = await cache.keys();
 
-Get cache statistics.
+// Count entries
+const count = await cache.count();
 
-```typescript
+// Statistics
 const stats = await cache.stats();
-console.log(`${stats.entryCount} entries, ${stats.totalSizeBytes} bytes`);
+// => { entryCount, totalSizeBytes, oldestEntry?, newestEntry? }
 ```
 
-### Remove/Prune Operations
+### Cache Management
 
-#### `remove(key)`
+```typescript
+// Remove single entry
+await cache.remove(key);
 
-Remove specific entry.
+// Remove expired entries
+await cache.removeExpired();
+// => { removedCount, freedBytes, removedKeys }
 
-```typescript
-const removed = await cache.remove("image-key");
-```
+// LRU prune to size limit
+await cache.pruneLru(50 * 1024 * 1024);
 
-#### `removeExpired()`
+// Clear all
+await cache.clear();
 
-Remove all expired entries.
+// Validate & repair index
+await cache.validateAndRepair();
 
-```typescript
-const result = await cache.removeExpired();
-console.log(`Removed ${result.removedCount} entries, freed ${result.freedBytes} bytes`);
+// TTL management
+await cache.touch(key);              // Refresh access time
+await cache.setTtl(key, 86400000);   // Set new TTL
+await cache.extendTtl(key, 3600000); // Extend TTL
 ```
 
-#### `pruneLru(maxSizeBytes)`
-
-Prune to fit size limit using LRU.
+### Lifecycle
 
 ```typescript
-await cache.pruneLru(50 * 1024 * 1024); // Prune to 50MB
+// Flush pending writes (when using debounce)
+await cache.flush();
+
+// Destroy and release resources
+await cache.destroy();
 ```
 
-#### `clear()`
+## Adapters
 
-Remove all entries.
+The library uses a pluggable adapter architecture:
 
-```typescript
-await cache.clear();
-```
+| Adapter | Platform | Storage |
+|---------|----------|---------|
+| **RNFS** | iOS/Android | `react-native-fs` |
+| **Web** | Browser | Cache Storage + IndexedDB |
+| **Memory** | All | In-memory (testing) |
 
-### Maintenance
+### Default Adapter (Auto-selected)
 
-#### `validateAndRepair()`
+```typescript
+// React Native — uses RNFS adapter
+import { createImmutableFileCache } from "@dynlabs/react-native-immutable-file-cache";
 
-Validate index against filesystem and rebuild if needed.
+// Web — uses Web adapter
+import { createImmutableFileCache } from "@dynlabs/react-native-immutable-file-cache/web";
+```
+
+### Custom Adapter
 
 ```typescript
-const result = await cache.validateAndRepair();
-if (result.repaired) {
-  console.log("Fixed issues:", result.issues);
-}
-```
+import { createImmutableFileCache, createRnfsAdapter } from "@dynlabs/react-native-immutable-file-cache";
 
-## Web-Specific: Blob URL Cleanup
+const cache = await createImmutableFileCache({
+  adapter: createRnfsAdapter({ baseDir: "/custom/path", namespace: "my-app" }),
+});
+```
 
-On web, `getPublicUri()` returns `blob:` URLs. To prevent memory leaks, clean up URLs when done:
+### Supported Sources
 
-```typescript
-import { createWebAdapter, IWebAdapterWithCleanup } from "@dynlabs/react-native-immutable-file-cache";
+| Source | RNFS | Web | Memory |
+|--------|------|-----|--------|
+| `url` | ✓ | ✓ | ✓ |
+| `file` | ✓ | — | ✓ |
+| `blob` | — | ✓ | ✓ |
+| `bytes` | ✓ | ✓ | ✓ |
 
-const adapter = createWebAdapter() as IWebAdapterWithCleanup;
+### Implementing Custom Adapters
 
-// When done with a specific URL
-adapter.revokeUri(entry.uri);
+```typescript
+import type { IStorageAdapter } from "@dynlabs/react-native-immutable-file-cache";
 
-// Or revoke all URLs
-adapter.revokeAllUris();
+const myAdapter: IStorageAdapter = {
+  kind: "my-storage",
+  rootId: "my-root",
+  supportedSources: new Set(["url", "bytes"]),
+
+  async ensureDir(path) { /* ... */ },
+  async exists(path) { /* ... */ },
+  async remove(path) { /* ... */ },
+  async removeDir(path) { /* ... */ },
+  async listDir(path) { /* ... */ },
+  async readText(path, encoding) { /* ... */ },
+  async writeTextAtomic(path, content, encoding) { /* ... */ },
+  async stat(path) { /* ... */ },
+  async writeBinaryAtomic(path, source, options) { /* ... */ },
+  async getPublicUri(path) { /* ... */ },
+};
 ```
 
 ## Error Handling
 
-The package provides typed errors:
-
 ```typescript
 import {
   CacheError,
@@ -362,23 +278,32 @@ try {
 }
 ```
 
-## Future Adapters
-
-The adapter architecture makes it easy to add support for:
-
-- `react-native-blob-util`
-- `expo-file-system`
-- S3-backed remote cache
-- SQLite-based storage
-- Custom encrypted storage
+## Observability
 
-To add a new adapter, implement `IStorageAdapter` and pass it to `createImmutableFileCache({ adapter })`.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on adding adapters.
+```typescript
+const cache = await createImmutableFileCache({
+  onEvent: (event) => {
+    switch (event.type) {
+      case "cache_hit":
+        console.log(`HIT: ${event.key} (${event.ageMs}ms old)`);
+        break;
+      case "cache_miss":
+        console.log(`MISS: ${event.key} (${event.reason})`);
+        break;
+      case "cache_write":
+        console.log(`WRITE: ${event.key} (${event.sizeBytes} bytes)`);
+        break;
+      case "cache_prune":
+        console.log(`PRUNE: removed ${event.removedCount} entries`);
+        break;
+    }
+  },
+});
+```
 
 ## Testing
 
-The package includes a `MemoryAdapter` for testing:
+Use the memory adapter for unit tests:
 
 ```typescript
 import { CacheEngine, createMemoryAdapter } from "@dynlabs/react-native-immutable-file-cache";
@@ -389,27 +314,24 @@ await cache.init();
 
 // Run tests...
 
-// Clean up
-adapter._reset();
+adapter._reset(); // Clean up
 ```
 
 ## Contributing
 
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
-
 ```bash
-# Clone and install
 git clone https://github.com/dienp/react-native-immutable-file-cache.git
 cd react-native-immutable-file-cache
 npm install
 
-# Development
 npm run typecheck  # Type check
 npm run lint       # Lint
 npm test           # Run tests
 npm run build      # Build
 ```
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
 ## License
 
-MIT
+[MIT](LICENSE)

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.2",
   "description": "Cross-platform immutable file cache with pluggable storage adapters for React Native and Web",
   "author": "dienp",
   "license": "MIT",