@serwist/core 8.4.3 → 9.0.0-preview.0

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/cacheNames.d.cts

@@ -1,20 +0,0 @@
-/**
- * Get the current cache names and prefix/suffix used by Workbox.
- *
- * `cacheNames.precache` is used for precached assets,
- * `cacheNames.googleAnalytics` is used by `@serwist/google-analytics` to
- * store `analytics.js`, and `cacheNames.runtime` is used for everything else.
- *
- * `cacheNames.prefix` can be used to retrieve just the current prefix value.
- * `cacheNames.suffix` can be used to retrieve just the current suffix value.
- *
- * @returns An object with `precache`, `runtime`, `prefix`, and `googleAnalytics` properties.
- */
-declare const cacheNames: {
-    readonly googleAnalytics: string;
-    readonly precache: string;
-    readonly prefix: string;
-    readonly runtime: string;
-    readonly suffix: string;
-};
-export { cacheNames };

package/dist/clientsClaim.d.cts

@@ -1,6 +0,0 @@
-/**
- * Claim any currently available clients once the service worker
- * becomes active. This is normally used in conjunction with `skipWaiting()`.
- */
-declare function clientsClaim(): void;
-export { clientsClaim };

package/dist/copyResponse.d.cts

@@ -1,20 +0,0 @@
-/**
- * Allows developers to copy a response and modify its `headers`, `status`,
- * or `statusText` values (the values settable via a
- * [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax)
- * object in the constructor).
- * To modify these values, pass a function as the second argument. That
- * function will be invoked with a single object with the response properties
- * `{headers, status, statusText}`. The return value of this function will
- * be used as the `ResponseInit` for the new `Response`. To change the values
- * either modify the passed parameter(s) and return it, or return a totally
- * new object.
- *
- * This method is intentionally limited to same-origin responses, regardless of
- * whether CORS was used or not.
- *
- * @param response
- * @param modifier
- */
-declare function copyResponse(response: Response, modifier?: (responseInit: ResponseInit) => ResponseInit): Promise<Response>;
-export { copyResponse };

package/dist/index.cjs

