swimple 0.1.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).
@@ -224,13 +248,14 @@ Creates a request handler function for your service worker fetch handler.
 | Option                   | Type       | Required | Default         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | ------------------------ | ---------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `cacheName`              | `string`   | Yes      | -               | Name of the cache, used when calling `Cache.open(cacheName)` internally. Changing this name effectively clears the previous cache entries.                                                                                                                                                                                                                                                                                                                                    |
-| `scope`                  | `string[]` | No       | `undefined`     | URL prefixes to cache by default (e.g., `['/api/']`). If not set and `defaultTTLSeconds` is set, all same-origin GET requests are cached automatically. If not set and `defaultTTLSeconds` is not set (or 0), no requests are cached by default. Individual requests outside the scope can still enable caching with `X-SW-Cache-TTL-Seconds` header.                                                                                                                         |
+| `scope`                  | `string[]` | No       | `undefined`     | URL prefixes to cache by default (e.g., `['/api/']`). If not set and `defaultTTLSeconds` is set, all same-origin GET requests are cached automatically. If not set and `defaultTTLSeconds` is not set (or 0), no requests are cached by default. Individual requests outside the scope can still enable caching with `X-SW-Cache-TTL-Seconds` header. **Note:** Cross-origin requests are never cached, regardless of scope or TTL headers.                                   |
 | `defaultStrategy`        | `string`   | No       | `'cache-first'` | Default caching strategy: `'cache-first'`, `'network-first'`, or `'stale-while-revalidate'`.                                                                                                                                                                                                                                                                                                                                                                                  |
 | `defaultTTLSeconds`      | `number`   | No       | `300`           | Maximum age for fresh content. Fresh content will be returned from cache for cache-first and stale-while-revalidate strategies, and also from network-first when offline. Fresh content does not get updated from the network. Since this defaults to `300`, caching is automatic by default for GET requests matching the scope. Set to `0` or `undefined` to disable automatic caching (individual requests can still enable caching with `X-SW-Cache-TTL-Seconds` header). |
 | `defaultStaleTTLSeconds` | `number`   | No       | `3600`          | Maximum age for stale content. Stale content will be returned from cache for cache-first (when offline), network-first (when offline), and stale-while-revalidate strategies. That means responses past the fresh TTL but within stale TTL can still be returned from cache. Stale content does get updated from the network.                                                                                                                                                 |
 | `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
 
@@ -647,6 +672,7 @@ self.addEventListener("fetch", (event) => {
 
 - Only GET requests are cached
 - Only 2xx (OK) GET responses are cached. Non-OK responses (4xx, 5xx, etc.) are not cached
+- **Cross-origin requests are not cached** - Only requests to the same origin as the service worker are cached. Requests to different origins will return `null` and are not processed by the cache handler.
 - Non-GET and non-mutating requests (POST/PATCH/PUT/DELETE) are not processed by the cache handler - it will return null. Practically, this means HEAD requests are not handled by the cache handler.
 - Query strings are part of the cache key. Different query strings create different cache entries (e.g., `/api/users?page=1` and `/api/users?page=2` are separate cache entries)
 - Cache invalidation happens automatically for mutations when `inferInvalidation: true`

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,14 +23,19 @@ import {
   clearCache,
   validateConfig,
   isOlderThanMaxAge,
-  cleanupOldCacheEntries
+  cleanupOldCacheEntries,
+  setLoggingEnabled,
+  log
 } from "./helpers.js";
 
 /**
  * Creates a request handler function for service worker fetch events.
+ * The handler implements HTTP caching with configurable strategies (cache-first, network-first, stale-while-revalidate),
+ * automatic cache invalidation for mutations, and periodic cache cleanup. Only handles same-origin GET requests
+ * that match the configured scope.
  *
- * @param {HandleRequestConfig} config - Configuration options
- * @returns {(event: FetchEvent) => Promise<Response> | null} Request handler function
+ * @param {HandleRequestConfig} config - Configuration options including cache name, scope, default strategy, and TTL settings
+ * @returns {(event: FetchEvent) => Promise<Response> | null} Request handler function that can be used in service worker fetch event listeners
  */
 export function createHandleRequest(config) {
   validateConfig(config);
@@ -46,11 +51,22 @@ 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;
 
-  // Main request handler
+  /**
+   * Service worker fetch event handler that implements HTTP caching strategies.
+   * Handles cache invalidation for mutations, implements cache-first/network-first/stale-while-revalidate
+   * strategies for GET requests, and performs automatic cache cleanup.
+   *
+   * @param {FetchEvent} event - The fetch event from the service worker
+   * @returns {Promise<Response> | null} The cached or fetched response, or null if request shouldn't be handled
+   */
   return function handleRequest(event) {
     const request = event.request;
     const url = request.url;
@@ -59,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);
@@ -70,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];
@@ -93,6 +116,29 @@ export function createHandleRequest(config) {
       return null;
     }
 
+    // Only cache same-origin requests - cross-origin requests are not cached
+    // In service worker context, self.location.origin is the service worker's origin
+    try {
+      const requestUrl = new URL(url);
+      // Check if we're in a service worker context and can determine the origin
+      if (
+        typeof self !== "undefined" &&
+        self.location &&
+        self.location.origin
+      ) {
+        const serviceWorkerOrigin = self.location.origin;
+        // If request origin doesn't match service worker origin, don't cache
+        if (requestUrl.origin !== serviceWorkerOrigin) {
+          return null;
+        }
+      }
+      // In test environments where self.location might not be available,
+      // we rely on the test setup to ensure proper origin handling
+    } catch (error) {
+      // If URL parsing fails, don't cache
+      return null;
+    }
+
     // Periodic cleanup: run on first fetch and every 100 fetches
     fetchCounter++;
     if (fetchCounter === 1 || fetchCounter % 100 === 0) {
@@ -108,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) {
@@ -120,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") {
@@ -131,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;
@@ -175,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;
             }
@@ -182,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;
         }
 
@@ -206,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 {
@@ -213,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) {
@@ -237,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.1.0",
+  "version": "0.3.0",
   "description": "A simple service worker library for request caching",
   "type": "module",
   "main": "index.js",

package/types.d.ts

@@ -12,7 +12,7 @@ export type CacheStrategy =
 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;
-  /** URL prefixes to cache by default (e.g., `['/api/']`). If not set and `defaultTTLSeconds` is set, all same-origin GET requests are cached automatically. If not set and `defaultTTLSeconds` is not set (or 0), no requests are cached by default. Individual requests outside the scope can still enable caching with `X-SW-Cache-TTL-Seconds` header. */
+  /** URL prefixes to cache by default (e.g., `['/api/']`). If not set and `defaultTTLSeconds` is set, all same-origin GET requests are cached automatically. If not set and `defaultTTLSeconds` is not set (or 0), no requests are cached by default. Individual requests outside the scope can still enable caching with `X-SW-Cache-TTL-Seconds` header. Note: Cross-origin requests are never cached, regardless of scope or TTL headers. */
   scope?: string[];
   /** Default caching strategy: `'cache-first'`, `'network-first'`, or `'stale-while-revalidate'`. */
   defaultStrategy?: CacheStrategy;
@@ -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;
 }