serwist 9.1.1 → 10.0.0-preview.10

package/src/lib/extensions/runtime-cache.ts

@@ -0,0 +1,126 @@
+import { parallel } from "@serwist/utils";
+import type { Serwist } from "#lib/core.js";
+import type { Extension } from "#lib/extension.js";
+import { handleRequest, registerCapture } from "#lib/functions/router.js";
+import { Strategy } from "../strategies/Strategy.js";
+import type { RuntimeCaching } from "../types.js";
+import { type PrecacheFallbackEntry, PrecacheFallbackPlugin } from "./precache/plugin-fallback.js";
+
+export interface WarmRuntimeCacheEntry {
+  integrity?: string;
+  url: string;
+}
+
+export interface WarmRuntimeCacheOptions {
+  concurrency?: number;
+}
+
+export interface FallbackEntry extends PrecacheFallbackEntry {}
+
+export interface FallbacksOptions {
+  /**
+   * A list of fallback entries.
+   */
+  entries: FallbackEntry[];
+}
+
+export interface RuntimeCacheOptions {
+  /**
+   * URLs that should be cached as the service worker is installed.
+   */
+  warmEntries?: (WarmRuntimeCacheEntry | string | Request)[];
+  /**
+   * Options for `warmEntries`.
+   */
+  warmOptions?: WarmRuntimeCacheOptions;
+  /**
+   * Precaches routes so that they can be used as a fallback when
+   * a {@linkcode Strategy} fails to generate a response.
+   *
+   * Note: This option mutates `runtimeCaching`. It also expects the URLs
+   * defined in `entries` to have been precached beforehand.
+   */
+  fallbacks?: FallbacksOptions;
+}
+
+export class RuntimeCache implements Extension {
+  _entries: RuntimeCaching[];
+  _options: RuntimeCacheOptions;
+  constructor(entries: RuntimeCaching[], options: RuntimeCacheOptions = {}) {
+    this._entries = entries;
+    this._options = options;
+    this.init = this.init.bind(this);
+    this.install = this.install.bind(this);
+  }
+
+  init({ serwist }: { serwist: Serwist }): void {
+    if (this._options.fallbacks !== undefined) {
+      const fallbackPlugin = new PrecacheFallbackPlugin({
+        fallbackUrls: this._options.fallbacks.entries,
+        serwist,
+      });
+
+      this._entries.forEach((cacheEntry) => {
+        if (
+          cacheEntry.handler instanceof Strategy &&
+          // This also filters entries with `PrecacheFallbackPlugin` as it also has `handlerDidError`.
+          !cacheEntry.handler.plugins.some((plugin) => "handlerDidError" in plugin)
+        ) {
+          cacheEntry.handler.plugins.push(fallbackPlugin);
+        }
+      });
+    }
+    for (const entry of this._entries) {
+      registerCapture(serwist, entry.matcher, entry.handler, entry.method);
+    }
+  }
+
+  async install({ event, serwist }: { event: ExtendableEvent; serwist: Serwist }) {
+    const concurrency = this._options.warmOptions?.concurrency ?? 10;
+    if (this._options.warmEntries) {
+      await parallel(concurrency, this._options.warmEntries, async (entry) => {
+        const request =
+          entry instanceof Request
+            ? entry
+            : typeof entry === "string"
+              ? new Request(entry, {
+                  credentials: "same-origin",
+                })
+              : new Request(entry.url, {
+                  integrity: entry.integrity,
+                  credentials: "same-origin",
+                });
+
+        await handleRequest(serwist, {
+          request,
+          event,
+        });
+      });
+    }
+  }
+
+  /**
+   * Any assets you wish to cache ahead of time which can't be revisioned
+   * should be cached with this method. All assets are cached on install
+   * regardless of whether an older version of the request is in the cache.
+   *
+   * The input can be a string or a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
+   *
+   * @example
+   * ```js
+   * // For unrevisioned assets that should always be downloaded
+   * // with every service worker update, use this method.
+   * serwist.warmRuntimeCache([
+   *   "/scripts/main.js',
+   *   "/images/default-avater.png",
+   *   new Request("/images/logo.png"),
+   *   new Request("/api/data.json"),
+   * ]);
+   * ```
+   * @param entries A set of urls to cache when the service worker is installed.
+   */
+  warmRuntimeCache(entries: (WarmRuntimeCacheEntry | string | Request)[]): void {
+    if (!this._options.warmEntries) this._options.warmEntries = [];
+    this._options.warmEntries.push(...entries);
+  }
+}

package/src/lib/functions/handlers.ts

