@budarin/pluggable-serviceworker 1.5.0 → 1.5.2

package/README.md

@@ -6,39 +6,59 @@
 
 ## 🚀 Почему этот пакет облегчает разработку?
 
-Разработка Service Worker'ов традиционно сложна из-за необходимости вручную управлять множественными обработчиками событий, обработкой ошибок и порядком выполнения. Этот пакет решает эти проблемы:
+Разработка Service Worker'ов традиционно сложна из-за необходимости вручную управлять множественными обработчиками событий, обработкой ошибок и порядком выполнения или изучать сложные и большие библиотеки. Этот пакет решает эти проблемы:
 
 ### 🔌 **Модульная архитектура**
 
 - **Плагинная система** позволяет разбивать функциональность на независимые модули
 - Каждый плагин отвечает за свою задачу (кеширование, аутентификация, уведомления)
 - Легко добавлять/удалять функциональность без изменения основного кода
-- Не нужно думать об инфраструктурном коде в обработчиках событий - пишите простой код не думая о сложностях кода самого сервисворкера
+- Не нужно думать об инфраструктурном коде в обработчиках событий — пишите простой код, не думая о сложностях самого сервис-воркера
 
-### 🎯 **Управление порядком выполнения**
+### 🎯 **Предсказуемый порядок выполнения**
 
-- **Предсказуемый порядок** - плагины без `order` выполняются первыми, затем по возрастанию `order`
-- **Гибкость** - можно контролировать последовательность инициализации
-- **Масштабируемость** - легко добавлять новые плагины в нужном месте
+- **Предсказуемый порядок** — плагины без `order` выполняются первыми, затем по возрастанию/убыванию `order`
+- **Гибкость** — можно контролировать последовательность инициализации
+- **Параллельно** для `install`, `activate`, `message`, `sync` — независимые задачи выполняются одновременно
+- **Последовательно** для `fetch` — первый вернувший ответ завершает цепочку; для `push` вызываются все плагины
+- Легко добавлять новые плагины в нужное место
 
-### ⚡ **Оптимизированная логика выполнения**
+### 📖 **Легко изучить и понять**
 
-- **Параллельно** для `install`, `activate`, `message`, `sync` - независимые задачи выполняются одновременно
-- **Последовательно** для `fetch` — первый успешный результат прерывает цепочку; для `push` — вызываются все плагины, показывается уведомление по каждому payload (или одно от библиотеки только когда **все** плагины вернули `undefined`)
-- **Производительность** - правильный выбор стратегии для каждого типа события
+- Один контракт — плагин с опциональными хуками, без отдельной модели роутинга и стратегий
+- Мало сущностей: плагин, фабрика плагина, `initServiceWorker`, опции
+- Низкая когнитивная нагрузка: цепочка плагинов и возвращаемые значения задают всё поведение
+- Быстро войти в проект по примерам и типу `ServiceWorkerPlugin`
+
+### 📦 **Маленький размер**
+
+- Минимум зависимостей, только рантайм плагинов
+- Нет встроенной сборки и тяжёлых модулей — в бандл попадает только то, что вы подключаете
+- Подходит для проектов, где важен размер бандла и простота зависимостей
+
+### 🎛 **Полный контроль над кодом**
+
+- Список кешируемых ассетов и стратегии задаёте вы — в коде или конфиге
+- Порядок плагинов, обработка ошибок и логгер полностью в ваших руках
+- Любая кастомная логика в `fetch`, `push`, `sync` — через свои плагины, без обхода чужих абстракций
 
 ### 🛡️ **Централизованная обработка ошибок**
 
-- **Единый обработчик** для всех типов ошибок
-- **Типизированные ошибки** - знаешь, что именно сломалось
-- **Изоляция** - ошибка в одном плагине не ломает остальные
+- **Единый обработчик** `onError` для всех типов ошибок в сервис-воркере с определение места возникновения ошибки в коде
+- **Типизированные ошибки** — знаешь, что именно сломалось
+- **Изоляция** — ошибка в одном плагине не ломает остальные
 - **Автоматическая обработка** глобальных событий ошибок
 
 ### 📝 **Удобное логирование**
 
