@b9g/cache 0.1.5 → 0.2.0-beta.0

package/README.md

@@ -4,11 +4,11 @@
 
 ## Features
 
-- **ServiceWorker Cache API**: Standard `caches` global and Cache interface from ServiceWorker spec
-- **Multiple Backends**: Memory, filesystem, Redis, KV store implementations  
+- **ServiceWorker Cache API**: Standard `Cache` and `CacheStorage` interfaces from ServiceWorker spec
+- **Multiple Backends**: Memory cache with LRU eviction, PostMessage coordination for workers
 - **Universal**: Same API works in browsers, Node.js, Bun, and edge platforms
 - **Request/Response Caching**: Full HTTP semantics with Request/Response objects
-- **Registry Pattern**: Named cache management with factory registration
+- **Factory Pattern**: Flexible cache creation with factory functions
 
 ## Installation
 
@@ -18,104 +18,208 @@ npm install @b9g/cache
 
 ## Quick Start
 
-```javascript
-import { CacheStorage, MemoryCache } from '@b9g/cache';
+### Using with Shovel (Recommended)
+
+Configure cache providers in via the `shovel` key in package.json or `shovel.json`:
+
+```json
+{
+  "caches": {
+    "pages": {"provider": "memory"},
+    "api": {"provider": "memory", "maxEntries": 5000}
+  }
+}
+```
 
-// Create cache storage
-const caches = new CacheStorage();
+Shovel provides `self.caches` as a global following the ServiceWorker CacheStorage API. Access it directly in your handlers and middleware:
 
-// Register cache implementations
-caches.register('api', () => new MemoryCache('api'));
-caches.register('pages', () => new MemoryCache('pages'));
+```typescript
+import {Router} from '@b9g/router';
+
+const router = new Router();
+
+// Cache middleware using generator API
+router.use(async function* (request, _context) {
+  if (request.method !== 'GET' || !self.caches) {
+    return yield request; // Skip caching
+  }
+
+  // Open cache
+  const cache = await self.caches.open('pages-v1');
+
+  // Check cache
+  const cached = await cache.match(request);
+  if (cached) {
+    return cached; // Cache hit
+  }
+
+  // Cache miss - get response from handler
+  const response = yield request;
+
+  // Store in cache
+  if (response.ok) {
+    await cache.put(request, response.clone());
+  }
+
+  return response;
+});
+
+router.route('/posts/:id')
+  .get(async (request, context) => {
+    const post = await getPost(context.params.id);
+    return Response.json(post, {
+      headers: {'Cache-Control': 'max-age=300'},
+    });
+  });
+```
+
+### Standalone Usage
+
+```javascript
+import {CustomCacheStorage} from '@b9g/cache';
+import {MemoryCache} from '@b9g/cache/memory';
+
+// Create cache storage with factory
+const caches = new CustomCacheStorage((name) => {
+  return new MemoryCache(name, {maxEntries: 1000});
+});
 
 // 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' }));
+const response = new Response(JSON.stringify({id: 1, title: 'Hello'}), {
+  headers: {
+    'Content-Type': 'application/json',
+    'Cache-Control': 'max-age=300',
+  }
+});
 await apiCache.put(request, response);
 
 // Retrieve response
 const cached = await apiCache.match(request);
-console.log(await cached.json()); // { id: 1, title: 'Hello' }
+console.log(await cached.json()); // {id: 1, title: 'Hello'}
 ```
 
-## Cache Implementations
+## Cache Providers
 
-### MemoryCache
+Shovel supports multiple cache providers that can be configured in `shovel.json`:
 
-In-memory cache with TTL and size limits:
+### Built-in Providers
 
-```javascript
-import { MemoryCache } from '@b9g/cache';
+- **`memory`** - In-memory cache with LRU eviction (default)
+- **`redis`** - Redis-backed cache (requires `@b9g/cache-redis`)
+- **`cloudflare`** - Uses Cloudflare Workers native Cache API (only works with the Cloudflare platform)
 
