@real-router/types 0.13.0 → 0.15.0

package/dist/cjs/index.d.ts

@@ -44,7 +44,7 @@ interface SimpleState<P extends Params = Params> {
     name: string;
     params: P;
 }
-type TransitionPhase = "deactivating" | "activating" | "middleware";
+type TransitionPhase = "deactivating" | "activating";
 type TransitionReason = "success" | "blocked" | "cancelled" | "error";
 interface TransitionMeta {
     phase: TransitionPhase;
@@ -103,7 +103,7 @@ interface RouterError extends Error {
  *
  * All options are optional and have sensible defaults. Options can be combined to achieve
  * complex navigation behaviors. The options object is stored in state.meta.options and is
- * available to middleware, guards, and event listeners.
+ * available to guards and event listeners.
  *
  * @see {@link Router.navigate} for navigation method that accepts these options
  * @see {@link State.meta} for where options are stored after navigation
@@ -137,11 +137,11 @@ interface NavigationOptions {
      *
      * Without `reload`:
      * - Navigation to current route throws SAME_STATES error
-     * - No lifecycle hooks or middleware execute
+     * - No lifecycle hooks execute
      * - No events are fired
      *
      * With `reload`:
-     * - Full transition executes (deactivate → activate → middleware)
+     * - Full transition executes (deactivate → activate)
      * - All lifecycle hooks run again
      * - TRANSITION_SUCCESS event fires with same state
      * - State object is recreated (new reference)
@@ -192,16 +192,16 @@ interface NavigationOptions {
      *
      * @description
      * When `true`, bypasses only the canDeactivate lifecycle hooks for segments being
-     * deactivated. canActivate guards and middleware still execute normally. This allows
+     * deactivated. canActivate guards still execute normally. This allows
      * forcing navigation away from routes with confirmation dialogs or unsaved changes.
      *
      * Skipped vs executed:
      * ```
      * // Normal transition
-     * deactivate(fromSegments) → activate(toSegments) → middleware → success
+     * deactivate(fromSegments) → activate(toSegments) → success
      *
      * // With forceDeactivate: true
-     * [skip deactivate] → activate(toSegments) → middleware → success
+     * [skip deactivate] → activate(toSegments) → success
      * ```
      *
      * ⚠️ Data loss risk: Bypassing canDeactivate means unsaved changes will be lost
@@ -227,21 +227,12 @@ interface NavigationOptions {
      *
      * @description
      * Automatically set by the router when a navigation is triggered by a redirect from
-     * middleware or lifecycle hooks. This flag is used internally to track redirect chains
+     * guards or lifecycle hooks. This flag is used internally to track redirect chains
      * and is stored in state.meta.options.redirected.
      *
      * @default false (auto-set by router during redirects)
      *
      * @example
-     * // Middleware triggers automatic redirect
-     * router.useMiddleware((toState, fromState, opts) => {
-     *   if (!isAuthenticated && toState.name !== 'login') {
-     *     // Router will automatically set redirected: true
-     *     return { name: 'login', params: { next: toState.path } };
-     *   }
-     * });
-     *
-     * @example
      * // Accessing redirect flag in lifecycle
      * router.addActivateGuard('dashboard', (toState, fromState) => {
      *   if (toState.meta?.options?.redirected) {
@@ -278,13 +269,6 @@ interface LimitsConfig {
      * @default 50
      */
     maxPlugins: number;
-    /**
-     * Maximum number of middleware functions in the navigation pipeline.
-     * Controls middleware chain length to prevent stack overflow and performance issues.
-     *
-     * @default 50
-     */
-    maxMiddleware: number;
     /**
      * Maximum number of event listeners per event type.
      * Prevents memory leaks from excessive listener registration.
@@ -319,7 +303,7 @@ interface LimitsConfig {
  * Base router types without Router class dependency.
  *
  * Router-dependent types (Route, RouteConfigUpdate, ActivationFnFactory,
- * MiddlewareFactory, PluginFactory) are defined in @real-router/core
+ * PluginFactory) are defined in @real-router/core
  * to avoid circular dependencies.
  */
 
@@ -433,6 +417,7 @@ interface Options {
     noValidate?: boolean;
 }
 type ActivationFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean | State | void> | State | void;
+type GuardFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean>;
 type DefaultDependencies = object;
 interface Config {
     decoders: Record<string, (params: Params) => Params>;
@@ -449,7 +434,6 @@ interface Plugin {
     onTransitionSuccess?: (toState: State, fromState: State | undefined, opts: NavigationOptions) => void;
     teardown?: () => void;
 }
-type Middleware = ActivationFn;
 interface SubscribeState {
     route: State;
     previousRoute?: State | undefined;
@@ -486,9 +470,9 @@ interface Navigator {
  * Defines the contract for router implementations. The actual Router class in
  * @real-router/core implements this interface with full functionality.
  *
- * This interface uses `ActivationFn | boolean` for guard types to avoid circular
+ * This interface uses `GuardFn | boolean` for guard types to avoid circular
  * dependencies. The concrete Router class in @real-router/core narrows this to
- * `ActivationFnFactory | boolean` for more precise type checking.
+ * `GuardFnFactory | boolean` for more precise type checking.
  */
 interface Router {
     /**
@@ -498,7 +482,7 @@ interface Router {
      * @param guard - Guard function or boolean
      * @returns this for method chaining
      */
-    addActivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    addActivateGuard: (name: string, guard: GuardFn | boolean) => this;
     /**
      * Register a deactivation guard for a route.
      *
@@ -506,7 +490,7 @@ interface Router {
      * @param guard - Guard function or boolean
      * @returns this for method chaining
      */
-    addDeactivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    addDeactivateGuard: (name: string, guard: GuardFn | boolean) => this;
     /**
      * Remove an activation guard from a route.
      *
@@ -534,7 +518,7 @@ interface Router {
      * Dispose the router and release all resources.
      *
      * Stops the router if active, calls plugin teardown, clears all event
-     * listeners, middleware, routes, and dependencies. After disposal, all
+     * listeners, routes, and dependencies. After disposal, all
      * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
      * call multiple times.
      */
@@ -599,4 +583,4 @@ interface ErrorCodeToValueMap {
     ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };

package/dist/cjs/metafile-cjs.json

@@ -1 +1 @@
-{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/index.ts":{"bytes":1298,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}
+{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/index.ts":{"bytes":1276,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}

package/dist/esm/index.d.mts

@@ -44,7 +44,7 @@ interface SimpleState<P extends Params = Params> {
     name: string;
     params: P;
 }
-type TransitionPhase = "deactivating" | "activating" | "middleware";
+type TransitionPhase = "deactivating" | "activating";
 type TransitionReason = "success" | "blocked" | "cancelled" | "error";
 interface TransitionMeta {
     phase: TransitionPhase;
@@ -103,7 +103,7 @@ interface RouterError extends Error {
  *
  * All options are optional and have sensible defaults. Options can be combined to achieve
  * complex navigation behaviors. The options object is stored in state.meta.options and is
- * available to middleware, guards, and event listeners.
+ * available to guards and event listeners.
  *
  * @see {@link Router.navigate} for navigation method that accepts these options
  * @see {@link State.meta} for where options are stored after navigation
@@ -137,11 +137,11 @@ interface NavigationOptions {
      *
      * Without `reload`:
      * - Navigation to current route throws SAME_STATES error
-     * - No lifecycle hooks or middleware execute
+     * - No lifecycle hooks execute
      * - No events are fired
      *
      * With `reload`:
-     * - Full transition executes (deactivate → activate → middleware)
+     * - Full transition executes (deactivate → activate)
      * - All lifecycle hooks run again
      * - TRANSITION_SUCCESS event fires with same state
      * - State object is recreated (new reference)
@@ -192,16 +192,16 @@ interface NavigationOptions {
      *
      * @description
      * When `true`, bypasses only the canDeactivate lifecycle hooks for segments being
-     * deactivated. canActivate guards and middleware still execute normally. This allows
+     * deactivated. canActivate guards still execute normally. This allows
      * forcing navigation away from routes with confirmation dialogs or unsaved changes.
      *
      * Skipped vs executed:
      * ```
      * // Normal transition
-     * deactivate(fromSegments) → activate(toSegments) → middleware → success
+     * deactivate(fromSegments) → activate(toSegments) → success
      *
      * // With forceDeactivate: true
-     * [skip deactivate] → activate(toSegments) → middleware → success
+     * [skip deactivate] → activate(toSegments) → success
      * ```
      *
      * ⚠️ Data loss risk: Bypassing canDeactivate means unsaved changes will be lost
@@ -227,21 +227,12 @@ interface NavigationOptions {
      *
      * @description
      * Automatically set by the router when a navigation is triggered by a redirect from
-     * middleware or lifecycle hooks. This flag is used internally to track redirect chains
+     * guards or lifecycle hooks. This flag is used internally to track redirect chains
      * and is stored in state.meta.options.redirected.
      *
      * @default false (auto-set by router during redirects)
      *
      * @example
-     * // Middleware triggers automatic redirect
-     * router.useMiddleware((toState, fromState, opts) => {
-     *   if (!isAuthenticated && toState.name !== 'login') {
-     *     // Router will automatically set redirected: true
-     *     return { name: 'login', params: { next: toState.path } };
-     *   }
-     * });
-     *
-     * @example
      * // Accessing redirect flag in lifecycle
      * router.addActivateGuard('dashboard', (toState, fromState) => {
      *   if (toState.meta?.options?.redirected) {
@@ -278,13 +269,6 @@ interface LimitsConfig {
      * @default 50
      */
     maxPlugins: number;
-    /**
-     * Maximum number of middleware functions in the navigation pipeline.
-     * Controls middleware chain length to prevent stack overflow and performance issues.
-     *
-     * @default 50
-     */
-    maxMiddleware: number;
     /**
      * Maximum number of event listeners per event type.
      * Prevents memory leaks from excessive listener registration.
@@ -319,7 +303,7 @@ interface LimitsConfig {
  * Base router types without Router class dependency.
  *
  * Router-dependent types (Route, RouteConfigUpdate, ActivationFnFactory,
- * MiddlewareFactory, PluginFactory) are defined in @real-router/core
+ * PluginFactory) are defined in @real-router/core
  * to avoid circular dependencies.
  */
 
@@ -433,6 +417,7 @@ interface Options {
     noValidate?: boolean;
 }
 type ActivationFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean | State | void> | State | void;
+type GuardFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean>;
 type DefaultDependencies = object;
 interface Config {
     decoders: Record<string, (params: Params) => Params>;
@@ -449,7 +434,6 @@ interface Plugin {
     onTransitionSuccess?: (toState: State, fromState: State | undefined, opts: NavigationOptions) => void;
     teardown?: () => void;
 }
-type Middleware = ActivationFn;
 interface SubscribeState {
     route: State;
     previousRoute?: State | undefined;
@@ -486,9 +470,9 @@ interface Navigator {
  * Defines the contract for router implementations. The actual Router class in
  * @real-router/core implements this interface with full functionality.
  *
- * This interface uses `ActivationFn | boolean` for guard types to avoid circular
+ * This interface uses `GuardFn | boolean` for guard types to avoid circular
  * dependencies. The concrete Router class in @real-router/core narrows this to
- * `ActivationFnFactory | boolean` for more precise type checking.
+ * `GuardFnFactory | boolean` for more precise type checking.
  */
 interface Router {
     /**
@@ -498,7 +482,7 @@ interface Router {
      * @param guard - Guard function or boolean
      * @returns this for method chaining
      */
-    addActivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    addActivateGuard: (name: string, guard: GuardFn | boolean) => this;
     /**
      * Register a deactivation guard for a route.
      *
@@ -506,7 +490,7 @@ interface Router {
      * @param guard - Guard function or boolean
      * @returns this for method chaining
      */
-    addDeactivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    addDeactivateGuard: (name: string, guard: GuardFn | boolean) => this;
     /**
      * Remove an activation guard from a route.
      *
@@ -534,7 +518,7 @@ interface Router {
      * Dispose the router and release all resources.
      *
      * Stops the router if active, calls plugin teardown, clears all event
-     * listeners, middleware, routes, and dependencies. After disposal, all
+     * listeners, routes, and dependencies. After disposal, all
      * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
      * call multiple times.
      */
@@ -599,4 +583,4 @@ interface ErrorCodeToValueMap {
     ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+export type { ActivationFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteParams, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };

package/dist/esm/metafile-esm.json

@@ -1 +1 @@
-{"inputs":{"src/index.ts":{"bytes":1298,"imports":[],"format":"esm"}},"outputs":{"dist/esm/index.mjs":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}
+{"inputs":{"src/index.ts":{"bytes":1276,"imports":[],"format":"esm"}},"outputs":{"dist/esm/index.mjs":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/types",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "commonjs",
   "description": "Shared TypeScript types for Real Router ecosystem",
   "types": "./dist/esm/index.d.mts",

package/src/base.ts

@@ -11,7 +11,7 @@ export interface SimpleState<P extends Params = Params> {
   params: P;
 }
 
-export type TransitionPhase = "deactivating" | "activating" | "middleware";
+export type TransitionPhase = "deactivating" | "activating";
 
 export type TransitionReason = "success" | "blocked" | "cancelled" | "error";
 
@@ -80,7 +80,7 @@ export interface RouterError extends Error {
  *
  * All options are optional and have sensible defaults. Options can be combined to achieve
  * complex navigation behaviors. The options object is stored in state.meta.options and is
- * available to middleware, guards, and event listeners.
+ * available to guards and event listeners.
  *
  * @see {@link Router.navigate} for navigation method that accepts these options
  * @see {@link State.meta} for where options are stored after navigation
@@ -121,11 +121,11 @@ export interface NavigationOptions {
    *
    * Without `reload`:
    * - Navigation to current route throws SAME_STATES error
-   * - No lifecycle hooks or middleware execute
+   * - No lifecycle hooks execute
    * - No events are fired
    *
    * With `reload`:
-   * - Full transition executes (deactivate → activate → middleware)
+   * - Full transition executes (deactivate → activate)
    * - All lifecycle hooks run again
    * - TRANSITION_SUCCESS event fires with same state
    * - State object is recreated (new reference)
@@ -178,16 +178,16 @@ export interface NavigationOptions {
    *
    * @description
    * When `true`, bypasses only the canDeactivate lifecycle hooks for segments being
-   * deactivated. canActivate guards and middleware still execute normally. This allows
+   * deactivated. canActivate guards still execute normally. This allows
    * forcing navigation away from routes with confirmation dialogs or unsaved changes.
    *
    * Skipped vs executed:
    * ```
    * // Normal transition
-   * deactivate(fromSegments) → activate(toSegments) → middleware → success
+   * deactivate(fromSegments) → activate(toSegments) → success
    *
    * // With forceDeactivate: true
-   * [skip deactivate] → activate(toSegments) → middleware → success
+   * [skip deactivate] → activate(toSegments) → success
    * ```
    *
    * ⚠️ Data loss risk: Bypassing canDeactivate means unsaved changes will be lost
@@ -214,21 +214,12 @@ export interface NavigationOptions {
    *
    * @description
    * Automatically set by the router when a navigation is triggered by a redirect from
-   * middleware or lifecycle hooks. This flag is used internally to track redirect chains
+   * guards or lifecycle hooks. This flag is used internally to track redirect chains
    * and is stored in state.meta.options.redirected.
    *
    * @default false (auto-set by router during redirects)
    *
    * @example
-   * // Middleware triggers automatic redirect
-   * router.useMiddleware((toState, fromState, opts) => {
-   *   if (!isAuthenticated && toState.name !== 'login') {
-   *     // Router will automatically set redirected: true
-   *     return { name: 'login', params: { next: toState.path } };
-   *   }
-   * });
-   *
-   * @example
    * // Accessing redirect flag in lifecycle
    * router.addActivateGuard('dashboard', (toState, fromState) => {
    *   if (toState.meta?.options?.redirected) {

package/src/index.ts

@@ -24,7 +24,7 @@ export type {
 } from "./base";
 
 // Router types (base types without Router dependency)
-// Note: Route, RouteConfigUpdate, ActivationFnFactory, MiddlewareFactory,
+// Note: Route, RouteConfigUpdate, ActivationFnFactory,
 // PluginFactory, BuildStateResultWithSegments are in @real-router/core
 export type {
   Options,
@@ -32,10 +32,10 @@ export type {
   ForwardToCallback,
   DefaultParamsCallback,
   ActivationFn,
+  GuardFn,
   DefaultDependencies,
   Config,
   Plugin,
-  Middleware,
   SubscribeState,
   SubscribeFn,
   Listener,

package/src/limits.ts

@@ -19,14 +19,6 @@ export interface LimitsConfig {
    */
   maxPlugins: number;
 
-  /**
-   * Maximum number of middleware functions in the navigation pipeline.
-   * Controls middleware chain length to prevent stack overflow and performance issues.
-   *
-   * @default 50
-   */
-  maxMiddleware: number;
-
   /**
    * Maximum number of event listeners per event type.
    * Prevents memory leaks from excessive listener registration.

package/src/router.ts

@@ -4,7 +4,7 @@
  * Base router types without Router class dependency.
  *
  * Router-dependent types (Route, RouteConfigUpdate, ActivationFnFactory,
- * MiddlewareFactory, PluginFactory) are defined in @real-router/core
+ * PluginFactory) are defined in @real-router/core
  * to avoid circular dependencies.
  */
 
@@ -161,6 +161,11 @@ export type ActivationFn = (
   // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
 ) => boolean | Promise<boolean | State | void> | State | void;
 
+export type GuardFn = (
+  toState: State,
+  fromState: State | undefined,
+) => boolean | Promise<boolean>;
+
 export type DefaultDependencies = object;
 
 export interface Config {
@@ -188,9 +193,6 @@ export interface Plugin {
   teardown?: () => void;
 }
 
-// eslint-disable-next-line sonarjs/redundant-type-aliases
-export type Middleware = ActivationFn;
-
 export interface SubscribeState {
   route: State;
   previousRoute?: State | undefined;
@@ -241,9 +243,9 @@ export interface Navigator {
  * Defines the contract for router implementations. The actual Router class in
  * @real-router/core implements this interface with full functionality.
  *
- * This interface uses `ActivationFn | boolean` for guard types to avoid circular
+ * This interface uses `GuardFn | boolean` for guard types to avoid circular
  * dependencies. The concrete Router class in @real-router/core narrows this to
- * `ActivationFnFactory | boolean` for more precise type checking.
+ * `GuardFnFactory | boolean` for more precise type checking.
  */
 export interface Router {
   /**
@@ -253,7 +255,7 @@ export interface Router {
    * @param guard - Guard function or boolean
    * @returns this for method chaining
    */
-  addActivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+  addActivateGuard: (name: string, guard: GuardFn | boolean) => this;
 
   /**
    * Register a deactivation guard for a route.
@@ -262,7 +264,7 @@ export interface Router {
    * @param guard - Guard function or boolean
    * @returns this for method chaining
    */
-  addDeactivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+  addDeactivateGuard: (name: string, guard: GuardFn | boolean) => this;
 
   /**
    * Remove an activation guard from a route.
@@ -294,7 +296,7 @@ export interface Router {
    * Dispose the router and release all resources.
    *
    * Stops the router if active, calls plugin teardown, clears all event
-   * listeners, middleware, routes, and dependencies. After disposal, all
+   * listeners, routes, and dependencies. After disposal, all
    * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
    * call multiple times.
    */