@@ -1,153 +0,0 @@
-'use strict';
-
-var quotaErrorCallbacks = require('./quotaErrorCallbacks.cjs');
-
-/**
- * Get the current cache names and prefix/suffix used by Workbox.
- *
- * `cacheNames.precache` is used for precached assets,
- * `cacheNames.googleAnalytics` is used by `@serwist/google-analytics` to
- * store `analytics.js`, and `cacheNames.runtime` is used for everything else.
- *
- * `cacheNames.prefix` can be used to retrieve just the current prefix value.
- * `cacheNames.suffix` can be used to retrieve just the current suffix value.
- *
- * @returns An object with `precache`, `runtime`, `prefix`, and `googleAnalytics` properties.
- */ const cacheNames = {
-    get googleAnalytics () {
-        return quotaErrorCallbacks.cacheNames.getGoogleAnalyticsName();
-    },
-    get precache () {
-        return quotaErrorCallbacks.cacheNames.getPrecacheName();
-    },
-    get prefix () {
-        return quotaErrorCallbacks.cacheNames.getPrefix();
-    },
-    get runtime () {
-        return quotaErrorCallbacks.cacheNames.getRuntimeName();
-    },
-    get suffix () {
-        return quotaErrorCallbacks.cacheNames.getSuffix();
-    }
-};
-
-/*
-  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.
-*/ // Give TypeScript the correct global.
-/**
- * Claim any currently available clients once the service worker
- * becomes active. This is normally used in conjunction with `skipWaiting()`.
- */ function clientsClaim() {
-    self.addEventListener("activate", ()=>self.clients.claim());
-}
-
-/**
- * Allows developers to copy a response and modify its `headers`, `status`,
- * or `statusText` values (the values settable via a
- * [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax)
- * object in the constructor).
- * To modify these values, pass a function as the second argument. That
- * function will be invoked with a single object with the response properties
- * `{headers, status, statusText}`. The return value of this function will
- * be used as the `ResponseInit` for the new `Response`. To change the values
- * either modify the passed parameter(s) and return it, or return a totally
- * new object.
- *
- * This method is intentionally limited to same-origin responses, regardless of
- * whether CORS was used or not.
- *
- * @param response
- * @param modifier
- */ async function copyResponse(response, modifier) {
-    let origin = null;
-    // If response.url isn't set, assume it's cross-origin and keep origin null.
-    if (response.url) {
-        const responseURL = new URL(response.url);
-        origin = responseURL.origin;
-    }
-    if (origin !== self.location.origin) {
-        throw new quotaErrorCallbacks.SerwistError("cross-origin-copy-response", {
-            origin
-        });
-    }
-    const clonedResponse = response.clone();
-    // Create a fresh `ResponseInit` object by cloning the headers.
-    const responseInit = {
-        headers: new Headers(clonedResponse.headers),
-        status: clonedResponse.status,
-        statusText: clonedResponse.statusText
-    };
-    // Apply any user modifications.
-    const modifiedResponseInit = modifier ? modifier(responseInit) : responseInit;
-    // Create the new response from the body stream and `ResponseInit`
-    // modifications. Note: not all browsers support the Response.body stream,
-    // so fall back to reading the entire body into memory as a blob.
-    const body = quotaErrorCallbacks.canConstructResponseFromBodyStream() ? clonedResponse.body : await clonedResponse.blob();
-    return new Response(body, modifiedResponseInit);
-}
-
-/**
- * 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) {
-    if (process.env.NODE_ENV !== "production") {
-        quotaErrorCallbacks.finalAssertExports.isType(callback, "function", {
-            moduleName: "@serwist/core",
-            funcName: "register",
-            paramName: "callback"
-        });
-    }
-    quotaErrorCallbacks.quotaErrorCallbacks.add(callback);
-    if (process.env.NODE_ENV !== "production") {
-        quotaErrorCallbacks.logger.log("Registered a callback to respond to quota errors.", callback);
-    }
-}
-
-/**
- * Modifies the default cache names used by the Serwist packages.
- * Cache names are generated as `<prefix>-<Cache Name>-<suffix>`.
- *
- * @param details
- */ function setCacheNameDetails(details) {
-    if (process.env.NODE_ENV !== "production") {
-        for (const key of Object.keys(details)){
-            quotaErrorCallbacks.finalAssertExports.isType(details[key], "string", {
-                moduleName: "@serwist/core",
-                funcName: "setCacheNameDetails",
-                paramName: `details.${key}`
-            });
-        }
-        if (details.precache?.length === 0) {
-            throw new quotaErrorCallbacks.SerwistError("invalid-cache-name", {
-                cacheNameId: "precache",
-                value: details.precache
-            });
-        }
-        if (details.runtime?.length === 0) {
-            throw new quotaErrorCallbacks.SerwistError("invalid-cache-name", {
-                cacheNameId: "runtime",
-                value: details.runtime
-            });
-        }
-        if (details.googleAnalytics?.length === 0) {
-            throw new quotaErrorCallbacks.SerwistError("invalid-cache-name", {
-                cacheNameId: "googleAnalytics",
-                value: details.googleAnalytics
-            });
-        }
-    }
-    quotaErrorCallbacks.cacheNames.updateDetails(details);
-}
-
-exports.cacheNames = cacheNames;
-exports.clientsClaim = clientsClaim;
-exports.copyResponse = copyResponse;
-exports.registerQuotaErrorCallback = registerQuotaErrorCallback;
-exports.setCacheNameDetails = setCacheNameDetails;

package/dist/index.internal.cjs

