@real-router/browser-plugin 0.6.3 → 0.8.0

package/src/factory.ts

@@ -0,0 +1,88 @@
+import { getPluginApi } from "@real-router/core";
+
+import { createSafeBrowser } from "./browser";
+import { defaultOptions, LOGGER_CONTEXT, source } from "./constants";
+import { BrowserPlugin } from "./plugin";
+import { createRegExpCache } from "./url-utils";
+import { validateOptions } from "./validation";
+
+import type {
+  BrowserPluginOptions,
+  Browser,
+  SharedFactoryState,
+} from "./types";
+import type { PluginFactory, Router } from "@real-router/core";
+
+/**
+ * Browser plugin factory for real-router.
+ * Integrates router with browser history API.
+ *
+ * @param opts - Plugin configuration options
+ * @param browser - Browser API abstraction (for testing/SSR)
+ * @returns Plugin factory function
+ *
+ * @example
+ * ```ts
+ * // Hash routing
+ * router.usePlugin(browserPluginFactory({ useHash: true, hashPrefix: "!" }));
+ *
+ * // History routing with hash preservation
+ * router.usePlugin(browserPluginFactory({ useHash: false, preserveHash: true }));
+ * ```
+ */
+export function browserPluginFactory(
+  opts?: Partial<BrowserPluginOptions>,
+  browser: Browser = createSafeBrowser(),
+): PluginFactory {
+  const hasInvalidTypes = validateOptions(opts, defaultOptions);
+
+  let options = { ...defaultOptions, ...opts } as BrowserPluginOptions;
+
+  if (hasInvalidTypes) {
+    console.warn(
+      `[${LOGGER_CONTEXT}] Using default options due to invalid types`,
+    );
+    options = { ...defaultOptions } as BrowserPluginOptions;
+  }
+
+  if (options.useHash === true) {
+    delete (options as unknown as Record<string, unknown>).preserveHash;
+  } else {
+    delete (options as unknown as Record<string, unknown>).hashPrefix;
+  }
+
+  if (options.base) {
+    if (!options.base.startsWith("/")) {
+      options.base = `/${options.base}`;
+    }
+
+    if (options.base.endsWith("/")) {
+      options.base = options.base.slice(0, -1);
+    }
+  }
+
+  const regExpCache = createRegExpCache();
+
+  const forceDeactivate = options.forceDeactivate;
+  /* v8 ignore next 4 -- @preserve both branches tested, coverage tool limitation */
+  const transitionOptions =
+    forceDeactivate === undefined
+      ? { source, replace: true as const }
+      : { forceDeactivate, source, replace: true as const };
+
+  const shared: SharedFactoryState = { removePopStateListener: undefined };
+
+  return function browserPlugin(routerBase) {
+    const plugin = new BrowserPlugin(
+      routerBase as Router,
+      getPluginApi(routerBase),
+      options,
+      browser,
+      regExpCache,
+      transitionOptions,
+      shared,
+    );
+
+    return plugin.getPlugin();
+  };
+}

package/src/index.ts

@@ -5,13 +5,13 @@
 import type { Params, State } from "@real-router/core";
 
 // Main plugin factory
-export { browserPluginFactory } from "./plugin";
+export { browserPluginFactory } from "./factory";
 
 // Types
-export type { BrowserPluginOptions, Browser, HistoryState } from "./types";
+export type { BrowserPluginOptions, Browser } from "./types";
 
-// Type guards (maybe useful for consumers)
-export { isStateStrict as isState, isHistoryState } from "type-guards";
+// Type guards
+export { isStateStrict as isState } from "type-guards";
 
 /**
  * Module augmentation for real-router.
@@ -41,12 +41,6 @@ declare module "@real-router/core" {
       title?: string,
     ) => void;
 
-    /**
-     * Last known router state.
-     * Added by browser plugin.
-     */
-    lastKnownState?: State;
-
     start(path?: string): Promise<State>;
   }
 }