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

package/README.md

@@ -175,94 +175,96 @@ 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
-type EventData = {
-  type: string;
-  url: string;
-};
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+    };
 
-onOPFSQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    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
-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
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+      size: number; // File size in bytes
+      reason: string; // Reason the write was not started
+    };
 
-**`onOPFSEvictionCompleted`** — subscribe to notification when eviction has finished.
+    onOPFSWriteSkipped(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-type EventData = {
-  type: string;
-  count: number; // Number of files removed by eviction
-};
+- **`onOPFSEvictionCompleted`** — subscribe to notification when eviction has finished.
 
-onOPFSEvictionCompleted(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      count: number; // Number of files removed by eviction
+    };
 
-**`onOPFSWriteFailed`** — subscribe to notification on write error (network, disk, partial file removed).
+    onOPFSEvictionCompleted(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-type EventData = {
-  type: string;
-  url?: string;
-  reason: string; // Reason the write failed
-};
+- **`onOPFSWriteFailed`** — subscribe to notification on write error (network, disk, partial file removed).
 
-onOPFSWriteFailed(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url?: string;
+      reason: string; // Reason the write failed
+    };
 
-**`onOPFSSkipQuotaExceeded`** — subscribe to notification on repeat request for a blacklisted URL (resource not cached).
+    onOPFSWriteFailed(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-type EventData = {
-  type: string;
-  url: string;
-};
+- **`onOPFSSkipQuotaExceeded`** — subscribe to notification on repeat request for a blacklisted URL (resource not cached).
 
-onOPFSSkipQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+    };
 
-### Cache management and types
+    onOPFSSkipQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-**`listOpfsCachedResources`** — returns the list of cached resources.
+### Cache management utilities
 
-```ts
-listOpfsCachedResources(): Promise<OpfsCachedResource[]>
-```
+Functions to list cached resources, check by URL, and remove by URL. Called from the client (page); use when you need to show the user what is cached and let them delete selected items.
 
-Each array element:
+- **`listOpfsCachedResources`** — returns the list of cached resources.
 
-```ts
-interface OpfsCachedResource {
-  url: string;
-  size: number;
-  type: string | undefined;
-  lastModified: string | undefined;
-}
-```
+    ```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`.
 
@@ -304,52 +306,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

@@ -165,94 +165,96 @@ await writeToOpfs(dir, key, response.body, metadata);
 type Unsubscribe = () => void;
 ```
 
-**`onOPFSQuotaExceeded`** — подписка на уведомление об исчерпании квоты при записи в OPFS.
+- **`onOPFSQuotaExceeded`** — подписка на уведомление об исчерпании квоты при записи в OPFS.
 
-```ts
-type EventData = {
-  type: string;
-  url: string;
-};
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+    };
 
-onOPFSQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    onOPFSQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-**`onOPFSWriteSkipped`** — подписка на уведомление о пропуске записи (файл не влезает даже после эвикции).
+- **`onOPFSWriteSkipped`** — подписка на уведомление о пропуске записи (файл не влезает даже после эвикции).
 
-```ts
-type EventData = {
-  type: string;
-  url: string;
-  size: number; // Размер файла в байтах
-  reason: string; // Причина (почему запись не начата)
-};
-
-onOPFSWriteSkipped(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+      size: number; // Размер файла в байтах
+      reason: string; // Причина (почему запись не начата)
+    };
 
-**`onOPFSEvictionCompleted`** — подписка на уведомление о завершении эвикции.
+    onOPFSWriteSkipped(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-type EventData = {
-  type: string;
-  count: number; // Число удалённых при эвикции файлов
-};
+- **`onOPFSEvictionCompleted`** — подписка на уведомление о завершении эвикции.
 
-onOPFSEvictionCompleted(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      count: number; // Число удалённых при эвикции файлов
+    };
 
-**`onOPFSWriteFailed`** — подписка на уведомление об ошибке записи (сеть, диск, удалён частичный файл).
+    onOPFSEvictionCompleted(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-type EventData = {
-  type: string;
-  url?: string;
-  reason: string; // Причина ошибки записи
-};
+- **`onOPFSWriteFailed`** — подписка на уведомление об ошибке записи (сеть, диск, удалён частичный файл).
 
-onOPFSWriteFailed(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url?: string;
+      reason: string; // Причина ошибки записи
+    };
 
-**`onOPFSSkipQuotaExceeded`** — подписка на уведомление о повторном запросе к URL из чёрного списка (ресурс не кешируем).
+    onOPFSWriteFailed(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-```ts
-type EventData = {
-  type: string;
-  url: string;
-};
+- **`onOPFSSkipQuotaExceeded`** — подписка на уведомление о повторном запросе к URL из чёрного списка (ресурс не кешируем).
 
-onOPFSSkipQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
-```
+    ```ts
+    type EventData = {
+      type: string;
+      url: string;
+    };
 
-### Управление кешем и типы
+    onOPFSSkipQuotaExceeded(handler: (event: MessageEvent<EventData>) => void): Unsubscribe
+    ```
 
-**`listOpfsCachedResources`** — возвращает список закешированных ресурсов.
+### Утилиты управления кэшем
 
-```ts
-listOpfsCachedResources(): Promise<OpfsCachedResource[]>
-```
+Функции для получения списка закешированных ресурсов, проверки по URL и удаления по URL. Вызываются на клиенте (страница); нужны, когда надо показать пользователю, что в кэше, и дать удалить выбранное.
 
-Элемент массива:
+- **`listOpfsCachedResources`** — возвращает список закешированных ресурсов.
 
-```ts
-interface OpfsCachedResource {
-  url: string;
-  size: number;
-  type: string | undefined;
-  lastModified: string | undefined;
-}
-```
+    ```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`.
 
@@ -294,52 +296,52 @@ const unsubSkip = onOPFSSkipQuotaExceeded((event: MessageEvent) => {
 
 Общая настройка кеша (имя папки, доля квоты) задаётся в **configureOpfs({ folderName, maxCacheFraction })**. Ниже — плагины пакета и их опции.
 
-**`opfsServeRange`** — читает файлы из OPFS и отдаёт запрошенные диапазоны байтов.
-
-```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.
-
-```ts
-opfsPrecache(options: {
-  urls: string[] | (() => Promise<string[]>); // список URL или функция
-  order?: number;
-  enableLogging?: boolean;
-  pinned?: string[]; // glob-паттерны URL, защищённых от эвикции (см. «Закреплённые ресурсы»)
-}): Plugin | undefined
-```
-
-**`opfsRangeFromNetworkAndCache`** — обрабатывает запросы, которые opfsServeRange не обслужил (ресурс ещё не в кеше): идёт в сеть, отдаёт ответ клиенту и при необходимости догружает файл в OPFS в фоне.
-
-```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.
-
-```ts
-opfsBackgroundFetch(options?: {
-  order?: number;
-  include?: string[];
-  exclude?: string[];
-  enableLogging?: boolean;
-  pinned?: string[]; // glob-паттерны URL, защищённых от эвикции
-}): Plugin | undefined
-```
+- **`opfsServeRange`** — читает файлы из OPFS и отдаёт запрошенные диапазоны байтов.
+
+    ```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.
+
+    ```ts
+    opfsPrecache(options: {
+      urls: string[] | (() => Promise<string[]>); // список URL или функция
+      order?: number;
+      enableLogging?: boolean;
+      pinned?: string[]; // glob-паттерны URL, защищённых от эвикции (см. «Закреплённые ресурсы»)
+    }): Plugin | undefined
+    ```
+
+- **`opfsRangeFromNetworkAndCache`** — обрабатывает запросы, которые opfsServeRange не обслужил (ресурс ещё не в кеше): идёт в сеть, отдаёт ответ клиенту и при необходимости догружает файл в OPFS в фоне.
+
+    ```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.
+
+    ```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.8",
+  "version": "1.1.10",
   "description": "Service Worker plugin: serve HTTP Range requests from OPFS files",
   "keywords": [
     "service-worker",