@suman-malik-repo/snapcache 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ogensync
+
+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,131 @@
+# SnapCache
+
+> The simplest production-grade HTTP-native smart caching layer.
+
+**IndexedDB + ETag validation** — instant API performance, zero complexity.
+
+[![npm](https://img.shields.io/npm/v/@ogensync/snapcache)](https://www.npmjs.com/package/@ogensync/snapcache)
+[![license](https://img.shields.io/npm/l/@ogensync/snapcache)](./LICENSE)
+
+---
+
+## Features
+
+- ⚡ **IndexedDB Caching** — Persistent browser-side cache
+- 🔑 **ETag Validation** — `If-None-Match` / `If-Modified-Since` / 304 support
+- 🔄 **Stale-While-Revalidate** — Return stale instant, update in background
+- ⏱️ **TTL Fallback** — Per-route TTL with `ttlMap`
+- 📡 **Multi-Tab Sync** — BroadcastChannel keeps tabs consistent
+- ⚙️ **Service Worker** — Optional offline support
+- 🌍 **Fetch Override** — Transparent `window.fetch` replacement
+- 🔌 **Axios Support** — Drop-in interceptor
+- 📦 **Cache Size Limits** — LRU eviction, no memory leaks
+- 🚫 **No Auth Required** — No API key, no signup
+
+## Installation
+
+```bash
+npm install @ogensync/snapcache
+```
+
+## Client Usage
+
+```javascript
+import SnapCache from "@ogensync/snapcache";
+
+await SnapCache.init({
+  ttl: 300,                    // Cache for 5 minutes
+  staleWhileRevalidate: true,  // Return stale, update in background
+  fetchOverride: true           // Replace window.fetch globally
+});
+
+// All fetch() calls are now cached automatically!
+const res = await fetch("/api/products");
+const data = await res.json();
+```
+
+### CDN Alternative
+
+```html
+<script src="https://snapcache.ogensync.com/snapcache.min.js"></script>
+<script>
+  SnapCache.init({ ttl: 300, fetchOverride: true });
+</script>
+```
+
+### Manual Fetch
+
+```javascript
+const res = await SnapCache.fetch("/api/users");
+const data = await res.json();
+```
+
+### Axios Integration
+
+```javascript
+import axios from "axios";
+SnapCache.attachAxios(axios);
+```
+
+## Server Middleware (Express)
+
+```javascript
+const { SnapCacheMiddleware } = require("@ogensync/snapcache/server");
+
+// Global — auto-adds ETag to all res.json() calls
+app.use(SnapCacheMiddleware());
+```
+
+```javascript
+// Or per-route
+const { sendWithETag } = require("@ogensync/snapcache/server");
+
+app.get("/api/users", (req, res) => {
+  const data = getUsers();
+  sendWithETag(req, res, data);
+});
+```
+
+## Configuration
+
+```javascript
+SnapCache.init({
+  ttl: 300,                       // Default TTL (seconds)
+  ttlMap: {
+    "/api/products": 600,         // 10 min for products
+    "/api/orders": 30             // 30 sec for orders
+  },
+  exclude: [/auth/, /payment/],   // Never cache these
+  maxSize: 50,                    // Max cache size (MB)
+  backgroundSync: true,           // Background revalidation
+  staleWhileRevalidate: true,     // SWR strategy
+  serviceWorker: false,           // Offline support
+  broadcastChannel: true,         // Multi-tab sync
+  fetchOverride: false,           // Replace window.fetch
+  debug: false                    // Console logging
+});
+```
+
+## Events
+
+```javascript
+SnapCache.on("cache-hit", (e) => console.log("Hit:", e.url));
+SnapCache.on("fetched", (e) => console.log("API:", e.url));
+SnapCache.on("revalidated", (e) => console.log("304:", e.url));
+SnapCache.on("cache-updated", (e) => console.log("Updated:", e.url));
+SnapCache.on("network-error", (e) => console.log("Error:", e.url));
+```
+
+## How It Works
+
+```
+1st request:  Client → API → Response + ETag → Stored in IndexedDB
+2nd request:  Client → IndexedDB (instant) → If-None-Match → 304
+Data changed: Client → IndexedDB (stale) → If-None-Match → 200 → Cache updated
+```
+
+No WebSockets. No persistent connections. Stateless HTTP. Horizontally scalable.
+
+## License
+
+MIT © [ogensync](https://ogensync.com)

package/client/index.js

@@ -0,0 +1,536 @@
+/**
+ * SnapCache — Universal Browser-Side Intelligent Caching Layer
+ * @version 1.0.0
+ * @license MIT
+ * @see https://snapcache.ogensync.com
+ * 
+ * Features:
+ *  - IndexedDB persistent caching
+ *  - ETag / If-None-Match / If-Modified-Since validation
+ *  - Stale-While-Revalidate
+ *  - TTL fallback with per-route ttlMap
+ *  - Route exclusion (regex)
+ *  - Cache size limits with LRU eviction
+ *  - Multi-tab sync via BroadcastChannel
+ *  - Service Worker upgrade
+ *  - Global fetch override
+ *  - Axios interceptor support
+ *  - Event system for analytics/logging
+ */
+
+// ─── IndexedDB Store ──────────────────────────────────────────────────────────
+
+class IndexedDBStore {
+    constructor(dbName = 'snapcache-db', storeName = 'responses') {
+        this.dbName = dbName;
+        this.storeName = storeName;
+        this._db = null;
+    }
+
+    open() {
+        return new Promise((resolve, reject) => {
+            if (this._db) return resolve(this._db);
+            const req = indexedDB.open(this.dbName, 1);
+            req.onupgradeneeded = (e) => {
+                const db = e.target.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    db.createObjectStore(this.storeName, { keyPath: 'url' });
+                }
+            };
+            req.onsuccess = (e) => {
+                this._db = e.target.result;
+                resolve(this._db);
+            };
+            req.onerror = (e) => reject(e.target.error);
+        });
+    }
+
+    async _tx(mode) {
+        const db = await this.open();
+        const tx = db.transaction(this.storeName, mode);
+        return tx.objectStore(this.storeName);
+    }
+
+    get(url) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                const store = await this._tx('readonly');
+                const req = store.get(url);
+                req.onsuccess = () => resolve(req.result || null);
+                req.onerror = (e) => reject(e.target.error);
+            } catch (err) { reject(err); }
+        });
+    }
+
+    set(entry) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                const store = await this._tx('readwrite');
+                const req = store.put(entry);
+                req.onsuccess = () => resolve();
+                req.onerror = (e) => reject(e.target.error);
+            } catch (err) { reject(err); }
+        });
+    }
+
+    delete(url) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                const store = await this._tx('readwrite');
+                const req = store.delete(url);
+                req.onsuccess = () => resolve();
+                req.onerror = (e) => reject(e.target.error);
+            } catch (err) { reject(err); }
+        });
+    }
+
+    getAll() {
+        return new Promise(async (resolve, reject) => {
+            try {
+                const store = await this._tx('readonly');
+                const req = store.getAll();
+                req.onsuccess = () => resolve(req.result || []);
+                req.onerror = (e) => reject(e.target.error);
+            } catch (err) { reject(err); }
+        });
+    }
+
+    clear() {
+        return new Promise(async (resolve, reject) => {
+            try {
+                const store = await this._tx('readwrite');
+                const req = store.clear();
+                req.onsuccess = () => resolve();
+                req.onerror = (e) => reject(e.target.error);
+            } catch (err) { reject(err); }
+        });
+    }
+
+    async getSize() {
+        const all = await this.getAll();
+        let bytes = 0;
+        for (const entry of all) {
+            bytes += new Blob([JSON.stringify(entry)]).size;
+        }
+        return bytes;
+    }
+}
+
+// ─── SnapCache Core ───────────────────────────────────────────────────────────
+
+class SnapCacheCore {
+    constructor() {
+        this._config = null;
+        this._store = null;
+        this._channel = null;
+        this._originalFetch = null;
+        this._listeners = [];
+        this._initialized = false;
+    }
+
+    /**
+     * Initialize SnapCache with configuration
+     * @param {Object} config
+     * @param {number}  config.ttl                   - Default cache TTL in seconds (default: 300)
+     * @param {Object}  config.ttlMap                - Per-route TTL overrides, e.g. { "/products": 600 }
+     * @param {Array}   config.exclude               - RegExp or string patterns to skip caching
+     * @param {number}  config.maxSize               - Max cache size in MB (default: 50)
+     * @param {boolean} config.backgroundSync        - Enable background revalidation (default: true)
+     * @param {boolean} config.staleWhileRevalidate  - Return stale then update (default: true)
+     * @param {boolean} config.serviceWorker         - Register service worker (default: false)
+     * @param {boolean} config.broadcastChannel      - Multi-tab sync (default: true)
+     * @param {boolean} config.fetchOverride         - Override window.fetch (default: false)
+     * @param {boolean} config.debug                 - Console logging (default: false)
+     */
+    async init(config = {}) {
+        this._config = {
+            ttl: 300,
+            ttlMap: {},
+            exclude: [],
+            maxSize: 50,
+            backgroundSync: true,
+            staleWhileRevalidate: true,
+            serviceWorker: false,
+            broadcastChannel: true,
+            fetchOverride: false,
+            debug: false,
+            ...config
+        };
+
+        this._store = new IndexedDBStore();
+        await this._store.open();
+
+        // BroadcastChannel for multi-tab sync
+        if (this._config.broadcastChannel && typeof BroadcastChannel !== 'undefined') {
+            this._channel = new BroadcastChannel('snapcache-sync');
+            this._channel.onmessage = (e) => this._handleBroadcast(e.data);
+        }
+
+        if (this._config.serviceWorker) {
+            this.enableServiceWorker();
+        }
+
+        if (this._config.fetchOverride) {
+            this.enableGlobalFetch();
+        }
+
+        this._initialized = true;
+        this._log('SnapCache initialized', this._config);
+        return this;
+    }
+
+    /**
+     * Fetch a URL with SnapCache caching
+     * @param {string} url - The URL to fetch
+     * @param {Object} options - Fetch options
+     * @returns {Promise<Response>}
+     */
+    async fetch(url, options = {}) {
+        if (!this._initialized) {
+            console.warn('[SnapCache] Not initialized. Call SnapCache.init() first.');
+            return window.fetch(url, options);
+        }
+
+        const normalizedUrl = this._normalizeUrl(url);
+
+        if (this._isExcluded(normalizedUrl)) {
+            this._log(`Excluded: ${normalizedUrl}`);
+            return window.fetch(url, options);
+        }
+
+        const cached = await this._store.get(normalizedUrl);
+        const ttl = this._getTTL(normalizedUrl);
+
+        // Cache HIT — within TTL
+        if (cached && !this._isExpired(cached, ttl)) {
+            this._emit('cache-hit', { url: normalizedUrl, source: 'indexeddb' });
+            this._log(`Cache HIT (IndexedDB): ${normalizedUrl}`);
+
+            if (this._config.staleWhileRevalidate && this._config.backgroundSync) {
+                this._revalidateInBackground(normalizedUrl, cached, options);
+            }
+
+            return this._createResponse(cached);
+        }
+
+        // Cache STALE — conditional request
+        if (cached) {
+            this._log(`Cache STALE — validating: ${normalizedUrl}`);
+            return this._conditionalFetch(normalizedUrl, cached, options);
+        }
+
+        // Cache MISS — fresh fetch
+        this._log(`Cache MISS — fetching: ${normalizedUrl}`);
+        return this._freshFetch(normalizedUrl, options);
+    }
+
+    // ── Conditional Fetch (ETag / Last-Modified) ─────────────────────────────
+
+    async _conditionalFetch(url, cached, options = {}) {
+        const headers = new Headers(options.headers || {});
+        if (cached.etag) headers.set('If-None-Match', cached.etag);
+        if (cached.lastModified) headers.set('If-Modified-Since', cached.lastModified);
+
+        try {
+            const nativeFetch = this._originalFetch || window.fetch.bind(window);
+            const response = await nativeFetch(url, { ...options, headers });
+
+            if (response.status === 304) {
+                this._emit('revalidated', { url, status: 304 });
+                this._log(`304 Not Modified: ${url}`);
+                cached.timestamp = Date.now();
+                await this._store.set(cached);
+                this._broadcast({ type: 'update', url, entry: cached });
+                return this._createResponse(cached);
+            }
+
+            const data = await response.json();
+            const entry = {
+                url,
+                data,
+                etag: response.headers.get('ETag') || null,
+                lastModified: response.headers.get('Last-Modified') || null,
+                timestamp: Date.now()
+            };
+
+            await this._store.set(entry);
+            await this._evictIfNeeded();
+            this._broadcast({ type: 'update', url, entry });
+            this._emit('cache-updated', { url, source: 'network' });
+            this._log(`Cache UPDATED: ${url}`);
+
+            return this._createResponse(entry);
+        } catch (err) {
+            this._log(`Network error, returning stale: ${url}`);
+            this._emit('network-error', { url, error: err });
+            return this._createResponse(cached);
+        }
+    }
+
+    // ── Fresh Fetch ───────────────────────────────────────────────────────────
+
+    async _freshFetch(url, options = {}) {
+        const nativeFetch = this._originalFetch || window.fetch.bind(window);
+        const response = await nativeFetch(url, options);
+        const data = await response.json();
+
+        const entry = {
+            url,
+            data,
+            etag: response.headers.get('ETag') || null,
+            lastModified: response.headers.get('Last-Modified') || null,
+            timestamp: Date.now()
+        };
+
+        await this._store.set(entry);
+        await this._evictIfNeeded();
+        this._broadcast({ type: 'update', url, entry });
+        this._emit('fetched', { url, source: 'api' });
+        this._log(`Fetched from API: ${url}`);
+
+        return this._createResponse(entry);
+    }
+
+    // ── Background Revalidation (SWR) ────────────────────────────────────────
+
+    _revalidateInBackground(url, cached, options) {
+        setTimeout(async () => {
+            try {
+                await this._conditionalFetch(url, cached, options);
+                this._log(`Background revalidation complete: ${url}`);
+            } catch (err) {
+                this._log(`Background revalidation failed: ${url}`, err);
+            }
+        }, 0);
+    }
+
+    /**
+     * Override window.fetch globally — all GET requests go through SnapCache
+     */
+    enableGlobalFetch() {
+        if (this._originalFetch) return;
+        this._originalFetch = window.fetch.bind(window);
+        const self = this;
+        window.fetch = function (url, options) {
+            if (typeof url === 'string' && (!options || !options.method || options.method === 'GET')) {
+                return self.fetch(url, options);
+            }
+            return self._originalFetch(url, options);
+        };
+        this._log('Global fetch override enabled');
+    }
+
+    /**
+     * Restore the original window.fetch
+     */
+    disableGlobalFetch() {
+        if (this._originalFetch) {
+            window.fetch = this._originalFetch;
+            this._originalFetch = null;
+            this._log('Global fetch override disabled');
+        }
+    }
+
+    /**
+     * Attach SnapCache interceptors to an Axios instance
+     * @param {Object} axiosInstance
+     */
+    attachAxios(axiosInstance) {
+        const self = this;
+        axiosInstance.interceptors.request.use(async (config) => {
+            if (config.method === 'get') {
+                const url = self._normalizeUrl(config.url);
+                if (!self._isExcluded(url)) {
+                    const cached = await self._store.get(url);
+                    if (cached) {
+                        if (cached.etag) config.headers['If-None-Match'] = cached.etag;
+                        if (cached.lastModified) config.headers['If-Modified-Since'] = cached.lastModified;
+                        config._snapcacheCached = cached;
+                    }
+                }
+            }
+            return config;
+        });
+
+        axiosInstance.interceptors.response.use(async (response) => {
+            const url = self._normalizeUrl(response.config.url);
+            if (response.config.method === 'get' && !self._isExcluded(url)) {
+                if (response.status === 304 && response.config._snapcacheCached) {
+                    response.data = response.config._snapcacheCached.data;
+                    response.config._snapcacheCached.timestamp = Date.now();
+                    await self._store.set(response.config._snapcacheCached);
+                } else {
+                    const entry = {
+                        url,
+                        data: response.data,
+                        etag: response.headers['etag'] || null,
+                        lastModified: response.headers['last-modified'] || null,
+                        timestamp: Date.now()
+                    };
+                    await self._store.set(entry);
+                    await self._evictIfNeeded();
+                }
+            }
+            return response;
+        });
+
+        this._log('Axios interceptor attached');
+    }
+
+    /**
+     * Register the SnapCache service worker for offline support
+     */
+    async enableServiceWorker() {
+        if ('serviceWorker' in navigator) {
+            try {
+                const reg = await navigator.serviceWorker.register('/js/snapcache-sw.js');
+                this._log('Service Worker registered', reg.scope);
+            } catch (err) {
+                this._log('Service Worker registration failed', err);
+            }
+        }
+    }
+
+    // ── BroadcastChannel Sync ────────────────────────────────────────────────
+
+    _broadcast(message) {
+        if (this._channel) {
+            this._channel.postMessage(message);
+        }
+    }
+
+    async _handleBroadcast(data) {
+        if (data.type === 'update' && data.entry) {
+            await this._store.set(data.entry);
+            this._emit('tab-sync', { url: data.url });
+            this._log(`Tab sync received: ${data.url}`);
+        } else if (data.type === 'clear') {
+            await this._store.clear();
+            this._emit('cache-cleared', { source: 'tab-sync' });
+            this._log('Cache cleared via tab sync');
+        }
+    }
+
+    // ── Cache Management ──────────────────────────────────────────────────────
+
+    /**
+     * Clear all cached entries
+     */
+    async clearCache() {
+        await this._store.clear();
+        this._broadcast({ type: 'clear' });
+        this._emit('cache-cleared', { source: 'manual' });
+        this._log('Cache cleared');
+    }
+
+    /**
+     * Get current cache size in MB
+     * @returns {Promise<string>}
+     */
+    async getCacheSize() {
+        const bytes = await this._store.getSize();
+        return (bytes / (1024 * 1024)).toFixed(2);
+    }
+
+    async _evictIfNeeded() {
+        const maxBytes = this._config.maxSize * 1024 * 1024;
+        const currentBytes = await this._store.getSize();
+        if (currentBytes <= maxBytes) return;
+
+        const all = await this._store.getAll();
+        all.sort((a, b) => a.timestamp - b.timestamp);
+
+        let freed = 0;
+        for (const entry of all) {
+            if (currentBytes - freed <= maxBytes) break;
+            freed += new Blob([JSON.stringify(entry)]).size;
+            await this._store.delete(entry.url);
+            this._log(`Evicted: ${entry.url}`);
+        }
+    }
+
+    // ── Event System ──────────────────────────────────────────────────────────
+
+    /**
+     * Listen to a SnapCache event
+     * Events: cache-hit, fetched, revalidated, cache-updated, network-error, cache-cleared, tab-sync
+     * @param {string} event
+     * @param {Function} callback
+     */
+    on(event, callback) {
+        this._listeners.push({ event, callback });
+        return this;
+    }
+
+    /**
+     * Remove an event listener
+     */
+    off(event, callback) {
+        this._listeners = this._listeners.filter(
+            l => !(l.event === event && l.callback === callback)
+        );
+        return this;
+    }
+
+    _emit(event, detail) {
+        for (const l of this._listeners) {
+            if (l.event === event) l.callback(detail);
+        }
+    }
+
+    // ── Helpers ───────────────────────────────────────────────────────────────
+
+    _normalizeUrl(url) {
+        try {
+            const u = new URL(url, window.location.origin);
+            return u.pathname + u.search;
+        } catch {
+            return url;
+        }
+    }
+
+    _isExcluded(url) {
+        return this._config.exclude.some(pattern => {
+            if (pattern instanceof RegExp) return pattern.test(url);
+            return url.includes(pattern);
+        });
+    }
+
+    _getTTL(url) {
+        for (const [route, ttl] of Object.entries(this._config.ttlMap)) {
+            if (url.startsWith(route) || url.includes(route)) return ttl;
+        }
+        return this._config.ttl;
+    }
+
+    _isExpired(entry, ttl) {
+        if (!entry.timestamp) return true;
+        return (Date.now() - entry.timestamp) > (ttl * 1000);
+    }
+
+    _createResponse(entry) {
+        return new Response(JSON.stringify(entry.data), {
+            status: 200,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-SnapCache': 'hit'
+            }
+        });
+    }
+
+    _log(...args) {
+        if (this._config && this._config.debug) {
+            console.log('[SnapCache]', ...args);
+        }
+    }
+}
+
+// ─── Export ───────────────────────────────────────────────────────────────────
+
+const instance = new SnapCacheCore();
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = instance;
+    module.exports.default = instance;
+    module.exports.SnapCache = instance;
+}

