zip-peek 0.2.0 → 0.2.2

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`;
 ```
 
@@ -63,22 +63,22 @@ npm install zip-peek
 ## Basic Usage
 
 ```ts
-import { initZipPeek } from 'zip-peek';
+import { initZipPeek } from "zip-peek";
 
 const zipPeekInit = await initZipPeek({
-    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:
@@ -93,25 +93,25 @@ The browser requests that URL normally. The service worker intercepts it and ser
 
 ```ts
 type InitZipPeekOptions = {
-    workerUrl: string;
-    scopeUrl: string;
-    reloadOnFirstInstall?: boolean;
-    cacheClearingStrategy?: ZipCacheClearingStrategy;
-    allowedZipUrls?: string[];
-    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';
+type ZipCacheClearingStrategy = "keep-all" | "keep-allowed-urls" | "clear-all";
 ```
 
 Returns:
 
 ```ts
 type InitZipPeekResult = {
-    reloaded: boolean;
-    initialized: boolean;
+  reloaded: boolean;
+  initialized: boolean;
 };
 ```
 
@@ -124,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
@@ -136,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.
@@ -160,17 +161,17 @@ Defaults to `'keep-all'`. Controls which zip-peek cache entries are cleared duri
 
 `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 rejects matching requests for ZIP URLs outside the list.
+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://cdn.example.com/packages/zipfile.zip"];
 allowedZipUrls: [
-    'https://d3jfe.cloudfront.net/somedir/zipfile.zip?Expires=1798761599&Signature=K2CJW4Z7B3DCM4&Key-Pair-Id=K2CJW4Z7B3DCM4',
-]
+  "https://d3jfe.cloudfront.net/somedir/zipfile.zip?Expires=1798761599&Signature=K2CJW4Z7B3DCM4&Key-Pair-Id=K2CJW4Z7B3DCM4",
+];
 ```
 
 `zipAssetCacheName`
@@ -190,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`
@@ -268,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/",
 });
 ```
 
@@ -300,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",
+        },
+      ],
+    }),
+  ],
 };
 ```
 
@@ -326,8 +327,11 @@ For example, after resolving the emitted filename:
 
 ```ts
 await initZipPeek({
-    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,
 });
 ```
 
