@vouchington/utils 0.7.4 → 0.7.5

package/README.md

@@ -36,6 +36,10 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
   request/acknowledge round trip with an injected message type and acceptance check, and a named
   Web Lock wrapper. Request actions, expected state transitions, and the bind/clear/reconcile
   sequence stay in the application.
+- `service-worker-activation`: `waitForActiveServiceWorker(registration, options)` resolves when
+  the registration has an active worker. An installing or waiting worker is preferred over
+  `serviceWorker.ready`. `timeoutMs` bounds the wait; omit it to wait without a deadline. The
+  caller supplies the timeout and may inject `serviceWorker` (default `navigator.serviceWorker`).
 - `json-ld`: schema.org JSON-LD builders (organization, website, navigation, collection, thing,
   comparison, item list, breadcrumb, profile) and script-safe serialization. Callers inject the
   absolute-URL resolver and site name; product schemas such as posts stay in the application.

package/dist/service-worker-activation.d.mts

@@ -0,0 +1,26 @@
+export declare class ServiceWorkerActivationTimeoutError extends Error {
+    constructor();
+}
+export interface WaitForActiveServiceWorkerOptions {
+    timeoutMs?: number;
+    /** Defaults to navigator.serviceWorker; injectable for tests. */
+    serviceWorker?: ServiceWorkerContainer;
+}
+declare global {
+    interface ServiceWorker extends EventTarget {
+        readonly state: 'parsed' | 'installing' | 'installed' | 'activating' | 'activated' | 'redundant';
+    }
+    interface ServiceWorkerRegistration {
+        readonly active: ServiceWorker | null;
+        readonly installing: ServiceWorker | null;
+        readonly waiting: ServiceWorker | null;
+    }
+    interface ServiceWorkerContainer {
+        readonly ready: Promise<ServiceWorkerRegistration>;
+    }
+    interface Navigator {
+        readonly serviceWorker: ServiceWorkerContainer;
+    }
+}
+/** Resolves when `registration` has an active worker. Pass `timeoutMs` to bound the wait. */
+export declare function waitForActiveServiceWorker(registration: ServiceWorkerRegistration, options?: WaitForActiveServiceWorkerOptions): Promise<ServiceWorkerRegistration>;

package/dist/service-worker-activation.mjs

@@ -0,0 +1,50 @@
+export class ServiceWorkerActivationTimeoutError extends Error {
+    constructor() {
+        super('Timed out waiting for the service worker to activate.');
+        this.name = 'ServiceWorkerActivationTimeoutError';
+    }
+}
+/** Resolves when `registration` has an active worker. Pass `timeoutMs` to bound the wait. */
+export function waitForActiveServiceWorker(registration, options = {}) {
+    const replacement = registration.installing ?? registration.waiting;
+    if (!replacement) {
+        if (registration.active)
+            return Promise.resolve(registration);
+        const container = options.serviceWorker ?? navigator.serviceWorker;
+        return waitWithOptionalTimeout(container.ready, options.timeoutMs);
+    }
+    if (replacement.state === 'activated')
+        return Promise.resolve(registration);
+    return waitForReplacement(registration, replacement, options.timeoutMs);
+}
+function waitForReplacement(registration, worker, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timeout = timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => finish(() => reject(new ServiceWorkerActivationTimeoutError())), timeoutMs);
+        function finish(settle) {
+            worker.removeEventListener('statechange', onStateChange);
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            settle();
+        }
+        function onStateChange() {
+            if (worker.state === 'activated')
+                finish(() => resolve(registration));
+            else if (worker.state === 'redundant') {
+                finish(() => reject(new Error('Service worker replacement became redundant.')));
+            }
+        }
+        worker.addEventListener('statechange', onStateChange);
+        onStateChange();
+    });
+}
+function waitWithOptionalTimeout(ready, timeoutMs) {
+    if (timeoutMs === undefined)
+        return ready;
+    let timeout;
+    const timedOut = new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new ServiceWorkerActivationTimeoutError()), timeoutMs);
+    });
+    return Promise.race([ready, timedOut]).finally(() => clearTimeout(timeout));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -65,6 +65,11 @@
       "import": "./dist/web-push-binding.mjs",
       "default": "./dist/web-push-binding.mjs"
     },
+    "./service-worker-activation": {
+      "types": "./dist/service-worker-activation.d.mts",
+      "import": "./dist/service-worker-activation.mjs",
+      "default": "./dist/service-worker-activation.mjs"
+    },
     "./json-ld": {
       "types": "./dist/json-ld.d.mts",
       "import": "./dist/json-ld.mjs",