vite-plugin-build-version-file 0.1.12 → 0.1.13

package/README.md

@@ -382,6 +382,30 @@ checkVersion()
 - 弹窗、通知、静默刷新等策略放在业务项目里
 - 请求失败后继续下一轮检查，避免一次失败中断流程
 
+## 刷新指定项目缓存
+
+```ts
+import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+
+await clearUrlCache('/vue-app/')
+```
+
+`url` 可省略；省略时默认使用当前 Vue 项目页面 URL：
+
+```ts
+await clearUrlCache()
+```
+
+Vue hash 路由会原样保留，缓存时间戳写在 `#` 前，确保服务器能够收到：
+
+```text
+https://cus.smarex.com.cn/pc/?_=随机值#/login?redirect=/dashboard/analysis
+```
+
+该方法仅支持同源 URL。它会绕过缓存请求 URL、强制刷新原 URL、通过隐藏 iframe 再次加载页面，最后携带随机时间戳跳转到该 URL。创建 iframe 前会销毁同一页面中已有的缓存刷新 iframe。单次请求或 iframe 加载失败不会阻断最终跳转。
+
+受浏览器限制，前端代码无法直接删除指定 URL 下的全部 HTTP 缓存；该方法只能尽可能刷新对应 Vue 项目的缓存。
+
 ## 开发态行为
 
 开发态下，插件不会向业务项目目录写入文件。
@@ -824,6 +848,30 @@ Recommendations:
 - Keep prompts, notifications, silent reloads, and retry rules in application code.
 - Continue polling after failed requests.
 
+## Refreshing a Project Cache
+
+```ts
+import { clearUrlCache } from 'vite-plugin-build-version-file/client'
+
+await clearUrlCache('/vue-app/')
+```
+
+The `url` argument is optional. When omitted, the current Vue project page URL is used:
+
+```ts
+await clearUrlCache()
+```
+
+Vue hash routes are preserved. The cache-busting timestamp is added before `#` so the server receives it:
+
+```text
+https://cus.smarex.com.cn/pc/?_=random-value#/login?redirect=/dashboard/analysis
+```
+
+This method only supports same-origin URLs. It bypasses the cached URL, forces a refresh of the original URL, loads the page again in a hidden iframe, and finally navigates to the URL with a random timestamp. Any existing cache-refresh iframe created by this method is removed before a new one is created. A failed request or iframe load does not prevent the final navigation.
+
+Browser code cannot directly delete every HTTP cache entry under a specific URL. This method refreshes the corresponding Vue application cache on a best-effort basis.
+
 ## Development Behavior
 
 In development, the plugin does not write files into your project directory.

package/dist/client.cjs

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  clearUrlCache: () => clearUrlCache
+});
+module.exports = __toCommonJS(client_exports);
+var CACHE_BUST_PARAM = "_";
+var IFRAME_ID = "vite-plugin-build-version-file-cache-iframe";
+var IFRAME_TIMEOUT = 5e3;
+function createCacheBustedUrl(url) {
+  const targetUrl = new URL(url, window.location.href);
+  const hash = targetUrl.hash;
+  targetUrl.hash = "";
+  targetUrl.searchParams.set(
+    CACHE_BUST_PARAM,
+    `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  targetUrl.hash = hash;
+  return targetUrl.href;
+}
+function loadIframe(url) {
+  return new Promise((resolve) => {
+    document.getElementById(IFRAME_ID)?.remove();
+    const iframe = document.createElement("iframe");
+    let completed = false;
+    const complete = () => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      window.clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = window.setTimeout(complete, IFRAME_TIMEOUT);
+    iframe.hidden = true;
+    iframe.id = IFRAME_ID;
+    iframe.addEventListener("load", complete, { once: true });
+    iframe.addEventListener("error", complete, { once: true });
+    iframe.src = url;
+    document.documentElement.appendChild(iframe);
+  });
+}
+async function clearUrlCache(url = window.location.href) {
+  const targetUrl = new URL(url, window.location.href).href;
+  await Promise.allSettled([
+    fetch(createCacheBustedUrl(targetUrl), { cache: "no-store" }).then(
+      (response) => response.arrayBuffer()
+    ),
+    fetch(targetUrl, { cache: "reload" }).then(
+      (response) => response.arrayBuffer()
+    )
+  ]);
+  try {
+    await loadIframe(createCacheBustedUrl(targetUrl));
+  } finally {
+    window.location.replace(createCacheBustedUrl(targetUrl));
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearUrlCache
+});

package/dist/client.d.cts

@@ -0,0 +1,3 @@
+declare function clearUrlCache(url?: string): Promise<void>;
+
+export { clearUrlCache };

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+declare function clearUrlCache(url?: string): Promise<void>;
+
+export { clearUrlCache };

package/dist/client.mjs

@@ -0,0 +1,56 @@
+// src/client.ts
+var CACHE_BUST_PARAM = "_";
+var IFRAME_ID = "vite-plugin-build-version-file-cache-iframe";
+var IFRAME_TIMEOUT = 5e3;
+function createCacheBustedUrl(url) {
+  const targetUrl = new URL(url, window.location.href);
+  const hash = targetUrl.hash;
+  targetUrl.hash = "";
+  targetUrl.searchParams.set(
+    CACHE_BUST_PARAM,
+    `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  targetUrl.hash = hash;
+  return targetUrl.href;
+}
+function loadIframe(url) {
+  return new Promise((resolve) => {
+    document.getElementById(IFRAME_ID)?.remove();
+    const iframe = document.createElement("iframe");
+    let completed = false;
+    const complete = () => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      window.clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = window.setTimeout(complete, IFRAME_TIMEOUT);
+    iframe.hidden = true;
+    iframe.id = IFRAME_ID;
+    iframe.addEventListener("load", complete, { once: true });
+    iframe.addEventListener("error", complete, { once: true });
+    iframe.src = url;
+    document.documentElement.appendChild(iframe);
+  });
+}
+async function clearUrlCache(url = window.location.href) {
+  const targetUrl = new URL(url, window.location.href).href;
+  await Promise.allSettled([
+    fetch(createCacheBustedUrl(targetUrl), { cache: "no-store" }).then(
+      (response) => response.arrayBuffer()
+    ),
+    fetch(targetUrl, { cache: "reload" }).then(
+      (response) => response.arrayBuffer()
+    )
+  ]);
+  try {
+    await loadIframe(createCacheBustedUrl(targetUrl));
+  } finally {
+    window.location.replace(createCacheBustedUrl(targetUrl));
+  }
+}
+export {
+  clearUrlCache
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-build-version-file",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "A Vite plugin that emits version.json and injects version metadata into HTML.",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.cjs"
     }
   },
   "files": [