@real-router/core 0.25.4 → 0.26.0

package/src/namespaces/StateNamespace/validators.ts

@@ -0,0 +1,46 @@
+// packages/core/src/namespaces/StateNamespace/validators.ts
+
+/**
+ * Static validation functions for StateNamespace.
+ * Called by Router facade before instance methods.
+ */
+
+import { isString, isParams, getTypeDescription } from "type-guards";
+
+/**
+ * Validates makeState arguments.
+ */
+export function validateMakeStateArgs(
+  name: unknown,
+  params: unknown,
+  path: unknown,
+  forceId: unknown,
+): void {
+  // Validate name is a string
+  if (!isString(name)) {
+    throw new TypeError(
+      `[router.makeState] Invalid name: ${getTypeDescription(name)}. Expected string.`,
+    );
+  }
+
+  // Validate params if provided
+  if (params !== undefined && !isParams(params)) {
+    throw new TypeError(
+      `[router.makeState] Invalid params: ${getTypeDescription(params)}. Expected plain object.`,
+    );
+  }
+
+  // Validate path if provided
+  if (path !== undefined && !isString(path)) {
+    throw new TypeError(
+      `[router.makeState] Invalid path: ${getTypeDescription(path)}. Expected string.`,
+    );
+  }
+
+  // Validate forceId if provided
+  if (forceId !== undefined && typeof forceId !== "number") {
+    throw new TypeError(
+      `[router.makeState] Invalid forceId: ${getTypeDescription(forceId)}. Expected number.`,
+    );
+  }
+}

package/src/namespaces/index.ts

@@ -1,6 +1,8 @@
 // packages/core/src/namespaces/index.ts
 
