@real-router/types 0.20.0 → 0.22.0

package/dist/cjs/index.d.ts

@@ -576,11 +576,11 @@ type EventsKeys = "ROUTER_START" | "ROUTER_STOP" | "TRANSITION_START" | "TRANSIT
 /**
  * Error code values
  */
-type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED";
+type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED" | "PLUGIN_CONFLICT";
 /**
  * Error code keys
  */
-type ErrorCodeKeys = "ROUTER_NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ROUTER_ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "TRANSITION_CANCELLED" | "ROUTER_DISPOSED";
+type ErrorCodeKeys = "ROUTER_NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ROUTER_ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "TRANSITION_CANCELLED" | "ROUTER_DISPOSED" | "PLUGIN_CONFLICT";
 /**
  * Mapping of event keys to plugin methods
  */
@@ -624,6 +624,7 @@ interface ErrorCodeToValueMap {
     TRANSITION_ERR: "TRANSITION_ERR";
     TRANSITION_CANCELLED: "CANCELLED";
     ROUTER_DISPOSED: "DISPOSED";
+    PLUGIN_CONFLICT: "PLUGIN_CONFLICT";
 }
 
 /**
@@ -631,6 +632,24 @@ interface ErrorCodeToValueMap {
  * These interfaces are implemented by standalone API functions in @real-router/core.
  */
 
+/**
+ * Maps interceptable method names to their signatures.
+ * Used by {@link PluginApi.addInterceptor} to provide type-safe interceptor registration.
+ *
+ * To add a new interceptable method:
+ * 1. Add its signature here
+ * 2. Wrap it with `createInterceptable()` in `RouterWiringBuilder`
+ */
+interface InterceptableMethodMap {
+    start: (path?: string) => Promise<State>;
+    buildPath: (route: string, params?: Params) => string;
+    forwardState: (routeName: string, routeParams: Params) => SimpleState;
+}
+/**
+ * Type-safe interceptor callback.
+ * Receives `next` (the next function in the chain) followed by the method's original parameters.
+ */
+type InterceptorFn<M extends keyof InterceptableMethodMap> = (next: InterceptableMethodMap[M], ...args: Parameters<InterceptableMethodMap[M]>) => ReturnType<InterceptableMethodMap[M]>;
 /**
  * Plugin API — for plugins and infrastructure packages.
  * Hides plugin-internal methods from public autocomplete.
@@ -642,14 +661,12 @@ interface PluginApi {
     matchPath: <P extends Params = Params, MP extends Params = Params>(path: string) => State<P, MP> | undefined;
     setRootPath: (rootPath: string) => void;
     getRootPath: () => string;
-    navigateToState: (toState: State, fromState: State | undefined, opts: NavigationOptions) => Promise<State>;
     addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
     buildNavigationState: (name: string, params?: Params) => State | undefined;
     getOptions: () => Options;
     getTree: () => unknown;
-    getForwardState: () => <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
-    setForwardState: (fn: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>) => void;
-    addBuildPathInterceptor: (fn: (routeName: string, params: Params) => Params) => Unsubscribe;
+    addInterceptor: <M extends keyof InterceptableMethodMap>(method: M, fn: InterceptorFn<M>) => Unsubscribe;
+    extendRouter: (extensions: Record<string, unknown>) => Unsubscribe;
 }
 /**
  * Routes API — for dynamic route mutation.
@@ -688,4 +705,4 @@ interface LifecycleApi<Dependencies extends DefaultDependencies = DefaultDepende
     removeDeactivateGuard: (name: string) => void;
 }
 
-export type { Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DependenciesApi, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, GuardFnFactory, LifecycleApi, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, PluginMethod, QueryParamsMode, QueryParamsOptions, Route, RouteConfigUpdate, RouteParams, RouteTreeState, Router, RouterError, RoutesApi, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+export type { Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DependenciesApi, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, GuardFnFactory, InterceptableMethodMap, InterceptorFn, LifecycleApi, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, PluginMethod, QueryParamsMode, QueryParamsOptions, Route, RouteConfigUpdate, RouteParams, RouteTreeState, Router, RouterError, RoutesApi, 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":1349,"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":1392,"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

@@ -576,11 +576,11 @@ type EventsKeys = "ROUTER_START" | "ROUTER_STOP" | "TRANSITION_START" | "TRANSIT
 /**
  * Error code values
  */
