swimple 0.3.0 → 0.4.0

package/README.md

@@ -163,17 +163,28 @@ The `customFetch` function has the same signature as the native `fetch` function
 
 ### 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.
+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/"],
-  enableLogging: true
+  loggingLevel: "verbose" // or "minimal" for less verbose output
 });
 ```
 
-When logging is enabled, you'll see console output like:
+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
@@ -255,7 +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).                                                                                                                                                                                     |
-| `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.                                                                                                                                                                                                                                                                               |
+| `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,17 +6,18 @@
 /// <reference lib="esnext" />
 /// <reference lib="webworker" />
 
-/** @import { CacheStrategy, HandleRequestConfig } from "./types" */
+/** @import { CacheStrategy, HandleRequestConfig, LoggingLevel } from "./types" */
 
 // Module-level logging state
-let loggingEnabled = false;
+/** @type {LoggingLevel} */
+let loggingLevel = "none";
 
 /**
- * Set whether logging is enabled
- * @param {boolean} enabled - Whether to enable logging
+ * Set the logging level
+ * @param {LoggingLevel} level - Logging level: "none", "minimal", or "verbose"
  */
-export function setLoggingEnabled(enabled) {
-  loggingEnabled = enabled;
+export function setLoggingLevel(level) {
+  loggingLevel = level;
 }
 
 /**
@@ -165,7 +166,7 @@ export function getStrategy(headers, defaultStrategy, url = "") {
       strategyHeader
     )
   ) {
-    log(`X-SW-Cache-Strategy header set: ${strategyHeader} (${url})`);
+    logVerbose(`X-SW-Cache-Strategy header set: ${strategyHeader} (${url})`);
     return /** @type {CacheStrategy} */ (strategyHeader);
   }
   return defaultStrategy;
@@ -183,7 +184,7 @@ export function getTTL(headers, defaultTTL, url = "") {
   if (ttlHeader === null) {
     return defaultTTL > 0 ? defaultTTL : null;
   }
-  log(`X-SW-Cache-TTL-Seconds header set: ${ttlHeader} (${url})`);
+  logVerbose(`X-SW-Cache-TTL-Seconds header set: ${ttlHeader} (${url})`);
   const ttl = parseInt(ttlHeader, 10);
   if (isNaN(ttl) || ttl <= 0) {
     return null;
@@ -203,7 +204,9 @@ export function getStaleTTL(headers, defaultStaleTTL, url = "") {
   if (staleTTLHeader === null) {
     return defaultStaleTTL > 0 ? defaultStaleTTL : null;
   }
-  log(`X-SW-Cache-Stale-TTL-Seconds header set: ${staleTTLHeader} (${url})`);
+  logVerbose(
+    `X-SW-Cache-Stale-TTL-Seconds header set: ${staleTTLHeader} (${url})`
+  );
   const staleTTL = parseInt(staleTTLHeader, 10);
   if (isNaN(staleTTL) || staleTTL <= 0) {
     return null;
@@ -235,8 +238,10 @@ export function matchesScope(url, scope, defaultTTLSeconds) {
 export async function invalidateCache(cacheName, urls) {
   const cache = await caches.open(cacheName);
   const deletePromises = urls.map(async (url) => {
-    log(`Cache invalidated: ${url}`);
     const deleted = await cache.delete(url);
+    if (deleted) {
+      logInfo(`Cache invalidated: ${url}`);
+    }
     return deleted;
   });
   await Promise.allSettled(deletePromises);
@@ -292,21 +297,31 @@ export async function cleanupOldCacheEntries(cacheName, maxAgeSeconds) {
   await Promise.allSettled(cleanupPromises);
   if (cleanedUrls.length > 0) {
     cleanedUrls.forEach((url) => {
-      log(`Cache entry cleaned up (maxAge): ${url}`);
+      logVerbose(`Cache entry cleaned up (maxAge): ${url}`);
     });
-    log(
+    logVerbose(
       `Cleaned up ${cleanedUrls.length} cache entr${cleanedUrls.length === 1 ? "y" : "ies"} due to maxAge`
     );
   }
 }
 
 /**
- * Log a message if logging is enabled
+ * Log an informational message (minimal and verbose levels)
  * @param {string} message - Message to log
  */
-export function log(message) {
-  if (loggingEnabled) {
-    console.log(`[swimple] ${message}`);
+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}`);
   }
 }
 
