@ovineko/spa-guard 0.0.1-alpha-1

package/dist/schema/parse.d.ts

@@ -0,0 +1,6 @@
+export declare const parseBeacon: (value: unknown) => {
+    errorMessage?: string | undefined;
+    eventMessage?: string | undefined;
+    eventName?: string | undefined;
+    serialized?: string | undefined;
+};

package/dist/schema/parse.js

@@ -0,0 +1,8 @@
+import {
+  parseBeacon
+} from "../chunk-BL4EG6R7.js";
+import "../chunk-XV2YCVOR.js";
+import "../chunk-MLKGABMK.js";
+export {
+  parseBeacon
+};

package/dist/vite-plugin/index.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "vite";
+import { type Options } from "../common/options";
+export interface VitePluginOptions extends Options {
+    trace?: boolean;
+}
+export declare const spaGuardVitePlugin: (options?: VitePluginOptions) => Plugin;

package/dist/vite-plugin/index.js

@@ -0,0 +1,38 @@
+import {
+  name,
+  optionsWindowKey
+} from "../chunk-VWV6L4Q2.js";
+import "../chunk-MLKGABMK.js";
+
+// src/vite-plugin/index.ts
+import fsPromise from "fs/promises";
+import path from "path";
+var getInlineScript = async (options) => {
+  const buildDir = options.trace ? "dist-inline-trace" : "dist-inline";
+  const script = await fsPromise.readFile(path.join(import.meta.dirname, `../${buildDir}/index.js`), "utf8").then((r) => r.trim());
+  return `window.${optionsWindowKey}=${JSON.stringify(options)};${script}`;
+};
+var spaGuardVitePlugin = (options = {}) => {
+  return {
+    name: `${name}/vite-plugin`,
+    transformIndexHtml: {
+      handler: async (html) => {
+        const inlineScript = await getInlineScript(options);
+        return {
+          html,
+          tags: [
+            {
+              children: inlineScript,
+              injectTo: "head-prepend",
+              tag: "script"
+            }
+          ]
+        };
+      },
+      order: "post"
+    }
+  };
+};
+export {
+  spaGuardVitePlugin
+};

package/dist-inline/index.js

