@real-router/core 0.2.4 → 0.3.0

package/README.md

@@ -239,6 +239,7 @@ Set up route forwarding (redirect).\
 `toRoute: string` — target route name\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/forward)
+
 ---
 
 ### State Utilities
@@ -266,11 +267,29 @@ Build state from route name.\
 `params?: Params` — route parameters\
 Returns: `State | undefined`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/buildState)
+#### `router.buildStateWithSegments(name: string, params?: Params): { state: State; segments: RouteSegment[] } | undefined`
+Build state with route segments for advanced use cases.\
+`name: string` — route name\
+`params?: Params` — route parameters\
+Returns: `{ state, segments } | undefined`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/buildStateWithSegments)
+#### `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.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`\
+`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.\
@@ -278,6 +297,7 @@ Check if child state is descendant of parent.\
 `childState: State` — child state\
 Returns: `boolean`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/areStatesDescendants)
+
 ---
 
 ### Path Operations
@@ -297,7 +317,9 @@ Returns: `State | undefined`\
 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.\
@@ -308,6 +330,7 @@ Returns: `void`\
 Get root path prefix.\
 Returns: `string`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/getRootPath)
+
 ---
 
 ### Dependencies
@@ -346,20 +369,27 @@ Returns: `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
@@ -373,12 +403,8 @@ Returns: `Router`\
 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`.\
-`name: string` — route name\
-`params?: Params` — route parameters\
-`strictEquality?: boolean` — exact match\
-`ignoreQueryParams?: boolean` — ignore query params\
+#### `router.isActive(): boolean`
+Check if router is active (started and has current state).\
 Returns: `boolean`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/isActive)
 #### `router.clearCanActivate(name: string): void`
@@ -401,6 +427,7 @@ Remove event listener.\
 `listener: Function` — listener to remove\
 Returns: `void`\
 [Wiki](https://github.com/greydragon888/real-router/wiki/removeEventListener)
+
 ---
 
 ## Configuration

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, NavigationOptions, SimpleState, RouteTreeState, DoneFn, ActivationFn, Unsubscribe, Middleware, RouterError as RouterError$1, EventName, Plugin, CancelFn, SubscribeFn } 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,286 @@ 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>;
+    makeNotFoundState(path: string, options?: NavigationOptions): State;
+    getState<P extends Params = Params, MP extends Params = Params>(): State<P, MP> | undefined;
+    setState<P extends Params = Params, MP extends Params = Params>(state?: State<P, MP>): void;
+    getPreviousState(): State | undefined;
+    areStatesEqual(state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean): boolean;
+    areStatesDescendants(parentState: State, childState: State): boolean;
+    forwardState<P extends Params = Params>(routeName: string, routeParams: P): SimpleState<P>;
+    buildState(routeName: string, routeParams: Params): RouteTreeState | undefined;
+    buildStateWithSegments<P extends Params = Params>(routeName: string, routeParams: P): BuildStateResultWithSegments<P> | 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;
+    isStarted(): boolean;
+    isActive(): boolean;
+    isNavigating(): boolean;
+    start(...args: [] | [done: DoneFn] | [startPathOrState: string | State] | [startPathOrState: string | State, done: DoneFn]): this;
+    stop(): this;
+    canDeactivate(name: string, canDeactivateHandler: ActivationFnFactory<Dependencies> | boolean): this;
+    clearCanDeactivate(name: string, silent?: boolean): this;
+    canActivate(name: string, canActivateHandler: ActivationFnFactory<Dependencies> | boolean): this;
+    clearCanActivate(name: string, silent?: boolean): this;
+    getLifecycleFactories(): [
+        Record<string, ActivationFnFactory<Dependencies>>,
+        Record<string, ActivationFnFactory<Dependencies>>
+    ];
+    getLifecycleFunctions(): [
+        Map<string, ActivationFn>,
+        Map<string, ActivationFn>
+    ];
+    usePlugin(...plugins: PluginFactory<Dependencies>[]): Unsubscribe;
+    getPlugins(): PluginFactory<Dependencies>[];
+    useMiddleware(...middlewares: MiddlewareFactory<Dependencies>[]): Unsubscribe;
+    clearMiddleware(): this;
+    getMiddlewareFactories(): MiddlewareFactory<Dependencies>[];
+    getMiddlewareFunctions(): Middleware[];
+    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;
+    invokeEventListeners(eventName: EventToNameMap[EventsKeys], toState?: State, fromState?: State, arg?: RouterError$1 | NavigationOptions): void;
+    hasListeners(eventName: EventToNameMap[EventsKeys]): boolean;
+    removeEventListener<E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]): void;
+    addEventListener<E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]): Unsubscribe;
+    forward(fromRoute: string, toRoute: string): this;
+    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 +484,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 };