@real-router/core 0.2.4 → 0.4.0

package/README.md

@@ -66,9 +66,9 @@ router.start("/users/123", (err, state) => {
 
 Stops the router. [Wiki](https://github.com/greydragon888/real-router/wiki/stop)
 
-#### `router.isStarted()`
+#### `router.isActive()`
 
-Returns whether the router is started. [Wiki](https://github.com/greydragon888/real-router/wiki/isStarted)
+Returns whether the router is active (started and has current state). [Wiki](https://github.com/greydragon888/real-router/wiki/isActive)
 
 ---
 
@@ -159,10 +159,13 @@ Adds an event listener. Returns an unsubscribe function. [Wiki](https://github.c
 ```typescript
 import { events } from "@real-router/core";
 
-router.addEventListener(events.TRANSITION_START, (toState, fromState) => {
+const unsubscribe = router.addEventListener(events.TRANSITION_START, (toState, fromState) => {
   console.log("Starting:", toState.name);
 });
 
+// To remove listener, call the returned unsubscribe function
+unsubscribe();
+
 // Available events:
 // ROUTER_START, ROUTER_STOP
 // TRANSITION_START, TRANSITION_SUCCESS, TRANSITION_ERROR, TRANSITION_CANCEL
@@ -197,6 +200,12 @@ router.useMiddleware((router) => (toState, fromState, done) => {
 });
 ```
 
+#### `router.clearMiddleware()`
+
+Clear all middleware.\
+Returns: `void`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/clearMiddleware)
+
 ---
 
 ## Advanced API
@@ -208,37 +217,45 @@ Add a route definition at runtime.\
 `route: Route` — route configuration object\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/addRoute)
+
 #### `router.removeRoute(name: string): void`
 Remove a route by name.\
 `name: string` — route name to remove\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/removeRoute)
+
 #### `router.getRoute(name: string): Route | undefined`
 Get route definition by name.\
 `name: string` — route name\
 Returns: `Route | undefined`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/getRoute)
+
 #### `router.hasRoute(name: string): boolean`
 Check if a route exists.\
 `name: string` — route name\
 Returns: `boolean`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/hasRoute)
+
 #### `router.clearRoutes(): void`
 Remove all routes.
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/clearRoutes)
+
 #### `router.updateRoute(name: string, updates: Partial<Route>): void`
 Update route configuration.\
 `name: string` — route name\
 `updates: Partial<Route>` — properties to update\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/updateRoute)
-#### `router.forward(fromRoute: string, toRoute: string): void`
-Set up route forwarding (redirect).\
-`fromRoute: string` — source route name\
-`toRoute: string` — target route name\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/forward)
+
+**Note:** To set up route forwarding (redirect), use the `forwardTo` option in route configuration:
+
+```typescript
+router.addRoute({ name: "old-url", path: "/old", forwardTo: "new-url" });
+// Or update existing route
+router.updateRoute("old-url", { forwardTo: "new-url" });
+```
+
 ---
 
 ### State Utilities
@@ -247,37 +264,21 @@ Returns: `void`\
 Get previous router state.\
 Returns: `State | undefined`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/getPreviousState)
-#### `router.setState(state: State): void`
-Set state directly without navigation.\
-`state: State` — state to set\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/setState)
-#### `router.makeState(name: string, params?: Params, path?: string, meta?: object): State`
-Create a state object.\
-`name: string` — route name\
-`params?: Params` — route parameters\
-`path?: string` — URL path\
-`meta?: object` — metadata\
-Returns: `State`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/makeState)
-#### `router.buildState(name: string, params?: Params): State | undefined`
-Build state from route name.\
-`name: string` — route name\
-`params?: Params` — route parameters\
-Returns: `State | undefined`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/buildState)
+
+#### `router.shouldUpdateNode(nodeName: string): (toState, fromState?) => boolean`
+Create a predicate to check if a route node should update during transition.\
+`nodeName: string` — route node name\
+Returns: predicate function\
+[Wiki](https://github.com/greydragon888/real-router/wiki/shouldUpdateNode)
+
 #### `router.areStatesEqual(state1: State, state2: State, ignoreQueryParams?: boolean): boolean`
 Compare two states for equality.\
 `state1: State` — first state\
 `state2: State` — second state\
-`ignoreQueryParams?: boolean` — ignore query params (default: true)Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/areStatesEqual)
-#### `router.areStatesDescendants(parentState: State, childState: State): boolean`
-Check if child state is descendant of parent.\
-`parentState: State` — parent state\
-`childState: State` — child state\
+`ignoreQueryParams?: boolean` — ignore query params (default: true)\
 Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/areStatesDescendants)
