@serwist/sw 9.0.0-preview.2 → 9.0.0-preview.20

package/src/precaching/addRoute.ts

@@ -0,0 +1,30 @@
+/*
+  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 { registerRoute } from "../routing/registerRoute.js";
+import { PrecacheRoute } from "./PrecacheRoute.js";
+import { getSingletonPrecacheController } from "./singletonPrecacheController.js";
+import type { PrecacheRouteOptions } from "./types.js";
+
+/**
+ * Add a `fetch` listener to the service worker that will
+ * respond to
+ * [network requests](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Custom_responses_to_requests)
+ * with precached assets.
+ *
+ * Requests for assets that aren't precached, the `FetchEvent` will not be
+ * responded to, allowing the event to fall through to other `fetch` event
+ * listeners.
+ *
+ * @param options See the `@serwist/precaching.PrecacheRoute` options.
+ */
+export const addRoute = (options?: PrecacheRouteOptions): void => {
+  const precacheController = getSingletonPrecacheController();
+
+  const precacheRoute = new PrecacheRoute(precacheController, options);
+  registerRoute(precacheRoute);
+};

package/src/precaching/cleanupOutdatedCaches.ts

@@ -0,0 +1,33 @@
+/*
+  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 { logger, privateCacheNames } from "@serwist/core/internal";
+
+import { deleteOutdatedCaches } from "./utils/deleteOutdatedCaches.js";
+
+declare const self: ServiceWorkerGlobalScope;
+
+/**
+ * Adds an `activate` event listener which will clean up incompatible
+ * precaches that were created by older versions of Serwist.
+ */
+export const cleanupOutdatedCaches = (): void => {
+  self.addEventListener("activate", (event: ExtendableEvent) => {
+    const cacheName = privateCacheNames.getPrecacheName();
+
+    event.waitUntil(
+      deleteOutdatedCaches(cacheName).then((cachesDeleted) => {
+        if (process.env.NODE_ENV !== "production") {
+          if (cachesDeleted.length > 0) {
+            logger.log("The following out-of-date precaches were cleaned up automatically:", cachesDeleted);
+          }
+        }
+      }),
+    );
+  });
+};

package/src/precaching/createHandlerBoundToURL.ts

@@ -0,0 +1,30 @@
+/*
+  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 { RouteHandlerCallback } from "@serwist/core";
+
+import { getSingletonPrecacheController } from "./singletonPrecacheController.js";
+
+/**
+ * Helper function that calls `PrecacheController#createHandlerBoundToURL`
+ * on the default `PrecacheController` instance.
+ *
+ * If you are creating your own `PrecacheController`, then call the
+ * `PrecacheController#createHandlerBoundToURL` on that instance,
+ * instead of using this function.
+ *
+ * @param url The precached URL which will be used to lookup the
+ * `Response`.
+ * @param fallbackToNetwork Whether to attempt to get the
+ * response from the network if there's a precache miss.
+ * @return
+ */
+export const createHandlerBoundToURL = (url: string): RouteHandlerCallback => {
+  const precacheController = getSingletonPrecacheController();
+  return precacheController.createHandlerBoundToURL(url);
+};

package/src/precaching/getCacheKeyForURL.ts

@@ -0,0 +1,33 @@
+/*
+  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 { getSingletonPrecacheController } from "./singletonPrecacheController.js";
+
+/**
+ * Takes in a URL, and returns the corresponding URL that could be used to
+ * lookup the entry in the precache.
+ *
+ * If a relative URL is provided, the location of the service worker file will
+ * be used as the base.
+ *
+ * For precached entries without revision information, the cache key will be the
+ * same as the original URL.
+ *
+ * For precached entries with revision information, the cache key will be the
+ * original URL with the addition of a query parameter used for keeping track of
+ * the revision info.
+ *
+ * @param url The URL whose cache key to look up.
+ * @returns The cache key that corresponds to that URL.
+ */
+function getCacheKeyForURL(url: string): string | undefined {
+  const precacheController = getSingletonPrecacheController();
+  return precacheController.getCacheKeyForURL(url);
+}
+
+export { getCacheKeyForURL };

package/src/precaching/matchPrecache.ts

