swimple 0.4.0 → 0.6.0

package/README.md

@@ -416,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.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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/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.d.ts

@@ -0,0 +1,134 @@
+/// <reference no-default-lib="true"/>
+/**
+ * Set the logging level
+ * @param {LoggingLevel} level - Logging level: "none", "minimal", or "verbose"
+ */
+export function setLoggingLevel(level: LoggingLevel): void;
+/**
+ * Get header value (case-insensitive)
+ * @param {Headers} headers
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function getHeader(headers: Headers, name: string): string | null;
+/**
+ * Get all header values for a given header name (case-insensitive)
+ * Useful when a header has been set multiple times (e.g., multiple X-SW-Cache-Invalidate headers)
+ * When headers are set multiple times with append(), they are concatenated with ", " (comma+space)
+ * This function splits them back into individual values
+ * @param {Headers} headers
+ * @param {string} name - Header name to look up
+ * @returns {string[]} Array of all header values for the given name
+ */
+export function getAllHeaders(headers: Headers, name: string): string[];
+/**
+ * Get cache timestamp from response
+ * @param {Response} response
+ * @returns {number | null} Timestamp in milliseconds since epoch, or null if not found
+ */
+export function getCacheTimestamp(response: Response): number | null;
+/**
+ * Check if response is fresh
+ * @param {Response} response
+ * @param {number} ttl - Time-to-live in seconds
+ * @returns {boolean}
+ */
+export function isFresh(response: Response, ttl: number): boolean;
+/**
+ * Check if response is stale (but usable)
+ * @param {Response} response
+ * @param {number} ttl - Time-to-live in seconds
+ * @param {number | null} staleTTL - Stale time-to-live in seconds
+ * @returns {boolean}
+ */
+export function isStale(response: Response, ttl: number, staleTTL: number | null): boolean;
+/**
+ * Add timestamp to response
+ * @param {Response} response
+ * @returns {Response}
+ */
+export function addTimestamp(response: Response): Response;
+/**
+ * Get inferred invalidation paths
+ * @param {string} url
+ * @returns {string[]}
+ */
+export function getInferredInvalidationPaths(url: string): string[];
+/**
+ * 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: Headers, defaultStrategy: CacheStrategy, url?: string): CacheStrategy;
+/**
+ * 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: Headers, defaultTTL: number, url?: string): number | null;
+/**
+ * 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: Headers, defaultStaleTTL: number, url?: string): number | null;
+/**
+ * Check if URL matches scope.  Returns true if scope array is empty or if the URL pathname starts with any of the scope prefixes.
+ * @param {string} url
+ * @param {string[]} scope
+ * @param {number} defaultTTLSeconds
+ * @returns {boolean}
+ */
+export function matchesScope(url: string, scope: string[], defaultTTLSeconds: number): boolean;
+/**
+ * Invalidate cache entries
+ * @param {string} cacheName
+ * @param {string[]} urls
+ * @returns {Promise<void>}
+ */
+export function invalidateCache(cacheName: string, urls: string[]): Promise<void>;
+/**
+ * Clear entire cache
+ * @param {string} cacheName
+ * @returns {Promise<void>}
+ */
+export function clearCache(cacheName: string): Promise<void>;
+/**
+ * Check if a cached response is older than the maximum age
+ * @param {Response} response
+ * @param {number} maxAgeSeconds - Maximum age in seconds
+ * @returns {boolean}
+ */
+export function isOlderThanMaxAge(response: Response, maxAgeSeconds: number): boolean;
+/**
+ * Clean up cache entries older than maxAgeSeconds
+ * @param {string} cacheName
+ * @param {number} maxAgeSeconds - Maximum age in seconds
+ * @returns {Promise<void>}
+ */
+export function cleanupOldCacheEntries(cacheName: string, maxAgeSeconds: number): Promise<void>;
+/**
+ * Log an informational message (minimal and verbose levels)
+ * @param {string} message - Message to log
+ */
+export function logInfo(message: string): void;
+/**
+ * Log a verbose message (verbose level only)
+ * @param {string} message - Message to log
+ */
+export function logVerbose(message: string): void;
+/**
+ * Validate configuration object
+ * @param {HandleRequestConfig} config - Configuration object to validate
+ * @throws {Error} If config is invalid
+ */
+export function validateConfig(config: HandleRequestConfig): void;
+import type { LoggingLevel } from "./types";
+import type { CacheStrategy } from "./types";
+import type { HandleRequestConfig } from "./types";

package/helpers.js

@@ -8,6 +8,13 @@
 
 /** @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
 /** @type {LoggingLevel} */
 let loggingLevel = "none";
@@ -71,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;
   }
@@ -120,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,
@@ -159,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
     )
   ) {
-    logVerbose(`X-SW-Cache-Strategy header set: ${strategyHeader} (${url})`);
+    logVerbose(
+      `${CACHE_STRATEGY_HEADER} header set: ${strategyHeader} (${url})`
+    );
     return /** @type {CacheStrategy} */ (strategyHeader);
   }
   return defaultStrategy;
@@ -180,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;
   }
-  logVerbose(`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;
@@ -200,12 +209,12 @@ 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;
   }
   logVerbose(
-    `X-SW-Cache-Stale-TTL-Seconds header set: ${staleTTLHeader} (${url})`
+    `${CACHE_STALE_TTL_HEADER} header set: ${staleTTLHeader} (${url})`
   );
   const staleTTL = parseInt(staleTTLHeader, 10);
   if (isNaN(staleTTL) || staleTTL <= 0) {

package/index.d.ts

@@ -0,0 +1,13 @@
+/// <reference no-default-lib="true"/>
+/**
+ * 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 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: HandleRequestConfig): (event: FetchEvent) => Promise<Response> | null;
+export { cleanupOldCacheEntries } from "./helpers.js";
+import type { HandleRequestConfig } from "./types";

package/index.js

@@ -28,6 +28,11 @@ import {
   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.
@@ -75,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) {
-      logVerbose(`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);
@@ -85,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) => {
-        logVerbose(`X-SW-Cache-Invalidate header set: ${path} (${url})`);
+        logVerbose(`${CACHE_INVALIDATE_HEADER} header set: ${path} (${url})`);
       });
     }
 
@@ -153,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

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "swimple",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A simple service worker library for request caching",
   "type": "module",
   "main": "index.js",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./headers": {
+      "types": "./headers.d.ts",
+      "default": "./headers.js"
+    }
   },
   "scripts": {
     "test": "npm run test:unit && npm run test:e2e && npm run test:ui",
@@ -13,7 +20,8 @@
     "test:e2e": "node --test tests/**/*.e2e.test.js",
     "test:ui": "playwright test",
     "format:check": "prettier --check .",
-    "format:fix": "prettier --write ."
+    "format:fix": "prettier --write .",
+    "prepublishOnly": "tsc --allowJs --declaration --emitDeclarationOnly --outDir ./ --skipLibCheck --target es2022 --module es2022 --moduleResolution node index.js headers.js helpers.js"
   },
   "keywords": [
     "service-worker",
@@ -27,7 +35,8 @@
   "license": "MIT",
   "devDependencies": {
     "@playwright/test": "^1.57.0",
-    "prettier": "^3.7.4"
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3"
   },
   "engines": {
     "node": ">=24"

package/types.d.ts

@@ -1,3 +1,5 @@
+// NOTE: this is the only .d.ts file that is checked in, other declaration files are generated as part of the prepublishOnly script.
+
 /**
  * Caching strategy for handling requests.
  * - `cache-first`: Return from cache if fresh (within TTL), otherwise fetch from network immediately. Stale cache is only used when offline (network request fails). No background updates.