@real-router/types 0.10.0 → 0.12.0

package/dist/cjs/index.d.ts

@@ -40,16 +40,29 @@ interface RouteTreeState<P extends Record<string, unknown> = RouteParams> {
 }
 
 type Unsubscribe = () => void;
-type CancelFn = () => void;
 interface SimpleState<P extends Params = Params> {
     name: string;
     params: P;
 }
+type TransitionPhase = "deactivating" | "activating" | "middleware";
+type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+interface TransitionMeta {
+    phase: TransitionPhase;
+    from?: string;
+    reason: TransitionReason;
+    blocker?: string;
+    segments: {
+        deactivated: string[];
+        activated: string[];
+        intersection: string;
+    };
+}
 interface State<P extends Params = Params, MP extends Params = Params> {
     name: string;
     params: P;
     path: string;
     meta?: StateMeta<MP> | undefined;
+    transition?: TransitionMeta | undefined;
 }
 interface StateMeta<P extends Params = Params> {
     id: number;
@@ -82,7 +95,6 @@ interface RouterError extends Error {
     getField: (key: string) => unknown;
     toJSON: () => Record<string, unknown>;
 }
-type DoneFn = (error?: RouterError, state?: State) => void;
 /**
  * Configuration options that control navigation transition behavior.
  *
@@ -282,6 +294,13 @@ interface LimitsConfig {
      * @default 10000
      */
     maxListeners: number;
+    /**
+     * Listener count at which a memory leak warning is logged per event type.
+     * Set to 0 to disable the warning.
+     *
+     * @default 1000
+     */
+    warnListeners: number;
     /**
      * Maximum depth of nested event propagation.
      * Prevents infinite recursion in event handling chains.
@@ -415,7 +434,7 @@ interface Options {
      */
     noValidate?: boolean;
 }
-type ActivationFn = (toState: State, fromState: State | undefined, done: DoneFn) => boolean | Promise<boolean | object | void> | State | void;
+type ActivationFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean | State | void> | State | void;
 type DefaultDependencies = object;
 interface Config {
     decoders: Record<string, (params: Params) => Params>;
@@ -457,7 +476,7 @@ interface Subscription {
  * For full router access, use the Router interface directly or the useRouter() hook.
  */
 interface Navigator {
-    navigate: (routeName: string, routeParamsOrDone?: Params | DoneFn, optionsOrDone?: NavigationOptions | DoneFn, done?: DoneFn) => CancelFn;
+    navigate: (routeName: string, routeParams?: Params, options?: NavigationOptions) => Promise<State>;
     getState: () => State | undefined;
     isActiveRoute: (name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
     canNavigateTo: (name: string, params?: Params) => boolean;
@@ -513,6 +532,15 @@ interface Router {
      * @returns true if navigation is allowed, false otherwise
      */
     canNavigateTo: (name: string, params?: Params) => boolean;
+    /**
+     * 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
+     * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
+     * call multiple times.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -530,11 +558,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";
+type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED";
 /**
  * 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";
+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";
 /**
  * Mapping of event keys to plugin methods
  */
@@ -570,6 +598,7 @@ interface ErrorCodeToValueMap {
     CANNOT_ACTIVATE: "CANNOT_ACTIVATE";
     TRANSITION_ERR: "TRANSITION_ERR";
     TRANSITION_CANCELLED: "CANCELLED";
+    ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, CancelFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DoneFn, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };
+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, 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":1248,"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":1283,"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

@@ -40,16 +40,29 @@ interface RouteTreeState<P extends Record<string, unknown> = RouteParams> {
 }
 
 type Unsubscribe = () => void;
-type CancelFn = () => void;
 interface SimpleState<P extends Params = Params> {
     name: string;
     params: P;
 }
+type TransitionPhase = "deactivating" | "activating" | "middleware";
+type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+interface TransitionMeta {
+    phase: TransitionPhase;
+    from?: string;
+    reason: TransitionReason;
+    blocker?: string;
+    segments: {
+        deactivated: string[];
+        activated: string[];
+        intersection: string;
+    };
+}
 interface State<P extends Params = Params, MP extends Params = Params> {
     name: string;
     params: P;
     path: string;
     meta?: StateMeta<MP> | undefined;
+    transition?: TransitionMeta | undefined;
 }
 interface StateMeta<P extends Params = Params> {
     id: number;
@@ -82,7 +95,6 @@ interface RouterError extends Error {
     getField: (key: string) => unknown;
     toJSON: () => Record<string, unknown>;
 }
-type DoneFn = (error?: RouterError, state?: State) => void;
 /**
  * Configuration options that control navigation transition behavior.
  *
@@ -282,6 +294,13 @@ interface LimitsConfig {
      * @default 10000
      */
     maxListeners: number;
+    /**
+     * Listener count at which a memory leak warning is logged per event type.
+     * Set to 0 to disable the warning.
+     *
+     * @default 1000
+     */
+    warnListeners: number;
     /**
      * Maximum depth of nested event propagation.
      * Prevents infinite recursion in event handling chains.
@@ -415,7 +434,7 @@ interface Options {
      */
     noValidate?: boolean;
 }
-type ActivationFn = (toState: State, fromState: State | undefined, done: DoneFn) => boolean | Promise<boolean | object | void> | State | void;
+type ActivationFn = (toState: State, fromState: State | undefined) => boolean | Promise<boolean | State | void> | State | void;
 type DefaultDependencies = object;
 interface Config {
     decoders: Record<string, (params: Params) => Params>;
@@ -457,7 +476,7 @@ interface Subscription {
  * For full router access, use the Router interface directly or the useRouter() hook.
  */
 interface Navigator {
-    navigate: (routeName: string, routeParamsOrDone?: Params | DoneFn, optionsOrDone?: NavigationOptions | DoneFn, done?: DoneFn) => CancelFn;
+    navigate: (routeName: string, routeParams?: Params, options?: NavigationOptions) => Promise<State>;
     getState: () => State | undefined;
     isActiveRoute: (name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
     canNavigateTo: (name: string, params?: Params) => boolean;
@@ -513,6 +532,15 @@ interface Router {
      * @returns true if navigation is allowed, false otherwise
      */
     canNavigateTo: (name: string, params?: Params) => boolean;
+    /**
+     * 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
+     * mutating methods throw a ROUTER_DISPOSED error. Idempotent — safe to
+     * call multiple times.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -530,11 +558,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";
+type ErrorCodeValues = "NOT_STARTED" | "NO_START_PATH_OR_STATE" | "ALREADY_STARTED" | "ROUTE_NOT_FOUND" | "SAME_STATES" | "CANNOT_DEACTIVATE" | "CANNOT_ACTIVATE" | "TRANSITION_ERR" | "CANCELLED" | "DISPOSED";
 /**
  * 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";
+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";
 /**
  * Mapping of event keys to plugin methods
  */
@@ -570,6 +598,7 @@ interface ErrorCodeToValueMap {
     CANNOT_ACTIVATE: "CANNOT_ACTIVATE";
     TRANSITION_ERR: "TRANSITION_ERR";
     TRANSITION_CANCELLED: "CANCELLED";
+    ROUTER_DISPOSED: "DISPOSED";
 }
 
-export type { ActivationFn, CancelFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DoneFn, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };
+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, 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":1248,"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":1283,"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.10.0",
+  "version": "0.12.0",
   "type": "commonjs",
   "description": "Shared TypeScript types for Real Router ecosystem",
   "types": "./dist/esm/index.d.mts",