@real-router/core 0.25.3 → 0.26.0

package/dist/cjs/index.d.ts

@@ -1,38 +1,33 @@
-import { EventToPluginMap, EventToNameMap, ErrorCodeKeys, ErrorCodeValues, ErrorCodeToValueMap, DefaultDependencies, Options, Params, State, StateMetaInput, SimpleState, RouteTreeState, Unsubscribe, EventName, Plugin, SubscribeFn, NavigationOptions, GuardFn, ForwardToCallback, EventsKeys, ActivationFn, Navigator } from '@real-router/types';
-export { ActivationFn, Config, DefaultDependencies, GuardFn, Listener, NavigationOptions, Navigator, Options, Params, Plugin, SimpleState, State, StateMeta, SubscribeFn, SubscribeState, Subscription, Unsubscribe } from '@real-router/types';
+import { Params, RouteTreeState, DefaultDependencies, Router as Router$1, Route, Options, State, PluginFactory, Unsubscribe, SubscribeFn, NavigationOptions, ErrorCodeKeys, ErrorCodeValues, ErrorCodeToValueMap, EventToNameMap, Navigator, PluginApi, RoutesApi, DependenciesApi, LifecycleApi } from '@real-router/types';
+export { Config, DefaultDependencies, DependenciesApi, GuardFn, GuardFnFactory, LifecycleApi, Listener, NavigationOptions, Navigator, Options, Params, Plugin, PluginApi, PluginFactory, Route, RouteConfigUpdate, RoutesApi, SimpleState, State, StateMeta, SubscribeFn, SubscribeState, Subscription, Unsubscribe } from '@real-router/types';
 
-type ConstantsKeys = "UNKNOWN_ROUTE";
-type Constants = Record<ConstantsKeys, string>;
-type ErrorCodes = Record<ErrorCodeKeys, ErrorCodeValues>;
-/**
- * Error codes for router operations.
- * Used to identify specific failure scenarios in navigation and lifecycle.
- * Frozen to prevent accidental modifications.
- */
-declare const errorCodes: ErrorCodeToValueMap;
-/**
- * General router constants.
- * Special route names and identifiers.
- */
-declare const constants: Constants;
 /**
- * Plugin method names.
- * Maps to methods that plugins can implement to hook into router lifecycle.
+ * Core-internal types + re-exports from @real-router/types.
+ *
+ * Factory types (PluginFactory, GuardFnFactory) and
+ * route config types (Route, RouteConfigUpdate) are canonical in @real-router/types
+ * and re-exported here for backward compatibility.
  */
-declare const plugins: EventToPluginMap;
+
 /**
- * Event names for router event system.
- * Used with addEventListener/removeEventListener for reactive subscriptions.
+ * 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
  */
-declare const events: EventToNameMap;
+interface BuildStateResultWithSegments<P extends Params = Params> {
+    readonly state: RouteTreeState<P>;
+    readonly segments: readonly unknown[];
+}
 
 /**
  * Router class with integrated namespace architecture.
  *
  * All functionality is provided by namespace classes:
  * - OptionsNamespace: getOptions (immutable)
- * - DependenciesNamespace: get/set/remove dependencies
- * - EventEmitter: event listeners, subscribe
+ * - DependenciesStore: get/set/remove dependencies
+ * - EventEmitter: subscribe
  * - StateNamespace: state storage (getState, setState, getPreviousState)
  * - RoutesNamespace: route tree operations
  * - RouteLifecycleNamespace: canActivate/canDeactivate guards
@@ -42,7 +37,7 @@ declare const events: EventToNameMap;
  *
  * @internal This class implementation is internal. Use createRouter() instead.
  */