-type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED";
+type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED" | "PLUGIN_CONFLICT";
 /**
  * Error code keys
  */
-type ErrorCodeKeys = "ROUTER_NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ROUTER_ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "TRANSITION_CANCELLED" | "ROUTER_DISPOSED";
+type ErrorCodeKeys = "ROUTER_NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ROUTER_ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "TRANSITION_CANCELLED" | "ROUTER_DISPOSED" | "PLUGIN_CONFLICT";
 /**
  * Mapping of event keys to plugin methods
  */
@@ -624,6 +624,7 @@ interface ErrorCodeToValueMap {
     TRANSITION_ERR: "TRANSITION_ERR";
     TRANSITION_CANCELLED: "CANCELLED";
     ROUTER_DISPOSED: "DISPOSED";
+    PLUGIN_CONFLICT: "PLUGIN_CONFLICT";
 }
 
 /**
@@ -631,6 +632,24 @@ interface ErrorCodeToValueMap {
  * These interfaces are implemented by standalone API functions in @real-router/core.
  */
 
+/**
+ * Maps interceptable method names to their signatures.
+ * Used by {@link PluginApi.addInterceptor} to provide type-safe interceptor registration.
+ *
+ * To add a new interceptable method:
+ * 1. Add its signature here
+ * 2. Wrap it with `createInterceptable()` in `RouterWiringBuilder`
+ */
+interface InterceptableMethodMap {
+    start: (path?: string) => Promise<State>;
+    buildPath: (route: string, params?: Params) => string;
+    forwardState: (routeName: string, routeParams: Params) => SimpleState;
+}
+/**
+ * Type-safe interceptor callback.
+ * Receives `next` (the next function in the chain) followed by the method's original parameters.
+ */
+type InterceptorFn<M extends keyof InterceptableMethodMap> = (next: InterceptableMethodMap[M], ...args: Parameters<InterceptableMethodMap[M]>) => ReturnType<InterceptableMethodMap[M]>;
 /**
  * Plugin API — for plugins and infrastructure packages.
  * Hides plugin-internal methods from public autocomplete.
@@ -642,14 +661,12 @@ interface PluginApi {
     matchPath: <P extends Params = Params, MP extends Params = Params>(path: string) => State<P, MP> | undefined;
     setRootPath: (rootPath: string) => void;
     getRootPath: () => string;
-    navigateToState: (toState: State, fromState: State | undefined, opts: NavigationOptions) => Promise<State>;
     addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
     buildNavigationState: (name: string, params?: Params) => State | undefined;
     getOptions: () => Options;
     getTree: () => unknown;
-    getForwardState: () => <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
-    setForwardState: (fn: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>) => void;
-    addBuildPathInterceptor: (fn: (routeName: string, params: Params) => Params) => Unsubscribe;
+    addInterceptor: <M extends keyof InterceptableMethodMap>(method: M, fn: InterceptorFn<M>) => Unsubscribe;
+    extendRouter: (extensions: Record<string, unknown>) => Unsubscribe;
 }
 /**
  * Routes API — for dynamic route mutation.
@@ -688,4 +705,4 @@ interface LifecycleApi<Dependencies extends DefaultDependencies = DefaultDepende
     removeDeactivateGuard: (name: string) => void;
 }
 
-export type { Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DependenciesApi, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, GuardFnFactory, LifecycleApi, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, PluginMethod, QueryParamsMode, QueryParamsOptions, Route, RouteConfigUpdate, RouteParams, RouteTreeState, Router, RouterError, RoutesApi, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+export type { Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DependenciesApi, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, GuardFn, GuardFnFactory, InterceptableMethodMap, InterceptorFn, LifecycleApi, LimitsConfig, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, PluginMethod, QueryParamsMode, QueryParamsOptions, Route, RouteConfigUpdate, RouteParams, RouteTreeState, Router, RouterError, RoutesApi, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };

package/dist/esm/metafile-esm.json

@@ -1 +1 @@
-{"inputs":{"src/index.ts":{"bytes":1349,"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":1392,"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.20.0",
+  "version": "0.22.0",
   "type": "commonjs",
   "description": "Shared TypeScript types for Real Router ecosystem",
   "types": "./dist/esm/index.d.mts",

package/src/api.ts

@@ -10,7 +10,6 @@ import type {
   State,
   SimpleState,
   StateMetaInput,
-  NavigationOptions,
   Unsubscribe,
 } from "./base";
 import type { EventMethodMap, EventName } from "./constants";
@@ -24,6 +23,29 @@ import type {
   RouteConfigUpdate,
 } from "./router";
 
+/**
+ * Maps interceptable method names to their signatures.
+ * Used by {@link PluginApi.addInterceptor} to provide type-safe interceptor registration.
+ *
+ * To add a new interceptable method:
+ * 1. Add its signature here
+ * 2. Wrap it with `createInterceptable()` in `RouterWiringBuilder`
+ */
+export interface InterceptableMethodMap {
+  start: (path?: string) => Promise<State>;
+  buildPath: (route: string, params?: Params) => string;
+  forwardState: (routeName: string, routeParams: Params) => SimpleState;
+}
+
+/**
+ * Type-safe interceptor callback.
+ * Receives `next` (the next function in the chain) followed by the method's original parameters.
+ */
+export type InterceptorFn<M extends keyof InterceptableMethodMap> = (
+  next: InterceptableMethodMap[M],
+  ...args: Parameters<InterceptableMethodMap[M]>
+) => ReturnType<InterceptableMethodMap[M]>;
+
 /**
  * Plugin API — for plugins and infrastructure packages.
  * Hides plugin-internal methods from public autocomplete.
@@ -54,12 +76,6 @@ export interface PluginApi {
   setRootPath: (rootPath: string) => void;
   getRootPath: () => string;
 
-  navigateToState: (
-    toState: State,
-    fromState: State | undefined,
-    opts: NavigationOptions,
-  ) => Promise<State>;
-
   addEventListener: <E extends EventName>(
     eventName: E,
     cb: Plugin[EventMethodMap[E]],
@@ -71,21 +87,12 @@ export interface PluginApi {
 
   getTree: () => unknown;
 
-  getForwardState: () => <P extends Params = Params>(
-    routeName: string,
-    routeParams: P,
-  ) => SimpleState<P>;
-
-  setForwardState: (
-    fn: <P extends Params = Params>(
-      routeName: string,
-      routeParams: P,
-    ) => SimpleState<P>,
-  ) => void;
-
-  addBuildPathInterceptor: (
-    fn: (routeName: string, params: Params) => Params,
+  addInterceptor: <M extends keyof InterceptableMethodMap>(
+    method: M,
+    fn: InterceptorFn<M>,
   ) => Unsubscribe;
+
+  extendRouter: (extensions: Record<string, unknown>) => Unsubscribe;
 }
 
 /**

package/src/constants.ts

@@ -46,7 +46,8 @@ export type ErrorCodeValues =
   | "CANNOT_ACTIVATE"
   | "TRANSITION_ERR"
   | "CANCELLED"
-  | "DISPOSED";
+  | "DISPOSED"
+  | "PLUGIN_CONFLICT";
 
 /**
  * Error code keys
@@ -61,7 +62,8 @@ export type ErrorCodeKeys =
   | "CANNOT_ACTIVATE"
   | "TRANSITION_ERR"
   | "TRANSITION_CANCELLED"
-  | "ROUTER_DISPOSED";
+  | "ROUTER_DISPOSED"
+  | "PLUGIN_CONFLICT";
 
 /**
  * Mapping of event keys to plugin methods
@@ -109,4 +111,5 @@ export interface ErrorCodeToValueMap {
   TRANSITION_ERR: "TRANSITION_ERR";
   TRANSITION_CANCELLED: "CANCELLED";
   ROUTER_DISPOSED: "DISPOSED";
+  PLUGIN_CONFLICT: "PLUGIN_CONFLICT";
 }

package/src/index.ts

@@ -66,6 +66,8 @@ export type {
   RoutesApi,
   DependenciesApi,
   LifecycleApi,
+  InterceptableMethodMap,
+  InterceptorFn,
 } from "./api";
 
 // Note: RouterError type is a forward declaration matching the class in real-router package