serwist 9.0.0-preview.24

package/src/legacy/handlePrecaching.ts

@@ -0,0 +1,86 @@
+import { NavigationRoute } from "../NavigationRoute.js";
+import { cleanupOutdatedCaches as cleanupOutdatedCachesImpl } from "../cleanupOutdatedCaches.js";
+import type { PrecacheEntry, PrecacheRouteOptions } from "../types.js";
+import type { PrecacheController } from "./PrecacheController.js";
+import { PrecacheRoute } from "./PrecacheRoute.js";
+import type { Router } from "./Router.js";
+import { createHandlerBoundToURL } from "./createHandlerBoundToURL.js";
+import { getSingletonPrecacheController } from "./singletonPrecacheController.js";
+import { getSingletonRouter } from "./singletonRouter.js";
+
+/**
+ * @deprecated
+ */
+export interface HandlePrecachingOptions {
+  /**
+   * An optional `PrecacheController` instance. If not provided, the singleton
+   * `PrecacheController` will be used.
+   */
+  precacheController?: PrecacheController;
+  /**
+   * An optional `Router` instance. If not provided, the singleton `Router`
+   * will be used.
+   */
+  router?: Router;
+  /**
+   * A list of URLs that should be cached.
+   */
+  precacheEntries?: (PrecacheEntry | string)[];
+  /**
+   * Options to customize how Serwist precaches the URLs.
+   */
+  precacheOptions?: PrecacheRouteOptions;
+  /**
+   * Whether outdated caches should be removed.
+   *
+   * @default false
+   */
+  cleanupOutdatedCaches?: boolean;
+  /**
+   * An URL that should point to a HTML file with which navigation requests for URLs that aren't
+   * precached will be fulfilled.
+   */
+  navigateFallback?: string;
+  /**
+   * URLs that should be allowed to use the `navigateFallback` handler.
+   */
+  navigateFallbackAllowlist?: RegExp[];
+  /**
+   * URLs that should not be allowed to use the `navigateFallback` handler. This takes precedence
+   * over `navigateFallbackAllowlist`.
+   */
+  navigateFallbackDenylist?: RegExp[];
+}
+
+/**
+ * Handles a list of precache entries and cleans up outdated caches.
+ *
+ * @param options
+ * @deprecated
+ */
+export const handlePrecaching = ({
+  precacheController = getSingletonPrecacheController(),
+  router = getSingletonRouter(),
+  precacheEntries,
+  precacheOptions,
+  cleanupOutdatedCaches = false,
+  navigateFallback,
+  navigateFallbackAllowlist,
+  navigateFallbackDenylist,
+}: HandlePrecachingOptions): void => {
+  if (!!precacheEntries && precacheEntries.length > 0) {
+    precacheController.precache(precacheEntries);
+    router.registerRoute(new PrecacheRoute(precacheController, precacheOptions));
+
+    if (cleanupOutdatedCaches) cleanupOutdatedCachesImpl();
+
+    if (navigateFallback) {
+      router.registerRoute(
+        new NavigationRoute(createHandlerBoundToURL(navigateFallback), {
+          allowlist: navigateFallbackAllowlist,
+          denylist: navigateFallbackDenylist,
+        }),
+      );
+    }
+  }
+};

package/src/legacy/installSerwist.ts

@@ -0,0 +1,19 @@
+import { Serwist, type SerwistOptions } from "../Serwist.js";
+
+/**
+ * Options for `installSerwist`.
+ *
+ * @deprecated
+ */
+export type InstallSerwistOptions = SerwistOptions;
+
+/**
+ * Abstracts away the core APIs of Serwist.
+ *
+ * @param options - `installSerwist` options.
+ * @deprecated
+ */
+export const installSerwist = (options: InstallSerwistOptions): void => {
+  const serwist = new Serwist(options);
+  serwist.addEventListeners();
+};

package/src/legacy/matchPrecache.ts

@@ -0,0 +1,26 @@
+/*
+  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
+ * @deprecated
+ */
+export const matchPrecache = (request: string | Request): Promise<Response | undefined> => {
+  return getSingletonPrecacheController().matchPrecache(request);
+};

