@real-router/browser-plugin 0.8.0 → 0.9.0

package/src/plugin.ts

@@ -1,16 +1,15 @@
-import { RouterError } from "@real-router/core";
+import {
+  createPopstateHandler,
+  createPopstateLifecycle,
+  createStartInterceptor,
+  createReplaceHistoryState,
+  shouldReplaceHistory,
+  updateBrowserState,
+} from "browser-env";
 
-import { LOGGER_CONTEXT } from "./constants";
-import { getRouteFromEvent, updateBrowserState } from "./popstate-utils";
 import { buildUrl, urlToPath } from "./url-utils";
 
-import type {
-  Browser,
-  BrowserPluginOptions,
-  RegExpCache,
-  SharedFactoryState,
-  URLParseOptions,
-} from "./types";
+import type { BrowserPluginOptions } from "./types";
 import type {
   NavigationOptions,
   Params,
@@ -19,32 +18,20 @@ import type {
   State,
   Plugin,
 } from "@real-router/core";
+import type { Browser, SharedFactoryState } from "browser-env";
 
 export class BrowserPlugin {
   readonly #router: Router;
-  readonly #api: PluginApi;
-  readonly #options: BrowserPluginOptions;
   readonly #browser: Browser;
-  readonly #regExpCache: RegExpCache;
-  readonly #prefix: string;
-  readonly #transitionOptions: {
-    source: string;
-    replace: true;
-    forceDeactivate?: boolean;
-  };
-  readonly #shared: SharedFactoryState;
-
-  #isTransitioning = false;
-  #deferredPopstateEvent: PopStateEvent | null = null;
   readonly #removeStartInterceptor: () => void;
   readonly #removeExtensions: () => void;
+  readonly #lifecycle: Pick<Plugin, "onStart" | "onStop" | "teardown">;
 
   constructor(
     router: Router,
     api: PluginApi,
-    options: BrowserPluginOptions,
+    options: Required<BrowserPluginOptions>,
     browser: Browser,
-    regExpCache: RegExpCache,
     transitionOptions: {
       source: string;
       replace: true;
@@ -53,199 +40,79 @@ export class BrowserPlugin {
     shared: SharedFactoryState,
   ) {
     this.#router = router;
-    this.#api = api;
-    this.#options = options;
     this.#browser = browser;
-    this.#regExpCache = regExpCache;
-    this.#transitionOptions = transitionOptions;
-    this.#shared = shared;
-
-    const normalizedOptions = options as URLParseOptions;
 
-    this.#prefix = options.useHash ? `#${normalizedOptions.hashPrefix}` : "";
+    this.#removeStartInterceptor = createStartInterceptor(api, browser);
 
-    this.#removeStartInterceptor = this.#api.addInterceptor(
-      "start",
-      (next, path) => next(path ?? this.#browser.getLocation(this.#options)),
-    );
+    const pluginBuildUrl = (route: string, params?: Params) => {
+      const path = router.buildPath(route, params);
 
-    this.#removeExtensions = this.#api.extendRouter({
-      buildUrl: (route: string, params?: Params) => {
-        const path = this.#router.buildPath(route, params);
+      return buildUrl(path, options.base);
+    };
 
-        return buildUrl(
-          path,
-          (this.#options as URLParseOptions).base,
-          this.#prefix,
-        );
-      },
+    this.#removeExtensions = api.extendRouter({
+      buildUrl: pluginBuildUrl,
       matchUrl: (url: string) => {
-        const path = urlToPath(
-          url,
-          this.#options as URLParseOptions,
-          this.#regExpCache,
-        );
+        const path = urlToPath(url, options.base);
 
-        return path ? this.#api.matchPath(path) : undefined;
+        return path ? api.matchPath(path) : undefined;
       },
-      replaceHistoryState: (name: string, params: Params = {}) => {
-        const state = this.#api.buildState(name, params);
-
-        if (!state) {
-          throw new Error(
-            `[real-router] Cannot replace state: route "${name}" is not found`,
-          );
-        }
-
-        const builtState = this.#api.makeState(
-          state.name,
-          state.params,
-          this.#router.buildPath(state.name, state.params),
-          {
-            params: state.meta,
-          },
-          1, // forceId
-        );
-        const url = this.#router.buildUrl(name, params);
+      replaceHistoryState: createReplaceHistoryState(
+        api,
+        router,
+        browser,
+        pluginBuildUrl,
+      ),
+    });
+
+    const handler = createPopstateHandler({
+      router,
+      api,
+      browser,
+      transitionOptions,
+      loggerContext: "browser-plugin",
+      buildUrl: (name: string, params?: Params) =>
+        router.buildUrl(name, params),
+    });
 
-        updateBrowserState(builtState, url, true, this.#browser);
+    this.#lifecycle = createPopstateLifecycle({
+      browser,
+      shared,
+      handler,
+      cleanup: () => {
+        this.#removeStartInterceptor();
+        this.#removeExtensions();
       },
     });
   }
 
   getPlugin(): Plugin {
     return {
-      onStart: () => {
-        if (this.#shared.removePopStateListener) {
-          this.#shared.removePopStateListener();
-        }
-
-        this.#shared.removePopStateListener = this.#browser.addPopstateListener(
-          (evt: PopStateEvent) => void this.#onPopState(evt),
-        );
-      },
-
-      onStop: () => {
-        if (this.#shared.removePopStateListener) {
-          this.#shared.removePopStateListener();
-          this.#shared.removePopStateListener = undefined;
-        }
-      },
+      ...this.#lifecycle,
 
       onTransitionSuccess: (
         toState: State,
         fromState: State | undefined,
         navOptions: NavigationOptions,
       ) => {
-        const shouldReplaceHistory =
-          (navOptions.replace ?? !fromState) ||
-          (!!navOptions.reload &&
-            this.#router.areStatesEqual(toState, fromState, false));
+        const replaceHistory = shouldReplaceHistory(
+          navOptions,
+          toState,
+          fromState,
+          this.#router,
+        );
 
         const url = this.#router.buildUrl(toState.name, toState.params);
 
         const shouldPreserveHash =
-          !!this.#options.preserveHash &&
-          (!fromState || fromState.path === toState.path);
+          !fromState || fromState.path === toState.path;
 
         const finalUrl = shouldPreserveHash
           ? url + this.#browser.getHash()
           : url;
 
-        updateBrowserState(
-          toState,
-          finalUrl,
-          shouldReplaceHistory,
-          this.#browser,
-        );
-      },
-
-      teardown: () => {
-        if (this.#shared.removePopStateListener) {
-          this.#shared.removePopStateListener();
-          this.#shared.removePopStateListener = undefined;
-        }
-
-        this.#removeStartInterceptor();
-        this.#removeExtensions();
+        updateBrowserState(toState, finalUrl, replaceHistory, this.#browser);
       },
     };
   }
-
-  #processDeferredEvent(): void {
-    if (this.#deferredPopstateEvent) {
-      const event = this.#deferredPopstateEvent;
-
-      this.#deferredPopstateEvent = null;
-      console.warn(`[${LOGGER_CONTEXT}] Processing deferred popstate event`);
-      void this.#onPopState(event);
-    }
-  }
-
-  async #onPopState(evt: PopStateEvent): Promise<void> {
-    if (this.#isTransitioning) {
-      console.warn(
-        `[${LOGGER_CONTEXT}] Transition in progress, deferring popstate event`,
-      );
-      this.#deferredPopstateEvent = evt;
-
-      return;
-    }
-
-    this.#isTransitioning = true;
-
-    try {
-      const route = getRouteFromEvent(
-        evt,
-        this.#api,
-        this.#browser,
-        this.#options,
-      );
-
-      // eslint-disable-next-line unicorn/prefer-ternary
-      if (route) {
-        await this.#router.navigate(
-          route.name,
-          route.params,
-          this.#transitionOptions,
-        );
-      } else {
-        await this.#router.navigateToDefault({
-          ...this.#transitionOptions,
-          reload: true,
-          replace: true,
-        });
-      }
-    } catch (error) {
-      if (!(error instanceof RouterError)) {
-        this.#recoverFromCriticalError(error);
-      }
-    } finally {
-      this.#isTransitioning = false;
-      this.#processDeferredEvent();
-    }
-  }
-
-  #recoverFromCriticalError(error: unknown): void {
-    console.error(`[${LOGGER_CONTEXT}] Critical error in onPopState`, error);
-
-    try {
-      const currentState = this.#router.getState();
-
-      /* v8 ignore next -- @preserve: router always has state after start(); defensive guard for edge cases */
-      if (currentState) {
-        const url = this.#router.buildUrl(
-          currentState.name,
-          currentState.params,
-        );
-
-        this.#browser.replaceState(currentState, url);
-      }
-    } catch (recoveryError) {
-      console.error(
-        `[${LOGGER_CONTEXT}] Failed to recover from critical error`,
-        recoveryError,
-      );
-    }
-  }
 }