@@ -345,9 +360,11 @@ export function validateConfig(config) {
     );
   }
   if (
-    cfg.enableLogging !== undefined &&
-    typeof cfg.enableLogging !== "boolean"
+    cfg.loggingLevel !== undefined &&
+    !["none", "minimal", "verbose"].includes(String(cfg.loggingLevel))
   ) {
-    throw new Error("config.enableLogging must be a boolean if provided");
+    throw new Error(
+      'config.loggingLevel must be one of: "none", "minimal", "verbose"'
+    );
   }
 }

package/index.js

@@ -24,8 +24,9 @@ import {
   validateConfig,
   isOlderThanMaxAge,
   cleanupOldCacheEntries,
-  setLoggingEnabled,
-  log
+  setLoggingLevel,
+  logInfo,
+  logVerbose
 } from "./helpers.js";
 
 /**
@@ -51,10 +52,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;
+  const loggingLevel = config.loggingLevel ?? "none";
 
   // Set module-level logging state
-  setLoggingEnabled(enableLogging);
+  setLoggingLevel(loggingLevel);
 
   // Track fetch counter for periodic cleanup
   let fetchCounter = 0;
@@ -75,7 +76,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}`);
+      logVerbose(`X-SW-Cache-Clear header set: ${url}`);
       return (async () => {
         await clearCache(cacheName);
         return customFetch(request);
@@ -89,7 +90,7 @@ export function createHandleRequest(config) {
 
     if (invalidateHeaders.length > 0) {
       invalidateHeaders.forEach((path) => {
-        log(`X-SW-Cache-Invalidate header set: ${path} (${url})`);
+        logVerbose(`X-SW-Cache-Invalidate header set: ${path} (${url})`);
       });
     }
 
@@ -177,22 +178,22 @@ export function createHandleRequest(config) {
 
         if (cachedResponse) {
           if (isFresh(cachedResponse, ttl)) {
-            log(`Cache hit: ${url}`);
+            logInfo(`Cache hit: ${url}`);
             return cachedResponse;
           }
 
           // Reactive cleanup: delete if older than maxCacheAgeSeconds
           if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
-            log(`Cache entry cleaned up (maxAge): ${url}`);
+            logVerbose(`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}`);
+          logVerbose(`Cache miss: ${url}`);
         } else if (!isStale(cachedResponse, ttl, staleTTL)) {
-          log(`Cache miss (stale): ${url}`);
+          logVerbose(`Cache miss (stale): ${url}`);
         }
         let networkResponse;
         try {
@@ -200,7 +201,7 @@ export function createHandleRequest(config) {
         } catch (error) {
           // Network failed, return stale cache if available
           if (cachedResponse && isStale(cachedResponse, ttl, staleTTL)) {
-            log(`Cache hit (stale, offline): ${url}`);
+            logInfo(`Cache hit (stale, offline): ${url}`);
             return cachedResponse;
           }
           throw error;
@@ -229,7 +230,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}`);
+              logVerbose(`Cache entry cleaned up (maxAge): ${url}`);
               cache.delete(request); // Fire-and-forget cleanup
               throw error;
             }
@@ -237,11 +238,11 @@ export function createHandleRequest(config) {
               isFresh(cachedResponse, ttl) ||
               isStale(cachedResponse, ttl, staleTTL)
             ) {
-              log(`Cache hit (offline): ${url}`);
+              logInfo(`Cache hit (offline): ${url}`);
               return cachedResponse;
             }
           }
-          log(`Cache miss (offline): ${url}`);
+          logVerbose(`Cache miss (offline): ${url}`);
           throw error;
         }
 
@@ -263,7 +264,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}`);
+            logVerbose(`Cache entry cleaned up (maxAge): ${url}`);
             cache.delete(request); // Fire-and-forget cleanup
             // Continue to fetch from network
           } else {
@@ -272,9 +273,9 @@ export function createHandleRequest(config) {
 
             if (fresh || stale) {
               if (fresh) {
-                log(`Cache hit: ${url}`);
+                logInfo(`Cache hit: ${url}`);
               } else {
-                log(`Cache hit (stale): ${url}`);
+                logInfo(`Cache hit (stale): ${url}`);
               }
               // Return cached response immediately
               // Update cache in background if stale
@@ -301,9 +302,9 @@ export function createHandleRequest(config) {
         // 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}`);
+          logVerbose(`Cache miss: ${url}`);
         } else {
-          log(`Cache miss (too stale): ${url}`);
+          logVerbose(`Cache miss (too stale): ${url}`);
         }
         const networkResponse = await customFetch(request);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swimple",
-  "version": "0.3.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,6 +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;
-  /** Enable logging for cache hits, misses, header usage, invalidation, and cleanup. Defaults to false. */
-  enableLogging?: boolean;
+  /** 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;
 }