@@ -0,0 +1,25 @@
+/*
+  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 { getSingletonPrecacheController } from "./singletonPrecacheController.js";
+
+/**
+ * Helper function that calls `PrecacheController#matchPrecache`
+ * on the default `PrecacheController` instance.
+ *
+ * If you are creating your own `PrecacheController`, then call
+ * `PrecacheController#matchPrecache` on that instance,
+ * instead of using this function.
+ *
+ * @param request The key (without revisioning parameters)
+ * to look up in the precache.
+ * @returns
+ */
+export const matchPrecache = (request: string | Request): Promise<Response | undefined> => {
+  return getSingletonPrecacheController().matchPrecache(request);
+};

package/src/precaching/precache.ts

@@ -0,0 +1,31 @@
+/*
+  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 { getSingletonPrecacheController } from "./singletonPrecacheController.js";
+import type { PrecacheEntry } from "./types.js";
+
+/**
+ * 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.
+ *
+ * Please note: This method **will not** serve any of the cached files for you.
+ * It only precaches files. To respond to a network request you call
+ * `@serwist/precaching.addRoute`.
+ *
+ * If you have a single array of files to precache, you can just call
+ * `@serwist/precaching.precacheAndRoute`.
+ *
+ * @param entries Array of entries to precache.
+ */
+export const precache = (entries: (PrecacheEntry | string)[]): void => {
+  const precacheController = getSingletonPrecacheController();
+  precacheController.precache(entries);
+};

package/src/precaching/precacheAndRoute.ts

@@ -0,0 +1,27 @@
+/*
+  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 { addRoute } from "./addRoute.js";
+import { precache } from "./precache.js";
+import type { PrecacheEntry, PrecacheRouteOptions } from "./types.js";
+
+/**
+ * This method will add entries to the precache list and add a route to
+ * respond to fetch events.
+ *
+ * This is a convenience method that will call
+ * `@serwist/precaching.precache` and
+ * `@serwist/precaching.addRoute` in a single call.
+ *
+ * @param entries Array of entries to precache.
+ * @param options See the `@serwist/precaching.PrecacheRoute` options.
+ */
+export const precacheAndRoute = (entries: (PrecacheEntry | string)[], options?: PrecacheRouteOptions): void => {
+  precache(entries);
+  addRoute(options);
+};

package/src/precaching/singletonPrecacheController.ts

@@ -0,0 +1,57 @@
+/*
+  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 defaultPrecacheController: PrecacheController | undefined = undefined;
+
+/**
+ * Creates a new, singleton `PrecacheController` if one does not exist. If one does
+ * already exist, that instance is returned. This instance is used by Serwist's
+ * `PrecacheController`-dependent functions and classes unless you provide a different
+ * `Router` to them.
+ *
+ * @returns The singleton `PrecacheController`.
+ */
+export const getSingletonPrecacheController = (): PrecacheController => {
+  if (!defaultPrecacheController) {
+    defaultPrecacheController = new PrecacheController();
+  }
+  return defaultPrecacheController;
+};
+
+/**
+ * Changes the singleton `PrecacheController` to a different instance. This is meant for when you do not
+ * want to pass your own `PrecacheController` to every one of Serwist's `PrecacheController`-dependent
+ * functions and classes.
+ *
+ * It is highly recommended that you call this before anything else, if you plan on doing so.
+ *
+ * @example
+ * ```js
+ * import { PrecacheController, setSingletonPrecacheController } from "@serwist/sw/precaching";
+ *
+ * const controller = new PrecacheController();
+ *
+ * setSingletonPrecacheController(controller);
+ *
+ * // Do something with your controller...
+ *
+ * // This class now automatically picks up your `PrecacheController`! Without `setSingletonPrecacheController`,
+ * // you'd need to write this instead: `new Serwist({ controller })`
+ * const serwist = new Serwist();
+ *
+ * serwist.install();
+ * ```
+ * @param router
+ * @returns The new singleton `PrecacheController`.
+ */
+export const setSingletonPrecacheController = (precacheController: PrecacheController): PrecacheController => {
+  defaultPrecacheController = precacheController;
+  return defaultPrecacheController;
+};

package/src/precaching/types.ts

