swimple 0.2.0 → 0.4.0

package/README.md

@@ -161,6 +161,41 @@ 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. The library supports three logging levels:
+
+- `"none"` (default): No logging
+- `"minimal"`: console.info logs cache hits and cache invalidation only
+- `"verbose"`: console.debug logs all events including cache misses, header usage, and cleanup
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  loggingLevel: "verbose" // or "minimal" for less verbose output
+});
+```
+
+With `loggingLevel: "minimal"`, you'll see:
+
+```
+[swimple] Cache hit: https://example.com/api/users
+[swimple] Cache invalidated: https://example.com/api/users/123
+```
+
+With `loggingLevel: "verbose"`, you'll see all events:
+
+```
+[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 +266,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).                                                                                                                                                                                     |
+| `loggingLevel`           | `string`   | No       | `"none"`        | Logging level: `"none"` (no logging), `"minimal"` (cache hits and invalidation only), or `"verbose"` (all logging including misses, header usage, and cleanup). When enabled, logs are written to the console with the `[swimple]` prefix. Useful for debugging cache behavior.                                                                                                                                                                                               |
 
 #### Returns
 

package/helpers.js

@@ -6,7 +6,19 @@
 /// <reference lib="esnext" />
 /// <reference lib="webworker" />
 
-/** @import { CacheStrategy, HandleRequestConfig } from "./types" */
+/** @import { CacheStrategy, HandleRequestConfig, LoggingLevel } from "./types" */
+
+// Module-level logging state
+/** @type {LoggingLevel} */
+let loggingLevel = "none";
+
+/**
+ * Set the logging level
+ * @param {LoggingLevel} level - Logging level: "none", "minimal", or "verbose"
+ */
+export function setLoggingLevel(level) {
+  loggingLevel = level;
+}
 
 /**
  * Get header value (case-insensitive)
@@ -143,9 +155,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 +166,7 @@ export function getStrategy(headers, defaultStrategy) {
       strategyHeader
     )
   ) {
+    logVerbose(`X-SW-Cache-Strategy header set: ${strategyHeader} (${url})`);
     return /** @type {CacheStrategy} */ (strategyHeader);
   }
   return defaultStrategy;
@@ -162,13 +176,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;
   }
+  logVerbose(`X-SW-Cache-TTL-Seconds header set: ${ttlHeader} (${url})`);
   const ttl = parseInt(ttlHeader, 10);
   if (isNaN(ttl) || ttl <= 0) {
     return null;
@@ -180,13 +196,17 @@ 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;
   }