@@ -0,0 +1,149 @@
+import { defaultMethod, type HTTPMethod } from "#lib/constants.js";
+import type { Extension, ExtensionParam } from "#lib/extension.js";
+import type { Route } from "#lib/route.js";
+import type { RouteHandler } from "#lib/types.js";
+import { logger } from "#utils/logger.js";
+import { normalizeHandler } from "#utils/normalizeHandler.js";
+import { waitUntil } from "#utils/waitUntil.js";
+import type { Serwist } from "../core.js";
+import { handleRequest } from "./router.js";
+
+declare const self: ServiceWorkerGlobalScope;
+
+export type RequestArgs = string | [string, RequestInit?];
+
+export interface CacheURLsMessageData {
+  type: string;
+  payload: {
+    urlsToCache: RequestArgs[];
+  };
+}
+
+/**
+ * Adds Serwist's event listeners. Before calling it, add your own listeners should you need to.
+ */
+export const addEventListeners = (state: Serwist) => {
+  self.addEventListener("install", createInstallHandler(state));
+  self.addEventListener("activate", createActivateHandler(state));
+  self.addEventListener("fetch", createFetchHandler(state));
+  self.addEventListener("message", createCacheHandler(state));
+};
+
+export const createInstallHandler = (state: Serwist) => {
+  return (event: ExtendableEvent): Promise<void> => {
+    return waitUntil(event, async () => {
+      for (const callback of iterateExtensions(state, "install")) {
+        await callback({ event, serwist: state });
+      }
+    });
+  };
+};
+
+export const createActivateHandler = (state: Serwist) => {
+  return (event: ExtendableEvent): Promise<void> => {
+    return waitUntil(event, async () => {
+      for (const callback of iterateExtensions(state, "activate")) {
+        await callback({ event, serwist: state });
+      }
+    });
+  };
+};
+
+/**
+ * Gets a `Response` from an appropriate `Route`'s handler. Call this method
+ * from the service worker's `fetch` event.
+ * @param event
+ */
+export const createFetchHandler = (state: Serwist) => {
+  return (event: FetchEvent) => {
+    const { request } = event;
+    const responsePromise = handleRequest(state, { request, event });
+    if (responsePromise) {
+      event.respondWith(responsePromise);
+    }
+  };
+};
+
+/**
+ * Caches new URLs on demand. Call this method from the service worker's
+ * `message` event. To trigger the handler, send a message of type `"CACHE_URLS"`
+ * alongside a list of URLs that should be cached as `urlsToCache`.
+ * @param event
+ */
+export const createCacheHandler = (state: Serwist) => {
+  return (event: ExtendableMessageEvent) => {
+    if (event.data && event.data.type === "CACHE_URLS") {
+      const { payload }: CacheURLsMessageData = event.data;
+
+      if (process.env.NODE_ENV !== "production") {
+        logger.debug("Caching URLs from the window", payload.urlsToCache);
+      }
+
+      const requestPromises = Promise.all(
+        payload.urlsToCache.map((entry: string | [string, RequestInit?]) => {
+          let request: Request;
+          if (typeof entry === "string") {
+            request = new Request(entry);
+          } else {
+            request = new Request(...entry);
+          }
+          return handleRequest(state, { request, event });
+        }),
+      );
+
+      event.waitUntil(requestPromises);
+
+      // If a MessageChannel was used, reply to the message on success.
+      if (event.ports?.[0]) {
+        void requestPromises.then(() => event.ports[0].postMessage(true));
+      }
+    }
+  };
+};
+
+/**
+ * Define a default handler that's called when no routes explicitly
+ * match the incoming request.
+ *
+ * Each HTTP method (`'GET'`, `'POST'`, etc.) gets its own default handler.
+ *
+ * Without a default handler, unmatched requests will go against the
+ * network as if there were no service worker present.
+ *
+ * @param handler A callback function that returns a `Promise` resulting in a `Response`.
+ * @param method The HTTP method to associate with this default handler. Each method
+ * has its own default. Defaults to `'GET'`.
+ */
+export const setDefaultHandler = (state: Serwist, handler: RouteHandler, method: HTTPMethod = defaultMethod): void => {
+  state.defaultHandlerMap.set(method, normalizeHandler(handler));
+};
+
+/**
+ * If a {@linkcode Route} throws an error while handling a request, this handler
+ * will be called and given a chance to provide a response.
+ *
+ * @param handler A callback function that returns a `Promise` resulting
+ * in a `Response`.
+ */
+export const setCatchHandler = (state: Serwist, handler: RouteHandler): void => {
+  state.catchHandler = normalizeHandler(handler);
+};
+
+/**
+ * Accepts a callback name and returns an iterable of matching plugin callbacks.
+ *
+ * @param name The name fo the callback to run
+ * @returns
+ */
+export function* iterateExtensions<C extends keyof Extension>(state: Serwist, name: C): Generator<NonNullable<Extension[C]>> {
+  if (!state.extensions) return;
+
+  for (const controller of state.extensions) {
+    if (typeof controller[name] === "function") {
+      const callback = (param: ExtensionParam[C]) => {
+        controller[name]!(param as any);
+      };
+      yield callback as NonNullable<Extension[C]>;
+    }
+  }
+}

