swimple 0.2.0 → 0.3.0

package/README.md

@@ -161,6 +161,30 @@ const handleRequest = createHandleRequest({
 
 The `customFetch` function has the same signature as the native `fetch` function. It will be used for all network requests made by the cache handler.
 
+### Example 5: Enable Logging
+
+You can enable logging to debug cache behavior. When enabled, the library logs cache hits, misses, header usage, invalidation, and cleanup events to the console.
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  enableLogging: true
+});
+```
+
+When logging is enabled, you'll see console output like:
+
+```
+[swimple] Cache hit: https://example.com/api/users
+[swimple] Cache miss: https://example.com/api/posts
+[swimple] X-SW-Cache-TTL-Seconds header set: 600 (https://example.com/api/users)
+[swimple] Cache invalidated: https://example.com/api/users/123
+[swimple] Cache entry cleaned up (maxAge): https://example.com/api/old-data
+```
+
+This is useful for debugging cache behavior and understanding when requests are served from cache vs. network.
+
 ## Clearing the cache on logout
 
 It can be useful to clear the cache on logout or other events. You can do this by setting the `X-SW-Cache-Clear` header on a request (any value will work - the header's presence triggers cache clearing).
@@ -231,6 +255,7 @@ Creates a request handler function for your service worker fetch handler.
 | `inferInvalidation`      | `boolean`  | No       | `true`          | Automatically invalidate cache on POST/PATCH/PUT/DELETE requests.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `customFetch`            | `function` | No       | `fetch`         | Custom fetch function to use for network requests. Receives a `Request` object and must return a `Promise<Response>`. Useful for handling authentication errors (401/403) or adding custom headers to all requests.                                                                                                                                                                                                                                                           |
 | `maxCacheAgeSeconds`     | `number`   | No       | `7200`          | Maximum age (in seconds) before cache entries are automatically cleaned up. Entries older than this age are deleted. Defaults to 7200 seconds (2 hours, which is 2x the default stale TTL). Cache entries are cleaned up reactively (when accessed) and periodically (every 100 fetches).                                                                                                                                                                                     |
+| `enableLogging`          | `boolean`  | No       | `false`         | Enable logging for cache hits, misses, header usage, invalidation, and cleanup. When enabled, logs are written to the console with the `[swimple]` prefix. Useful for debugging cache behavior.                                                                                                                                                                                                                                                                               |
 
 #### Returns
 

package/helpers.js

@@ -8,6 +8,17 @@
 
 /** @import { CacheStrategy, HandleRequestConfig } from "./types" */
 
+// Module-level logging state
+let loggingEnabled = false;
+
+/**
+ * Set whether logging is enabled
+ * @param {boolean} enabled - Whether to enable logging
+ */
+export function setLoggingEnabled(enabled) {
+  loggingEnabled = enabled;
+}
+
 /**
  * Get header value (case-insensitive)
  * @param {Headers} headers
@@ -143,9 +154,10 @@ export function getInferredInvalidationPaths(url) {
  * Get strategy from request headers or use default
  * @param {Headers} headers
  * @param {CacheStrategy} defaultStrategy
+ * @param {string} url - Request URL for logging
  * @returns {CacheStrategy}
  */
-export function getStrategy(headers, defaultStrategy) {
+export function getStrategy(headers, defaultStrategy, url = "") {
   const strategyHeader = getHeader(headers, "X-SW-Cache-Strategy");
   if (
     strategyHeader &&
@@ -153,6 +165,7 @@ export function getStrategy(headers, defaultStrategy) {
       strategyHeader
     )
   ) {
+    log(`X-SW-Cache-Strategy header set: ${strategyHeader} (${url})`);
     return /** @type {CacheStrategy} */ (strategyHeader);
   }
   return defaultStrategy;
@@ -162,13 +175,15 @@ export function getStrategy(headers, defaultStrategy) {
  * Get TTL from request headers or use default
  * @param {Headers} headers
  * @param {number} defaultTTL - Default TTL in seconds
+ * @param {string} url - Request URL for logging
  * @returns {number | null} TTL in seconds, or null if caching is disabled
  */
-export function getTTL(headers, defaultTTL) {
+export function getTTL(headers, defaultTTL, url = "") {
   const ttlHeader = getHeader(headers, "X-SW-Cache-TTL-Seconds");
   if (ttlHeader === null) {
     return defaultTTL > 0 ? defaultTTL : null;
   }
+  log(`X-SW-Cache-TTL-Seconds header set: ${ttlHeader} (${url})`);
   const ttl = parseInt(ttlHeader, 10);
   if (isNaN(ttl) || ttl <= 0) {
     return null;
@@ -180,13 +195,15 @@ export function getTTL(headers, defaultTTL) {
  * Get stale TTL from request headers or use default
  * @param {Headers} headers
  * @param {number} defaultStaleTTL - Default stale TTL in seconds
+ * @param {string} url - Request URL for logging
  * @returns {number | null} Stale TTL in seconds, or null if stale caching is disabled
  */
-export function getStaleTTL(headers, defaultStaleTTL) {
+export function getStaleTTL(headers, defaultStaleTTL, url = "") {
   const staleTTLHeader = getHeader(headers, "X-SW-Cache-Stale-TTL-Seconds");
   if (staleTTLHeader === null) {
     return defaultStaleTTL > 0 ? defaultStaleTTL : null;
   }
+  log(`X-SW-Cache-Stale-TTL-Seconds header set: ${staleTTLHeader} (${url})`);
   const staleTTL = parseInt(staleTTLHeader, 10);
   if (isNaN(staleTTL) || staleTTL <= 0) {
     return null;
@@ -217,7 +234,12 @@ export function matchesScope(url, scope, defaultTTLSeconds) {
  */
 export async function invalidateCache(cacheName, urls) {
   const cache = await caches.open(cacheName);
-  await Promise.allSettled(urls.map((url) => cache.delete(url)));
+  const deletePromises = urls.map(async (url) => {
+    log(`Cache invalidated: ${url}`);
+    const deleted = await cache.delete(url);
+    return deleted;
+  });
+  await Promise.allSettled(deletePromises);
 }
 
 /**
@@ -256,15 +278,36 @@ export async function cleanupOldCacheEntries(cacheName, maxAgeSeconds) {
   const cache = await caches.open(cacheName);
   const keys = await cache.keys();
   const cleanupPromises = [];
+  const cleanedUrls = [];
 
   for (const request of keys) {
     const response = await cache.match(request);
     if (response && isOlderThanMaxAge(response, maxAgeSeconds)) {
+      const url = request.url || request.toString();
+      cleanedUrls.push(url);
       cleanupPromises.push(cache.delete(request));
     }
   }
 
   await Promise.allSettled(cleanupPromises);
+  if (cleanedUrls.length > 0) {
+    cleanedUrls.forEach((url) => {
+      log(`Cache entry cleaned up (maxAge): ${url}`);
+    });
+    log(
+      `Cleaned up ${cleanedUrls.length} cache entr${cleanedUrls.length === 1 ? "y" : "ies"} due to maxAge`
+    );
+  }
+}
+
+/**
+ * Log a message if logging is enabled
+ * @param {string} message - Message to log
+ */
+export function log(message) {
+  if (loggingEnabled) {
+    console.log(`[swimple] ${message}`);
+  }
 }
 
 /**
@@ -301,4 +344,10 @@ export function validateConfig(config) {
       "config.maxCacheAgeSeconds must be a positive number if provided"
     );
   }
+  if (
+    cfg.enableLogging !== undefined &&
+    typeof cfg.enableLogging !== "boolean"
+  ) {
+    throw new Error("config.enableLogging must be a boolean if provided");
+  }
 }

package/index.js

@@ -23,7 +23,9 @@ import {
   clearCache,
   validateConfig,
   isOlderThanMaxAge,
-  cleanupOldCacheEntries
+  cleanupOldCacheEntries,
+  setLoggingEnabled,
+  log
 } from "./helpers.js";
 
 /**
@@ -49,6 +51,10 @@ export function createHandleRequest(config) {
   const maxCacheAgeSeconds = config.maxCacheAgeSeconds ?? 7200;
   const inferInvalidation = config.inferInvalidation ?? true;
   const customFetch = config.customFetch || fetch;
+  const enableLogging = config.enableLogging ?? false;
+
+  // Set module-level logging state
+  setLoggingEnabled(enableLogging);
 
   // Track fetch counter for periodic cleanup
   let fetchCounter = 0;
@@ -69,6 +75,7 @@ export function createHandleRequest(config) {
 
     // Handle cache clearing - header presence (any value) triggers cache clear
     if (getHeader(headers, "X-SW-Cache-Clear") !== null) {
+      log(`X-SW-Cache-Clear header set: ${url}`);
       return (async () => {
         await clearCache(cacheName);
         return customFetch(request);
@@ -80,6 +87,12 @@ export function createHandleRequest(config) {
     const invalidateHeaders = getAllHeaders(headers, "X-SW-Cache-Invalidate");
     const isMutation = ["POST", "PATCH", "PUT", "DELETE"].includes(method);
 
+    if (invalidateHeaders.length > 0) {
+      invalidateHeaders.forEach((path) => {
+        log(`X-SW-Cache-Invalidate header set: ${path} (${url})`);
+      });
+    }
+
     if (invalidateHeaders.length > 0 || (inferInvalidation && isMutation)) {
       return (async () => {
         let pathsToInvalidate = [...invalidateHeaders];
@@ -141,7 +154,7 @@ export function createHandleRequest(config) {
     // Check if request matches scope and should be cached
     const hasExplicitTTLHeader =
       getHeader(headers, "X-SW-Cache-TTL-Seconds") !== null;
-    const ttl = getTTL(headers, defaultTTLSeconds);
+    const ttl = getTTL(headers, defaultTTLSeconds, url);
 
     // If scope doesn't match and there's no explicit TTL header, don't handle the request
     if (!matchesScope(url, scope, defaultTTLSeconds) && !hasExplicitTTLHeader) {
@@ -153,8 +166,8 @@ export function createHandleRequest(config) {
       return null;
     }
 
-    const staleTTL = getStaleTTL(headers, defaultStaleTTLSeconds);
-    const strategy = getStrategy(headers, defaultStrategy);
+    const staleTTL = getStaleTTL(headers, defaultStaleTTLSeconds, url);
+    const strategy = getStrategy(headers, defaultStrategy, url);
 
     // Handle cache-first strategy
     if (strategy === "cache-first") {
@@ -164,22 +177,30 @@ export function createHandleRequest(config) {
 
         if (cachedResponse) {
           if (isFresh(cachedResponse, ttl)) {
+            log(`Cache hit: ${url}`);
             return cachedResponse;
           }
 
           // Reactive cleanup: delete if older than maxCacheAgeSeconds
           if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+            log(`Cache entry cleaned up (maxAge): ${url}`);
             await cache.delete(request); // Fire-and-forget cleanup
           }
         }
 
         // No fresh cache, fetch from network
+        if (!cachedResponse) {
+          log(`Cache miss: ${url}`);
+        } else if (!isStale(cachedResponse, ttl, staleTTL)) {
+          log(`Cache miss (stale): ${url}`);
+        }
         let networkResponse;
         try {
           networkResponse = await customFetch(request);
         } catch (error) {
           // Network failed, return stale cache if available
           if (cachedResponse && isStale(cachedResponse, ttl, staleTTL)) {
+            log(`Cache hit (stale, offline): ${url}`);
             return cachedResponse;
           }
           throw error;
@@ -208,6 +229,7 @@ export function createHandleRequest(config) {
           if (cachedResponse) {
             // Reactive cleanup: delete if older than maxCacheAgeSeconds
             if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+              log(`Cache entry cleaned up (maxAge): ${url}`);
               cache.delete(request); // Fire-and-forget cleanup
               throw error;
             }
@@ -215,9 +237,11 @@ export function createHandleRequest(config) {
               isFresh(cachedResponse, ttl) ||
               isStale(cachedResponse, ttl, staleTTL)
             ) {
+              log(`Cache hit (offline): ${url}`);
               return cachedResponse;
             }
           }
+          log(`Cache miss (offline): ${url}`);
           throw error;
         }
 
@@ -239,6 +263,7 @@ export function createHandleRequest(config) {
         if (cachedResponse) {
           // Reactive cleanup: delete if older than maxCacheAgeSeconds
           if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+            log(`Cache entry cleaned up (maxAge): ${url}`);
             cache.delete(request); // Fire-and-forget cleanup
             // Continue to fetch from network
           } else {
@@ -246,6 +271,11 @@ export function createHandleRequest(config) {
             const stale = isStale(cachedResponse, ttl, staleTTL);
 
             if (fresh || stale) {
+              if (fresh) {
+                log(`Cache hit: ${url}`);
+              } else {
+                log(`Cache hit (stale): ${url}`);
+              }
               // Return cached response immediately
               // Update cache in background if stale
               if (stale) {
@@ -270,6 +300,11 @@ export function createHandleRequest(config) {
         // No cache or too stale, fetch from network, no need for fallback if offline
         // because we already know if there was a cached response it won't be
         // fresh or stale if we've reached this point
+        if (!cachedResponse) {
+          log(`Cache miss: ${url}`);
+        } else {
+          log(`Cache miss (too stale): ${url}`);
+        }
         const networkResponse = await customFetch(request);
 
         // Cache the response if successful

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swimple",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A simple service worker library for request caching",
   "type": "module",
   "main": "index.js",

package/types.d.ts

@@ -26,4 +26,6 @@ export interface HandleRequestConfig {
   customFetch?: typeof fetch;
   /** Maximum age (in seconds) before cache entries are automatically cleaned up. Entries older than this age are deleted. Defaults to 7200 seconds (2 hours, which is 2x the default stale TTL). Cache entries are cleaned up reactively (when accessed) and periodically (every 100 fetches). */
   maxCacheAgeSeconds?: number;
+  /** Enable logging for cache hits, misses, header usage, invalidation, and cleanup. Defaults to false. */
+  enableLogging?: boolean;
 }