swimple 0.4.0 → 0.5.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.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

@@ -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.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,12 @@
 {
   "name": "swimple",
-  "version": "0.4.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",