@ovineko/spa-guard 0.0.2-alpha-1 → 0.0.4

package/dist/index-DL8CfPXg.d.mts

@@ -0,0 +1,26 @@
+//#region src/i18n/translations.d.ts
+declare const translations: Record<string, SpaGuardTranslations>;
+//#endregion
+//#region src/i18n/index.d.ts
+interface SpaGuardTranslations {
+  heading: string;
+  loading: string;
+  message: string;
+  reload: string;
+  retrying: string;
+  rtl?: boolean;
+  tryAgain: string;
+}
+/**
+ * Match a language code or Accept-Language header against available translations.
+ *
+ * - If `input` is undefined, returns `"en"`.
+ * - If `input` contains `,` or `;q=`, it's parsed as an Accept-Language header
+ *   with quality values sorted descending.
+ * - Otherwise it's treated as a direct language code.
+ *
+ * Resolution: exact match → prefix match → `"en"` (or first available if `"en"` not in list).
+ */
+declare function matchLang(input: string | undefined, available?: string[]): string;
+//#endregion
+export { matchLang as n, translations as r, SpaGuardTranslations as t };

package/dist/index-rPxPv6iu.d.mts

@@ -0,0 +1,16 @@
+//#region src/schema/index.d.ts
+interface BeaconSchema {
+  appName?: string;
+  errorContext?: string;
+  errorMessage?: string;
+  errorType?: string;
+  eventMessage?: string;
+  eventName?: string;
+  httpStatus?: number;
+  retryAttempt?: number;
+  retryId?: string;
+  serialized?: string;
+  url?: string;
+}
+//#endregion
+export { BeaconSchema as t };

package/dist/logger-Cp1Eyk6S.mjs