package/src/lib/functions/router.ts

@@ -0,0 +1,314 @@
+import { assert } from "#utils/assert.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
+import { parseRoute } from "#utils/parseRoute.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import type { HTTPMethod } from "../constants.js";
+import type { Serwist } from "../core.js";
+import type { Route } from "../route.js";
+import type { RouteHandler, RouteHandlerCallbackOptions, RouteMatchCallback, RouteMatchCallbackOptions } from "../types.js";
+
+/**
+ * Registers a `RegExp`, string, or function with a caching
+ * strategy to the router.
+ *
+ * @param capture If the capture param is a {@linkcode Route} object, all other arguments will be ignored.
+ * @param handler A callback function that returns a `Promise` resulting in a `Response`.
+ * This parameter is required if `capture` is not a {@linkcode Route} object.
+ * @param method The HTTP method to match the route against. Defaults to `'GET'`.
+ * @returns The generated {@linkcode Route} object.
+ */
+export const registerCapture = <T extends RegExp | string | RouteMatchCallback | Route>(
+  state: Serwist,
+  capture: T,
+  handler?: T extends Route ? never : RouteHandler,
+  method?: T extends Route ? never : HTTPMethod,
+): Route => {
+  const route = parseRoute(capture, handler, method);
+  registerRoute(state, route);
+  return route;
+};
+
+/**
+ * Registers a {@linkcode Route} with the router.
+ *
+ * @param route The {@linkcode Route} to register.
+ */
+export const registerRoute = (state: Serwist, route: Route): void => {
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isType(route, "object", {
+      moduleName: "serwist",
+      className: "Serwist",
+      funcName: "registerRoute",
+      paramName: "route",
+    });
+
+    assert!.hasMethod(route, "match", {
+      moduleName: "serwist",
+      className: "Serwist",
+      funcName: "registerRoute",
+      paramName: "route",
+    });
+
+    assert!.isType(route.handler, "object", {
+      moduleName: "serwist",
+      className: "Serwist",
+      funcName: "registerRoute",
+      paramName: "route",
+    });
+
+    assert!.hasMethod(route.handler, "handle", {
+      moduleName: "serwist",
+      className: "Serwist",
+      funcName: "registerRoute",
+      paramName: "route.handler",
+    });
+
+    assert!.isType(route.method, "string", {
+      moduleName: "serwist",
+      className: "Serwist",
+      funcName: "registerRoute",
+      paramName: "route.method",
+    });
+  }
+
+  if (!state.routes.has(route.method)) {
+    state.routes.set(route.method, []);
+  }
+
+  // Give precedence to all of the earlier routes by adding this additional
+  // route to the end of the array.
+  state.routes.get(route.method)!.push(route);
+};
+
+/**
+ * Unregisters a route from the router.
+ *
+ * @param route The {@linkcode Route} object to unregister.
+ */
+export const unregisterRoute = (state: Serwist, route: Route): void => {
+  if (!state.routes.has(route.method)) {
+    throw new SerwistError("unregister-route-but-not-found-with-method", {
+      method: route.method,
+    });
+  }
+
+  const routeIndex = state.routes.get(route.method)!.indexOf(route);
+  if (routeIndex > -1) {
+    state.routes.get(route.method)!.splice(routeIndex, 1);
+  } else {
+    throw new SerwistError("unregister-route-route-not-registered");
+  }
+};
+
+/**
+ * Applies the routing rules to a `FetchEvent` object to get a response from an
+ * appropriate route.
+ *
+ * @param options
+ * @returns A promise is returned if a registered route can handle the request.
+ * If there is no matching route and there's no default handler, `undefined`
+ * is returned.
+ */
+export const handleRequest = (
+  state: Serwist,
+  {
+    request,
+    event,
+  }: {
+    /**
+     * The request to handle.
+     */
+    request: Request;
+    /**
+     * The event that triggered the request.
+     */
+    event: ExtendableEvent;
+  },
+): Promise<Response> | undefined => {
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isInstance(request, Request, {
+      moduleName: "serwist",
+      className: "Serwist",
+      funcName: "handleRequest",
+      paramName: "options.request",
+    });
+  }
+
+  const url = new URL(request.url, location.href);
+  if (!url.protocol.startsWith("http")) {
+    if (process.env.NODE_ENV !== "production") {
+      logger.debug("Router only supports URLs that start with 'http'.");
+    }
+    return;
+  }
+
+  const sameOrigin = url.origin === location.origin;
+  const { params, route } = findMatchingRoute(state, {
+    event,
+    request,
+    sameOrigin,
+    url,
+  });
+  let handler = route?.handler;
+
+  const debugMessages = [];
+  if (process.env.NODE_ENV !== "production") {
+    if (handler) {
+      debugMessages.push(["Found a route to handle this request:", route]);
+
+      if (params) {
+        debugMessages.push([`Passing the following params to the route's handler:`, params]);
+      }
+    }
+  }
+
+  // If we don't have a handler because there was no matching route, then
+  // fall back to defaultHandler if that's defined.
+  const method = request.method as HTTPMethod;
+  if (!handler && state.defaultHandlerMap.has(method)) {
+    if (process.env.NODE_ENV !== "production") {
+      debugMessages.push(`Failed to find a matching route. Falling back to the default handler for ${method}.`);
+    }
+    handler = state.defaultHandlerMap.get(method);
+  }
+
+  if (!handler) {
+    if (process.env.NODE_ENV !== "production") {
+      // No handler so Serwist will do nothing. If logs is set of debug
+      // i.e. verbose, we should print out this information.
+      logger.debug(`No route found for: ${getFriendlyURL(url)}`);
+    }
+    return;
+  }
+
+  if (process.env.NODE_ENV !== "production") {
+    // We have a handler, meaning Serwist is going to handle the route.
+    // print the routing details to the console.
+    logger.groupCollapsed(`Router is responding to: ${getFriendlyURL(url)}`);
+
+    for (const msg of debugMessages) {
+      if (Array.isArray(msg)) {
+        logger.log(...msg);
+      } else {
+        logger.log(msg);
+      }
+    }
+
+    logger.groupEnd();
+  }
+
+  // Wrap in try and catch in case the handle method throws a synchronous
+  // error. It should still callback to the catch handler.
+  let responsePromise: Promise<Response>;
+  try {
+    responsePromise = handler.handle({ url, request, event, params });
+  } catch (err) {
+    responsePromise = Promise.reject(err);
+  }
+
+  // Get route's catch handler, if it exists
+  const catchHandler = route?.catchHandler;
+
+  if (responsePromise instanceof Promise && (state.catchHandler || catchHandler)) {
+    responsePromise = responsePromise.catch(async (err) => {
+      // If there's a route catch handler, process that first
+      if (catchHandler) {
+        if (process.env.NODE_ENV !== "production") {
+          // Still include URL here as it will be async from the console group
+          // and may not make sense without the URL
+          logger.groupCollapsed(`Error thrown when responding to:  ${getFriendlyURL(url)}. Falling back to route's Catch Handler.`);
+          logger.error("Error thrown by:", route);
+          logger.error(err);
+          logger.groupEnd();
+        }
+
+        try {
+          return await catchHandler.handle({ url, request, event, params });
+        } catch (catchErr) {
+          if (catchErr instanceof Error) {
+            err = catchErr;
+          }
+        }
+      }
+
+      if (state.catchHandler) {
+        if (process.env.NODE_ENV !== "production") {
+          // Still include URL here as it will be async from the console group
+          // and may not make sense without the URL
+          logger.groupCollapsed(`Error thrown when responding to:  ${getFriendlyURL(url)}. Falling back to global Catch Handler.`);
+          logger.error("Error thrown by:", route);
+          logger.error(err);
+          logger.groupEnd();
+        }
+        return state.catchHandler.handle({ url, request, event });
+      }
+
+      throw err;
+    });
+  }
+
+  return responsePromise;
+};
+
+/**
+ * Checks a request and URL (and optionally an event) against the list of
+ * registered routes, and if there's a match, returns the corresponding
+ * route along with any params generated by the match.
+ *
+ * @param options
+ * @returns An object with `route` and `params` properties. They are populated
+ * if a matching route was found or `undefined` otherwise.
+ */
+export const findMatchingRoute = (
+  state: Serwist,
+  { url, sameOrigin, request, event }: RouteMatchCallbackOptions,
+): {
+  route?: Route;
+  params?: RouteHandlerCallbackOptions["params"];
+} => {
+  const routes = state.routes.get(request.method as HTTPMethod) || [];
+  for (const route of routes) {
+    let params: Promise<any> | undefined;
+    // route.match returns type any, not possible to change right now.
+    const matchResult = route.match({ url, sameOrigin, request, event });
+    if (matchResult) {
+      if (process.env.NODE_ENV !== "production") {
+        // Warn developers that using an async matchCallback is almost always
+        // not the right thing to do.
+        if (matchResult instanceof Promise) {
+          logger.warn(
+            `While routing ${getFriendlyURL(
+              url,
+            )}, an async matchCallback function was used. Please convert the following route to use a synchronous matchCallback function:`,
+            route,
+          );
+        }
+      }
+
+      // See https://github.com/GoogleChrome/workbox/issues/2079
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      params = matchResult;
+      if (Array.isArray(params) && params.length === 0) {
+        // Instead of passing an empty array in as params, use undefined.
+        params = undefined;
+      } else if (
+        matchResult.constructor === Object && // eslint-disable-line
+        Object.keys(matchResult).length === 0
+      ) {
+        // Instead of passing an empty object in as params, use undefined.
+        params = undefined;
+      } else if (typeof matchResult === "boolean") {
+        // For the boolean value true (rather than just something truth-y),
+        // don't set params.
+        // See https://github.com/GoogleChrome/workbox/pull/2134#issuecomment-513924353
+        params = undefined;
+      }
+
+      // Return early if have a match.
+      return { route, params };
+    }
+  }
+  // If no match was found above, return and empty object.
+  return {};
+};