@@ -342,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",
+        },
+      ],
+    }),
+  ],
 };
 ```
 
@@ -362,8 +366,8 @@ Then use:
 
 ```ts
 await initZipPeek({
-    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,
 });
 ```
 
@@ -386,6 +390,10 @@ Extracted assets expire after two hours by default. Set `assetCacheTtlMs` to cus
 
 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
 
 - The ZIP URL must end with `.zip`.

package/dist/index.d.ts

@@ -1,24 +1,6 @@
-import { isZipPackage } from './zip-utils';
-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;
-};
+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.
  *

package/dist/index.js

@@ -10,7 +10,7 @@ function normalizeAllowedZipUrls(allowedZipUrls) {
         return undefined;
     }
     if (allowedZipUrls.length === 0) {
-        throw new Error('zip-peek: allowedZipUrls must contain at least one ZIP URL when provided.');
+        throw new Error("zip-peek: allowedZipUrls must contain at least one ZIP URL when provided.");
     }
     const normalized = new Set();
     for (const zipUrl of allowedZipUrls) {
@@ -18,7 +18,7 @@ function normalizeAllowedZipUrls(allowedZipUrls) {
         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));
+        normalized.add((0, zip_utils_1.normalizeZipUrl)(resolvedZipUrl));
     }
     return Array.from(normalized);
 }
@@ -29,19 +29,19 @@ function postWorkerMessage(message) {
     }
     return new Promise((resolve, reject) => {
         const channel = new MessageChannel();
-        channel.port1.onmessage = event => {
+        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.'));
+                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.'));
+            reject(new Error("zip-peek: failed to receive service worker response."));
         };
         controller.postMessage(message, [channel.port2]);
     });
@@ -56,12 +56,14 @@ function postWorkerMessage(message) {
  * `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, }) {
+async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, zipAssetCacheName, assetCacheTtlMs, logPrefix, }) {
     const normalizedAllowedZipUrls = normalizeAllowedZipUrls(allowedZipUrls);
-    if (cacheClearingStrategy === 'keep-allowed-urls' && !normalizedAllowedZipUrls) {
+    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)) {
+    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)({
@@ -73,7 +75,7 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
         return { reloaded: true, initialized: false };
     }
     await postWorkerMessage({
-        type: 'ZIP_SW_CONFIG',
+        type: "ZIP_SW_CONFIG",
         config: {
             zipAssetCacheName,
             assetCacheTtlMs,
@@ -81,12 +83,12 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
             allowedZipUrls: normalizedAllowedZipUrls ?? null,
         },
     });
-    if (cacheClearingStrategy === 'clear-all') {
+    if (cacheClearingStrategy === "clear-all") {
         await postWorkerMessage({
-            type: 'CLEAR_ALL_ZIP_ASSETS',
+            type: "CLEAR_ALL_ZIP_ASSETS",
         });
         await postWorkerMessage({
-            type: 'ZIP_SW_CONFIG',
+            type: "ZIP_SW_CONFIG",
             config: {
                 zipAssetCacheName,
                 assetCacheTtlMs,
@@ -95,15 +97,16 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
             },
         });
     }
-    else if (cacheClearingStrategy === 'keep-allowed-urls' && normalizedAllowedZipUrls) {
+    else if (cacheClearingStrategy === "keep-allowed-urls" &&
+        normalizedAllowedZipUrls) {
         await postWorkerMessage({
-            type: 'CLEAR_ZIP_ASSETS_EXCEPT_ALLOWED',
+            type: "CLEAR_ZIP_ASSETS_EXCEPT_ALLOWED",
             allowedZipUrls: normalizedAllowedZipUrls,
         });
     }
     if (normalizedAllowedZipUrls) {
         await postWorkerMessage({
-            type: 'PRELOAD_ZIP_MANIFESTS',
+            type: "PRELOAD_ZIP_MANIFESTS",
             allowedZipUrls: normalizedAllowedZipUrls,
         });
     }

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.d.ts

@@ -1,13 +1,17 @@
 /** True when the URL points at a `.zip` package (path ends with `.zip`). */
 export declare function isZipPackage(url: string): boolean;
+export type NormalizeZipUrlOptions = {
+    /** Remove cache-buster `t` query param (default: true). */
+    stripCacheBuster?: boolean;
+    /** Drop fragment `#...` (default: true). */
+    stripHash?: boolean;
+};
 /**
- * Strip only the `t` cache-buster query param; keep everything else verbatim.
+ * Normalize a ZIP package URL for cache keys, allow-lists, and manifests.
  * Avoids `URL` / `URLSearchParams` so SigV4 values (e.g. `%2F` in credentials)
  * are not re-encoded.
  */
-export declare function stripTParam(urlString: string): string;
-/** Same key the service worker uses for manifests / purge (presigned query kept). */
-export declare const normalizeZipUrlForSw: typeof stripTParam;
+export declare function normalizeZipUrl(urlString: string, options?: NormalizeZipUrlOptions): string;
 /** Align zip entry names with URL paths under `*.zip/…`. */
 export declare function normalizeZipEntryPath(name: string): string;
 export type ParsedZipAssetRequest = {
@@ -24,5 +28,5 @@ export type ParsedZipAssetRequest = {
  * Returns `null` for bare `.zip` GETs (e.g. manifest bootstrap).
  */
 export declare function parseZipAssetRequest(urlString: string): ParsedZipAssetRequest | null;
-/** Cache key for a zip asset (decoded manifest key + zip URL without `t`). */
+/** Cache key for a zip asset (decoded manifest key + normalized zip URL). */
 export declare function canonicalZipAssetRequestUrl(zipUrl: string, manifestKey: string): string;

package/dist/zip-utils.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeZipUrlForSw = void 0;
 exports.isZipPackage = isZipPackage;
-exports.stripTParam = stripTParam;
+exports.normalizeZipUrl = normalizeZipUrl;
 exports.normalizeZipEntryPath = normalizeZipEntryPath;
 exports.parseZipAssetRequest = parseZipAssetRequest;
 exports.canonicalZipAssetRequestUrl = canonicalZipAssetRequestUrl;
@@ -10,41 +9,46 @@ 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");
     }
 }
 /**
- * Strip only the `t` cache-buster query param; keep everything else verbatim.
+ * Normalize a ZIP package URL for cache keys, allow-lists, and manifests.
  * Avoids `URL` / `URLSearchParams` so SigV4 values (e.g. `%2F` in credentials)
  * are not re-encoded.
  */
-function stripTParam(urlString) {
-    const qIdx = urlString.indexOf('?');
+function normalizeZipUrl(urlString, options = {}) {
+    const { stripCacheBuster = true, stripHash = true } = options;
+    const withoutHash = (url) => (stripHash ? url.split("#")[0] : url);
+    if (!stripCacheBuster) {
+        return withoutHash(urlString);
+    }
+    const qIdx = urlString.indexOf("?");
     if (qIdx === -1)
-        return urlString.split('#')[0];
-    const hashIdx = urlString.indexOf('#', qIdx);
+        return withoutHash(urlString);
+    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 = stripHash || 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,33 +72,33 @@ 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,
         internalPath: safeDecodeSegment(rawInternal),
     };
 }
-/** Cache key for a zip asset (decoded manifest key + zip URL without `t`). */
+/** Cache key for a zip asset (decoded manifest key + normalized zip URL). */
 function canonicalZipAssetRequestUrl(zipUrl, manifestKey) {
-    return zipUrl + '/' + encodeURI(manifestKey);
+    return zipUrl + "/" + encodeURIComponent(manifestKey);
 }