-export { DependenciesNamespace } from "./DependenciesNamespace";
+export { createDependenciesStore } from "./DependenciesNamespace";
+
+export type { DependenciesStore } from "./DependenciesNamespace";
 
 export {
   deepFreeze,
@@ -33,8 +35,4 @@ export { NavigationNamespace } from "./NavigationNamespace";
 
 export { RouterLifecycleNamespace } from "./RouterLifecycleNamespace";
 
-export { CloneNamespace } from "./CloneNamespace";
-
-export type { ApplyConfigFn, CloneData, RouterFactory } from "./CloneNamespace";
-
 export { EventBusNamespace } from "./EventBusNamespace";

package/src/types.ts

@@ -1,32 +1,30 @@
 // packages/core/src/types.ts
 
 /**
- * Router-dependent types.
+ * Core-internal types + re-exports from @real-router/types.
  *
- * These types reference the Router class and are therefore defined in core
- * rather than core-types to avoid circular dependencies.
+ * Factory types (PluginFactory, GuardFnFactory) and
+ * route config types (Route, RouteConfigUpdate) are canonical in @real-router/types
+ * and re-exported here for backward compatibility.
  */
 
-import type { events, plugins } from "./constants";
-import type { Router } from "./Router";
 import type {
-  ActivationFn,
-  DefaultDependencies,
-  EventsKeys,
-  ForwardToCallback,
-  GuardFn,
   LimitsConfig,
   NavigationOptions,
   Params,
-  Plugin,
   RouterError as RouterErrorType,
   RouteTreeState,
   State,
 } from "@real-router/types";
 
-export type EventMethodMap = {
-  [K in EventsKeys as (typeof events)[K]]: (typeof plugins)[K];
-};
+// Re-export from @real-router/types (canonical source)
+export type {
+  GuardFnFactory,
+  PluginFactory,
+  Route,
+  RouteConfigUpdate,
+  EventMethodMap,
+} from "@real-router/types";
 
 /**
  * Event argument tuples for the router's 6 events.
@@ -68,127 +66,3 @@ export interface BuildStateResultWithSegments<P extends Params = Params> {
   readonly state: RouteTreeState<P>;
   readonly segments: readonly unknown[];
 }
-
-/**
- * Route configuration.
- */
-export interface Route<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  [key: string]: unknown;
-  /** Route name (dot-separated for nested routes). */
-  name: string;
-  /** URL path pattern for this route. */
-  path: string;
-  /** Factory function that returns a guard for route activation. */
-  canActivate?: GuardFnFactory<Dependencies>;
-  /** Factory function that returns a guard for route deactivation. */
-  canDeactivate?: GuardFnFactory<Dependencies>;
-  /**
-   * Redirects navigation to another route.
-   *
-   * IMPORTANT: forwardTo creates a URL alias, not a transition chain.
-   * Guards (canActivate) on the source route are NOT executed.
-   * Only guards on the final destination are executed.
-   *
-   * This matches Vue Router and Angular Router behavior.
-   *
-   * @example
-   * // Correct: guard on target
-   * { name: "old", path: "/old", forwardTo: "new" }
-   * { name: "new", path: "/new", canActivate: myGuard }
-   *
-   * // Wrong: guard on source (will be ignored with warning)
-   * { name: "old", path: "/old", forwardTo: "new", canActivate: myGuard }
-   */
-  forwardTo?: string | ForwardToCallback<Dependencies>;
-  /** Nested child routes. */
-  children?: Route<Dependencies>[];
-  /** Encodes state params to URL params. */
-  encodeParams?: (stateParams: Params) => Params;
-  /** Decodes URL params to state params. */
-  decodeParams?: (pathParams: Params) => Params;
-  /**
-   * Default parameters for this route.
-   *
-   * @remarks
-   * **Type Contract:**
-   * The type of defaultParams MUST match the expected params type P
-   * when using `router.makeState<P>()` or `router.navigate<P>()`.
-   *
-   * These values are merged into state.params when creating route states.
-   * Missing URL params are filled from defaultParams.
-   *
-   * @example
-   * ```typescript
-   * // Define route with pagination defaults
-   * {
-   *   name: "users",
-   *   path: "/users",
-   *   defaultParams: { page: 1, limit: 10 }
-   * }
-   *
-   * // Navigate without specifying page/limit
-   * router.navigate("users", { filter: "active" });
-   * // Result: state.params = { page: 1, limit: 10, filter: "active" }
-   *
-   * // Correct typing — include defaultParams properties
-   * type UsersParams = { page: number; limit: number; filter?: string };
-   * ```
-   */
-  defaultParams?: Params;
-}
-
-/**
- * Configuration update options for updateRoute().
- * All properties are optional. Set to null to remove the configuration.
- */
-export interface RouteConfigUpdate<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  /** Set to null to remove forwardTo */
-  forwardTo?: string | ForwardToCallback<Dependencies> | null;
-  /** Set to null to remove defaultParams */
-  defaultParams?: Params | null;
-  /** Set to null to remove decoder */
-  decodeParams?: ((params: Params) => Params) | null;
-  /** Set to null to remove encoder */
-  encodeParams?: ((params: Params) => Params) | null;
-  /** Set to null to remove canActivate */
-  canActivate?: GuardFnFactory<Dependencies> | null;
-  /** Set to null to remove canDeactivate */
-  canDeactivate?: GuardFnFactory<Dependencies> | null;
-}
-
-/**
- * Factory function for creating activation guards.
- * Receives the router instance and a dependency getter.
- */
-export type ActivationFnFactory<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> = (
-  router: Router<Dependencies>,
-  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
-) => ActivationFn;
-
-/**
- * Factory function for creating guards.
- * Receives the router instance and a dependency getter.
- */
-export type GuardFnFactory<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> = (
-  router: Router<Dependencies>,
-  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
-) => GuardFn;
-
-/**
- * Factory function for creating plugins.
- * Receives the router instance and a dependency getter.
- */
-export type PluginFactory<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> = (
-  router: Router<Dependencies>,
-  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
-) => Plugin;

package/src/wiring/RouterWiringBuilder.ts

@@ -1,5 +1,8 @@
 // packages/core/src/wiring/RouterWiringBuilder.ts
 