package/src/{navigationPreload.ts → lib/navigation-preload.ts}

@@ -1,4 +1,4 @@
-import { logger } from "./utils/logger.js";
+import { logger } from "#utils/logger.js";
 
 declare const self: ServiceWorkerGlobalScope;
 

package/src/lib/{rangeRequests → range-requests}/RangeRequestsPlugin.ts

@@ -6,7 +6,7 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { SerwistPlugin } from "../../types.js";
+import type { StrategyPlugin } from "#lib/types.js";
 import { createPartialResponse } from "./createPartialResponse.js";
 
 /**
@@ -15,7 +15,7 @@ import { createPartialResponse } from "./createPartialResponse.js";
  * It does this by intercepting the `cachedResponseWillBeUsed` plugin callback
  * and returning the appropriate subset of the cached response body.
  */
-export class RangeRequestsPlugin implements SerwistPlugin {
+export class RangeRequestsPlugin implements StrategyPlugin {
   /**
    * @param options
    * @returns If request contains a `Range` header, then a
@@ -23,7 +23,7 @@ export class RangeRequestsPlugin implements SerwistPlugin {
    * returned. Otherwise, `cachedResponse` is returned as-is.
    * @private
    */
-  cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"] = async ({ request, cachedResponse }) => {
+  cachedResponseWillBeUsed: StrategyPlugin["cachedResponseWillBeUsed"] = async ({ request, cachedResponse }) => {
     // Only return a sliced response if there's something valid in the cache,
     // and there's a Range: header in the request.
     if (cachedResponse && request.headers.has("range")) {

package/src/lib/{rangeRequests → range-requests}/createPartialResponse.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { logger } from "../../utils/logger.js";
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
 import { calculateEffectiveBoundaries } from "./utils/calculateEffectiveBoundaries.js";
 import { parseRangeHeader } from "./utils/parseRangeHeader.js";
 

package/src/lib/range-requests/index.ts

@@ -0,0 +1,2 @@
+export { createPartialResponse } from "./createPartialResponse.js";
+export { RangeRequestsPlugin } from "./RangeRequestsPlugin.js";

package/src/lib/{rangeRequests → range-requests}/utils/calculateEffectiveBoundaries.ts

@@ -6,8 +6,8 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../../utils/SerwistError.js";
-import { assert } from "../../../utils/assert.js";
+import { assert } from "#utils/assert.js";
+import { SerwistError } from "#utils/SerwistError.js";
 
 /**
  * @param blob A source blob.

package/src/lib/{rangeRequests → range-requests}/utils/parseRangeHeader.ts

@@ -6,8 +6,8 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../../utils/SerwistError.js";
-import { assert } from "../../../utils/assert.js";
+import { assert } from "#utils/assert.js";
+import { SerwistError } from "#utils/SerwistError.js";
 
 /**
  * @param rangeHeader A `Range` header value.