serwist 9.0.12 → 10.0.0-preview.1

package/src/{legacy → controllers/PrecacheController}/PrecacheController.ts

@@ -1,82 +1,110 @@
-/*
-  Copyright 2019 Google LLC
-
-  Use of this source code is governed by an MIT-style
-  license that can be found in the LICENSE file or at
-  https://opensource.org/licenses/MIT.
-*/
-
 import { parallel } from "@serwist/utils";
-import { PrecacheStrategy } from "../lib/strategies/PrecacheStrategy.js";
-import type { Strategy } from "../lib/strategies/Strategy.js";
-import type { RouteHandlerCallback, SerwistPlugin } from "../types.js";
-import type { CleanupResult, InstallResult, PrecacheEntry } from "../types.js";
-import { PrecacheInstallReportPlugin } from "../utils/PrecacheInstallReportPlugin.js";
-import { SerwistError } from "../utils/SerwistError.js";
-import { assert } from "../utils/assert.js";
-import { cacheNames as privateCacheNames } from "../utils/cacheNames.js";
-import { createCacheKey } from "../utils/createCacheKey.js";
-import { logger } from "../utils/logger.js";
-import { printCleanupDetails } from "../utils/printCleanupDetails.js";
-import { printInstallDetails } from "../utils/printInstallDetails.js";
-import { waitUntil } from "../utils/waitUntil.js";
-import { PrecacheCacheKeyPlugin } from "./utils/PrecacheCacheKeyPlugin.js";
+import type { Strategy } from "../../lib/strategies/Strategy.js";
+import type { Controller, RouteHandlerCallback, UrlManipulation } from "../../types.js";
+import { assert } from "../../utils/assert.js";
+import { createCacheKey } from "../../utils/createCacheKey.js";
+import { logger } from "../../utils/logger.js";
+import { PrecacheInstallReportPlugin } from "./PrecacheInstallReportPlugin.js";
+import { SerwistError } from "../../utils/SerwistError.js";
+import { printInstallDetails } from "../../utils/printInstallDetails.js";
+import { printCleanupDetails } from "../../utils/printCleanupDetails.js";
+import { PrecacheStrategy } from "./PrecacheStrategy.js";
+import { PrecacheRoute } from "./PrecacheRoute.js";
+import type { Serwist } from "../../Serwist.js";
+import { NavigationRoute } from "../../NavigationRoute.js";
+import type { PrecacheStrategyOptions } from "./PrecacheStrategy.js";
+import { parsePrecacheOptions } from "./parsePrecacheOptions.js";
+
+export interface PrecacheEntry {
+  integrity?: string;
+  url: string;
+  revision?: string | null;
+}
 
-// Give TypeScript the correct global.
-declare const self: ServiceWorkerGlobalScope;
+export interface PrecacheRouteOptions {
+  /**
+   * Tells Serwist to check the precache for an entry whose URL is the request URL appended
+   * with the specified value. Only applies if the request URL ends with "/".
+   *
+   * @default "index.html"
+   */
+  directoryIndex?: string | null;
+  /**
+   * An array of `RegExp` objects matching search params that should be removed when looking
+   * for a precache match.
+   */
+  ignoreURLParametersMatching?: RegExp[];
+  /**
+   * Tells Serwist to check the precache for an entry whose URL is the request URL appended
+   * with ".html".
+   *
+   * @default true
+   */
+  cleanURLs?: boolean;
+  /**
+   * A function that should take a URL and return an array of alternative URLs that should
+   * be checked for precache matches.
+   */
+  urlManipulation?: UrlManipulation;
+}
 