package/src/legacy/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 type { PrecacheEntry } from "../types.js";
+import { getSingletonPrecacheController } from "./singletonPrecacheController.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/legacy.addRoute`.
+ *
+ * If you have a single array of files to precache, you can just call
+ * `serwist/legacy.precacheAndRoute`.
+ *
+ * @param entries Array of entries to precache.
+ * @deprecated
+ */
+export const precache = (entries: (PrecacheEntry | string)[]): void => {
+  getSingletonPrecacheController().precache(entries);
+};

package/src/legacy/precacheAndRoute.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 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/legacy.precache` and
+ * `serwist/legacy.addRoute` in a single call.
+ *
+ * @param entries Array of entries to precache.
+ * @param options See the `serwist.PrecacheRouteOptions` options.
+ * @deprecated
+ */
+export const precacheAndRoute = (entries: (PrecacheEntry | string)[], options?: PrecacheRouteOptions): void => {
+  precache(entries);
+  addRoute(options);
+};

package/src/legacy/registerRoute.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 type { RouteHandler, RouteMatchCallback } from "../types.js";
+import type { Route } from "../Route.js";
+import type { HTTPMethod } from "../constants.js";
+import { getSingletonRouter } from "./singletonRouter.js";
+
+/**
+ * Registers a `RegExp`, string, or function with a caching
+ * strategy to a singleton `Router` instance.
+ *
+ * @param capture If the capture param is a `Route`, all other arguments will be ignored.
+ * @param handler A callback function that returns a `Promise` resulting in a `Response`.
+ * This parameter is required if `capture` is not a `Route` object.
+ * @param method The HTTP method to match the `Route` against. Defaults to `'GET'`.
+ * @returns The generated `Route`, which can then be provided to `unregisterRoute` if needed.
+ * @deprecated
+ */
+export const registerRoute = (capture: RegExp | string | RouteMatchCallback | Route, handler?: RouteHandler, method?: HTTPMethod): Route => {
+  return getSingletonRouter().registerCapture(capture, handler, method);
+};

package/src/legacy/registerRuntimeCaching.ts

@@ -0,0 +1,17 @@
+import { registerRoute } from "./registerRoute.js";
+
+import type { RuntimeCaching } from "../types.js";
+
+/**
+ * Registers caching strategies to a singleton Router instance. It is a simple
+ * syntatic sugar for `serwist/legacy.registerRoute`.
+ *
+ * @param runtimeCachingList
+ * @returns
+ * @deprecated
+ */
+export const registerRuntimeCaching = (...runtimeCachingList: RuntimeCaching[]): void => {
+  for (const entry of runtimeCachingList) {
+    registerRoute(entry.matcher, entry.handler, entry.method);
+  }
+};

package/src/legacy/setCatchHandler.ts

@@ -0,0 +1,21 @@
+/*
+  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 { RouteHandler } from "../types.js";
+import { getSingletonRouter } from "./singletonRouter.js";
+
+/**
+ * If a `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.
+ * @deprecated
+ */
+export const setCatchHandler = (handler: RouteHandler): void => {
+  getSingletonRouter().setCatchHandler(handler);
+};

package/src/legacy/setDefaultHandler.ts

@@ -0,0 +1,24 @@
+/*
+  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 { RouteHandler } from "../types.js";
+import { getSingletonRouter } from "./singletonRouter.js";
+
+/**
+ * Defines a default `handler` that's called when no routes explicitly
+ * match the incoming request.
+ *
+ * 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.
+ * @deprecated
+ */
+export const setDefaultHandler = (handler: RouteHandler): void => {
+  getSingletonRouter().setDefaultHandler(handler);
+};

package/src/legacy/singletonPrecacheController.ts

