@real-router/core 0.23.0 → 0.24.0

package/src/namespaces/PluginsNamespace/PluginsNamespace.ts

@@ -219,6 +219,13 @@ export class PluginsNamespace<
     return this.#plugins.has(factory);
   }
 
+  /**
+   * 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).
+   * Named "dispose" (not "clear") because there is active cleanup to perform.
+   */
   disposeAll(): void {
     for (const unsubscribe of this.#unsubscribes) {
       unsubscribe();
@@ -244,9 +251,17 @@ export class PluginsNamespace<
     const { warn, error } = computeThresholds(maxPlugins);
 
     if (totalCount >= error) {
-      logger.error(LOGGER_CONTEXT, `${totalCount} plugins registered!`);
+      logger.error(
+        LOGGER_CONTEXT,
+        `${totalCount} plugins registered! ` +
+          `This is excessive and will impact performance. ` +
+          `Hard limit at ${maxPlugins}.`,
+      );
     } else if (totalCount >= warn) {
-      logger.warn(LOGGER_CONTEXT, `${totalCount} plugins registered`);
+      logger.warn(
+        LOGGER_CONTEXT,
+        `${totalCount} plugins registered. ` + `Consider if all are necessary.`,
+      );
     }
   }
 

package/src/namespaces/PluginsNamespace/validators.ts

@@ -19,10 +19,10 @@ import type { DefaultDependencies, Plugin } from "@real-router/types";
 export function validateUsePluginArgs<D extends DefaultDependencies>(
   plugins: unknown[],
 ): asserts plugins is PluginFactory<D>[] {
-  for (const plugin of plugins) {
+  for (const [i, plugin] of plugins.entries()) {
     if (typeof plugin !== "function") {
       throw new TypeError(
-        `[router.usePlugin] Expected plugin factory function, got ${typeof plugin}`,
+        `[router.usePlugin] Expected plugin factory function at index ${i}, got ${getTypeDescription(plugin)}`,
       );
     }
   }
@@ -74,6 +74,10 @@ export function validatePluginLimit(
   const totalCount = currentCount + newCount;
 
   if (totalCount > maxPlugins) {
-    throw new Error(`[router.usePlugin] Plugin limit exceeded (${maxPlugins})`);
+    throw new Error(
+      `[router.usePlugin] Plugin limit exceeded (${maxPlugins}). ` +
+        `Current: ${currentCount}, Attempting to add: ${newCount}. ` +
+        `This indicates an architectural problem. Consider consolidating plugins.`,
+    );
   }
 }

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, ` +

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";
@@ -85,14 +85,14 @@ export class RoutesNamespace<
   // 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 = "";

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/typeGuards.ts

@@ -11,7 +11,6 @@ export {
   isState,
   isParams,
   isNavigationOptions,
-  isPromise,
   isBoolean,
   validateRouteName,
 } from "type-guards";

package/src/types.ts

@@ -14,6 +14,7 @@ import type {
   DefaultDependencies,
   EventsKeys,
   ForwardToCallback,
+  GuardFn,
   LimitsConfig,
   Middleware,
   NavigationOptions,
@@ -81,9 +82,9 @@ export interface Route<
   /** URL path pattern for this route. */
   path: string;
   /** Factory function that returns a guard for route activation. */
-  canActivate?: ActivationFnFactory<Dependencies>;
+  canActivate?: GuardFnFactory<Dependencies>;
   /** Factory function that returns a guard for route deactivation. */
-  canDeactivate?: ActivationFnFactory<Dependencies>;
+  canDeactivate?: GuardFnFactory<Dependencies>;
   /**
    * Redirects navigation to another route.
    *
@@ -155,9 +156,9 @@ export interface RouteConfigUpdate<
   /** Set to null to remove encoder */
   encodeParams?: ((params: Params) => Params) | null;
   /** Set to null to remove canActivate */
-  canActivate?: ActivationFnFactory<Dependencies> | null;
+  canActivate?: GuardFnFactory<Dependencies> | null;
   /** Set to null to remove canDeactivate */
-  canDeactivate?: ActivationFnFactory<Dependencies> | null;
+  canDeactivate?: GuardFnFactory<Dependencies> | null;
 }
 
 /**
@@ -171,6 +172,17 @@ export type ActivationFnFactory<
   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 middleware.
  * Receives the router instance and a dependency getter.