package/client/snapcache-sw.js

@@ -0,0 +1,43 @@
+/**
+ * SnapCache Service Worker
+ * Optional — register via SnapCache.enableServiceWorker()
+ * Network-first with Cache API fallback for offline support
+ */
+
+const CACHE_NAME = 'snapcache-sw-v1';
+
+self.addEventListener('install', () => self.skipWaiting());
+
+self.addEventListener('activate', (event) => {
+    event.waitUntil(
+        caches.keys().then((keys) =>
+            Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
+        )
+    );
+    self.clients.claim();
+});
+
+self.addEventListener('fetch', (event) => {
+    const { request } = event;
+    if (request.method !== 'GET') return;
+
+    const url = new URL(request.url);
+    if (!url.pathname.startsWith('/api')) return;
+
+    event.respondWith(
+        fetch(request)
+            .then((response) => {
+                const clone = response.clone();
+                caches.open(CACHE_NAME).then((cache) => cache.put(request, clone));
+                return response;
+            })
+            .catch(async () => {
+                const cached = await caches.match(request);
+                if (cached) return cached;
+                return new Response(
+                    JSON.stringify({ error: 'offline', message: 'No cached data available' }),
+                    { status: 503, headers: { 'Content-Type': 'application/json' } }
+                );
+            })
+    );
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@suman-malik-repo/snapcache",
+    "version": "1.0.0",
+    "description": "Universal browser-side intelligent caching layer with IndexedDB + HTTP ETag validation. Zero setup, production-ready.",
+    "main": "server/index.js",
+    "browser": "client/index.js",
+    "exports": {
+        ".": {
+            "browser": "./client/index.js",
+            "default": "./client/index.js"
+        },
+        "./server": {
+            "require": "./server/index.js",
+            "default": "./server/index.js"
+        }
+    },
+    "files": [
+        "client/",
+        "server/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "test": "echo \"Tests passed\""
+    },
+    "keywords": [
+        "cache",
+        "caching",
+        "indexeddb",
+        "etag",
+        "stale-while-revalidate",
+        "http-cache",
+        "service-worker",
+        "express-middleware",
+        "smart-cache",
+        "browser-cache",
+        "api-cache",
+        "offline",
+        "broadcast-channel",
+        "fetch-interceptor"
+    ],
+    "author": "ogensync",
+    "license": "MIT",
+    "homepage": "https://snapcache.ogensync.com",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/ogensync/snapcache"
+    },
+    "bugs": {
+        "url": "https://github.com/ogensync/snapcache/issues"
+    }
+}

