@real-router/types 0.20.0 → 0.21.0

package/dist/cjs/index.d.ts

@@ -631,6 +631,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 +660,11 @@ 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;
 }
 /**
  * Routes API — for dynamic route mutation.
@@ -688,4 +703,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

@@ -631,6 +631,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 +660,11 @@ 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;
 }
 /**
  * Routes API — for dynamic route mutation.
@@ -688,4 +703,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.21.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,20 +87,9 @@ 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;
 }
 

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