-declare class Router<Dependencies extends DefaultDependencies = DefaultDependencies> {
+declare class Router<Dependencies extends DefaultDependencies = DefaultDependencies> implements Router$1<Dependencies> {
     #private;
     [key: string]: unknown;
     /**
@@ -51,178 +46,42 @@ declare class Router<Dependencies extends DefaultDependencies = DefaultDependenc
      * @param dependencies - DI dependencies
      */
     constructor(routes?: Route<Dependencies>[], options?: Partial<Options>, dependencies?: Dependencies);
-    addRoute(routes: Route<Dependencies>[] | Route<Dependencies>, options?: {
-        parent?: string;
-    }): this;
-    removeRoute(name: string): this;
-    clearRoutes(): this;
-    getRoute(name: string): Route<Dependencies> | undefined;
-    getRouteConfig(name: string): Record<string, unknown> | 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): 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;
-    buildNavigationState(name: string, params?: Params): State | undefined;
     shouldUpdateNode(nodeName: string): (toState: State, fromState?: State) => boolean;
-    getOptions(): Options;
     isActive(): boolean;
     start(startPath: string): Promise<State>;
     stop(): this;
     dispose(): void;
-    addDeactivateGuard(name: string, canDeactivateHandler: GuardFnFactory<Dependencies> | boolean): this;
-    addActivateGuard(name: string, canActivateHandler: GuardFnFactory<Dependencies> | boolean): this;
-    removeActivateGuard(name: string): void;
-    removeDeactivateGuard(name: string): void;
     canNavigateTo(name: string, params?: Params): boolean;
     usePlugin(...plugins: PluginFactory<Dependencies>[]): Unsubscribe;
-    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;
     subscribe(listener: SubscribeFn): Unsubscribe;
-    navigate(routeName: string): Promise<State>;
-    navigate(routeName: string, routeParams: Params): Promise<State>;
-    navigate(routeName: string, routeParams: Params, options: NavigationOptions): Promise<State>;
-    navigateToDefault(): Promise<State>;
-    navigateToDefault(options: NavigationOptions): Promise<State>;
-    navigateToState(toState: State, fromState: State | undefined, opts: NavigationOptions): Promise<State>;
-    clone(dependencies?: Dependencies): Router<Dependencies>;
+    navigate(routeName: string, routeParams?: Params, options?: NavigationOptions): Promise<State>;
+    navigateToDefault(options?: NavigationOptions): Promise<State>;
 }
 
+type ConstantsKeys = "UNKNOWN_ROUTE";
+type Constants = Record<ConstantsKeys, string>;
+type ErrorCodes = Record<ErrorCodeKeys, ErrorCodeValues>;
 /**
- * Router-dependent types.
- *
- * These types reference the Router class and are therefore defined in core
- * rather than core-types to avoid circular dependencies.
- */
-
-type EventMethodMap = {
-    [K in EventsKeys as (typeof events)[K]]: (typeof plugins)[K];
-};
-/**
- * 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?: GuardFnFactory<Dependencies>;
-    /** Factory function that returns a guard for route deactivation. */
-    canDeactivate?: GuardFnFactory<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 | ForwardToCallback<Dependencies>;
-    /** 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 | ForwardToCallback<Dependencies> | 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?: GuardFnFactory<Dependencies> | null;
-    /** Set to null to remove canDeactivate */
-    canDeactivate?: GuardFnFactory<Dependencies> | null;
-}
-/**
- * Factory function for creating activation guards.
- * Receives the router instance and a dependency getter.
+ * Error codes for router operations.
+ * Used to identify specific failure scenarios in navigation and lifecycle.
+ * Frozen to prevent accidental modifications.
  */
-type ActivationFnFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => ActivationFn;
+declare const errorCodes: ErrorCodeToValueMap;
 /**
- * Factory function for creating guards.
- * Receives the router instance and a dependency getter.
+ * General router constants.
+ * Special route names and identifiers.
  */
-type GuardFnFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => GuardFn;
+declare const constants: Constants;
 /**
- * Factory function for creating plugins.
- * Receives the router instance and a dependency getter.
+ * Event names for router event system.
+ * Used with addEventListener/removeEventListener for reactive subscriptions.
  */
-type PluginFactory<Dependencies extends DefaultDependencies = DefaultDependencies> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => Plugin;
+declare const events: EventToNameMap;
 
 declare class RouterError extends Error {
     [key: string]: unknown;
@@ -429,6 +288,16 @@ declare class RouterError extends Error {
  */
 declare const createRouter: <Dependencies extends DefaultDependencies = DefaultDependencies>(routes?: Route<Dependencies>[], options?: Partial<Options>, dependencies?: Dependencies) => Router<Dependencies>;
 
-declare const getNavigator: <Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router<Dependencies>) => Navigator;
+declare const getNavigator: <Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router$1<Dependencies>) => Navigator;
+
+declare function getPluginApi<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router$1<Dependencies>): PluginApi;
+
+declare function getRoutesApi<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router$1<Dependencies>): RoutesApi<Dependencies>;
+
+declare function getDependenciesApi<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router$1<Dependencies>): DependenciesApi<Dependencies>;
+
+declare function getLifecycleApi<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router$1<Dependencies>): LifecycleApi<Dependencies>;
+
+declare function cloneRouter<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router$1<Dependencies>, dependencies?: Dependencies): Router<Dependencies>;
 
-export { type ActivationFnFactory, type BuildStateResultWithSegments, type Constants, type ErrorCodes, type GuardFnFactory, type PluginFactory, type Route, type RouteConfigUpdate, Router, RouterError, constants, createRouter, errorCodes, events, getNavigator };
+export { type BuildStateResultWithSegments, type Constants, type ErrorCodes, Router, RouterError, cloneRouter, constants, createRouter, errorCodes, events, getDependenciesApi, getLifecycleApi, getNavigator, getPluginApi, getRoutesApi };