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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,415 @@
+# @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.
+
+## 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
+
+## Installation
+
+```bash
+npm install @dynlabs/react-native-immutable-file-cache
+```
+
+### React Native (iOS/Android)
+
+Also install the filesystem dependency:
+
+```bash
+npm install react-native-fs
+cd ios && pod install
+```
+
+### Web
+
+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"
+);
+
+if (result.status === "created") {
+  console.log("Cached new image:", result.entry.sizeBytes, "bytes");
+} else {
+  console.log("Image already cached");
+}
+
+// Retrieve cached entry
+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
+
+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
+
+```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,
+});
+```
+
+### 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.
+
+```typescript
+const result = await cache.putFromFile("doc-key", "/path/to/document.pdf", {
+  ext: ".pdf",
+});
+```
+
+#### `putFromBlob(key, blob, options?)` (Web only)
+
+Cache content from a Blob.
+
+```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]));
+```
+
+### 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);
+}
+```
+
+#### `has(key)`
+
+Check if key exists and is not expired.
+
+```typescript
+if (await cache.has("image-key")) {
+  // Entry exists
+}
+```
+
+#### `peek(key)`
+
+Get entry metadata without updating `lastAccessedAt`.
+
+```typescript
+const entry = await cache.peek("image-key");
+```
+
+### List/Query Operations
+
+#### `list(options?)`
+
+List entries with sorting, filtering, and pagination.
+
+```typescript
+const entries = await cache.list({
+  sortBy: "createdAt",      // "createdAt" | "lastAccessedAt" | "sizeBytes" | "key"
+  order: "desc",            // "asc" | "desc"
+  limit: 10,
+  offset: 0,
+  filter: (entry) => entry.sizeBytes > 1000,
+});
+```
+
+#### `stats()`
+
+Get cache statistics.
+
+```typescript
+const stats = await cache.stats();
+console.log(`${stats.entryCount} entries, ${stats.totalSizeBytes} bytes`);
+```
+
+### Remove/Prune Operations
+
+#### `remove(key)`
+
+Remove specific entry.
+
+```typescript
+const removed = await cache.remove("image-key");
+```
+
+#### `removeExpired()`
+
+Remove all expired entries.
+
+```typescript
+const result = await cache.removeExpired();
+console.log(`Removed ${result.removedCount} entries, freed ${result.freedBytes} bytes`);
+```
+
+#### `pruneLru(maxSizeBytes)`
+
+Prune to fit size limit using LRU.
+
+```typescript
+await cache.pruneLru(50 * 1024 * 1024); // Prune to 50MB
+```
+
+#### `clear()`
+
+Remove all entries.
+
+```typescript
+await cache.clear();
+```
+
+### Maintenance
+
+#### `validateAndRepair()`
+
+Validate index against filesystem and rebuild if needed.
+
+```typescript
+const result = await cache.validateAndRepair();
+if (result.repaired) {
+  console.log("Fixed issues:", result.issues);
+}
+```
+
+## Web-Specific: Blob URL Cleanup
+
+On web, `getPublicUri()` returns `blob:` URLs. To prevent memory leaks, clean up URLs when done:
+
+```typescript
+import { createWebAdapter, IWebAdapterWithCleanup } from "@dynlabs/react-native-immutable-file-cache";
+
+const adapter = createWebAdapter() as IWebAdapterWithCleanup;
+
+// When done with a specific URL
+adapter.revokeUri(entry.uri);
+
+// Or revoke all URLs
+adapter.revokeAllUris();
+```
+
+## Error Handling
+
+The package provides typed errors:
+
+```typescript
+import {
+  CacheError,
+  UnsupportedSourceError,
+  AdapterIOError,
+  CorruptIndexError,
+  ImmutableConflictError,
+  EntryNotFoundError,
+} from "@dynlabs/react-native-immutable-file-cache";
+
+try {
+  await cache.putFromBlob("key", blob);
+} catch (error) {
+  if (error instanceof UnsupportedSourceError) {
+    console.log(`${error.sourceType} not supported on ${error.adapterKind}`);
+  }
+}
+```
+
+## 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
+
+To add a new adapter, implement `IStorageAdapter` and pass it to `createImmutableFileCache({ adapter })`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on adding adapters.
+
+## Testing
+
+The package includes a `MemoryAdapter` for testing:
+
+```typescript
+import { CacheEngine, createMemoryAdapter } from "@dynlabs/react-native-immutable-file-cache";
+
+const adapter = createMemoryAdapter("test");
+const cache = new CacheEngine({ namespace: "test" }, adapter);
+await cache.init();
+
+// Run tests...
+
+// Clean up
+adapter._reset();
+```
+
+## 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
+```
+
+## License
+
+MIT

