@real-router/core 0.2.4 → 0.4.0

package/dist/esm/index.d.mts

@@ -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 };