SharedCache

A standards-compliant HTTP cache implementation for server-side applications.

SharedCache is an HTTP caching library that follows Web Standards and HTTP specifications. It implements a cache interface similar to the Web Cache API but optimized for server-side shared caching scenarios.

📋 Table of Contents

• ✨ Key Features
• 🤔 Why SharedCache?
• ⚡ Quick Decision Guide
• 📦 Installation
• 🚀 Quick Start
• 📋 Standards Compliance
• ☁️ Cloudflare Comparison
• 📖 Documentation
• 🤝 Who's Using SharedCache
• 🙏 Acknowledgments
• 📄 License

✨ Key Features

• 📋 RFC Compliance: Supports RFC 5861 directives like stale-if-error and stale-while-revalidate
• 🎯 Smart Caching: Handles complex HTTP scenarios including Vary headers, proxy revalidation, and authenticated responses
• 🔧 Flexible Storage: Pluggable storage backend supporting memory, Redis, or any custom key-value store
• 🚀 Enhanced Fetch: Extends the standard fetch API with caching capabilities while maintaining full compatibility
• 🔌 Middleware Origin: createCacheHandler for in-process handlers (e.g. middleware next())
• 🎛️ Custom Cache Keys: Cache key customization supporting device types, cookies, headers, and URL components
• ⚡ Shared Cache Optimization: Prioritizes s-maxage over max-age for shared cache performance
• 🌍 Universal Runtime: Compatible with WinterCG environments including Node.js, Deno, Bun, and Edge Runtime

🤔 Why SharedCache?

While the Web fetch API has become ubiquitous in server-side JavaScript, existing browser Cache APIs are designed for single-user scenarios. Server-side applications need shared caches that serve multiple users efficiently.

SharedCache provides:

• Server-Optimized Caching: Designed for multi-user server environments
• Standards Compliance: Follows HTTP specifications and server-specific patterns
• Production Ready: Battle-tested patterns from CDN and proxy implementations

⚡ Quick Decision Guide

✅ Use SharedCache When:

• Node.js environments - Native caches API not available
• API response caching - Need to reduce backend load and improve response times
• Cross-runtime portability - Want consistent caching across Node.js, Deno, Bun
• Custom storage backends - Need Redis, database, or distributed caching solutions
• Meta-framework development - Building applications that deploy to multiple environments

❌ Don't Use SharedCache When:

• Edge runtimes with native caches - Cloudflare Workers, Vercel Edge already provide caches API
• Browser applications - Use the native Web Cache API instead (unless you need HTTP cache control directives support)
• Simple in-memory caching - Consider lighter alternatives like lru-cache directly
• Single-request caching - Basic memoization might be sufficient

📦 Installation

npm install @web-widget/shared-cache

# Using yarn
yarn add @web-widget/shared-cache

# Using pnpm
pnpm add @web-widget/shared-cache

🚀 Quick Start

import {
  CacheStorage,
  createFetch,
  type KVStorage,
} from '@web-widget/shared-cache';
import { LRUCache } from 'lru-cache';

const createLRUCache = (): KVStorage => {
  const store = new LRUCache<string, any>({ max: 1024 });

  return {
    async get(cacheKey: string) {
      return store.get(cacheKey);
    },
    async set(cacheKey: string, value: any, ttl?: number) {
      store.set(cacheKey, value, { ttl });
    },
    async delete(cacheKey: string) {
      return store.delete(cacheKey);
    },
  };
};

const caches = new CacheStorage(createLRUCache());

async function example() {
  const cache = await caches.open('api-cache-v1');

  const fetch = createFetch(cache, {
    defaults: {
      cacheControlOverride: 's-maxage=300',
      ignoreRequestCacheControl: true,
    },
  });

  const response1 = await fetch(
    'https://httpbin.org/response-headers?cache-control=max-age%3D604800'
  ); // First request: network

  const response2 = await fetch(
    'https://httpbin.org/response-headers?cache-control=max-age%3D604800'
  ); // Second request: cache

  console.log(response2.headers.get('x-cache-status')); // "HIT"
}

