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

package/dist/retryOrchestrator-mn9XcIVu.d.mts

@@ -0,0 +1,257 @@
+import { g as UnsubscribeFn, h as SubscribeFn, r as SPAGuardEvent, t as EmitOptions } from "./types-DrN8pgyc.mjs";
+
+//#region src/common/constants.d.ts
+declare const optionsWindowKey = "__SPA_GUARD_OPTIONS__";
+declare const debugSyncErrorEventType = "spa-guard:debug-sync-error";
+//#endregion
+//#region src/common/logger.d.ts
+interface Logger {
+  beaconSendFailed(error: unknown): void;
+  capturedError(type: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  fallbackAlreadyShown(error: unknown): void;
+  fallbackInjectFailed(error: unknown): void;
+  fallbackTargetNotFound(selector: string): void;
+  log(msg: string, ...args: unknown[]): void;
+  logEvent(event: SPAGuardEvent): void;
+  noBeaconEndpoint(): void;
+  noFallbackConfigured(): void;
+  reloadAlreadyScheduled(error: unknown): void;
+  retryCycleStarting(retryId: string, fromAttempt: number): void;
+  retrySchedulingReload(retryId: string, attempt: number, delay: number): void;
+  versionChangeDetected(oldVersion: null | string, latestVersion: string): void;
+  versionCheckAlreadyRunning(): void;
+  versionCheckDisabled(): void;
+  versionCheckFailed(error: unknown): void;
+  versionCheckHttpError(status: number): void;
+  versionCheckParseError(): void;
+  versionCheckPaused(): void;
+  versionCheckRequiresEndpoint(): void;
+  versionCheckResumed(): void;
+  versionCheckResumedImmediate(): void;
+  versionCheckStarted(mode: string, interval: number, version: string): void;
+  versionCheckStopped(): void;
+  warn(msg: string, ...args: unknown[]): void;
+}
+declare const createLogger: () => Logger;
+//#endregion
+//#region src/common/events/internal.d.ts
+declare const emitEvent: (event: SPAGuardEvent, options?: EmitOptions) => void;
+declare const subscribe: (cb: SubscribeFn) => UnsubscribeFn;
+declare const disableDefaultRetry: () => void;
+declare const enableDefaultRetry: () => void;
+declare const isDefaultRetryEnabled: () => boolean;
+declare namespace options_d_exports {
+  export { Options, getOptions, optionsWindowKey };
+}
+interface Options {
+  /**
+   * Application name for beacon source identification.
+   * Useful in monorepo setups to identify which app sent the beacon.
+   */
+  appName?: string;
+  /**
+   * Configuration for proactive version checking to detect new deployments.
+   * When configured with a `version`, periodically polls to detect version changes
+   * and dispatches a `spa-guard:version-change` CustomEvent on the window.
+   */
+  checkVersion?: {
+    /**
+     * Cache mode for the fetch request used to check the version.
+     * - "no-store": Bypass the HTTP cache entirely (default).
+     * - "no-cache": Revalidate with the server before using cached response.
+     * @default "no-store"
+     */
+    cache?: "no-cache" | "no-store";
+    /**
+     * Endpoint URL for JSON mode version checking.
+     * Required when mode is "json".
+     */
+    endpoint?: string;
+    /**
+     * Polling interval in milliseconds.
+     * @default 300000
+     */
+    interval?: number;
+    /**
+     * Detection mode.
+     * - "html": Re-fetches the current page and parses the injected version from the HTML.
+     * - "json": Fetches a dedicated JSON endpoint.
+     * @default "html"
+     */
+    mode?: "html" | "json";
+    /**
+     * Behavior when a version change is detected.
+     * - "reload": Automatically calls location.reload() after dispatching the event.
+     * - "event": Only dispatches the spa-guard:version-change CustomEvent (no reload).
+     * @default "reload"
+     */
+    onUpdate?: "event" | "reload";
+  };
+  /**
+   * Enable automatic retry cycle reset when enough time has passed
+   * since the last reload. When true, if the user stays on a page longer
+   * than the retry delay, the next error will start a fresh retry cycle.
+   * @default true
+   */
+  enableRetryReset?: boolean;
+  /**
+   * Error filtering and retry configuration.
+   */
+  errors?: {
+    /**
+     * List of error message substrings that should trigger the retry/reload process,
+     * same as chunk load errors. Useful for custom errors that indicate a stale deployment.
+     * @default []
+     */
+    forceRetry?: string[];
+    /**
+     * List of error message substrings to ignore and not report.
+     * If error message contains any of these strings, it will be filtered out.
+     * @default []
+     */
+    ignore?: string[];
+  };
+  /**
+   * Controls behavior for regular unhandled promise rejections
+   * (those that are not chunk errors or ForceRetry errors).
+   * @default { retry: false, sendBeacon: true }
+   */
+  handleUnhandledRejections?: {
+    /**
+     * Whether to attempt a page reload on unhandled rejections.
+     * @default false
+     */
+    retry?: boolean;
+    /**
+     * Whether to send a beacon report on unhandled rejections.
+     * @default true
+     */
+    sendBeacon?: boolean;
+  };
+  html?: {
+    fallback?: {
+      /** Custom HTML to display when all reload attempts are exhausted */content?: string; /** CSS selector where the fallback HTML should be injected @default "body" */
+      selector?: string;
+    };
+    loading?: {
+      /** Custom HTML to display during the loading/retrying state */content?: string;
+    };
+    /**
+     * Spinner overlay configuration.
+     * Controls the full-page loading spinner injected by the Vite plugin
+     * and available via `showSpinner()`/`dismissSpinner()` at runtime.
+     */
+    spinner?: {
+      /**
+       * Overlay background color.
+       * Used as CSS variable fallback: var(--spa-guard-spinner-bg, <this value>).
+       * @default '#fff'
+       */
+      background?: string;
+      /**
+       * Custom spinner HTML (the spinner element only, no container/overlay).
+       * If not provided, uses the default SVG spinner.
+       */
+      content?: string;
+      /**
+       * Disable spinner entirely.
+       * No injection into body, showSpinner() is a no-op, Spinner returns null.
+       * @default false
+       */
+      disabled?: boolean;
+    };
+  };
+  /**
+   * Options for the lazyWithRetry module-level retry logic.
+   * Controls retry behaviour for dynamic imports before falling back to a full page reload.
+   */
+  lazyRetry?: {
+    /**
+     * Call triggerRetry() after all retry attempts for dynamic imports are exhausted.
+     * If true, triggers page reload logic after all retryDelays fail.
+     * If false, only throws the error to the error boundary without a reload.
+     * @default true
+     */
+    callReloadOnFailure?: boolean;
+    /**
+     * Array of delays in milliseconds for dynamic import retry attempts.
+     * Each element represents one retry attempt with the given delay.
+     * The number of elements determines the total number of retry attempts.
+     * @default [1000, 2000]
+     * @example [500, 1500, 3000] // 3 attempts: 500ms, 1.5s, 3s
+     */
+    retryDelays?: number[];
+  };
+  /**
+   * Minimum time in milliseconds between retry cycle resets.
+   * Prevents infinite reset loops by ensuring a reset can only happen
+   * if the previous reset was at least this many milliseconds ago.
+   * @default 5000 (5 seconds)
+   */
+  minTimeBetweenResets?: number;
+  /** @default [1000, 2000, 5000] */
+  reloadDelays?: number[];
+  reportBeacon?: {
+    endpoint?: string;
+  };
+  /**
+   * Configuration for automatic recovery from static asset 404 errors
+   * caused by deployment version mismatches.
+   */
+  staticAssets?: {
+    /**
+     * Automatically trigger a cache-busting reload when a hashed static asset
+     * fails to load and the page has been open long enough to suggest a stale deployment.
+     * @default true
+     */
+    autoRecover?: boolean;
+    /**
+     * Milliseconds to wait after the first failed asset before triggering the reload.
+     * Allows collecting multiple concurrent failures into a single reload.
+     * @default 500
+     */
+    recoveryDelay?: number;
+  };
+  /** @default true */
+  useRetryId?: boolean;
+  /**
+   * Current application version. Used by the version checker to detect new deployments.
+   * Automatically generated by the Vite plugin using `crypto.randomUUID()` if not explicitly provided.
+   */
+  version?: string;
+}
+declare const getOptions: () => Options;
+//#endregion
+//#region src/common/retryOrchestrator.d.ts
+type RetryPhase = "fallback" | "idle" | "scheduled";
+interface RetrySnapshot {
+  attempt: number;
+  lastSource?: string;
+  lastTriggerTime?: number;
+  phase: RetryPhase;
+  retryId: null | string;
+}
+interface TriggerInput {
+  cacheBust?: boolean;
+  error?: unknown;
+  source?: string;
+}
+type TriggerResult = {
+  reason: string;
+  status: "deduped";
+} | {
+  status: "accepted";
+} | {
+  status: "fallback";
+} | {
+  status: "internal-error";
+} | {
+  status: "retry-disabled";
+};
+declare const triggerRetry: (input?: TriggerInput) => TriggerResult;
+declare const markRetryHealthyBoot: () => void;
+declare const getRetrySnapshot: () => RetrySnapshot;
+declare const resetRetryOrchestratorForTests: () => void;
+//#endregion
+export { Logger as _, getRetrySnapshot as a, optionsWindowKey as b, triggerRetry as c, options_d_exports as d, disableDefaultRetry as f, subscribe as g, isDefaultRetryEnabled as h, TriggerResult as i, Options as l, enableDefaultRetry as m, RetrySnapshot as n, markRetryHealthyBoot as o, emitEvent as p, TriggerInput as r, resetRetryOrchestratorForTests as s, RetryPhase as t, getOptions as u, createLogger as v, debugSyncErrorEventType as y };

package/dist/runtime/debug/index.d.ts

@@ -1,3 +1,4 @@
+//#region src/runtime/debug/index.d.ts
 type Position = "bottom-left" | "bottom-right" | "top-left" | "top-right";
 /**
  * Creates a debug panel for spa-guard that displays state, events,
@@ -5,8 +6,9 @@ type Position = "bottom-left" | "bottom-right" | "top-left" | "top-right";
  *
  * Returns a cleanup function that removes the panel and unsubscribes all listeners.
  */
-export declare function createDebugger(options?: {
-    defaultOpen?: boolean;
-    position?: Position;
+declare function createDebugger(options?: {
+  defaultOpen?: boolean;
+  position?: Position;
 }): () => void;
-export {};
+//#endregion
+export { createDebugger };