zip-peek 0.1.0 → 0.2.1

package/README.md

@@ -17,14 +17,14 @@ Use this package when your app receives a base path and later appends folders an
 For example, your app may normally treat the base path as a directory:
 
 ```ts
-const basePath = 'https://cdn.example.com/packages/session';
+const basePath = "https://cdn.example.com/packages/session";
 const imageUrl = `${basePath}/slides/slide-1/image.png`;
 ```
 
 If the same assets are sometimes delivered as a ZIP file instead:
 
 ```ts
-const basePath = 'https://cdn.example.com/packages/session.zip';
+const basePath = "https://cdn.example.com/packages/session.zip";
 const imageUrl = `${basePath}/slides/slide-1/image.png`;
 ```
 
@@ -39,16 +39,14 @@ The package provides two pieces:
 
 At runtime, the package:
 
-1. Checks whether the provided `zipUrl` points to a `.zip` file.
-2. Registers the ZIP service worker with the configured `workerUrl` and `scopeUrl`.
-3. Reloads once after first service worker install when needed, so the page becomes controlled.
-4. Reads the ZIP central directory using HTTP range requests.
-5. Sends the parsed ZIP manifest to the service worker.
-6. Intercepts asset requests under the ZIP URL.
-7. Fetches only the byte range needed for the requested file.
-8. Inflates deflated files using `fflate`.
-9. Returns the extracted file bytes to the browser request as a normal `Response`.
-10. Caches extracted assets in the browser Cache API.
+1. Registers the ZIP service worker with the configured `workerUrl` and `scopeUrl`.
+2. Reloads once after first service worker install when needed, so the page becomes controlled.
+3. Intercepts matching `.zip/...` asset requests within the service worker scope.
+4. Loads and caches the ZIP central directory on first use, or during init when `allowedZipUrls` is provided.
+5. Fetches only the byte range needed for the requested file.
+6. Inflates deflated files using `fflate`.
+7. Returns the extracted file bytes to the browser request as a normal `Response`.
+8. Caches extracted assets in the browser Cache API.
 
 ## Installation
 
@@ -65,23 +63,22 @@ npm install zip-peek
 ## Basic Usage
 
 ```ts
-import { initZipPeek } from 'zip-peek';
+import { initZipPeek } from "zip-peek";
 
 const zipPeekInit = await initZipPeek({
-    zipUrl: 'https://cdn.example.com/packages/zipfile.zip',
-    workerUrl: new URL('/zipServiceWorker.js', window.location.origin).href,
-    scopeUrl: new URL('/', window.location.origin).href,
+  workerUrl: new URL("/zipServiceWorker.js", window.location.origin).href,
+  scopeUrl: new URL("/", window.location.origin).href,
 });
 
 if (zipPeekInit.reloaded) {
-    return;
+  return;
 }
 ```
 
 After initialization, your app can continue building asset URLs under the ZIP URL:
 
 ```ts
-const zipUrl = 'https://cdn.example.com/packages/zipfile.zip';
+const zipUrl = "https://cdn.example.com/packages/zipfile.zip";
 const imgUrl = `${zipUrl}/slides/slide-1/image.png`;
 
 // This request will work normally and zip-peek will do the magic in the background:
@@ -96,39 +93,30 @@ The browser requests that URL normally. The service worker intercepts it and ser
 
 ```ts
 type InitZipPeekOptions = {
-    zipUrl: string;
-    workerUrl: string;
-    scopeUrl: string;
-    reloadOnFirstInstall?: boolean;
-    purgeOtherZipAssets?: boolean;
-    zipAssetCacheName?: string;
-    assetCacheTtlMs?: number;
-    logPrefix?: string;
+  workerUrl: string;
+  scopeUrl: string;
+  reloadOnFirstInstall?: boolean;
+  cacheClearingStrategy?: ZipCacheClearingStrategy;
+  allowedZipUrls?: string[];
+  zipAssetCacheName?: string;
+  assetCacheTtlMs?: number;
+  logPrefix?: string;
 };
