@budarin/pluggable-serviceworker 1.5.6 → 1.5.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -28
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.js +1 -1
- package/dist/client/register.d.ts +1 -1
- package/dist/client/register.js +1 -1
- package/dist/index.js +2 -2
- package/dist/plugins/precacheAndNotify.d.ts +2 -1
- package/dist/plugins/precacheAndNotify.js +4 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -313,7 +313,7 @@ initServiceWorker(
|
|
|
313
313
|
|
|
314
314
|
**Плагин** — это объект с полем `name` и опциональными обработчиками (`install`, `fetch`, `activate` и т.д.). В массив `initServiceWorker(plugins, options)` передаются именно такие объекты.
|
|
315
315
|
|
|
316
|
-
**Фабрика плагина** — функция, которая принимает конфиг и возвращает плагин (объект). Например: `precache(config)`, `serveFromCache(config)` или собственная `precacheAndServePlugin(config)` из примера выше. Конфиг задаётся по месту вызова
|
|
316
|
+
**Фабрика плагина** — функция, которая принимает конфиг и возвращает плагин (объект). Например: `precache(config)`, `serveFromCache(config)` или собственная `precacheAndServePlugin(config)` из примера выше. Конфиг задаётся по месту вызова фабрики.
|
|
317
317
|
|
|
318
318
|
### 🔌 Интерфейс плагина
|
|
319
319
|
|
|
@@ -368,8 +368,8 @@ interface ServiceWorkerPlugin<_C extends PluginContext = PluginContext> {
|
|
|
368
368
|
### 🎯 Особенности обработчиков
|
|
369
369
|
|
|
370
370
|
- Во все методы вторым аргументом передаётся **logger** (всегда определён: из `options` или `console`).
|
|
371
|
-
- **`fetch`**:
|
|
372
|
-
- **`push`**:
|
|
371
|
+
- **`fetch`**: может вернуть `Response` для завершения цепочки или `undefined` для передачи следующему плагину. Если все плагины вернули `undefined`, фреймворк вызывает `fetch(event.request)`.
|
|
372
|
+
- **`push`**: может вернуть `PushNotificationPayload` (объект для [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification)), `false` (не отображать уведомление) или `undefined` (решение об отображении отдаётся библиотеке). Вызываются все плагины с `push`. Для каждого результата типа `PushNotificationPayload` вызывается `showNotification`. Уведомление не показывается, если все вернули `false` или смесь `undefined` и `false` без payload. Библиотека отображает одно уведомление **только когда все** плагины вернули `undefined` (и в данных есть что показывать).
|
|
373
373
|
- **Остальные обработчики** (`install`, `activate`, `message`, `sync`, `periodicsync`): возвращаемое значение не используется; фреймворк вызывает метод каждого плагина по очереди, цепочка не прерывается.
|
|
374
374
|
- **Все обработчики опциональны** — реализуйте только нужные события.
|
|
375
375
|
|
|
@@ -378,7 +378,7 @@ interface ServiceWorkerPlugin<_C extends PluginContext = PluginContext> {
|
|
|
378
378
|
Плагины выполняются в следующем порядке:
|
|
379
379
|
|
|
380
380
|
1. **Сначала ВСЕ плагины без `order`** - в том порядке, в котором они были добавлены
|
|
381
|
-
2. **Затем плагины с `order`** - в порядке
|
|
381
|
+
2. **Затем плагины с `order`** - в порядке возрастания/убывания значений `order`
|
|
382
382
|
|
|
383
383
|
### Пример:
|
|
384
384
|
|
|
@@ -501,22 +501,22 @@ function authPlugin(config: { protectedPaths: string[] }): Plugin {
|
|
|
501
501
|
Один примитив — одна операция. Импорт: `@budarin/pluggable-serviceworker/plugins`.
|
|
502
502
|
Примитивы с конфигом — **фабрики плагинов** (см. раздел «Фабрика плагинов»): конфиг передаётся при вызове по месту использования; в `options` в `initServiceWorker` попадают только `logger?` и `onError?`. Примитивы без конфига (`skipWaiting`, `claim`, …) — готовые объекты плагинов.
|
|
503
503
|
|
|
504
|
-
| Название | Событие | Описание
|
|
505
|
-
| ------------------------------- | ---------- |
|
|
506
|
-
| `precache*(config)` | `install` | Кеширует список ресурсов из `config.assets` в кеш `config.cacheName`.
|
|
507
|
-
| `precacheAndNotify(config)` | `install` |
|
|
508
|
-
| `precacheMissing(config)` | `install` | Добавляет в кеш только те ресурсы из `config.assets`, которых ещё нет в кеше.
|
|
509
|
-
| `pruneStaleCache(config)` | `activate` | Удаляет из кеша записи, чей URL не входит в `config.assets`.
|
|
510
|
-
| `skipWaiting` | `install` | Вызывает `skipWaiting()`.
|
|
511
|
-
| `claim` | `activate` | Вызывает `clients.claim()`.
|
|
512
|
-
| `reloadClients` | `activate` | Перезагружает все окна-клиенты через `client.navigate(client.url)`.
|
|
513
|
-
| `claimAndReloadClients` | `activate` | Композиция **claim** + **reloadClients**: сначала claim, затем перезагрузка (порядок гарантирован — один плагин).
|
|
514
|
-
| `skipWaitingOnMessage(config?)` | `message` | При сообщении с `event.data.type === 'SW_MSG_SKIP_WAITING'` вызывает `skipWaiting()`.
|
|
515
|
-
| `serveFromCache(config)` | `fetch` | Отдаёт ресурс из кеша `config.cacheName`; при отсутствии его в кэше — undefined.
|
|
516
|
-
| `restoreAssetToCache(config)` | `fetch` | Для URL из `config.assets`: отдам ресурс из кеша или запрашиваем по сети, затем в кладем кго в кеш. Иначе — undefined.
|
|
517
|
-
| `cacheFirst(config)` | `fetch` | Отдаем ресурс из кэша `config.cacheName`: при отсутствии его в кэше — делаем запрос на сервер и затем кладем ответ в кэш.
|
|
518
|
-
| `networkFirst(config)` | `fetch` | Делаем запрос на сервер, при успехе — кладем его в кэш. При ошибке — отдаем из кэша. Иначе - `undefined`.
|
|
519
|
-
| `staleWhileRevalidate(config)` | `fetch` | Отдаёт из кэша, в фоне обновляет кэш.
|
|
504
|
+
| Название | Событие | Описание |
|
|
505
|
+
| ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
506
|
+
| `precache*(config)` | `install` | Кеширует список ресурсов из `config.assets` в кеш `config.cacheName`. |
|
|
507
|
+
| `precacheAndNotify(config)` | `install` | Выполняет ту же работу что и **precache** плагин, затем отправляет активным клиентам сообщение `startInstallingMessage (по-умолчанию SW_MSG_START_INSTALLING)` до начала кэширования ресурсов и `installedMessage (по-умолчанию SW_MSG_INSTALLED)` после окончания операции. |
|
|
508
|
+
| `precacheMissing(config)` | `install` | Добавляет в кеш только те ресурсы из `config.assets`, которых ещё нет в кеше. |
|
|
509
|
+
| `pruneStaleCache(config)` | `activate` | Удаляет из кеша записи, чей URL не входит в `config.assets`. |
|
|
510
|
+
| `skipWaiting` | `install` | Вызывает `skipWaiting()`. |
|
|
511
|
+
| `claim` | `activate` | Вызывает `clients.claim()`. |
|
|
512
|
+
| `reloadClients` | `activate` | Перезагружает все окна-клиенты через `client.navigate(client.url)`. |
|
|
513
|
+
| `claimAndReloadClients` | `activate` | Композиция **claim** + **reloadClients**: сначала claim, затем перезагрузка (порядок гарантирован — один плагин). |
|
|
514
|
+
| `skipWaitingOnMessage(config?)` | `message` | При сообщении с `event.data.type === 'SW_MSG_SKIP_WAITING'` вызывает `skipWaiting()`. |
|
|
515
|
+
| `serveFromCache(config)` | `fetch` | Отдаёт ресурс из кеша `config.cacheName`; при отсутствии его в кэше — undefined. |
|
|
516
|
+
| `restoreAssetToCache(config)` | `fetch` | Для URL из `config.assets`: отдам ресурс из кеша или запрашиваем по сети, затем в кладем кго в кеш. Иначе — undefined. |
|
|
517
|
+
| `cacheFirst(config)` | `fetch` | Отдаем ресурс из кэша `config.cacheName`: при отсутствии его в кэше — делаем запрос на сервер и затем кладем ответ в кэш. |
|
|
518
|
+
| `networkFirst(config)` | `fetch` | Делаем запрос на сервер, при успехе — кладем его в кэш. При ошибке — отдаем из кэша. Иначе - `undefined`. |
|
|
519
|
+
| `staleWhileRevalidate(config)` | `fetch` | Отдаёт из кэша, в фоне обновляет кэш. |
|
|
520
520
|
|
|
521
521
|
#### Композиция примитивов
|
|
522
522
|
|
|
@@ -619,18 +619,18 @@ activateOnNextVisitServiceWorker({
|
|
|
619
619
|
|
|
620
620
|
### Публикуемые утилиты
|
|
621
621
|
|
|
622
|
-
| Название
|
|
623
|
-
|
|
|
624
|
-
| `
|
|
625
|
-
| `normalizeUrl(url)`
|
|
626
|
-
| `notifyClients(messageType)`
|
|
622
|
+
| Название | Где использовать | Описание |
|
|
623
|
+
| --------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
624
|
+
| `registerServiceWorkerWithClaimWorkaround(scriptURL, options?)` | клиент | Регистрация SW для случая, когда в activate вызывается claim(); при первом заходе при необходимости один автоматический reload (обход [бага браузера](https://issues.chromium.org/issues/482903583)). Импорт: `@budarin/pluggable-serviceworker/client`. |
|
|
625
|
+
| `normalizeUrl(url)` | SW | Нормализует URL (относительный → абсолютный по origin SW) для сравнения. Импорт: `@budarin/pluggable-serviceworker/utils`. |
|
|
626
|
+
| `notifyClients(messageType)` | SW | Отправляет сообщение `{ type: messageType }` всем окнам-клиентам. Импорт: `@budarin/pluggable-serviceworker/utils`. |
|
|
627
627
|
|
|
628
|
-
На странице используйте **клиентский API** библиотеки, чтобы SW корректно взял контроль уже на первой загрузке (обход [бага браузера](https://issues.chromium.org/issues/482903583)):
|
|
628
|
+
На странице используйте **клиентский API** библиотеки, чтобы SW корректно взял контроль уже на первой загрузке если сервисворкер использует `claim()` для того, чтобы сразу же установить контроль над страницей (обход [бага браузера](https://issues.chromium.org/issues/482903583)):
|
|
629
629
|
|
|
630
630
|
```typescript
|
|
631
|
-
import {
|
|
631
|
+
import { registerServiceWorkerWithClaimWorkaround } from '@budarin/pluggable-serviceworker/client';
|
|
632
632
|
|
|
633
|
-
const reg = await
|
|
633
|
+
const reg = await registerServiceWorkerWithClaimWorkaround('/sw.js');
|
|
634
634
|
```
|
|
635
635
|
|
|
636
636
|
Без этого API на первом визите страница может остаться без контроллера до перезагрузки.
|
package/dist/client/index.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export {
|
|
1
|
+
export { registerServiceWorkerWithClaimWorkaround } from './register.js';
|
package/dist/client/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export {
|
|
1
|
+
export { registerServiceWorkerWithClaimWorkaround } from './register.js';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare function
|
|
1
|
+
export declare function registerServiceWorkerWithClaimWorkaround(scriptURL: string, options?: RegistrationOptions): Promise<ServiceWorkerRegistration | undefined>;
|
package/dist/client/register.js
CHANGED
package/dist/index.js
CHANGED
|
@@ -92,7 +92,7 @@ export function createEventHandlers(plugins, options) {
|
|
|
92
92
|
handler(event, logger);
|
|
93
93
|
}
|
|
94
94
|
catch (error) {
|
|
95
|
-
options.onError?.(error, event, ServiceWorkerErrorType.
|
|
95
|
+
options.onError?.(error, event, ServiceWorkerErrorType.MESSAGE_ERROR_HANDLER);
|
|
96
96
|
}
|
|
97
97
|
});
|
|
98
98
|
},
|
|
@@ -181,7 +181,7 @@ export function createEventHandlers(plugins, options) {
|
|
|
181
181
|
},
|
|
182
182
|
messageerror: (event) => {
|
|
183
183
|
try {
|
|
184
|
-
options.onError?.(event.data, event, ServiceWorkerErrorType.
|
|
184
|
+
options.onError?.(event.data, event, ServiceWorkerErrorType.MESSAGE_ERROR);
|
|
185
185
|
}
|
|
186
186
|
catch (error) {
|
|
187
187
|
logger.error('Error in messageerror handler:', error);
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { Plugin } from '../index.js';
|
|
2
2
|
import type { PrecacheConfig } from './precache.js';
|
|
3
3
|
export interface PrecacheAndNotifyConfig extends PrecacheConfig {
|
|
4
|
-
|
|
4
|
+
startInstallingMessage?: string;
|
|
5
|
+
installedMessage?: string;
|
|
5
6
|
}
|
|
6
7
|
export declare function precacheAndNotify(config: PrecacheAndNotifyConfig): Plugin;
|
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
import { notifyClients } from '../utils/notifyClients.js';
|
|
2
|
-
import { SW_MSG_INSTALLED } from '@budarin/http-constants/service-worker';
|
|
2
|
+
import { SW_MSG_INSTALLED, SW_MSG_START_INSTALLING, } from '@budarin/http-constants/service-worker';
|
|
3
3
|
export function precacheAndNotify(config) {
|
|
4
|
-
const { cacheName, assets,
|
|
4
|
+
const { cacheName, assets, startInstallingMessage = SW_MSG_START_INSTALLING, installedMessage = SW_MSG_INSTALLED, } = config;
|
|
5
5
|
return {
|
|
6
6
|
name: 'precacheAndNotify',
|
|
7
7
|
install: async () => {
|
|
8
|
+
await notifyClients(startInstallingMessage);
|
|
8
9
|
const cache = await caches.open(cacheName);
|
|
9
10
|
await cache.addAll(assets);
|
|
10
|
-
await notifyClients(
|
|
11
|
+
await notifyClients(installedMessage);
|
|
11
12
|
},
|
|
12
13
|
};
|
|
13
14
|
}
|