serwist 9.0.0-preview.24

package/src/utils/cacheNames.ts

@@ -0,0 +1,87 @@
+/*
+  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.
+*/
+
+declare let registration: ServiceWorkerRegistration | undefined;
+
+export interface CacheNameDetails {
+  googleAnalytics: string;
+  precache: string;
+  prefix: string;
+  runtime: string;
+  suffix: string;
+}
+
+export interface PartialCacheNameDetails {
+  /**
+   * The string to add to the beginning of the precache and runtime cache names.
+   */
+  prefix?: string;
+  /**
+   * The string to add to the end of the precache and runtime cache names.
+   */
+  suffix?: string;
+  /**
+   * The cache name to use for precache caching.
+   */
+  precache?: string;
+  /**
+   * The cache name to use for runtime caching.
+   */
+  runtime?: string;
+  /**
+   * The cache name to use for `@serwist/google-analytics` caching.
+   */
+  googleAnalytics?: string;
+  [propName: string]: string | undefined;
+}
+
+export type CacheNameDetailsProp = "googleAnalytics" | "precache" | "prefix" | "runtime" | "suffix";
+
+const _cacheNameDetails: CacheNameDetails = {
+  googleAnalytics: "googleAnalytics",
+  precache: "precache-v2",
+  prefix: "serwist",
+  runtime: "runtime",
+  suffix: typeof registration !== "undefined" ? registration.scope : "",
+};
+
+const _createCacheName = (cacheName: string): string => {
+  return [_cacheNameDetails.prefix, cacheName, _cacheNameDetails.suffix].filter((value) => value && value.length > 0).join("-");
+};
+
+const eachCacheNameDetail = (fn: (key: CacheNameDetailsProp) => void): void => {
+  for (const key of Object.keys(_cacheNameDetails)) {
+    fn(key as CacheNameDetailsProp);
+  }
+};
+
+export const cacheNames = {
+  updateDetails: (details: PartialCacheNameDetails): void => {
+    eachCacheNameDetail((key: CacheNameDetailsProp): void => {
+      const detail = details[key];
+      if (typeof detail === "string") {
+        _cacheNameDetails[key] = detail;
+      }
+    });
+  },
+  getGoogleAnalyticsName: (userCacheName?: string): string => {
+    return userCacheName || _createCacheName(_cacheNameDetails.googleAnalytics);
+  },
+  getPrecacheName: (userCacheName?: string): string => {
+    return userCacheName || _createCacheName(_cacheNameDetails.precache);
+  },
+  getPrefix: (): string => {
+    return _cacheNameDetails.prefix;
+  },
+  getRuntimeName: (userCacheName?: string): string => {
+    return userCacheName || _createCacheName(_cacheNameDetails.runtime);
+  },
+  getSuffix: (): string => {
+    return _cacheNameDetails.suffix;
+  },
+};

package/src/utils/canConstructReadableStream.ts

@@ -0,0 +1,34 @@
+/*
+  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.
+*/
+
+let supportStatus: boolean | undefined;
+
+/**
+ * A utility function that determines whether the current browser supports
+ * constructing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/ReadableStream)
+ * object.
+ *
+ * @returns `true`, if the current browser can successfully construct a `ReadableStream`, `false` otherwise.
+ *
+ * @private
+ */
+function canConstructReadableStream(): boolean {
+  if (supportStatus === undefined) {
+    // See https://github.com/GoogleChrome/workbox/issues/1473
+    try {
+      new ReadableStream({ start() {} });
+      supportStatus = true;
+    } catch (error) {
+      supportStatus = false;
+    }
+  }
+
+  return supportStatus;
+}
+
+export { canConstructReadableStream };

package/src/utils/canConstructResponseFromBodyStream.ts

@@ -0,0 +1,37 @@
+/*
+  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.
+*/
+
+let supportStatus: boolean | undefined;
+
+/**
+ * A utility function that determines whether the current browser supports
+ * constructing a new `Response` from a `response.body` stream.
+ *
+ * @returns `true`, if the current browser can successfully construct
+ * a `Response` from a `response.body` stream, `false` otherwise.
+ * @private
+ */
+function canConstructResponseFromBodyStream(): boolean {
+  if (supportStatus === undefined) {
+    const testResponse = new Response("");
+
+    if ("body" in testResponse) {
+      try {
+        new Response(testResponse.body);
+        supportStatus = true;
+      } catch (error) {
+        supportStatus = false;
+      }
+    }
+    supportStatus = false;
+  }
+
+  return supportStatus;
+}
+
+export { canConstructResponseFromBodyStream };

package/src/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 "./SerwistError.js";
+
+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 const 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/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 const 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/utils/dontWaitFor.ts

@@ -0,0 +1,16 @@
+/*
+  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.
+*/
+
+/**
+ * A helper function that prevents a promise from being flagged as unused.
+ *
+ * @private
+ */
+export function dontWaitFor(promise: Promise<any>): void {
+  // Effective no-op.
+  void promise.then(() => {});
+}

package/src/utils/executeQuotaErrorCallbacks.ts

