@serwist/sw 9.0.0-preview.21 → 9.0.0-preview.24

package/src/routing/singletonRouter.ts

@@ -1,76 +0,0 @@
-/*
-  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`.
- */
-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/sw/routing";
- *
- * const router = new Router();
- *
- * setSingletonRouter(router);
- *
- * router.registerRoute(
- *   new Route(
- *     /\/api\/.*\/*.json/,
- *     new NetworkOnly({
- *       plugins: [backgroundSync],
- *     }),
- *     "POST",
- *   ),
- * );
- *
- * // This class now automatically picks up your `Router`! Without `setSingletonRouter`, you'd need to
- * // write this instead: `new Serwist({ router })`
- * const serwist = new Serwist();
- *
- * serwist.install();
- * ```
- * @param router
- * @returns The new singleton `Router`.
- */
-export const setSingletonRouter = (router: Router): Router => {
-  if (defaultRouter) {
-    defaultRouter.removeFetchListener();
-    defaultRouter.removeCacheListener();
-  }
-  defaultRouter = router;
-  defaultRouter.addFetchListener();
-  defaultRouter.addCacheListener();
-  return defaultRouter;
-};

package/src/routing/unregisterRoute.ts

@@ -1,11 +0,0 @@
-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.
- */
-export const unregisterRoute = (route: Route): void => {
-  getSingletonRouter().unregisterRoute(route);
-};

package/src/routing/utils/constants.ts

@@ -1,24 +0,0 @@
-/*
-  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 type HTTPMethod = "DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT";
-
-/**
- * The default HTTP method, 'GET', used when there's no specific method
- * configured for a route.
- *
- * @private
- */
-export const defaultMethod = "GET" satisfies HTTPMethod;
-
-/**
- * The list of valid HTTP methods associated with requests that could be routed.
- *
- * @private
- */
-export const validMethods = ["DELETE", "GET", "HEAD", "PATCH", "POST", "PUT"] satisfies HTTPMethod[];

package/src/routing/utils/normalizeHandler.ts

@@ -1,40 +0,0 @@
-/*
-  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 "@serwist/core";
-import { assert } from "@serwist/core/internal";
-
-/**
- * @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/routing",
-        className: "Route",
-        funcName: "constructor",
-        paramName: "handler",
-      });
-    }
-    return handler;
-  }
-  if (process.env.NODE_ENV !== "production") {
-    assert!.isType(handler, "function", {
-      moduleName: "@serwist/routing",
-      className: "Route",
-      funcName: "constructor",
-      paramName: "handler",
-    });
-  }
-  return { handle: handler };
-};

package/src/strategies/CacheFirst.ts

@@ -1,87 +0,0 @@
-/*
-  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 { assert, SerwistError, logger } from "@serwist/core/internal";
-
-import { Strategy } from "./Strategy.js";
-import type { StrategyHandler } from "./StrategyHandler.js";
-import { messages } from "./utils/messages.js";
-
-/**
- * An implementation of the [cache first](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#cache_first_falling_back_to_network)
- * request strategy.
- *
- * A cache first strategy is useful for assets that have been revisioned,
- * such as URLs like `/styles/example.a8f5f1.css`, since they
- * can be cached for long periods of time.
- *
- * If the network request fails, and there is no cache match, this will throw
- * a `SerwistError` exception.
- */
-export class CacheFirst extends Strategy {
-  /**
-   * @private
-   * @param request A request to run this strategy for.
-   * @param handler The event that triggered the request.
-   * @returns
-   */
-  async _handle(request: Request, handler: StrategyHandler): Promise<Response> {
-    const logs = [];
-
-    if (process.env.NODE_ENV !== "production") {
-      assert!.isInstance(request, Request, {
-        moduleName: "@serwist/strategies",
-        className: this.constructor.name,
-        funcName: "makeRequest",
-        paramName: "request",
-      });
-    }
-
-    let response = await handler.cacheMatch(request);
-
-    let error: Error | undefined = undefined;
-    if (!response) {
-      if (process.env.NODE_ENV !== "production") {
-        logs.push(`No response found in the '${this.cacheName}' cache. Will respond with a network request.`);
-      }
-      try {
-        response = await handler.fetchAndCachePut(request);
-      } catch (err) {
-        if (err instanceof Error) {
-          error = err;
-        }
-      }
-
-      if (process.env.NODE_ENV !== "production") {
-        if (response) {
-          logs.push("Got response from network.");
-        } else {
-          logs.push("Unable to get a response from the network.");
-        }
-      }
-    } else {
-      if (process.env.NODE_ENV !== "production") {
-        logs.push(`Found a cached response in the '${this.cacheName}' cache.`);
-      }
-    }
-
-    if (process.env.NODE_ENV !== "production") {
-      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
-      for (const log of logs) {
-        logger.log(log);
-      }
-      messages.printFinalResponse(response);
-      logger.groupEnd();
-    }
-
-    if (!response) {
-      throw new SerwistError("no-response", { url: request.url, error });
-    }
-    return response;
-  }
-}

package/src/strategies/CacheOnly.ts

@@ -1,58 +0,0 @@
-/*
-  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 { assert, SerwistError, logger } from "@serwist/core/internal";
-
-import { Strategy } from "./Strategy.js";
-import type { StrategyHandler } from "./StrategyHandler.js";
-import { messages } from "./utils/messages.js";
-
-/**
- * An implementation of the [cache only](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#cache-only)
- * request strategy.
- *
- * This class is useful if you want to take advantage of any Serwist plugin.
- *
- * If there is no cache match, this will throw a `SerwistError` exception.
- */
-export class CacheOnly extends Strategy {
-  /**
-   * @private
-   * @param request A request to run this strategy for.
-   * @param handler The event that triggered the request.
-   * @returns
-   */
-  async _handle(request: Request, handler: StrategyHandler): Promise<Response> {
-    if (process.env.NODE_ENV !== "production") {
-      assert!.isInstance(request, Request, {
-        moduleName: "@serwist/strategies",
-        className: this.constructor.name,
-        funcName: "makeRequest",
-        paramName: "request",
-      });
-    }
-
-    const response = await handler.cacheMatch(request);
-
-    if (process.env.NODE_ENV !== "production") {
-      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
-      if (response) {
-        logger.log(`Found a cached response in the '${this.cacheName}' cache.`);
-        messages.printFinalResponse(response);
-      } else {
-        logger.log(`No response found in the '${this.cacheName}' cache.`);
-      }
-      logger.groupEnd();
-    }
-
-    if (!response) {
-      throw new SerwistError("no-response", { url: request.url });
-    }
-    return response;
-  }
-}

package/src/strategies/NetworkFirst.ts

@@ -1,228 +0,0 @@
-/*
-  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 { assert, SerwistError, logger } from "@serwist/core/internal";
-
-import type { StrategyOptions } from "./Strategy.js";
-import { Strategy } from "./Strategy.js";
-import type { StrategyHandler } from "./StrategyHandler.js";
-import { cacheOkAndOpaquePlugin } from "./plugins/cacheOkAndOpaquePlugin.js";
-import { messages } from "./utils/messages.js";
-
-export interface NetworkFirstOptions extends StrategyOptions {
-  /**
-   * If set, any network requests that fail to respond within the timeout will fallback to the cache.
-   */
-  networkTimeoutSeconds?: number;
-}
-
-/**
- * An implementation of the [network first](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#network-first-falling-back-to-cache)
- * request strategy.
- *
- * By default, this strategy will cache responses with a 200 status code as
- * well as [opaque responses](https://developer.chrome.com/docs/workbox/caching-resources-during-runtime/#opaque-responses).
- * Opaque responses are are cross-origin requests where the response doesn't
- * support [CORS](https://enable-cors.org/).
- *
- * If the network request fails, and there is no cache match, this will throw
- * a `SerwistError` exception.
- */
-export class NetworkFirst extends Strategy {
-  private readonly _networkTimeoutSeconds: number;
-  /**
-   * @param options
-   * This option can be used to combat
-   * "[lie-fi](https://developers.google.com/web/fundamentals/performance/poor-connectivity/#lie-fi)"
-   * scenarios.
-   */
-  constructor(options: NetworkFirstOptions = {}) {
-    super(options);
-
-    // If this instance contains no plugins with a 'cacheWillUpdate' callback,
-    // prepend the `cacheOkAndOpaquePlugin` plugin to the plugins list.
-    if (!this.plugins.some((p) => "cacheWillUpdate" in p)) {
-      this.plugins.unshift(cacheOkAndOpaquePlugin);
-    }
-
-    this._networkTimeoutSeconds = options.networkTimeoutSeconds || 0;
-    if (process.env.NODE_ENV !== "production") {
-      if (this._networkTimeoutSeconds) {
-        assert!.isType(this._networkTimeoutSeconds, "number", {
-          moduleName: "@serwist/strategies",
-          className: this.constructor.name,
-          funcName: "constructor",
-          paramName: "networkTimeoutSeconds",
-        });
-      }
-    }
-  }
-
-  /**
-   * @private
-   * @param request A request to run this strategy for.
-   * @param handler The event that triggered the request.
-   * @returns
-   */
-  async _handle(request: Request, handler: StrategyHandler): Promise<Response> {
-    const logs: any[] = [];
-
-    if (process.env.NODE_ENV !== "production") {
-      assert!.isInstance(request, Request, {
-        moduleName: "@serwist/strategies",
-        className: this.constructor.name,
-        funcName: "handle",
-        paramName: "makeRequest",
-      });
-    }
-
-    const promises: Promise<Response | undefined>[] = [];
-    let timeoutId: number | undefined;
-
-    if (this._networkTimeoutSeconds) {
-      const { id, promise } = this._getTimeoutPromise({
-        request,
-        logs,
-        handler,
-      });
-      timeoutId = id;
-      promises.push(promise);
-    }
-
-    const networkPromise = this._getNetworkPromise({
-      timeoutId,
-      request,
-      logs,
-      handler,
-    });
-
-    promises.push(networkPromise);
-
-    const response = await handler.waitUntil(
-      (async () => {
-        // Promise.race() will resolve as soon as the first promise resolves.
-        return (
-          (await handler.waitUntil(Promise.race(promises))) ||
-          // If Promise.race() resolved with null, it might be due to a network
-          // timeout + a cache miss. If that were to happen, we'd rather wait until
-          // the networkPromise resolves instead of returning null.
-          // Note that it's fine to await an already-resolved promise, so we don't
-          // have to check to see if it's still "in flight".
-          (await networkPromise)
-        );
-      })(),
-    );
-
-    if (process.env.NODE_ENV !== "production") {
-      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
-      for (const log of logs) {
-        logger.log(log);
-      }
-      messages.printFinalResponse(response);
-      logger.groupEnd();
-    }
-
-    if (!response) {
-      throw new SerwistError("no-response", { url: request.url });
-    }
-    return response;
-  }
-
-  /**
-   * @param options
-   * @returns
-   * @private
-   */
-  private _getTimeoutPromise({
-    request,
-    logs,
-    handler,
-  }: {
-    request: Request;
-    /**
-     * A reference to the logs array.
-     */
-    logs: any[];
-    handler: StrategyHandler;
-  }): { promise: Promise<Response | undefined>; id?: number } {
-    // biome-ignore lint/suspicious/noImplicitAnyLet: setTimeout is typed with Node.js's typings, so we can't use number | undefined here.
-    let timeoutId;
-    const timeoutPromise: Promise<Response | undefined> = new Promise((resolve) => {
-      const onNetworkTimeout = async () => {
-        if (process.env.NODE_ENV !== "production") {
-          logs.push(`Timing out the network response at ${this._networkTimeoutSeconds} seconds.`);
-        }
-        resolve(await handler.cacheMatch(request));
-      };
-      timeoutId = setTimeout(onNetworkTimeout, this._networkTimeoutSeconds * 1000);
-    });
-
-    return {
-      promise: timeoutPromise,
-      id: timeoutId,
-    };
-  }
-
-  /**
-   * @param options
-   * @param options.timeoutId
-   * @param options.request
-   * @param options.logs A reference to the logs Array.
-   * @param options.event
-   * @returns
-   *
-   * @private
-   */
-  async _getNetworkPromise({
-    timeoutId,
-    request,
-    logs,
-    handler,
-  }: {
-    request: Request;
-    logs: any[];
-    timeoutId?: number;
-    handler: StrategyHandler;
-  }): Promise<Response | undefined> {
-    let error: Error | undefined = undefined;
-    let response: Response | undefined = undefined;
-    try {
-      response = await handler.fetchAndCachePut(request);
-    } catch (fetchError) {
-      if (fetchError instanceof Error) {
-        error = fetchError;
-      }
-    }
-
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
-
-    if (process.env.NODE_ENV !== "production") {
-      if (response) {
-        logs.push("Got response from network.");
-      } else {
-        logs.push("Unable to get a response from the network. Will respond " + "with a cached response.");
-      }
-    }
-
-    if (error || !response) {
-      response = await handler.cacheMatch(request);
-
-      if (process.env.NODE_ENV !== "production") {
-        if (response) {
-          logs.push(`Found a cached response in the '${this.cacheName}' cache.`);
-        } else {
-          logs.push(`No response found in the '${this.cacheName}' cache.`);
-        }
-      }
-    }
-
-    return response;
-  }
-}

package/src/strategies/NetworkOnly.ts

@@ -1,96 +0,0 @@
-/*
-  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 { assert, SerwistError, logger, timeout } from "@serwist/core/internal";
-
-import type { StrategyOptions } from "./Strategy.js";
-import { Strategy } from "./Strategy.js";
-import type { StrategyHandler } from "./StrategyHandler.js";
-import { messages } from "./utils/messages.js";
-
-export interface NetworkOnlyOptions extends Omit<StrategyOptions, "cacheName" | "matchOptions"> {
-  /**
-   * If set, any network requests that fail to respond within the timeout will result in a network error.
-   */
-  networkTimeoutSeconds?: number;
-}
-
-/**
- * An implementation of the [network only](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#network-only)
- * request strategy.
- *
- * This class is useful if you want to take advantage of any Serwist plugin.
- *
- * If the network request fails, this will throw a `SerwistError` exception.
- */
-export class NetworkOnly extends Strategy {
-  private readonly _networkTimeoutSeconds: number;
-
-  /**
-   * @param options
-   */
-  constructor(options: NetworkOnlyOptions = {}) {
-    super(options);
-
-    this._networkTimeoutSeconds = options.networkTimeoutSeconds || 0;
-  }
-
-  /**
-   * @private
-   * @param request A request to run this strategy for.
-   * @param handler The event that triggered the request.
-   * @returns
-   */
-  async _handle(request: Request, handler: StrategyHandler): Promise<Response> {
-    if (process.env.NODE_ENV !== "production") {
-      assert!.isInstance(request, Request, {
-        moduleName: "@serwist/strategies",
-        className: this.constructor.name,
-        funcName: "_handle",
-        paramName: "request",
-      });
-    }
-
-    let error: Error | undefined = undefined;
-    let response: Response | undefined;
-
-    try {
-      const promises: Promise<Response | undefined>[] = [handler.fetch(request)];
-
-      if (this._networkTimeoutSeconds) {
-        const timeoutPromise = timeout(this._networkTimeoutSeconds * 1000) as Promise<undefined>;
-        promises.push(timeoutPromise);
-      }
-
-      response = await Promise.race(promises);
-      if (!response) {
-        throw new Error(`Timed out the network response after ${this._networkTimeoutSeconds} seconds.`);
-      }
-    } catch (err) {
-      if (err instanceof Error) {
-        error = err;
-      }
-    }
-
-    if (process.env.NODE_ENV !== "production") {
-      logger.groupCollapsed(messages.strategyStart(this.constructor.name, request));
-      if (response) {
-        logger.log("Got response from network.");
-      } else {
-        logger.log("Unable to get a response from the network.");
-      }
-      messages.printFinalResponse(response);
-      logger.groupEnd();
-    }
-
-    if (!response) {
-      throw new SerwistError("no-response", { url: request.url, error });
-    }
-    return response;
-  }
-}