serwist 10.0.0-preview.7 → 10.0.0-preview.9

package/src/lib/{precaching/PrecacheFallbackPlugin.ts → extensions/precache/plugin-fallback.ts}

@@ -5,10 +5,10 @@
   license that can be found in the LICENSE file or at
   https://opensource.org/licenses/MIT.
 */
-
-import type { PrecacheController } from "#lib/controllers/PrecacheController/PrecacheController.js";
-import type { Serwist } from "../../Serwist.js";
-import type { HandlerDidErrorCallbackParam, StrategyPlugin } from "../../types.js";
+import type { Serwist } from "#lib/core.js";
+import { handleRequest } from "#lib/functions/router.js";
+import { Serwist as LegacySerwist } from "#lib/serwist.js";
+import type { HandlerDidErrorCallbackParam, StrategyPlugin } from "#lib/types.js";
 
 export interface PrecacheFallbackEntry {
   /**
@@ -28,15 +28,10 @@ export interface PrecacheFallbackPluginOptions {
    * if the associated strategy can't generate a response.
    */
   fallbackUrls: (string | PrecacheFallbackEntry)[];
-  /**
-   * A {@linkcode PrecacheController} instance.
-   */
-  precacheController: PrecacheController;
   /**
    * A {@linkcode Serwist} instance.
-   * @deprecated Use `precacheController` instead.
    */
-  serwist?: Serwist;
+  serwist: LegacySerwist | Serwist;
 }
 
 /**
@@ -49,21 +44,17 @@ export interface PrecacheFallbackPluginOptions {
  */
 export class PrecacheFallbackPlugin implements StrategyPlugin {
   private readonly _fallbackUrls: (string | PrecacheFallbackEntry)[];
-  private readonly _precacheController: PrecacheController;
+  private readonly _serwist: Serwist;
 
   /**
    * Constructs a new instance with the associated `fallbackUrls`.
    *
    * @param config
    */
-  constructor({ fallbackUrls, precacheController, serwist }: PrecacheFallbackPluginOptions) {
+  constructor({ fallbackUrls, serwist }: PrecacheFallbackPluginOptions) {
     this._fallbackUrls = fallbackUrls;
     // TODO(ducanhgh): remove in v11.
-    if (!serwist) {
-      this._precacheController = precacheController;
-    } else {
-      this._precacheController = serwist.precache;
-    }
+    this._serwist = serwist instanceof LegacySerwist ? serwist.state : serwist;
   }
 
   /**
@@ -74,14 +65,24 @@ export class PrecacheFallbackPlugin implements StrategyPlugin {
   async handlerDidError(param: HandlerDidErrorCallbackParam) {
     for (const fallback of this._fallbackUrls) {
       if (typeof fallback === "string") {
-        const fallbackResponse = await this._precacheController.matchPrecache(fallback);
+        const fallbackResponse = handleRequest(this._serwist, {
+          request: new Request(fallback, {
+            credentials: "same-origin",
+          }),
+          event: param.event,
+        });
         if (fallbackResponse !== undefined) {
-          return fallbackResponse;
+          return await fallbackResponse;
         }
       } else if (fallback.matcher(param)) {
-        const fallbackResponse = await this._precacheController.matchPrecache(fallback.url);
+        const fallbackResponse = handleRequest(this._serwist, {
+          request: new Request(fallback.url, {
+            credentials: "same-origin",
+          }),
+          event: param.event,
+        });
         if (fallbackResponse !== undefined) {
-          return fallbackResponse;
+          return await fallbackResponse;
         }
       }
     }

package/src/lib/{controllers/PrecacheController/PrecacheInstallReportPlugin.ts → extensions/precache/plugin-install-report.ts}

@@ -6,7 +6,7 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { StrategyPlugin, StrategyPluginCallbackParam } from "../../../types.js";
+import type { StrategyPlugin, StrategyPluginCallbackParam } from "#lib/types.js";
 
 /**
  * A plugin designed to determine the number of assets that were updated (or not updated)

package/src/lib/extensions/precache/route.ts

@@ -0,0 +1,72 @@
+/*
+  Copyright 2020 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 type { Serwist } from "#lib/core.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, UrlManipulation } from "../../types.js";
+import type { Precache } from "./extension.js";
+
+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;
+}
+
+/**
+ * A subclass of {@linkcode Route} that takes a {@linkcode Serwist} instance and uses it to match
+ * incoming requests and handle fetching responses from the precache.
+ */
+export class PrecacheRoute extends Route {
+  /**
+   * @param precache A {@linkcode Precache} instance.
+   * @param options Options to control how requests are matched
+   * against the list of precached URLs.
+   */
+  constructor(precache: Precache, options?: PrecacheRouteOptions) {
+    const match: RouteMatchCallback = ({ request }: RouteMatchCallbackOptions) => {
+      const urlsToCacheKeys = precache.getUrlsToPrecacheKeys();
+      for (const possibleURL of generateURLVariations(request.url, options)) {
+        const cacheKey = urlsToCacheKeys.get(possibleURL);
+        if (cacheKey) {
+          const integrity = precache.getIntegrityForPrecacheKey(cacheKey);
+          return { cacheKey, integrity };
+        }
+      }
+      if (process.env.NODE_ENV !== "production") {
+        logger.debug(`Precaching did not find a match for ${getFriendlyURL(request.url)}.`);
+      }
+      return;
+    };
+
+    super(match, precache.strategy);
+  }
+}

package/src/lib/{controllers/PrecacheController/PrecacheStrategy.ts → extensions/precache/strategy.ts}

@@ -6,13 +6,13 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "#utils/SerwistError.js";
+import type { Serwist } from "#lib/core.js";
+import type { StrategyPlugin } from "#lib/types.js";
+import { copyResponse } from "#lib/utils.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 { copyResponse } from "../../../copyResponse.js";
-import type { StrategyPlugin } from "../../../types.js";
+import { SerwistError } from "#utils/SerwistError.js";
 import type { StrategyOptions } from "../../strategies/Strategy.js";
 import { Strategy } from "../../strategies/Strategy.js";
 import type { StrategyHandler } from "../../strategies/StrategyHandler.js";
@@ -103,7 +103,7 @@ export class PrecacheStrategy extends Strategy {
   }
 
   async _handleFetch(request: Request, handler: StrategyHandler): Promise<Response> {
-    let response: Response | undefined = undefined;
+    let response: Response | undefined;
 
     const params = (handler.params || {}) as {
       cacheKey?: string;

package/src/lib/{controllers/RuntimeCacheController.ts → extensions/runtime-cache.ts}

@@ -1,8 +1,10 @@
 import { parallel } from "@serwist/utils";
-import type { Serwist } from "../../Serwist.js";
-import type { Controller, RuntimeCaching } from "../../types.js";
-import { type PrecacheFallbackEntry, PrecacheFallbackPlugin } from "../precaching/PrecacheFallbackPlugin.js";
+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;
@@ -22,7 +24,7 @@ export interface FallbacksOptions {
   entries: FallbackEntry[];
 }
 
-export interface RuntimeCacheControllerOptions {
+export interface RuntimeCacheOptions {
   /**
    * URLs that should be cached as the service worker is installed.
    */
@@ -41,10 +43,10 @@ export interface RuntimeCacheControllerOptions {
   fallbacks?: FallbacksOptions;
 }
 
-export class RuntimeCacheController implements Controller {
+export class RuntimeCache implements Extension {
   _entries: RuntimeCaching[];
-  _options: RuntimeCacheControllerOptions;
-  constructor(entries: RuntimeCaching[], options: RuntimeCacheControllerOptions = {}) {
+  _options: RuntimeCacheOptions;
+  constructor(entries: RuntimeCaching[], options: RuntimeCacheOptions = {}) {
     this._entries = entries;
     this._options = options;
     this.init = this.init.bind(this);
@@ -55,7 +57,7 @@ export class RuntimeCacheController implements Controller {
     if (this._options.fallbacks !== undefined) {
       const fallbackPlugin = new PrecacheFallbackPlugin({
         fallbackUrls: this._options.fallbacks.entries,
-        precacheController: serwist.precache,
+        serwist,
       });
 
       this._entries.forEach((cacheEntry) => {
@@ -69,7 +71,7 @@ export class RuntimeCacheController implements Controller {
       });
     }
     for (const entry of this._entries) {
-      serwist.registerCapture(entry.matcher, entry.handler, entry.method);
+      registerCapture(serwist, entry.matcher, entry.handler, entry.method);
     }
   }
 
@@ -80,11 +82,16 @@ export class RuntimeCacheController implements Controller {
         const request =
           entry instanceof Request
             ? entry
-            : new Request(typeof entry === "string" ? entry : entry.url, {
-                integrity: typeof entry !== "string" ? entry.integrity : undefined,
-                credentials: "same-origin",
-              });
-        await serwist.handleRequest({
+            : typeof entry === "string"
+              ? new Request(entry, {
+                  credentials: "same-origin",
+                })
+              : new Request(entry.url, {
+                  integrity: entry.integrity,
+                  credentials: "same-origin",
+                });
+
+        await handleRequest(serwist, {
           request,
           event,
         });

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]>;
+    }
+  }
+}