@serwist/sw 9.0.0-preview.17 → 9.0.0-preview.18

package/src/precaching/utils/createCacheKey.ts

@@ -0,0 +1,68 @@
+/*
+  Copyright 2018 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 { SerwistError } from "@serwist/core/internal";
+
+import type { PrecacheEntry } from "../types.js";
+
+interface CacheKey {
+  cacheKey: string;
+  url: string;
+}
+
+// Name of the search parameter used to store revision info.
+const REVISION_SEARCH_PARAM = "__WB_REVISION__";
+
+/**
+ * Converts a manifest entry into a versioned URL suitable for precaching.
+ *
+ * @param entry
+ * @returns A URL with versioning info.
+ *
+ * @private
+ */
+export function createCacheKey(entry: PrecacheEntry | string): CacheKey {
+  if (!entry) {
+    throw new SerwistError("add-to-cache-list-unexpected-type", { entry });
+  }
+
+  // If a precache manifest entry is a string, it's assumed to be a versioned
+  // URL, like '/app.abcd1234.js'. Return as-is.
+  if (typeof entry === "string") {
+    const urlObject = new URL(entry, location.href);
+    return {
+      cacheKey: urlObject.href,
+      url: urlObject.href,
+    };
+  }
+
+  const { revision, url } = entry;
+  if (!url) {
+    throw new SerwistError("add-to-cache-list-unexpected-type", { entry });
+  }
+
+  // If there's just a URL and no revision, then it's also assumed to be a
+  // versioned URL.
+  if (!revision) {
+    const urlObject = new URL(url, location.href);
+    return {
+      cacheKey: urlObject.href,
+      url: urlObject.href,
+    };
+  }
+
+  // Otherwise, construct a properly versioned URL using the custom Serwist
+  // search parameter along with the revision info.
+  const cacheKeyURL = new URL(url, location.href);
+  const originalURL = new URL(url, location.href);
+  cacheKeyURL.searchParams.set(REVISION_SEARCH_PARAM, revision);
+  return {
+    cacheKey: cacheKeyURL.href,
+    url: originalURL.href,
+  };
+}

package/src/precaching/utils/deleteOutdatedCaches.ts

@@ -0,0 +1,40 @@
+/*
+  Copyright 2018 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.
+*/
+
+// Give TypeScript the correct global.
+declare let self: ServiceWorkerGlobalScope;
+
+const SUBSTRING_TO_FIND = "-precache-";
+
+/**
+ * Cleans up incompatible precaches that were created by older versions of
+ * Serwist, by a service worker registered under the current scope.
+ *
+ * This is meant to be called as part of the `activate` event.
+ *
+ * This should be safe to use as long as you don't include `substringToFind`
+ * (defaulting to `-precache-`) in your non-precache cache names.
+ *
+ * @param currentPrecacheName The cache name currently in use for
+ * precaching. This cache won't be deleted.
+ * @param substringToFind Cache names which include this
+ * substring will be deleted (excluding `currentPrecacheName`).
+ * @returns A list of all the cache names that were deleted.
+ * @private
+ */
+export const deleteOutdatedCaches = async (currentPrecacheName: string, substringToFind: string = SUBSTRING_TO_FIND): Promise<string[]> => {
+  const cacheNames = await self.caches.keys();
+
+  const cacheNamesToDelete = cacheNames.filter((cacheName) => {
+    return cacheName.includes(substringToFind) && cacheName.includes(self.registration.scope) && cacheName !== currentPrecacheName;
+  });
+
+  await Promise.all(cacheNamesToDelete.map((cacheName) => self.caches.delete(cacheName)));
+
+  return cacheNamesToDelete;
+};

package/src/precaching/utils/generateURLVariations.ts

@@ -0,0 +1,55 @@
+/*
+  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 type { PrecacheRouteOptions } from "../types.js";
+import { removeIgnoredSearchParams } from "./removeIgnoredSearchParams.js";
+
+/**
+ * Generator function that yields possible variations on the original URL to
+ * check, one at a time.
+ *
+ * @param url
+ * @param options
+ *
+ * @private
+ */
+export function* generateURLVariations(
+  url: string,
+  {
+    ignoreURLParametersMatching = [/^utm_/, /^fbclid$/],
+    directoryIndex = "index.html",
+    cleanURLs = true,
+    urlManipulation,
+  }: PrecacheRouteOptions = {},
+): Generator<string, void, unknown> {
+  const urlObject = new URL(url, location.href);
+  urlObject.hash = "";
+  yield urlObject.href;
+
+  const urlWithoutIgnoredParams = removeIgnoredSearchParams(urlObject, ignoreURLParametersMatching);
+  yield urlWithoutIgnoredParams.href;
+
+  if (directoryIndex && urlWithoutIgnoredParams.pathname.endsWith("/")) {
+    const directoryURL = new URL(urlWithoutIgnoredParams.href);
+    directoryURL.pathname += directoryIndex;
+    yield directoryURL.href;
+  }
+
+  if (cleanURLs) {
+    const cleanURL = new URL(urlWithoutIgnoredParams.href);
+    cleanURL.pathname += ".html";
+    yield cleanURL.href;
+  }
+
+  if (urlManipulation) {
+    const additionalURLs = urlManipulation({ url: urlObject });
+    for (const urlToAttempt of additionalURLs) {
+      yield urlToAttempt.href;
+    }
+  }
+}