package/lib/commonjs/adapters/memoryAdapter.js

@@ -0,0 +1,266 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createMemoryAdapter = createMemoryAdapter;
+var _errors = require("../core/errors");
+/**
+ * In-Memory Storage Adapter
+ *
+ * For testing purposes only.
+ * Implements IStorageAdapter using in-memory storage.
+ */
+
+/* eslint-disable @typescript-eslint/require-await */
+
+/**
+ * Extended interface for memory adapter with test utilities.
+ */
+
+/**
+ * Creates an in-memory storage adapter for testing.
+ */
+function createMemoryAdapter(namespace) {
+  const ns = namespace ?? "default";
+  const rootId = `memory://${ns}`;
+
+  // In-memory storage
+  const files = new Map();
+  const directories = new Set();
+
+  // Track blob URLs for cleanup
+  const blobUrls = new Map();
+
+  /**
+   * Normalizes path by removing leading/trailing slashes.
+   */
+  const normalizePath = path => {
+    return path.replace(/^\/+|\/+$/g, "");
+  };
+
+  /**
+   * Gets the parent directory of a path.
+   */
+  const getParentDir = path => {
+    const lastSlash = path.lastIndexOf("/");
+    return lastSlash > 0 ? path.substring(0, lastSlash) : null;
+  };
+  const adapter = {
+    kind: "memory",
+    rootId,
+    // ─────────────────────────────────────────────────────────────────
+    // Directory Management
+    // ─────────────────────────────────────────────────────────────────
+
+    async ensureDir(path) {
+      const normalized = normalizePath(path);
+      if (normalized) {
+        directories.add(normalized);
+        // Also ensure parent directories
+        const parent = getParentDir(normalized);
+        if (parent) {
+          await this.ensureDir(parent);
+        }
+      }
+    },
+    async exists(path) {
+      const normalized = normalizePath(path);
+      return files.has(normalized) || directories.has(normalized);
+    },
+    async remove(path) {
+      const normalized = normalizePath(path);
+      files.delete(normalized);
+    },
+    async removeDir(path) {
+      const normalized = normalizePath(path);
+      const prefix = normalized + "/";
+
+      // Remove all files with this prefix
+      for (const key of files.keys()) {
+        if (key === normalized || key.startsWith(prefix)) {
+          files.delete(key);
+        }
+      }
+
+      // Remove all directories with this prefix
+      for (const dir of directories) {
+        if (dir === normalized || dir.startsWith(prefix)) {
+          directories.delete(dir);
+        }
+      }
+    },
+    async listDir(path) {
+      const normalized = normalizePath(path);
+      const prefix = normalized ? normalized + "/" : "";
+      const entries = new Set();
+
+      // Find all files in this directory
+      for (const key of files.keys()) {
+        if (key.startsWith(prefix)) {
+          const relativePath = key.slice(prefix.length);
+          const firstSlash = relativePath.indexOf("/");
+          if (firstSlash === -1) {
+            // Direct child file
+            entries.add(relativePath);
+          }
+        }
+      }
+      return Array.from(entries);
+    },
+    // ─────────────────────────────────────────────────────────────────
+    // File I/O
+    // ─────────────────────────────────────────────────────────────────
+
+    async readText(path, _encoding) {
+      const normalized = normalizePath(path);
+      const entry = files.get(normalized);
+      if (!entry) {
+        throw new _errors.AdapterIOError("readText", path, new Error("File not found"));
+      }
+      const decoder = new TextDecoder("utf-8");
+      return decoder.decode(entry.content);
+    },
+    async writeTextAtomic(path, content, _encoding) {
+      const normalized = normalizePath(path);
+      const encoder = new TextEncoder();
+      const bytes = encoder.encode(content);
+      files.set(normalized, {
+        content: bytes,
+        mtime: Date.now(),
+        contentType: "text/plain"
+      });
+
+      // Ensure parent directory exists
+      const parent = getParentDir(normalized);
+      if (parent) {
+        directories.add(parent);
+      }
+    },
+    async stat(path) {
+      const normalized = normalizePath(path);
+      const entry = files.get(normalized);
+      if (!entry) {
+        throw new _errors.AdapterIOError("stat", path, new Error("File not found"));
+      }
+      return {
+        sizeBytes: entry.content.length,
+        mtimeMs: entry.mtime
+      };
+    },
+    async writeBinaryAtomic(path, source, options) {
+      const normalized = normalizePath(path);
+      let content;
+      let contentType;
+      switch (source.type) {
+        case "url":
+          {
+            // Simulate URL fetch
+            try {
+              const response = await fetch(source.url, {
+                headers: {
+                  ...source.headers,
+                  ...options?.headers
+                }
+              });
+              if (!response.ok) {
+                throw new Error(`Fetch failed: ${response.status}`);
+              }
+              contentType = response.headers.get("content-type") ?? undefined;
+              const buffer = await response.arrayBuffer();
+              content = new Uint8Array(buffer);
+              options?.onProgress?.(100);
+            } catch (error) {
+              throw new _errors.AdapterIOError("writeBinaryAtomic", path, error);
+            }
+            break;
+          }
+        case "file":
+          {
+            // Simulate file copy (just use path as content for testing)
+            const encoder = new TextEncoder();
+            content = encoder.encode(`[file:${source.filePath}]`);
+            options?.onProgress?.(100);
+            break;
+          }
+        case "blob":
+          {
+            const buffer = await source.blob.arrayBuffer();
+            content = new Uint8Array(buffer);
+            contentType = source.blob.type || undefined;
+            options?.onProgress?.(100);
+            break;
+          }
+        case "bytes":
+          {
+            content = source.bytes;
+            options?.onProgress?.(100);
+            break;
+          }
+        default:
+          {
+            const _exhaustive = source;
+            throw new _errors.AdapterIOError("writeBinaryAtomic", path, new Error(`Unknown source type: ${_exhaustive.type}`));
+          }
+      }
+      files.set(normalized, {
+        content,
+        mtime: Date.now(),
+        contentType
+      });
+
+      // Ensure parent directory exists
+      const parent = getParentDir(normalized);
+      if (parent) {
+        directories.add(parent);
+      }
+      return {
+        sizeBytes: content.length,
+        contentType
+      };
+    },
+    async getPublicUri(path) {
+      const normalized = normalizePath(path);
+      const entry = files.get(normalized);
+      if (!entry) {
+        throw new _errors.AdapterIOError("getPublicUri", path, new Error("File not found"));
+      }
+
+      // Check if we already have a blob URL for this path
+      const existing = blobUrls.get(normalized);
+      if (existing) {
+        return existing;
+      }
+
+      // Create blob URL
+      const blob = new Blob([entry.content.buffer], {
+        type: entry.contentType ?? "application/octet-stream"
+      });
+      const url = URL.createObjectURL(blob);
+      blobUrls.set(normalized, url);
+      return url;
+    },
+    // ─────────────────────────────────────────────────────────────────
+    // Test Utilities
+    // ─────────────────────────────────────────────────────────────────
+
+    _reset() {
+      files.clear();
+      directories.clear();
+      // Revoke all blob URLs
+      for (const url of blobUrls.values()) {
+        URL.revokeObjectURL(url);
+      }
+      blobUrls.clear();
+    },
+    _getContent(path) {
+      const normalized = normalizePath(path);
+      return files.get(normalized)?.content;
+    },
+    _getAllPaths() {
+      return Array.from(files.keys());
+    }
+  };
+  return adapter;
+}
+//# sourceMappingURL=memoryAdapter.js.map