@@ -0,0 +1,33 @@
+/*
+  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 "./logger.js";
+import { quotaErrorCallbacks } from "../models/quotaErrorCallbacks.js";
+
+/**
+ * Runs all of the callback functions, one at a time sequentially, in the order
+ * in which they were registered.
+ *
+ * @private
+ */
+export const executeQuotaErrorCallbacks = async (): Promise<void> => {
+  if (process.env.NODE_ENV !== "production") {
+    logger.log(`About to run ${quotaErrorCallbacks.size} callbacks to clean up caches.`);
+  }
+
+  for (const callback of quotaErrorCallbacks) {
+    await callback();
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(callback, "is complete.");
+    }
+  }
+
+  if (process.env.NODE_ENV !== "production") {
+    logger.log("Finished running callbacks.");
+  }
+};

package/src/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,
+  {
+    directoryIndex = "index.html",
+    ignoreURLParametersMatching = [/^utm_/, /^fbclid$/],
+    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/utils/getFriendlyURL.ts

@@ -0,0 +1,16 @@
+/*
+  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.
+*/
+
+const getFriendlyURL = (url: URL | string): string => {
+  const urlObj = new URL(String(url), location.href);
+  // See https://github.com/GoogleChrome/workbox/issues/2323
+  // We want to include everything, except for the origin if it's same-origin.
+  return urlObj.href.replace(new RegExp(`^${location.origin}`), "");
+};
+
+export { getFriendlyURL };

package/src/utils/logger.ts

@@ -0,0 +1,95 @@
+/*
+  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.
+*/
+
+// logger is used inside of both service workers and the window global scope.
+declare global {
+  interface WorkerGlobalScope {
+    __WB_DISABLE_DEV_LOGS: boolean;
+  }
+
+  interface Window {
+    __WB_DISABLE_DEV_LOGS: boolean;
+  }
+}
+
+/**
+ * The logger used by Serwist inside of both service workers and the window global scope.
+ *
+ * Note: This is forcibly `null` in production mode to reduce bundle size. Do check whether
+ * you are currently in development mode (by using `process.env.NODE_ENV !== "production"`)
+ * before using it.
+ */
+export const logger =
+  process.env.NODE_ENV === "production"
+    ? null!
+    : (() => {
+        // Don't overwrite this value if it's already set.
+        // See https://github.com/GoogleChrome/workbox/pull/2284#issuecomment-560470923
+        if (!("__WB_DISABLE_DEV_LOGS" in globalThis)) {
+          self.__WB_DISABLE_DEV_LOGS = false;
+        }
+
+        let inGroup = false;
+
+        const methodToColorMap = {
+          debug: "#7f8c8d", // Gray
+          log: "#2ecc71", // Green
+          warn: "#f39c12", // Yellow
+          error: "#c0392b", // Red
+          groupCollapsed: "#3498db", // Blue
+          groupEnd: null, // No colored prefix on groupEnd
+        };
+
+        type LoggerMethods = keyof typeof methodToColorMap;
+
+        const print = (method: LoggerMethods, args: any[]) => {
+          if (self.__WB_DISABLE_DEV_LOGS) {
+            return;
+          }
+
+          if (method === "groupCollapsed") {
+            // Safari doesn't print all console.groupCollapsed() arguments:
+            // https://bugs.webkit.org/show_bug.cgi?id=182754
+            if (typeof navigator !== "undefined" && /^((?!chrome|android).)*safari/i.test(navigator.userAgent)) {
+              console[method](...args);
+              return;
+            }
+          }
+
+          const styles = [
+            `background: ${methodToColorMap[method]!}`,
+            "border-radius: 0.5em",
+            "color: white",
+            "font-weight: bold",
+            "padding: 2px 0.5em",
+          ];
+
+          // When in a group, the serwist prefix is not displayed.
+          const logPrefix = inGroup ? [] : ["%cserwist", styles.join(";")];
+
+          console[method](...logPrefix, ...args);
+
+          if (method === "groupCollapsed") {
+            inGroup = true;
+          }
+          if (method === "groupEnd") {
+            inGroup = false;
+          }
+        };
+
+        const loggerMethods = Object.keys(methodToColorMap) as LoggerMethods[];
+
+        return loggerMethods.reduce(
+          (api, method) => {
+            api[method] = (...args: any[]) => {
+              print(method, args);
+            };
+            return api;
+          },
+          {} as { [method in LoggerMethods]: (...args: any[]) => void },
+        );
+      })();

package/src/utils/normalizeHandler.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.
+*/
+
+import type { RouteHandler, RouteHandlerObject } from "../types.js";
+import { assert } from "./assert.js";
+
+/**
+ * @param handler Either a function, or an object with a
+ * 'handle' method.
+ * @returns An object with a handle method.
+ *
+ * @private
+ */
+export const normalizeHandler = (handler: RouteHandler): RouteHandlerObject => {
+  if (handler && typeof handler === "object") {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.hasMethod(handler, "handle", {
+        moduleName: "serwist",
+        className: "Route",
+        funcName: "constructor",
+        paramName: "handler",
+      });
+    }
+    return handler;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isType(handler, "function", {
+      moduleName: "serwist",
+      className: "Route",
+      funcName: "constructor",
+      paramName: "handler",
+    });
+  }
+  return { handle: handler };
+};

package/src/utils/pluginUtils.ts

@@ -0,0 +1,15 @@
+/*
+  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 { SerwistPlugin } from "../types.js";
+
+export const pluginUtils = {
+  filter: (plugins: SerwistPlugin[], callbackName: string): SerwistPlugin[] => {
+    return plugins.filter((plugin) => callbackName in plugin);
+  },
+};

package/src/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 "./logger.js";
+
+/**
+ * @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 const 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/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 "./logger.js";
+
+/**
+ * @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 const 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/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 const 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;
+};