@@ -0,0 +1 @@
+var e="@ovineko/spa-guard",r=Symbol.for(e+":event-subscribers"),t=(Symbol.for(e+":internal-config"),"spaGuardRetryId"),o="spaGuardRetryAttempt";globalThis.window&&!globalThis.window[r]&&(globalThis.window[r]=new Set);var n=globalThis.window?.[r]??new Set,i=e=>{let r=a(e);return!!r&&[/Failed to fetch dynamically imported module/i,/Importing a module script failed/i,/error loading dynamically imported module/i,/Unable to preload CSS/i,/Loading chunk \d+ failed/i,/Loading CSS chunk \d+ failed/i,/ChunkLoadError/i,/Failed to fetch/i,/NaN/i].some(e=>e.test(r))},a=e=>e instanceof Error?e.message:"string"==typeof e?e:e&&"object"==typeof e&&"message"in e?e.message+"":e&&"object"==typeof e&&"reason"in e?a(e.reason):null,l=e=>"[spa-guard] "+e,s={fallbackHtml:'<div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif"><div style="text-align:center"><h1>Something went wrong</h1><p>Please refresh the page to continue.</p><button onclick="location.reload()">Refresh Page</button></div></div>',reloadDelays:[1e3,2e3,5e3],useRetryId:!0},c=()=>{let e=globalThis.window?.__SPA_GUARD_OPTIONS__;return{...s,...e,reportBeacon:{...s.reportBeacon,...e?.reportBeacon}}},d=e=>{let r=c();if(!r.reportBeacon?.endpoint)return void console.warn(l("Report endpoint is not configured"));let t=JSON.stringify(e);"function"==typeof globalThis.window?.navigator.sendBeacon&&navigator.sendBeacon(r.reportBeacon.endpoint,t)||fetch(r.reportBeacon.endpoint,{body:t,keepalive:!0,method:"POST"}).catch(e=>{console.error(l("Failed to send beacon:"),e)})},u=e=>{let r=c(),n=r.reloadDelays??[1e3,2e3,5e3],i=r.useRetryId??!0,a=i?(()=>{try{let e=new URLSearchParams(window.location.search),r=e.get(t),n=e.get(o);return r&&n?{retryAttempt:parseInt(n,10),retryId:r}:null}catch{return null}})():null,s=a?a.retryAttempt:0;if(s>=n.length)return console.error(l("All reload attempts exhausted"),e),d({errorMessage:"Exceeded maximum reload attempts",eventName:"chunk_error_max_reloads",serialized:JSON.stringify({error:e+"",retryAttempt:s,retryId:a?.retryId})}),void m();let u=s+1,f=a?.retryId??(()=>{if(typeof crypto<"u"&&crypto.randomUUID)return crypto.randomUUID();if(typeof crypto<"u"&&crypto.getRandomValues){let e=new Uint32Array(2);return crypto.getRandomValues(e),`${Date.now()}-${e[0].toString(36)}${e[1].toString(36)}`}return`${Date.now()}-${Math.random().toString(36).slice(2,15)}`})(),p=n[s];console.warn(l(`Reload attempt ${u}/${n.length} in ${p}ms (retryId: ${f})`),e),setTimeout(()=>{if(i){let e=((e,r)=>{let n=new URL(window.location.href);return n.searchParams.set(t,e),n.searchParams.set(o,r+""),n.toString()})(f,u);window.location.href=e}else window.location.reload()},p)},m=()=>{let e=c().fallbackHtml;if(e)try{document.body.innerHTML=e}catch(e){console.error(l("Failed to inject fallback UI"),e)}else console.error(l("No fallback UI configured"))},f=e=>{try{let r=p(e);return JSON.stringify(r,null,2)}catch{return JSON.stringify({error:"Failed to serialize error",fallback:e+""})}},p=e=>{if(null==e)return{type:"null",value:e};if("object"!=typeof e)return{type:typeof e,value:e};if(e instanceof Error)return{message:e.message,name:e.name,stack:e.stack,type:"Error",...y(e)};if("reason"in e&&"promise"in e)return{reason:p(e.reason),type:"PromiseRejectionEvent"};if("error"in e&&"message"in e&&"filename"in e)return{colno:e.colno,error:p(e.error),filename:e.filename,lineno:e.lineno,message:e.message,type:"ErrorEvent"};if("violatedDirective"in e&&"blockedURI"in e){let r=e;return{blockedURI:r.blockedURI,columnNumber:r.columnNumber,effectiveDirective:r.effectiveDirective,lineNumber:r.lineNumber,originalPolicy:r.originalPolicy,sourceFile:r.sourceFile,type:"SecurityPolicyViolationEvent",violatedDirective:r.violatedDirective}}if("type"in e&&"target"in e){let r=e;return{eventType:r.type,target:g(r.target),timeStamp:r.timeStamp,type:"Event"}}return{type:"object",value:v(e)}},y=e=>{let r={};for(let t of Object.getOwnPropertyNames(e))if(!["message","name","stack"].includes(t))try{r[t]=e[t]}catch{}return r},g=e=>e?e instanceof HTMLElement?{className:e.className,href:e.href,id:e.id,src:e.src,tagName:e.tagName}:{type:e+""}:null,v=e=>{let r={};for(let t of Object.keys(e))try{let o=e[t];r[t]="object"==typeof o?o+"":o}catch{}return r};(()=>{(e=>{n.forEach(r=>r(e))})({name:"test"});let e=window.addEventListener;e("error",e=>{if(console.error(l("error:capture:"),e),i(e))return e.preventDefault(),void u(e);let r=f(e);d({errorMessage:e.message,eventName:"error",serialized:r})},!0),e("error",e=>{console.error(l("error:"),e)}),e("unhandledrejection",e=>{if(console.error(l("unhandledrejection:"),e),i(e.reason))return e.preventDefault(),void u(e.reason);let r=f(e);d({errorMessage:e.reason+"",eventName:"unhandledrejection",serialized:r})}),e("uncaughtException",e=>{console.error(l("uncaughtException:"),e);let r=f(e);d({eventName:"uncaughtException",serialized:r})}),e("securitypolicyviolation",e=>{console.error(l("CSP violation:"),e.blockedURI,e.violatedDirective);let r=f(e);d({eventMessage:`${e.violatedDirective}: ${e.blockedURI}`,eventName:"securitypolicyviolation",serialized:r})}),e("vite:preloadError",e=>{console.error(l("vite:preloadError:"),e),e.preventDefault(),u(e)})})();

package/dist-inline-trace/index.js

