@budarin/pluggable-serviceworker 1.1.1 → 1.2.0

package/README.md

@@ -1,421 +1,502 @@
-# @budarin/pluggable-serviceworker
-
-🔌 Расширяемый через плагины Service Worker
-
-Библиотека для создания модульных и расширяемых Service Worker'ов с помощью системы плагинов.
-
-## 🚀 Почему этот пакет облегчает разработку?
-
-Разработка Service Worker'ов традиционно сложна из-за необходимости вручную управлять множественными обработчиками событий, обработкой ошибок и порядком выполнения. Этот пакет решает эти проблемы:
-
-### 🔌 **Модульная архитектура**
-
-- **Плагинная система** позволяет разбивать функциональность на независимые модули
-- Каждый плагин отвечает за свою задачу (кеширование, аутентификация, уведомления)
-- Легко добавлять/удалять функциональность без изменения основного кода
-- Не нужно думать об инфраструктурном коде в обработчиках событий - пишите простой код не думая о сложностях кода самого сервисворкера
-
-### 🎯 **Управление порядком выполнения**
-
-- **Предсказуемый порядок** - плагины без `order` выполняются первыми, затем по возрастанию `order`
-- **Гибкость** - можно контролировать последовательность инициализации
-- **Масштабируемость** - легко добавлять новые плагины в нужном месте
-
-### ⚡ **Оптимизированная логика выполнения**
-
-- **Параллельно** для `install`, `activate`, `message`, `sync` - независимые задачи выполняются одновременно
-- **Последовательно** для `fetch`, `push` - первый успешный результат прерывает цепочку
-- **Производительность** - правильный выбор стратегии для каждого типа события
-
-### 🛡️ **Централизованная обработка ошибок**
-
-- **Единый обработчик** для всех типов ошибок
-- **Типизированные ошибки** - знаешь, что именно сломалось
-- **Изоляция** - ошибка в одном плагине не ломает остальные
-- **Автоматическая обработка** глобальных событий ошибок
-
-### 📝 **Удобное логирование**
-
-- **Настраиваемый логгер** с разными уровнями
-- **Контекстная информация** в логах
-- **Отладка** становится намного проще
-
-## 📦 Установка
-
-```bash
-npm install @budarin/pluggable-serviceworker
-```
-
-или
-
-```bash
-pnpm add @budarin/pluggable-serviceworker
-```
-
-## 🚀 Быстрый старт
-
-### Базовое использование
-
-```typescript
-// sw.js
-import { initServiceWorker } from '@budarin/pluggable-serviceworker';
-
-// Простой плагин для кеширования
-const cachePlugin = {
-    name: 'cache-plugin',
-
-    install: async (event) => {
-        const cache = await caches.open('my-cache-v1');
-        await cache.addAll(['/', '/styles.css', '/script.js']);
-    },
-
-    fetch: async (event) => {
-        const cachedResponse = await caches.match(event.request);
-        return cachedResponse; // если результат undefined → фреймворк сам вызовет fetch(event.request)
-    },
-};
-
-// Инициализация Service Worker с плагинами
-initServiceWorker([cachePlugin], { logger: console });
-```
-
-**Важно:** для `fetch` плагину не нужно самому вызывать `fetch(event.request)`, если все плагины вернули `undefined` - фреймворк сам выполняет запрос в сеть.
-
-## ⚙️ Конфигурация
-
-Функция `initServiceWorker` принимает второй параметр `config` типа `ServiceWorkerConfig`:
-
-```typescript
-interface ServiceWorkerConfig {
-    logger?: Logger; // Опционально, по умолчанию console
-    onError?: (
-        error: Error | any,
-        event: Event,
-        errorType?: ServiceWorkerErrorType
-    ) => void;
-}
-```
-
-### Поля конфигурации
-
-#### `logger?: Logger` (опциональное)
-
-Объект для логирования с методами `info`, `warn`, `error`, `debug`. По умолчанию используется `console`. Может быть передан любой объект, реализующий интерфейс `Logger`.
-
-```typescript
-interface Logger {
-    info: (...data: unknown[]) => void;
-    warn: (...data: unknown[]) => void;
-    error: (...data: unknown[]) => void;
-    debug: (...data: unknown[]) => void;
-}
-```
-
-**Пример:**
-
-```typescript
-const logger = console; // Использование стандартного console
-
-const config = {
-    logger,
-    // или
-    logger: {
-        info: (...data) => customLog('INFO', ...data),
-        warn: (...data) => customLog('WARN', ...data),
-        error: (...data) => customLog('ERROR', ...data),
-        debug: (...data) => customLog('DEBUG', ...data),
-    },
-};
-```
-
-#### `onError?: (error, event, errorType) => void` (опциональное)
-
-Единый обработчик для всех типов ошибок в Service Worker. **Дефолтного обработчика ошибок нет** - если `onError` не передан, ошибки будут проигнорированы (не обработаны).
-
-**Параметры:**
-
-- `error: Error | any` - объект ошибки
-- `event: Event` - событие, в контексте которого произошла ошибка
-- `errorType?: ServiceWorkerErrorType` - тип ошибки (см. раздел "Обработка ошибок")
-
-**Важно:** Если `onError` не указан, ошибки в плагинах и глобальные ошибки будут проигнорированы. Для production-окружения рекомендуется всегда указывать `onError` для логирования и мониторинга ошибок.
-
-**Пример минимальной конфигурации:**
-
-```typescript
-// Без onError - ошибки будут проигнорированы
-initServiceWorker([cachePlugin], { logger: console });
-
-// С onError - ошибки будут обработаны
-const logger = console; // Использование стандартного console
-
-initServiceWorker([cachePlugin], {
-    logger,
-    onError: (error, event, errorType) => {
-        logger.error('Service Worker error:', error, errorType);
-    },
-});
-```
-
-### Обработка ошибок
-
-Библиотека предоставляет единый обработчик для всех типов ошибок в Service Worker:
-
-```typescript
-import {
-    initServiceWorker,
-    ServiceWorkerErrorType,
-} from '@budarin/pluggable-serviceworker';
-
-const logger = console; // или свой объект с методами info, warn, error, debug
-
-const config = {
-    logger,
-    onError: (error, event, errorType) => {
-        logger.info(`Ошибка типа "${errorType}":`, error);
-
-        switch (errorType) {
-            case ServiceWorkerErrorType.ERROR:
-                // JavaScript ошибки
-                logger.error('JavaScript error:', error);
-                break;
-
-            case ServiceWorkerErrorType.MESSAGE_ERROR:
-                // Ошибки сообщений
-                logger.error('Message error:', error);
-                break;
-
-            case ServiceWorkerErrorType.UNHANDLED_REJECTION:
-                // Необработанные Promise rejection
-                logger.error('Unhandled promise rejection:', error);
-                break;
-
-            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);
-
-                // можно даже так - отправка ошибки в аналитику
-                fetch('/api/errors', {
-                    method: 'POST',
-                    body: JSON.stringify({
-                        error: error.message,
-                        eventType: event.type,
-                        url: event.request?.url,
-                        timestamp: Date.now(),
-                    }),
-                }).catch(() => {
-                    // Игнорируем ошибки отправки логов
-                });
-        }
-    },
-};
-
-initServiceWorker(
-    [
-        /* ваши плагины */
-    ],
-    config
-);
-```
-
-## 🔌 Интерфейс плагина
-
-Каждый плагин должен реализовывать интерфейс `ServiceWorkerPlugin`:
-
-```typescript
-interface ServiceWorkerPlugin {
-    /** Уникальное имя плагина */
-    name: string;
-
-    /** Порядок выполнения (опционально) */
-    order?: number;
-
-    /** Обработчик события install */
-    install?: (event: ExtendableEvent) => Promise<void> | void;
-
-    /** Обработчик события activate */
-    activate?: (event: ExtendableEvent) => Promise<void> | void;
-
-    /** Обработчик события fetch */
-    fetch?: (
-        event: FetchEvent
-    ) => Promise<Response | undefined> | Response | undefined;
-
-    /** Обработчик события message */
-    message?: (event: SwMessageEvent) => void;
-
-    /** Обработчик события sync */
-    sync?: (event: SyncEvent) => Promise<void> | void;
-
-    /** Обработчик события push */
-    push?: (event: PushEvent) => Promise<void> | void;
-
-    /** Обработчик события periodicsync */
-    periodicsync?: (event: PeriodicSyncEvent) => Promise<void> | void;
-}
-```
-
-### 📝 Описание методов
-
-| Метод          | Событие        | Возвращает              | Описание                                |
-| -------------- | -------------- | ----------------------- | --------------------------------------- |
-| `install`      | `install`      | `void`                  | Инициализация плагина при установке SW  |
-| `activate`     | `activate`     | `void`                  | Активация плагина при обновлении SW     |
-| `fetch`        | `fetch`        | `Response \| undefined` | Обработка сетевых запросов              |
-| `message`      | `message`      | `void`                  | Обработка сообщений от основного потока |
-| `sync`         | `sync`         | `void`                  | Синхронизация данных в фоне             |
-| `push`         | `push`         | `void`                  | Обработка push-уведомлений              |
-| `periodicsync` | `periodicsync` | `void`                  | Периодические фоновые задачи            |
-
-### 🎯 Особенности обработчиков
-
-- **`fetch`**: Возвращает `Response` для завершения цепочки или `undefined` для передачи следующему плагину. Если все плагины вернули `undefined`, фреймворк вызывает `fetch(event.request)`
-- **Остальные**: Не возвращают значения, выполняются для всех плагинов
-- **Все методы опциональны** - реализуйте только нужные события
-
-### 🔄 Обновление Service Worker (skipWaiting / clients.claim)
-
-Библиотека **не вызывает** `skipWaiting()` и `clients.claim()` — это поведение задаётся индивидуально в каждом проекте и оставлено на усмотрение плагинов. При необходимости вызывайте их в своих обработчиках `install` и `activate`:
-
-```typescript
-const updatePlugin = {
-    name: 'update-plugin',
-    install: (event) => {
-        self.skipWaiting();
-    },
-    activate: (event) => {
-        event.waitUntil(self.clients.claim());
-    },
-};
-```
-
-## 🎯 Порядок выполнения
-
-Плагины выполняются в следующем порядке:
-
-1. **Сначала ВСЕ плагины без `order`** - в том порядке, в котором они были добавлены
-2. **Затем плагины с `order`** - в порядке возрастания значений `order`
-
-### Пример:
-
-```typescript
-const plugins = [
-    { name: 'first' }, // без order - выполняется первым
-    { name: 'fourth', order: 2 },
-    { name: 'second' }, // без order - выполняется вторым
-    { name: 'third', order: 1 },
-    { name: 'fifth' }, // без order - выполняется третьим
-];
-
-// Порядок выполнения: first → second → fifth → third → fourth
-```
-
-**Преимущества новой системы:**
-
-- 🎯 **Предсказуемость** - плагины без `order` всегда выполняются первыми
-- 🔧 **Простота** - не нужно знать, какие номера уже заняты
-- 📈 **Масштабируемость** - легко добавлять новые плагины в нужном порядке
-
-## ⚡ Логика выполнения обработчиков
-
-Разные типы событий Service Worker обрабатываются по-разному в зависимости от их специфики:
-
-### 🔄 Параллельное выполнение
-
-**События:** `install`, `activate`, `message`, `sync`, `periodicsync`
-
-Все обработчики выполняются **одновременно** с помощью `Promise.all()`:
-
-```typescript
-// Все плагины инициализируются параллельно
-const installPlugin1 = {
-    name: 'cache-assets',
-    install: async () => {
-        /* кеширование ресурсов приложения*/
-    },
-};
-const installPlugin2 = {
-    name: 'cache-ext',
-    install: async () => {
-        /* кэширование вспомогательных ресурсов */
-    },
-};
-
-// Оба install обработчика выполнятся одновременно
-```
-
-**Почему параллельно:**
-
-- **install/activate**: Все плагины должны инициализироваться независимо
-- **message**: Все плагины должны получить сообщение одновременно
-- **sync**: Разные задачи синхронизации независимы (синхронизация данных + кеша)
-- **periodicsync**: Периодические задачи независимы друг от друга
-
-### ➡️ Последовательное выполнение
-
-**События:** `fetch`, `push`
-
-Обработчики выполняются **по очереди** до первого успешного результата:
-
-#### Fetch - с прерыванием цепочки
-
-```typescript
-const authPlugin = {
-    name: 'auth',
-    // Без order - выполняется первым
-    fetch: async (event) => {
-        if (needsAuth(event.request)) {
-            return new Response('Unauthorized', { status: 401 }); // Прерывает цепочку
-        }
-        return undefined; // Передает следующему плагину
-    },
-};
-```
-
-**Почему последовательно:**
-
-- **fetch**: Нужен только один ответ, первый успешный прерывает цепочку. Если никто не вернул ответ — выполняется `fetch(event.request)`
-- **push**: Избегает конфликтов уведомлений, но все плагины должны обработать событие
-
-### 📋 Сводная таблица
-
-| Событие        | Выполнение      | Прерывание | Причина                          |
-| -------------- | --------------- | ---------- | -------------------------------- |
-| `install`      | Параллельно     | Нет        | Независимая инициализация        |
-| `activate`     | Параллельно     | Нет        | Независимая активация            |
-| `fetch`        | Последовательно | Да         | Нужен один ответ                 |
-| `message`      | Параллельно     | Нет        | Все получают сообщение           |
-| `sync`         | Параллельно     | Нет        | Независимые задачи               |
-| `periodicsync` | Параллельно     | Нет        | Независимые периодические задачи |
-| `push`         | Последовательно | Нет        | Избегание конфликтов             |
-
-## 🛡️ Обработка ошибок
-
-Библиотека автоматически перехватывает и обрабатывает все типы ошибок в Service Worker через единый обработчик `config.onError` (см. раздел [Конфигурация](#-конфигурация)).
-
-**Особенности:**
-
-- **Единый обработчик** - все типы ошибок обрабатываются через `config.onError` (опциональное поле)
-- **Дефолтного обработчика нет** - если `onError` не указан, ошибки будут проигнорированы
-- **Типизированные ошибки** - третий параметр `errorType` указывает тип ошибки из `ServiceWorkerErrorType`
-- **Глобальные события** - автоматическая обработка `error`, `messageerror`, `unhandledrejection`, `rejectionhandled`
-- **Изоляция ошибок** - ошибка в одном плагине не останавливает выполнение других
-- **Безопасность** - ошибки в самих обработчиках ошибок логируются через `logger.error`
-
-## Режим разработки
-
-Если нужно, чтобы в режиме разработки ни один из плагинов ничего не кэшировал и не пытался что-либо отдавать из кэша - можно использовть `import.meta.env.DEV` для Vite для условного использования кэширования.
-
-## 📄 Лицензия
-
-MIT © Vadim Budarin
+# @budarin/pluggable-serviceworker
+
+🔌 Расширяемый через плагины Service Worker
+
+Библиотека для создания модульных и расширяемых Service Worker'ов с помощью системы плагинов.
+
+## 🚀 Почему этот пакет облегчает разработку?
+
+Разработка Service Worker'ов традиционно сложна из-за необходимости вручную управлять множественными обработчиками событий, обработкой ошибок и порядком выполнения. Этот пакет решает эти проблемы:
+
+### 🔌 **Модульная архитектура**
+
+- **Плагинная система** позволяет разбивать функциональность на независимые модули
+- Каждый плагин отвечает за свою задачу (кеширование, аутентификация, уведомления)
+- Легко добавлять/удалять функциональность без изменения основного кода
+- Не нужно думать об инфраструктурном коде в обработчиках событий - пишите простой код не думая о сложностях кода самого сервисворкера
+
+### 🎯 **Управление порядком выполнения**
+
+- **Предсказуемый порядок** - плагины без `order` выполняются первыми, затем по возрастанию `order`
+- **Гибкость** - можно контролировать последовательность инициализации
+- **Масштабируемость** - легко добавлять новые плагины в нужном месте
+
+### ⚡ **Оптимизированная логика выполнения**
+
+- **Параллельно** для `install`, `activate`, `message`, `sync` - независимые задачи выполняются одновременно
+- **Последовательно** для `fetch`, `push` - первый успешный результат прерывает цепочку
+- **Производительность** - правильный выбор стратегии для каждого типа события
+
+### 🛡️ **Централизованная обработка ошибок**
+
+- **Единый обработчик** для всех типов ошибок
+- **Типизированные ошибки** - знаешь, что именно сломалось
+- **Изоляция** - ошибка в одном плагине не ломает остальные
+- **Автоматическая обработка** глобальных событий ошибок
+
+### 📝 **Удобное логирование**
+
+- **Настраиваемый логгер** с разными уровнями
+- **Контекстная информация** в логах
+- **Отладка** становится намного проще
+
+## 📦 Установка
+
+```bash
+npm install @budarin/pluggable-serviceworker
+```
+
+или
+
+```bash
+pnpm add @budarin/pluggable-serviceworker
+```
+
+## 🚀 Быстрый старт
+
+### Базовое использование
+
+```typescript
+// sw.js
+import {
+    initServiceWorker,
+    type ServiceWorkerPlugin,
+    type SwContext,
+} from '@budarin/pluggable-serviceworker';
+
+// Контекст: список ассетов для precache и имя кеша
+interface PrecacheAndServeContext extends SwContext {
+    assets: string[];
+    cacheName: string;
+}
+
+const precacheAndServePlugin: ServiceWorkerPlugin<PrecacheAndServeContext> = {
+    name: 'precache-and-serve',
+
+    install: async (_event, context) => {
+        const cache = await caches.open(context.cacheName);
+        await cache.addAll(context.assets);
+    },
+
+    fetch: async (event, context) => {
+        const cache = await caches.open(context.cacheName);
+        return cache.match(event.request) ?? undefined;
+    },
+};
+
+// TypeScript проверит, что в options есть assets и cacheName
+initServiceWorker([precacheAndServePlugin], {
+    logger: console,
+    assets: ['/', '/styles.css', '/script.js'],
+    cacheName: 'my-cache-v1',
+});
+```
+
+**Важно:** для `fetch` плагину не нужно самому вызывать `fetch(event.request)`, если все плагины вернули `undefined` - фреймворк сам выполняет запрос в сеть. Во все обработчики плагинов вторым аргументом передаётся **контекст** — те же данные, что вы передали в `initServiceWorker`.
+
+## Демо
+
+В папке [demo/](demo/) — приложение **React + Vite** с пресетом **offlineFirst** и типовым сервис-воркером **activateOnSignal**. Запуск из корня: `pnpm install && pnpm build`, затем `cd demo && pnpm install && pnpm run dev`. Подробности и ссылки на публичные песочницы (StackBlitz, CodeSandbox) — в [demo/README.md](demo/README.md).
+
+[Open in StackBlitz](https://stackblitz.com/github/budarin/pluggable-serviceworker/tree/master/demo) · [Open in CodeSandbox](https://codesandbox.io/s/github/budarin/pluggable-serviceworker/tree/master/demo)
+
+## `initServiceWorker(plugins, options)`
+
+`initServiceWorker` — точка входа: она регистрирует обработчики событий Service Worker (`install`, `activate`, `fetch`, …) и прогоняет их через список плагинов.
+
+- `plugins`: массив плагинов
+- `options`: один общий объект с настройками/данными, который будет доступен плагинам как **контекст**
+
+**Пример:**
+
+```typescript
+initServiceWorker([myPlugin], {
+    logger: console,
+    // ... тут будут поля контекста, которые требуют плагины ...
+});
+```
+
+## ⚙️ Конфигурация и контекст (options)
+
+Функция `initServiceWorker` принимает второй параметр `options` типа `ServiceWorkerInitOptions` (контекст для плагинов + `onError` для библиотеки). В обработчики плагинов вторым аргументом передаётся **контекст** — часть этого объекта без `onError` (тип контекста — `SwContext` и ваши поля; при типизированных плагинах — пересечение требуемых ими полей).
+
+```typescript
+interface SwContext {
+    logger?: Logger; // по умолчанию console
+    // сюда можно добавлять свои поля: version, assets, cacheName и т.д.
+}
+
+// В initServiceWorker передаётся ServiceWorkerInitOptions = SwContext + onError:
+interface ServiceWorkerInitOptions extends SwContext {
+    onError?: (error, event, errorType?) => void; // только для библиотеки, в плагины не передаётся
+}
+```
+
+В тип контекста, который видят плагины, входит только `SwContext` и ваши поля; `onError` в этот тип не входит и используется только библиотекой.
+
+Формируйте объект `options` в своём сервис-воркере (контекст для плагинов + при необходимости `onError`) и передавайте его в `initServiceWorker`. В плагины передаётся тот же объект как контекст — плагины получают доступ к полям контекста, а `onError` остаётся внутренним делом библиотеки.
+
+### Поля конфигурации
+
+#### `logger?: Logger` (опциональное)
+
+Объект для логирования с методами `info`, `warn`, `error`, `debug`. По умолчанию используется `console`. Может быть передан любой объект, реализующий интерфейс `Logger`.
+
+```typescript
+interface Logger {
+    trace: (...data: unknown[]) => void;
+    debug: (...data: unknown[]) => void;
+    info: (...data: unknown[]) => void;
+    warn: (...data: unknown[]) => void;
+    error: (...data: unknown[]) => void;
+}
+```
+
+**Пример:**
+
+```typescript
+const logger = console; // Использование стандартного console
+
+const options = {
+    logger,
+    // или
+    logger: {
+        trace: (...data) => customLog('TRACE', ...data),
+        debug: (...data) => customLog('DEBUG', ...data),
+        info: (...data) => customLog('INFO', ...data),
+        warn: (...data) => customLog('WARN', ...data),
+        error: (...data) => customLog('ERROR', ...data),
+    },
+};
+```
+
+#### `onError?: (error, event, errorType) => void` (опциональное)
+
+Единый обработчик для всех типов ошибок в Service Worker. **Дефолтного обработчика ошибок нет** - если `onError` не передан, ошибки будут проигнорированы (не обработаны).
+
+**Параметры:**
+
+- `error: Error | any` - объект ошибки
+- `event: Event` - событие, в контексте которого произошла ошибка
+- `errorType?: ServiceWorkerErrorType` - тип ошибки (см. раздел "Обработка ошибок")
+
+**Важно:** Если `onError` не указан, ошибки в плагинах и глобальные ошибки будут проигнорированы. Для production-окружения рекомендуется всегда указывать `onError` для логирования и мониторинга ошибок.
+
+**Пример минимальной конфигурации:**
+
+```typescript
+// Без onError - ошибки будут проигнорированы
+initServiceWorker([cachePlugin], {});
+
+// С onError - ошибки будут обработаны
+initServiceWorker([cachePlugin], {
+    logger: console,
+    onError: (error, event, errorType) => {
+        console.error('Service Worker error:', error, errorType);
+    },
+});
+```
+
+### Обработка ошибок
+
+Библиотека позволяет описать единый обработчик для всех типов ошибок в Service Worker и выполнить обработку индивидуально каждого типа ошибки. Она сама подписывается на глобальные события `error`, `messageerror`, `unhandledrejection`, `rejectionhandled`; ошибка в одном плагине не останавливает выполнение остальных. Если внутри `onError` произойдёт исключение, оно логируется через `options.logger`.
+
+```typescript
+import {
+    initServiceWorker,
+    ServiceWorkerErrorType,
+} from '@budarin/pluggable-serviceworker';
+
+const logger = console; // или свой объект с методами info, warn, error, debug
+
+const options = {
+    logger,
+    onError: (error, event, errorType) => {
+        logger.info(`Ошибка типа "${errorType}":`, error);
+
+        switch (errorType) {
+            case ServiceWorkerErrorType.ERROR:
+                // JavaScript ошибки
+                logger.error('JavaScript error:', error);
+                break;
+
+            case ServiceWorkerErrorType.MESSAGE_ERROR:
+                // Ошибки сообщений
+                logger.error('Message error:', error);
+                break;
+
+            case ServiceWorkerErrorType.UNHANDLED_REJECTION:
+                // Необработанные Promise rejection
+                logger.error('Unhandled promise rejection:', error);
+                break;
+
+            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);
+
+                // можно даже так - отправка ошибки в аналитику
+                fetch('/api/errors', {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        error: error.message,
+                        eventType: event.type,
+                        url: event.request?.url,
+                        timestamp: Date.now(),
+                    }),
+                }).catch(() => {
+                    // Игнорируем ошибки отправки логов
+                });
+        }
+    },
+};
+
+initServiceWorker(
+    [
+        /* ваши плагины */
+    ],
+    options
+);
+```
+
+## 🔌 Интерфейс плагина
+
+Каждый плагин реализует интерфейс `ServiceWorkerPlugin<C>`, где `C extends SwContext` — тип контекста, который плагин ожидает. Во все обработчики вторым аргументом передаётся контекст (те же данные, что в `options` при инициализации, без `onError`).
+
+```typescript
+interface ServiceWorkerPlugin<C extends SwContext = SwContext> {
+    name: string;
+    order?: number;
+
+    install?: (event: ExtendableEvent, context?: C) => Promise<void> | void;
+    activate?: (event: ExtendableEvent, context?: C) => Promise<void> | void;
+    fetch?: (
+        event: FetchEvent,
+        context?: C
+    ) => Promise<Response | undefined> | Response | undefined;
+    message?: (event: SwMessageEvent, context?: C) => void;
+    sync?: (event: SyncEvent, context?: C) => Promise<void> | void;
+    push?: (
+        event: PushEvent,
+        context?: C
+    ) =>
+        | Promise<PushNotificationPayload | void>
+        | PushNotificationPayload
+        | void;
+    periodicsync?: (
+        event: PeriodicSyncEvent,
+        context?: C
+    ) => Promise<void> | void;
+}
+```
+
+Плагин может объявить требуемый контекст через дженерик: `ServiceWorkerPlugin<SwContext & { assets: string[]; cacheName: string }>`. Тогда TypeScript потребует передать в `initServiceWorker` объект `options` с полями `assets` и `cacheName` (при вызове с литералом массива плагинов тип `options` выводится автоматически).
+
+### 📝 Описание методов
+
+| Метод          | Событие        | Возвращает                        | Описание                                                       |
+| -------------- | -------------- | --------------------------------- | -------------------------------------------------------------- |
+| `install`      | `install`      | `void`                            | Инициализация плагина при установке SW                         |
+| `activate`     | `activate`     | `void`                            | Активация плагина при обновлении SW                            |
+| `fetch`        | `fetch`        | `Response \| undefined`           | Обработка сетевых запросов                                     |
+| `message`      | `message`      | `void`                            | Обработка сообщений от основного потока                        |
+| `sync`         | `sync`         | `void`                            | Синхронизация данных в фоне                                    |
+| `push`         | `push`         | `PushNotificationPayload \| void` | Данные для уведомления; библиотека вызывает `showNotification` |
+| `periodicsync` | `periodicsync` | `void`                            | Периодические фоновые задачи                                   |
+
+### 🎯 Особенности обработчиков
+
+- Во все методы вторым аргументом передаётся **контекст** (данные из объекта, переданного в `initServiceWorker`, без `onError`). Параметр можно не использовать, если плагину контекст не нужен.
+- **`fetch`**: Возвращает `Response` для завершения цепочки или `undefined` для передачи следующему плагину. Если все плагины вернули `undefined`, фреймворк вызывает `fetch(event.request)`.
+- **`push`**: Как и fetch — возвращает `PushNotificationPayload` (объект для [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification)) или `undefined`. Тип экспортируется из пакета. Первый плагин, вернувший объект с `title`, «выигрывает»: библиотека вызывает `self.registration.showNotification(title, options)`. Если все вернули `undefined`, уведомление не показывается.
+- **Остальные обработчики** (`install`, `activate`, `message`, `sync`, `periodicsync`): возвращаемое значение не используется; фреймворк вызывает метод каждого плагина по очереди, цепочка не прерывается.
+- **Все обработчики опциональны** — реализуйте только нужные события.
+
+### 🔄 Обновление Service Worker (skipWaiting / clients.claim)
+
+Библиотека **не вызывает** `skipWaiting()` и `clients.claim()` — это поведение задаётся индивидуально в каждом проекте и оставлено на усмотрение плагинов. При необходимости вызывайте их в своих обработчиках `install` и `activate` (в библиотеке реализованы данные примитивы - смотри ниже):
+
+```typescript
+const updatePlugin = {
+    name: 'update-plugin',
+    install: (event) => {
+        self.skipWaiting();
+    },
+    activate: (event) => {
+        event.waitUntil(self.clients.claim());
+    },
+};
+```
+
+## 🎯 Порядок выполнения
+
+Плагины выполняются в следующем порядке:
+
+1. **Сначала ВСЕ плагины без `order`** - в том порядке, в котором они были добавлены
+2. **Затем плагины с `order`** - в порядке возрастания значений `order`
+
+### Пример:
+
+```typescript
+const plugins = [
+    { name: 'first' }, // без order - выполняется первым
+    { name: 'fourth', order: 2 },
+    { name: 'second' }, // без order - выполняется вторым
+    { name: 'third', order: 1 },
+    { name: 'fifth' }, // без order - выполняется третьим
+];
+
+// Порядок выполнения: first → second → fifth → third → fourth
+```
+
+**Преимущества новой системы:**
+
+- 🎯 **Предсказуемость** - плагины без `order` всегда выполняются первыми
+- 🔧 **Простота** - не нужно знать, какие номера уже заняты
+- 📈 **Масштабируемость** - легко добавлять новые плагины в нужном порядке
+
+## ⚡ Логика выполнения обработчиков
+
+Разные типы событий Service Worker обрабатываются по-разному в зависимости от их специфики:
+
+### 🔄 Параллельное выполнение
+
+**События:** `install`, `activate`, `message`, `sync`, `periodicsync`
+
+Все обработчики выполняются **одновременно** с помощью `Promise.all()`:
+
+```typescript
+// Все плагины инициализируются параллельно
+const installPlugin1 = {
+    name: 'cache-assets',
+    install: async () => {
+        /* кеширование ресурсов приложения*/
+    },
+};
+const installPlugin2 = {
+    name: 'cache-ext',
+    install: async () => {
+        /* кэширование вспомогательных ресурсов */
+    },
+};
+
+// Оба install обработчика выполнятся одновременно
+```
+
+**Почему параллельно:**
+
+- **install/activate**: Все плагины должны инициализироваться независимо
+- **message**: Все плагины должны получить сообщение одновременно
+- **sync**: Разные задачи синхронизации независимы (синхронизация данных + кеша)
+- **periodicsync**: Периодические задачи независимы друг от друга
+
+### ➡️ Последовательное выполнение
+
+**События:** `fetch`, `push`
+
+Обработчики выполняются **по очереди** до первого успешного результата:
+
+#### Fetch - с прерыванием цепочки
+
+```typescript
+const authPlugin = {
+    name: 'auth',
+    // Без order - выполняется первым
+    fetch: async (event) => {
+        if (needsAuth(event.request)) {
+            return new Response('Unauthorized', { status: 401 }); // Прерывает цепочку
+        }
+        return undefined; // Передает следующему плагину
+    },
+};
+```
+
+**Почему последовательно:**
+
+- **fetch**: Нужен только один ответ, первый успешный прерывает цепочку. Если никто не вернул ответ — выполняется `fetch(event.request)`
+- **push**: Плагин может вернуть данные для уведомления типа `PushNotificationPayload` | `undefined`. Библиотека один раз вызывает `showNotification` по первому вернувшемуся payload; цепочка прерывается — одно уведомление, без конфликтов.
+
+### 📋 Сводная таблица
+
+| Событие        | Выполнение      | Прерывание | Причина                                                |
+| -------------- | --------------- | ---------- | ------------------------------------------------------ |
+| `install`      | Параллельно     | Нет        | Независимая инициализация                              |
+| `activate`     | Параллельно     | Нет        | Независимая активация                                  |
+| `fetch`        | Последовательно | Да         | Нужен один ответ                                       |
+| `message`      | Параллельно     | Нет        | Все получают сообщение                                 |
+| `sync`         | Параллельно     | Нет        | Независимые задачи                                     |
+| `periodicsync` | Параллельно     | Нет        | Независимые периодические задачи                       |
+| `push`         | Последовательно | Да         | Один показ уведомления (библиотека по первому payload) |
+
+## Примитивы, пресеты и типовые сервис-воркеры
+
+### Примитивы (плагины)
+
+Один примитив — одна операция. Импорт: `@budarin/pluggable-serviceworker/plugins`.
+
+| Название                 | Событие  | Описание                                                                                                                                                                            |
+| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **precache**             | install  | Кеширует список `context.assets` в кеш `context.cacheName`.                                                                                                                         |
+| **skipWaiting**          | install  | Вызывает `skipWaiting()`.                                                                                                                                                           |
+| **claim**                | activate | Вызывает `clients.claim()`.                                                                                                                                                         |
+| **claimOnMessage**       | message  | При сообщении с `event.data.type === context.claimMessageType` (по умолчанию `'SW_ACTIVATE'`) вызывает `skipWaiting()`. `clients.claim()` вызывается плагином **claim** в activate. |
+| **serveFromCache**       | fetch    | Отдаёт из кеша; при промахе — undefined.                                                                                                                                            |
+| **restoreAssetToCache**  | fetch    | Для URL из `context.assets`: сначала из кеша; если в кеше нет — запрос с сервера, в кеш, ответ браузеру.                                                                            |
+| **cacheFirst**           | fetch    | Кеш → при промахе сеть, ответ в кеш.                                                                                                                                                |
+| **networkFirst**         | fetch    | Сеть → при ошибке/офлайне из кеша.                                                                                                                                                  |
+| **staleWhileRevalidate** | fetch    | Отдаёт из кеша, в фоне обновляет кеш из сети.                                                                                                                                       |
+
+Контекст для кеширующих примитивов: `OfflineFirstContext` (assets, cacheName, опционально claimMessageType). Импортируйте тип из основного пакета.
+
+### Пресеты
+
+Комбинации примитивов (стратегии кеширования). Импорт: `@budarin/pluggable-serviceworker/presets`.
+
+| Название         | Состав                    | Назначение                           |
+| ---------------- | ------------------------- | ------------------------------------ |
+| **offlineFirst** | precache + serveFromCache | Статика из кеша, при промахе — сеть. |
+
+Стратегии **networkFirst**, **staleWhileRevalidate** и др. доступны как примитивы — собирайте свой кастомный сервис-воркер из примитивов и пресетов.
+
+### Типовые сервис-воркеры (из коробки)
+
+Готовые точки входа по **моменту активации** (все с кешированием offline-first). Импорт: `@budarin/pluggable-serviceworker/sw`.
+
+| Название                             | Описание                                                                                            |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| **activateOnNextVisitServiceWorker** | Кеширующий SW, активируется при следующем визите страницы.                                          |
+| **activateImmediatelyServiceWorker** | Кеширующий SW, активируется сразу (skipWaiting + claim).                                            |
+| **activateOnSignalServiceWorker**    | Кеширующий SW, активируется по сигналу со страницы (сообщение с типом из options.claimMessageType). |
+
+Пример использования типового SW:
+
+```typescript
+// sw.js — точка входа вашего сервис-воркера
+import { activateOnNextVisitServiceWorker } from '@budarin/pluggable-serviceworker/sw';
+
+activateOnNextVisitServiceWorker({
+    assets: ['/', '/styles.css', '/script.js'],
+    cacheName: 'my-cache-v1',
+    logger: console,
+    onError: (err, event, type) => console.error(type, err),
+});
+```
+
+На странице регистрируйте этот файл: `navigator.serviceWorker.register('/sw.js')` (или путь, по которому сборка отдаёт ваш sw.js).
+
+## Режим разработки
+
+Если нужно, чтобы в режиме разработки ни один из плагинов ничего не кэшировал и не пытался что-либо отдавать из кэша - в плагине и сервисворкере можно использовть `import.meta.env.DEV` для Vite для условного использования кэширования.
+
+## 📄 Лицензия
+
+MIT © Vadim Budarin