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

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,98 +175,90 @@ 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
-```
+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
+type EventData = {
+  type: string;
+  url: string;
+  size: number; // File size in bytes
+  reason: string; // Reason the write was not started
+};
+
+onOPFSWriteSkipped(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
 ```
 
-- `event.data`:
-  ```ts
-  {
-    type: string;
-    url: string;
-    /** File size in bytes */
-    size: number;
-    /** Reason the write was not started */
-    reason: string;
-  }
-  ```
-
-### `onOPFSEvictionCompleted` — subscribe to notification when eviction has finished.
+**`onOPFSEvictionCompleted`** — subscribe to notification when eviction has finished.
 
 ```ts
-onOPFSEvictionCompleted(handler: (event: MessageEvent) => void): Unsubscribe
-```
+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
-```
+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
-```
+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[]>
 ```
 
-### `hasInOpfsCache` — checks whether a URL is in the cache.
+Each array element:
+
+```ts
+interface OpfsCachedResource {
+  url: string;
+  size: number;
+  type: string | undefined;
+  lastModified: string | undefined;
+}
+```
+
+**`hasInOpfsCache`** — checks whether a URL is in the cache.
 
 ```ts
 hasInOpfsCache(url: string): Promise<boolean>
 ```
 
-### `deleteFromOpfsCache` — removes a resource by URL from the cache.
+**`deleteFromOpfsCache`** — removes a resource by URL from the cache.
 
 ```ts
 deleteFromOpfsCache(url: string): Promise<void>
@@ -312,7 +304,7 @@ 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.
+**`opfsServeRange`** — reads files from OPFS and serves requested byte ranges.
 
 ```ts
 opfsServeRange(options?: {
@@ -324,7 +316,7 @@ opfsServeRange(options?: {
 }): Plugin | undefined
 ```
 
