@budarin/pluggable-serviceworker 1.5.3 → 1.5.5

package/README.md

@@ -77,13 +77,13 @@ pnpm add @budarin/pluggable-serviceworker
 ### Базовое использование
 
 ```typescript
-// sw.js
+// precacheAndServePlugin.js
 import {
     type Plugin,
     initServiceWorker,
 } from '@budarin/pluggable-serviceworker';
 
-function precacheAndServePlugin(config: {
+export function precacheAndServePlugin(config: {
     cacheName: string;
     assets: string[];
 }): Plugin {
@@ -115,6 +115,11 @@ function precacheAndServePlugin(config: {
         },
     };
 }
+```
+
+```typescript
+// sw.ts
+import { precacheAndServePlugin } from './precacheAndServePlugin';
 
 initServiceWorker([
     precacheAndServePlugin({
@@ -124,22 +129,11 @@ initServiceWorker([
 ]);
 ```
 
-**Важно:**
-
-- для `fetch` плагину не нужно самому вызывать `fetch(event.request)` — если все плагины вернули `undefined`, фреймворк сам идёт в сеть.
-- конфиг плагина задаётся по месту вызова фабрики; в `options` только `logger?` и `onError?`.
-
-### Фабрика плагинов
-
-**Плагин** — это объект с полем `name` и опциональными обработчиками (`install`, `fetch`, `activate` и т.д.). В массив `initServiceWorker(plugins, options)` передаются именно такие объекты.
-
-**Фабрика плагина** — функция, которая принимает конфиг и возвращает плагин (объект). Например: `precache(config)`, `serveFromCache(config)` или собственная `precacheAndServePlugin(config)` из примера выше. Конфиг задаётся по месту вызова фабрики; в общий `options` попадают только `logger?` и `onError?`.
-
 ## Демо
 
 В папке [demo/](demo/) — приложение **React + Vite** с пресетом **offlineFirst** и типовым сервис-воркером **activateOnSignal**. Запуск из корня: `pnpm start`. Подробности — в [demo/README.md](demo/README.md).
 
-## `initServiceWorker(plugins, options)`
+## initServiceWorker(plugins, options)
 
 `initServiceWorker` — точка входа: регистрирует обработчики событий Service Worker (`install`, `activate`, `fetch`, …) и прогоняет их через список плагинов.
 