package/src/precaching/utils/getCacheKeyForURL.ts

@@ -0,0 +1,36 @@
+/*
+  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 type { PrecacheRouteOptions } from "../types.js";
+import { generateURLVariations } from "./generateURLVariations.js";
+import { getOrCreatePrecacheController } from "./getOrCreatePrecacheController.js";
+
+/**
+ * This function will take the request URL and manipulate it based on the
+ * configuration options.
+ *
+ * @param url
+ * @param options
+ * @returns Returns the URL in the cache that matches the request,
+ * if possible.
+ *
+ * @private
+ */
+export const getCacheKeyForURL = (url: string, options: PrecacheRouteOptions): string | undefined => {
+  const precacheController = getOrCreatePrecacheController();
+
+  const urlsToCacheKeys = precacheController.getURLsToCacheKeys();
+  for (const possibleURL of generateURLVariations(url, options)) {
+    const possibleCacheKey = urlsToCacheKeys.get(possibleURL);
+    if (possibleCacheKey) {
+      return possibleCacheKey;
+    }
+  }
+
+  return undefined;
+};

package/src/precaching/utils/getOrCreatePrecacheController.ts

@@ -0,0 +1,22 @@
+/*
+  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 { PrecacheController } from "../PrecacheController.js";
+
+let precacheController: PrecacheController | undefined;
+
+/**
+ * @returns
+ * @private
+ */
+export const getOrCreatePrecacheController = (): PrecacheController => {
+  if (!precacheController) {
+    precacheController = new PrecacheController();
+  }
+  return precacheController;
+};

package/src/precaching/utils/printCleanupDetails.ts

@@ -0,0 +1,38 @@
+/*
+  Copyright 2018 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 { logger } from "@serwist/core/internal";
+
+/**
+ * @param groupTitle
+ * @param deletedURLs
+ *
+ * @private
+ */
+const logGroup = (groupTitle: string, deletedURLs: string[]) => {
+  logger.groupCollapsed(groupTitle);
+
+  for (const url of deletedURLs) {
+    logger.log(url);
+  }
+
+  logger.groupEnd();
+};
+
+/**
+ * @param deletedURLs
+ * @private
+ */
+export function printCleanupDetails(deletedURLs: string[]): void {
+  const deletionCount = deletedURLs.length;
+  if (deletionCount > 0) {
+    logger.groupCollapsed(`During precaching cleanup, ${deletionCount} cached request${deletionCount === 1 ? " was" : "s were"} deleted.`);
+    logGroup("Deleted Cache Requests", deletedURLs);
+    logger.groupEnd();
+  }
+}

package/src/precaching/utils/printInstallDetails.ts

@@ -0,0 +1,53 @@
+/*
+  Copyright 2018 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 { logger } from "@serwist/core/internal";
+
+/**
+ * @param groupTitle
+ * @param urls
+ *
+ * @private
+ */
+function _nestedGroup(groupTitle: string, urls: string[]): void {
+  if (urls.length === 0) {
+    return;
+  }
+
+  logger.groupCollapsed(groupTitle);
+
+  for (const url of urls) {
+    logger.log(url);
+  }
+
+  logger.groupEnd();
+}
+
+/**
+ * @param urlsToPrecache
+ * @param  urlsAlreadyPrecached
+ * @private
+ */
+export function printInstallDetails(urlsToPrecache: string[], urlsAlreadyPrecached: string[]): void {
+  const precachedCount = urlsToPrecache.length;
+  const alreadyPrecachedCount = urlsAlreadyPrecached.length;
+
+  if (precachedCount || alreadyPrecachedCount) {
+    let message = `Precaching ${precachedCount} file${precachedCount === 1 ? "" : "s"}.`;
+
+    if (alreadyPrecachedCount > 0) {
+      message += ` ${alreadyPrecachedCount} ` + `file${alreadyPrecachedCount === 1 ? " is" : "s are"} already cached.`;
+    }
+
+    logger.groupCollapsed(message);
+
+    _nestedGroup("View newly precached URLs.", urlsToPrecache);
+    _nestedGroup("View previously precached URLs.", urlsAlreadyPrecached);
+    logger.groupEnd();
+  }
+}