+  logVerbose(
+    `X-SW-Cache-Stale-TTL-Seconds header set: ${staleTTLHeader} (${url})`
+  );
   const staleTTL = parseInt(staleTTLHeader, 10);
   if (isNaN(staleTTL) || staleTTL <= 0) {
     return null;
@@ -217,7 +237,14 @@ 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) => {
+    const deleted = await cache.delete(url);
+    if (deleted) {
+      logInfo(`Cache invalidated: ${url}`);
+    }
+    return deleted;
+  });
+  await Promise.allSettled(deletePromises);
 }
 
 /**
@@ -256,15 +283,46 @@ 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) => {
+      logVerbose(`Cache entry cleaned up (maxAge): ${url}`);
+    });
+    logVerbose(
+      `Cleaned up ${cleanedUrls.length} cache entr${cleanedUrls.length === 1 ? "y" : "ies"} due to maxAge`
+    );
+  }
+}
+
+/**
+ * Log an informational message (minimal and verbose levels)
+ * @param {string} message - Message to log
+ */
+export function logInfo(message) {
+  if (loggingLevel === "minimal" || loggingLevel === "verbose") {
+    console.info(`[swimple] ${message}`);
+  }
+}
+
+/**
+ * Log a verbose message (verbose level only)
+ * @param {string} message - Message to log
+ */
+export function logVerbose(message) {
+  if (loggingLevel === "verbose") {
+    console.debug(`[swimple] ${message}`);
+  }
 }
 
 /**
@@ -301,4 +359,12 @@ export function validateConfig(config) {
       "config.maxCacheAgeSeconds must be a positive number if provided"
     );
   }
+  if (
+    cfg.loggingLevel !== undefined &&
+    !["none", "minimal", "verbose"].includes(String(cfg.loggingLevel))
+  ) {
+    throw new Error(
+      'config.loggingLevel must be one of: "none", "minimal", "verbose"'
+    );
+  }
 }

package/index.js

@@ -23,7 +23,10 @@ import {
   clearCache,
   validateConfig,
   isOlderThanMaxAge,
-  cleanupOldCacheEntries
+  cleanupOldCacheEntries,
+  setLoggingLevel,
+  logInfo,
+  logVerbose
 } from "./helpers.js";
 
 /**
@@ -49,6 +52,10 @@ export function createHandleRequest(config) {
   const maxCacheAgeSeconds = config.maxCacheAgeSeconds ?? 7200;
   const inferInvalidation = config.inferInvalidation ?? true;
   const customFetch = config.customFetch || fetch;
+  const loggingLevel = config.loggingLevel ?? "none";
+
+  // Set module-level logging state
+  setLoggingLevel(loggingLevel);
 
   // Track fetch counter for periodic cleanup
   let fetchCounter = 0;
@@ -69,6 +76,7 @@ export function createHandleRequest(config) {
 
     // Handle cache clearing - header presence (any value) triggers cache clear
     if (getHeader(headers, "X-SW-Cache-Clear") !== null) {
+      logVerbose(`X-SW-Cache-Clear header set: ${url}`);
       return (async () => {
         await clearCache(cacheName);
         return customFetch(request);
@@ -80,6 +88,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) => {
+        logVerbose(`X-SW-Cache-Invalidate header set: ${path} (${url})`);
+      });
+    }
+
     if (invalidateHeaders.length > 0 || (inferInvalidation && isMutation)) {
       return (async () => {
         let pathsToInvalidate = [...invalidateHeaders];
@@ -141,7 +155,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 +167,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 +178,30 @@ export function createHandleRequest(config) {
 
         if (cachedResponse) {
           if (isFresh(cachedResponse, ttl)) {
+            logInfo(`Cache hit: ${url}`);
             return cachedResponse;
           }
 
           // Reactive cleanup: delete if older than maxCacheAgeSeconds
           if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+            logVerbose(`Cache entry cleaned up (maxAge): ${url}`);
             await cache.delete(request); // Fire-and-forget cleanup
           }
         }
 
         // No fresh cache, fetch from network
+        if (!cachedResponse) {
+          logVerbose(`Cache miss: ${url}`);
+        } else if (!isStale(cachedResponse, ttl, staleTTL)) {
+          logVerbose(`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)) {
+            logInfo(`Cache hit (stale, offline): ${url}`);
             return cachedResponse;
           }
           throw error;
@@ -208,6 +230,7 @@ export function createHandleRequest(config) {
           if (cachedResponse) {
             // Reactive cleanup: delete if older than maxCacheAgeSeconds
             if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+              logVerbose(`Cache entry cleaned up (maxAge): ${url}`);
               cache.delete(request); // Fire-and-forget cleanup
               throw error;
             }
@@ -215,9 +238,11 @@ export function createHandleRequest(config) {
               isFresh(cachedResponse, ttl) ||
               isStale(cachedResponse, ttl, staleTTL)
             ) {
+              logInfo(`Cache hit (offline): ${url}`);
               return cachedResponse;
             }
           }
+          logVerbose(`Cache miss (offline): ${url}`);
           throw error;
         }
 
@@ -239,6 +264,7 @@ export function createHandleRequest(config) {
         if (cachedResponse) {
           // Reactive cleanup: delete if older than maxCacheAgeSeconds
           if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+            logVerbose(`Cache entry cleaned up (maxAge): ${url}`);
             cache.delete(request); // Fire-and-forget cleanup
             // Continue to fetch from network
           } else {
@@ -246,6 +272,11 @@ export function createHandleRequest(config) {
             const stale = isStale(cachedResponse, ttl, staleTTL);
 
             if (fresh || stale) {
+              if (fresh) {
+                logInfo(`Cache hit: ${url}`);
+              } else {
+                logInfo(`Cache hit (stale): ${url}`);
+              }
               // Return cached response immediately
               // Update cache in background if stale
               if (stale) {
@@ -270,6 +301,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) {
+          logVerbose(`Cache miss: ${url}`);
+        } else {
+          logVerbose(`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.4.0",
   "description": "A simple service worker library for request caching",
   "type": "module",
   "main": "index.js",

package/types.d.ts

@@ -9,6 +9,14 @@ export type CacheStrategy =
   | "network-first"
   | "stale-while-revalidate";
 
+/**
+ * Logging level for cache operations.
+ * - `none`: No logging
+ * - `minimal`: Logs cache hits and cache invalidation only
+ * - `verbose`: Logs all events including cache misses, cleanup, and header usage
+ */
+export type LoggingLevel = "none" | "minimal" | "verbose";
+
 export interface HandleRequestConfig {
   /** Name of the cache, used when calling `Cache.open(cacheName)` internally. Changing this name effectively clears the previous cache entries. */
   cacheName: string;
@@ -26,4 +34,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;
+  /** Logging level: "none" (no logging), "minimal" (cache hits and invalidation only), or "verbose" (all logging including misses, cleanup, and headers). Defaults to "none". */
+  loggingLevel?: LoggingLevel;
 }