@serwist/core 8.4.4 → 9.0.0-preview.1

package/src/models/pluginEvents.ts

@@ -0,0 +1,17 @@
+/*
+  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 enum pluginEvents {
+  CACHE_DID_UPDATE = "cacheDidUpdate",
+  CACHE_KEY_WILL_BE_USED = "cacheKeyWillBeUsed",
+  CACHE_WILL_UPDATE = "cacheWillUpdate",
+  CACHED_RESPONSE_WILL_BE_USED = "cachedResponseWillBeUsed",
+  FETCH_DID_FAIL = "fetchDidFail",
+  FETCH_DID_SUCCEED = "fetchDidSucceed",
+  REQUEST_WILL_FETCH = "requestWillFetch",
+}

package/src/models/quotaErrorCallbacks.ts

@@ -0,0 +1,13 @@
+/*
+  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.
+*/
+
+// Callbacks to be executed whenever there's a quota error.
+// biome-ignore lint/complexity/noBannedTypes: Can't change Function type right now.
+const quotaErrorCallbacks: Set<Function> = new Set();
+
+export { quotaErrorCallbacks };

package/src/registerQuotaErrorCallback.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 { assert } from "./_private/assert.js";
+import { logger } from "./_private/logger.js";
+import { quotaErrorCallbacks } from "./models/quotaErrorCallbacks.js";
+
+/**
+ * Adds a function to the set of quotaErrorCallbacks that will be executed if
+ * there's a quota error.
+ *
+ * @param callback
+ */
+// biome-ignore lint/complexity/noBannedTypes: Can't change Function type
+function registerQuotaErrorCallback(callback: Function): void {
+  if (process.env.NODE_ENV !== "production") {
+    assert!.isType(callback, "function", {
+      moduleName: "@serwist/core",
+      funcName: "register",
+      paramName: "callback",
+    });
+  }
+
+  quotaErrorCallbacks.add(callback);
+
+  if (process.env.NODE_ENV !== "production") {
+    logger.log("Registered a callback to respond to quota errors.", callback);
+  }
+}
+
+export { registerQuotaErrorCallback };

package/src/setCacheNameDetails.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 { SerwistError } from "./_private/SerwistError.js";
+import { assert } from "./_private/assert.js";
+import type { PartialCacheNameDetails } from "./_private/cacheNames.js";
+import { cacheNames } from "./_private/cacheNames.js";
+
+/**
+ * Modifies the default cache names used by the Serwist packages.
+ * Cache names are generated as `<prefix>-<Cache Name>-<suffix>`.
+ *
+ * @param details
+ */
+function setCacheNameDetails(details: PartialCacheNameDetails): void {
+  if (process.env.NODE_ENV !== "production") {
+    for (const key of Object.keys(details)) {
+      assert!.isType(details[key], "string", {
+        moduleName: "@serwist/core",
+        funcName: "setCacheNameDetails",
+        paramName: `details.${key}`,
+      });
+    }
+
+    if (details.precache?.length === 0) {
+      throw new SerwistError("invalid-cache-name", {
+        cacheNameId: "precache",
+        value: details.precache,
+      });
+    }
+
+    if (details.runtime?.length === 0) {
+      throw new SerwistError("invalid-cache-name", {
+        cacheNameId: "runtime",
+        value: details.runtime,
+      });
+    }
+
+    if (details.googleAnalytics?.length === 0) {
+      throw new SerwistError("invalid-cache-name", {
+        cacheNameId: "googleAnalytics",
+        value: details.googleAnalytics,
+      });
+    }
+  }
+
+  cacheNames.updateDetails(details);
+}
+
+export { setCacheNameDetails };

package/src/types.ts