package/src/precaching/utils/removeIgnoredSearchParams.ts

@@ -0,0 +1,29 @@
+/*
+  Copyright 2018 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.
+*/
+
+/**
+ * Removes any URL search parameters that should be ignored.
+ *
+ * @param urlObject The original URL.
+ * @param ignoreURLParametersMatching RegExps to test against
+ * each search parameter name. Matches mean that the search parameter should be
+ * ignored.
+ * @returns The URL with any ignored search parameters removed.
+ * @private
+ */
+export function removeIgnoredSearchParams(urlObject: URL, ignoreURLParametersMatching: RegExp[] = []): URL {
+  // Convert the iterable into an array at the start of the loop to make sure
+  // deletion doesn't mess up iteration.
+  for (const paramName of [...urlObject.searchParams.keys()]) {
+    if (ignoreURLParametersMatching.some((regExp) => regExp.test(paramName))) {
+      urlObject.searchParams.delete(paramName);
+    }
+  }
+
+  return urlObject;
+}

package/src/routing/NavigationRoute.ts

@@ -0,0 +1,119 @@
+/*
+  Copyright 2018 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 { RouteHandler, RouteMatchCallbackOptions } from "@serwist/core";
+import { assert, logger } from "@serwist/core/internal";
+
+import { Route } from "./Route.js";
+
+export interface NavigationRouteMatchOptions {
+  /**
+   * If any of these patterns
+   * match the URL's pathname and search parameter, the route will handle the
+   * request (assuming the denylist doesn't match).
+   *
+   * @default [/./]
+   */
+  allowlist?: RegExp[];
+  /**
+   * If any of these patterns match, the route will not handle the request (even if a allowlist RegExp matches).
+   */
+  denylist?: RegExp[];
+}
+
+/**
+ * NavigationRoute makes it easy to create a `@serwist/routing` Route that matches for browser
+ * [navigation requests](https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests).
+ *
+ * It will only match incoming Requests whose [mode](https://fetch.spec.whatwg.org/#concept-request-mode) is set to `navigate`.
+ *
+ * You can optionally only apply this route to a subset of navigation requests
+ * by using one or both of the `denylist` and `allowlist` parameters.
+ */
+export class NavigationRoute extends Route {
+  private readonly _allowlist: RegExp[];
+  private readonly _denylist: RegExp[];
+
+  /**
+   * If both `denylist` and `allowlist` are provided, the `denylist` will
+   * take precedence and the request will not match this route.
+   *
+   * The regular expressions in `allowlist` and `denylist`
+   * are matched against the concatenated
+   * [`pathname`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/pathname)
+   * and [`search`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/search)
+   * portions of the requested URL.
+   *
+   * *Note*: These RegExps may be evaluated against every destination URL during
+   * a navigation. Avoid using
+   * [complex RegExps](https://github.com/GoogleChrome/workbox/issues/3077),
+   * or else your users may see delays when navigating your site.
+   *
+   * @param handler A callback function that returns a Promise resulting in a Response.
+   * @param options
+   */
+  constructor(handler: RouteHandler, { allowlist = [/./], denylist = [] }: NavigationRouteMatchOptions = {}) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isArrayOfClass(allowlist, RegExp, {
+        moduleName: "@serwist/routing",
+        className: "NavigationRoute",
+        funcName: "constructor",
+        paramName: "options.allowlist",
+      });
+      assert!.isArrayOfClass(denylist, RegExp, {
+        moduleName: "@serwist/routing",
+        className: "NavigationRoute",
+        funcName: "constructor",
+        paramName: "options.denylist",
+      });
+    }
+
+    super((options: RouteMatchCallbackOptions) => this._match(options), handler);
+
+    this._allowlist = allowlist;
+    this._denylist = denylist;
+  }
+
+  /**
+   * Routes match handler.
+   *
+   * @param options
+   * @returns
+   * @private
+   */
+  private _match({ url, request }: RouteMatchCallbackOptions): boolean {
+    if (request && request.mode !== "navigate") {
+      return false;
+    }
+
+    const pathnameAndSearch = url.pathname + url.search;
+
+    for (const regExp of this._denylist) {
+      if (regExp.test(pathnameAndSearch)) {
+        if (process.env.NODE_ENV !== "production") {
+          logger.log(
+            `The navigation route ${pathnameAndSearch} is not being used, since the URL matches this denylist pattern: ${regExp.toString()}`,
+          );
+        }
+        return false;
+      }
+    }
+
+    if (this._allowlist.some((regExp) => regExp.test(pathnameAndSearch))) {
+      if (process.env.NODE_ENV !== "production") {
+        logger.debug(`The navigation route ${pathnameAndSearch} is being used.`);
+      }
+      return true;
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(`The navigation route ${pathnameAndSearch} is not being used, since the URL being navigated to doesn't match the allowlist.`);
+    }
+    return false;
+  }
+}

