@budarin/pluggable-serviceworker 1.5.4 → 1.5.6

package/README.md

@@ -220,7 +220,6 @@ initServiceWorker([cachePlugin]);
 
 // С onError - ошибки будут обработаны
 initServiceWorker([cachePlugin], {
-    logger: console,
     onError: (error, event, errorType) => {
         console.error('Service Worker error:', error, errorType);
     },
@@ -245,33 +244,45 @@ const options = {
         logger.info(`Ошибка типа "${errorType}":`, error);
 
         switch (errorType) {
+            // Ошибки в плагинах при обработке соответствующего события
+            case ServiceWorkerErrorType.INSTALL_ERROR:
+            case ServiceWorkerErrorType.ACTIVATE_ERROR:
+            case ServiceWorkerErrorType.FETCH_ERROR:
+            case ServiceWorkerErrorType.MESSAGE_ERROR:
+            case ServiceWorkerErrorType.SYNC_ERROR:
+            case ServiceWorkerErrorType.PERIODICSYNC_ERROR:
+            case ServiceWorkerErrorType.PUSH_ERROR:
+                logger.error(`Plugin error (${errorType}):`, error);
+
+                // если нужно - мы можем получить конкретную точку в коде того плагина в котором произошла ошибка
+                if (error instanceof Error && error.stack) {
+                    logger.error('Plugin error Stack:', error.stack);
+                }
+
+                break;
+
+            // Глобальные JavaScript ошибки
             case ServiceWorkerErrorType.ERROR:
-                // JavaScript ошибки
                 logger.error('JavaScript error:', error);
                 break;
 
-            case ServiceWorkerErrorType.MESSAGE_ERROR:
-                // Ошибки сообщений
+            // Глобальное событие messageerror (например, ошибка structured clone)
+            case ServiceWorkerErrorType.MESSAGE_ERROR_HANDLER:
                 logger.error('Message error:', error);
                 break;
 
+            // Необработанные Promise rejection
             case ServiceWorkerErrorType.UNHANDLED_REJECTION:
-                // Необработанные Promise rejection
                 logger.error('Unhandled promise rejection:', error);
                 break;
 
+            // Обработанные Promise rejection
             case ServiceWorkerErrorType.REJECTION_HANDLED:
-                // Обработанные Promise rejection
                 logger.info('Promise rejection handled:', error);
                 break;
 
-            case ServiceWorkerErrorType.PLUGIN_ERROR:
-                // Ошибки в плагинах
-                logger.error('Plugin error:', error);
-                break;
-
+            // Неизвестные типы ошибок
             default:
-                // Неизвестные типы ошибок
                 logger.error('Unknown error type:', error);
 
                 // можно даже так - отправка ошибки в аналитику
@@ -606,16 +617,23 @@ activateOnNextVisitServiceWorker({
 });
 ```
 
-На странице регистрируйте этот файл: `navigator.serviceWorker.register('/sw.js')` (или путь, по которому сборка отдаёт ваш sw.js).
-
 ### Публикуемые утилиты
 
-Утилиты, доступные для использования в своих плагинах. Импорт: `@budarin/pluggable-serviceworker/utils`.
+| Название                                     | Где использовать | Описание                                                                                                                                                                                                 |
+| -------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerServiceWorker(scriptURL, options?)` | клиент           | Регистрация SW; при первом заходе при необходимости один автоматический reload (обход [бага браузера](https://issues.chromium.org/issues/482903583)). Импорт: `@budarin/pluggable-serviceworker/client`. |
+| `normalizeUrl(url)`                          | SW               | Нормализует URL (относительный → абсолютный по origin SW) для сравнения. Импорт: `@budarin/pluggable-serviceworker/utils`.                                                                               |
+| `notifyClients(messageType)`                 | SW               | Отправляет сообщение `{ type: messageType }` всем окнам-клиентам. Импорт: `@budarin/pluggable-serviceworker/utils`.                                                                                      |
+
+На странице используйте **клиентский API** библиотеки, чтобы SW корректно взял контроль уже на первой загрузке (обход [бага браузера](https://issues.chromium.org/issues/482903583)):
+
+```typescript
+import { registerServiceWorker } from '@budarin/pluggable-serviceworker/client';
+
+const reg = await registerServiceWorker('/sw.js');
+```
 
-| Название                     | Описание                                                                 |
-| ---------------------------- | ------------------------------------------------------------------------ |
-| `normalizeUrl(url)`          | Нормализует URL (относительный → абсолютный по origin SW) для сравнения. |
-| `notifyClients(messageType)` | Отправляет сообщение `{ type: messageType }` всем окнам-клиентам (SW).   |
+Без этого API на первом визите страница может остаться без контроллера до перезагрузки.
 
 ## Разработка пакета плагина
 

package/dist/client/index.d.ts

@@ -0,0 +1 @@
+export { registerServiceWorker } from './register.js';

package/dist/client/index.js

@@ -0,0 +1 @@
+export { registerServiceWorker } from './register.js';

package/dist/client/register.d.ts

@@ -0,0 +1 @@
+export declare function registerServiceWorker(scriptURL: string, options?: RegistrationOptions): Promise<ServiceWorkerRegistration | undefined>;

package/dist/client/register.js

@@ -0,0 +1,22 @@
+export async function registerServiceWorker(scriptURL, options) {
+    if (!('serviceWorker' in navigator)) {
+        return undefined;
+    }
+    const reg = await navigator.serviceWorker.register(scriptURL, options);
+    await navigator.serviceWorker.ready;
+    if (navigator.serviceWorker.controller != null) {
+        return reg;
+    }
+    const key = `pluggable-sw-reload-${reg.scope}`;
+    try {
+        if (sessionStorage.getItem(key) != null) {
+            return reg;
+        }
+        sessionStorage.setItem(key, '1');
+        location.reload();
+    }
+    catch {
+        return reg;
+    }
+    return reg;
+}

package/dist/client/updateWhenControlled.d.ts

@@ -0,0 +1,3 @@
+export declare function updateWhenControlled(registration: ServiceWorkerRegistration, options?: {
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/client/updateWhenControlled.js

@@ -0,0 +1,25 @@
+export function updateWhenControlled(registration, options = {}) {
+    const { timeoutMs = 5000 } = options;
+    if (navigator.serviceWorker.controller != null) {
+        registration.update();
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const doUpdate = () => {
+            registration.update();
+            cleanup();
+            resolve();
+        };
+        const cleanup = () => {
+            navigator.serviceWorker.removeEventListener('controllerchange', onControllerChange);
+            clearTimeout(timer);
+        };
+        const onControllerChange = () => {
+            if (navigator.serviceWorker.controller != null) {
+                doUpdate();
+            }
+        };
+        navigator.serviceWorker.addEventListener('controllerchange', onControllerChange);
+        const timer = setTimeout(doUpdate, timeoutMs);
+    });
+}

package/dist/index.d.ts

@@ -1,7 +1,13 @@
 export declare enum ServiceWorkerErrorType {
     ERROR = "error",
-    PLUGIN_ERROR = "plugin_error",
+    INSTALL_ERROR = "install_error",
+    ACTIVATE_ERROR = "activate_error",
+    FETCH_ERROR = "fetch_error",
     MESSAGE_ERROR = "messageerror",
+    MESSAGE_ERROR_HANDLER = "message_error_handler",
+    SYNC_ERROR = "sync_error",
+    PERIODICSYNC_ERROR = "periodicsync_error",
+    PUSH_ERROR = "push_error",
     REJECTION_HANDLED = "rejectionhandled",
     UNHANDLED_REJECTION = "unhandledrejection"
 }

package/dist/index.js

@@ -2,8 +2,14 @@ import { SW_EVENT_PUSH, SW_EVENT_SYNC, SW_EVENT_ERROR, SW_EVENT_FETCH, SW_EVENT_
 export var ServiceWorkerErrorType;
 (function (ServiceWorkerErrorType) {
     ServiceWorkerErrorType["ERROR"] = "error";
-    ServiceWorkerErrorType["PLUGIN_ERROR"] = "plugin_error";
+    ServiceWorkerErrorType["INSTALL_ERROR"] = "install_error";
+    ServiceWorkerErrorType["ACTIVATE_ERROR"] = "activate_error";
+    ServiceWorkerErrorType["FETCH_ERROR"] = "fetch_error";
     ServiceWorkerErrorType["MESSAGE_ERROR"] = "messageerror";
+    ServiceWorkerErrorType["MESSAGE_ERROR_HANDLER"] = "message_error_handler";
+    ServiceWorkerErrorType["SYNC_ERROR"] = "sync_error";
+    ServiceWorkerErrorType["PERIODICSYNC_ERROR"] = "periodicsync_error";
+    ServiceWorkerErrorType["PUSH_ERROR"] = "push_error";
     ServiceWorkerErrorType["REJECTION_HANDLED"] = "rejectionhandled";
     ServiceWorkerErrorType["UNHANDLED_REJECTION"] = "unhandledrejection";
 })(ServiceWorkerErrorType || (ServiceWorkerErrorType = {}));
@@ -48,12 +54,12 @@ export function createEventHandlers(plugins, options) {
         install: (event) => {
             event.waitUntil(Promise.all(handlers.install.map((handler) => Promise.resolve()
                 .then(() => handler(event, logger))
-                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR)))));
+                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.INSTALL_ERROR)))));
         },
         activate: (event) => {
             event.waitUntil(Promise.all(handlers.activate.map((handler) => Promise.resolve()
                 .then(() => handler(event, logger))
-                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR)))));
+                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.ACTIVATE_ERROR)))));
         },
         fetch: (event) => {
             event.respondWith((async () => {
@@ -65,14 +71,14 @@ export function createEventHandlers(plugins, options) {
                         }
                     }
                     catch (error) {
-                        options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR);
+                        options.onError?.(error, event, ServiceWorkerErrorType.FETCH_ERROR);
                     }
                 }
                 try {
                     return await fetch(event.request);
                 }
                 catch (error) {
-                    options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR);
+                    options.onError?.(error, event, ServiceWorkerErrorType.FETCH_ERROR);
                     return new Response('', {
                         status: 503,
                         statusText: 'Service Unavailable',
@@ -86,19 +92,19 @@ export function createEventHandlers(plugins, options) {
                     handler(event, logger);
                 }
                 catch (error) {
-                    options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR);
+                    options.onError?.(error, event, ServiceWorkerErrorType.MESSAGE_ERROR);
                 }
             });
         },
         sync: (event) => {
             event.waitUntil(Promise.all(handlers.sync.map((handler) => Promise.resolve()
                 .then(() => handler(event, logger))
-                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR)))));
+                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.SYNC_ERROR)))));
         },
         periodicsync: (event) => {
             event.waitUntil(Promise.all(handlers.periodicsync.map((handler) => Promise.resolve()
                 .then(() => handler(event, logger))
-                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR)))));
+                .catch((error) => options.onError?.(error, event, ServiceWorkerErrorType.PERIODICSYNC_ERROR)))));
         },
         push: (event) => {
             event.waitUntil((async () => {
@@ -109,7 +115,7 @@ export function createEventHandlers(plugins, options) {
                         returns.push(result);
                     }
                     catch (error) {
-                        options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR);
+                        options.onError?.(error, event, ServiceWorkerErrorType.PUSH_ERROR);
                         returns.push(undefined);
                     }
                 }
@@ -161,7 +167,7 @@ export function createEventHandlers(plugins, options) {
                     await self.registration.showNotification(title, opts);
                 }
                 catch (error) {
-                    options.onError?.(error, event, ServiceWorkerErrorType.PLUGIN_ERROR);
+                    options.onError?.(error, event, ServiceWorkerErrorType.PUSH_ERROR);
                 }
             })());
         },