+
+type ZipCacheClearingStrategy = "keep-all" | "keep-allowed-urls" | "clear-all";
 ```
 
 Returns:
 
 ```ts
 type InitZipPeekResult = {
-    reloaded: boolean;
-    initialized: boolean;
+  reloaded: boolean;
+  initialized: boolean;
 };
 ```
 
 ### Options
 
-`zipUrl`
-
-The URL of the ZIP package. This can be absolute or relative, but it must point to a path ending in `.zip`. It can also be a presigned url.
-
-Example:
-
-```ts
-zipUrl: 'https://cdn.example.com/packages/zipfile.zip'
-zipUrl: 'https://d3jfe.cloudfront.net/somedir/zipfile.zip?Expires=1798761599&Signature=K2CJW4Z7B3DCM4&Key-Pair-Id=K2CJW4Z7B3DCM4'
-```
-
 `workerUrl`
 
 The URL where the browser can download the service worker JavaScript file. The service worker file must be served from the same origin as the page.
@@ -136,10 +124,10 @@ The URL where the browser can download the service worker JavaScript file. The s
 Example:
 
 ```ts
-workerUrl: new URL('./zipServiceWorker.js', window.location.href).href
+workerUrl: new URL("./zipServiceWorker.js", window.location.href).href;
 ```
 
-In production, you will usually prefer hashed file to give it a long CacheControl duration:
+In production, you will usually prefer hashed file to give it a long `Cache-Control` duration:
 
 ```text
 zipServiceWorker.a1b2c3d4.js
@@ -148,12 +136,13 @@ zipServiceWorker.a1b2c3d4.js
 `scopeUrl`
 
 The service worker scope. The worker can only intercept requests inside this scope.