@@ -0,0 +1,315 @@
+/*
+  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.
+*/
+
+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 interface RouteMatchCallback {
+  (options: RouteMatchCallbackOptions): any;
+}
+
+/**
+ * Options passed to a `RouteHandlerCallback` function.
+ */
+export declare interface RouteHandlerCallbackOptions {
+  /**
+   * The event associated with the request.
+   */
+  event: ExtendableEvent;
+  /**
+   * A request to run this strategy for.
+   */
+  request: Request;
+  url: URL;
+  /**
+   * The return value from `@serwist/routing`'s `matchCallback` (if applicable).
+   */
+  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;
+}
+
+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 interface 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 interface 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 in `@serwist/routing` that accept route handlers take either.
+ */
+export type RouteHandler = RouteHandlerCallback | RouteHandlerObject;
+
+export interface HandlerWillStartCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export interface 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 interface CacheDidUpdateCallback {
+  (param: CacheDidUpdateCallbackParam): Promise<any>;
+}
+
+export interface CacheKeyWillBeUsedCallbackParam {
+  mode: string;
+  request: Request;
+  event: ExtendableEvent;
+  params?: any;
+  state?: PluginState;
+}
+
+export interface CacheKeyWillBeUsedCallback {
+  (param: CacheKeyWillBeUsedCallbackParam): Promise<Request | string>;
+}
+
+export interface CacheWillUpdateCallbackParam {
+  request: Request;
+  response: Response;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export interface CacheWillUpdateCallback {
+  (param: CacheWillUpdateCallbackParam): Promise<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 interface CachedResponseWillBeUsedCallback {
+  (param: CachedResponseWillBeUsedCallbackParam): Promise<any>;
+}
+
+export interface FetchDidFailCallbackParam {
+  error: Error;
+  originalRequest: Request;
+  request: Request;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export interface FetchDidFailCallback {
+  (param: FetchDidFailCallbackParam): Promise<any>;
+}
+
+export interface FetchDidSucceedCallbackParam {
+  request: Request;
+  response: Response;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export interface FetchDidSucceedCallback {
+  (param: FetchDidSucceedCallbackParam): Promise<Response>;
+}
+
+export interface RequestWillFetchCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export interface RequestWillFetchCallback {
+  (param: RequestWillFetchCallbackParam): Promise<Request>;
+}
+
+export interface HandlerWillRespondCallbackParam {
+  request: Request;
+  response: Response;
+  event: ExtendableEvent;
+  state?: PluginState;
+}
+
+export interface HandlerWillRespondCallback {
+  (param: HandlerWillRespondCallbackParam): Promise<Response>;
+}
+
+export interface HandlerDidErrorCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  error: Error;
+  state?: PluginState;
+}
+
+export interface HandlerDidErrorCallback {
+  (param: HandlerDidErrorCallbackParam): Promise<Response | undefined>;
+}
+
+export interface HandlerDidRespondCallbackParam {
+  request: Request;
+  event: ExtendableEvent;
+  response?: Response;
+  state?: PluginState;
+}
+
+export interface HandlerDidRespondCallback {
+  (param: HandlerDidRespondCallbackParam): Promise<any>;
+}
+
+export interface HandlerDidCompleteCallbackParam {
+  request: Request;
+  error?: Error;
+  event: ExtendableEvent;
+  response?: Response;
+  state?: PluginState;
+}
+
+export interface HandlerDidCompleteCallback {
+  (param: HandlerDidCompleteCallbackParam): Promise<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;
+}

package/src/utils/pluginUtils.ts

@@ -0,0 +1,15 @@
+/*
+  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 { SerwistPlugin } from "../types.js";
+
+export const pluginUtils = {
+  filter: (plugins: SerwistPlugin[], callbackName: string): SerwistPlugin[] => {
+    return plugins.filter((plugin) => callbackName in plugin);
+  },
+};

package/src/utils/welcome.ts

@@ -0,0 +1,25 @@
+/*
+  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 } from "../_private/logger.js";
+
+// A SerwistCore instance must be exported before we can use the logger.
+// This is so it can get the current log level.
+if (process.env.NODE_ENV !== "production") {
+  const padding = "   ";
+  logger.groupCollapsed("Welcome to Serwist!");
+  logger.log(
+    "You are currently using a development build. " +
+      "By default this will switch to prod builds when not on localhost. " +
+      "You can force this with serwist.setConfig({debug: true|false}).",
+  );
+  logger.log(`📖 Read the guides and documentation\n${padding}https://developers.google.com/web/tools/workbox/`);
+  logger.log(`❓ Use the Discussions tab on Github to ask questions\n${padding}https://github.com/serwist/serwist/discussions`);
+  logger.log(`🐛 Found a bug? Report it on GitHub\n${padding}https://github.com/serwist/serwist/issues/new`);
+  logger.groupEnd();
+}

package/dist/_private/Deferred.d.cts

@@ -1,18 +0,0 @@
-/**
- * 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
- */
-declare 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();
-}
-export { Deferred };

package/dist/_private/SerwistError.d.cts

@@ -1,23 +0,0 @@
-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
- */
-declare 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: string, details?: MapLikeObject);
-}
-export { SerwistError };

package/dist/_private/assert.d.cts

@@ -1,10 +0,0 @@
-import type { MapLikeObject } from "../types.js";
-declare const finalAssertExports: {
-    hasMethod: (object: MapLikeObject, expectedMethod: string, details: MapLikeObject) => void;
-    isArray: (value: any[], details: MapLikeObject) => void;
-    isInstance: (object: unknown, expectedClass: Function, details: MapLikeObject) => void;
-    isOneOf: (value: any, validValues: any[], details: MapLikeObject) => void;
-    isType: (object: unknown, expectedType: string, details: MapLikeObject) => void;
-    isArrayOfClass: (value: any, expectedClass: Function, details: MapLikeObject) => void;
-} | null;
-export { finalAssertExports as assert };

package/dist/_private/cacheMatchIgnoreParams.d.cts

