@serwist/core 8.1.0 → 8.2.0

package/dist/_private/Deferred.d.cts

@@ -0,0 +1,18 @@
+/**
+ * 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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,10 @@
+/**
+ * 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

@@ -0,0 +1,6 @@
+/**
+ * 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

@@ -0,0 +1,8 @@
+/**
+ * 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

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

package/dist/_private/logger.d.cts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,11 @@
+/**
+ * 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 };

package/dist/cacheNames.d.cts

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,6 @@
+/**
+ * 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

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,154 @@
+'use strict';
+
+var quotaErrorCallbacks = require('./quotaErrorCallbacks-t3P-jWKl.js');
+
+/**
+ * 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
+ */ // Can't change Function type
+// eslint-disable-next-line @typescript-eslint/ban-types
+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") {
+        Object.keys(details).forEach((key)=>{
+            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

@@ -0,0 +1,244 @@
+'use strict';
+
+var quotaErrorCallbacks = require('./quotaErrorCallbacks-t3P-jWKl.js');
+
+/*
+  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 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 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;
+    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;
+            } else {
+                // 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;