-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
-});
+You can also use custom providers by specifying a module path:
+
+```json
+{
+  "caches": {
+    "pages": {"provider": "memory"},
+    "sessions": {"provider": "redis", "url": "REDIS_URL"},
+    "custom": {"provider": "./my-cache-provider.js"}
+  }
+}
 ```
 
-### FilesystemCache
+Pattern matching is supported for cache names:
+
+```json
+{
+  "caches": {
+    "api-*": {"provider": "memory", "maxEntries": 5000},
+    "page-*": {"provider": "memory", "maxEntries": 100}
+  }
+}
+```
 
-File-based cache for SSG and persistent storage:
+## Cache Implementations
+
+### MemoryCache
+
+In-memory cache with LRU eviction and HTTP Cache-Control header support:
 
 ```javascript
-import { FilesystemCache } from '@b9g/cache';
+import {MemoryCache} from '@b9g/cache/memory';
 
-const cache = new FilesystemCache('pages', {
-  directory: './dist/cache',
-  compression: true,
-  indexing: true
+const cache = new MemoryCache(name, {
+  maxEntries: 1000,  // Maximum number of entries (LRU eviction)
 });
+
+// Cache respects Cache-Control headers
+await cache.put(request, new Response(data, {
+  headers: {'Cache-Control': 'max-age=300'},
+}));
+
+// After 300 seconds, match() returns undefined
 ```
 
-## CacheStorage Registry
+### PostMessageCache
+
+Worker-side cache that coordinates with main thread via PostMessage:
 
 ```javascript
-import { CacheStorage, MemoryCache, FilesystemCache } from '@b9g/cache';
+import {PostMessageCache} from '@b9g/cache/postmessage';
 
-const caches = new CacheStorage();
+// In worker thread - forwards operations to main thread
+const cache = new PostMessageCache({
+  name: 'shared',
+  timeout: 30000, // Optional, defaults to 30000ms
+});
 
-// Register different implementations
-caches.register('api', () => 
-  new MemoryCache('api', { ttl: 300 })
-);
+// Operations are synchronized with main thread's MemoryCache
+await cache.put(request, response);
+```
 
-caches.register('pages', () =>
-  new FilesystemCache('pages', { directory: './dist/pages' })
-);
+## CustomCacheStorage
 
-caches.register('assets', () =>
-  new MemoryCache('assets', { maxEntries: 10000 })
-);
+Create cache storage with a factory function:
+
+```javascript
+import {CustomCacheStorage} from '@b9g/cache';
+import {MemoryCache} from '@b9g/cache/memory';
 
-// Use with router
-import { Router } from '@b9g/router';
-const router = new Router({ caches });
+const caches = new CustomCacheStorage((name) => {
+  // Different caches can have different configurations
+  if (name === 'api') {
+    return new MemoryCache(name, {maxEntries: 5000});
+  }
+  if (name === 'pages') {
+    return new MemoryCache(name, {maxEntries: 100});
+  }
+  return new MemoryCache();
+});
 ```
 
 ## Exports
 
-### Classes
+### Main (`@b9g/cache`)
 
-- `Cache` - Abstract base class for cache implementations
-- `CustomCacheStorage` - CacheStorage implementation with factory registration
+- `Cache` - Abstract base class implementing `globalThis.Cache`
+- `CustomCacheStorage` - CacheStorage implementation with factory pattern
+- `generateCacheKey(request, options?)` - Generate cache key from Request
+- `toRequest(request)` - Convert RequestInfo or URL to Request
+- `CacheQueryOptions` - Type for cache query options
 
-### Functions
+### Memory (`@b9g/cache/memory`)
 
-- `generateCacheKey(request, options?)` - Generate a cache key from a Request
+- `MemoryCache` - In-memory cache with LRU and Cache-Control support
+- `MemoryCacheOptions` - Configuration type
 
-### Types
+### PostMessage (`@b9g/cache/postmessage`)
 
-- `CacheQueryOptions` - Options for cache query operations (ignoreSearch, ignoreMethod, ignoreVary)
-- `CacheFactory` - Factory function type `(name: string) => Cache | Promise<Cache>`
+- `PostMessageCache` - Worker-side cache with main thread coordination
+- `PostMessageCacheOptions` - Configuration type
+- `handleCacheResponse(message)` - Message handler for worker coordination
 
 ## API Reference
 
 ### Standard Cache Methods
 