-- **Настраиваемый логгер** с разными уровнями
-- **Контекстная информация** в логах
-- **Отладка** становится намного проще
+- **Настраиваемый логгер** с разными уровнями (`trace`, `debug`, `info`, `warn`, `error`)
+- Во все обработчики плагинов передаётся один и тот же `logger` — контекстная отладка
+- При желании можно подставить любой объект с этим интерфейсом
+
+### ✅ **Готовые решения из коробки**
+
+- Пресет **offlineFirst** — precache при установке и отдача из кеша при запросах
+- Готовые сервисворкеры: **activateOnSignal**, **activateImmediately**, **activateOnNextVisit** — рабочий типовой сервис-воркер в несколько строк без написания плагинов
 
 ## 📦 Установка
 
@@ -440,6 +460,7 @@ function authPlugin(config: {
             if (protectedPaths.some((p) => path.startsWith(p))) {
                 if (needsAuth(event.request)) {
                     logger.warn('auth: unauthorized', event.request.url);
+
                     return new Response('Unauthorized', { status: 401 }); // Прерывает цепочку
                 }
             }
@@ -454,7 +475,7 @@ function authPlugin(config: {
 **Почему последовательно:**
 
 - **fetch**: Нужен только один ответ на текущий запрос браузера, первый успешный прерывает цепочку. Если никто не вернул ответ — выполняется `fetch(event.request)`
-- **push**: Плагин может вернуть `PushNotificationPayload`, `false` (не показывать) или `undefined` (решение отдаётся библиотеке). Библиотека вызывает `showNotification` для каждого payload. Не показываем, если все вернули `false` или смесь без payload. Библиотека показывает одно только когда **все** вернули `undefined`.
+- **push**: Плагин может вернуть `PushNotificationPayload`, `false` (не показывать) или `undefined` (решение отдаётся библиотеке). Библиотека вызывает `showNotification` для каждого payload. Не показываем, если все вернули `false` или смесь без payload. Библиотека показывает нотификацию и в случае когда **все** плагины вернули `undefined`.
 
 ### 📋 Сводная таблица
 
@@ -479,19 +500,19 @@ function authPlugin(config: {
 | Название                        | Событие    | Описание                                                                                                                     |
 | ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `precache*(config)`             | `install`  | Кеширует список ресурсов из `config.assets` в кеш `config.cacheName`.                                                        |
-| `precacheAndNotify(config)`     | install    | Как **precache**, затем отправляет активным клиентам сообщение `{ type: config.messageType }` (по умолчанию `SW_INSTALLED`). |
+| `precacheAndNotify(config)`     | `install`  | Как **precache**, затем отправляет активным клиентам сообщение `{ type: config.messageType }` (по умолчанию `SW_INSTALLED`). |
 | `precacheMissing(config)`       | `install`  | Добавляет в кеш только те ресурсы из `config.assets`, которых ещё нет в кеше.                                                |
 | `pruneStaleCache(config)`       | `activate` | Удаляет из кеша записи, чей URL не входит в `config.assets`.                                                                 |
-| `skipWaiting                    | `install`  | Вызывает `skipWaiting()`.                                                                                                    |
+| `skipWaiting`                   | `install`  | Вызывает `skipWaiting()`.                                                                                                    |
 | `claim`                         | `activate` | Вызывает `clients.claim()`.                                                                                                  |
 | `reloadClients`                 | `activate` | Перезагружает все окна-клиенты через `client.navigate(client.url)`.                                                          |
 | `claimAndReloadClients`         | `activate` | Композиция **claim** + **reloadClients**: сначала claim, затем перезагрузка (порядок гарантирован — один плагин).            |
 | `skipWaitingOnMessage(config?)` | `message`  | При сообщении с `event.data.type === 'SW_MSG_SKIP_WAITING'` вызывает `skipWaiting()`.                                        |
 | `serveFromCache(config)`        | `fetch`    | Отдаёт ресурс из кеша `config.cacheName`; при отсутствии его в кэше — undefined.                                             |
 | `restoreAssetToCache(config)`   | `fetch`    | Для URL из `config.assets`: отдам ресурс из кеша или запрашиваем по сети, затем в кладем кго в кеш. Иначе — undefined.       |
-| cacheFirst(config)`             | `fetch`    | Отдаем ресурс из кэша `config.cacheName`: при отсутствии его в кэше — делаем запрос на сервер и затем кладем ответ в кэш.    |
+| `cacheFirst(config)`            | `fetch`    | Отдаем ресурс из кэша `config.cacheName`: при отсутствии его в кэше — делаем запрос на сервер и затем кладем ответ в кэш.    |
 | `networkFirst(config)`          | `fetch`    | Делаем запрос на сервер, при успехе — кладем его в кэш. При ошибке — отдаем из кэша. Иначе - `undefined`.                    |
-| `staleWhileRevalidate(config)`  | fetch      | Отдаёт из кэша, в фоне обновляет кэш.                                                                                        |
+| `staleWhileRevalidate(config)`  | `fetch`    | Отдаёт из кэша, в фоне обновляет кэш.                                                                                        |
 
 #### Композиция примитивов
 
@@ -499,32 +520,29 @@ function authPlugin(config: {
 
 **Пример: claimAndReloadClients как композиция двух примитивов**
 
-Плагин **claimAndReloadClients** из коробки выполняет в `activate` последовательно: `clients.claim()`, затем перезагрузка всех окон.
+Плагин **claimAndReloadClients** вызывает существующие примитивы **claim** и **reloadClients** по очереди:
 
 ```typescript
-// Реализация плагина claimAndReloadClients (из @budarin/pluggable-serviceworker/plugins)
-activate: () =>
-    self.clients.claim().then(() =>
-        self.clients
-            .matchAll({ type: 'window' })
-            .then((list) =>
-                Promise.all(list.map((client) => client.navigate(client.url)))
-            )
-    ),
-```
+import { claim } from '@budarin/pluggable-serviceworker/plugins';
+import { reloadClients } from '@budarin/pluggable-serviceworker/plugins';
 
-Два плагина **claim** и **reloadClients** в стеке выполняют `activate` **параллельно** (см. «Логика выполнения обработчиков»), порядок завершения операций не гарантирован. Для строгой последовательности «сначала claim, потом reload» используйте один плагин **claimAndReloadClients**.
+const claimPlugin = claim();
+const reloadPlugin = reloadClients();
 
-```typescript
-initServiceWorker([claim, reloadClients], options); // оба activate — параллельно
+activate: (event, logger) =>
+    Promise.resolve(claimPlugin.activate(event, logger)).then(() =>
+        reloadPlugin.activate(event, logger)
+    ),
 ```
 
 **Пример: кастомный кэш и логика по URL**
 
-Фабрика `postsSwrPlugin(config)` возвращает плагин, который применяет stale-while-revalidate только к запросам, подходящим под `pathPattern`. Логика SWR инлайнована в обработчик `fetch`.
+Фабрика `postsSwrPlugin(config)` возвращает плагин, который применяет `stale-while-revalidate`(SWR) только к запросам, подходящим под `pathPattern`.
 
 ```typescript
+// postsSwrPlugin.ts
 import type { Plugin } from '@budarin/pluggable-serviceworker';
+
 import {
     precache,
     serveFromCache,
@@ -536,28 +554,39 @@ function postsSwrPlugin(config: {
     pathPattern?: RegExp;
 }): Plugin {
     const { cacheName, pathPattern = /\/api\/posts(\/|$)/ } = config;
+
     return {
         name: 'postsSwr',
         order: 0,
+
         fetch: async (event) => {
-            if (!pathPattern.test(new URL(event.request.url).pathname))
+            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)
+                if (response.ok) {
                     await cache.put(event.request, response.clone());
+                }
+
                 return response;
             });
+
             if (cached) {
                 void revalidate;
                 return cached;
             }
+
             return revalidate;
         },
     };
 }
+```
 
+```typescript
+// sw.ts
 const staticCache = 'static-v1';
 const assets = ['/', '/main.js'];
 
@@ -580,7 +609,6 @@ initServiceWorker(
 | `offlineFirst(config)` | `precache(config) + serveFromCache(config)` | Статика из кеша, при отсутствии ресурса в кэше — делаем запрос к серверу. |
 
 Конфиг пресета: `OfflineFirstConfig` (cacheName, assets). Импорт из `@budarin/pluggable-serviceworker/presets`.
-
 Стратегии **networkFirst**, **staleWhileRevalidate** и др. доступны как примитивы — собирайте свой кастомный сервис-воркер из примитивов и пресетов.
 
 ### Типовые сервис-воркеры (из коробки)

package/dist/plugins/claimAndReloadClients.js

@@ -1,10 +1,10 @@
+import { claim } from './claim.js';
+import { reloadClients } from './reloadClients.js';
 export function claimAndReloadClients() {
+    const claimPlugin = claim();
+    const reloadPlugin = reloadClients();
     return {
         name: 'claimAndReloadClients',
-        activate: () => self.clients
-            .claim()
-            .then(() => self.clients
-            .matchAll({ type: 'window' })
-            .then((list) => Promise.all(list.map((client) => client.navigate(client.url))))),
+        activate: (event, logger) => Promise.resolve(claimPlugin.activate(event, logger)).then(() => reloadPlugin.activate(event, logger)),
     };
 }

package/dist/plugins/skipWaitingOnMessage.js

@@ -4,8 +4,9 @@ export function skipWaitingOnMessage(config = {}) {
     return {
         name: 'skipWaitingOnMessage',
         message: (event) => {
-            if (event.data?.type !== messageType)
+            if (event.data?.type !== messageType) {
                 return;
+            }
             self.skipWaiting();
         },
     };

package/dist/sw/activateImmediately.d.ts

@@ -1,5 +1,5 @@
 import type { ServiceWorkerInitOptions } from '../index.js';
-import { type OfflineFirstConfig } from '../presets/offlineFirst.js';
+import type { OfflineFirstConfig } from '../presets/offlineFirst.js';
 export interface ActivateImmediatelyOptions extends ServiceWorkerInitOptions, OfflineFirstConfig {
 }
 export declare function activateImmediatelyServiceWorker(options: ActivateImmediatelyOptions): void;

package/dist/sw/activateImmediately.js

@@ -1,7 +1,7 @@
+import { claim } from '../plugins/claim.js';
 import { initServiceWorker } from '../index.js';
-import { offlineFirst, } from '../presets/offlineFirst.js';
 import { skipWaiting } from '../plugins/skipWaiting.js';
-import { claim } from '../plugins/claim.js';
+import { offlineFirst } from '../presets/offlineFirst.js';
 export function activateImmediatelyServiceWorker(options) {
     initServiceWorker([...offlineFirst(options), skipWaiting, claim], options);
 }

package/dist/sw/activateOnNextVisit.d.ts

@@ -1,5 +1,5 @@
 import type { ServiceWorkerInitOptions } from '../index.js';
-import { type OfflineFirstConfig } from '../presets/offlineFirst.js';
+import type { OfflineFirstConfig } from '../presets/offlineFirst.js';
 export interface ActivateOnNextVisitOptions extends ServiceWorkerInitOptions, OfflineFirstConfig {
 }
 export declare function activateOnNextVisitServiceWorker(options: ActivateOnNextVisitOptions): void;

package/dist/sw/activateOnNextVisit.js

@@ -1,5 +1,5 @@
 import { initServiceWorker } from '../index.js';
-import { offlineFirst, } from '../presets/offlineFirst.js';
+import { offlineFirst } from '../presets/offlineFirst.js';
 export function activateOnNextVisitServiceWorker(options) {
     initServiceWorker(offlineFirst(options), options);
 }

package/dist/utils/openCacheAndMatch.d.ts

@@ -0,0 +1,4 @@
+export declare function openCacheAndMatch(cacheName: string, request: Request): Promise<{
+    cache: Cache;
+    cached: Response | undefined;
+}>;

package/dist/utils/openCacheAndMatch.js

@@ -0,0 +1,5 @@
+export async function openCacheAndMatch(cacheName, request) {
+    const cache = await caches.open(cacheName);
+    const cached = await cache.match(request);
+    return { cache, cached: cached ?? undefined };
+}

package/package.json

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