@@ -1,243 +0,0 @@
-'use strict';
-
-var quotaErrorCallbacks = require('./quotaErrorCallbacks.cjs');
-
-/*
-  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 {
-    promise;
-    resolve;
-    reject;
-    /**
-   * 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;
-        });
-    }
-}
-
-/*
-  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, ignoreParams) {
-    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, request, ignoreParams, matchOptions) {
-    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;
-}
-
-/*
-  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.
-*/ let supportStatus;
-/**
- * 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
- */ function canConstructReadableStream() {
-    if (supportStatus === undefined) {
-        // See https://github.com/GoogleChrome/workbox/issues/1473
-        try {
-            new ReadableStream({
-                start () {}
-            });
-            supportStatus = true;
-        } catch (error) {
-            supportStatus = false;
-        }
-    }
-    return supportStatus;
-}
-
-/*
-  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.
-*/ /**
- * A helper function that prevents a promise from being flagged as unused.
- *
- * @private
- **/ function dontWaitFor(promise) {
-    // Effective no-op.
-    void promise.then(()=>{});
-}
-
-/**
- * Runs all of the callback functions, one at a time sequentially, in the order
- * in which they were registered.
- *
- * @private
- */ async function executeQuotaErrorCallbacks() {
-    if (process.env.NODE_ENV !== "production") {
-        quotaErrorCallbacks.logger.log(`About to run ${quotaErrorCallbacks.quotaErrorCallbacks.size} callbacks to clean up caches.`);
-    }
-    for (const callback of quotaErrorCallbacks.quotaErrorCallbacks){
-        await callback();
-        if (process.env.NODE_ENV !== "production") {
-            quotaErrorCallbacks.logger.log(callback, "is complete.");
-        }
-    }
-    if (process.env.NODE_ENV !== "production") {
-        quotaErrorCallbacks.logger.log("Finished running callbacks.");
-    }
-}
-
-/*
-  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.
-*/ const getFriendlyURL = (url)=>{
-    const urlObj = new URL(String(url), location.href);
-    // See https://github.com/GoogleChrome/workbox/issues/2323
-    // We want to include everything, except for the origin if it's same-origin.
-    return urlObj.href.replace(new RegExp(`^${location.origin}`), "");
-};
-
-/*
-  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.
-*/ /**
- * 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
- */ function timeout(ms) {
-    return new Promise((resolve)=>setTimeout(resolve, ms));
-}
-
-const MAX_RETRY_TIME = 2000;
-/**
- * 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
- */ async function resultingClientExists(resultingClientId) {
-    if (!resultingClientId) {
-        return;
-    }
-    let existingWindows = await self.clients.matchAll({
-        type: "window"
-    });
-    const existingWindowIds = new Set(existingWindows.map((w)=>w.id));
-    let resultingWindow = undefined;
-    const startTime = performance.now();
-    // Only wait up to `MAX_RETRY_TIME` to find a matching client.
-    while(performance.now() - startTime < MAX_RETRY_TIME){
-        existingWindows = await self.clients.matchAll({
-            type: "window"
-        });
-        resultingWindow = existingWindows.find((w)=>{
-            if (resultingClientId) {
-                // If we have a `resultingClientId`, we can match on that.
-                return w.id === resultingClientId;
-            }
-            // Otherwise match on finding a window not in `existingWindowIds`.
-            return !existingWindowIds.has(w.id);
-        });
-        if (resultingWindow) {
-            break;
-        }
-        // Sleep for 100ms and retry.
-        await timeout(100);
-    }
-    return resultingWindow;
-}
-
-/*
-  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.
-*/ /**
- * A utility method that makes it easier to use `event.waitUntil` with
- * async functions and return the result.
- *
- * @param event
- * @param asyncFn
- * @returns
- * @private
- */ function waitUntil(event, asyncFn) {
-    const returnPromise = asyncFn();
-    event.waitUntil(returnPromise);
-    return returnPromise;
-}
-
-exports.SerwistError = quotaErrorCallbacks.SerwistError;
-exports.assert = quotaErrorCallbacks.finalAssertExports;
-exports.canConstructResponseFromBodyStream = quotaErrorCallbacks.canConstructResponseFromBodyStream;
-exports.logger = quotaErrorCallbacks.logger;
-exports.privateCacheNames = quotaErrorCallbacks.cacheNames;
-exports.Deferred = Deferred;
-exports.cacheMatchIgnoreParams = cacheMatchIgnoreParams;
-exports.canConstructReadableStream = canConstructReadableStream;
-exports.dontWaitFor = dontWaitFor;
-exports.executeQuotaErrorCallbacks = executeQuotaErrorCallbacks;
-exports.getFriendlyURL = getFriendlyURL;
-exports.resultingClientExists = resultingClientExists;
-exports.timeout = timeout;
-exports.waitUntil = waitUntil;

package/dist/models/messages/messageGenerator.d.cts

@@ -1 +0,0 @@
-export declare const messageGenerator: ((code: string, ...args: any[]) => string) | ((code: string, details?: {}) => string);