@@ -0,0 +1,53 @@
+/*
+  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`.
+ * @deprecated
+ */
+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/legacy";
+ *
+ * const controller = new PrecacheController();
+ *
+ * setSingletonPrecacheController(controller);
+ *
+ * // Do something with your controller...
+ * ```
+ * @param router
+ * @returns The new singleton `PrecacheController`.
+ * @deprecated
+ */
+export const setSingletonPrecacheController = (precacheController: PrecacheController): PrecacheController => {
+  defaultPrecacheController = precacheController;
+  return defaultPrecacheController;
+};

package/src/legacy/singletonRouter.ts

@@ -0,0 +1,70 @@
+/*
+  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 { Router } from "./Router.js";
+
+let defaultRouter: Router | undefined = undefined;
+
+/**
+ * Creates a new, singleton `Router` if one does not exist. If one does
+ * already exist, that instance is returned. This instance is used by
+ * Serwist's `Router`-dependent functions and classes unless you provide
+ * a different `Router` to them.
+ *
+ * @returns The singleton `Router`.
+ * @deprecated
+ */
+export const getSingletonRouter = (): Router => {
+  if (!defaultRouter) {
+    defaultRouter = new Router();
+
+    // The helpers that use the default Router assume these listeners exist.
+    defaultRouter.addFetchListener();
+    defaultRouter.addCacheListener();
+  }
+  return defaultRouter;
+};
+
+/**
+ * Changes the singleton `Router` to a different instance. This is meant for when you do not
+ * want to pass your own `Router` to every one of Serwist's `Router`-dependent functions and classes.
+ * If this or `getSingletonRouter` has been called before, it removes the listeners of the
+ * previous singleton `Router`. It also adds those of the new one, so you need not do that yourself.
+ *
+ * It is highly recommended that you call this before anything else, if you plan on doing so.
+ *
+ * @example
+ * ```js
+ * import { Router, setSingletonRouter } from "serwist/legacy";
+ *
+ * const router = new Router();
+ *
+ * setSingletonRouter(router);
+ *
+ * router.registerRoute(
+ *   new Route(
+ *     /\/api\/.*\/*.json/,
+ *     new NetworkOnly(),
+ *     "POST",
+ *   ),
+ * );
+ * ```
+ * @param router
+ * @returns The new singleton `Router`.
+ * @deprecated
+ */
+export const setSingletonRouter = (router: Router): Router => {
+  if (defaultRouter) {
+    defaultRouter.removeFetchListener();
+    defaultRouter.removeCacheListener();
+  }
+  defaultRouter = router;
+  defaultRouter.addFetchListener();
+  defaultRouter.addCacheListener();
+  return defaultRouter;
+};

package/src/legacy/unregisterRoute.ts

@@ -0,0 +1,12 @@
+import type { Route } from "../Route.js";
+import { getSingletonRouter } from "./singletonRouter.js";
+
+/**
+ * Unregisters a route from the singleton `Router` instance.
+ *
+ * @param route The route to unregister.
+ * @deprecated
+ */
+export const unregisterRoute = (route: Route): void => {
+  getSingletonRouter().unregisterRoute(route);
+};

package/src/legacy/utils/PrecacheCacheKeyPlugin.ts

@@ -0,0 +1,33 @@
+/*
+  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 "../../types.js";
+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
+ */
+export 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;
+  };
+}

package/src/legacy/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 "../../utils/generateURLVariations.js";
+import { getSingletonPrecacheController } from "../singletonPrecacheController.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/models/messages/messageGenerator.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.
+*/
+
+import type { MapLikeObject } from "../../types.js";
+import { type MessageKey, messages } from "./messages.js";
+
+const fallback = (code: string, ...args: any[]) => {
+  let msg = code;
+  if (args.length > 0) {
+    msg += ` :: ${JSON.stringify(args)}`;
+  }
+  return msg;
+};
+
+const generatorFunction = (code: MessageKey, details: MapLikeObject = {}) => {
+  const message = messages[code];
+  if (!message) {
+    throw new Error(`Unable to find message for code '${code}'.`);
+  }
+
+  return message(details);
+};
+
+export const messageGenerator = process.env.NODE_ENV === "production" ? fallback : generatorFunction;