+All cache implementations provide the standard Cache API:
+
 ```javascript
 // Check for cached response
 const response = await cache.match(request, options?);
@@ -140,10 +244,7 @@ const requests = await cache.keys(request?, options?);
 ### CacheStorage Methods
 
 ```javascript
-// Register cache factory
-caches.register(name, factory);
-
-// Open named cache
+// Open named cache (creates if doesn't exist)
 const cache = await caches.open(name);
 
 // Check if cache exists
@@ -154,6 +255,12 @@ const deleted = await caches.delete(name);
 
 // List cache names
 const names = await caches.keys();
+
+// Match across all caches
+const response = await caches.match(request, options?);
+
+// Cleanup (disposes all caches)
+await caches.dispose();
 ```
 
 ## Cache Options
@@ -162,29 +269,52 @@ const names = await caches.keys();
 
 ```javascript
 const response = await cache.match(request, {
-  ignoreSearch: true,     // Ignore query parameters
+  ignoreSearch: true,     // Ignore query parameters in URL
   ignoreMethod: false,    // Consider HTTP method
-  ignoreVary: false,      // Honor Vary header
-  cacheName: 'specific'   // Target specific cache
+  ignoreVary: false,      // Honor Vary header (default behavior)
 });
 ```
 
-### Storage Options
+**Vary Header Support:**
+
+The cache respects the HTTP `Vary` header by default:
 
 ```javascript
-// Memory cache options
-new MemoryCache('name', {
-  maxEntries: 1000,
-  ttl: 300,
-  maxSize: 50 * 1024 * 1024
-});
+// Cache a response that varies on Accept-Encoding
+await cache.put(
+  new Request('https://api.example.com/data', {
+    headers: {'Accept-Encoding': 'gzip'},
+  }),
+  new Response(gzippedData, {
+    headers: {'Vary': 'Accept-Encoding'},
+  })
+);
+
+// Same URL with same Accept-Encoding: matches
+await cache.match(new Request('https://api.example.com/data', {
+  headers: {'Accept-Encoding': 'gzip'},
+})); // ✓ Returns cached response
+
+// Same URL with different Accept-Encoding: no match
+await cache.match(new Request('https://api.example.com/data', {
+  headers: {'Accept-Encoding': 'br'},
+})); // ✗ Returns undefined
+
+// Use ignoreVary to bypass Vary header checking
+await cache.match(new Request('https://api.example.com/data', {
+  headers: {'Accept-Encoding': 'br'},
+}), {ignoreVary: true}); // ✓ Returns cached response
+```
 
-// Filesystem cache options
-new FilesystemCache('name', {
-  directory: './cache',
-  compression: true,
-  indexing: true,
-  fsync: false
+Special cases:
+- `Vary: *` means the response varies on everything and will never match (unless `ignoreVary: true`)
+- Multiple headers: `Vary: Accept-Encoding, User-Agent` requires all specified headers to match
+
+### MemoryCache Options
+
+```javascript
+new MemoryCache(name, {
+  maxEntries: 1000  // Maximum entries (LRU eviction when exceeded)
 });
 ```
 
@@ -193,99 +323,93 @@ new FilesystemCache('name', {
 ### With Router
 
 ```javascript
-import { Router } from '@b9g/router';
-import { CacheStorage, MemoryCache } from '@b9g/cache';
+import {Router} from '@b9g/router';
+import {CustomCacheStorage} from '@b9g/cache';
+import {MemoryCache} from '@b9g/cache/memory';
 
-const caches = new CacheStorage();
-caches.register('api', () => new MemoryCache('api'));
+const caches = new CustomCacheStorage((name) =>
+  new MemoryCache(name, {maxEntries: 1000})
+);
 
-const router = new Router({ caches });
+const router = new Router();
 
 // Cache-aware middleware