+[Wiki](https://github.com/greydragon888/real-router/wiki/areStatesEqual)
+
 ---
 
 ### Path Operations
@@ -288,26 +289,24 @@ Build URL path from route name.\
 `params?: Params` — route parameters\
 Returns: `string`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/buildPath)
-#### `router.matchPath(path: string): State | undefined`
-Match URL path to state.\
-`path: string` — URL path to match\
-Returns: `State | undefined`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/matchPath)
+
+#### `router.buildUrl(name: string, params?: Params, options?: object): string`
+Build full URL from route name (includes base path and query string).\
+`name: string` — route name\
+`params?: Params` — route parameters\
+`options?: object` — URL building options\
+Returns: `string`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/buildUrl)
+
 #### `router.isActiveRoute(name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean): boolean`
 Check if route is currently active.\
 `name: string` — route name\
 `params?: Params` — route parameters\
-`strictEquality?: boolean` — exact match (default: false)`ignoreQueryParams?: boolean` — ignore query params (default: true)Returns: `boolean`\
+`strictEquality?: boolean` — exact match (default: false)\
+`ignoreQueryParams?: boolean` — ignore query params (default: true)\
+Returns: `boolean`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/isActiveRoute)
-#### `router.setRootPath(rootPath: string): void`
-Set root path prefix for all routes.\
-`rootPath: string` — root path prefix\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/setRootPath)
-#### `router.getRootPath(): string`
-Get root path prefix.\
-Returns: `string`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/getRootPath)
+
 ---
 
 ### Dependencies
@@ -317,49 +316,64 @@ Get a dependency by name.\
 `name: string` — dependency name\
 Returns: `unknown`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/getDependency)
+
 #### `router.getDependencies(): Dependencies`
 Get all dependencies.\
 Returns: `Dependencies`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/getDependencies)
+
 #### `router.setDependency(name: string, value: unknown): void`
 Set a dependency.\
 `name: string` — dependency name\
 `value: unknown` — dependency value\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/setDependency)
+
 #### `router.setDependencies(deps: Dependencies): void`
 Set multiple dependencies.\
 `deps: Dependencies` — dependencies object\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/setDependencies)
+
 #### `router.hasDependency(name: string): boolean`
 Check if dependency exists.\
 `name: string` — dependency name\
 Returns: `boolean`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/hasDependency)
+
 #### `router.removeDependency(name: string): void`
 Remove a dependency.\
 `name: string` — dependency name\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/removeDependency)
+
 #### `router.resetDependencies(): void`
 Remove all dependencies.\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/resetDependencies)
+
 ---
 
 ### Options
 
 #### `router.getOptions(): Options`
-Get router options.\
+Get all router options.\
 Returns: `Options`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/getOptions)
+
+#### `router.getOption(name: keyof Options): unknown`
+Get a single router option by name.\
+`name: keyof Options` — option name\
+Returns: option value\
+[Wiki](https://github.com/greydragon888/real-router/wiki/getOption)
+
 #### `router.setOption(name: string, value: unknown): void`
 Set a router option. Must be called before `start()`.\
 `name: string` — option name\
 `value: unknown` — option value\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/setOption)
+
 ---
 
 ### Other
@@ -369,38 +383,72 @@ Clone router for SSR.\
 `dependencies?: Dependencies` — override dependencies\
 Returns: `Router`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/clone)