@@ -175,7 +181,7 @@ export function createEventHandlers(plugins, options) {
         },
         messageerror: (event) => {
             try {
-                options.onError?.(event.data, event, ServiceWorkerErrorType.MESSAGE_ERROR);
+                options.onError?.(event.data, event, ServiceWorkerErrorType.MESSAGE_ERROR_HANDLER);
             }
             catch (error) {
                 logger.error('Error in messageerror handler:', error);

package/dist/plugins/reloadUncontrolledClients.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from '../index.js';
+export declare function reloadUncontrolledClients(): Plugin;

package/dist/plugins/reloadUncontrolledClients.js

@@ -0,0 +1,15 @@
+export function reloadUncontrolledClients() {
+    return {
+        name: 'reloadUncontrolledClients',
+        activate: async () => {
+            const controlled = await self.clients.matchAll({ type: 'window' });
+            if (controlled.length > 0)
+                return;
+            const all = await self.clients.matchAll({
+                type: 'window',
+                includeUncontrolled: true,
+            });
+            await Promise.all(all.map((client) => client.navigate(client.url)));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@budarin/pluggable-serviceworker",
-  "version": "1.5.4",
+  "version": "1.5.6",
   "description": "Extensible via plugins service worker",
   "keywords": [
     "serviceworker",
@@ -21,6 +21,7 @@
   ],
   "exports": {
     ".": "./dist/index.js",
+    "./client": "./dist/client/index.js",
     "./plugins": "./dist/plugins/index.js",
     "./presets": "./dist/presets/index.js",
     "./sw": "./dist/sw/index.js",
@@ -44,6 +45,7 @@
     "test:watch": "vitest",
     "clear-caches": "sh scripts/clear-caches.sh",
     "pnpm-install": "pnpm install",
+    "sync-workspace": "sh scripts/sync-workspace.sh",
     "upgrade-deps": "sh scripts/upgrade-deps.sh",
     "publish-package": "pnpm build && pnpm publish --access=public"
   }