@@ -0,0 +1,534 @@
+import { A as markInitialized, D as getLogger, I as staticAssetRecoveryKey, T as emitEvent, a as triggerRetry, c as shouldIgnoreMessages, g as getOptions, j as setLogger, k as isInitialized, m as getRetryInfoForBeacon, o as sendBeacon, s as shouldForceRetry } from "./retryOrchestrator-DNGIHV2M.mjs";
+//#region src/common/isChunkError.ts
+const isChunkError = (error) => {
+	const message = getErrorMessage(error);
+	if (!message) return false;
+	return [
+		/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
+	].some((pattern) => pattern.test(message));
+};
+const 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;
+};
+//#endregion
+//#region src/common/serializeError.ts
+const 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)
+		});
+	}
+};
+const MAX_DEPTH = 4;
+const MAX_KEYS = 20;
+const MAX_STRING_LEN = 500;
+const truncate = (str) => str.length > MAX_STRING_LEN ? str.slice(0, MAX_STRING_LEN) + "…" : str;
+const 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 ? truncate(error.stack) : void 0,
+		type: "Error",
+		...extractErrorProperties(error)
+	};
+	if ("reason" in error && "promise" in error) {
+		const evt = error;
+		const reason = evt.reason;
+		const pageUrl = typeof window !== "undefined" && typeof window.location?.href === "string" ? window.location.href : void 0;
+		return {
+			constructorName: reason?.constructor?.name,
+			isTrusted: evt.isTrusted,
+			pageUrl,
+			reason: serializeRejectionReason(reason, /* @__PURE__ */ new WeakSet(), 0),
+			timeStamp: evt.timeStamp,
+			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)
+	};
+};
+const serializeRejectionReason = (reason, visited, depth) => {
+	if (reason === null || reason === void 0) return {
+		type: "null",
+		value: reason
+	};
+	if (typeof reason !== "object") {
+		const val = typeof reason === "string" ? truncate(reason) : reason;
+		return {
+			type: typeof reason,
+			value: val
+		};
+	}
+	if (visited.has(reason)) return { type: "circular" };
+	visited.add(reason);
+	if (typeof AggregateError !== "undefined" && reason instanceof AggregateError) return {
+		errors: reason.errors.slice(0, 3).map((e) => serializeSafeError(e, visited, depth + 1)),
+		message: truncate(reason.message),
+		name: reason.name,
+		stack: reason.stack ? truncate(reason.stack) : void 0,
+		type: "Error"
+	};
+	if (typeof DOMException !== "undefined" && reason instanceof DOMException) return {
+		code: reason.code,
+		message: truncate(reason.message),
+		name: reason.name,
+		type: "Error"
+	};
+	const reasonObj = reason;
+	if (reasonObj.response != null) {
+		const response = reasonObj.response;
+		const result = { type: "HttpError" };
+		if (response.status !== void 0) result.status = response.status;
+		if (response.statusText !== void 0) result.statusText = typeof response.statusText === "string" ? truncate(response.statusText) : response.statusText;
+		if (response.url !== void 0) result.url = typeof response.url === "string" ? truncate(response.url) : response.url;
+		if (response.method !== void 0) result.method = response.method;
+		if (response.type !== void 0) result.responseType = response.type;
+		try {
+			const headers = response.headers;
+			if (headers) {
+				let xRequestId;
+				if (typeof headers.get === "function") xRequestId = headers.get("X-Request-ID") ?? headers.get("x-request-id");
+				else if (typeof headers === "object") xRequestId = headers["X-Request-ID"] ?? headers["x-request-id"];
+				if (xRequestId) result.xRequestId = truncate(String(xRequestId));
+			}
+		} catch {}
+		const reqSource = reasonObj.config ?? reasonObj.request;
+		if (reqSource != null) {
+			const req = {};
+			if (reqSource.method !== void 0) req.method = reqSource.method;
+			if (reqSource.url !== void 0) req.url = typeof reqSource.url === "string" ? truncate(reqSource.url) : reqSource.url;
+			if (reqSource.baseURL !== void 0) req.baseURL = typeof reqSource.baseURL === "string" ? truncate(reqSource.baseURL) : reqSource.baseURL;
+			result.request = req;
+		}
+		return result;
+	}
+	if (reason instanceof Error) return serializeSafeError(reason, visited, depth);
+	return {
+		type: "object",
+		value: extractBoundedObject(reasonObj, visited, depth)
+	};
+};
+const serializeSafeError = (error, visited, depth) => {
+	if (!(error instanceof Error)) return serializeRejectionReason(error, visited, depth + 1);
+	const result = {
+		message: truncate(error.message),
+		name: error.name,
+		stack: error.stack ? truncate(error.stack) : void 0,
+		type: "Error"
+	};
+	if (depth < MAX_DEPTH && error.cause !== void 0) {
+		const cause = error.cause;
+		if (typeof cause === "object" && cause !== null) {
+			if (!visited.has(cause)) result.cause = serializeRejectionReason(cause, visited, depth + 1);
+		} else result.cause = cause;
+	}
+	return result;
+};
+const extractBoundedObject = (obj, visited, depth) => {
+	const result = {};
+	let keyCount = 0;
+	for (const key of Object.keys(obj)) {
+		if (keyCount >= MAX_KEYS) break;
+		try {
+			const value = obj[key];
+			if (value === null || value === void 0 || typeof value !== "object") result[key] = typeof value === "string" ? truncate(value) : value;
+			else if (depth < MAX_DEPTH && !visited.has(value)) {
+				visited.add(value);
+				result[key] = extractBoundedObject(value, visited, depth + 1);
+			} else result[key] = "[object]";
+		} catch {}
+		keyCount++;
+	}
+	return result;
+};
+const extractErrorProperties = (error) => {
+	const props = {};
+	let keyCount = 0;
+	for (const key of Object.getOwnPropertyNames(error)) {
+		if (keyCount >= MAX_KEYS) break;
+		if (![
+			"message",
+			"name",
+			"stack"
+		].includes(key)) {
+			try {
+				const value = error[key];
+				if (value === null || value === void 0 || typeof value !== "object") props[key] = typeof value === "string" ? truncate(value) : value;
+				else props[key] = "[object]";
+			} catch {}
+			keyCount++;
+		}
+	}
+	return props;
+};
+const 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) };
+};
+const extractOwnProperties = (obj) => {
+	const props = {};
+	let keyCount = 0;
+	for (const key of Object.keys(obj)) {
+		if (keyCount >= MAX_KEYS) break;
+		try {
+			const value = obj[key];
+			if (value === null || value === void 0 || typeof value !== "object") props[key] = typeof value === "string" ? truncate(value) : value;
+			else props[key] = "[object]";
+		} catch {}
+		keyCount++;
+	}
+	return props;
+};
+//#endregion
+//#region src/common/isStaticAssetError.ts
+const HASHED_ASSET_RE = /[-._][a-zA-Z0-9]{6,}\.(js|mjs|css)$/i;
+const isHashedAssetUrl = (url) => {
+	try {
+		const pathname = new URL(url).pathname;
+		return HASHED_ASSET_RE.test(pathname);
+	} catch {
+		return HASHED_ASSET_RE.test(url);
+	}
+};
+const isStaticAssetError = (event) => {
+	const target = event.target;
+	if (target instanceof HTMLScriptElement) return isHashedAssetUrl(target.src);
+	if (target instanceof HTMLLinkElement) return isHashedAssetUrl(target.href);
+	return false;
+};
+const checkResourceStatus = (url) => {
+	if (typeof performance === "undefined" || typeof performance.getEntriesByName !== "function") return true;
+	const entries = performance.getEntriesByName(url, "resource");
+	if (entries.length === 0) return true;
+	const entry = entries.at(-1);
+	if (entry.responseStatus >= 400) return true;
+	if (entry.transferSize === 0 && entry.decodedBodySize === 0) return true;
+	return false;
+};
+const isLikely404 = (url, timeSinceNavMs) => {
+	if (url !== void 0) return checkResourceStatus(url);
+	return (timeSinceNavMs ?? (typeof performance === "undefined" ? 0 : performance.now())) > 3e4;
+};
+const getAssetUrl = (event) => {
+	const target = event.target;
+	if (target instanceof HTMLScriptElement) return target.src;
+	if (target instanceof HTMLLinkElement) return target.href;
+	return "";
+};
+//#endregion
+//#region src/common/staticAssetRecovery.ts
+const getState = () => {
+	if (globalThis.window === void 0) return {
+		failedAssets: /* @__PURE__ */ new Set(),
+		recoveryTimer: null
+	};
+	if (!globalThis.window[staticAssetRecoveryKey]) globalThis.window[staticAssetRecoveryKey] = {
+		failedAssets: /* @__PURE__ */ new Set(),
+		recoveryTimer: null
+	};
+	return globalThis.window[staticAssetRecoveryKey];
+};
+const handleStaticAssetFailure = (url) => {
+	if (globalThis.window === void 0) return;
+	const state = getState();
+	state.failedAssets.add(url);
+	if (state.recoveryTimer !== null) return;
+	const delay = getOptions().staticAssets?.recoveryDelay ?? 500;
+	state.recoveryTimer = setTimeout(() => {
+		const s = getState();
+		s.recoveryTimer = null;
+		const assets = [...s.failedAssets];
+		s.failedAssets = /* @__PURE__ */ new Set();
+		triggerRetry({
+			cacheBust: true,
+			error: /* @__PURE__ */ new Error(`Static asset load failed: ${assets.join(", ")}`),
+			source: "static-asset-error"
+		});
+	}, delay);
+};
+//#endregion
+//#region src/common/listen/internal.ts
+const listenInternal = (serializeError, logger) => {
+	if (globalThis.window === void 0) return;
+	if (isInitialized()) return;
+	if (logger) setLogger(logger);
+	markInitialized();
+	const wa = globalThis.window.addEventListener.bind(globalThis.window);
+	wa("error", (event) => {
+		const assetUrl = getAssetUrl(event);
+		if (isStaticAssetError(event) && isLikely404(assetUrl)) {
+			if (shouldIgnoreMessages([assetUrl, event.message])) return;
+			event.preventDefault();
+			emitEvent({
+				name: "static-asset-load-failed",
+				url: assetUrl
+			});
+			if (getOptions().staticAssets?.autoRecover !== false) handleStaticAssetFailure(assetUrl);
+			return;
+		}
+		if (shouldIgnoreMessages([event.message])) return;
+		getLogger()?.capturedError("error", event);
+		if (isChunkError(event)) {
+			event.preventDefault();
+			triggerRetry({
+				error: event.error ?? event,
+				source: "chunk-error"
+			});
+			return;
+		}
+		if (shouldForceRetry([event.message])) {
+			event.preventDefault();
+			triggerRetry({
+				error: event.error ?? event,
+				source: "force-retry"
+			});
+			return;
+		}
+		const serialized = serializeError(event);
+		sendBeacon({
+			errorMessage: event.message,
+			eventName: "error",
+			serialized,
+			...getRetryInfoForBeacon()
+		});
+	}, true);
+	wa("unhandledrejection", (event) => {
+		const errorMessage = String(event.reason);
+		if (shouldIgnoreMessages([errorMessage])) return;
+		getLogger()?.capturedError("unhandledrejection", event);
+		if (isChunkError(event.reason)) {
+			event.preventDefault();
+			triggerRetry({
+				error: event.reason,
+				source: "chunk-error"
+			});
+			return;
+		}
+		if (shouldForceRetry([errorMessage])) {
+			event.preventDefault();
+			triggerRetry({
+				error: event.reason,
+				source: "force-retry"
+			});
+			return;
+		}
+		const rejectionConfig = getOptions().handleUnhandledRejections;
+		if (rejectionConfig?.sendBeacon !== false) sendBeacon({
+			errorMessage,
+			eventName: "unhandledrejection",
+			serialized: serializeError(event),
+			...getRetryInfoForBeacon()
+		});
+		if (rejectionConfig?.retry !== false) {
+			event.preventDefault();
+			triggerRetry({
+				error: event.reason,
+				source: "unhandled-rejection"
+			});
+		}
+	});
+	wa("securitypolicyviolation", (event) => {
+		const eventMessage = `${event.violatedDirective}: ${event.blockedURI}`;
+		if (shouldIgnoreMessages([eventMessage])) return;
+		getLogger()?.capturedError("csp", event.blockedURI, event.violatedDirective);
+		sendBeacon({
+			eventMessage,
+			eventName: "securitypolicyviolation",
+			serialized: serializeError(event),
+			...getRetryInfoForBeacon()
+		});
+	});
+	wa("vite:preloadError", (event) => {
+		const payload = event?.payload;
+		if (shouldIgnoreMessages([payload?.message || event?.message])) return;
+		getLogger()?.capturedError("vite:preloadError", event);
+		event.preventDefault();
+		triggerRetry({
+			error: payload ?? event,
+			source: "vite:preloadError"
+		});
+	});
+};
+//#endregion
+//#region src/common/logger.ts
+const PREFIX = "[spa-guard]";
+const eventLogConfig = {
+	"chunk-error": "error",
+	"fallback-ui-not-rendered": "error",
+	"fallback-ui-shown": "warn",
+	"lazy-retry-attempt": "warn",
+	"lazy-retry-exhausted": "error",
+	"lazy-retry-start": "log",
+	"lazy-retry-success": "log",
+	"retry-attempt": "warn",
+	"retry-exhausted": "error",
+	"retry-reset": "log",
+	"static-asset-load-failed": "error"
+};
+const formatEvent = (event) => {
+	switch (event.name) {
+		case "chunk-error": return `${PREFIX} chunk-error: isRetrying=${event.isRetrying}`;
+		case "fallback-ui-not-rendered": {
+			const selectorPart = event.selector ? ` selector=${event.selector}` : "";
+			return `${PREFIX} fallback-ui-not-rendered: reason=${event.reason}${selectorPart}`;
+		}
+		case "fallback-ui-shown": return `${PREFIX} fallback-ui-shown`;
+		case "lazy-retry-attempt": return `${PREFIX} lazy-retry-attempt: attempt ${event.attempt}/${event.totalAttempts}, delay ${event.delay}ms`;
+		case "lazy-retry-exhausted": return `${PREFIX} lazy-retry-exhausted: ${event.totalAttempts} attempts, willReload=${event.willReload}`;
+		case "lazy-retry-start": return `${PREFIX} lazy-retry-start: totalAttempts=${event.totalAttempts}`;
+		case "lazy-retry-success": {
+			const timePart = event.totalTime === void 0 ? "" : `, totalTime=${event.totalTime}ms`;
+			return `${PREFIX} lazy-retry-success: succeeded on attempt ${event.attempt}${timePart}`;
+		}
+		case "retry-attempt": return `${PREFIX} retry-attempt: attempt ${event.attempt} in ${event.delay}ms (retryId: ${event.retryId})`;
+		case "retry-exhausted": return `${PREFIX} retry-exhausted: finalAttempt=${event.finalAttempt} (retryId: ${event.retryId})`;
+		case "retry-reset": return `${PREFIX} retry-reset: ${event.timeSinceReload}ms since last reload (retryId: ${event.previousRetryId})`;
+		case "static-asset-load-failed": return `${PREFIX} static-asset-load-failed: ${event.url}`;
+	}
+};
+const createLogger = () => ({
+	beaconSendFailed(error) {
+		console.error(`${PREFIX} Failed to send beacon:`, error);
+	},
+	capturedError(type, ...args) {
+		console.error(`${PREFIX} ${type}:capture:`, ...args);
+	},
+	error(msg, ...args) {
+		console.error(`${PREFIX} ${msg}`, ...args);
+	},
+	fallbackAlreadyShown(error) {
+		console.error(`${PREFIX} Fallback UI was already shown. Not retrying to prevent infinite loop.`, error);
+	},
+	fallbackInjectFailed(error) {
+		console.error(`${PREFIX} Failed to inject fallback UI`, error);
+	},
+	fallbackTargetNotFound(selector) {
+		console.error(`${PREFIX} Target element not found for selector: ${selector}`);
+	},
+	log(msg, ...args) {
+		console.log(`${PREFIX} ${msg}`, ...args);
+	},
+	logEvent(event) {
+		const level = eventLogConfig[event.name];
+		const message = formatEvent(event);
+		if (event.name === "chunk-error" || event.name === "lazy-retry-attempt" || event.name === "lazy-retry-exhausted") console[level](message, event.error);
+		else console[level](message);
+	},
+	noBeaconEndpoint() {
+		console.warn(`${PREFIX} Report endpoint is not configured`);
+	},
+	noFallbackConfigured() {
+		console.error(`${PREFIX} No fallback UI configured`);
+	},
+	reloadAlreadyScheduled(error) {
+		console.log(`${PREFIX} Reload already scheduled, ignoring duplicate chunk error:`, error);
+	},
+	retryCycleStarting(retryId, fromAttempt) {
+		console.log(`${PREFIX} Retry cycle starting: retryId=${retryId}, fromAttempt=${fromAttempt}`);
+	},
+	retrySchedulingReload(retryId, attempt, delay) {
+		console.log(`${PREFIX} Scheduling reload: retryId=${retryId}, attempt=${attempt}, delay=${delay}ms`);
+	},
+	versionChangeDetected(oldVersion, latestVersion) {
+		console.warn(`${PREFIX} New version available (${oldVersion ?? "unknown"} → ${latestVersion}). Please refresh to get the latest version.`);
+	},
+	versionCheckAlreadyRunning() {
+		console.warn(`${PREFIX} Version check already running`);
+	},
+	versionCheckDisabled() {
+		console.warn(`${PREFIX} Version checking disabled: no version configured`);
+	},
+	versionCheckFailed(error) {
+		console.error(`${PREFIX} Version check failed`, error);
+	},
+	versionCheckHttpError(status) {
+		console.warn(`${PREFIX} Version check HTTP error: ${status}`);
+	},
+	versionCheckParseError() {
+		console.warn(`${PREFIX} Failed to parse version from HTML`);
+	},
+	versionCheckPaused() {
+		console.log(`${PREFIX} Version check paused (tab hidden)`);
+	},
+	versionCheckRequiresEndpoint() {
+		console.warn(`${PREFIX} JSON version check mode requires endpoint`);
+	},
+	versionCheckResumed() {
+		console.log(`${PREFIX} Version check resumed (tab visible)`);
+	},
+	versionCheckResumedImmediate() {
+		console.log(`${PREFIX} Version check resumed with immediate check (tab visible, interval elapsed)`);
+	},
+	versionCheckStarted(mode, interval, version) {
+		console.log(`${PREFIX} Starting version check (mode: ${mode}, interval: ${interval}ms, current: ${version})`);
+	},
+	versionCheckStopped() {
+		console.log(`${PREFIX} Version check stopped`);
+	},
+	warn(msg, ...args) {
+		console.warn(`${PREFIX} ${msg}`, ...args);
+	}
+});
+//#endregion
+export { isChunkError as i, listenInternal as n, serializeError as r, createLogger as t };