package/src/routing/RegExpRoute.ts

@@ -0,0 +1,74 @@
+/*
+  Copyright 2018 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 { RouteHandler, RouteMatchCallback, RouteMatchCallbackOptions } from "@serwist/core";
+import { assert, logger } from "@serwist/core/internal";
+
+import { Route } from "./Route.js";
+import type { HTTPMethod } from "./utils/constants.js";
+
+/**
+ * RegExpRoute makes it easy to create a regular expression based on a `@serwist/routing` Route.
+ *
+ * For same-origin requests the RegExp only needs to match part of the URL. For
+ * requests against third-party servers, you must define a RegExp that matches
+ * the start of the URL.
+ */
+export class RegExpRoute extends Route {
+  /**
+   * If the regular expression contains
+   * [capture groups](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#grouping-back-references),
+   * the captured values will be passed to the `params` argument.
+   *
+   * @param regExp The regular expression to match against URLs.
+   * @param handler A callback function that returns a Promise resulting in a Response.
+   * @param method The HTTP method to match the Route, defaults to GET.
+   * against.
+   */
+  constructor(regExp: RegExp, handler: RouteHandler, method?: HTTPMethod) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isInstance(regExp, RegExp, {
+        moduleName: "@serwist/routing",
+        className: "RegExpRoute",
+        funcName: "constructor",
+        paramName: "pattern",
+      });
+    }
+
+    const match: RouteMatchCallback = ({ url }: RouteMatchCallbackOptions) => {
+      const result = regExp.exec(url.href);
+
+      // Return immediately if there's no match.
+      if (!result) {
+        return;
+      }
+
+      // Require that the match start at the first character in the URL string
+      // if it's a cross-origin request.
+      // See https://github.com/GoogleChrome/workbox/issues/281 for the context
+      // behind this behavior.
+      if (url.origin !== location.origin && result.index !== 0) {
+        if (process.env.NODE_ENV !== "production") {
+          logger.debug(
+            `The regular expression '${regExp.toString()}' only partially matched against the cross-origin URL '${url.toString()}'. RegExpRoute's will only handle cross-origin requests if they match the entire URL.`,
+          );
+        }
+
+        return;
+      }
+
+      // If the route matches, but there aren't any capture groups defined, then
+      // this will return [], which is truthy and therefore sufficient to
+      // indicate a match.
+      // If there are capture groups, then it will return their values.
+      return result.slice(1);
+    };
+
+    super(match, handler, method);
+  }
+}

package/src/routing/Route.ts

@@ -0,0 +1,68 @@
+/*
+  Copyright 2018 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 { RouteHandler, RouteHandlerObject, RouteMatchCallback } from "@serwist/core";
+import { assert } from "@serwist/core/internal";
+
+import type { HTTPMethod } from "./utils/constants.js";
+import { defaultMethod, validMethods } from "./utils/constants.js";
+import { normalizeHandler } from "./utils/normalizeHandler.js";
+
+/**
+ * A `Route` consists of a pair of callback functions, "match" and "handler".
+ * The "match" callback determine if a route should be used to "handle" a
+ * request by returning a non-falsy value if it can. The "handler" callback
+ * is called when there is a match and should return a Promise that resolves
+ * to a `Response`.
+ */
+export class Route {
+  handler: RouteHandlerObject;
+  match: RouteMatchCallback;
+  method: HTTPMethod;
+  catchHandler?: RouteHandlerObject;
+
+  /**
+   * Constructor for Route class.
+   *
+   * @param match A callback function that determines whether the
+   * route matches a given `fetch` event by returning a non-falsy value.
+   * @param handler A callback function that returns a Promise resolving
+   * to a Response.
+   * @param method The HTTP method to match the Route against. Defaults
+   * to GET.
+   */
+  constructor(match: RouteMatchCallback, handler: RouteHandler, method: HTTPMethod = defaultMethod) {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(match, "function", {
+        moduleName: "@serwist/routing",
+        className: "Route",
+        funcName: "constructor",
+        paramName: "match",
+      });
+
+      if (method) {
+        assert!.isOneOf(method, validMethods, { paramName: "method" });
+      }
+    }
+
+    // These values are referenced directly by Router so cannot be
+    // altered by minificaton.
+    this.handler = normalizeHandler(handler);
+    this.match = match;
+    this.method = method;
+  }
+
+  /**
+   *
+   * @param handler A callback function that returns a Promise resolving
+   * to a Response.
+   */
+  setCatchHandler(handler: RouteHandler): void {
+    this.catchHandler = normalizeHandler(handler);
+  }
+}