@serwist/precaching 8.4.3 → 9.0.0-preview.0

package/src/_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/addPlugins.ts

@@ -0,0 +1,23 @@
+/*
+  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 { SerwistPlugin } from "@serwist/core";
+
+import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.js";
+
+/**
+ * Adds plugins to the precaching strategy.
+ *
+ * @param plugins
+ */
+function addPlugins(plugins: SerwistPlugin[]): void {
+  const precacheController = getOrCreatePrecacheController();
+  precacheController.strategy.plugins.push(...plugins);
+}
+
+export { addPlugins };

package/src/addRoute.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 { registerRoute } from "@serwist/routing";
+
+import { PrecacheRoute } from "./PrecacheRoute.js";
+import type { PrecacheRouteOptions } from "./_types.js";
+import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.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.
+ */
+function addRoute(options?: PrecacheRouteOptions): void {
+  const precacheController = getOrCreatePrecacheController();
+
+  const precacheRoute = new PrecacheRoute(precacheController, options);
+  registerRoute(precacheRoute);
+}
+
+export { addRoute };

package/src/cleanupOutdatedCaches.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.
+*/
+
+import { logger, privateCacheNames } from "@serwist/core/internal";
+
+import { deleteOutdatedCaches } from "./utils/deleteOutdatedCaches.js";
+
+/**
+ * Adds an `activate` event listener which will clean up incompatible
+ * precaches that were created by older versions of Serwist.
+ */
+function cleanupOutdatedCaches(): void {
+  // See https://github.com/Microsoft/TypeScript/issues/28357#issuecomment-436484705
+  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);
+          }
+        }
+      }),
+    );
+  }) as EventListener);
+}
+
+export { cleanupOutdatedCaches };

package/src/createHandlerBoundToURL.ts

@@ -0,0 +1,32 @@
+/*
+  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 { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.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
+ */
+function createHandlerBoundToURL(url: string): RouteHandlerCallback {
+  const precacheController = getOrCreatePrecacheController();
+  return precacheController.createHandlerBoundToURL(url);
+}
+
+export { createHandlerBoundToURL };

package/src/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 { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.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 = getOrCreatePrecacheController();
+  return precacheController.getCacheKeyForURL(url);
+}
+
+export { getCacheKeyForURL };

package/{dist/index.d.cts → src/index.ts}

@@ -1,3 +1,11 @@
+/*
+  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 { PrecacheController } from "./PrecacheController.js";
 import { PrecacheFallbackPlugin } from "./PrecacheFallbackPlugin.js";
 import { PrecacheRoute } from "./PrecacheRoute.js";
@@ -10,6 +18,7 @@ import { getCacheKeyForURL } from "./getCacheKeyForURL.js";
 import { matchPrecache } from "./matchPrecache.js";
 import { precache } from "./precache.js";
 import { precacheAndRoute } from "./precacheAndRoute.js";
+
 /**
  * Most consumers of this module will want to use the
  * `@serwist/precaching.precacheAndRoute`
@@ -20,5 +29,20 @@ import { precacheAndRoute } from "./precacheAndRoute.js";
  * `@serwist/precaching.PrecacheController`
  * interface.
  */
-export { addPlugins, addRoute, cleanupOutdatedCaches, createHandlerBoundToURL, getCacheKeyForURL, matchPrecache, precache, precacheAndRoute, PrecacheController, PrecacheFallbackPlugin, PrecacheRoute, PrecacheStrategy, };
+
+export {
+  addPlugins,
+  addRoute,
+  cleanupOutdatedCaches,
+  createHandlerBoundToURL,
+  getCacheKeyForURL,
+  matchPrecache,
+  precache,
+  precacheAndRoute,
+  PrecacheController,
+  PrecacheFallbackPlugin,
+  PrecacheRoute,
+  PrecacheStrategy,
+};
+
 export * from "./_types.js";

package/src/matchPrecache.ts

@@ -0,0 +1,28 @@
+/*
+  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 { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.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
+ */
+function matchPrecache(request: string | Request): Promise<Response | undefined> {
+  const precacheController = getOrCreatePrecacheController();
+  return precacheController.matchPrecache(request);
+}
+
+export { matchPrecache };

package/src/precache.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 type { PrecacheEntry } from "./_types.js";
+import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.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.
+ */
+function precache(entries: (PrecacheEntry | string)[]): void {
+  const precacheController = getOrCreatePrecacheController();
+  precacheController.precache(entries);
+}
+
+export { precache };

package/src/precacheAndRoute.ts

@@ -0,0 +1,29 @@
+/*
+  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 { PrecacheEntry, PrecacheRouteOptions } from "./_types.js";
+import { addRoute } from "./addRoute.js";
+import { precache } from "./precache.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.
+ */
+function precacheAndRoute(entries: (PrecacheEntry | string)[], options?: PrecacheRouteOptions): void {
+  precache(entries);
+  addRoute(options);
+}
+
+export { precacheAndRoute };

package/src/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/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/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/utils/deleteOutdatedCaches.ts

@@ -0,0 +1,42 @@
+/*
+  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
+ */
+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;
+};
+
+export { deleteOutdatedCaches };

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,
+  {
+    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/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/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;
+};