-### `opfsPrecache` — during SW install, fetches a list of URLs and writes them to OPFS.
+**`opfsPrecache`** — during SW install, fetches a list of URLs and writes them to OPFS.
 
 ```ts
 opfsPrecache(options: {
@@ -335,7 +327,7 @@ opfsPrecache(options: {
 }): 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.
+**`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?: {
@@ -347,7 +339,7 @@ opfsRangeFromNetworkAndCache(options?: {
 }): Plugin | undefined
 ```
 
-### `opfsBackgroundFetch` — on successful Background Fetch completion, writes responses into OPFS; subsequent Range requests for these URLs are served by opfsServeRange.
+**`opfsBackgroundFetch`** — on successful Background Fetch completion, writes responses into OPFS; subsequent Range requests for these URLs are served by opfsServeRange.
 
 ```ts
 opfsBackgroundFetch(options?: {

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,98 +165,90 @@ await writeToOpfs(dir, key, response.body, metadata);
 type Unsubscribe = () => void;
 ```
 
-### `onOPFSQuotaExceeded` — подписка на уведомление об исчерпании квоты при записи в OPFS.
+**`onOPFSQuotaExceeded`** — подписка на уведомление об исчерпании квоты при записи в OPFS.
 
 ```ts
-onOPFSQuotaExceeded(handler: (event: MessageEvent) => void): Unsubscribe
-```
+type EventData = {
+  type: string;
+  url: string;
+};
 
-- `event.data`:
-    ```ts
-    {
-        type: string;
-        url: string;
-    }
-    ```
+onOPFSQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+```
 
-### `onOPFSWriteSkipped` — подписка на уведомление о пропуске записи (файл не влезает даже после эвикции).
+**`onOPFSWriteSkipped`** — подписка на уведомление о пропуске записи (файл не влезает даже после эвикции).
 
 ```ts
-onOPFSWriteSkipped(handler: (event: MessageEvent) => void): Unsubscribe
+type EventData = {
+  type: string;
+  url: string;
+  size: number; // Размер файла в байтах
+  reason: string; // Причина (почему запись не начата)
+};
+
+onOPFSWriteSkipped(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
 ```
 
-- `event.data`:
-    ```ts
-    {
-        type: string;
-        url: string;
-        /** Размер файла в байтах */
-        size: number;
-        /** Причина (почему запись не начата) */
-        reason: string;
-    }
-    ```
-
-### `onOPFSEvictionCompleted` — подписка на уведомление о завершении эвикции.
+**`onOPFSEvictionCompleted`** — подписка на уведомление о завершении эвикции.
 
 ```ts
-onOPFSEvictionCompleted(handler: (event: MessageEvent) => void): Unsubscribe
-```
+type EventData = {
+  type: string;
+  count: number; // Число удалённых при эвикции файлов
+};
 
-- `event.data`:
-    ```ts
-    {
-        type: string;
-        /** Число удалённых при эвикции файлов */
-        count: number;
-    }
-    ```
+onOPFSEvictionCompleted(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+```
 
-### `onOPFSWriteFailed` — подписка на уведомление об ошибке записи (сеть, диск, удалён частичный файл).
+**`onOPFSWriteFailed`** — подписка на уведомление об ошибке записи (сеть, диск, удалён частичный файл).
 
 ```ts
-onOPFSWriteFailed(handler: (event: MessageEvent) => void): Unsubscribe
-```
+type EventData = {
+  type: string;
+  url?: string;
+  reason: string; // Причина ошибки записи
+};
 
-- `event.data`:
-    ```ts
-    {
-      type: string;
-      url?: string;
-      /** Причина ошибки записи */
-      reason: string;
-    }
-    ```
+onOPFSWriteFailed(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+```
 
-### `onOPFSSkipQuotaExceeded` — подписка на уведомление о повторном запросе к URL из чёрного списка (ресурс не кешируем).
+**`onOPFSSkipQuotaExceeded`** — подписка на уведомление о повторном запросе к URL из чёрного списка (ресурс не кешируем).
 
 ```ts
-onOPFSSkipQuotaExceeded(handler: (event: MessageEvent) => void): Unsubscribe
-```
+type EventData = {
+  type: string;
+  url: string;
+};
 
-- `event.data`:
-    ```ts
-    {
-        type: string;
-        url: string;
-    }
-    ```
+onOPFSSkipQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+```
 
-**Управление кешем и типы**
+### Управление кешем и типы
 
-### `listOpfsCachedResources` — возвращает список закешированных ресурсов. Элемент: `{ url, size, type?, lastModified? }`.
+**`listOpfsCachedResources`** — возвращает список закешированных ресурсов.
 
 ```ts
 listOpfsCachedResources(): Promise<OpfsCachedResource[]>
 ```
 
-### `hasInOpfsCache` — проверяет наличие URL в кеше.
+Элемент массива:
+
+```ts
+interface OpfsCachedResource {
+  url: string;
+  size: number;
+  type: string | undefined;
+  lastModified: string | undefined;
+}
+```
+
+**`hasInOpfsCache`** — проверяет наличие URL в кеше.
 
 ```ts
 hasInOpfsCache(url: string): Promise<boolean>
 ```
 
-### `deleteFromOpfsCache` — удаляет ресурс по URL из кеша.
+**`deleteFromOpfsCache`** — удаляет ресурс по URL из кеша.
 
 ```ts
 deleteFromOpfsCache(url: string): Promise<void>
@@ -302,7 +294,7 @@ const unsubSkip = onOPFSSkipQuotaExceeded((event: MessageEvent) => {
 
 Общая настройка кеша (имя папки, доля квоты) задаётся в **configureOpfs({ folderName, maxCacheFraction })**. Ниже — плагины пакета и их опции.
 
-### `opfsServeRange` — читает файлы из OPFS и отдаёт запрошенные диапазоны байтов.
+**`opfsServeRange`** — читает файлы из OPFS и отдаёт запрошенные диапазоны байтов.
 
 ```ts
 opfsServeRange(options?: {
@@ -314,7 +306,7 @@ opfsServeRange(options?: {
 }): Plugin | undefined
 ```
 
-### `opfsPrecache` — при установке сервис-воркера загружает список URL и записывает их в OPFS.
+**`opfsPrecache`** — при установке сервис-воркера загружает список URL и записывает их в OPFS.
 
 ```ts
 opfsPrecache(options: {
@@ -325,7 +317,7 @@ opfsPrecache(options: {
 }): Plugin | undefined
 ```
 
-### `opfsRangeFromNetworkAndCache` — обрабатывает запросы, которые opfsServeRange не обслужил (ресурс ещё не в кеше): идёт в сеть, отдаёт ответ клиенту и при необходимости догружает файл в OPFS в фоне.
+**`opfsRangeFromNetworkAndCache`** — обрабатывает запросы, которые opfsServeRange не обслужил (ресурс ещё не в кеше): идёт в сеть, отдаёт ответ клиенту и при необходимости догружает файл в OPFS в фоне.
 
 ```ts
 opfsRangeFromNetworkAndCache(options?: {
@@ -337,7 +329,7 @@ opfsRangeFromNetworkAndCache(options?: {
 }): Plugin | undefined
 ```
 
-### `opfsBackgroundFetch` — при успешном завершении загрузки через Background Fetch API записывает ответы в OPFS; дальнейшие range‑запросы по этим URL обслуживает opfsServeRange.
+**`opfsBackgroundFetch`** — при успешном завершении загрузки через Background Fetch API записывает ответы в OPFS; дальнейшие range‑запросы по этим URL обслуживает opfsServeRange.
 
 ```ts
 opfsBackgroundFetch(options?: {

package/package.json

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