-#### `router.isNavigating(): boolean`
-Check if navigation is in progress.\
-Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/isNavigating)
-#### `router.isActive(name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean): boolean`
-Alias for `isActiveRoute`.\
+
+#### `router.cancel(): void`
+Cancel the current navigation in progress.\
+Returns: `void`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/cancel)
+
+---
+
+## Plugin Development API
+
+The following methods are designed for **plugin authors**. They provide low-level access for advanced use cases like browser history integration, persistent parameters, and custom navigation sources.
+
+These methods are stable but intended for plugin development, not application code.
+
+#### `router.matchPath(path: string, source?: string): State | undefined`
+Match URL path to route state.\
+`path: string` — URL path to match\
+`source?: string` — navigation source identifier\
+Returns: `State | undefined`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/matchPath)
+
+#### `router.makeState(name, params?, path?, meta?, forceId?): State`
+Create State with custom `meta.id` for history restoration.\
 `name: string` — route name\
 `params?: Params` — route parameters\
-`strictEquality?: boolean` — exact match\
-`ignoreQueryParams?: boolean` — ignore query params\
-Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/isActive)
-#### `router.clearCanActivate(name: string): void`
-Clear activation guard for a route.\
+`path?: string` — URL path\
+`meta?: object` — metadata\
+`forceId?: number` — force specific `meta.id` value\
+Returns: `State`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/makeState)
+
+#### `router.buildState(name: string, params?: Params): State | undefined`
+Validate route and build state with segment metadata.\
 `name: string` — route name\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/clearCanActivate)
-#### `router.clearCanDeactivate(name: string): void`
-Clear deactivation guard for a route.\
+`params?: Params` — route parameters\
+Returns: `State | undefined`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/buildState)
+
+#### `router.forwardState(name: string, params: Params): { name: string; params: Params }`
+Resolve route forwarding and merge default params.\
 `name: string` — route name\
+`params: Params` — route parameters\
+Returns: `{ name, params }` — resolved route name and merged params\
+[Wiki](https://github.com/greydragon888/real-router/wiki/forwardState)
+
+#### `router.navigateToState(toState, fromState, opts, done, emitSuccess): CancelFn`
+Navigate with pre-built State object.\
+`toState: State` — target state\
+`fromState: State | undefined` — current state\
+`opts: NavigationOptions` — navigation options\
+`done: DoneFn` — callback\
+`emitSuccess: boolean` — whether to emit TRANSITION_SUCCESS\
+Returns: `CancelFn`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/navigateToState)
+
+#### `router.setRootPath(rootPath: string): void`
+Dynamically modify router base path.\
+`rootPath: string` — new root path prefix\
 Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/clearCanDeactivate)
-#### `router.clearMiddleware(): void`
-Clear all middleware.\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/clearMiddleware)
-#### `router.removeEventListener(event: string, listener: Function): void`
-Remove event listener.\
-`event: string` — event name\
-`listener: Function` — listener to remove\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/removeEventListener)
+[Wiki](https://github.com/greydragon888/real-router/wiki/setRootPath)
+
+#### `router.getRootPath(): string`
+Read current base path.\
+Returns: `string`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/getRootPath)
+
 ---
 
 ## Configuration