@@ -0,0 +1,46 @@
+/*
+  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.
+*/
+
+export interface InstallResult {
+  updatedURLs: string[];
+  notUpdatedURLs: string[];
+}
+
+export interface CleanupResult {
+  deletedCacheRequests: string[];
+}
+
+export declare interface PrecacheEntry {
+  integrity?: string;
+  url: string;
+  revision?: string | null;
+}
+
+export interface PrecacheRouteOptions {
+  /**
+   * The `directoryIndex` will check cache entries for a URL ending with '/'
+   * to see if there is a hit when appending the `directoryIndex` value.
+   */
+  directoryIndex?: string | null;
+  /**
+   * An array of RegExp's to remove search params when looking for a cache match.
+   */
+  ignoreURLParametersMatching?: RegExp[];
+  /**
+   * The `cleanURLs` option will check the cache for the URL with a `.html` added
+   * to the end of the end.
+   */
+  cleanURLs?: boolean;
+  /**
+   * This is a function that should take a URL and return an array of
+   * alternative URLs that should be checked for precache matches.
+   */
+  urlManipulation?: UrlManipulation;
+}
+
+export type UrlManipulation = ({ url }: { url: URL }) => URL[];

package/src/precaching/utils/PrecacheCacheKeyPlugin.ts

@@ -0,0 +1,36 @@
+/*
+  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 { SerwistPlugin, SerwistPluginCallbackParam } from "@serwist/core";
+
+import type { PrecacheController } from "../PrecacheController.js";
+
+/**
+ * A plugin, designed to be used with PrecacheController, to translate URLs into
+ * the corresponding cache key, based on the current revision info.
+ *
+ * @private
+ */
+class PrecacheCacheKeyPlugin implements SerwistPlugin {
+  private readonly _precacheController: PrecacheController;
+
+  constructor({ precacheController }: { precacheController: PrecacheController }) {
+    this._precacheController = precacheController;
+  }
+
+  cacheKeyWillBeUsed: SerwistPlugin["cacheKeyWillBeUsed"] = async ({ request, params }: SerwistPluginCallbackParam["cacheKeyWillBeUsed"]) => {
+    // Params is type any, can't change right now.
+    /* eslint-disable */
+    const cacheKey = params?.cacheKey || this._precacheController.getCacheKeyForURL(request.url);
+    /* eslint-enable */
+
+    return cacheKey ? new Request(cacheKey, { headers: request.headers }) : request;
+  };
+}
+
+export { PrecacheCacheKeyPlugin };

package/src/precaching/utils/PrecacheInstallReportPlugin.ts

@@ -0,0 +1,49 @@
+/*
+  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 { SerwistPlugin, SerwistPluginCallbackParam } from "@serwist/core";
+
+/**
+ * A plugin, designed to be used with PrecacheController, to determine the
+ * of assets that were updated (or not updated) during the install event.
+ *
+ * @private
+ */
+class PrecacheInstallReportPlugin implements SerwistPlugin {
+  updatedURLs: string[] = [];
+  notUpdatedURLs: string[] = [];
+
+  handlerWillStart: SerwistPlugin["handlerWillStart"] = async ({ request, state }: SerwistPluginCallbackParam["handlerWillStart"]) => {
+    // TODO: `state` should never be undefined...
+    if (state) {
+      state.originalRequest = request;
+    }
+  };
+
+  cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"] = async ({
+    event,
+    state,
+    cachedResponse,
+  }: SerwistPluginCallbackParam["cachedResponseWillBeUsed"]) => {
+    if (event.type === "install") {
+      if (state?.originalRequest && state.originalRequest instanceof Request) {
+        // TODO: `state` should never be undefined...
+        const url = state.originalRequest.url;
+
+        if (cachedResponse) {
+          this.notUpdatedURLs.push(url);
+        } else {
+          this.updatedURLs.push(url);
+        }
+      }
+    }
+    return cachedResponse;
+  };
+}
+
+export { PrecacheInstallReportPlugin };

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 { getSingletonPrecacheController } from "../singletonPrecacheController.js";
+import type { PrecacheRouteOptions } from "../types.js";
+import { generateURLVariations } from "./generateURLVariations.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 = getSingletonPrecacheController();
+
+  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/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();
+  }
+}