+See [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register#scope) for more details.
 
 Examples:
 
 ```ts
-scopeUrl: new URL('/', window.location.origin).href
-scopeUrl: new URL('/app/', window.location.origin).href
+scopeUrl: new URL("/", window.location.origin).href;
+scopeUrl: new URL("/app/", window.location.origin).href;
 ```
 
 Choose the smallest scope that includes the pages and asset requests you want the service worker to intercept. For local development, the scope often differs from production because the app may be served from a different path.
@@ -162,9 +151,28 @@ Choose the smallest scope that includes the pages and asset requests you want th
 
 Defaults to `true`. When a service worker is installed for the first time, the current page may not yet be controlled by it. With this option enabled, the package reloads once and returns `{ reloaded: true, initialized: false }`.
 
-`purgeOtherZipAssets`
+`cacheClearingStrategy`
+
+Defaults to `'keep-all'`. Controls which zip-peek cache entries are cleared during initialization.
+
+- `'keep-all'`: do not clear cached ZIP manifests or extracted assets.
+- `'keep-allowed-urls'`: requires non-empty `allowedZipUrls`; clears cached ZIP data for URLs outside the allow-list.
+- `'clear-all'`: clears all zip-peek cached manifests and extracted assets for a fresh start.
 
-Defaults to `true`. Removes cached assets and manifests for other ZIP URLs from this package's Cache API bucket.
+`allowedZipUrls`
+
+Restricts zip-peek to a known set of ZIP package URLs. When omitted, zip-peek lazily serves any matching `.zip/...` request inside the service worker scope. When provided, the array must contain at least one ZIP URL, and zip-peek transparently passes matching requests for ZIP URLs outside the list.
+
+The allow-list also acts as a warmup list: zip-peek loads and caches each allowed ZIP manifest during initialization.
+
+Examples:
+
+```ts
+allowedZipUrls: ["https://cdn.example.com/packages/zipfile.zip"];
+allowedZipUrls: [
+  "https://d3jfe.cloudfront.net/somedir/zipfile.zip?Expires=1798761599&Signature=K2CJW4Z7B3DCM4&Key-Pair-Id=K2CJW4Z7B3DCM4",
+];
+```
 
 `zipAssetCacheName`
 
@@ -183,7 +191,7 @@ Controls how long extracted assets remain valid in the Cache API.
 Default:
 
 ```ts
-2 * 60 * 60 * 1000
+2 * 60 * 60 * 1000; // 2 hours
 ```
 
 `logPrefix`
@@ -261,8 +269,8 @@ The registered scope must be allowed by both:
 Example:
 
 ```ts
-navigator.serviceWorker.register('/app/zipServiceWorker.a1b2c3d4.js', {
-    scope: '/app/',
+navigator.serviceWorker.register("/app/zipServiceWorker.a1b2c3d4.js", {
+  scope: "/app/",
 });
 ```
 
@@ -293,19 +301,19 @@ Your application must copy this file into its public build output. The browser r
 When your app emits hashed assets, copy the worker with a content hash and pass the final worker URL to `initZipPeek()`.
 
 ```js
-const CopyPlugin = require('copy-webpack-plugin');
+const CopyPlugin = require("copy-webpack-plugin");
 
 module.exports = {
-    plugins: [
-        new CopyPlugin({
-            patterns: [
-                {
-                    from: require.resolve('zip-peek/zipServiceWorker.js'),
-                    to: 'zipServiceWorker.[contenthash:8].js',
-                },
-            ],
-        }),
-    ],
+  plugins: [
+    new CopyPlugin({
+      patterns: [
+        {
+          from: require.resolve("zip-peek/zipServiceWorker.js"),
+          to: "zipServiceWorker.[contenthash:8].js",
+        },
+      ],
+    }),
+  ],
 };
 ```
 
@@ -319,9 +327,11 @@ For example, after resolving the emitted filename:
 
 ```ts
 await initZipPeek({
-    zipUrl,
-    workerUrl: new URL(`/assets/${zipServiceWorkerFilename}`, window.location.origin).href,
-    scopeUrl: new URL('/', window.location.origin).href,
+  workerUrl: new URL(
+    `/assets/${zipServiceWorkerFilename}`,
+    window.location.origin,
+  ).href,
+  scopeUrl: new URL("/", window.location.origin).href,
 });
 ```
 
@@ -336,19 +346,19 @@ zipServiceWorker.a1b2c3d4.js
 In development, it is usually simpler to copy the worker without a hash:
 
 ```js
-const CopyPlugin = require('copy-webpack-plugin');
+const CopyPlugin = require("copy-webpack-plugin");
 
 module.exports = {
-    plugins: [
-        new CopyPlugin({
-            patterns: [
-                {
-                    from: require.resolve('zip-peek/zipServiceWorker.js'),
-                    to: 'zipServiceWorker.js',
-                },
-            ],
-        }),
-    ],
+  plugins: [
+    new CopyPlugin({
+      patterns: [
+        {
+          from: require.resolve("zip-peek/zipServiceWorker.js"),
+          to: "zipServiceWorker.js",
+        },
+      ],
+    }),
+  ],
 };
 ```
 
@@ -356,9 +366,8 @@ Then use:
 
 ```ts
 await initZipPeek({
-    zipUrl,
-    workerUrl: new URL('/zipServiceWorker.js', window.location.origin).href,
-    scopeUrl: new URL('/', window.location.origin).href,
+  workerUrl: new URL("/zipServiceWorker.js", window.location.origin).href,
+  scopeUrl: new URL("/", window.location.origin).href,
 });
 ```
 
@@ -379,7 +388,11 @@ zip-cache-v1
 
 Extracted assets expire after two hours by default. Set `assetCacheTtlMs` to customize this.
 
-When `purgeOtherZipAssets` is enabled, initializing one ZIP removes cached ZIP assets for other ZIP URLs in the same cache bucket to avoid taking too much cache size.
+Use `cacheClearingStrategy` to control initialization-time cleanup. `keep-all` leaves existing entries untouched, `keep-allowed-urls` removes cached ZIP data outside `allowedZipUrls`, and `clear-all` removes all zip-peek cached ZIP data before warming any allowed manifests.
+
+## Internal Flow
+
+For a detailed explanation of how the service worker intercepts requests, parses ZIP files, and handles caching, see the [Zip Service Worker Flow documentation](./docs/ZIP_SERVICE_WORKER_FLOW.md).
 
 ## Limitations
 

package/dist/index.d.ts

@@ -1,19 +1,15 @@
-import { ZipWorkerConfig } from './ZipStreamManager';
-import { isZipPackage } from './zip-utils';
-export type InitZipPeekOptions = {
-    zipUrl: string;
-    workerUrl: string;
-    scopeUrl: string;
-    reloadOnFirstInstall?: boolean;
-    purgeOtherZipAssets?: boolean;
-    zipAssetCacheName?: string;
-    assetCacheTtlMs?: number;
-    logPrefix?: string;
-};
-export type InitZipPeekResult = {
-    reloaded: boolean;
-    initialized: boolean;
-};
-export declare function initZipPeek({ zipUrl, workerUrl, scopeUrl, reloadOnFirstInstall, purgeOtherZipAssets, zipAssetCacheName, assetCacheTtlMs, logPrefix, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
+import type { InitZipPeekOptions, InitZipPeekResult } from "./types";
+import { isZipPackage } from "./zip-utils";
+export type { InitZipPeekOptions, InitZipPeekResult, ZipCacheClearingStrategy, ZipWorkerConfig, } from "./types";
+/**
+ * Registers the zip-peek service worker and configures lazy ZIP asset loading.
+ *
+ * By default, zip-peek serves any matching `.zip/...` request within the
+ * service worker scope by loading the ZIP manifest on first use. Pass
+ * `allowedZipUrls` to restrict serving to a known, non-empty set of ZIP
+ * package URLs and warm their manifests during initialization. Use
+ * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
+ * ZIP URLs, or clear all zip-peek cache entries before use.
+ */
+export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, cacheClearingStrategy, allowedZipUrls, zipAssetCacheName, assetCacheTtlMs, logPrefix, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
 export { isZipPackage };
-export type { ZipWorkerConfig };

package/dist/index.js

@@ -3,11 +3,67 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isZipPackage = void 0;
 exports.initZipPeek = initZipPeek;
 const registerZipServiceWorker_1 = require("./registerZipServiceWorker");
-const ZipStreamManager_1 = require("./ZipStreamManager");
 const zip_utils_1 = require("./zip-utils");
 Object.defineProperty(exports, "isZipPackage", { enumerable: true, get: function () { return zip_utils_1.isZipPackage; } });
-async function initZipPeek({ zipUrl, workerUrl, scopeUrl, reloadOnFirstInstall = true, purgeOtherZipAssets = true, zipAssetCacheName, assetCacheTtlMs, logPrefix, }) {
-    if (!(0, zip_utils_1.isZipPackage)(zipUrl)) {
+function normalizeAllowedZipUrls(allowedZipUrls) {
+    if (allowedZipUrls === undefined) {
+        return undefined;
+    }
+    if (allowedZipUrls.length === 0) {
+        throw new Error("zip-peek: allowedZipUrls must contain at least one ZIP URL when provided.");
+    }
+    const normalized = new Set();
+    for (const zipUrl of allowedZipUrls) {
+        const resolvedZipUrl = new URL(zipUrl, window.location.href).href;
+        if (!(0, zip_utils_1.isZipPackage)(resolvedZipUrl)) {
+            throw new Error(`zip-peek: allowedZipUrls contains a non-ZIP URL: ${zipUrl}`);
+        }
+        normalized.add((0, zip_utils_1.normalizeZipUrlForSw)(resolvedZipUrl));
+    }
+    return Array.from(normalized);
+}
+function postWorkerMessage(message) {
+    const controller = navigator.serviceWorker.controller;
+    if (!controller) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = (event) => {
+            const response = event.data;
+            channel.port1.close();
+            if (!response || response.ok) {
+                resolve();
+            }
+            else {
+                reject(new Error(response.error ?? "zip-peek: service worker message failed."));
+            }
+        };
+        channel.port1.onmessageerror = () => {
+            channel.port1.close();
+            reject(new Error("zip-peek: failed to receive service worker response."));
+        };
+        controller.postMessage(message, [channel.port2]);
+    });
+}
+/**
+ * Registers the zip-peek service worker and configures lazy ZIP asset loading.
+ *
+ * By default, zip-peek serves any matching `.zip/...` request within the
+ * service worker scope by loading the ZIP manifest on first use. Pass
+ * `allowedZipUrls` to restrict serving to a known, non-empty set of ZIP
+ * package URLs and warm their manifests during initialization. Use
+ * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
+ * ZIP URLs, or clear all zip-peek cache entries before use.
+ */
+async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, zipAssetCacheName, assetCacheTtlMs, logPrefix, }) {
+    const normalizedAllowedZipUrls = normalizeAllowedZipUrls(allowedZipUrls);
+    if (cacheClearingStrategy === "keep-allowed-urls" &&
+        !normalizedAllowedZipUrls) {
+        throw new Error('zip-peek: cacheClearingStrategy "keep-allowed-urls" requires a non-empty allowedZipUrls allow-list.');
+    }
+    if (!("serviceWorker" in navigator)) {
+        console.warn("zip-peek: Service Worker API not supported.");
         return { reloaded: false, initialized: false };
     }
     const reloaded = await (0, registerZipServiceWorker_1.ensureZipServiceWorkerRegistered)({
@@ -18,14 +74,41 @@ async function initZipPeek({ zipUrl, workerUrl, scopeUrl, reloadOnFirstInstall =
     if (reloaded) {
         return { reloaded: true, initialized: false };
     }
-    const workerConfig = {
-        zipAssetCacheName,
-        assetCacheTtlMs,
-        logPrefix,
-    };
-    await ZipStreamManager_1.ZipStreamManager.init(zipUrl, {
-        purgeOtherZipAssets,
-        workerConfig,
+    await postWorkerMessage({
+        type: "ZIP_SW_CONFIG",
+        config: {
+            zipAssetCacheName,
+            assetCacheTtlMs,
+            logPrefix,
+            allowedZipUrls: normalizedAllowedZipUrls ?? null,
+        },
     });
+    if (cacheClearingStrategy === "clear-all") {
+        await postWorkerMessage({
+            type: "CLEAR_ALL_ZIP_ASSETS",
+        });
+        await postWorkerMessage({
+            type: "ZIP_SW_CONFIG",
+            config: {
+                zipAssetCacheName,
+                assetCacheTtlMs,
+                logPrefix,
+                allowedZipUrls: normalizedAllowedZipUrls ?? null,
+            },
+        });
+    }
+    else if (cacheClearingStrategy === "keep-allowed-urls" &&
+        normalizedAllowedZipUrls) {
+        await postWorkerMessage({
+            type: "CLEAR_ZIP_ASSETS_EXCEPT_ALLOWED",
+            allowedZipUrls: normalizedAllowedZipUrls,
+        });
+    }
+    if (normalizedAllowedZipUrls) {
+        await postWorkerMessage({
+            type: "PRELOAD_ZIP_MANIFESTS",
+            allowedZipUrls: normalizedAllowedZipUrls,
+        });
+    }
     return { reloaded: false, initialized: true };
 }

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+export type ZipWorkerConfig = {
+    zipAssetCacheName?: string;
+    assetCacheTtlMs?: number;
+    logPrefix?: string;
+};
+export type ZipCacheClearingStrategy = 'keep-all' | 'keep-allowed-urls' | 'clear-all';
+export type InitZipPeekOptions = {
+    workerUrl: string;
+    scopeUrl: string;
+    reloadOnFirstInstall?: boolean;
+    cacheClearingStrategy?: ZipCacheClearingStrategy;
+    allowedZipUrls?: string[];
+    zipAssetCacheName?: string;
+    assetCacheTtlMs?: number;
+    logPrefix?: string;
+};
+export type InitZipPeekResult = {
+    reloaded: boolean;
+    initialized: boolean;
+};
+export type WorkerMessageResponse = {
+    ok: boolean;
+    error?: string;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/zip-utils.js

@@ -10,10 +10,10 @@ exports.canonicalZipAssetRequestUrl = canonicalZipAssetRequestUrl;
 function isZipPackage(url) {
     try {
         const u = new URL(url);
-        return u.pathname.endsWith('.zip');
+        return u.pathname.endsWith(".zip");
     }
     catch {
-        return url.split('?')[0].endsWith('.zip');
+        return url.split("?")[0].endsWith(".zip");
     }
 }
 /**
@@ -22,29 +22,31 @@ function isZipPackage(url) {
  * are not re-encoded.
  */
 function stripTParam(urlString) {
-    const qIdx = urlString.indexOf('?');
+    const qIdx = urlString.indexOf("?");
     if (qIdx === -1)
-        return urlString.split('#')[0];
-    const hashIdx = urlString.indexOf('#', qIdx);
+        return urlString.split("#")[0];
+    const hashIdx = urlString.indexOf("#", qIdx);
     const prefix = urlString.substring(0, qIdx);
-    const querySection = hashIdx === -1 ? urlString.substring(qIdx + 1) : urlString.substring(qIdx + 1, hashIdx);
-    const hashSection = hashIdx === -1 ? '' : urlString.substring(hashIdx);
-    const filtered = querySection.split('&').filter(p => {
-        const eqIdx = p.indexOf('=');
+    const querySection = hashIdx === -1
+        ? urlString.substring(qIdx + 1)
+        : urlString.substring(qIdx + 1, hashIdx);
+    const hashSection = hashIdx === -1 ? "" : urlString.substring(hashIdx);
+    const filtered = querySection.split("&").filter((p) => {
+        const eqIdx = p.indexOf("=");
         const k = eqIdx === -1 ? p : p.substring(0, eqIdx);
-        return k !== 't';
+        return k !== "t";
     });
     if (filtered.length === 0)
         return prefix + hashSection;
-    return prefix + '?' + filtered.join('&') + hashSection;
+    return prefix + "?" + filtered.join("&") + hashSection;
 }
 /** Same key the service worker uses for manifests / purge (presigned query kept). */
 exports.normalizeZipUrlForSw = stripTParam;
 /** Align zip entry names with URL paths under `*.zip/…`. */
 function normalizeZipEntryPath(name) {
-    let s = name.replace(/\\/g, '/');
-    while (s.startsWith('/'))
-        s = s.slice(1);
+    let s = name.replace(/\\/g, "/"); // Replace backslashes with forward slashes.
+    while (s.startsWith("/"))
+        s = s.slice(1); // Remove leading slashes.
     return s;
 }
 function safeDecodeSegment(s) {
@@ -68,26 +70,26 @@ function parseZipAssetRequest(urlString) {
     const match = /\.zip([/?])/.exec(urlString);
     if (!match)
         return null;
-    const sepIdx = match.index + 4;
+    const sepIdx = match.index + ".zip".length;
     const separator = match[1];
     const zipUrlBase = urlString.substring(0, sepIdx);
-    if (separator === '/') {
+    if (separator === "/") {
         const rest = urlString.substring(sepIdx + 1);
-        const qIdx = rest.indexOf('?');
+        const qIdx = rest.indexOf("?");
         const rawInternal = qIdx === -1 ? rest : rest.substring(0, qIdx);
-        if (rawInternal === '')
+        if (rawInternal === "")
             return null;
         return { zipUrl: zipUrlBase, internalPath: safeDecodeSegment(rawInternal) };
     }
     const afterZip = urlString.substring(sepIdx);
-    const slashIdx = afterZip.indexOf('/');
+    const slashIdx = afterZip.indexOf("/");
     if (slashIdx === -1)
         return null;
     const zipQueryPart = afterZip.substring(0, slashIdx);
     const afterSlash = afterZip.substring(slashIdx + 1);
-    const qIdx = afterSlash.indexOf('?');
+    const qIdx = afterSlash.indexOf("?");
     const rawInternal = qIdx === -1 ? afterSlash : afterSlash.substring(0, qIdx);
-    if (rawInternal === '')
+    if (rawInternal === "")
         return null;
     return {
         zipUrl: zipUrlBase + zipQueryPart,
@@ -96,5 +98,5 @@ function parseZipAssetRequest(urlString) {
 }
 /** Cache key for a zip asset (decoded manifest key + zip URL without `t`). */
 function canonicalZipAssetRequestUrl(zipUrl, manifestKey) {
-    return zipUrl + '/' + encodeURI(manifestKey);
+    return zipUrl + "/" + encodeURIComponent(manifestKey);
 }