-interface PrecacheControllerOptions {
+export interface PrecacheControllerOptions {
   /**
    * The cache to use for precaching.
    */
   cacheName?: string;
   /**
-   * Plugins to use when precaching as well as responding to fetch
-   * events for precached assets.
-   */
-  plugins?: SerwistPlugin[];
-  /**
-   * Whether to attempt to get the response from the network if there's
-   * a precache miss.
+   * Whether outdated caches should be removed.
+   *
+   * @default false
    */
-  fallbackToNetwork?: boolean;
+  cleanupOutdatedCaches?: boolean;
   /**
    * The number of precache requests that should be made concurrently.
    *
-   * @default 1
+   * @default 10
+   */
+  concurrency?: number;
+  /**
+   * An URL that should point to a HTML file with which navigation requests for URLs that aren't
+   * precached will be fulfilled.
+   */
+  navigateFallback?: string;
+  /**
+   * URLs that should be allowed to use the `navigateFallback` handler.
+   */
+  navigateFallbackAllowlist?: RegExp[];
+  /**
+   * URLs that should not be allowed to use the `navigateFallback` handler. This takes precedence
+   * over `navigateFallbackAllowlist`.
    */
-  concurrentPrecaching?: number;
+  navigateFallbackDenylist?: RegExp[];
 }
 
-/**
- * Performs efficient precaching of assets.
- * @deprecated
- */
-export class PrecacheController {
-  private _installAndActiveListenersAdded?: boolean;
-  private _concurrentPrecaching: number;
-  private readonly _strategy: Strategy;
+export interface PrecacheOptions extends PrecacheStrategyOptions, PrecacheRouteOptions, PrecacheControllerOptions {}
+
+export class PrecacheController implements Controller {
   private readonly _urlsToCacheKeys: Map<string, string> = new Map();
   private readonly _urlsToCacheModes: Map<string, "reload" | "default" | "no-store" | "no-cache" | "force-cache" | "only-if-cached"> = new Map();
   private readonly _cacheKeysToIntegrities: Map<string, string> = new Map();
-
+  private readonly _strategy: Strategy;
+  private _options: PrecacheControllerOptions;
+  private _routeOptions: PrecacheRouteOptions;
   /**
    * Create a new PrecacheController.
    *
    * @param options
    */
-  constructor({ cacheName, plugins = [], fallbackToNetwork = true, concurrentPrecaching = 1 }: PrecacheControllerOptions = {}) {
-    this._concurrentPrecaching = concurrentPrecaching;
-    this._strategy = new PrecacheStrategy({
-      cacheName: privateCacheNames.getPrecacheName(cacheName),
-      plugins: [...plugins, new PrecacheCacheKeyPlugin({ precacheController: this })],
-      fallbackToNetwork,
-    });
+  constructor(entries: (PrecacheEntry | string)[], precacheOptions?: PrecacheOptions) {
+    const { strategyOptions, routeOptions, controllerOptions } = parsePrecacheOptions(this, precacheOptions);
+    this.addToCacheList(entries);
+    this._strategy = new PrecacheStrategy(strategyOptions);
+    this._options = controllerOptions;
+    this._routeOptions = routeOptions;
     // Bind the install and activate methods to the instance.
     this.install = this.install.bind(this);
     this.activate = this.activate.bind(this);
   }
-
   /**
    * The strategy created by this controller and
    * used to cache assets and respond to `fetch` events.
@@ -84,38 +112,17 @@ export class PrecacheController {
   get strategy(): Strategy {
     return this._strategy;
   }
-
   /**
-   * Adds items to the precache list, removing any duplicates and
-   * stores the files in the precache cache when the service
-   * worker installs.
-   *
-   * This method can be called multiple times.
-   *
-   * @param entries Array of entries to precache.
-   */
-  precache(entries: (PrecacheEntry | string)[]): void {
-    this.addToCacheList(entries);
-
-    if (!this._installAndActiveListenersAdded) {
-      self.addEventListener("install", this.install);
-      self.addEventListener("activate", this.activate);
-      this._installAndActiveListenersAdded = true;
-    }
-  }
-
-  /**
-   * This method will add items to the precache list, removing duplicates
-   * and ensuring the information is valid.
+   * Adds items to the cache list, removing duplicates and ensuring the information is valid.
    *
    * @param entries Array of entries to precache.
    */
   addToCacheList(entries: (PrecacheEntry | string)[]): void {
     if (process.env.NODE_ENV !== "production") {
       assert!.isArray(entries, {
-        moduleName: "serwist/legacy",
+        moduleName: "serwist",
         className: "PrecacheController",
-        funcName: "addToCacheList",
+        funcName: "addEntries",
         paramName: "entries",
       });
     }
@@ -154,7 +161,7 @@ export class PrecacheController {
       if (urlsToWarnAbout.length > 0) {
         const warningMessage = `Serwist is precaching URLs without revision info: ${urlsToWarnAbout.join(
           ", ",
-        )}\nThis is generally NOT safe. Learn more at https://bit.ly/wb-precache`;
+        )}\nThis is generally NOT safe, as you risk serving outdated assets.`;
         if (process.env.NODE_ENV === "production") {
           // Use console directly to display this warning without bloating
           // bundle sizes by pulling in all of the logger codebase in prod.
@@ -165,83 +172,64 @@ export class PrecacheController {
       }
     }
   }
-
-  /**
-   * Precaches new and updated assets. Call this method from the service worker
-   * install event.
-   *
-   * Note: this method calls `event.waitUntil()` for you, so you do not need
-   * to call it yourself in your event handlers.
-   *
-   * @param event
-   * @returns
-   */
-  install(event: ExtendableEvent): Promise<InstallResult> {
-    return waitUntil<InstallResult>(event, async () => {
-      const installReportPlugin = new PrecacheInstallReportPlugin();
-      this.strategy.plugins.push(installReportPlugin);
-
-      await parallel(this._concurrentPrecaching, Array.from(this._urlsToCacheKeys.entries()), async ([url, cacheKey]): Promise<void> => {
-        const integrity = this._cacheKeysToIntegrities.get(cacheKey);
-        const cacheMode = this._urlsToCacheModes.get(url);
-
-        const request = new Request(url, {
-          integrity,
-          cache: cacheMode,
-          credentials: "same-origin",
-        });
-
-        await Promise.all(
-          this.strategy.handleAll({
-            event,
-            request,
-            url: new URL(request.url),
-            params: { cacheKey },
-          }),
-        );
+  init(serwist: Serwist) {
+    serwist.registerRoute(new PrecacheRoute(this, this._routeOptions));
+
+    if (this._options.navigateFallback) {
+      serwist.registerRoute(
+        new NavigationRoute(this.createHandlerBoundToUrl(this._options.navigateFallback), {
+          allowlist: this._options.navigateFallbackAllowlist,
+          denylist: this._options.navigateFallbackDenylist,
+        }),
+      );
+    }
+  }
+  async install(event: ExtendableEvent): Promise<void> {
+    const installReportPlugin = new PrecacheInstallReportPlugin();
+    this._strategy.plugins.push(installReportPlugin);
+    await parallel(this._options.concurrency!, Array.from(this._urlsToCacheKeys.entries()), async ([url, cacheKey]): Promise<void> => {
+      const integrity = this._cacheKeysToIntegrities.get(cacheKey);
+      const cacheMode = this._urlsToCacheModes.get(url);
+
+      const request = new Request(url, {
+        integrity,
+        cache: cacheMode,
+        credentials: "same-origin",
       });
 
-      const { updatedURLs, notUpdatedURLs } = installReportPlugin;
-
-      if (process.env.NODE_ENV !== "production") {
-        printInstallDetails(updatedURLs, notUpdatedURLs);
-      }
-
-      return { updatedURLs, notUpdatedURLs };
+      await Promise.all(
+        this._strategy.handleAll({
+          event,
+          request,
+          url: new URL(request.url),
+          params: { cacheKey },
+        }),
+      );
     });
-  }
 
-  /**
-   * Deletes assets that are no longer present in the current precache manifest.
-   * Call this method from the service worker activate event.
-   *
-   * Note: this method calls `event.waitUntil()` for you, so you do not need
-   * to call it yourself in your event handlers.
-   *
-   * @param event
-   * @returns
-   */
-  activate(event: ExtendableEvent): Promise<CleanupResult> {
-    return waitUntil<CleanupResult>(event, async () => {
-      const cache = await self.caches.open(this.strategy.cacheName);
-      const currentlyCachedRequests = await cache.keys();
-      const expectedCacheKeys = new Set(this._urlsToCacheKeys.values());
+    const { updatedURLs, notUpdatedURLs } = installReportPlugin;
 
-      const deletedCacheRequests: string[] = [];
+    if (process.env.NODE_ENV !== "production") {
+      printInstallDetails(updatedURLs, notUpdatedURLs);
+    }
+  }
+  async activate(): Promise<void> {
+    const cache = await self.caches.open(this._strategy.cacheName);
+    const currentlyCachedRequests = await cache.keys();
+    const expectedCacheKeys = new Set(this._urlsToCacheKeys.values());
 
-      for (const request of currentlyCachedRequests) {
-        if (!expectedCacheKeys.has(request.url)) {
-          await cache.delete(request);
-          deletedCacheRequests.push(request.url);
-        }
-      }
+    const deletedCacheRequests: string[] = [];
 
-      if (process.env.NODE_ENV !== "production") {
-        printCleanupDetails(deletedCacheRequests);
+    for (const request of currentlyCachedRequests) {
+      if (!expectedCacheKeys.has(request.url)) {
+        await cache.delete(request);
+        deletedCacheRequests.push(request.url);
       }
+    }
 
-      return { deletedCacheRequests };
-    });
+    if (process.env.NODE_ENV !== "production") {
+      printCleanupDetails(deletedCacheRequests);
+    }
   }
 
   /**
@@ -250,7 +238,7 @@ export class PrecacheController {
    *
    * @returns A URL to cache key mapping.
    */
-  getURLsToCacheKeys(): Map<string, string> {
+  getUrlsToPrecacheKeys(): Map<string, string> {
     return this._urlsToCacheKeys;
   }
 
@@ -260,20 +248,20 @@ export class PrecacheController {
    *
    * @returns The precached URLs.
    */
-  getCachedURLs(): string[] {
+  getPrecachedUrls(): string[] {
     return [...this._urlsToCacheKeys.keys()];
   }
 
   /**
    * Returns the cache key used for storing a given URL. If that URL is
-   * unversioned, like `/index.html', then the cache key will be the original
+   * unversioned, like "/index.html", then the cache key will be the original
    * URL with a search parameter appended to it.
    *
    * @param url A URL whose cache key you want to look up.
    * @returns The versioned URL that corresponds to a cache key
    * for the original URL, or undefined if that URL isn't precached.
    */
-  getCacheKeyForURL(url: string): string | undefined {
+  getPrecacheKeyForUrl(url: string): string | undefined {
     const urlObject = new URL(url, location.href);
     return this._urlsToCacheKeys.get(urlObject.href);
   }
@@ -283,7 +271,7 @@ export class PrecacheController {
    * @returns The subresource integrity associated with the cache key,
    * or undefined if it's not set.
    */
-  getIntegrityForCacheKey(cacheKey: string): string | undefined {
+  getIntegrityForPrecacheKey(cacheKey: string): string | undefined {
     return this._cacheKeysToIntegrities.get(cacheKey);
   }
 
@@ -307,9 +295,9 @@ export class PrecacheController {
    */
   async matchPrecache(request: string | Request): Promise<Response | undefined> {
     const url = request instanceof Request ? request.url : request;
-    const cacheKey = this.getCacheKeyForURL(url);
+    const cacheKey = this.getPrecacheKeyForUrl(url);
     if (cacheKey) {
-      const cache = await self.caches.open(this.strategy.cacheName);
+      const cache = await self.caches.open(this._strategy.cacheName);
       return cache.match(cacheKey);
     }
     return undefined;
@@ -322,8 +310,8 @@ export class PrecacheController {
    * @param url The precached URL which will be used to lookup the response.
    * @return
    */
-  createHandlerBoundToURL(url: string): RouteHandlerCallback {
-    const cacheKey = this.getCacheKeyForURL(url);
+  createHandlerBoundToUrl(url: string): RouteHandlerCallback {
+    const cacheKey = this.getPrecacheKeyForUrl(url);
     if (!cacheKey) {
       throw new SerwistError("non-precached-url", { url });
     }
@@ -331,7 +319,7 @@ export class PrecacheController {
       options.request = new Request(url);
       options.params = { cacheKey, ...options.params };
 
-      return this.strategy.handle(options);
+      return this._strategy.handle(options);
     };
   }
 }

package/src/{utils → controllers/PrecacheController}/PrecacheInstallReportPlugin.ts

@@ -6,7 +6,7 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { SerwistPlugin, SerwistPluginCallbackParam } from "../types.js";
+import type { StrategyPlugin, StrategyPluginCallbackParam } from "../../types.js";
 
 /**
  * A plugin designed to determine the number of assets that were updated (or not updated)
@@ -14,22 +14,22 @@ import type { SerwistPlugin, SerwistPluginCallbackParam } from "../types.js";
  *
  * @private
  */
-export class PrecacheInstallReportPlugin implements SerwistPlugin {
+export class PrecacheInstallReportPlugin implements StrategyPlugin {
   updatedURLs: string[] = [];
   notUpdatedURLs: string[] = [];
 
-  handlerWillStart: SerwistPlugin["handlerWillStart"] = async ({ request, state }: SerwistPluginCallbackParam["handlerWillStart"]) => {
+  handlerWillStart: StrategyPlugin["handlerWillStart"] = async ({ request, state }: StrategyPluginCallbackParam["handlerWillStart"]) => {
     // TODO: `state` should never be undefined...
     if (state) {
       state.originalRequest = request;
     }
   };
 
-  cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"] = async ({
+  cachedResponseWillBeUsed: StrategyPlugin["cachedResponseWillBeUsed"] = async ({
     event,
     state,
     cachedResponse,
-  }: SerwistPluginCallbackParam["cachedResponseWillBeUsed"]) => {
+  }: StrategyPluginCallbackParam["cachedResponseWillBeUsed"]) => {
     if (event.type === "install") {
       if (state?.originalRequest && state.originalRequest instanceof Request) {
         // TODO: `state` should never be undefined...

package/src/{PrecacheRoute.ts → controllers/PrecacheController/PrecacheRoute.ts}

@@ -6,13 +6,12 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { Route } from "./Route.js";
-import type { Serwist } from "./Serwist.js";
-import type { RouteMatchCallback, RouteMatchCallbackOptions } from "./types.js";
-import type { PrecacheRouteOptions } from "./types.js";
-import { generateURLVariations } from "./utils/generateURLVariations.js";
-import { getFriendlyURL } from "./utils/getFriendlyURL.js";
-import { logger } from "./utils/logger.js";
+import { Route } from "../../Route.js";
+import type { RouteMatchCallback, RouteMatchCallbackOptions } from "../../types.js";
+import { generateURLVariations } from "../../utils/generateURLVariations.js";
+import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
+import { logger } from "../../utils/logger.js";
+import type { PrecacheController, PrecacheRouteOptions } from "./PrecacheController.js";
 
 /**
  * A subclass of {@linkcode Route} that takes a {@linkcode Serwist} instance and uses it to match
@@ -20,17 +19,17 @@ import { logger } from "./utils/logger.js";
  */
 export class PrecacheRoute extends Route {
   /**
-   * @param serwist A {@linkcode Serwist} instance.
+   * @param controller A {@linkcode PrecacheController} instance.
    * @param options Options to control how requests are matched
    * against the list of precached URLs.
    */
-  constructor(serwist: Serwist, options?: PrecacheRouteOptions) {
+  constructor(controller: PrecacheController, options?: PrecacheRouteOptions) {
     const match: RouteMatchCallback = ({ request }: RouteMatchCallbackOptions) => {
-      const urlsToCacheKeys = serwist.getUrlsToPrecacheKeys();
+      const urlsToCacheKeys = controller.getUrlsToPrecacheKeys();
       for (const possibleURL of generateURLVariations(request.url, options)) {
         const cacheKey = urlsToCacheKeys.get(possibleURL);
         if (cacheKey) {
-          const integrity = serwist.getIntegrityForPrecacheKey(cacheKey);
+          const integrity = controller.getIntegrityForPrecacheKey(cacheKey);
           return { cacheKey, integrity };
         }
       }
@@ -40,6 +39,6 @@ export class PrecacheRoute extends Route {
       return;
     };
 
-    super(match, serwist.precacheStrategy);
+    super(match, controller.strategy);
   }
 }

package/src/{lib/strategies → controllers/PrecacheController}/PrecacheStrategy.ts

@@ -7,15 +7,15 @@
 */
 
 import { copyResponse } from "../../copyResponse.js";
-import type { SerwistPlugin } from "../../types.js";
+import type { StrategyPlugin } from "../../types.js";
 import { SerwistError } from "../../utils/SerwistError.js";
 import { cacheNames as privateCacheNames } from "../../utils/cacheNames.js";
 import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
 import { logger } from "../../utils/logger.js";
 import type { Serwist } from "../../Serwist.js";
-import type { StrategyOptions } from "./Strategy.js";
-import { Strategy } from "./Strategy.js";
-import type { StrategyHandler } from "./StrategyHandler.js";
+import type { StrategyOptions } from "../../lib/strategies/Strategy.js";
+import { Strategy } from "../../lib/strategies/Strategy.js";
+import type { StrategyHandler } from "../../lib/strategies/StrategyHandler.js";
 
 export interface PrecacheStrategyOptions extends StrategyOptions {
   /**
@@ -39,7 +39,7 @@ export interface PrecacheStrategyOptions extends StrategyOptions {
 export class PrecacheStrategy extends Strategy {
   private readonly _fallbackToNetwork: boolean;
 
-  static readonly defaultPrecacheCacheabilityPlugin: SerwistPlugin = {
+  static readonly defaultPrecacheCacheabilityPlugin: StrategyPlugin = {
     async cacheWillUpdate({ response }) {
       if (!response || response.status >= 400) {
         return null;
@@ -49,7 +49,7 @@ export class PrecacheStrategy extends Strategy {
     },
   };
 
-  static readonly copyRedirectedCacheableResponsesPlugin: SerwistPlugin = {
+  static readonly copyRedirectedCacheableResponsesPlugin: StrategyPlugin = {
     async cacheWillUpdate({ response }) {
       return response.redirected ? await copyResponse(response) : response;
     },
@@ -63,7 +63,7 @@ export class PrecacheStrategy extends Strategy {
 
     super(options);
 
-    this._fallbackToNetwork = options.fallbackToNetwork === false ? false : true;
+    this._fallbackToNetwork = options.fallbackToNetwork !== false;
 
     // Redirected responses cannot be used to satisfy a navigation request, so
     // any redirected response must be "copied" rather than cloned, so the new

package/src/controllers/PrecacheController/parsePrecacheOptions.ts

@@ -0,0 +1,46 @@
+import type { PrecacheStrategyOptions } from "./PrecacheStrategy.js";
+import type { PrecacheController, PrecacheControllerOptions, PrecacheOptions, PrecacheRouteOptions } from "./PrecacheController.js";
+import type { Require } from "@serwist/utils";
+import { privateCacheNames } from "../../index.internal.js";
+import { PrecacheCacheKeyPlugin } from "./PrecacheCacheKeyPlugin.js";
+
+export const parsePrecacheOptions = (
+  controller: PrecacheController,
+  {
+    cacheName,
+    plugins,
+    fetchOptions,
+    matchOptions,
+    fallbackToNetwork,
+    directoryIndex,
+    ignoreURLParametersMatching,
+    cleanURLs,
+    urlManipulation,
+    cleanupOutdatedCaches,
+    concurrency,
+    navigateFallback,
+    navigateFallbackAllowlist,
+    navigateFallbackDenylist,
+  }: PrecacheOptions = {},
+) => ({
+  strategyOptions: {
+    cacheName: privateCacheNames.getPrecacheName(cacheName),
+    plugins: [...(plugins ?? []), new PrecacheCacheKeyPlugin({ precacheController: controller })],
+    fetchOptions,
+    matchOptions,
+    fallbackToNetwork,
+  } satisfies Require<PrecacheStrategyOptions, "cacheName" | "plugins">,
+  routeOptions: {
+    directoryIndex,
+    ignoreURLParametersMatching,
+    cleanURLs,
+    urlManipulation,
+  } satisfies PrecacheRouteOptions,
+  controllerOptions: {
+    cleanupOutdatedCaches,
+    concurrency: concurrency ?? 10,
+    navigateFallback,
+    navigateFallbackAllowlist,
+    navigateFallbackDenylist,
+  } satisfies Require<PrecacheControllerOptions, "concurrency">,
+});