@@ -0,0 +1,360 @@
+// package.json
+var name = "@ovineko/spa-guard";
+
+// src/common/constants.ts
+var optionsWindowKey = "__SPA_GUARD_OPTIONS__";
+var eventSubscribersWindowKey = /* @__PURE__ */ Symbol.for(`${name}:event-subscribers`);
+var internalConfigWindowKey = /* @__PURE__ */ Symbol.for(`${name}:internal-config`);
+var RETRY_ID_PARAM = "spaGuardRetryId";
+var RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
+
+// src/common/events/internal.ts
+if (globalThis.window && !globalThis.window[eventSubscribersWindowKey]) {
+  globalThis.window[eventSubscribersWindowKey] = /* @__PURE__ */ new Set();
+}
+var subscribers = globalThis.window?.[eventSubscribersWindowKey] ?? /* @__PURE__ */ new Set();
+var emitEvent = (event) => {
+  subscribers.forEach((cb) => cb(event));
+};
+
+// src/common/isChunkError.ts
+var isChunkError = (error) => {
+  const message = getErrorMessage(error);
+  if (!message) {
+    return false;
+  }
+  const patterns = [
+    /Failed to fetch dynamically imported module/i,
+    /Importing a module script failed/i,
+    /error loading dynamically imported module/i,
+    /Unable to preload CSS/i,
+    /Loading chunk \d+ failed/i,
+    /Loading CSS chunk \d+ failed/i,
+    /ChunkLoadError/i,
+    /Failed to fetch/i,
+    /NaN/i
+  ];
+  return patterns.some((pattern) => pattern.test(message));
+};
+var getErrorMessage = (error) => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object" && "message" in error) {
+    return String(error.message);
+  }
+  if (error && typeof error === "object" && "reason" in error) {
+    return getErrorMessage(error.reason);
+  }
+  return null;
+};
+
+// src/common/log.ts
+var logMessage = (msg) => `[spa-guard] ${msg}`;
+
+// src/common/fallbackHtml.generated.ts
+var defaultFallbackHtml = `<div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif"><div style="text-align:center"><h1>Something went wrong</h1><p>Please refresh the page to continue.</p><button onclick="location.reload()">Refresh Page</button></div></div>`;
+
+// src/common/options.ts
+var defaultOptions = {
+  fallbackHtml: defaultFallbackHtml,
+  reloadDelays: [1e3, 2e3, 5e3],
+  useRetryId: true
+};
+var getOptions = () => {
+  const windowOptions = globalThis.window?.[optionsWindowKey];
+  return {
+    ...defaultOptions,
+    ...windowOptions,
+    reportBeacon: {
+      ...defaultOptions.reportBeacon,
+      ...windowOptions?.reportBeacon
+    }
+  };
+};
+
+// src/common/sendBeacon.ts
+var sendBeacon = (beacon) => {
+  const options = getOptions();
+  if (!options.reportBeacon?.endpoint) {
+    console.warn(logMessage("Report endpoint is not configured"));
+    return;
+  }
+  const body = JSON.stringify(beacon);
+  const isSendBeaconAvailable = typeof globalThis.window?.navigator.sendBeacon === "function";
+  const isSentBeacon = isSendBeaconAvailable && navigator.sendBeacon(options.reportBeacon.endpoint, body);
+  if (!isSentBeacon) {
+    fetch(options.reportBeacon.endpoint, { body, keepalive: true, method: "POST" }).catch(
+      (error) => {
+        console.error(logMessage("Failed to send beacon:"), error);
+      }
+    );
+  }
+};
+
+// src/common/reload.ts
+var getRetryStateFromUrl = () => {
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const retryId = params.get(RETRY_ID_PARAM);
+    const retryAttempt = params.get(RETRY_ATTEMPT_PARAM);
+    if (retryId && retryAttempt) {
+      return {
+        retryAttempt: parseInt(retryAttempt, 10),
+        retryId
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+var generateRetryId = () => {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    const array = new Uint32Array(2);
+    crypto.getRandomValues(array);
+    return `${Date.now()}-${array[0].toString(36)}${array[1].toString(36)}`;
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 15)}`;
+};
+var buildReloadUrl = (retryId, retryAttempt) => {
+  const url = new URL(window.location.href);
+  url.searchParams.set(RETRY_ID_PARAM, retryId);
+  url.searchParams.set(RETRY_ATTEMPT_PARAM, String(retryAttempt));
+  return url.toString();
+};
+var attemptReload = (error) => {
+  const options = getOptions();
+  const reloadDelays = options.reloadDelays ?? [1e3, 2e3, 5e3];
+  const useRetryId = options.useRetryId ?? true;
+  const retryState = useRetryId ? getRetryStateFromUrl() : null;
+  const currentAttempt = retryState ? retryState.retryAttempt : 0;
+  if (currentAttempt >= reloadDelays.length) {
+    console.error(logMessage("All reload attempts exhausted"), error);
+    sendBeacon({
+      errorMessage: "Exceeded maximum reload attempts",
+      eventName: "chunk_error_max_reloads",
+      serialized: JSON.stringify({
+        error: String(error),
+        retryAttempt: currentAttempt,
+        retryId: retryState?.retryId
+      })
+    });
+    showFallbackUI();
+    return;
+  }
+  const nextAttempt = currentAttempt + 1;
+  const retryId = retryState?.retryId ?? generateRetryId();
+  const delay = reloadDelays[currentAttempt];
+  console.warn(
+    logMessage(
+      `Reload attempt ${nextAttempt}/${reloadDelays.length} in ${delay}ms (retryId: ${retryId})`
+    ),
+    error
+  );
+  setTimeout(() => {
+    if (useRetryId) {
+      const reloadUrl = buildReloadUrl(retryId, nextAttempt);
+      window.location.href = reloadUrl;
+    } else {
+      window.location.reload();
+    }
+  }, delay);
+};
+var showFallbackUI = () => {
+  const options = getOptions();
+  const fallbackHtml = options.fallbackHtml;
+  if (!fallbackHtml) {
+    console.error(logMessage("No fallback UI configured"));
+    return;
+  }
+  try {
+    document.body.innerHTML = fallbackHtml;
+  } catch (error) {
+    console.error(logMessage("Failed to inject fallback UI"), error);
+  }
+};
+
+// src/common/serializeError.ts
+var serializeError = (error) => {
+  try {
+    const serialized = serializeErrorInternal(error);
+    return JSON.stringify(serialized, null, 2);
+  } catch {
+    return JSON.stringify({
+      error: "Failed to serialize error",
+      fallback: String(error)
+    });
+  }
+};
+var serializeErrorInternal = (error) => {
+  if (error === null || error === void 0) {
+    return { type: "null", value: error };
+  }
+  if (typeof error !== "object") {
+    return { type: typeof error, value: error };
+  }
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      name: error.name,
+      stack: error.stack,
+      type: "Error",
+      ...extractErrorProperties(error)
+    };
+  }
+  if ("reason" in error && "promise" in error) {
+    return {
+      reason: serializeErrorInternal(error.reason),
+      type: "PromiseRejectionEvent"
+    };
+  }
+  if ("error" in error && "message" in error && "filename" in error) {
+    return {
+      colno: error.colno,
+      error: serializeErrorInternal(error.error),
+      filename: error.filename,
+      lineno: error.lineno,
+      message: error.message,
+      type: "ErrorEvent"
+    };
+  }
+  if ("violatedDirective" in error && "blockedURI" in error) {
+    const evt = error;
+    return {
+      blockedURI: evt.blockedURI,
+      columnNumber: evt.columnNumber,
+      effectiveDirective: evt.effectiveDirective,
+      lineNumber: evt.lineNumber,
+      originalPolicy: evt.originalPolicy,
+      sourceFile: evt.sourceFile,
+      type: "SecurityPolicyViolationEvent",
+      violatedDirective: evt.violatedDirective
+    };
+  }
+  if ("type" in error && "target" in error) {
+    const evt = error;
+    return {
+      eventType: evt.type,
+      target: extractEventTarget(evt.target),
+      timeStamp: evt.timeStamp,
+      type: "Event"
+    };
+  }
+  return {
+    type: "object",
+    value: extractOwnProperties(error)
+  };
+};
+var extractErrorProperties = (error) => {
+  const props = {};
+  for (const key of Object.getOwnPropertyNames(error)) {
+    if (!["message", "name", "stack"].includes(key)) {
+      try {
+        props[key] = error[key];
+      } catch {
+      }
+    }
+  }
+  return props;
+};
+var extractEventTarget = (target) => {
+  if (!target) {
+    return null;
+  }
+  if (target instanceof HTMLElement) {
+    return {
+      className: target.className,
+      href: target.href,
+      id: target.id,
+      src: target.src,
+      tagName: target.tagName
+    };
+  }
+  return { type: String(target) };
+};
+var extractOwnProperties = (obj) => {
+  const props = {};
+  for (const key of Object.keys(obj)) {
+    try {
+      const value = obj[key];
+      props[key] = typeof value === "object" ? String(value) : value;
+    } catch {
+    }
+  }
+  return props;
+};
+
+// src/common/listen/internal.ts
+var listenInternal = () => {
+  emitEvent({ name: "test" });
+  const wa = window.addEventListener;
+  wa(
+    "error",
+    (event) => {
+      console.error(logMessage("error:capture:"), event);
+      if (isChunkError(event)) {
+        event.preventDefault();
+        attemptReload(event);
+        return;
+      }
+      const serialized = serializeError(event);
+      sendBeacon({
+        errorMessage: event.message,
+        eventName: "error",
+        serialized
+      });
+    },
+    true
+  );
+  wa("error", (event) => {
+    console.error(logMessage("error:"), event);
+  });
+  wa("unhandledrejection", (event) => {
+    console.error(logMessage("unhandledrejection:"), event);
+    if (isChunkError(event.reason)) {
+      event.preventDefault();
+      attemptReload(event.reason);
+      return;
+    }
+    const serialized = serializeError(event);
+    sendBeacon({
+      errorMessage: String(event.reason),
+      eventName: "unhandledrejection",
+      serialized
+    });
+  });
+  wa("uncaughtException", (event) => {
+    console.error(logMessage("uncaughtException:"), event);
+    const serialized = serializeError(event);
+    sendBeacon({
+      eventName: "uncaughtException",
+      serialized
+    });
+  });
+  wa("securitypolicyviolation", (event) => {
+    console.error(logMessage("CSP violation:"), event.blockedURI, event.violatedDirective);
+    const serialized = serializeError(event);
+    sendBeacon({
+      eventMessage: `${event.violatedDirective}: ${event.blockedURI}`,
+      eventName: "securitypolicyviolation",
+      serialized
+    });
+  });
+  wa("vite:preloadError", (event) => {
+    console.error(logMessage("vite:preloadError:"), event);
+    event.preventDefault();
+    attemptReload(event);
+  });
+};
+
+// src/inline/index.ts
+(() => {
+  listenInternal();
+})();

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@ovineko/spa-guard",
+  "version": "0.0.1-alpha-1",
+  "description": "Chunk load error handling for SPAs with automatic recovery, beacon reporting, and deployment monitoring",
+  "keywords": [
+    "spa",
+    "chunk-load-error",
+    "vite",
+    "react",
+    "react-router",
+    "error-handling",
+    "error-boundary",
+    "deployment",
+    "beacon",
+    "monitoring",
+    "fastify",
+    "chunk",
+    "preload",
+    "dynamic-import"
+  ],
+  "homepage": "https://github.com/ovineko/ovineko/tree/main/packages/spa-guard",
+  "bugs": {
+    "url": "https://github.com/ovineko/ovineko/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ovineko/ovineko.git",
+    "directory": "packages/spa-guard"
+  },
+  "license": "MIT",
+  "author": "Alexander Svinarev <shibanet0@gmail.com> (shibanet0.com)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/common/index.d.ts",
+      "default": "./dist/common/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "default": "./dist/schema/index.js"
+    },
+    "./schema/parse": {
+      "types": "./dist/schema/parse.d.ts",
+      "default": "./dist/schema/parse.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./react-router": {
+      "types": "./dist/react-router/index.d.ts",
+      "default": "./dist/react-router/index.js"
+    },
+    "./fastify": {
+      "types": "./dist/fastify/index.d.ts",
+      "default": "./dist/fastify/index.js"
+    },
+    "./vite-plugin": {
+      "types": "./dist/vite-plugin/index.d.ts",
+      "default": "./dist/vite-plugin/index.js"
+    },
+    "./react-error-boundary": {
+      "types": "./dist/react-error-boundary/index.d.ts",
+      "default": "./dist/react-error-boundary/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "dist-inline",
+    "dist-inline-trace",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": "^19",
+    "react-error-boundary": "^6",
+    "react-router": "^7",
+    "typebox": "^1",
+    "vite": "^8 || ^7"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}