-router.use(async function* (request, context) {
-  if (request.method === 'GET' && context.cache) {
-    const cached = await context.cache.match(request);
-    if (cached) return cached;
+router.use(async function* (request, _context) {
+  if (request.method !== 'GET') {
+    return yield request;
   }
-  
+
+  const cache = await caches.open('api');
+  const cached = await cache.match(request);
+  if (cached) return cached;
+
   const response = yield request;
-  
-  if (request.method === 'GET' && context.cache && response.ok) {
-    await context.cache.put(request, response.clone());
+
+  if (response.ok) {
+    await cache.put(request, response.clone());
   }
-  
+
   return response;
 });
 
-router.route('/api/posts/:id', { cache: { name: 'api' } })
+router.route('/api/posts/:id')
   .get(postHandler);
 ```
 
-### Static Site Generation
+### Multi-Worker Setup
 
 ```javascript
-import { FilesystemCache } from '@b9g/cache';
+// Main thread
+import {CustomCacheStorage} from '@b9g/cache';
+import {MemoryCache} from '@b9g/cache/memory';
 
-const cache = new FilesystemCache('pages', {
-  directory: './dist'
+const caches = new CustomCacheStorage((name) =>
+  new MemoryCache()
+);
+
+worker.on('message', (message) => {
+  if (message.type?.startsWith('cache:')) {
+    caches.handleMessage(worker, message);
+  }
 });
 
-// Pre-populate cache at build time
-const paths = ['/about', '/contact', '/blog/post-1'];
+// Worker thread
+import {PostMessageCache} from '@b9g/cache/postmessage';
+import {handleCacheResponse} from '@b9g/cache/postmessage';
 
-for (const path of paths) {
-  const request = new Request(`https://example.com${path}`);
-  await cache.add(request); // Fetches through your router
-}
+const cache = new PostMessageCache('shared');
+
+self.addEventListener('message', (event) => {
+  if (event.data.type === 'cache:response' || event.data.type === 'cache:error') {
+    handleCacheResponse(event.data);
+  }
+});
 
-// At runtime, serve from cache
-const response = await cache.match(request);
+// Operations coordinate with main thread
+await cache.put(request, response);
 ```
 
-### Service Worker
+### HTTP Caching Semantics
 
 ```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
+import {MemoryCache} from '@b9g/cache/memory';
 
-For multi-worker setups, caches coordinate through PostMessage:
+const cache = new MemoryCache();
 
-```javascript
-// Worker thread cache coordination
-const cache = new MemoryCache('shared', {
-  coordination: {
-    type: 'postmessage',
-    channel: 'cache-coordination'
+// Respect Cache-Control headers
+const response = new Response(data, {
+  headers: {
+    'Cache-Control': 'max-age=3600',  // Cache for 1 hour
+    'Vary': 'Accept-Encoding',
   }
 });
 
-// Operations are coordinated across workers
-await cache.put(request, response); // Synced to all workers
+await cache.put(request, response);
+
+// After 3600 seconds, entry expires automatically
+const cached = await cache.match(request); // undefined after expiry
 ```
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/cache",
-  "version": "0.1.5",
+  "version": "0.2.0-beta.0",
   "description": "Universal Cache API for ServiceWorker applications. Provides standard CacheStorage and Cache interfaces across all JavaScript runtimes.",
   "keywords": [
     "cache",
@@ -9,14 +9,11 @@
     "cachestorage",
     "web-standards",
     "universal",
-    "memory",
-    "filesystem",
     "shovel"
   ],
   "dependencies": {},
   "devDependencies": {
-    "@b9g/libuild": "^0.1.18",
-    "bun-types": "latest"
+    "@b9g/libuild": "^0.1.18"
   },
   "type": "module",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -25,8 +25,11 @@ export declare function toRequest(request: RequestInfo | URL): Request;
  * Abstract Cache class implementing the Cache API interface
  * Provides shared implementations for add() and addAll() while requiring
  * concrete implementations to handle the core storage operations
+ *
+ * All cache implementations must follow the constructor signature:
+ * constructor(name: string, options?: CacheOptions)
  */
-export declare abstract class Cache {
+export declare abstract class Cache implements globalThis.Cache {
     /**
      * Returns a Promise that resolves to the response associated with the first matching request
      */
@@ -64,6 +67,11 @@ export declare abstract class Cache {
  * Normalizes the request for consistent cache key generation
  */
 export declare function generateCacheKey(request: RequestInfo | URL, options?: CacheQueryOptions): string;
+/**
+ * Constructor type for Cache implementations
+ * All cache classes must accept name as first parameter and optional options as second
+ */
+export type CacheConstructor<T extends Cache = Cache, O = any> = new (name: string, options?: O) => T;
 /**
  * Factory function for creating Cache instances based on cache name
  */
@@ -72,7 +80,7 @@ export type CacheFactory = (name: string) => Cache | Promise<Cache>;
  * CustomCacheStorage implements CacheStorage interface with a configurable factory
  * The factory function receives the cache name and can return different cache types
  */
-export declare class CustomCacheStorage {
+export declare class CustomCacheStorage implements CacheStorage {
     #private;
     constructor(factory: CacheFactory);
     /**
@@ -96,13 +104,6 @@ export declare class CustomCacheStorage {
      * Returns a list of all opened cache names
      */
     keys(): Promise<string[]>;
-    /**
-     * Get statistics about the cache storage
-     */
-    getStats(): {
-        openInstances: number;
-        cacheNames: string[];
-    };
     /**
      * Dispose of all cache instances
      * Calls dispose() on each cache if it exists (e.g., RedisCache needs to close connections)

package/src/index.js

@@ -110,15 +110,6 @@ var CustomCacheStorage = class {
   async keys() {
     return Array.from(this.#instances.keys());
   }
-  /**
-   * Get statistics about the cache storage
-   */
-  getStats() {
-    return {
-      openInstances: this.#instances.size,
-      cacheNames: Array.from(this.#instances.keys())
-    };
-  }
   /**
    * Dispose of all cache instances
    * Calls dispose() on each cache if it exists (e.g., RedisCache needs to close connections)
@@ -141,16 +132,23 @@ var CustomCacheStorage = class {
     try {
       const cache = await this.open(cacheName);
       let result;
+      const transfer = [];
       switch (type) {
         case "cache:match": {
           const req = new Request(message.request.url, message.request);
           const response = await cache.match(req, message.options);
-          result = response ? {
-            status: response.status,
-            statusText: response.statusText,
-            headers: Object.fromEntries(response.headers),
-            body: await response.text()
-          } : void 0;
+          if (response) {
+            const body = await response.arrayBuffer();
+            transfer.push(body);
+            result = {
+              status: response.status,
+              statusText: response.statusText,
+              headers: Object.fromEntries(response.headers),
+              body
+            };
+          } else {
+            result = void 0;
+          }
           break;
         }
         case "cache:put": {
@@ -180,7 +178,12 @@ var CustomCacheStorage = class {
           result = true;
           break;
       }
-      worker.postMessage({ type: "cache:response", requestID, result });
+      const responseMessage = { type: "cache:response", requestID, result };
+      if (transfer.length > 0) {
+        worker.postMessage(responseMessage, transfer);
+      } else {
+        worker.postMessage(responseMessage);
+      }
     } catch (error) {
       worker.postMessage({
         type: "cache:error",

package/src/memory.d.ts

@@ -9,10 +9,11 @@ export interface MemoryCacheOptions {
 /**
  * In-memory cache implementation using Map for storage
  * Supports LRU eviction and TTL expiration
+ * Uses Map's insertion order for LRU tracking
  */
 export declare class MemoryCache extends Cache {
     #private;
-    constructor(name: string, options?: MemoryCacheOptions);
+    constructor(_name: string, options?: MemoryCacheOptions);
     /**
      * Find a cached response for the given request
      */
@@ -33,13 +34,4 @@ export declare class MemoryCache extends Cache {
      * Clear all entries from the cache
      */
     clear(): Promise<void>;
-    /**
-     * Get cache statistics
-     */
-    getStats(): {
-        name: string;
-        size: number;
-        maxEntries: number;
-        hitRate: number;
-    };
 }

package/src/memory.js

@@ -7,33 +7,31 @@ import {
 } from "./index.js";
 var MemoryCache = class extends Cache {
   #storage;
-  #accessOrder;
-  #accessCounter;
-  #name;
   #options;
-  constructor(name, options = {}) {
+  constructor(_name, options = {}) {
     super();
     this.#storage = /* @__PURE__ */ new Map();
-    this.#accessOrder = /* @__PURE__ */ new Map();
-    this.#accessCounter = 0;
-    this.#name = name;
     this.#options = options;
   }
   /**
    * Find a cached response for the given request
    */
   async match(request, options) {
+    const req = toRequest(request);
     if (options?.ignoreSearch) {
       const filterKey = generateCacheKey(request, options);
       for (const [key2, entry2] of this.#storage) {
         if (this.#isExpired(entry2)) {
           this.#storage.delete(key2);
-          this.#accessOrder.delete(key2);
           continue;
         }
         const entryKey = generateCacheKey(entry2.request, options);
         if (entryKey === filterKey) {
-          this.#accessOrder.set(key2, ++this.#accessCounter);
+          if (!options?.ignoreVary && !this.#matchesVary(req, entry2)) {
+            continue;
+          }
+          this.#storage.delete(key2);
+          this.#storage.set(key2, entry2);
           return entry2.response.clone();
         }
       }
@@ -46,10 +44,13 @@ var MemoryCache = class extends Cache {
     }
     if (this.#isExpired(entry)) {
       this.#storage.delete(key);
-      this.#accessOrder.delete(key);
       return void 0;
     }
-    this.#accessOrder.set(key, ++this.#accessCounter);
+    if (!options?.ignoreVary && !this.#matchesVary(req, entry)) {
+      return void 0;
+    }
+    this.#storage.delete(key);
+    this.#storage.set(key, entry);
     return entry.response.clone();
   }
   /**
@@ -68,8 +69,10 @@ var MemoryCache = class extends Cache {
       response: clonedResponse,
       timestamp: Date.now()
     };
+    if (this.#storage.has(key)) {
+      this.#storage.delete(key);
+    }
     this.#storage.set(key, entry);
-    this.#accessOrder.set(key, ++this.#accessCounter);
     this.#enforceMaxEntries();
   }
   /**
@@ -78,23 +81,18 @@ var MemoryCache = class extends Cache {
   async delete(request, options) {
     if (options?.ignoreSearch) {
       const filterKey = generateCacheKey(request, options);
-      let deleted2 = false;
+      let deleted = false;
       for (const [key2, entry] of this.#storage) {
         const entryKey = generateCacheKey(entry.request, options);
         if (entryKey === filterKey) {
           this.#storage.delete(key2);
-          this.#accessOrder.delete(key2);
-          deleted2 = true;
+          deleted = true;
         }
       }
-      return deleted2;
+      return deleted;
     }
     const key = generateCacheKey(request, options);
-    const deleted = this.#storage.delete(key);
-    if (deleted) {
-      this.#accessOrder.delete(key);
-    }
-    return deleted;
+    return this.#storage.delete(key);
   }
   /**
    * Get all stored requests, optionally filtered by a request pattern
@@ -122,20 +120,6 @@ var MemoryCache = class extends Cache {
    */
   async clear() {
     this.#storage.clear();
-    this.#accessOrder.clear();
-    this.#accessCounter = 0;
-  }
-  /**
-   * Get cache statistics
-   */
-  getStats() {
-    return {
-      name: this.#name,
-      size: this.#storage.size,
-      maxEntries: this.#options.maxEntries,
-      hitRate: 0
-      // Could be implemented with additional tracking
-    };
   }
   /**
    * Check if a cache entry has expired based on Cache-Control header
@@ -152,21 +136,42 @@ var MemoryCache = class extends Cache {
     const maxAge = parseInt(maxAgeMatch[1], 10) * 1e3;
     return Date.now() - entry.timestamp > maxAge;
   }
+  /**
+   * Check if a request matches the Vary header of a cached entry
+   * Returns true if the request matches or if there's no Vary header
+   */
+  #matchesVary(request, entry) {
+    const varyHeader = entry.response.headers.get("vary");
+    if (!varyHeader) {
+      return true;
+    }
+    if (varyHeader === "*") {
+      return false;
+    }
+    const varyHeaders = varyHeader.split(",").map((h) => h.trim().toLowerCase());
+    for (const headerName of varyHeaders) {
+      const requestValue = request.headers.get(headerName);
+      const cachedValue = entry.request.headers.get(headerName);
+      if (requestValue !== cachedValue) {
+        return false;
+      }
+    }
+    return true;
+  }
   /**
    * Enforce maximum entry limits using LRU eviction
+   * Removes oldest entries (first in Map iteration order)
    */
   #enforceMaxEntries() {
     if (!this.#options.maxEntries || this.#storage.size <= this.#options.maxEntries) {
       return;
     }
-    const entries = Array.from(this.#accessOrder.entries()).sort(
-      (a, b) => a[1] - b[1]
-    );
     const toRemove = this.#storage.size - this.#options.maxEntries;
-    for (let i = 0; i < toRemove; i++) {
-      const [key] = entries[i];
+    let removed = 0;
+    for (const key of this.#storage.keys()) {
+      if (removed >= toRemove) break;
       this.#storage.delete(key);
-      this.#accessOrder.delete(key);
+      removed++;
     }
   }
 };

package/src/postmessage.d.ts

@@ -1,4 +1,9 @@
 import { Cache, type CacheQueryOptions } from "./index.js";
+/**
+ * Handle cache response/error messages from main thread.
+ * Called by worker.ts when receiving cache:response or cache:error messages.
+ */
+export declare function handleCacheResponse(message: any): void;
 /**
  * Configuration options for PostMessageCache
  */
@@ -7,8 +12,8 @@ export interface PostMessageCacheOptions {
     timeout?: number;
 }
 /**
- * Worker-side cache that forwards operations to main thread via postMessage
- * Only used for MemoryCache in multi-worker environments
+ * Worker-side cache that forwards operations to main thread via postMessage.
+ * Used for MemoryCache in multi-worker environments so all workers share state.
  */
 export declare class PostMessageCache extends Cache {
     #private;

package/src/postmessage.js

@@ -1,25 +1,7 @@
 /// <reference types="./postmessage.d.ts" />
 // src/postmessage.ts
 import { Cache } from "./index.js";
-function getParentPort() {
-  return typeof self !== "undefined" ? self : null;
-}
-var messageHandlerSetup = false;
 var pendingRequestsRegistry = /* @__PURE__ */ new Map();
-function setupMessageHandler() {
-  if (messageHandlerSetup)
-    return;
-  messageHandlerSetup = true;
-  const parentPort = getParentPort();
-  if (parentPort && parentPort.addEventListener) {
-    parentPort.addEventListener("message", (event) => {
-      const message = event.data;
-      if (message.type === "cache:response" || message.type === "cache:error") {
-        handleCacheResponse(message);
-      }
-    });
-  }
-}
 function handleCacheResponse(message) {
   const pending = pendingRequestsRegistry.get(message.requestID);
   if (pending) {
@@ -39,22 +21,30 @@ var PostMessageCache = class extends Cache {
     super();
     this.#name = name;
     this.#timeout = options.timeout ?? 3e4;
-    setupMessageHandler();
   }
-  async #sendRequest(type, data) {
-    const parentPort = getParentPort();
-    if (!parentPort) {
+  async #sendRequest(type, data, transfer) {
+    if (typeof self === "undefined") {
       throw new Error("PostMessageCache can only be used in worker threads");
     }
+    if (globalRequestID >= Number.MAX_SAFE_INTEGER) {
+      throw new Error(
+        "Congratulations! You've made 9 quadrillion cache requests. Please restart your server and tell us about your workload."
+      );
+    }
     const requestID = ++globalRequestID;
     return new Promise((resolve, reject) => {
       pendingRequestsRegistry.set(requestID, { resolve, reject });
-      parentPort.postMessage({
+      const message = {
         type,
         requestID,
         cacheName: this.#name,
         ...data
-      });
+      };
+      if (transfer && transfer.length > 0) {
+        self.postMessage(message, transfer);
+      } else {
+        self.postMessage(message);
+      }
       setTimeout(() => {
         if (pendingRequestsRegistry.has(requestID)) {
           pendingRequestsRegistry.delete(requestID);
@@ -64,16 +54,26 @@ var PostMessageCache = class extends Cache {
     });
   }
   async match(request, options) {
+    let requestBody;
+    const transfer = [];
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      requestBody = await request.arrayBuffer();
+      transfer.push(requestBody);
+    }
     const serializedRequest = {
       url: request.url,
       method: request.method,
       headers: Object.fromEntries(request.headers),
-      body: request.method !== "GET" && request.method !== "HEAD" ? await request.text() : void 0
+      body: requestBody
     };
-    const response = await this.#sendRequest("cache:match", {
-      request: serializedRequest,
-      options
-    });
+    const response = await this.#sendRequest(
+      "cache:match",
+      {
+        request: serializedRequest,
+        options
+      },
+      transfer
+    );
     if (!response) {
       return void 0;
     }
@@ -84,49 +84,82 @@ var PostMessageCache = class extends Cache {
     });
   }
   async put(request, response) {
+    const transfer = [];
+    let requestBody;
+    let responseBody;
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      requestBody = await request.clone().arrayBuffer();
+      transfer.push(requestBody);
+    }
+    responseBody = await response.clone().arrayBuffer();
+    transfer.push(responseBody);
     const serializedRequest = {
       url: request.url,
       method: request.method,
       headers: Object.fromEntries(request.headers),
-      body: request.method !== "GET" && request.method !== "HEAD" ? await request.clone().text() : void 0
+      body: requestBody
     };
     const serializedResponse = {
       status: response.status,
       statusText: response.statusText,
       headers: Object.fromEntries(response.headers),
-      body: await response.clone().text()
+      body: responseBody
     };
-    await this.#sendRequest("cache:put", {
-      request: serializedRequest,
-      response: serializedResponse
-    });
+    await this.#sendRequest(
+      "cache:put",
+      {
+        request: serializedRequest,
+        response: serializedResponse
+      },
+      transfer
+    );
   }
   async delete(request, options) {
+    let requestBody;
+    const transfer = [];
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      requestBody = await request.arrayBuffer();
+      transfer.push(requestBody);
+    }
     const serializedRequest = {
       url: request.url,
       method: request.method,
       headers: Object.fromEntries(request.headers),
-      body: request.method !== "GET" && request.method !== "HEAD" ? await request.text() : void 0
+      body: requestBody
     };
-    return await this.#sendRequest("cache:delete", {
-      request: serializedRequest,
-      options
-    });
+    return await this.#sendRequest(
+      "cache:delete",
+      {
+        request: serializedRequest,
+        options
+      },
+      transfer
+    );
   }
   async keys(request, options) {
     let serializedRequest;
+    const transfer = [];
     if (request) {
+      let requestBody;
+      if (request.method !== "GET" && request.method !== "HEAD") {
+        requestBody = await request.arrayBuffer();
+        transfer.push(requestBody);
+      }
       serializedRequest = {
         url: request.url,
         method: request.method,
         headers: Object.fromEntries(request.headers),
-        body: request.method !== "GET" && request.method !== "HEAD" ? await request.text() : void 0
+        body: requestBody
       };
     }
-    const keys = await this.#sendRequest("cache:keys", {
-      request: serializedRequest,
-      options
-    });
+    const keys = await this.#sendRequest(
+      "cache:keys",
+      {
+        request: serializedRequest,
+        options
+      },
+      transfer
+    );
     return keys.map(
       (req) => new Request(req.url, {
         method: req.method,
@@ -140,5 +173,6 @@ var PostMessageCache = class extends Cache {
   }
 };
 export {
-  PostMessageCache
+  PostMessageCache,
+  handleCacheResponse
 };