@b9g/cache 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,275 @@
+# @b9g/cache
+
+Universal Cache API implementation providing CacheStorage and Cache interfaces across all JavaScript runtimes.
+
+## Features
+
+- **Standard APIs**: Implements the Cache and CacheStorage APIs from service workers
+- **Multiple Backends**: Memory, filesystem, Redis, KV store implementations
+- **Universal**: Same API works in browsers, Node.js, Bun, and edge platforms
+- **Request/Response**: HTTP-semantic caching with full Request/Response support
+- **Registry Pattern**: Named cache management with factory registration
+
+## Installation
+
+```bash
+npm install @b9g/cache
+```
+
+## Quick Start
+
+```javascript
+import { CacheStorage, MemoryCache } from '@b9g/cache';
+
+// Create cache storage
+const caches = new CacheStorage();
+
+// Register cache implementations
+caches.register('api', () => new MemoryCache('api'));
+caches.register('pages', () => new MemoryCache('pages'));
+
+// Open and use caches
+const apiCache = await caches.open('api');
+
+// Store response
+const request = new Request('https://api.example.com/posts/1');
+const response = new Response(JSON.stringify({ id: 1, title: 'Hello' }));
+await apiCache.put(request, response);
+
+// Retrieve response
+const cached = await apiCache.match(request);
+console.log(await cached.json()); // { id: 1, title: 'Hello' }
+```
+
+## Cache Implementations
+
+### MemoryCache
+
+In-memory cache with TTL and size limits:
+
+```javascript
+import { MemoryCache } from '@b9g/cache';
+
+const cache = new MemoryCache('my-cache', {
+  maxEntries: 1000,        // Maximum number of entries
+  ttl: 300,               // Time to live in seconds
+  maxSize: 50 * 1024 * 1024 // Maximum total size in bytes
+});
+```
+
+### FilesystemCache
+
+File-based cache for SSG and persistent storage:
+
+```javascript
+import { FilesystemCache } from '@b9g/cache';
+
+const cache = new FilesystemCache('pages', {
+  directory: './dist/cache',
+  compression: true,
+  indexing: true
+});
+```
+
+## CacheStorage Registry
+
+```javascript
+import { CacheStorage, MemoryCache, FilesystemCache } from '@b9g/cache';
+
+const caches = new CacheStorage();
+
+// Register different implementations
+caches.register('api', () => 
+  new MemoryCache('api', { ttl: 300 })
+);
+
+caches.register('pages', () =>
+  new FilesystemCache('pages', { directory: './dist/pages' })
+);
+
+caches.register('assets', () =>
+  new MemoryCache('assets', { maxEntries: 10000 })
+);
+
+// Use with router
+import { Router } from '@b9g/router';
+const router = new Router({ caches });
+```
+
+## Cache API Reference
+
+### Standard Cache Methods
+
+```javascript
+// Check for cached response
+const response = await cache.match(request, options?);
+
+// Get all matching responses
+const responses = await cache.matchAll(request?, options?);
+
+// Store request/response pair
+await cache.put(request, response);
+
+// Fetch and store
+await cache.add(request);
+await cache.addAll(requests);
+
+// Remove cached entry
+const deleted = await cache.delete(request, options?);
+
+// List cached requests
+const requests = await cache.keys(request?, options?);
+```
+
+### CacheStorage Methods
+
+```javascript
+// Register cache factory
+caches.register(name, factory);
+
+// Open named cache
+const cache = await caches.open(name);
+
+// Check if cache exists
+const exists = await caches.has(name);
+
+// Delete named cache
+const deleted = await caches.delete(name);
+
+// List cache names
+const names = await caches.keys();
+```
+
+## Cache Options
+
+### Query Options
+
+```javascript
+const response = await cache.match(request, {
+  ignoreSearch: true,     // Ignore query parameters
+  ignoreMethod: false,    // Consider HTTP method
+  ignoreVary: false,      // Honor Vary header
+  cacheName: 'specific'   // Target specific cache
+});
+```
+
+### Storage Options
+
+```javascript
+// Memory cache options
+new MemoryCache('name', {
+  maxEntries: 1000,
+  ttl: 300,
+  maxSize: 50 * 1024 * 1024
+});
+
+// Filesystem cache options
+new FilesystemCache('name', {
+  directory: './cache',
+  compression: true,
+  indexing: true,
+  fsync: false
+});
+```
+
+## Integration Examples
+
+### With Router
+
+```javascript
+import { Router } from '@b9g/router';
+import { CacheStorage, MemoryCache } from '@b9g/cache';
+
+const caches = new CacheStorage();
+caches.register('api', () => new MemoryCache('api'));
+
+const router = new Router({ caches });
+
+// Cache-aware middleware
+router.use(async (request, context, next) => {
+  if (request.method === 'GET' && context.cache) {
+    const cached = await context.cache.match(request);
+    if (cached) return cached;
+  }
+  
+  const response = await next();
+  
+  if (request.method === 'GET' && context.cache && response.ok) {
+    await context.cache.put(request, response.clone());
+  }
+  
+  return response;
+});
+
+router.route('/api/posts/:id', { cache: { name: 'api' } })
+  .get(postHandler);
+```
+
+### Static Site Generation
+
+```javascript
+import { FilesystemCache } from '@b9g/cache';
+
+const cache = new FilesystemCache('pages', {
+  directory: './dist'
+});
+
+// Pre-populate cache at build time
+const paths = ['/about', '/contact', '/blog/post-1'];
+
+for (const path of paths) {
+  const request = new Request(`https://example.com${path}`);
+  await cache.add(request); // Fetches through your router
+}
+
+// At runtime, serve from cache
+const response = await cache.match(request);
+```
+
+### Service Worker
+
+```javascript
+// In service worker context
+import { CacheStorage } from '@b9g/cache';
+
+// Use native browser caches when available
+const caches = new CacheStorage();
+
+self.addEventListener('fetch', async event => {
+  const cache = await caches.open('runtime');
+  
+  event.respondWith(
+    cache.match(event.request).then(response => {
+      if (response) return response;
+      
+      return fetch(event.request).then(response => {
+        if (response.ok) {
+          cache.put(event.request, response.clone());
+        }
+        return response;
+      });
+    })
+  );
+});
+```
+
+## Cache Coordination
+
+For multi-worker setups, caches coordinate through PostMessage:
+
+```javascript
+// Worker thread cache coordination
+const cache = new MemoryCache('shared', {
+  coordination: {
+    type: 'postmessage',
+    channel: 'cache-coordination'
+  }
+});
+
+// Operations are coordinated across workers
+await cache.put(request, response); // Synced to all workers
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/cache",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Universal Cache API implementation",
   "keywords": [
     "cache",

package/src/index.d.ts

@@ -7,3 +7,11 @@ export { Cache, type CacheQueryOptions, generateCacheKey, cloneResponse } from "
 export { CustomCacheStorage, type CacheFactory } from "./cache-storage.js";
 export { MemoryCache, MemoryCacheManager, type MemoryCacheOptions } from "./memory.js";
 export { PostMessageCache, type PostMessageCacheOptions } from "./postmessage.js";
+import { MemoryCache, type MemoryCacheOptions } from "./memory.js";
+/**
+ * Platform adapter factory function
+ * Creates a MemoryCache instance with the given configuration
+ */
+export declare function createCache(config?: MemoryCacheOptions & {
+    name?: string;
+}): MemoryCache;

package/src/index.js

@@ -4,6 +4,11 @@ import { Cache, generateCacheKey, cloneResponse } from "./cache.js";
 import { CustomCacheStorage } from "./cache-storage.js";
 import { MemoryCache, MemoryCacheManager } from "./memory.js";
 import { PostMessageCache } from "./postmessage.js";
+import { MemoryCache as MemoryCache2 } from "./memory.js";
+function createCache(config = {}) {
+  const name = config.name || "default";
+  return new MemoryCache2(name, config);
+}
 export {
   Cache,
   CustomCacheStorage,
@@ -11,5 +16,6 @@ export {
   MemoryCacheManager,
   PostMessageCache,
   cloneResponse,
+  createCache,
   generateCacheKey
 };

package/src/memory.d.ts

@@ -75,7 +75,10 @@ export declare class MemoryCache extends Cache {
  * Only MemoryCache needs coordination since it stores data in process memory.
  * Other cache types can be used directly by workers without coordination.
  */
-import type { Worker } from "worker_threads";
+interface WorkerLike {
+    postMessage(value: any): void;
+    on(event: string, listener: (data: any) => void): void;
+}
 interface CacheMessage {
     type: string;
     requestId: string;
@@ -101,7 +104,7 @@ export declare class MemoryCacheManager {
     /**
      * Handle memory cache-related message from a Worker
      */
-    handleMessage(worker: Worker, message: CacheMessage): Promise<void>;
+    handleMessage(worker: WorkerLike, message: CacheMessage): Promise<void>;
     /**
      * Get or create a MemoryCache instance
      */

package/src/memory.js

@@ -41,7 +41,7 @@ var MemoryCache = class extends Cache {
       return;
     }
     const clonedRequest = request.clone();
-    const clonedResponse = cloneResponse(response);
+    const clonedResponse = await cloneResponse(response);
     const entry = {
       request: clonedRequest,
       response: clonedResponse,
@@ -217,7 +217,7 @@ var MemoryCacheManager = class {
     return {
       status: response.status,
       statusText: response.statusText,
-      headers: Object.fromEntries(response.headers.entries()),
+      headers: Object.fromEntries(response.headers),
       body: await response.text()
     };
   }
@@ -266,7 +266,7 @@ var MemoryCacheManager = class {
     return keys.map((r) => ({
       url: r.url,
       method: r.method,
-      headers: Object.fromEntries(r.headers.entries()),
+      headers: Object.fromEntries(r.headers),
       body: void 0
       // Keys typically don't need body
     }));

package/src/postmessage.js

@@ -1,7 +1,8 @@
 /// <reference types="./postmessage.d.ts" />
 // src/postmessage.ts
 import { Cache } from "./cache.js";
-import { parentPort, isMainThread } from "worker_threads";
+var isMainThread = typeof self === "undefined";
+var parentPort = typeof self !== "undefined" ? self : null;
 var PostMessageCache = class extends Cache {
   constructor(name, options = {}) {
     super();
@@ -60,7 +61,7 @@ var PostMessageCache = class extends Cache {
     const serializedRequest = {
       url: request.url,
       method: request.method,
-      headers: Object.fromEntries(request.headers.entries()),
+      headers: Object.fromEntries(request.headers),
       body: request.method !== "GET" && request.method !== "HEAD" ? await request.text() : void 0
     };
     const response = await this.sendRequest("cache:match", {
@@ -80,13 +81,13 @@ var PostMessageCache = class extends Cache {
     const serializedRequest = {
       url: request.url,
       method: request.method,
-      headers: Object.fromEntries(request.headers.entries()),
+      headers: Object.fromEntries(request.headers),
       body: request.method !== "GET" && request.method !== "HEAD" ? await request.clone().text() : void 0
     };
     const serializedResponse = {
       status: response.status,
       statusText: response.statusText,
-      headers: Object.fromEntries(response.headers.entries()),
+      headers: Object.fromEntries(response.headers),
       body: await response.clone().text()
     };
     await this.sendRequest("cache:put", {
@@ -98,7 +99,7 @@ var PostMessageCache = class extends Cache {
     const serializedRequest = {
       url: request.url,
       method: request.method,
-      headers: Object.fromEntries(request.headers.entries()),
+      headers: Object.fromEntries(request.headers),
       body: request.method !== "GET" && request.method !== "HEAD" ? await request.text() : void 0
     };
     return await this.sendRequest("cache:delete", {
@@ -112,7 +113,7 @@ var PostMessageCache = class extends Cache {
       serializedRequest = {
         url: request.url,
         method: request.method,
-        headers: Object.fromEntries(request.headers.entries()),
+        headers: Object.fromEntries(request.headers),
         body: request.method !== "GET" && request.method !== "HEAD" ? await request.text() : void 0
       };
     }