@@ -468,6 +516,12 @@ See [RouterError](https://github.com/greydragon888/real-router/wiki/RouterError)
 
 ---
 
+## Migration from router5
+
+See the [Migration Guide](https://github.com/greydragon888/real-router/wiki/migration-guide) for detailed guidance.
+
+---
+
 ## Related Packages
 
 - [@real-router/react](https://www.npmjs.com/package/@real-router/react) — React integration

package/dist/cjs/index.d.ts

@@ -1,5 +1,5 @@
-import { ErrorCodeKeys, ErrorCodeValues, ErrorCodeToValueMap, EventToNameMap, State, DefaultDependencies, Route, Options, Router } from '@real-router/types';
-export { ActivationFn, ActivationFnFactory, CancelFn, Config, DefaultDependencies, DoneFn, Listener, Middleware, MiddlewareFactory, NavigationOptions, Options, Params, Plugin, PluginFactory, Route, Router, SimpleState, State, StateMeta, SubscribeFn, SubscribeState, Subscription, Unsubscribe } from '@real-router/types';
+import { EventToPluginMap, EventToNameMap, ErrorCodeKeys, ErrorCodeValues, ErrorCodeToValueMap, EventsKeys, State, DefaultDependencies, Options, Params, StateMetaInput, SimpleState, RouteTreeState, DoneFn, Unsubscribe, EventName, Plugin, NavigationOptions, CancelFn, SubscribeFn, Middleware, ActivationFn } from '@real-router/types';
+export { ActivationFn, CancelFn, Config, DefaultDependencies, DoneFn, Listener, Middleware, NavigationOptions, Options, Params, Plugin, SimpleState, State, StateMeta, SubscribeFn, SubscribeState, Subscription, Unsubscribe } from '@real-router/types';
 
 type ConstantsKeys = "UNKNOWN_ROUTE";
 type Constants = Record<ConstantsKeys, string>;
@@ -15,12 +15,263 @@ declare const errorCodes: ErrorCodeToValueMap;
  * Special route names and identifiers.
  */
 declare const constants: Constants;
+/**
+ * Plugin method names.
+ * Maps to methods that plugins can implement to hook into router lifecycle.
+ */
+declare const plugins: EventToPluginMap;
 /**
  * Event names for router event system.
  * Used with addEventListener/removeEventListener for reactive subscriptions.
  */
 declare const events: EventToNameMap;
 
+type EventMethodMap = {
+    [K in EventsKeys as (typeof events)[K]]: (typeof plugins)[K];
+};
+/**
+ * Observable state passed to subscribers
+ */
+interface SubscribeState {
+    route: State;
+    previousRoute: State | undefined;
+}
+/**
+ * Observer interface per Observable spec
+ */
+interface Observer {
+    next?: (value: SubscribeState) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+}
+/**
+ * Subscription interface per Observable spec
+ */
+interface Subscription {
+    unsubscribe: () => void;
+    readonly closed: boolean;
+}
+/**
+ * Observable options for enhanced control
+ */
+interface ObservableOptions {
+    /** AbortSignal for automatic unsubscription */
+    signal?: AbortSignal;
+    /** Replay current state to new subscribers (default: true) */
+    replay?: boolean;
+}
+/**
+ * Observable interface for TC39 compliance
+ */
+interface RouterObservable {
+    [key: symbol]: () => RouterObservable;
+    subscribe: (observer: Observer | ((value: SubscribeState) => void), options?: ObservableOptions) => Subscription;
+}
+
+/**
+ * Symbol.observable polyfill declaration for TC39 proposal
+ *
+ * @see https://github.com/tc39/proposal-observable
+ */
+declare global {
+    interface SymbolConstructor {
+        readonly observable: unique symbol;
+    }
+}
+
+/**
+ * Router class with integrated namespace architecture.
+ *
+ * All functionality is provided by namespace classes:
+ * - OptionsNamespace: getOptions, setOption
+ * - DependenciesNamespace: get/set/remove dependencies
+ * - ObservableNamespace: event listeners, subscribe
+ * - StateNamespace: state storage (getState, setState, getPreviousState)
+ * - RoutesNamespace: route tree operations
+ * - RouteLifecycleNamespace: canActivate/canDeactivate guards
+ * - MiddlewareNamespace: middleware chain
+ * - PluginsNamespace: plugin lifecycle
+ * - NavigationNamespace: navigate, navigateToState
+ * - RouterLifecycleNamespace: start, stop, isStarted
+ *
+ * @internal This class implementation is internal. Use createRouter() instead.
+ */
+declare class Router<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    #private;
+    [key: string]: unknown;
+    /**
+     * @param routes - Route definitions
+     * @param options - Router options
+     * @param dependencies - DI dependencies
+     */
+    constructor(routes?: Route<Dependencies>[], options?: Partial<Options>, dependencies?: Dependencies);
+    addRoute(routes: Route<Dependencies>[] | Route<Dependencies>): this;
+    removeRoute(name: string): this;
+    clearRoutes(): this;
+    getRoute(name: string): Route<Dependencies> | undefined;
+    hasRoute(name: string): boolean;
+    updateRoute(name: string, updates: RouteConfigUpdate<Dependencies>): this;
+    isActiveRoute(name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean): boolean;
+    buildPath(route: string, params?: Params): string;
+    matchPath<P extends Params = Params, MP extends Params = Params>(path: string, source?: string): State<P, MP> | undefined;
+    setRootPath(rootPath: string): void;
+    getRootPath(): string;
+    makeState<P extends Params = Params, MP extends Params = Params>(name: string, params?: P, path?: string, meta?: StateMetaInput<MP>, forceId?: number): State<P, MP>;
+    getState<P extends Params = Params, MP extends Params = Params>(): State<P, MP> | undefined;
+    getPreviousState(): State | undefined;
+    areStatesEqual(state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean): boolean;
+    forwardState<P extends Params = Params>(routeName: string, routeParams: P): SimpleState<P>;
+    buildState(routeName: string, routeParams: Params): RouteTreeState | undefined;
+    shouldUpdateNode(nodeName: string): (toState: State, fromState?: State) => boolean;
+    getOptions(): Options;
+    getOption<K extends keyof Options>(option: K): Options[K];
+    setOption(option: keyof Options, value: Options[keyof Options]): this;
+    isActive(): boolean;
+    start(...args: [] | [done: DoneFn] | [startPathOrState: string | State] | [startPathOrState: string | State, done: DoneFn]): this;
+    stop(): this;
+    canDeactivate(name: string, canDeactivateHandler: ActivationFnFactory<Dependencies> | boolean): this;
+    canActivate(name: string, canActivateHandler: ActivationFnFactory<Dependencies> | boolean): this;
+    usePlugin(...plugins: PluginFactory<Dependencies>[]): Unsubscribe;
+    useMiddleware(...middlewares: MiddlewareFactory<Dependencies>[]): Unsubscribe;
+    clearMiddleware(): this;
+    setDependency<K extends keyof Dependencies & string>(dependencyName: K, dependency: Dependencies[K]): this;
+    setDependencies(deps: Dependencies): this;
+    getDependency<K extends keyof Dependencies>(key: K): Dependencies[K];
+    getDependencies(): Partial<Dependencies>;
+    removeDependency(dependencyName: keyof Dependencies): this;
+    hasDependency(dependencyName: keyof Dependencies): boolean;
+    resetDependencies(): this;
+    addEventListener<E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]): Unsubscribe;
+    navigate(routeName: string, routeParamsOrDone?: Params | DoneFn, optionsOrDone?: NavigationOptions | DoneFn, done?: DoneFn): CancelFn;
+    navigateToDefault(optsOrDone?: NavigationOptions | DoneFn, done?: DoneFn): CancelFn;
+    navigateToState(toState: State, fromState: State | undefined, opts: NavigationOptions, callback: DoneFn, emitSuccess: boolean): CancelFn;
+    subscribe(listener: SubscribeFn): Unsubscribe;
+    /**
+     * TC39 Observable spec: router[Symbol.observable]() returns observable
+     */
+    [Symbol.observable](): RouterObservable;
+    /**
+     * RxJS compatibility: router["@@observable"]() returns observable
+     */
+    ["@@observable"](): RouterObservable;
+    clone(dependencies?: Dependencies): Router<Dependencies>;
+}
+
+/**
+ * Router-dependent types.
+ *
+ * These types reference the Router class and are therefore defined in core
+ * rather than core-types to avoid circular dependencies.
+ */
+
+/**
+ * Extended build result that includes segments for path building.
+ * Used internally to avoid duplicate getSegmentsByName calls.
+ *
+ * @param segments - Route segments from getSegmentsByName (typed as unknown[] for cross-package compatibility)
+ * @internal
+ */
+interface BuildStateResultWithSegments<P extends Params = Params> {
+    readonly state: RouteTreeState<P>;
+    readonly segments: readonly unknown[];
+}
+/**
+ * Route configuration.
+ */
+interface Route<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    [key: string]: unknown;
+    /** Route name (dot-separated for nested routes). */
+    name: string;
+    /** URL path pattern for this route. */
+    path: string;
+    /** Factory function that returns a guard for route activation. */
+    canActivate?: ActivationFnFactory<Dependencies>;
+    /**
+     * Redirects navigation to another route.
+     *
+     * IMPORTANT: forwardTo creates a URL alias, not a transition chain.
+     * Guards (canActivate) on the source route are NOT executed.
+     * Only guards on the final destination are executed.
+     *
+     * This matches Vue Router and Angular Router behavior.
+     *
+     * @example
+     * // Correct: guard on target
+     * { name: "old", path: "/old", forwardTo: "new" }
+     * { name: "new", path: "/new", canActivate: myGuard }
+     *
+     * // Wrong: guard on source (will be ignored with warning)
+     * { name: "old", path: "/old", forwardTo: "new", canActivate: myGuard }
+     */
+    forwardTo?: string;
+    /** Nested child routes. */
+    children?: Route<Dependencies>[];
+    /** Encodes state params to URL params. */
+    encodeParams?: (stateParams: Params) => Params;
+    /** Decodes URL params to state params. */
+    decodeParams?: (pathParams: Params) => Params;
+    /**
+     * Default parameters for this route.
+     *
+     * @remarks
+     * **Type Contract:**
+     * The type of defaultParams MUST match the expected params type P
+     * when using `router.makeState<P>()` or `router.navigate<P>()`.
+     *
+     * These values are merged into state.params when creating route states.
+     * Missing URL params are filled from defaultParams.
+     *
+     * @example
+     * ```typescript
+     * // Define route with pagination defaults
+     * {
+     *   name: "users",
+     *   path: "/users",
+     *   defaultParams: { page: 1, limit: 10 }
+     * }
+     *
+     * // Navigate without specifying page/limit
+     * router.navigate("users", { filter: "active" });
+     * // Result: state.params = { page: 1, limit: 10, filter: "active" }
+     *
+     * // Correct typing — include defaultParams properties
+     * type UsersParams = { page: number; limit: number; filter?: string };
+     * ```
+     */
+    defaultParams?: Params;
+}
+/**
+ * Configuration update options for updateRoute().
+ * All properties are optional. Set to null to remove the configuration.
+ */
+interface RouteConfigUpdate<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    /** Set to null to remove forwardTo */
+    forwardTo?: string | null;
+    /** Set to null to remove defaultParams */
+    defaultParams?: Params | null;
+    /** Set to null to remove decoder */
+    decodeParams?: ((params: Params) => Params) | null;
+    /** Set to null to remove encoder */
+    encodeParams?: ((params: Params) => Params) | null;
+    /** Set to null to remove canActivate */
+    canActivate?: ActivationFnFactory<Dependencies> | null;
+}
+/**
+ * Factory function for creating activation guards.
+ * Receives the router instance and a dependency getter.
+ */
+type ActivationFnFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => ActivationFn;
+/**
+ * Factory function for creating middleware.
+ * Receives the router instance and a dependency getter.
+ */
+type MiddlewareFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => Middleware;
+/**
+ * Factory function for creating plugins.
+ * Receives the router instance and a dependency getter.
+ */
+type PluginFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => Plugin;
+
 declare class RouterError extends Error {
     [key: string]: unknown;
     readonly segment: string | undefined;
@@ -210,7 +461,20 @@ declare class RouterError extends Error {
 
 /**
  * Creates a new router instance.
+ *
+ * @param routes - Array of route definitions
+ * @param options - Router configuration options
+ * @param dependencies - Dependencies to inject into the router
+ * @returns A new Router instance
+ *
+ * @example
+ * const router = createRouter([
+ *   { name: 'home', path: '/' },
+ *   { name: 'users', path: '/users' },
+ * ]);
+ *
+ * router.start('/');
  */
 declare const createRouter: <Dependencies extends DefaultDependencies = DefaultDependencies>(routes?: Route<Dependencies>[], options?: Partial<Options>, dependencies?: Dependencies) => Router<Dependencies>;
 
-export { type Constants, type ErrorCodes, RouterError, constants, createRouter, errorCodes, events };
+export { type ActivationFnFactory, type BuildStateResultWithSegments, type Constants, type ErrorCodes, type MiddlewareFactory, type PluginFactory, type Route, type RouteConfigUpdate, Router, RouterError, constants, createRouter, errorCodes, events };