@serwist/strategies 9.0.0-preview.8 → 9.0.0

package/src/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/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;
-}
-
-export class NetworkFirst extends Strategy {
-  private readonly _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.
-   *
-   * @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/NetworkOnly.ts

@@ -1,95 +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;
-}
-
-export class NetworkOnly extends Strategy {
-  private readonly _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.
-   *
-   * @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;
-  }
-}

package/src/StaleWhileRevalidate.ts

@@ -1,108 +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 class StaleWhileRevalidate extends Strategy {
-  /**
-   * An implementation of the
-   * [stale-while-revalidate](https://developer.chrome.com/docs/workbox/caching-strategies-overview/#stale-while-revalidate)
-   * request strategy.
-   *
-   * Resources are requested from both the cache and the network in parallel.
-   * The strategy will respond with the cached version if available, otherwise
-   * wait for the network response. The cache is updated with the network response
-   * with each successful request.
-   *
-   * 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 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.
-   *
-   * @param options
-   */
-  constructor(options: StrategyOptions = {}) {
-    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);
-    }
-  }
-
-  /**
-   * @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: "handle",
-        paramName: "request",
-      });
-    }
-
-    const fetchAndCachePromise = handler.fetchAndCachePut(request).catch(() => {
-      // Swallow this error because a 'no-response' error will be thrown in
-      // main handler return flow. This will be in the `waitUntil()` flow.
-    });
-    void handler.waitUntil(fetchAndCachePromise);
-
-    let response = await handler.cacheMatch(request);
-
-    let error: Error | undefined = undefined;
-    if (response) {
-      if (process.env.NODE_ENV !== "production") {
-        logs.push(`Found a cached response in the '${this.cacheName}' cache. Will update with the network response in the background.`);
-      }
-    } else {
-      if (process.env.NODE_ENV !== "production") {
-        logs.push(`No response found in the '${this.cacheName}' cache. Will wait for the network response.`);
-      }
-      try {
-        // NOTE(philipwalton): Really annoying that we have to type cast here.
-        // https://github.com/microsoft/TypeScript/issues/20006
-        response = (await fetchAndCachePromise) as Response | undefined;
-      } catch (err) {
-        if (err instanceof Error) {
-          error = err;
-        }
-      }
-    }
-
-    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/Strategy.ts

@@ -1,203 +0,0 @@
-/*
-  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 { HandlerCallbackOptions, RouteHandlerObject, SerwistPlugin } from "@serwist/core";
-import { SerwistError, getFriendlyURL, logger, privateCacheNames } from "@serwist/core/internal";
-
-import { StrategyHandler } from "./StrategyHandler.js";
-
-export interface StrategyOptions {
-  /**
-   * Cache name to store and retrieve requests. Defaults to cache names provided by `@serwist/core`.
-   */
-  cacheName?: string;
-  /**
-   * [Plugins](https://developers.google.com/web/tools/workbox/guides/using-plugins)
-   * to use in conjunction with this caching strategy.
-   */
-  plugins?: SerwistPlugin[];
-  /**
-   * Values passed along to the [`init`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters)
-   * of [non-navigation](https://github.com/GoogleChrome/workbox/issues/1796) `fetch()` requests made by this strategy.
-   */
-  fetchOptions?: RequestInit;
-  /**
-   * The [`CacheQueryOptions`](https://w3c.github.io/ServiceWorker/#dictdef-cachequeryoptions)
-   * for any `cache.match()` or `cache.put()` calls made by this strategy.
-   */
-  matchOptions?: CacheQueryOptions;
-}
-
-/**
- * Classes extending the `Strategy` based class should implement this method,
- * and leverage `@serwist/strategies`'s `StrategyHandler` arg to perform all
- * fetching and cache logic, which will ensure all relevant cache, cache options,
- * fetch options and plugins are used (per the current strategy instance).
- */
-export abstract class Strategy implements RouteHandlerObject {
-  cacheName: string;
-  plugins: SerwistPlugin[];
-  fetchOptions?: RequestInit;
-  matchOptions?: CacheQueryOptions;
-
-  protected abstract _handle(request: Request, handler: StrategyHandler): Promise<Response | undefined>;
-
-  /**
-   * Creates a new instance of the strategy and sets all documented option
-   * properties as public instance properties.
-   *
-   * Note: if a custom strategy class extends the base Strategy class and does
-   * not need more than these properties, it does not need to define its own
-   * constructor.
-   *
-   * @param options
-   */
-  constructor(options: StrategyOptions = {}) {
-    this.cacheName = privateCacheNames.getRuntimeName(options.cacheName);
-    this.plugins = options.plugins || [];
-    this.fetchOptions = options.fetchOptions;
-    this.matchOptions = options.matchOptions;
-  }
-
-  /**
-   * Perform a request strategy and returns a `Promise` that will resolve with
-   * a `Response`, invoking all relevant plugin callbacks.
-   *
-   * When a strategy instance is registered with a `@serwist/routing` Route, this method is automatically
-   * called when the route matches.
-   *
-   * Alternatively, this method can be used in a standalone `FetchEvent`
-   * listener by passing it to `event.respondWith()`.
-   *
-   * @param options A `FetchEvent` or an object with the properties listed below.
-   * @param options.request A request to run this strategy for.
-   * @param options.event The event associated with the request.
-   * @param options.url
-   * @param options.params
-   */
-  handle(options: FetchEvent | HandlerCallbackOptions): Promise<Response> {
-    const [responseDone] = this.handleAll(options);
-    return responseDone;
-  }
-
-  /**
-   * Similar to `@serwist/strategies`'s `Strategy.handle`, but
-   * instead of just returning a `Promise` that resolves to a `Response` it
-   * it will return an tuple of `[response, done]` promises, where the former
-   * (`response`) is equivalent to what `handle()` returns, and the latter is a
-   * Promise that will resolve once any promises that were added to
-   * `event.waitUntil()` as part of performing the strategy have completed.
-   *
-   * You can await the `done` promise to ensure any extra work performed by
-   * the strategy (usually caching responses) completes successfully.
-   *
-   * @param options A `FetchEvent` or `HandlerCallbackOptions` object.
-   * @returns A tuple of [response, done] promises that can be used to determine when the response resolves as
-   * well as when the handler has completed all its work.
-   */
-  handleAll(options: FetchEvent | HandlerCallbackOptions): [Promise<Response>, Promise<void>] {
-    // Allow for flexible options to be passed.
-    if (options instanceof FetchEvent) {
-      options = {
-        event: options,
-        request: options.request,
-      };
-    }
-
-    const event = options.event;
-    const request = typeof options.request === "string" ? new Request(options.request) : options.request;
-    const params = "params" in options ? options.params : undefined;
-
-    const handler = new StrategyHandler(this, { event, request, params });
-
-    const responseDone = this._getResponse(handler, request, event);
-    const handlerDone = this._awaitComplete(responseDone, handler, request, event);
-
-    // Return an array of promises, suitable for use with Promise.all().
-    return [responseDone, handlerDone];
-  }
-
-  async _getResponse(handler: StrategyHandler, request: Request, event: ExtendableEvent): Promise<Response> {
-    await handler.runCallbacks("handlerWillStart", { event, request });
-
-    let response: Response | undefined = undefined;
-    try {
-      response = await this._handle(request, handler);
-      // The "official" Strategy subclasses all throw this error automatically,
-      // but in case a third-party Strategy doesn't, ensure that we have a
-      // consistent failure when there's no response or an error response.
-      if (response === undefined || response.type === "error") {
-        throw new SerwistError("no-response", { url: request.url });
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        for (const callback of handler.iterateCallbacks("handlerDidError")) {
-          response = await callback({ error, event, request });
-          if (response !== undefined) {
-            break;
-          }
-        }
-      }
-
-      if (!response) {
-        throw error;
-      }
-      if (process.env.NODE_ENV !== "production") {
-        throw logger.log(
-          `While responding to '${getFriendlyURL(request.url)}', an ${
-            error instanceof Error ? error.toString() : ""
-          } error occurred. Using a fallback response provided by a handlerDidError plugin.`,
-        );
-      }
-    }
-
-    for (const callback of handler.iterateCallbacks("handlerWillRespond")) {
-      response = (await callback({ event, request, response })) as Response;
-    }
-
-    return response;
-  }
-
-  async _awaitComplete(responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent): Promise<void> {
-    let response: Response | undefined = undefined;
-    let error: Error | undefined = undefined;
-
-    try {
-      response = await responseDone;
-    } catch (error) {
-      // Ignore errors, as response errors should be caught via the `response`
-      // promise above. The `done` promise will only throw for errors in
-      // promises passed to `handler.waitUntil()`.
-    }
-
-    try {
-      await handler.runCallbacks("handlerDidRespond", {
-        event,
-        request,
-        response,
-      });
-      await handler.doneWaiting();
-    } catch (waitUntilError) {
-      if (waitUntilError instanceof Error) {
-        error = waitUntilError;
-      }
-    }
-
-    await handler.runCallbacks("handlerDidComplete", {
-      event,
-      request,
-      response,
-      error,
-    });
-    handler.destroy();
-
-    if (error) {
-      throw error;
-    }
-  }
-}