@real-router/browser-plugin 0.6.3 → 0.7.0

package/src/popstate-utils.ts

@@ -0,0 +1,60 @@
+import { isStateStrict as isState } from "type-guards";
+
+import type { BrowserPluginOptions, Browser } from "./types";
+import type { PluginApi, State, Params } from "@real-router/core";
+
+/**
+ * Extracts route name and params from a popstate event.
+ *
+ * - If history.state is a valid router state → returns name/params from it
+ * - If not (e.g. manually entered URL) → matches current URL against route tree
+ * - Returns undefined if no route matches
+ *
+ * @param evt - PopStateEvent from browser
+ * @param api - PluginApi instance
+ * @param browser - Browser API instance
+ * @param options - Browser plugin options
+ * @returns Route identifier or undefined
+ */
+export function getRouteFromEvent(
+  evt: PopStateEvent,
+  api: PluginApi,
+  browser: Browser,
+  options: BrowserPluginOptions,
+): { name: string; params: Params } | undefined {
+  if (isState(evt.state)) {
+    return { name: evt.state.name, params: evt.state.params };
+  }
+
+  const state = api.matchPath(browser.getLocation(options));
+
+  return state ? { name: state.name, params: state.params } : undefined;
+}
+
+/**
+ * Updates browser state (pushState or replaceState)
+ *
+ * @param state - Router state
+ * @param url - URL to set
+ * @param replace - Whether to replace instead of push
+ * @param browser - Browser API instance
+ */
+export function updateBrowserState(
+  state: State,
+  url: string,
+  replace: boolean,
+  browser: Browser,
+): void {
+  const historyState = {
+    meta: state.meta,
+    name: state.name,
+    params: state.params,
+    path: state.path,
+  };
+
+  if (replace) {
+    browser.replaceState(historyState, url);
+  } else {
+    browser.pushState(historyState, url);
+  }
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-// packages/browser-plugin/modules/types.ts
+// packages/browser-plugin/src/types.ts
 
 import type { State } from "@real-router/core";
 
@@ -19,14 +19,6 @@ interface BaseBrowserPluginOptions {
    * @default ""
    */
   base?: string;
-
-  /**
-   * Merge new state with existing history.state when updating.
-   * Useful for preserving external state set by other code.
-   *
-   * @default false
-   */
-  mergeState?: boolean;
 }
 
 /**
@@ -146,51 +138,23 @@ export type BrowserPluginOptions = HashModeOptions | HistoryModeOptions;
  * Provides same interface in browser and SSR contexts.
  */
 export interface Browser {
-  /**
-   * Gets base path from current browser location
-   *
-   * @returns Current pathname
-   */
-  getBase: () => string;
-
   /**
    * Pushes new state to browser history
    *
    * @param state - History state object
-   * @param title - Document title (usually ignored by browsers)
    * @param path - URL path
    */
-  pushState: (state: HistoryState, title: string | null, path: string) => void;
+  pushState: (state: State, path: string) => void;
 
   /**
    * Replaces current history state
    *
    * @param state - History state object
-   * @param title - Document title (usually ignored by browsers)
    * @param path - URL path
    */
-  replaceState: (
-    state: HistoryState,
-    title: string | null,
-    path: string,
-  ) => void;
+  replaceState: (state: State, path: string) => void;
 
-  /**
-   * Adds popstate/hashchange event listeners.
-   * Overloaded to support both PopStateEvent and HashChangeEvent.
-   *
-   * @param fn - Event handler
-   * @param opts - Plugin options
-   * @returns Cleanup function to remove listeners
-   */
-  addPopstateListener: ((
-    fn: (evt: PopStateEvent) => void,
-    opts: BrowserPluginOptions,
-  ) => () => void) &
-    ((
-      fn: (evt: HashChangeEvent) => void,
-      opts: BrowserPluginOptions,
-    ) => () => void);
+  addPopstateListener: (fn: (evt: PopStateEvent) => void) => () => void;
 
   /**
    * Gets current location path respecting plugin options
@@ -200,13 +164,6 @@ export interface Browser {
    */
   getLocation: (opts: BrowserPluginOptions) => string;
 
-  /**
-   * Gets current history state with validation
-   *
-   * @returns Valid history state or undefined
-   */
-  getState: () => HistoryState | undefined;
-
   /**
    * Gets current URL hash
    *
@@ -216,7 +173,25 @@ export interface Browser {
 }
 
 /**
- * History state object stored in browser history.
- * Extends real-router State with additional properties that may be set by external code.
+ * 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 type HistoryState = State & Record<string, unknown>;
+export interface SharedFactoryState {
+  removePopStateListener: (() => void) | undefined;
+}

package/src/url-utils.ts

@@ -0,0 +1,95 @@
+// 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;
+  }
+
+  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 || "/";
+  }
+
+  if (options.base) {
+    const escapedBase = escapeRegExp(options.base);
+    const stripped = pathname.replace(regExpCache.get(`^${escapedBase}`), "");
+
+    return stripped.startsWith("/") ? stripped : `/${stripped}`;
+  }
+
+  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, 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);
+
+      return newRegExp;
+    },
+  };
+}

package/src/validation.ts

@@ -0,0 +1,66 @@
+import { type DefaultBrowserPluginOptions, LOGGER_CONTEXT } from "./constants";
+
+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;
+  }
+
+  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`);
+    }
+  }
+
+  return hasInvalidTypes;
+}

package/src/utils.ts

@@ -1,294 +0,0 @@
-// packages/browser-plugin/modules/utils.ts
-
-import { errorCodes } from "@real-router/core";
-import { isStateStrict as isState } from "type-guards";
-
-import { type DefaultBrowserPluginOptions, LOGGER_CONTEXT } from "./constants";
-
-import type { BrowserPluginOptions, HistoryState, Browser } from "./types";
-import type {
-  PluginApi,
-  Router,
-  NavigationOptions,
-  RouterError,
-  State,
-} from "@real-router/core";
-
-/**
- * No-op function for default callbacks
- */
-export const noop = (): void => undefined;
-
-/**
- * Cache for escaped RegExp strings
- */
-const escapeRegExpCache = new Map<string, string>();
-
-/**
- * Escapes special RegExp characters in a string.
- * Used to safely build RegExp from user-provided strings (hashPrefix, base).
- *
- * @param str - String to escape
- * @returns Escaped string safe for RegExp construction
- */
-export const escapeRegExp = (str: string): string => {
-  const cached = escapeRegExpCache.get(str);
-
-  if (cached !== undefined) {
-    return cached;
-  }
-
-  const escaped = str.replaceAll(/[$()*+.?[\\\]^{|}-]/g, String.raw`\$&`);
-
-  escapeRegExpCache.set(str, escaped);
-
-  return escaped;
-};
-
-/**
- * Creates state from popstate event
- *
- * @param evt - PopStateEvent from browser
- * @param api - PluginApi instance
- * @param browser - Browser API instance
- * @param options - Browser plugin options
- * @returns Router state or undefined
- */
-export function createStateFromEvent(
-  evt: PopStateEvent,
-  api: PluginApi,
-  browser: Browser,
-  options: BrowserPluginOptions,
-): State | undefined {
-  const isNewState = !isState(evt.state);
-
-  if (isNewState) {
-    return api.matchPath(browser.getLocation(options));
-  }
-
-  return api.makeState(
-    evt.state.name,
-    evt.state.params,
-    evt.state.path,
-    {
-      ...evt.state.meta,
-      params: evt.state.meta?.params ?? {},
-    },
-    evt.state.meta?.id,
-  );
-}
-
-/**
- * Checks if transition should be skipped (same states)
- *
- * @param newState - New state from event
- * @param currentState - Current router state
- * @param router - Router instance
- * @returns true if transition should be skipped
- */
-export function shouldSkipTransition(
-  newState: State | undefined,
-  currentState: State | undefined,
-  router: Router,
-): boolean {
-  if (!newState) {
-    return true;
-  }
-
-  return !!(
-    currentState && router.areStatesEqual(newState, currentState, false)
-  );
-}
-
-/**
- * Handles missing state by navigating to default route
- *
- * @param router - Router instance
- * @param api - Plugin API instance
- * @param transitionOptions - Options for transition
- * @returns true if handled, false if no default route
- */
-export function handleMissingState(
-  router: Router,
-  api: PluginApi,
-  transitionOptions: NavigationOptions,
-): boolean {
-  const routerOptions = api.getOptions();
-  const { defaultRoute } = routerOptions;
-
-  if (!defaultRoute) {
-    return false;
-  }
-
-  void router.navigateToDefault({
-    ...transitionOptions,
-    reload: true,
-    replace: true,
-  });
-
-  return true;
-}
-
-/**
- * Updates browser state (pushState or replaceState)
- *
- * @param state - Router state
- * @param url - URL to set
- * @param replace - Whether to replace instead of push
- * @param browser - Browser API instance
- * @param options - Browser plugin options
- */
-export function updateBrowserState(
-  state: State,
-  url: string,
-  replace: boolean,
-  browser: Browser,
-  options: BrowserPluginOptions,
-): void {
-  const trimmedState: HistoryState = {
-    meta: state.meta,
-    name: state.name,
-    params: state.params,
-    path: state.path,
-  };
-
-  const finalState: HistoryState =
-    options.mergeState && browser.getState()
-      ? { ...browser.getState(), ...trimmedState }
-      : trimmedState;
-
-  if (replace) {
-    browser.replaceState(finalState, "", url);
-  } else {
-    browser.pushState(finalState, "", url);
-  }
-}
-
-/**
- * Handles transition result (success or error)
- *
- * Success case is handled by the router FSM chain (TRANSITION_SUCCESS event).
- * This function only handles error cases that need URL restoration.
- *
- * @param err - Router error or undefined if successful
- * @param toState - Target state
- * @param fromState - Source state
- * @param isNewState - Whether this is a new state (not from history)
- * @param router - Router instance
- * @param browser - Browser API instance
- * @param options - Browser plugin options
- */
-export function handleTransitionResult(
-  err: RouterError | undefined,
-  toState: State | undefined,
-  fromState: State | undefined,
-  isNewState: boolean,
-  router: Router,
-  browser: Browser,
-  options: BrowserPluginOptions,
-): void {
-  // Success case handled by the router FSM chain (TRANSITION_SUCCESS event)
-  if (!err) {
-    return;
-  }
-
-  // Handle CANNOT_DEACTIVATE - restore previous URL
-  if (
-    err.code === errorCodes.CANNOT_DEACTIVATE &&
-    toState &&
-    fromState &&
-    !isNewState
-  ) {
-    const url = router.buildUrl(fromState.name, fromState.params);
-
-    updateBrowserState(fromState, url, true, browser, options);
-  }
-}
-
-/**
- * Type guard to check if a key exists in default options
- */
-function isDefaultOptionKey(
-  key: string,
-  defaults: DefaultBrowserPluginOptions,
-): key is keyof DefaultBrowserPluginOptions {
-  return key in defaults;
-}
-
-/**
- * Validates that an option value has the correct type
- */
-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;
-}
-
-/**
- * Validates browser plugin options and warns about conflicting configurations.
- * TypeScript types prevent conflicts at compile-time, but runtime validation
- * is needed for JavaScript users and dynamic configurations.
- *
- * IMPORTANT: This validates only user-provided options, not merged defaults.
- *
- * @returns true if invalid types detected, false otherwise
- */
-export function validateOptions(
-  opts: Partial<BrowserPluginOptions> | undefined,
-  defaultOptions: DefaultBrowserPluginOptions,
-): boolean {
-  if (!opts) {
-    return false;
-  }
-
-  let hasInvalidTypes = false;
-
-  // Validate option types against defaults
-  // Using Object.keys ensures we only check properties that actually exist
-  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;
-      }
-    }
-  }
-
-  // Check for hash mode conflicts
-  // Runtime validation for JS users - TypeScript prevents this at compile time
-
-  if (opts.useHash === true && "preserveHash" in opts) {
-    console.warn(`[${LOGGER_CONTEXT}] preserveHash ignored in hash mode`);
-  }
-
-  // Check for history mode conflicts
-  // Runtime validation for JS users - TypeScript prevents this at compile time
-
-  if (opts.useHash === false && "hashPrefix" in opts) {
-    // Single type assertion needed: TypeScript narrows opts to HistoryModeOptions
-    // where hashPrefix is 'never', but we need to check it at runtime for JS users
-    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`);
-    }
-  }
-
-  return hasInvalidTypes;
-}