swimple 0.5.0 → 0.6.0

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/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/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/package.json

@@ -1,12 +1,18 @@
 {
   "name": "swimple",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A simple service worker library for request caching",
   "type": "module",
   "main": "index.js",
   "exports": {
-    ".": "./index.js",
-    "./headers": "./headers.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",
@@ -14,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",
@@ -28,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.