@real-router/core 0.23.1 → 0.25.0

package/src/namespaces/NavigationNamespace/transition/executeLifecycleHooks.ts

@@ -1,32 +1,26 @@
-// packages/real-router/modules/transition/executeLifecycleHooks.ts
-
-import { logger } from "@real-router/logger";
-import { isState } from "type-guards";
-
-import { rethrowAsRouterError } from "./makeError";
-import { mergeStates } from "./mergeStates";
-import { processLifecycleResult } from "./processLifecycleResult";
+import { rethrowAsRouterError } from "./errorHandling";
 import { errorCodes } from "../../../constants";
 import { RouterError } from "../../../RouterError";
 
-import type { State, ActivationFn } from "@real-router/types";
+import type { GuardFn, State } from "@real-router/types";
 
 // Helper: execution of the Lifecycle Hooks group
-export const executeLifecycleHooks = async (
-  hooks: Map<string, ActivationFn>,
+export async function executeLifecycleHooks(
+  hooks: Map<string, GuardFn>,
   toState: State,
   fromState: State | undefined,
   segments: string[],
   errorCode: string,
   isCancelled: () => boolean,
-): Promise<State> => {
-  let currentState = toState;
+): Promise<void> {
   const segmentsToProcess = segments.filter((name) => hooks.has(name));
 
   if (segmentsToProcess.length === 0) {
-    return currentState;
+    return;
   }
 
+  let result: boolean | undefined;
+
   for (const segment of segmentsToProcess) {
     if (isCancelled()) {
       throw new RouterError(errorCodes.TRANSITION_CANCELLED);
@@ -37,48 +31,13 @@ export const executeLifecycleHooks = async (
     const hookFn = hooks.get(segment)!;
 
     try {
-      const result = hookFn(currentState, fromState);
-      const newState = await processLifecycleResult(
-        result,
-        currentState,
-        segment,
-      );
-
-      // Optimization: Early return for undefined newState (most common case ~90%+)
-      // This avoids isState() call and subsequent checks
-      if (newState !== currentState && isState(newState)) {
-        // Guards cannot redirect to a different route
-        if (newState.name !== currentState.name) {
-          throw new RouterError(errorCode, {
-            message:
-              "Guards cannot redirect to different route. Use middleware.",
-            attemptedRedirect: {
-              name: newState.name,
-              params: newState.params,
-              path: newState.path,
-            },
-          });
-        }
-
-        // Same route - safe to merge (param modifications, meta changes)
-        const hasChanged =
-          newState.params !== currentState.params ||
-          newState.path !== currentState.path;
-
-        if (hasChanged) {
-          logger.error(
-            "core:transition",
-            "Warning: State mutated during transition",
-            { from: currentState, to: newState },
-          );
-        }
-
-        currentState = mergeStates(newState, currentState);
-      }
+      result = await hookFn(toState, fromState);
     } catch (error: unknown) {
       rethrowAsRouterError(error, errorCode, segment);
     }
-  }
 
-  return currentState;
-};
+    if (!result) {
+      throw new RouterError(errorCode, { segment });
+    }
+  }
+}

package/src/namespaces/NavigationNamespace/transition/index.ts

@@ -1,7 +1,6 @@
-// packages/real-router/modules/transition/index.ts
+// packages/core/src/namespaces/NavigationNamespace/transition/index.ts
 
 import { executeLifecycleHooks } from "./executeLifecycleHooks";
-import { executeMiddleware } from "./executeMiddleware";
 import { constants, errorCodes } from "../../../constants";
 import { RouterError } from "../../../RouterError";
 import { getTransitionPath, nameToIDs } from "../../../transitionPath";
@@ -18,7 +17,6 @@ export async function transition(
   // We're caching the necessary data
   const [canDeactivateFunctions, canActivateFunctions] =
     deps.getLifecycleFunctions();
-  const middlewareFunctions = deps.getMiddlewareFunctions();
   const isUnknownRoute = toState.name === constants.UNKNOWN_ROUTE;
 
   // State management functions
@@ -34,12 +32,9 @@ export async function transition(
   const shouldDeactivate =
     fromState && !opts.forceDeactivate && toDeactivate.length > 0;
   const shouldActivate = !isUnknownRoute && toActivate.length > 0;
-  const shouldRunMiddleware = middlewareFunctions.length > 0;
-
-  let currentState = toState;
 
   if (shouldDeactivate) {
-    currentState = await executeLifecycleHooks(
+    await executeLifecycleHooks(
       canDeactivateFunctions,
       toState,
       fromState,
@@ -54,9 +49,9 @@ export async function transition(
   }
 
   if (shouldActivate) {
-    currentState = await executeLifecycleHooks(
+    await executeLifecycleHooks(
       canActivateFunctions,
-      currentState,
+      toState,
       fromState,
       toActivate,
       errorCodes.CANNOT_ACTIVATE,
@@ -68,19 +63,6 @@ export async function transition(
     throw new RouterError(errorCodes.TRANSITION_CANCELLED);
   }
 
-  if (shouldRunMiddleware) {
-    currentState = await executeMiddleware(
-      middlewareFunctions,
-      currentState,
-      fromState,
-      isCancelled,
-    );
-  }
-
-  if (isCancelled()) {
-    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-  }
-
   // Automatic cleaning of inactive segments
   if (fromState) {
     const activeSegments = nameToIDs(toState.name);
@@ -94,9 +76,9 @@ export async function transition(
   }
 
   return {
-    state: currentState,
+    state: toState,
     meta: {
-      phase: "middleware",
+      phase: "activating",
       segments: {
         deactivated: toDeactivate,
         activated: toActivate,

package/src/namespaces/NavigationNamespace/types.ts

@@ -2,8 +2,7 @@
 
 import type { BuildStateResultWithSegments } from "../../types";
 import type {
-  ActivationFn,
-  Middleware,
+  GuardFn,
   NavigationOptions,
   Options,
   Params,
@@ -110,13 +109,7 @@ export interface TransitionOutput {
  */
 export interface TransitionDependencies {
   /** Get lifecycle functions (canDeactivate, canActivate maps) */
-  getLifecycleFunctions: () => [
-    Map<string, ActivationFn>,
-    Map<string, ActivationFn>,
-  ];
-
-  /** Get middleware functions array */
-  getMiddlewareFunctions: () => Middleware[];
+  getLifecycleFunctions: () => [Map<string, GuardFn>, Map<string, GuardFn>];
 
   /** Check if router is active (for cancellation check on stop()) */
   isActive: () => boolean;

package/src/namespaces/PluginsNamespace/PluginsNamespace.ts

@@ -222,8 +222,8 @@ export class PluginsNamespace<
   /**
    * Disposes all registered plugins by running their teardown callbacks
    * and removing event listener subscriptions.
-   * Unlike {@link MiddlewareNamespace.clearAll}, active disposal is required —
-   * plugins have an active lifecycle (event subscriptions, teardown hooks).
+   * Active disposal is required because plugins have an active lifecycle
+   * (event subscriptions, teardown hooks).
    * Named "dispose" (not "clear") because there is active cleanup to perform.
    */
   disposeAll(): void {

package/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts

@@ -1,7 +1,7 @@
 // packages/core/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts
 
 import { logger } from "@real-router/logger";
-import { isBoolean, isPromise, getTypeDescription } from "type-guards";
+import { isBoolean, getTypeDescription } from "type-guards";
 
 import {
   validateHandler,
@@ -13,23 +13,19 @@ import { computeThresholds } from "../../helpers";
 
 import type { RouteLifecycleDependencies } from "./types";
 import type { Router } from "../../Router";
-import type { ActivationFnFactory, Limits } from "../../types";
-import type {
-  ActivationFn,
-  DefaultDependencies,
-  State,
-} from "@real-router/types";
+import type { GuardFnFactory, Limits } from "../../types";
+import type { DefaultDependencies, GuardFn, State } from "@real-router/types";
 
 /**
- * Converts a boolean value to an activation function factory.
+ * Converts a boolean value to a guard function factory.
  * Used for the shorthand syntax where true/false is passed instead of a function.
  */
 function booleanToFactory<Dependencies extends DefaultDependencies>(
   value: boolean,
-): ActivationFnFactory<Dependencies> {
-  const activationFn: ActivationFn = () => value;
+): GuardFnFactory<Dependencies> {
+  const guardFn: GuardFn = () => value;
 
-  return () => activationFn;
+  return () => guardFn;
 }
 
 /**
@@ -43,14 +39,14 @@ export class RouteLifecycleNamespace<
 > {
   readonly #canDeactivateFactories = new Map<
     string,
-    ActivationFnFactory<Dependencies>
+    GuardFnFactory<Dependencies>
   >();
   readonly #canActivateFactories = new Map<
     string,
-    ActivationFnFactory<Dependencies>
+    GuardFnFactory<Dependencies>
   >();
-  readonly #canDeactivateFunctions = new Map<string, ActivationFn>();
-  readonly #canActivateFunctions = new Map<string, ActivationFn>();
+  readonly #canDeactivateFunctions = new Map<string, GuardFn>();
+  readonly #canActivateFunctions = new Map<string, GuardFn>();
 
   readonly #registering = new Set<string>();
 
@@ -65,7 +61,7 @@ export class RouteLifecycleNamespace<
   static validateHandler<D extends DefaultDependencies>(
     handler: unknown,
     methodName: string,
-  ): asserts handler is ActivationFnFactory<D> | boolean {
+  ): asserts handler is GuardFnFactory<D> | boolean {
     validateHandler<D>(handler, methodName);
   }
 
@@ -95,7 +91,7 @@ export class RouteLifecycleNamespace<
    */
   addCanActivate(
     name: string,
-    handler: ActivationFnFactory<Dependencies> | boolean,
+    handler: GuardFnFactory<Dependencies> | boolean,
     skipValidation: boolean,
   ): void {
     if (!skipValidation) {
@@ -137,7 +133,7 @@ export class RouteLifecycleNamespace<
    */
   addCanDeactivate(
     name: string,
-    handler: ActivationFnFactory<Dependencies> | boolean,
+    handler: GuardFnFactory<Dependencies> | boolean,
     skipValidation: boolean,
   ): void {
     if (!skipValidation) {
@@ -208,17 +204,11 @@ export class RouteLifecycleNamespace<
    * @returns Tuple of [canDeactivateFactories, canActivateFactories]
    */
   getFactories(): [
-    Record<string, ActivationFnFactory<Dependencies>>,
-    Record<string, ActivationFnFactory<Dependencies>>,
+    Record<string, GuardFnFactory<Dependencies>>,
+    Record<string, GuardFnFactory<Dependencies>>,
   ] {
-    const deactivateRecord: Record<
-      string,
-      ActivationFnFactory<Dependencies>
-    > = {};
-    const activateRecord: Record<
-      string,
-      ActivationFnFactory<Dependencies>
-    > = {};
+    const deactivateRecord: Record<string, GuardFnFactory<Dependencies>> = {};
+    const activateRecord: Record<string, GuardFnFactory<Dependencies>> = {};
 
     for (const [name, factory] of this.#canDeactivateFactories) {
       deactivateRecord[name] = factory;
@@ -236,7 +226,7 @@ export class RouteLifecycleNamespace<
    *
    * @returns Tuple of [canDeactivateFunctions, canActivateFunctions] as Maps
    */
-  getFunctions(): [Map<string, ActivationFn>, Map<string, ActivationFn>] {
+  getFunctions(): [Map<string, GuardFn>, Map<string, GuardFn>] {
     return [this.#canDeactivateFunctions, this.#canActivateFunctions];
   }
 
@@ -279,9 +269,9 @@ export class RouteLifecycleNamespace<
   #registerHandler(
     type: "activate" | "deactivate",
     name: string,
-    handler: ActivationFnFactory<Dependencies> | boolean,
-    factories: Map<string, ActivationFnFactory<Dependencies>>,
-    functions: Map<string, ActivationFn>,
+    handler: GuardFnFactory<Dependencies> | boolean,
+    factories: Map<string, GuardFnFactory<Dependencies>>,
+    functions: Map<string, GuardFn>,
     methodName: string,
     isOverwrite: boolean,
   ): void {
@@ -328,7 +318,7 @@ export class RouteLifecycleNamespace<
   }
 
   #checkGuardSync(
-    functions: Map<string, ActivationFn>,
+    functions: Map<string, GuardFn>,
     name: string,
     toState: State,
     fromState: State | undefined,
@@ -347,17 +337,12 @@ export class RouteLifecycleNamespace<
         return result;
       }
 
-      if (isPromise(result)) {
-        logger.warn(
-          `router.${methodName}`,
-          `Guard for "${name}" returned a Promise. Sync check cannot resolve async guards — returning false.`,
-        );
-
-        return false;
-      }
+      logger.warn(
+        `router.${methodName}`,
+        `Guard for "${name}" returned a Promise. Sync check cannot resolve async guards — returning false.`,
+      );
 
-      // Guard returned void/State — permissive default
-      return true;
+      return false;
     } catch {
       return false;
     }

package/src/namespaces/RouteLifecycleNamespace/validators.ts

@@ -9,7 +9,7 @@ import { isBoolean, getTypeDescription } from "type-guards";
 
 import { DEFAULT_LIMITS } from "../../constants";
 
-import type { ActivationFnFactory } from "../../types";
+import type { GuardFnFactory } from "../../types";
 import type { DefaultDependencies } from "@real-router/types";
 
 /**
@@ -18,7 +18,7 @@ import type { DefaultDependencies } from "@real-router/types";
 export function validateHandler<D extends DefaultDependencies>(
   handler: unknown,
   methodName: string,
-): asserts handler is ActivationFnFactory<D> | boolean {
+): asserts handler is GuardFnFactory<D> | boolean {
   if (!isBoolean(handler) && typeof handler !== "function") {
     throw new TypeError(
       `[router.${methodName}] Handler must be a boolean or factory function, ` +
@@ -59,7 +59,7 @@ export function validateHandlerLimit(
     throw new Error(
       `[router.${methodName}] Lifecycle handler limit exceeded (${maxLifecycleHandlers}). ` +
         `This indicates too many routes with individual handlers. ` +
-        `Consider using middleware for cross-cutting concerns.`,
+        `Consider using plugins for cross-cutting concerns.`,
     );
   }
 }

package/src/namespaces/RoutesNamespace/RoutesNamespace.ts

@@ -39,8 +39,8 @@ import { getTransitionPath } from "../../transitionPath";
 
 import type { RouteConfig, RoutesDependencies } from "./types";
 import type {
-  ActivationFnFactory,
   BuildStateResultWithSegments,
+  GuardFnFactory,
   Route,
   RouteConfigUpdate,
 } from "../../types";
@@ -77,22 +77,27 @@ export class RoutesNamespace<
 
   readonly #definitions: RouteDefinition[] = [];
   readonly #config: RouteConfig = createEmptyConfig();
-  readonly #resolvedForwardMap: Record<string, string> = Object.create(
+  #resolvedForwardMap: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+
+  #routeCustomFields: Record<string, Record<string, unknown>> = Object.create(
     null,
-  ) as Record<string, string>;
+  ) as Record<string, Record<string, unknown>>;
 
   // Pending canActivate handlers that need to be registered after router is set
   // Key: route name, Value: canActivate factory
   readonly #pendingCanActivate = new Map<
     string,
-    ActivationFnFactory<Dependencies>
+    GuardFnFactory<Dependencies>
   >();
 
   // Pending canDeactivate handlers that need to be registered after router is set
   // Key: route name, Value: canDeactivate factory
   readonly #pendingCanDeactivate = new Map<
     string,
-    ActivationFnFactory<Dependencies>
+    GuardFnFactory<Dependencies>
   >();
 
   #rootPath = "";
@@ -346,6 +351,18 @@ export class RoutesNamespace<
     return this.#enrichRoute(definition, name);
   }
 
+  getRouteConfig(name: string): Record<string, unknown> | undefined {
+    if (!this.#matcher.hasRoute(name)) {
+      return undefined;
+    }
+
+    return this.#routeCustomFields[name];
+  }
+
+  getRouteCustomFields(): Record<string, Record<string, unknown>> {
+    return this.#routeCustomFields;
+  }
+
   /**
    * Adds one or more routes to the router.
    * Input already validated by facade (properties and state-dependent checks).
@@ -473,31 +490,15 @@ export class RoutesNamespace<
   clearRoutes(): void {
     this.#definitions.length = 0;
 
-    // Clear all config entries
-    for (const key in this.#config.decoders) {
-      delete this.#config.decoders[key];
-    }
-
-    for (const key in this.#config.encoders) {
-      delete this.#config.encoders[key];
-    }
-
-    for (const key in this.#config.defaultParams) {
-      delete this.#config.defaultParams[key];
-    }
-
-    for (const key in this.#config.forwardMap) {
-      delete this.#config.forwardMap[key];
-    }
-
-    for (const key in this.#config.forwardFnMap) {
-      delete this.#config.forwardFnMap[key];
-    }
+    // Reset config to empty null-prototype objects
+    Object.assign(this.#config, createEmptyConfig());
 
     // Clear forward cache
-    for (const key in this.#resolvedForwardMap) {
-      delete this.#resolvedForwardMap[key];
-    }
+    this.#resolvedForwardMap = Object.create(null) as Record<string, string>;
+    this.#routeCustomFields = Object.create(null) as Record<
+      string,
+      Record<string, unknown>
+    >;
 
     // Rebuild empty tree
     this.#rebuildTree();
@@ -872,6 +873,7 @@ export class RoutesNamespace<
   applyClonedConfig(
     config: RouteConfig,
     resolvedForwardMap: Record<string, string>,
+    routeCustomFields: Record<string, Record<string, unknown>>,
   ): void {
     Object.assign(this.#config.decoders, config.decoders);
     Object.assign(this.#config.encoders, config.encoders);
@@ -879,6 +881,7 @@ export class RoutesNamespace<
     Object.assign(this.#config.forwardMap, config.forwardMap);
     Object.assign(this.#config.forwardFnMap, config.forwardFnMap);
     this.setResolvedForwardMap({ ...resolvedForwardMap });
+    Object.assign(this.#routeCustomFields, routeCustomFields);
   }
 
   /**
@@ -1219,9 +1222,7 @@ export class RoutesNamespace<
 
   #validateAndCacheForwardMap(): void {
     // Clear existing cache
-    for (const key in this.#resolvedForwardMap) {
-      delete this.#resolvedForwardMap[key];
-    }
+    this.#resolvedForwardMap = Object.create(null) as Record<string, string>;
 
     // Resolve all chains
     for (const fromRoute of Object.keys(this.#config.forwardMap)) {
@@ -1238,9 +1239,7 @@ export class RoutesNamespace<
    */
   #cacheForwardMap(): void {
     // Clear existing cache
-    for (const key in this.#resolvedForwardMap) {
-      delete this.#resolvedForwardMap[key];
-    }
+    this.#resolvedForwardMap = Object.create(null) as Record<string, string>;
 
     // Resolve chains without validation
     for (const fromRoute of Object.keys(this.#config.forwardMap)) {
@@ -1263,6 +1262,7 @@ export class RoutesNamespace<
     clearConfigEntries(this.#config.defaultParams, shouldClear);
     clearConfigEntries(this.#config.forwardMap, shouldClear);
     clearConfigEntries(this.#config.forwardFnMap, shouldClear);
+    clearConfigEntries(this.#routeCustomFields, shouldClear);
 
     // Clear forwardMap entries pointing TO deleted route
     clearConfigEntries(this.#config.forwardMap, (key) =>
@@ -1305,6 +1305,25 @@ export class RoutesNamespace<
     route: Route<Dependencies>,
     fullName: string,
   ): void {
+    const standardKeys = new Set([
+      "name",
+      "path",
+      "children",
+      "canActivate",
+      "canDeactivate",
+      "forwardTo",
+      "encodeParams",
+      "decodeParams",
+      "defaultParams",
+    ]);
+    const customFields = Object.fromEntries(
+      Object.entries(route).filter(([k]) => !standardKeys.has(k)),
+    );
+
+    if (Object.keys(customFields).length > 0) {
+      this.#routeCustomFields[fullName] = customFields;
+    }
+
     // Register canActivate via deps.canActivate (allows tests to spy on router.canActivate)
     if (route.canActivate) {
       // Note: Uses #depsStore directly because this method is called from constructor

package/src/namespaces/RoutesNamespace/stateBuilder.ts

@@ -1,4 +1,4 @@
-// packages/real-router/modules/core/stateBuilder.ts
+// packages/core/src/namespaces/RoutesNamespace/stateBuilder.ts
 
 /**
  * State Builder Utilities.

package/src/namespaces/RoutesNamespace/types.ts

@@ -1,6 +1,6 @@
 // packages/core/src/namespaces/RoutesNamespace/types.ts
 
-import type { ActivationFnFactory } from "../../types";
+import type { GuardFnFactory } from "../../types";
 import type {
   DefaultDependencies,
   ForwardToCallback,
@@ -22,13 +22,13 @@ export interface RoutesDependencies<
   /** Register canActivate handler for a route */
   addActivateGuard: (
     name: string,
-    handler: ActivationFnFactory<Dependencies>,
+    handler: GuardFnFactory<Dependencies>,
   ) => void;
 
   /** Register canDeactivate handler for a route */
   addDeactivateGuard: (
     name: string,
-    handler: ActivationFnFactory<Dependencies>,
+    handler: GuardFnFactory<Dependencies>,
   ) => void;
 
   /** Create state object */

package/src/namespaces/index.ts

@@ -12,8 +12,6 @@ export {
 
 export { StateNamespace } from "./StateNamespace";
 
-export { MiddlewareNamespace } from "./MiddlewareNamespace";
-
 export {
   PluginsNamespace,
   EVENTS_MAP,

package/src/transitionPath.ts

@@ -1,6 +1,6 @@
-// packages/real-router/modules/transitionPath.ts
+// packages/core/src/transitionPath.ts
 
-import type { Params, State } from "@real-router/types";
+import type { State } from "@real-router/types";
 
 /**
  * Parameters extracted from a route segment.
@@ -99,19 +99,7 @@ function extractSegmentParams(name: string, state: State): SegmentParams {
 
   const result: SegmentParams = {};
 
-  for (const key in keys as Params) {
-    // Skip inherited properties
-    if (!Object.hasOwn(keys, key)) {
-      continue;
-    }
-
-    // Skip undefined values for consistent behavior (treat { key: undefined } same as missing key)
-    // Edge case: can appear from manual State creation or object merging
-    // @ts-expect-error Params type doesn't allow undefined, but it can appear at runtime
-    if (keys[key] === undefined) {
-      continue;
-    }
-
+  for (const key of Object.keys(keys)) {
     const value = state.params[key];
 
     // Skip null/undefined values
@@ -166,15 +154,9 @@ function pointOfDifference(
     const toParams = extractSegmentParams(toSegment, toState);
     const fromParams = extractSegmentParams(fromSegment, fromState);
 
-    // Fast check: different number of parameters
+    // Compare parameter values
     const toKeys = Object.keys(toParams);
-    const fromKeys = Object.keys(fromParams);
 
-    if (toKeys.length !== fromKeys.length) {
-      return i;
-    }
-
-    // Detailed check: compare parameter values
     for (const key of toKeys) {
       if (toParams[key] !== fromParams[key]) {
         return i;
@@ -384,24 +366,6 @@ export function getTransitionPath(
     };
   }
 
-  // ===== FAST PATH 4: Same routes with empty meta.params =====
-  // If both have empty meta.params {}, no parameter checking needed
-  if (toState.name === fromState.name && toHasMeta && fromHasMeta) {
-    const toParamsEmpty =
-      toState.meta && Object.keys(toState.meta.params).length === 0;
-    const fromParamsEmpty =
-      fromState.meta && Object.keys(fromState.meta.params).length === 0;
-
-    if (toParamsEmpty && fromParamsEmpty) {
-      // Both have empty params - no transition needed
-      return {
-        intersection: toState.name,
-        toActivate: [],
-        toDeactivate: [],
-      };
-    }
-  }
-
   // ===== STANDARD PATH: Routes with parameters =====
   // Use original algorithm for complex cases with parameters
   const toStateIds = nameToIDs(toState.name);