@budarin/psw-plugin-opfs-serve-range 1.1.7 → 1.1.9

package/README.md

@@ -163,11 +163,11 @@ The response may not have a `Content-Length` header – when writing the full bo
 
 Client‑side helpers are exported from the entry point `@budarin/psw-plugin-opfs-serve-range/client`. This section gives signatures, types, and examples; [opfs-cache-behavior.md](https://github.com/budarin/psw-plugin-opfs-serve-range/blob/master/docs/opfs-cache-behavior.md) only describes **when** the service worker sends messages (limits, LRU, eviction), not the API.
 
-**Message payload**
+### Message payload
 
 Each handler receives a `MessageEvent`; `event.data` is `{ type: string } & OpfsMessagePayload`, and some events add a `count` field. The package type `OpfsMessagePayload` is `{ url?: string; size?: number; limit?: number; reason?: string }`.
 
-**Message subscriptions**
+### Message subscriptions
 
 Each function takes a handler and returns an unsubscribe function (call it to remove the subscription). Below are the subscriptions for messages that the service worker actually sends in the current version.
 
@@ -175,102 +175,94 @@ Each function takes a handler and returns an unsubscribe function (call it to re
 type Unsubscribe = () => void;
 ```
 
-### `onOPFSQuotaExceeded` — subscribe to notification when the browser throws QuotaExceeded while writing to OPFS.
+- **`onOPFSQuotaExceeded`** — subscribe to notification when the browser throws QuotaExceeded while writing to OPFS.
 
-```ts
-onOPFSQuotaExceeded(handler: (event: MessageEvent) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+    };
 
-- `event.data`:
-  ```ts
-  {
-    type: string;
-    url: string;
-  }
-  ```
+    onOPFSQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-### `onOPFSWriteSkipped` — subscribe to notification when the write was skipped (file does not fit even after eviction).
+- **`onOPFSWriteSkipped`** — subscribe to notification when the write was skipped (file does not fit even after eviction).
 
-```ts
-onOPFSWriteSkipped(handler: (event: MessageEvent) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+      size: number; // File size in bytes
+      reason: string; // Reason the write was not started
+    };
 
-- `event.data`:
-  ```ts
-  {
-    type: string;
-    url: string;
-    /** File size in bytes */
-    size: number;
-    /** Reason the write was not started */
-    reason: string;
-  }
-  ```
+    onOPFSWriteSkipped(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-### `onOPFSEvictionCompleted` — subscribe to notification when eviction has finished.
+- **`onOPFSEvictionCompleted`** — subscribe to notification when eviction has finished.
 
-```ts
-onOPFSEvictionCompleted(handler: (event: MessageEvent) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      count: number; // Number of files removed by eviction
+    };
 
-- `event.data`:
-  ```ts
-  {
-    type: string;
-    /** Number of files removed by eviction */
-    count: number;
-  }
-  ```
+    onOPFSEvictionCompleted(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-### `onOPFSWriteFailed` — subscribe to notification on write error (network, disk, partial file removed).
+- **`onOPFSWriteFailed`** — subscribe to notification on write error (network, disk, partial file removed).
 
-```ts
-onOPFSWriteFailed(handler: (event: MessageEvent) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url?: string;
+      reason: string; // Reason the write failed
+    };
 
-- `event.data`:
-  ```ts
-  {
-    type: string;
-    url?: string;
-    /** Reason the write failed */
-    reason: string;
-  }
-  ```
+    onOPFSWriteFailed(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-### `onOPFSSkipQuotaExceeded` — subscribe to notification on repeat request for a blacklisted URL (resource not cached).
+- **`onOPFSSkipQuotaExceeded`** — subscribe to notification on repeat request for a blacklisted URL (resource not cached).
 
-```ts
-onOPFSSkipQuotaExceeded(handler: (event: MessageEvent) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+    };
 
-- `event.data`:
-  ```ts
-  {
-    type: string;
-    url: string;
-  }
-  ```
+    onOPFSSkipQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-**Cache management and types**
+### Cache management and types
 
-### `listOpfsCachedResources` — returns the list of cached resources. Each item: `{ url, size, type?, lastModified? }`.
+- **`listOpfsCachedResources`** — returns the list of cached resources.
 
-```ts
-listOpfsCachedResources(): Promise<OpfsCachedResource[]>
-```
+    ```ts
+    listOpfsCachedResources(): Promise<OpfsCachedResource[]>
+    ```
 
-### `hasInOpfsCache` — checks whether a URL is in the cache.
+    Each array element:
 
-```ts
-hasInOpfsCache(url: string): Promise<boolean>
-```
+    ```ts
+    interface OpfsCachedResource {
+      url: string;
+      size: number;
+      type: string | undefined;
+      lastModified: string | undefined;
+    }
+    ```
 
-### `deleteFromOpfsCache` — removes a resource by URL from the cache.
+- **`hasInOpfsCache`** — checks whether a URL is in the cache.
 
-```ts
-deleteFromOpfsCache(url: string): Promise<void>
-```
+    ```ts
+    hasInOpfsCache(url: string): Promise<boolean>
+    ```
+
+- **`deleteFromOpfsCache`** — removes a resource by URL from the cache.
+
+    ```ts
+    deleteFromOpfsCache(url: string): Promise<void>
+    ```
 
 Types `OpfsMessagePayload` and `OpfsCachedResource` are exported. Message type constants (name equals the string value in `event.data.type`): `OPFS_MSG_QUOTA_EXCEEDED`, `OPFS_MSG_WRITE_SKIPPED_SIZE`, `OPFS_MSG_CACHE_LIMIT_REACHED`, `OPFS_MSG_EVICTION_COMPLETED`, `OPFS_MSG_WRITE_FAILED`, `OPFS_MSG_SKIP_QUOTA_EXCEEDED`.
 
@@ -312,52 +304,52 @@ If you need finer‑grained control (show a list of cached resources and let use
 
 Global cache settings (folder name, quota fraction) are set in **configureOpfs({ folderName, maxCacheFraction })**. Below are the package plugins and their options.
 
-### `opfsServeRange` — reads files from OPFS and serves requested byte ranges.
-
-```ts
-opfsServeRange(options?: {
-  order?: number;
-  enableLogging?: boolean;
-  include?: string[];
-  exclude?: string[];
-  rangeResponseCacheControl?: string; // Cache-Control for 206 responses (default: max-age=31536000, immutable)
-}): Plugin | undefined
-```
-
-### `opfsPrecache` — during SW install, fetches a list of URLs and writes them to OPFS.
-
-```ts
-opfsPrecache(options: {
-  urls: string[] | (() => Promise<string[]>); // array of URLs or function
-  order?: number;
-  enableLogging?: boolean;
-  pinned?: string[]; // glob patterns for URLs protected from eviction (see «Pinned resources»)
-}): Plugin | undefined
-```
-
-### `opfsRangeFromNetworkAndCache` — handles requests that opfsServeRange did not serve (resource not in cache yet): goes to the network, streams the response to the client, and optionally fills OPFS in the background.
-
-```ts
-opfsRangeFromNetworkAndCache(options?: {
-  order?: number;
-  include?: string[];
-  exclude?: string[];
-  enableLogging?: boolean;
-  pinned?: string[]; // glob patterns for URLs protected from eviction
-}): Plugin | undefined
-```
-
-### `opfsBackgroundFetch` — on successful Background Fetch completion, writes responses into OPFS; subsequent Range requests for these URLs are served by opfsServeRange.
-
-```ts
-opfsBackgroundFetch(options?: {
-  order?: number;
-  include?: string[];
-  exclude?: string[];
-  enableLogging?: boolean;
-  pinned?: string[]; // glob patterns for URLs protected from eviction
-}): Plugin | undefined
-```
+- **`opfsServeRange`** — reads files from OPFS and serves requested byte ranges.
+
+    ```ts
+    opfsServeRange(options?: {
+      order?: number;
+      enableLogging?: boolean;
+      include?: string[];
+      exclude?: string[];
+      rangeResponseCacheControl?: string; // Cache-Control for 206 responses (default: max-age=31536000, immutable)
+    }): Plugin | undefined
+    ```
+
+- **`opfsPrecache`** — during SW install, fetches a list of URLs and writes them to OPFS.
+
+    ```ts
+    opfsPrecache(options: {
+      urls: string[] | (() => Promise<string[]>); // array of URLs or function
+      order?: number;
+      enableLogging?: boolean;
+      pinned?: string[]; // glob patterns for URLs protected from eviction (see «Pinned resources»)
+    }): Plugin | undefined
+    ```
+
+- **`opfsRangeFromNetworkAndCache`** — handles requests that opfsServeRange did not serve (resource not in cache yet): goes to the network, streams the response to the client, and optionally fills OPFS in the background.
+
+    ```ts
+    opfsRangeFromNetworkAndCache(options?: {
+      order?: number;
+      include?: string[];
+      exclude?: string[];
+      enableLogging?: boolean;
+      pinned?: string[]; // glob patterns for URLs protected from eviction
+    }): Plugin | undefined
+    ```
+
+- **`opfsBackgroundFetch`** — on successful Background Fetch completion, writes responses into OPFS; subsequent Range requests for these URLs are served by opfsServeRange.
+
+    ```ts
+    opfsBackgroundFetch(options?: {
+      order?: number;
+      include?: string[];
+      exclude?: string[];
+      enableLogging?: boolean;
+      pinned?: string[]; // glob patterns for URLs protected from eviction
+    }): Plugin | undefined
+    ```
 
 To trigger downloads from the client: `@budarin/pluggable-serviceworker/client/background-fetch`.
 

package/README.ru.md

@@ -153,11 +153,11 @@ await writeToOpfs(dir, key, response.body, metadata);
 
 Клиентские хелперы экспортируются из entry point `@budarin/psw-plugin-opfs-serve-range/client`. В этом разделе — сигнатуры, типы и примеры; в [opfs-cache-behavior.ru.md](https://github.com/budarin/psw-plugin-opfs-serve-range/blob/master/docs/opfs-cache-behavior.ru.md) описано только **когда** сервис-воркер шлёт сообщения (лимиты, LRU, эвикция), не API.
 
-**Данные в сообщениях**
+### Данные в сообщениях
 
 Обработчик получает `MessageEvent`; `event.data` имеет тип `{ type: string } & OpfsMessagePayload` плюс при необходимости поле `count`. Тип `OpfsMessagePayload` в пакете: `{ url?: string; size?: number; limit?: number; reason?: string }`.
 
-**Подписки на сообщения**
+### Подписки на сообщения
 
 Каждая функция принимает обработчик и возвращает функцию отписки (вызов снимает подписку). Ниже перечислены подписки, сообщения которых сервис-воркер реально отправляет в текущей версии.
 
@@ -165,102 +165,94 @@ await writeToOpfs(dir, key, response.body, metadata);
 type Unsubscribe = () => void;
 ```
 
-### `onOPFSQuotaExceeded` — подписка на уведомление об исчерпании квоты при записи в OPFS.
+- **`onOPFSQuotaExceeded`** — подписка на уведомление об исчерпании квоты при записи в OPFS.
 
-```ts
-onOPFSQuotaExceeded(handler: (event: MessageEvent) => void): Unsubscribe
-```
-
-- `event.data`:
     ```ts
-    {
-        type: string;
-        url: string;
-    }
-    ```
+    type EventData = {
+      type: string;
+      url: string;
+    };
 
-### `onOPFSWriteSkipped` — подписка на уведомление о пропуске записи (файл не влезает даже после эвикции).
+    onOPFSQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-onOPFSWriteSkipped(handler: (event: MessageEvent) => void): Unsubscribe
-```
+- **`onOPFSWriteSkipped`** — подписка на уведомление о пропуске записи (файл не влезает даже после эвикции).
 
-- `event.data`:
     ```ts
-    {
-        type: string;
-        url: string;
-        /** Размер файла в байтах */
-        size: number;
-        /** Причина (почему запись не начата) */
-        reason: string;
-    }
-    ```
+    type EventData = {
+      type: string;
+      url: string;
+      size: number; // Размер файла в байтах
+      reason: string; // Причина (почему запись не начата)
+    };
 
-### `onOPFSEvictionCompleted` — подписка на уведомление о завершении эвикции.
+    onOPFSWriteSkipped(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-onOPFSEvictionCompleted(handler: (event: MessageEvent) => void): Unsubscribe
-```
+- **`onOPFSEvictionCompleted`** — подписка на уведомление о завершении эвикции.
 
-- `event.data`:
     ```ts
-    {
-        type: string;
-        /** Число удалённых при эвикции файлов */
-        count: number;
-    }
-    ```
+    type EventData = {
+      type: string;
+      count: number; // Число удалённых при эвикции файлов
+    };
 
-### `onOPFSWriteFailed` — подписка на уведомление об ошибке записи (сеть, диск, удалён частичный файл).
+    onOPFSEvictionCompleted(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-onOPFSWriteFailed(handler: (event: MessageEvent) => void): Unsubscribe
-```
+- **`onOPFSWriteFailed`** — подписка на уведомление об ошибке записи (сеть, диск, удалён частичный файл).
 
-- `event.data`:
     ```ts
-    {
+    type EventData = {
       type: string;
       url?: string;
-      /** Причина ошибки записи */
-      reason: string;
-    }
+      reason: string; // Причина ошибки записи
+    };
+
+    onOPFSWriteFailed(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
     ```
 
-### `onOPFSSkipQuotaExceeded` — подписка на уведомление о повторном запросе к URL из чёрного списка (ресурс не кешируем).
+- **`onOPFSSkipQuotaExceeded`** — подписка на уведомление о повторном запросе к URL из чёрного списка (ресурс не кешируем).
 
-```ts
-onOPFSSkipQuotaExceeded(handler: (event: MessageEvent) => void): Unsubscribe
-```
-
-- `event.data`:
     ```ts
-    {
-        type: string;
-        url: string;
-    }
+    type EventData = {
+      type: string;
+      url: string;
+    };
+
+    onOPFSSkipQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
     ```
 
-**Управление кешем и типы**
+### Управление кешем и типы
 
-### `listOpfsCachedResources` — возвращает список закешированных ресурсов. Элемент: `{ url, size, type?, lastModified? }`.
+- **`listOpfsCachedResources`** — возвращает список закешированных ресурсов.
 
-```ts
-listOpfsCachedResources(): Promise<OpfsCachedResource[]>
-```
+    ```ts
+    listOpfsCachedResources(): Promise<OpfsCachedResource[]>
+    ```
 
-### `hasInOpfsCache` — проверяет наличие URL в кеше.
+    Элемент массива:
 
-```ts
-hasInOpfsCache(url: string): Promise<boolean>
-```
+    ```ts
+    interface OpfsCachedResource {
+      url: string;
+      size: number;
+      type: string | undefined;
+      lastModified: string | undefined;
+    }
+    ```
 
-### `deleteFromOpfsCache` — удаляет ресурс по URL из кеша.
+- **`hasInOpfsCache`** — проверяет наличие URL в кеше.
 
-```ts
-deleteFromOpfsCache(url: string): Promise<void>
-```
+    ```ts
+    hasInOpfsCache(url: string): Promise<boolean>
+    ```
+
+- **`deleteFromOpfsCache`** — удаляет ресурс по URL из кеша.
+
+    ```ts
+    deleteFromOpfsCache(url: string): Promise<void>
+    ```
 
 Типы `OpfsMessagePayload` и `OpfsCachedResource` экспортируются из пакета. Константы типов сообщений (имя совпадает со строковым значением в `event.data.type`): `OPFS_MSG_QUOTA_EXCEEDED`, `OPFS_MSG_WRITE_SKIPPED_SIZE`, `OPFS_MSG_CACHE_LIMIT_REACHED`, `OPFS_MSG_EVICTION_COMPLETED`, `OPFS_MSG_WRITE_FAILED`, `OPFS_MSG_SKIP_QUOTA_EXCEEDED`.
 
@@ -302,52 +294,52 @@ const unsubSkip = onOPFSSkipQuotaExceeded((event: MessageEvent) => {
 
 Общая настройка кеша (имя папки, доля квоты) задаётся в **configureOpfs({ folderName, maxCacheFraction })**. Ниже — плагины пакета и их опции.
 
-### `opfsServeRange` — читает файлы из OPFS и отдаёт запрошенные диапазоны байтов.
+- **`opfsServeRange`** — читает файлы из OPFS и отдаёт запрошенные диапазоны байтов.
 
-```ts
-opfsServeRange(options?: {
-  order?: number;
-  enableLogging?: boolean;
-  include?: string[];
-  exclude?: string[];
-  rangeResponseCacheControl?: string; // Cache-Control для ответов 206 (по умолчанию max-age=31536000, immutable)
-}): Plugin | undefined
-```
+    ```ts
+    opfsServeRange(options?: {
+      order?: number;
+      enableLogging?: boolean;
+      include?: string[];
+      exclude?: string[];
+      rangeResponseCacheControl?: string; // Cache-Control для ответов 206 (по умолчанию max-age=31536000, immutable)
+    }): Plugin | undefined
+    ```
 
-### `opfsPrecache` — при установке сервис-воркера загружает список URL и записывает их в OPFS.
+- **`opfsPrecache`** — при установке сервис-воркера загружает список URL и записывает их в OPFS.
 
-```ts
-opfsPrecache(options: {
-  urls: string[] | (() => Promise<string[]>); // список URL или функция
-  order?: number;
-  enableLogging?: boolean;
-  pinned?: string[]; // glob-паттерны URL, защищённых от эвикции (см. «Закреплённые ресурсы»)
-}): Plugin | undefined
-```
+    ```ts
+    opfsPrecache(options: {
+      urls: string[] | (() => Promise<string[]>); // список URL или функция
+      order?: number;
+      enableLogging?: boolean;
+      pinned?: string[]; // glob-паттерны URL, защищённых от эвикции (см. «Закреплённые ресурсы»)
+    }): Plugin | undefined
+    ```
 
-### `opfsRangeFromNetworkAndCache` — обрабатывает запросы, которые opfsServeRange не обслужил (ресурс ещё не в кеше): идёт в сеть, отдаёт ответ клиенту и при необходимости догружает файл в OPFS в фоне.
+- **`opfsRangeFromNetworkAndCache`** — обрабатывает запросы, которые opfsServeRange не обслужил (ресурс ещё не в кеше): идёт в сеть, отдаёт ответ клиенту и при необходимости догружает файл в OPFS в фоне.
 
-```ts
-opfsRangeFromNetworkAndCache(options?: {
-  order?: number;
-  include?: string[];
-  exclude?: string[];
-  enableLogging?: boolean;
-  pinned?: string[]; // glob-паттерны URL, защищённых от эвикции
-}): Plugin | undefined
-```
+    ```ts
+    opfsRangeFromNetworkAndCache(options?: {
+      order?: number;
+      include?: string[];
+      exclude?: string[];
+      enableLogging?: boolean;
+      pinned?: string[]; // glob-паттерны URL, защищённых от эвикции
+    }): Plugin | undefined
+    ```
 
-### `opfsBackgroundFetch` — при успешном завершении загрузки через Background Fetch API записывает ответы в OPFS; дальнейшие range‑запросы по этим URL обслуживает opfsServeRange.
+- **`opfsBackgroundFetch`** — при успешном завершении загрузки через Background Fetch API записывает ответы в OPFS; дальнейшие range‑запросы по этим URL обслуживает opfsServeRange.
 
-```ts
-opfsBackgroundFetch(options?: {
-  order?: number;
-  include?: string[];
-  exclude?: string[];
-  enableLogging?: boolean;
-  pinned?: string[]; // glob-паттерны URL, защищённых от эвикции
-}): Plugin | undefined
-```
+    ```ts
+    opfsBackgroundFetch(options?: {
+      order?: number;
+      include?: string[];
+      exclude?: string[];
+      enableLogging?: boolean;
+      pinned?: string[]; // glob-паттерны URL, защищённых от эвикции
+    }): Plugin | undefined
+    ```
 
 Запуск загрузки с клиента: утилиты из `@budarin/pluggable-serviceworker/client/background-fetch`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@budarin/psw-plugin-opfs-serve-range",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "Service Worker plugin: serve HTTP Range requests from OPFS files",
   "keywords": [
     "service-worker",