package/src/types.ts

@@ -1,11 +1,9 @@
 // packages/browser-plugin/src/types.ts
 
-import type { State } from "@real-router/core";
-
 /**
- * Common options shared between hash and history modes
+ * Browser plugin configuration.
  */
-interface BaseBrowserPluginOptions {
+export interface BrowserPluginOptions {
   /**
    * Force deactivation of current route even if canDeactivate returns false.
    *
@@ -20,178 +18,3 @@ interface BaseBrowserPluginOptions {
    */
   base?: string;
 }
-
-/**
- * Hash-based routing configuration.
- * Uses URL hash for navigation (e.g., example.com/#/path).
- *
- * @example
- * ```ts
- * // Standard hash routing
- * browserPluginFactory({ useHash: true })
- * // → example.com/#/users
- *
- * // Hash routing with prefix
- * browserPluginFactory({ useHash: true, hashPrefix: "!" })
- * // → example.com/#!/users
- * ```
- */
-export interface HashModeOptions extends BaseBrowserPluginOptions {
-  /**
-   * Enable hash-based routing
-   */
-  useHash: true;
-
-  /**
-   * Prefix for hash (e.g., "!" for "#!/path").
-   * Only valid when useHash is true.
-   *
-   * @default ""
-   */
-  hashPrefix?: string;
-
-  /**
-   * Not available in hash mode.
-   * Hash preservation only works with HTML5 History API.
-   * Use `useHash: false` to enable this option.
-   */
-  preserveHash?: never;
-}
-
-/**
- * HTML5 History API routing configuration.
- * Uses pushState/replaceState for navigation (e.g., example.com/path).
- *
- * @example
- * ```ts
- * // Standard history routing
- * browserPluginFactory({ useHash: false })
- * // → example.com/users
- *
- * // Preserve URL hash fragments
- * browserPluginFactory({ useHash: false, preserveHash: true })
- * // → example.com/users#section
- * ```
- */
-export interface HistoryModeOptions extends BaseBrowserPluginOptions {
-  /**
-   * Disable hash-based routing (use HTML5 History API)
-   *
-   * @default false
-   */
-  useHash?: false;
-
-  /**
-   * Preserve URL hash fragment on initial navigation.
-   * Only valid when useHash is false.
-   *
-   * @default true
-   */
-  preserveHash?: boolean;
-
-  /**
-   * Not available in history mode.
-   * Hash prefix only works with hash-based routing.
-   * Use `useHash: true` to enable this option.
-   */
-  hashPrefix?: never;
-}
-
-/**
- * Type-safe browser plugin configuration.
- *
- * Uses discriminated union to prevent conflicting options:
- * - Hash mode (useHash: true): allows hashPrefix, forbids preserveHash
- * - History mode (useHash: false): allows preserveHash, forbids hashPrefix
- *
- * @example
- * ```ts
- * // ✅ Valid: Hash mode with prefix
- * const config1: BrowserPluginOptions = {
- *   useHash: true,
- *   hashPrefix: "!"
- * };
- *
- * // ✅ Valid: History mode with hash preservation
- * const config2: BrowserPluginOptions = {
- *   useHash: false,
- *   preserveHash: true
- * };
- *
- * // ❌ Error: Cannot use preserveHash with hash mode
- * const config3: BrowserPluginOptions = {
- *   useHash: true,
- *   preserveHash: true  // Type error!
- * };
- *
- * // ❌ Error: Cannot use hashPrefix with history mode
- * const config4: BrowserPluginOptions = {
- *   useHash: false,
- *   hashPrefix: "!"  // Type error!
- * };
- * ```
- */
-export type BrowserPluginOptions = HashModeOptions | HistoryModeOptions;
-
-/**
- * Browser API abstraction for cross-environment compatibility.
- * Provides same interface in browser and SSR contexts.
- */
-export interface Browser {
-  /**
-   * Pushes new state to browser history
-   *
-   * @param state - History state object
-   * @param path - URL path
-   */
-  pushState: (state: State, path: string) => void;
-
-  /**
-   * Replaces current history state
-   *
-   * @param state - History state object
-   * @param path - URL path
-   */
-  replaceState: (state: State, path: string) => void;
-
-  addPopstateListener: (fn: (evt: PopStateEvent) => void) => () => void;
-
-  /**
-   * Gets current location path respecting plugin options
-   *
-   * @param opts - Plugin options
-   * @returns Current path string
-   */
-  getLocation: (opts: BrowserPluginOptions) => string;
-
-  /**
-   * Gets current URL hash
-   *
-   * @returns Hash string (including #)
-   */
-  getHash: () => string;
-}
-
-/**
- * Subset of BrowserPluginOptions needed for URL parsing operations.
- * Intentionally a flat interface (not a discriminated union) because this is an
- * internal type for pure functions — the calling code in plugin.ts already works
- * with validated BrowserPluginOptions and passes correct values.
- */
-export interface URLParseOptions {
-  readonly useHash: boolean;
-  readonly base: string;
-  readonly hashPrefix: string;
-}
-
-export interface RegExpCache {
-  get: (pattern: string) => RegExp;
-}
-
-/**
- * Shared mutable state across BrowserPlugin instances created by the same factory.
- * Enables cleanup of a previous instance's popstate listener when the factory is reused.
- */
-export interface SharedFactoryState {
-  removePopStateListener: (() => void) | undefined;
-}

package/src/url-utils.ts

@@ -1,43 +1,12 @@
 // packages/browser-plugin/src/url-utils.ts
 
-import { LOGGER_CONTEXT } from "./constants";
-
-import type { URLParseOptions, RegExpCache } from "./types";
-
-const escapeRegExpCache = new Map<string, string>();
-
-export const escapeRegExp = (str: string): string => {
-  const cached = escapeRegExpCache.get(str);
-
-  if (cached !== undefined) {
-    return cached;
-  }
+import { safeParseUrl } from "browser-env";
 
-  const escaped = str.replaceAll(/[$()*+.?[\\\]^{|}-]/g, String.raw`\$&`);
-
-  escapeRegExpCache.set(str, escaped);
-
-  return escaped;
-};
-
-export function extractPath(
-  pathname: string,
-  hash: string,
-  options: URLParseOptions,
-  regExpCache: RegExpCache,
-): string {
-  if (options.useHash) {
-    const escapedHashPrefix = escapeRegExp(options.hashPrefix);
-    const path = escapedHashPrefix
-      ? hash.replace(regExpCache.get(`^#${escapedHashPrefix}`), "")
-      : hash.slice(1);
-
-    return path || "/";
-  }
+import { LOGGER_CONTEXT } from "./constants";
 
-  if (options.base) {
-    const escapedBase = escapeRegExp(options.base);
-    const stripped = pathname.replace(regExpCache.get(`^${escapedBase}`), "");
+export function extractPath(pathname: string, base: string): string {
+  if (base && pathname.startsWith(base)) {
+    const stripped = pathname.slice(base.length);
 
     return stripped.startsWith("/") ? stripped : `/${stripped}`;
   }
@@ -45,51 +14,14 @@ export function extractPath(
   return pathname;
 }
 
-export function urlToPath(
-  url: string,
-  options: URLParseOptions,
-  regExpCache: RegExpCache,
-): string | null {
-  try {
-    const parsedUrl = new URL(url, globalThis.location.origin);
-
-    if (!["http:", "https:"].includes(parsedUrl.protocol)) {
-      console.warn(`[${LOGGER_CONTEXT}] Invalid URL protocol in ${url}`);
-
-      return null;
-    }
-
-    return (
-      extractPath(parsedUrl.pathname, parsedUrl.hash, options, regExpCache) +
-      parsedUrl.search
-    );
-  } catch (error) {
-    console.warn(`[${LOGGER_CONTEXT}] Could not parse url ${url}`, error);
-
-    return null;
-  }
+export function buildUrl(path: string, base: string): string {
+  return base + path;
 }
 
-export function buildUrl(path: string, base: string, prefix: string): string {
-  return base + prefix + path;
-}
-
-export function createRegExpCache(): RegExpCache {
-  const cache = new Map<string, RegExp>();
-
-  return {
-    get(pattern: string): RegExp {
-      const cached = cache.get(pattern);
-
-      if (cached !== undefined) {
-        return cached;
-      }
-
-      const newRegExp = new RegExp(pattern);
-
-      cache.set(pattern, newRegExp);
+export function urlToPath(url: string, base: string): string | null {
+  const parsedUrl = safeParseUrl(url, LOGGER_CONTEXT);
 
-      return newRegExp;
-    },
-  };
+  return parsedUrl
+    ? extractPath(parsedUrl.pathname, base) + parsedUrl.search
+    : null;
 }

package/src/validation.ts

@@ -1,66 +1,10 @@
-import { type DefaultBrowserPluginOptions, LOGGER_CONTEXT } from "./constants";
+import { createOptionsValidator } from "browser-env";
 
-import type { BrowserPluginOptions } from "./types";
-
-function isDefaultOptionKey(
-  key: string,
-  defaults: DefaultBrowserPluginOptions,
-): key is keyof DefaultBrowserPluginOptions {
-  return key in defaults;
-}
-
-function validateOptionType(
-  key: keyof DefaultBrowserPluginOptions,
-  value: unknown,
-  expectedType: string,
-): boolean {
-  const actualType = typeof value;
-
-  if (actualType !== expectedType && value !== undefined) {
-    console.warn(
-      `[${LOGGER_CONTEXT}] Invalid type for '${key}': expected ${expectedType}, got ${actualType}`,
-    );
-
-    return false;
-  }
-
-  return true;
-}
-
-export function validateOptions(
-  opts: Partial<BrowserPluginOptions> | undefined,
-  defaultOptions: DefaultBrowserPluginOptions,
-): boolean {
-  if (!opts) {
-    return false;
-  }
+import { LOGGER_CONTEXT, defaultOptions } from "./constants";
 
-  let hasInvalidTypes = false;
-
-  for (const key of Object.keys(opts)) {
-    if (isDefaultOptionKey(key, defaultOptions)) {
-      const expectedType = typeof defaultOptions[key];
-      const value = opts[key];
-      const isValid = validateOptionType(key, value, expectedType);
-
-      if (!isValid) {
-        hasInvalidTypes = true;
-      }
-    }
-  }
-
-  if (opts.useHash === true && "preserveHash" in opts) {
-    console.warn(`[${LOGGER_CONTEXT}] preserveHash ignored in hash mode`);
-  }
-
-  if (opts.useHash === false && "hashPrefix" in opts) {
-    const optsRecord = opts as unknown as Record<string, unknown>;
-    const hashPrefix = optsRecord.hashPrefix;
-
-    if (hashPrefix !== undefined && hashPrefix !== "") {
-      console.warn(`[${LOGGER_CONTEXT}] hashPrefix ignored in history mode`);
-    }
-  }
+import type { BrowserPluginOptions } from "./types";
 
-  return hasInvalidTypes;
-}
+export const validateOptions = createOptionsValidator<BrowserPluginOptions>(
+  defaultOptions,
+  LOGGER_CONTEXT,
+);