@@ -226,7 +220,6 @@ initServiceWorker([cachePlugin]);
 
 // С onError - ошибки будут обработаны
 initServiceWorker([cachePlugin], {
-    logger: console,
     onError: (error, event, errorType) => {
         console.error('Service Worker error:', error, errorType);
     },
@@ -251,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);
 
                 // можно даже так - отправка ошибки в аналитику
@@ -304,7 +309,13 @@ initServiceWorker(
 );
 ```
 
-## 🔌 Интерфейс плагина
+## Плагины
+
+**Плагин** — это объект с полем `name` и опциональными обработчиками (`install`, `fetch`, `activate` и т.д.). В массив `initServiceWorker(plugins, options)` передаются именно такие объекты.
+
+**Фабрика плагина** — функция, которая принимает конфиг и возвращает плагин (объект). Например: `precache(config)`, `serveFromCache(config)` или собственная `precacheAndServePlugin(config)` из примера выше. Конфиг задаётся по месту вызова фабрики; в общий `options` попадают только `logger?` и `onError?`.
+
+### 🔌 Интерфейс плагина
 
 Плагин — объект, реализующий интерфейс `ServiceWorkerPlugin`. Во все обработчики вторым аргументом передаётся **logger** (всегда определён: из `options` или `console`). Специфичный для плагина конфиг задаётся при вызове **фабрики** плагина; в `options` только `logger?` и `onError?`. Параметр типа `_C` (например `PluginContext`) используется для типизации; по умолчанию контекст содержит только `logger`.
 
@@ -488,7 +499,6 @@ function authPlugin(config: { protectedPaths: string[] }): Plugin {
 ### Примитивы (плагины)
 
 Один примитив — одна операция. Импорт: `@budarin/pluggable-serviceworker/plugins`.
-
 Примитивы с конфигом — **фабрики плагинов** (см. раздел «Фабрика плагинов»): конфиг передаётся при вызове по месту использования; в `options` в `initServiceWorker` попадают только `logger?` и `onError?`. Примитивы без конфига (`skipWaiting`, `claim`, …) — готовые объекты плагинов.
 
 | Название                        | Событие    | Описание                                                                                                                     |
@@ -512,9 +522,7 @@ function authPlugin(config: { protectedPaths: string[] }): Plugin {
 
 Обработчики одного типа (`install`, `activate` и т.д.) у разных плагинов выполняются **параллельно**. Если нужна строгая последовательность (например «сначала claim, потом перезагрузка клиентов»), соберите один плагин, который по очереди вызывает логику примитивов — для гарантии порядка.
 
-**Пример: claimAndReloadClients как композиция двух примитивов**
-
-Плагин **claimAndReloadClients** вызывает существующие примитивы **claim** и **reloadClients** по очереди:
+Пример: claimAndReloadClients как композиция двух примитивов. Плагин вызывает существующие примитивы **claim** и **reloadClients** по очереди:
 
 ```typescript
 import { claim } from '@budarin/pluggable-serviceworker/plugins';
@@ -537,43 +545,24 @@ activate: (event, logger) =>
 // postsSwrPlugin.ts
 import type { Plugin } from '@budarin/pluggable-serviceworker';
 
-import {
-    precache,
-    serveFromCache,
-} from '@budarin/pluggable-serviceworker/plugins';
-import { initServiceWorker } from '@budarin/pluggable-serviceworker';
+import { staleWhileRevalidate } from '@budarin/pluggable-serviceworker/plugins';
 
 function postsSwrPlugin(config: {
     cacheName: string;
     pathPattern?: RegExp;
 }): Plugin {
     const { cacheName, pathPattern = /\/api\/posts(\/|$)/ } = config;
+    const swrPlugin = staleWhileRevalidate({ cacheName });
 
     return {
         name: 'postsSwr',
         order: 0,
 
-        fetch: async (event) => {
+        fetch: async (event, logger) => {
             if (!pathPattern.test(new URL(event.request.url).pathname)) {
                 return undefined;
             }
-
-            const cache = await caches.open(cacheName);
-            const cached = await cache.match(event.request);
-            const revalidate = fetch(event.request).then(async (response) => {
-                if (response.ok) {
-                    await cache.put(event.request, response.clone());
-                }
-
-                return response;
-            });
-
-            if (cached) {
-                void revalidate;
-                return cached;
-            }
-
-            return revalidate;
+            return swrPlugin.fetch!(event, logger);
         },
     };
 }
@@ -619,14 +608,12 @@ initServiceWorker(
 
 ```typescript
 // sw.js — точка входа вашего сервис-воркера
-import { customLogger } from './customLogger';
 import { activateOnNextVisitServiceWorker } from '@budarin/pluggable-serviceworker/sw';
 
 activateOnNextVisitServiceWorker({
-    assets: ['/', '/styles.css', '/script.js'],
     cacheName: 'my-cache-v1',
-    logger: customLogger,
-    onError: (err, event, type) => customLogger.error(type, err),
+    assets: ['/', '/styles.css', '/script.js'],
+    onError: (err, event, type) => console.error(type, err),
 });
 ```
 
@@ -655,7 +642,7 @@ activateOnNextVisitServiceWorker({
         "@budarin/pluggable-serviceworker": "^1.0.0"
     },
     "devDependencies": {
-        "@budarin/pluggable-serviceworker": "^1.5.0"
+        "@budarin/pluggable-serviceworker": "^1.5.5"
     }
 }
 ```

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@budarin/pluggable-serviceworker",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Extensible via plugins service worker",
   "keywords": [
     "serviceworker",