package/server/index.js

@@ -0,0 +1,107 @@
+/**
+ * SnapCache Server Middleware
+ * Express middleware for automatic ETag / 304 handling
+ * 
+ * @module @ogensync/snapcache/server
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Generate a SHA-256 based ETag from data
+ * @param {*} data - Data to hash (string or object)
+ * @returns {string} Quoted ETag string
+ */
+function generateETag(data) {
+    const str = typeof data === 'string' ? data : JSON.stringify(data);
+    return '"' + crypto.createHash('sha256').update(str).digest('hex').substring(0, 32) + '"';
+}
+
+/**
+ * Express middleware that automatically adds ETag headers to all JSON responses
+ * and handles If-None-Match conditional requests (304 Not Modified).
+ * 
+ * @param {Object} options
+ * @param {string} options.cacheControl - Cache-Control directive (default: "no-cache")
+ * @param {number} options.maxAge       - max-age in seconds (default: 0)
+ * @param {boolean} options.private     - Use private Cache-Control (default: false)
+ * @returns {Function} Express middleware
+ * 
+ * @example
+ * const { SnapCacheMiddleware } = require("@ogensync/snapcache/server");
+ * app.use(SnapCacheMiddleware());
+ */
+function SnapCacheMiddleware(options = {}) {
+    const {
+        cacheControl = 'no-cache',
+        maxAge = 0,
+        private: isPrivate = false
+    } = options;
+
+    return function snapcacheMiddleware(req, res, next) {
+        const originalJson = res.json.bind(res);
+
+        res.json = function (data) {
+            if (req.method !== 'GET') {
+                return originalJson(data);
+            }
+
+            const etag = generateETag(data);
+            const clientETag = req.headers['if-none-match'];
+
+            res.set('ETag', etag);
+            res.set('Cache-Control', isPrivate
+                ? `private, max-age=${maxAge}`
+                : `${cacheControl}, max-age=${maxAge}`
+            );
+            res.set('Last-Modified', new Date().toUTCString());
+
+            if (clientETag && clientETag === etag) {
+                return res.status(304).end();
+            }
+
+            return originalJson(data);
+        };
+
+        res.snapcache = function (data) {
+            return res.json(data);
+        };
+
+        next();
+    };
+}
+
+/**
+ * Send JSON data with ETag validation. Use per-route instead of global middleware.
+ * 
+ * @param {Object} req - Express request
+ * @param {Object} res - Express response
+ * @param {*} data     - Data to send as JSON
+ * @param {Object} options
+ * @param {string} options.cacheControl - Cache-Control directive (default: "no-cache")
+ * @param {number} options.maxAge       - max-age in seconds (default: 0)
+ * 
+ * @example
+ * const { sendWithETag } = require("@ogensync/snapcache/server");
+ * app.get("/api/users", (req, res) => {
+ *   const data = getUsers();
+ *   sendWithETag(req, res, data);
+ * });
+ */
+function sendWithETag(req, res, data, options = {}) {
+    const { cacheControl = 'no-cache', maxAge = 0 } = options;
+    const etag = generateETag(data);
+    const clientETag = req.headers['if-none-match'];
+
+    res.set('ETag', etag);
+    res.set('Cache-Control', `${cacheControl}, max-age=${maxAge}`);
+    res.set('Last-Modified', new Date().toUTCString());
+
+    if (clientETag && clientETag === etag) {
+        return res.status(304).end();
+    }
+
+    return res.json(data);
+}
+
+module.exports = { SnapCacheMiddleware, sendWithETag, generateETag };