swimple 0.3.0 → 0.5.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
 
@@ -405,6 +416,65 @@ fetch("/api/logout", {
 
 **Note:** While this header is typically used on mutation requests (POST/PATCH/PUT/DELETE), if used on a GET request, it will still clear the cache and attempt to fetch from network. If the network fails, the error will propagate to the caller.
 
+## Header Constants
+
+For convenience, swimple exports header name constants that you can use in your non-service-worker code (e.g., client-side JavaScript) to avoid hard-coding header names. This helps prevent typos and makes refactoring easier.
+
+### Importing Header Constants
+
+#### Node.js / npm Import
+
+```javascript
+import {
+  CACHE_STRATEGY_HEADER,
+  CACHE_TTL_HEADER,
+  CACHE_STALE_TTL_HEADER,
+  CACHE_INVALIDATE_HEADER,
+  CACHE_CLEAR_HEADER
+} from "swimple/headers";
+
+// Use in your fetch calls
+fetch("/api/users", {
+  headers: {
+    [CACHE_STRATEGY_HEADER]: "network-first",
+    [CACHE_TTL_HEADER]: "600"
+  }
+});
+```
+
+#### CDN Import
+
+```javascript
+import {
+  CACHE_STRATEGY_HEADER,
+  CACHE_TTL_HEADER,
+  CACHE_STALE_TTL_HEADER,
+  CACHE_INVALIDATE_HEADER,
+  CACHE_CLEAR_HEADER
+} from "https://cdn.jsdelivr.net/npm/swimple@1.0.0/headers.js";
+
+// Use in your fetch calls
+const headers = new Headers();
+headers.set(CACHE_TTL_HEADER, "300");
+headers.append(CACHE_INVALIDATE_HEADER, "/api/users");
+headers.append(CACHE_INVALIDATE_HEADER, "/api/posts");
+
+fetch("/api/users/123", {
+  method: "PATCH",
+  headers
+});
+```
+
+### Available Constants
+
+- `CACHE_STRATEGY_HEADER` - `"X-SW-Cache-Strategy"`
+- `CACHE_TTL_HEADER` - `"X-SW-Cache-TTL-Seconds"`
+- `CACHE_STALE_TTL_HEADER` - `"X-SW-Cache-Stale-TTL-Seconds"`
+- `CACHE_INVALIDATE_HEADER` - `"X-SW-Cache-Invalidate"`
+- `CACHE_CLEAR_HEADER` - `"X-SW-Cache-Clear"`
+
+**Note:** There is also an internal `CACHE_TIMESTAMP_HEADER` constant (`"x-sw-cache-timestamp"`), but this is used internally by the library and should not be set manually.
+
 ## Caching Behavior
 
 ### Automatic Caching (Default)

package/headers.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+/**
+ * Header constants used by swimple for cache control.
+ * These constants can be imported in non-service-worker code to set headers on requests.
+ *
+ * @example
+ * // Node.js / npm import
+ * import { CACHE_STRATEGY_HEADER, CACHE_TTL_HEADER } from "swimple/headers";
+ *
+ * @example
+ * // CDN import
+ * import { CACHE_STRATEGY_HEADER, CACHE_TTL_HEADER } from "https://cdn.jsdelivr.net/npm/swimple@1.0.0/headers.js";
+ */
+
+/**
+ * Header name for overriding the caching strategy for a specific request.
+ * Values: "cache-first", "network-first", or "stale-while-revalidate"
+ */
+export const CACHE_STRATEGY_HEADER = "X-SW-Cache-Strategy";
+
+/**
+ * Header name for setting the time-to-live (in seconds) for a cached response.
+ * Set to "0" to completely opt out of caching for a specific request.
+ */
+export const CACHE_TTL_HEADER = "X-SW-Cache-TTL-Seconds";
+
+/**
+ * Header name for setting the stale time-to-live (in seconds) for a cached response.
+ * Used by cache-first (when offline), network-first (when offline), and stale-while-revalidate strategies.
+ */
+export const CACHE_STALE_TTL_HEADER = "X-SW-Cache-Stale-TTL-Seconds";
+
+/**
+ * Header name for explicitly invalidating specific cache entries.
+ * Can be set multiple times to invalidate multiple paths.
+ */
+export const CACHE_INVALIDATE_HEADER = "X-SW-Cache-Invalidate";
+
+/**
+ * Header name for clearing the entire cache.
+ * Any value works - the header's presence triggers cache clearing.
+ */
+export const CACHE_CLEAR_HEADER = "X-SW-Cache-Clear";
+
+/**
+ * Internal header name used to store the cache timestamp in cached responses.
+ * This header is set automatically by the library and should not be set manually.
+ */
+export const CACHE_TIMESTAMP_HEADER = "x-sw-cache-timestamp";

package/helpers.js

@@ -6,17 +6,25 @@
 /// <reference lib="esnext" />
 /// <reference lib="webworker" />
 
-/** @import { CacheStrategy, HandleRequestConfig } from "./types" */
+/** @import { CacheStrategy, HandleRequestConfig, LoggingLevel } from "./types" */
+
+import {
+  CACHE_TIMESTAMP_HEADER,
+  CACHE_STRATEGY_HEADER,
+  CACHE_TTL_HEADER,
+  CACHE_STALE_TTL_HEADER
+} from "./headers.js";
 
 // 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;
 }
 
 /**
@@ -70,7 +78,7 @@ export function getAllHeaders(headers, name) {
  * @returns {number | null} Timestamp in milliseconds since epoch, or null if not found
  */
 export function getCacheTimestamp(response) {
-  const timestampHeader = getHeader(response.headers, "x-sw-cache-timestamp");
+  const timestampHeader = getHeader(response.headers, CACHE_TIMESTAMP_HEADER);
   if (!timestampHeader) {
     return null;
   }
@@ -119,7 +127,7 @@ export function isStale(response, ttl, staleTTL) {
  */
 export function addTimestamp(response) {
   const headers = new Headers(response.headers);
-  headers.set("x-sw-cache-timestamp", Date.now().toString());
+  headers.set(CACHE_TIMESTAMP_HEADER, Date.now().toString());
   return new Response(response.body, {
     status: response.status,
     statusText: response.statusText,
@@ -158,14 +166,16 @@ export function getInferredInvalidationPaths(url) {
  * @returns {CacheStrategy}
  */
 export function getStrategy(headers, defaultStrategy, url = "") {
-  const strategyHeader = getHeader(headers, "X-SW-Cache-Strategy");
+  const strategyHeader = getHeader(headers, CACHE_STRATEGY_HEADER);
   if (
     strategyHeader &&
     ["cache-first", "network-first", "stale-while-revalidate"].includes(
       strategyHeader
     )
   ) {
-    log(`X-SW-Cache-Strategy header set: ${strategyHeader} (${url})`);
+    logVerbose(
+      `${CACHE_STRATEGY_HEADER} header set: ${strategyHeader} (${url})`
+    );
     return /** @type {CacheStrategy} */ (strategyHeader);
   }
   return defaultStrategy;
@@ -179,11 +189,11 @@ export function getStrategy(headers, defaultStrategy, url = "") {
  * @returns {number | null} TTL in seconds, or null if caching is disabled
  */
 export function getTTL(headers, defaultTTL, url = "") {
-  const ttlHeader = getHeader(headers, "X-SW-Cache-TTL-Seconds");
+  const ttlHeader = getHeader(headers, CACHE_TTL_HEADER);
   if (ttlHeader === null) {
     return defaultTTL > 0 ? defaultTTL : null;
   }
-  log(`X-SW-Cache-TTL-Seconds header set: ${ttlHeader} (${url})`);
+  logVerbose(`${CACHE_TTL_HEADER} header set: ${ttlHeader} (${url})`);
   const ttl = parseInt(ttlHeader, 10);
   if (isNaN(ttl) || ttl <= 0) {
     return null;
@@ -199,11 +209,13 @@ export function getTTL(headers, defaultTTL, url = "") {
  * @returns {number | null} Stale TTL in seconds, or null if stale caching is disabled
  */
 export function getStaleTTL(headers, defaultStaleTTL, url = "") {
-  const staleTTLHeader = getHeader(headers, "X-SW-Cache-Stale-TTL-Seconds");
+  const staleTTLHeader = getHeader(headers, CACHE_STALE_TTL_HEADER);
   if (staleTTLHeader === null) {
     return defaultStaleTTL > 0 ? defaultStaleTTL : null;
   }
-  log(`X-SW-Cache-Stale-TTL-Seconds header set: ${staleTTLHeader} (${url})`);
+  logVerbose(
+    `${CACHE_STALE_TTL_HEADER} header set: ${staleTTLHeader} (${url})`
+  );
   const staleTTL = parseInt(staleTTLHeader, 10);
   if (isNaN(staleTTL) || staleTTL <= 0) {
     return null;
@@ -235,8 +247,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 +306,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 +369,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,9 +24,15 @@ import {
   validateConfig,
   isOlderThanMaxAge,
   cleanupOldCacheEntries,
-  setLoggingEnabled,
-  log
+  setLoggingLevel,
+  logInfo,
+  logVerbose
 } from "./helpers.js";
+import {
+  CACHE_CLEAR_HEADER,
+  CACHE_INVALIDATE_HEADER,
+  CACHE_TTL_HEADER
+} from "./headers.js";
 
 /**
  * Creates a request handler function for service worker fetch events.
@@ -51,10 +57,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;
@@ -74,8 +80,8 @@ export function createHandleRequest(config) {
     const headers = request.headers;
 
     // 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}`);
+    if (getHeader(headers, CACHE_CLEAR_HEADER) !== null) {
+      logVerbose(`${CACHE_CLEAR_HEADER} header set: ${url}`);
       return (async () => {
         await clearCache(cacheName);
         return customFetch(request);
@@ -84,12 +90,12 @@ export function createHandleRequest(config) {
 
     // Handle invalidation for mutations
     // Check for explicit invalidation headers first (works even if inferInvalidation is false)
-    const invalidateHeaders = getAllHeaders(headers, "X-SW-Cache-Invalidate");
+    const invalidateHeaders = getAllHeaders(headers, CACHE_INVALIDATE_HEADER);
     const isMutation = ["POST", "PATCH", "PUT", "DELETE"].includes(method);
 
     if (invalidateHeaders.length > 0) {
       invalidateHeaders.forEach((path) => {
-        log(`X-SW-Cache-Invalidate header set: ${path} (${url})`);
+        logVerbose(`${CACHE_INVALIDATE_HEADER} header set: ${path} (${url})`);
       });
     }
 
@@ -152,8 +158,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 hasExplicitTTLHeader = getHeader(headers, CACHE_TTL_HEADER) !== null;
     const ttl = getTTL(headers, defaultTTLSeconds, url);
 
     // If scope doesn't match and there's no explicit TTL header, don't handle the request
@@ -177,22 +182,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 +205,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 +234,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 +242,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 +268,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 +277,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 +306,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,11 +1,12 @@
 {
   "name": "swimple",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A simple service worker library for request caching",
   "type": "module",
   "main": "index.js",
   "exports": {
-    ".": "./index.js"
+    ".": "./index.js",
+    "./headers": "./headers.js"
   },
   "scripts": {
     "test": "npm run test:unit && npm run test:e2e && npm run test:ui",

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;
 }