serwist 9.0.0-preview.24

package/src/types.ts

@@ -0,0 +1,358 @@
+import type { HTTPMethod } from "./constants.js";
+
+export type PromiseOrNot<T> = T | Promise<T>;
+
+export interface MapLikeObject {
+  [key: string]: any;
+}
+
+/**
+ * Using a plain `MapLikeObject` for now, but could extend/restrict this
+ * in the future.
+ */
+export type PluginState = MapLikeObject;
+
+/**
+ * Options passed to a `RouteMatchCallback` function.
+ */
+export interface RouteMatchCallbackOptions {
+  event: ExtendableEvent;
+  request: Request;
+  sameOrigin: boolean;
+  url: URL;
+}
+
+/**
+ * The "match" callback is used to determine if a `Route` should apply for a
+ * particular URL and request. When matching occurs in response to a fetch
+ * event from the client, the `event` object is also supplied. However, since
+ * the match callback can be invoked outside of a fetch event, matching logic
+ * should not assume the `event` object will always be available.
+ * If the match callback returns a truthy value, the matching route's
+ * `RouteHandlerCallback` will be invoked immediately. If the value returned
+ * is a non-empty array or object, that value will be set on the handler's
+ * `options.params` argument.
+ */
+export type RouteMatchCallback = (options: RouteMatchCallbackOptions) => any;
+
+/**
+ * Options passed to a `RouteHandlerCallback` function.
+ */
+export interface RouteHandlerCallbackOptions {
+  /**
+   * The event associated with the request.
+   */
+  event: ExtendableEvent;
+  /**
+   * A request to run this strategy for.
+   */
+  request: Request;
+  url: URL;
+  params?: string[] | MapLikeObject;
+}
+/**
+ * Options passed to a `ManualHandlerCallback` function.
+ */
+export interface ManualHandlerCallbackOptions {
+  /**
+   * The event associated with the request.
+   */
+  event: ExtendableEvent;
+  /**
+   * A request to run this strategy for.
+   */
+  request: Request | string;
+  url?: never;
+  /**
+   * The return value from `serwist.matchCallback` (if applicable).
+   */
+  params?: never;
+}
+
+export type HandlerCallbackOptions = RouteHandlerCallbackOptions | ManualHandlerCallbackOptions;
+
+/**
+ * The "handler" callback is invoked whenever a `Router` matches a URL/Request
+ * to a `Route` via its `RouteMatchCallback`. This handler callback should
+ * return a `Promise` that resolves with a `Response`.
+ *
+ * If a non-empty array or object is returned by the `RouteMatchCallback` it
+ * will be passed in as this handler's `options.params` argument.
+ */
+export type RouteHandlerCallback = (options: RouteHandlerCallbackOptions) => Promise<Response>;
+
+/**
+ * The "handler" callback is invoked whenever a `Router` matches a URL/Request
+ * to a `Route` via its `RouteMatchCallback`. This handler callback should
+ * return a `Promise` that resolves with a `Response`.
+ *
+ * If a non-empty array or object is returned by the `RouteMatchCallback` it
+ * will be passed in as this handler's `options.params` argument.
+ */
+export type ManualHandlerCallback = (options: ManualHandlerCallbackOptions) => Promise<Response>;
+
+/**
+ * An object with a `handle` method of type `RouteHandlerCallback`.
+ *
+ * A `Route` object can be created with either an `RouteHandlerCallback`
+ * function or this `RouteHandler` object. The benefit of the `RouteHandler`
+ * is it can be extended (as is done by the `serwist/strategies` package).
+ */
+export interface RouteHandlerObject {
+  handle: RouteHandlerCallback;
+}
+
+/**
+ * Either a `RouteHandlerCallback` or a `RouteHandlerObject`.
+ * Most APIs that accept route handlers take either.
+ */
+export type RouteHandler = RouteHandlerCallback | RouteHandlerObject;
+
+export interface HandlerWillStartCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export type HandlerWillStartCallback = (param: HandlerWillStartCallbackParam) => Promise<any>;
+
+export interface CacheDidUpdateCallbackParam {
+  /**
+   * Name of the cache the responses belong to. This is included in the
+   * broadcast message.
+   */
+  cacheName: string;
+  /**
+   * Possibly updated response to compare.
+   */
+  newResponse: Response;
+  /**
+   * The `Request` object for the cached entry.
+   */
+  request: Request;
+  /**
+   * The event that triggered this possible cache update.
+   */
+  event: ExtendableEvent;
+  /**
+   * Cached response to compare.
+   */
+  oldResponse?: Response | null;
+  state?: PluginState;
+}
+
+export type CacheDidUpdateCallback = (param: CacheDidUpdateCallbackParam) => PromiseOrNot<any>;
+
+export interface CacheKeyWillBeUsedCallbackParam {
+  mode: string;
+  request: Request;
+  event: ExtendableEvent;
+  params?: any;
+  state?: PluginState;
+}
+
+export type CacheKeyWillBeUsedCallback = (param: CacheKeyWillBeUsedCallbackParam) => PromiseOrNot<Request | string>;
+
+export interface CacheWillUpdateCallbackParam {
+  request: Request;
+  response: Response;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export type CacheWillUpdateCallback = (param: CacheWillUpdateCallbackParam) => PromiseOrNot<any>;
+
+export interface CachedResponseWillBeUsedCallbackParam {
+  /**
+   * Name of the cache the response is in.
+   */
+  cacheName: string;
+  /**
+   * The original request, which may or may not
+   * contain a Range: header.
+   */
+  request: Request;
+  /**
+   * The complete cached `Response` object that's been read
+   * from a cache and whose freshness should be checked.
+   */
+  cachedResponse?: Response;
+  event: ExtendableEvent;
+  matchOptions?: CacheQueryOptions;
+  state?: PluginState;
+}
+
+export type CachedResponseWillBeUsedCallback = (param: CachedResponseWillBeUsedCallbackParam) => PromiseOrNot<any>;
+
+export interface FetchDidFailCallbackParam {
+  error: Error;
+  originalRequest: Request;
+  request: Request;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export type FetchDidFailCallback = (param: FetchDidFailCallbackParam) => PromiseOrNot<any>;
+
+export interface FetchDidSucceedCallbackParam {
+  request: Request;
+  response: Response;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export type FetchDidSucceedCallback = (param: FetchDidSucceedCallbackParam) => PromiseOrNot<Response>;
+
+export interface RequestWillFetchCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export type RequestWillFetchCallback = (param: RequestWillFetchCallbackParam) => PromiseOrNot<Request>;
+
+export interface HandlerWillRespondCallbackParam {
+  request: Request;
+  response: Response;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export type HandlerWillRespondCallback = (param: HandlerWillRespondCallbackParam) => PromiseOrNot<Response>;
+
+export interface HandlerDidErrorCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  error: Error;
+  state?: PluginState;
+}
+
+export type HandlerDidErrorCallback = (param: HandlerDidErrorCallbackParam) => PromiseOrNot<Response | undefined>;
+
+export interface HandlerDidRespondCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  response?: Response;
+  state?: PluginState;
+}
+
+export type HandlerDidRespondCallback = (param: HandlerDidRespondCallbackParam) => PromiseOrNot<any>;
+
+export interface HandlerDidCompleteCallbackParam {
+  request: Request;
+  error?: Error;
+  event: ExtendableEvent;
+  response?: Response;
+  state?: PluginState;
+}
+
+export type HandlerDidCompleteCallback = (param: HandlerDidCompleteCallbackParam) => PromiseOrNot<any>;
+
+/**
+ * An object with optional lifecycle callback properties for the fetch and
+ * cache operations.
+ */
+export declare interface SerwistPlugin {
+  cacheDidUpdate?: CacheDidUpdateCallback;
+  cachedResponseWillBeUsed?: CachedResponseWillBeUsedCallback;
+  cacheKeyWillBeUsed?: CacheKeyWillBeUsedCallback;
+  cacheWillUpdate?: CacheWillUpdateCallback;
+  fetchDidFail?: FetchDidFailCallback;
+  fetchDidSucceed?: FetchDidSucceedCallback;
+  handlerDidComplete?: HandlerDidCompleteCallback;
+  handlerDidError?: HandlerDidErrorCallback;
+  handlerDidRespond?: HandlerDidRespondCallback;
+  handlerWillRespond?: HandlerWillRespondCallback;
+  handlerWillStart?: HandlerWillStartCallback;
+  requestWillFetch?: RequestWillFetchCallback;
+}
+
+export interface SerwistPluginCallbackParam {
+  cacheDidUpdate: CacheDidUpdateCallbackParam;
+  cachedResponseWillBeUsed: CachedResponseWillBeUsedCallbackParam;
+  cacheKeyWillBeUsed: CacheKeyWillBeUsedCallbackParam;
+  cacheWillUpdate: CacheWillUpdateCallbackParam;
+  fetchDidFail: FetchDidFailCallbackParam;
+  fetchDidSucceed: FetchDidSucceedCallbackParam;
+  handlerDidComplete: HandlerDidCompleteCallbackParam;
+  handlerDidError: HandlerDidErrorCallbackParam;
+  handlerDidRespond: HandlerDidRespondCallbackParam;
+  handlerWillRespond: HandlerWillRespondCallbackParam;
+  handlerWillStart: HandlerWillStartCallbackParam;
+  requestWillFetch: RequestWillFetchCallbackParam;
+}
+
+export interface SerwistGlobalConfig {
+  /**
+   * Whether Serwist should disable development logging.
+   *
+   * @default false
+   */
+  __WB_DISABLE_DEV_LOGS: boolean;
+}
+
+export interface RuntimeCaching {
+  /**
+   * The HTTP method to match against. The default value of `'GET'` is normally
+   * sufficient, unless you explicitly need to match `'POST'`, `'PUT'`, or
+   * another type of request.
+   * @default "GET"
+   */
+  method?: HTTPMethod;
+  /**
+   * This match criteria determines whether the configured handler will
+   * generate a response for any requests that don't match one of the precached
+   * URLs. If multiple `RuntimeCaching` routes are defined, then the first one
+   * whose `matcher` matches will be the one that responds.
+   *
+   * This value directly maps to the first parameter passed to
+   * `Serwist.registerRoute`. It's recommended to use a
+   * `serwist.RouteMatchCallback` function for greatest flexibility.
+   */
+  matcher: RegExp | string | RouteMatchCallback;
+  /**
+   * This determines how the runtime route will generate a response. It
+   * can be a `serwist.RouteHandler` callback function with custom
+   * response logic.
+   */
+  handler: RouteHandler;
+}
+
+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/utils/Deferred.ts

@@ -0,0 +1,33 @@
+/*
+  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.
+*/
+
+/**
+ * The Deferred class composes Promises in a way that allows for them to be
+ * resolved or rejected from outside the constructor. In most cases promises
+ * should be used directly, but Deferreds can be necessary when the logic to
+ * resolve a promise must be separate.
+ *
+ * @private
+ */
+class Deferred<T> {
+  promise: Promise<T>;
+  resolve!: (value: T) => void;
+  reject!: (reason?: any) => void;
+
+  /**
+   * Creates a promise and exposes its resolve and reject functions as methods.
+   */
+  constructor() {
+    this.promise = new Promise((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+}
+
+export { Deferred };

package/src/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 { Serwist } from "../Serwist.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: Serwist;
+
+  constructor({ precacheController }: { precacheController: Serwist }) {
+    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.getPrecacheKeyForUrl(request.url);
+    /* eslint-enable */
+
+    return cacheKey ? new Request(cacheKey, { headers: request.headers }) : request;
+  };
+}

package/src/utils/PrecacheInstallReportPlugin.ts

@@ -0,0 +1,47 @@
+/*
+  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";
+
+/**
+ * A plugin designed to determine the number of assets that were updated (or not updated)
+ * during the `install` event.
+ *
+ * @private
+ */
+export 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;
+  };
+}

package/src/utils/SerwistError.ts

@@ -0,0 +1,41 @@
+/*
+  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 { messageGenerator } from "../models/messages/messageGenerator.js";
+import type { MessageKey } from "../models/messages/messages.js";
+import type { MapLikeObject } from "../types.js";
+
+/**
+ * Serwist errors should be thrown with this class.
+ * This allows use to ensure the type easily in tests,
+ * helps developers identify errors from Serwist
+ * easily and allows use to optimise error
+ * messages correctly.
+ *
+ * @private
+ */
+export class SerwistError extends Error {
+  details?: MapLikeObject;
+
+  /**
+   *
+   * @param errorCode The error code that
+   * identifies this particular error.
+   * @param details Any relevant arguments
+   * that will help developers identify issues should
+   * be added as a key on the context object.
+   */
+  constructor(errorCode: MessageKey, details?: MapLikeObject) {
+    const message = messageGenerator(errorCode, details);
+
+    super(message);
+
+    this.name = errorCode;
+    this.details = details;
+  }
+}

package/src/utils/assert.ts

@@ -0,0 +1,89 @@
+/*
+  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 "./SerwistError.js";
+import type { MapLikeObject } from "../types.js";
+
+/*
+ * This method throws if the supplied value is not an array.
+ * The destructed values are required to produce a meaningful error for users.
+ * The destructed and restructured object is so it's clear what is
+ * needed.
+ */
+const isArray = (value: any[], details: MapLikeObject) => {
+  if (!Array.isArray(value)) {
+    throw new SerwistError("not-an-array", details);
+  }
+};
+
+const hasMethod = (object: MapLikeObject, expectedMethod: string, details: MapLikeObject) => {
+  const type = typeof object[expectedMethod];
+  if (type !== "function") {
+    details.expectedMethod = expectedMethod;
+    throw new SerwistError("missing-a-method", details);
+  }
+};
+
+const isType = (object: unknown, expectedType: string, details: MapLikeObject) => {
+  // biome-ignore lint/suspicious/useValidTypeof: Know to not make a mistake...
+  if (typeof object !== expectedType) {
+    details.expectedType = expectedType;
+    throw new SerwistError("incorrect-type", details);
+  }
+};
+
+const isInstance = (
+  object: unknown,
+  // biome-ignore lint/complexity/noBannedTypes: Need the general type to do the check later.
+  expectedClass: Function,
+  details: MapLikeObject,
+) => {
+  if (!(object instanceof expectedClass)) {
+    details.expectedClassName = expectedClass.name;
+    throw new SerwistError("incorrect-class", details);
+  }
+};
+
+const isOneOf = (value: any, validValues: any[], details: MapLikeObject) => {
+  if (!validValues.includes(value)) {
+    details.validValueDescription = `Valid values are ${JSON.stringify(validValues)}.`;
+    throw new SerwistError("invalid-value", details);
+  }
+};
+
+const isArrayOfClass = (
+  value: any,
+  // biome-ignore lint/complexity/noBannedTypes: Need general type to do check later.
+  expectedClass: Function,
+  details: MapLikeObject,
+) => {
+  const error = new SerwistError("not-array-of-class", details);
+  if (!Array.isArray(value)) {
+    throw error;
+  }
+
+  for (const item of value) {
+    if (!(item instanceof expectedClass)) {
+      throw error;
+    }
+  }
+};
+
+const finalAssertExports =
+  process.env.NODE_ENV === "production"
+    ? null
+    : {
+        hasMethod,
+        isArray,
+        isInstance,
+        isOneOf,
+        isType,
+        isArrayOfClass,
+      };
+
+export { finalAssertExports as assert };

package/src/utils/cacheMatchIgnoreParams.ts

@@ -0,0 +1,54 @@
+/*
+  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.
+*/
+
+function stripParams(fullURL: string, ignoreParams: string[]) {
+  const strippedURL = new URL(fullURL);
+  for (const param of ignoreParams) {
+    strippedURL.searchParams.delete(param);
+  }
+  return strippedURL.href;
+}
+
+/**
+ * Matches an item in the cache, ignoring specific URL params. This is similar
+ * to the `ignoreSearch` option, but it allows you to ignore just specific
+ * params (while continuing to match on the others).
+ *
+ * @private
+ * @param cache
+ * @param request
+ * @param matchOptions
+ * @param ignoreParams
+ * @returns
+ */
+async function cacheMatchIgnoreParams(
+  cache: Cache,
+  request: Request,
+  ignoreParams: string[],
+  matchOptions?: CacheQueryOptions,
+): Promise<Response | undefined> {
+  const strippedRequestURL = stripParams(request.url, ignoreParams);
+
+  // If the request doesn't include any ignored params, match as normal.
+  if (request.url === strippedRequestURL) {
+    return cache.match(request, matchOptions);
+  }
+
+  // Otherwise, match by comparing keys
+  const keysOptions = { ...matchOptions, ignoreSearch: true };
+  const cacheKeys = await cache.keys(request, keysOptions);
+
+  for (const cacheKey of cacheKeys) {
+    const strippedCacheKeyURL = stripParams(cacheKey.url, ignoreParams);
+    if (strippedRequestURL === strippedCacheKeyURL) {
+      return cache.match(cacheKey, matchOptions);
+    }
+  }
+  return;
+}
+
+export { cacheMatchIgnoreParams };