+import { getInternals } from "../internals";
+import { validateStateBuilderArgs } from "../namespaces/RoutesNamespace/validators";
+
 import type { EventBusNamespace } from "../namespaces";
 import type { WiringOptions } from "./types";
 import type {
@@ -18,33 +21,31 @@ export class RouterWiringBuilder<
   private readonly router: WiringOptions<Dependencies>["router"];
   private readonly options: WiringOptions<Dependencies>["options"];
   private readonly limits: WiringOptions<Dependencies>["limits"];
-  private readonly dependencies: WiringOptions<Dependencies>["dependencies"];
+  private readonly dependenciesStore: WiringOptions<Dependencies>["dependenciesStore"];
   private readonly state: WiringOptions<Dependencies>["state"];
   private readonly routes: WiringOptions<Dependencies>["routes"];
   private readonly routeLifecycle: WiringOptions<Dependencies>["routeLifecycle"];
   private readonly plugins: WiringOptions<Dependencies>["plugins"];
   private readonly navigation: WiringOptions<Dependencies>["navigation"];
   private readonly lifecycle: WiringOptions<Dependencies>["lifecycle"];
-  private readonly clone: WiringOptions<Dependencies>["clone"];
   private readonly eventBus: EventBusNamespace;
 
   constructor(wiringOptions: WiringOptions<Dependencies>) {
     this.router = wiringOptions.router;
     this.options = wiringOptions.options;
     this.limits = wiringOptions.limits;
-    this.dependencies = wiringOptions.dependencies;
+    this.dependenciesStore = wiringOptions.dependenciesStore;
     this.state = wiringOptions.state;
     this.routes = wiringOptions.routes;
     this.routeLifecycle = wiringOptions.routeLifecycle;
     this.plugins = wiringOptions.plugins;
     this.navigation = wiringOptions.navigation;
     this.lifecycle = wiringOptions.lifecycle;
-    this.clone = wiringOptions.clone;
     this.eventBus = wiringOptions.eventBus;
   }
 
   wireLimits(): void {
-    this.dependencies.setLimits(this.limits);
+    this.dependenciesStore.limits = this.limits;
     this.plugins.setLimits(this.limits);
     this.eventBus.setLimits({
       maxListeners: this.limits.maxListeners,
@@ -59,7 +60,7 @@ export class RouterWiringBuilder<
 
     const routeLifecycleDeps: RouteLifecycleDependencies<Dependencies> = {
       getDependency: <K extends keyof Dependencies>(dependencyName: K) =>
-        this.dependencies.get(dependencyName),
+        this.dependenciesStore.dependencies[dependencyName] as Dependencies[K],
     };
 
     this.routeLifecycle.setDependencies(routeLifecycleDeps);
@@ -68,18 +69,27 @@ export class RouterWiringBuilder<
   wireRoutesDeps(): void {
     const routesDeps: RoutesDependencies<Dependencies> = {
       addActivateGuard: (name, handler) => {
-        this.router.addActivateGuard(name, handler);
+        this.routeLifecycle.addCanActivate(name, handler, true);
       },
       addDeactivateGuard: (name, handler) => {
-        this.router.addDeactivateGuard(name, handler);
+        this.routeLifecycle.addCanDeactivate(name, handler, true);
       },
       makeState: (name, params, path, meta) =>
         this.state.makeState(name, params, path, meta),
       getState: () => this.state.get(),
       areStatesEqual: (state1, state2, ignoreQueryParams) =>
         this.state.areStatesEqual(state1, state2, ignoreQueryParams),
-      getDependency: (name) => this.dependencies.get(name),
-      forwardState: (name, params) => this.router.forwardState(name, params),
+      getDependency: (name) =>
+        this.dependenciesStore.dependencies[name] as Dependencies[typeof name],
+      forwardState: (name, params) => {
+        const ctx = getInternals(this.router);
+
+        if (!ctx.noValidate) {
+          validateStateBuilderArgs(name, params, "forwardState");
+        }
+
+        return ctx.forwardState(name, params);
+      },
     };
 
     this.routes.setDependencies(routesDeps);
@@ -94,7 +104,7 @@ export class RouterWiringBuilder<
         this.eventBus.addEventListener(eventName, cb),
       canNavigate: () => this.eventBus.canBeginTransition(),
       getDependency: <K extends keyof Dependencies>(dependencyName: K) =>
-        this.dependencies.get(dependencyName),
+        this.dependenciesStore.dependencies[dependencyName] as Dependencies[K],
     };
 
     this.plugins.setDependencies(pluginsDeps);
@@ -109,10 +119,13 @@ export class RouterWiringBuilder<
         this.state.set(state);
       },
       buildStateWithSegments: (routeName, routeParams) => {
-        const { name, params } = this.router.forwardState(
-          routeName,
-          routeParams,
-        );
+        const ctx = getInternals(this.router);
+
+        if (!ctx.noValidate) {
+          validateStateBuilderArgs(routeName, routeParams, "navigate");
+        }
+
+        const { name, params } = ctx.forwardState(routeName, routeParams);
 
         return this.routes.buildStateWithSegmentsResolved(name, params);
       },
@@ -123,7 +136,7 @@ export class RouterWiringBuilder<
       areStatesEqual: (state1, state2, ignoreQueryParams) =>
         this.state.areStatesEqual(state1, state2, ignoreQueryParams),
       getDependency: (name: string) =>
-        this.dependencies.get(name as keyof Dependencies),
+        this.dependenciesStore.dependencies[name as keyof Dependencies],
       startTransition: (toState, fromState) => {
         this.eventBus.beginTransition(toState, fromState);
       },
@@ -183,32 +196,13 @@ export class RouterWiringBuilder<
 
   wireStateDeps(): void {
     this.state.setDependencies({
-      getDefaultParams: () => this.routes.getConfig().defaultParams,
+      getDefaultParams: () => this.routes.getStore().config.defaultParams,
       buildPath: (name, params) =>
         this.routes.buildPath(name, params, this.options.get()),
       getUrlParams: (name) => this.routes.getUrlParams(name),
     });
   }
 
-  wireCloneCallbacks(): void {
-    this.clone.setGetCloneData(() => {
-      const [canDeactivateFactories, canActivateFactories] =
-        this.routeLifecycle.getFactories();
-
-      return {
-        routes: this.routes.cloneRoutes(),
-        options: { ...this.options.get() },
-        dependencies: this.dependencies.getAll(),
-        canDeactivateFactories,
-        canActivateFactories,
-        pluginFactories: this.plugins.getAll(),
-        routeConfig: this.routes.getConfig(),
-        resolvedForwardMap: this.routes.getResolvedForwardMap(),
-        routeCustomFields: this.routes.getRouteCustomFields(),
-      };
-    });
-  }
-
   wireCyclicDeps(): void {
     this.navigation.setCanNavigate(() => this.eventBus.canBeginTransition());
 

package/src/wiring/types.ts

@@ -1,8 +1,6 @@
 // packages/core/src/wiring/types.ts
 
 import type {
-  CloneNamespace,
-  DependenciesNamespace,
   EventBusNamespace,
   NavigationNamespace,
   OptionsNamespace,
@@ -12,6 +10,7 @@ import type {
   RoutesNamespace,
   StateNamespace,
 } from "../namespaces";
+import type { DependenciesStore } from "../namespaces/DependenciesNamespace/dependenciesStore";
 import type { Router } from "../Router";
 import type { Limits } from "../types";
 import type { DefaultDependencies } from "@real-router/types";
@@ -29,8 +28,8 @@ export interface WiringOptions<Dependencies extends DefaultDependencies> {
   options: OptionsNamespace;
   /** Immutable limits configuration */
   limits: Limits;
-  /** Dependencies namespace */
-  dependencies: DependenciesNamespace<Dependencies>;
+  /** Dependencies store */
+  dependenciesStore: DependenciesStore<Dependencies>;
   /** State namespace */
   state: StateNamespace;
   /** Routes namespace */
@@ -43,8 +42,6 @@ export interface WiringOptions<Dependencies extends DefaultDependencies> {
   navigation: NavigationNamespace;
   /** Router lifecycle namespace (start/stop) */
   lifecycle: RouterLifecycleNamespace;
-  /** Clone namespace (SSR cloning) */
-  clone: CloneNamespace<Dependencies>;
   /** EventBus namespace — unified FSM + EventEmitter abstraction */
   eventBus: EventBusNamespace;
 }

package/src/wiring/wireRouter.ts

@@ -23,6 +23,5 @@ export function wireRouter<Dependencies extends DefaultDependencies>(
   builder.wireNavigationDeps();
   builder.wireLifecycleDeps();
   builder.wireStateDeps();
-  builder.wireCloneCallbacks();
   builder.wireCyclicDeps();
 }

package/src/namespaces/CloneNamespace/CloneNamespace.ts

@@ -1,120 +0,0 @@
-// packages/core/src/namespaces/CloneNamespace/CloneNamespace.ts
-
-import { getTypeDescription } from "type-guards";
-
-import type { ApplyConfigFn, CloneData, RouterFactory } from "./types";
-import type { Router } from "../../Router";
-import type { DefaultDependencies } from "@real-router/types";
-
-/**
- * Independent namespace for router cloning operations.
- *
- * This namespace handles the logic of collecting data from a source router
- * and creating a configured clone. It requires a factory function to create
- * the new router instance.
- */
-export class CloneNamespace<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  // =========================================================================
-  // Instance fields
-  // =========================================================================
-
-  /**
-   * Function to get cloning data from the source router.
-   */
-  #getCloneData!: () => CloneData<Dependencies>;
-
-  // =========================================================================
-  // Static validation methods (called by facade before instance methods)
-  // =========================================================================
-
-  /**
-   * Validates clone arguments.
-   * Dependencies can be undefined or a plain object without getters.
-   */
-  static validateCloneArgs(dependencies: unknown): void {
-    // undefined is valid (no new dependencies)
-    if (dependencies === undefined) {
-      return;
-    }
-
-    // Must be a plain object
-    if (
-      !(
-        dependencies &&
-        typeof dependencies === "object" &&
-        dependencies.constructor === Object
-      )
-    ) {
-      throw new TypeError(
-        `[router.clone] Invalid dependencies: expected plain object or undefined, received ${getTypeDescription(dependencies)}`,
-      );
-    }
-
-    // Getters can throw, return different values, or have side effects
-    for (const key in dependencies) {
-      if (Object.getOwnPropertyDescriptor(dependencies, key)?.get) {
-        throw new TypeError(
-          `[router.clone] Getters not allowed in dependencies: "${key}"`,
-        );
-      }
-    }
-  }
-
-  /**
-   * Sets the function to collect clone data.
-   */
-  setGetCloneData(getCloneData: () => CloneData<Dependencies>): void {
-    this.#getCloneData = getCloneData;
-  }
-
-  /**
-   * Creates a clone of the router with optional new dependencies.
-   *
-   * @param dependencies - Optional new dependencies for the cloned router
-   * @param factory - Factory function to create the new router instance
-   * @param applyConfig - Function to apply route config to the new router
-   */
-  clone(
-    dependencies: Dependencies | undefined,
-    factory: RouterFactory<Dependencies>,
-    applyConfig: ApplyConfigFn<Dependencies>,
-  ): Router<Dependencies> {
-    // Collect all data from source router
-    const data = this.#getCloneData();
-
-    // Merge dependencies
-    const mergedDeps = {
-      ...data.dependencies,
-      ...dependencies,
-    } as Dependencies;
-
-    // Create new router instance
-    const newRouter = factory(data.routes, data.options, mergedDeps);
-
-    // Copy lifecycle factories
-    for (const [name, handler] of Object.entries(data.canDeactivateFactories)) {
-      newRouter.addDeactivateGuard(name, handler);
-    }
-
-    for (const [name, handler] of Object.entries(data.canActivateFactories)) {
-      newRouter.addActivateGuard(name, handler);
-    }
-
-    // Copy plugin factories
-    if (data.pluginFactories.length > 0) {
-      newRouter.usePlugin(...data.pluginFactories);
-    }
-
-    // Apply route config (decoders, encoders, defaultParams, forwardMap)
-    applyConfig(
-      newRouter,
-      data.routeConfig,
-      data.resolvedForwardMap,
-      data.routeCustomFields,
-    );
-
-    return newRouter;
-  }
-}

package/src/namespaces/CloneNamespace/index.ts

@@ -1,3 +0,0 @@
-export { CloneNamespace } from "./CloneNamespace";
-
-export type { ApplyConfigFn, CloneData, RouterFactory } from "./types";

package/src/namespaces/CloneNamespace/types.ts

@@ -1,42 +0,0 @@
-// packages/core/src/namespaces/CloneNamespace/types.ts
-
-import type { Router } from "../../Router";
-import type { GuardFnFactory, PluginFactory, Route } from "../../types";
-import type { RouteConfig } from "../RoutesNamespace";
-import type { DefaultDependencies, Options } from "@real-router/types";
-
-/**
- * Data collected from source router for cloning.
- */
-export interface CloneData<Dependencies extends DefaultDependencies> {
-  routes: Route<Dependencies>[];
-  options: Options;
-  dependencies: Partial<Dependencies>;
-  canDeactivateFactories: Record<string, GuardFnFactory<Dependencies>>;
-  canActivateFactories: Record<string, GuardFnFactory<Dependencies>>;
-  pluginFactories: PluginFactory<Dependencies>[];
-  routeConfig: RouteConfig;
-  resolvedForwardMap: Record<string, string>;
-  routeCustomFields: Record<string, Record<string, unknown>>;
-}
-
-/**
- * Factory function to create a new router instance.
- */
-export type RouterFactory<Dependencies extends DefaultDependencies> = (
-  routes: Route<Dependencies>[],
-  options: Partial<Options>,
-  dependencies: Dependencies,
-) => Router<Dependencies>;
-
-/**
- * Function to apply route config to a new router.
- */
-export type ApplyConfigFn<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> = (
-  router: Router<Dependencies>,
-  config: RouteConfig,
-  resolvedForwardMap: Record<string, string>,
-  routeCustomFields: Record<string, Record<string, unknown>>,
-) => void;