@@ -1,14 +0,0 @@
-/**
- * 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
- */
-declare function cacheMatchIgnoreParams(cache: Cache, request: Request, ignoreParams: string[], matchOptions?: CacheQueryOptions): Promise<Response | undefined>;
-export { cacheMatchIgnoreParams };

package/dist/_private/cacheNames.d.cts

@@ -1,39 +0,0 @@
-export interface CacheNameDetails {
-    googleAnalytics: string;
-    precache: string;
-    prefix: string;
-    runtime: string;
-    suffix: string;
-}
-export interface PartialCacheNameDetails {
-    /**
-     * The string to add to the beginning of the precache and runtime cache names.
-     */
-    prefix?: string;
-    /**
-     * The string to add to the end of the precache and runtime cache names.
-     */
-    suffix?: string;
-    /**
-     * The cache name to use for precache caching.
-     */
-    precache?: string;
-    /**
-     * The cache name to use for runtime caching.
-     */
-    runtime?: string;
-    /**
-     * The cache name to use for `@serwist/google-analytics` caching.
-     */
-    googleAnalytics?: string;
-    [propName: string]: string | undefined;
-}
-export type CacheNameDetailsProp = "googleAnalytics" | "precache" | "prefix" | "runtime" | "suffix";
-export declare const cacheNames: {
-    updateDetails: (details: PartialCacheNameDetails) => void;
-    getGoogleAnalyticsName: (userCacheName?: string) => string;
-    getPrecacheName: (userCacheName?: string) => string;
-    getPrefix: () => string;
-    getRuntimeName: (userCacheName?: string) => string;
-    getSuffix: () => string;
-};

package/dist/_private/canConstructReadableStream.d.cts

@@ -1,11 +0,0 @@
-/**
- * A utility function that determines whether the current browser supports
- * constructing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/ReadableStream)
- * object.
- *
- * @returns `true`, if the current browser can successfully construct a `ReadableStream`, `false` otherwise.
- *
- * @private
- */
-declare function canConstructReadableStream(): boolean;
-export { canConstructReadableStream };

package/dist/_private/canConstructResponseFromBodyStream.d.cts

@@ -1,10 +0,0 @@
-/**
- * A utility function that determines whether the current browser supports
- * constructing a new `Response` from a `response.body` stream.
- *
- * @returns `true`, if the current browser can successfully construct
- * a `Response` from a `response.body` stream, `false` otherwise.
- * @private
- */
-declare function canConstructResponseFromBodyStream(): boolean;
-export { canConstructResponseFromBodyStream };

package/dist/_private/dontWaitFor.d.cts

@@ -1,6 +0,0 @@
-/**
- * A helper function that prevents a promise from being flagged as unused.
- *
- * @private
- **/
-export declare function dontWaitFor(promise: Promise<any>): void;

package/dist/_private/executeQuotaErrorCallbacks.d.cts

@@ -1,8 +0,0 @@
-/**
- * Runs all of the callback functions, one at a time sequentially, in the order
- * in which they were registered.
- *
- * @private
- */
-declare function executeQuotaErrorCallbacks(): Promise<void>;
-export { executeQuotaErrorCallbacks };

package/dist/_private/getFriendlyURL.d.cts

@@ -1,2 +0,0 @@
-declare const getFriendlyURL: (url: URL | string) => string;
-export { getFriendlyURL };

package/dist/_private/logger.d.cts

@@ -1,10 +0,0 @@
-declare global {
-    interface WorkerGlobalScope {
-        __WB_DISABLE_DEV_LOGS: boolean;
-    }
-    interface Window {
-        __WB_DISABLE_DEV_LOGS: boolean;
-    }
-}
-declare const logger: Console;
-export { logger };

package/dist/_private/resultingClientExists.d.cts

@@ -1,11 +0,0 @@
-/**
- * Returns a promise that resolves to a window client matching the passed
- * `resultingClientId`. For browsers that don't support `resultingClientId`
- * or if waiting for the resulting client to apper takes too long, resolve to
- * `undefined`.
- *
- * @param resultingClientId
- * @returns
- * @private
- */
-export declare function resultingClientExists(resultingClientId?: string): Promise<Client | undefined>;

package/dist/_private/timeout.d.cts

@@ -1,9 +0,0 @@
-/**
- * Returns a promise that resolves and the passed number of milliseconds.
- * This utility is an async/await-friendly version of `setTimeout`.
- *
- * @param ms
- * @returns
- * @private
- */
-export declare function timeout(ms: number): Promise<unknown>;

package/dist/_private/waitUntil.d.cts

@@ -1,11 +0,0 @@
-/**
- * A utility method that makes it easier to use `event.waitUntil` with
- * async functions and return the result.
- *
- * @param event
- * @param asyncFn
- * @returns
- * @private
- */
-declare function waitUntil(event: ExtendableEvent, asyncFn: () => Promise<any>): Promise<any>;
-export { waitUntil };