example();

Core APIs

| Export | Purpose | | ------------------------ | ------------------------------------ | | createFetch | Outbound HTTP fetch with caching | | createCacheHandler | In-process origin (middleware / SSR) | | CacheStorage / Cache | Cache storage and operations | | KVStorage | Pluggable storage backend interface |

Every response includes an x-cache-status header (HIT, MISS, UPDATING, STALE, …) for debugging. See the configuration guide for the full status table.

📋 Standards Compliance

SharedCache is built for production HTTP caching with full adherence to web standards:

| Standard | Status | Coverage | | ----------------------------------------------------------------------- | ------------------ | --------------------------------------- | | RFC 7234 (HTTP Caching) | ✅ Fully Compliant | 100% | | RFC 5861 (stale-* extensions) | ✅ Fully Compliant | 100% | | Web Cache API | ✅ Subset | Core methods (match, put, delete) | | WinterCG | ✅ Fully Supported | 100% |

Highlights:

• RFC 7234: Cache-Control directives, GET/HEAD caching, Vary processing, conditional requests
• RFC 5861: stale-while-revalidate and stale-if-error via createFetch
• Web Cache API: Core methods with HTTP semantics; match() / delete() support ignoreMethod (same subset as Cloudflare Workers Cache API)
• Security: Requests with Authorization headers are not cached unless the response explicitly allows it (public, s-maxage, etc.)

Powered by http-cache-semantics for RFC-compliant cache policy evaluation.

→ Full standards compliance guide — Web Cache API details, security notes, and implementation status.

☁️ Cloudflare Comparison

SharedCache is designed for origin-side caching (application servers with pluggable KVStorage such as Redis or S3), not as a replacement for Cloudflare's global edge cache. Where it helps to align with Cloudflare semantics, the library mirrors familiar patterns from the CDN and Workers Cache API:

• Cache Key — public cacheKeyRules (search, header, cookie, device) vs Cloudflare Cache Rules
• Cache Status — x-cache-status (HIT, MISS, UPDATING, STALE, …) vs CF-Cache-Status
• Workers Cache API — match() / delete() with ignoreMethod only; no ignoreSearch / ignoreVary
• Storage — KVStorage at the origin vs platform-managed edge / Workers cache

→ Full comparison guide — quick reference table and detailed notes.

📖 Documentation

| Guide | Description | | ------------------------------------------------------------ | -------------------------------------------------------------------- | | Examples | Redis, multi-tenant, authentication, and custom storage patterns | | Configuration | Global setup, sharedCache options, cache key rules, and monitoring | | API Reference | Complete API signatures and type definitions | | Logging | Logger setup, log levels, and debugging techniques | | FAQ | Storage backends, edge runtimes, Vary performance, and more | | Standards Compliance | RFC details, Web Cache API subset, and security notes | | Cloudflare Comparison | Mapping to Cloudflare Cache Rules and Workers Cache API |

🤝 Who's Using SharedCache

• Web Widget Meta Framework: Cache middleware
• InsMind.com: Page Cache
• Gaoding.com: Page Cache (Million-level URLs)

🙏 Acknowledgments

SharedCache draws inspiration from industry-leading caching implementations:

• Cloudflare Cache Key - Cache key customization patterns
• Next.js Data Cache - Server-side caching strategies
• nodejs/undici - Web Standards implementation
• http-cache-lru - HTTP cache semantics
• Cloudflare Miniflare - Edge runtime patterns
• Cloudflare Workers SDK - Worker environment optimizations
• ultrafetch - Fetch API extensions
• island.is Cache Middleware - Production caching patterns
• make-fetch-happen - HTTP caching with retry and offline support

📄 License

MIT License - see LICENSE file for details.