@real-router/core 0.38.0 → 0.40.0

package/dist/esm/index.d-DDimDpYc.d.mts

@@ -1,165 +0,0 @@
-import { DefaultDependencies, Router as Router$1, Route, Options, Params, State, PluginFactory, Unsubscribe, SubscribeFn, NavigationOptions } from '@real-router/types';
-
-/**
- * Router class with integrated namespace architecture.
- *
- * All functionality is provided by namespace classes:
- * - OptionsNamespace: getOptions (immutable)
- * - DependenciesStore: get/set/remove dependencies
- * - EventEmitter: subscribe
- * - StateNamespace: state storage (getState, setState, getPreviousState)
- * - RoutesNamespace: route tree operations
- * - RouteLifecycleNamespace: canActivate/canDeactivate guards
- * - PluginsNamespace: plugin lifecycle
- * - NavigationNamespace: navigate
- * - RouterLifecycleNamespace: start, stop, isStarted
- *
- * @internal This class implementation is internal. Use createRouter() instead.
- */
-declare class Router<Dependencies extends DefaultDependencies = DefaultDependencies> implements Router$1<Dependencies> {
-    #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);
-    isActiveRoute(name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean): boolean;
-    buildPath(route: string, params?: Params): string;
-    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;
-    shouldUpdateNode(nodeName: string): (toState: State, fromState?: State) => boolean;
-    isActive(): boolean;
-    start(startPath: string): Promise<State>;
-    stop(): this;
-    dispose(): void;
-    canNavigateTo(name: string, params?: Params): boolean;
-    usePlugin(...plugins: PluginFactory<Dependencies>[]): Unsubscribe;
-    subscribe(listener: SubscribeFn): Unsubscribe;
-    navigate(routeName: string, routeParams?: Params, options?: NavigationOptions): Promise<State>;
-    navigateToDefault(options?: NavigationOptions): Promise<State>;
-    navigateToNotFound(path?: string): State;
-}
-
-/**
- * Path Matcher Type Definitions.
- *
- * Core types for path matching and parameter extraction.
- *
- * @module path-matcher/types
- */
-/**
- * Constraint pattern for a URL parameter.
- */
-interface ConstraintPattern {
-    /**
-     * Compiled RegExp for validating the parameter value.
-     *
-     * @example /^(\d+)$/ for constraint "<\\d+>"
-     */
-    readonly pattern: RegExp;
-    /**
-     * Raw constraint string from the route pattern.
-     *
-     * @example "<\\d+>"
-     */
-    readonly constraint: string;
-}
-/**
- * Parameter metadata extracted from a route path pattern.
- */
-interface ParamMeta {
-    /**
-     * URL parameter names extracted from the path pattern.
-     *
-     * @example [":id", ":postId"] from "/users/:id/posts/:postId"
-     */
-    readonly urlParams: readonly string[];
-    /**
-     * Query parameter names extracted from the path pattern.
-     *
-     * @example ["q", "page"] from "/search?q&page"
-     */
-    readonly queryParams: readonly string[];
-    /**
-     * Splat parameter names extracted from the path pattern.
-     *
-     * @example ["path"] from "/files/*path"
-     */
-    readonly spatParams: readonly string[];
-    /**
-     * Map of parameter names to their type (url or query).
-     *
-     * @example { id: "url", q: "query" }
-     */
-    readonly paramTypeMap: Readonly<Record<string, "url" | "query">>;
-    /**
-     * Map of parameter names to their constraint patterns.
-     *
-     * Only includes parameters with explicit constraints (e.g., `:id<\\d+>`).
-     * Parameters without constraints are not included in this map.
-     *
-     * @example
-     * ```typescript
-     * buildParamMeta("/users/:id<\\d+>").constraintPatterns.get("id")
-     * // → { pattern: /^(\d+)$/, constraint: "<\\d+>" }
-     *
-     * buildParamMeta("/users/:id").constraintPatterns.size
-     * // → 0 (no constraints)
-     * ```
-     */
-    readonly constraintPatterns: ReadonlyMap<string, ConstraintPattern>;
-    /**
-     * Path pattern without query string, pre-computed for buildPath.
-     *
-     * @example "/users/:id" from "/users/:id?q&page"
-     */
-    readonly pathPattern: string;
-}
-
-/**
- * Immutable route tree node.
- *
- * This is the core data structure of the new route-tree architecture.
- * It contains only data (no methods) and is created by the builder.
- *
- * All caches are pre-computed at build time:
- * - nonAbsoluteChildren: filtered children without absolute paths
- * - absoluteDescendants: all descendants with absolute paths (recursive)
- * - parentSegments: array from root to parent
- * - fullName: pre-computed "users.profile" instead of runtime join
- */
-interface RouteTree {
-    /** Route segment name (e.g., "users" in "users.profile") */
-    readonly name: string;
-    /** Route path pattern (e.g., "/users/:id") */
-    readonly path: string;
-    /** Whether this route uses absolute path matching (path starts with "~") */
-    readonly absolute: boolean;
-    /** Child route nodes (Map for O(1) lookup by name) */
-    readonly children: ReadonlyMap<string, RouteTree>;
-    /** Parameter metadata extracted from path pattern (replaces parser dependency) */
-    readonly paramMeta: ParamMeta;
-    /** Parent node (null for root) */
-    readonly parent: RouteTree | null;
-    /** Children without absolute paths (for regular matching) */
-    readonly nonAbsoluteChildren: readonly RouteTree[];
-    /** Pre-computed full name (e.g., "users.profile") */
-    readonly fullName: string;
-    /**
-     * Pre-computed static path for routes without parameters.
-     * Used by buildPath fast path to avoid inject() overhead.
-     * Only set when route has no URL params, query params, or splat params.
-     */
-    readonly staticPath: string | null;
-    /**
-     * Pre-computed parameter type map for this segment.
-     * Cached to avoid recomputing on every navigation.
-     * Maps param name → "url" | "query".
-     */
-    readonly paramTypeMap: Readonly<Record<string, "url" | "query">>;
-}
-
-export { Router as R, type RouteTree as a };

package/src/namespaces/DependenciesNamespace/validators.ts

@@ -1,103 +0,0 @@
-// packages/core/src/namespaces/DependenciesNamespace/validators.ts
-
-/**
- * Static validation functions for dependencies.
- * Called by Router facade and getDependenciesApi before store operations.
- */
-
-import { getTypeDescription } from "type-guards";
-
-import { DEFAULT_LIMITS } from "../../constants";
-
-/**
- * Validates that dependency name is a string.
- * Called by facade before get/remove/has operations.
- */
-export function validateDependencyName(
-  name: unknown,
-  methodName: string,
-): asserts name is string {
-  if (typeof name !== "string") {
-    throw new TypeError(
-      `[router.${methodName}]: dependency name must be a string, got ${typeof name}`,
-    );
-  }
-}
-
-/**
- * Validates setDependency name argument.
- * Value is not validated - any value is valid.
- */
-export function validateSetDependencyArgs(
-  name: unknown,
-): asserts name is string {
-  if (typeof name !== "string") {
-    throw new TypeError(
-      `[router.setDependency]: dependency name must be a string, got ${typeof name}`,
-    );
-  }
-}
-
-/**
- * Validates that dependencies object is a plain object without getters.
- * Called by facade before setMultiple/constructor.
- */
-export function validateDependenciesObject(
-  deps: unknown,
-  methodName: string,
-): asserts deps is Record<string, unknown> {
-  // Reject non-plain objects (classes, Date, Map, Array)
-  if (!(deps && typeof deps === "object" && deps.constructor === Object)) {
-    throw new TypeError(
-      `[router.${methodName}] Invalid argument: expected plain object, received ${getTypeDescription(deps)}`,
-    );
-  }
-
-  // Getters can throw, return different values, or have side effects
-  for (const key in deps) {
-    if (Object.getOwnPropertyDescriptor(deps, key)?.get) {
-      throw new TypeError(
-        `[router.${methodName}] Getters not allowed: "${key}"`,
-      );
-    }
-  }
-}
-
-/**
- * Validates that dependency exists (not undefined).
- * Throws ReferenceError if dependency is not found.
- */
-export function validateDependencyExists(
-  value: unknown,
-  dependencyName: string,
-): asserts value is NonNullable<unknown> {
-  if (value === undefined) {
-    throw new ReferenceError(
-      `[router.getDependency]: dependency "${dependencyName}" not found`,
-    );
-  }
-}
-
-/**
- * Validates that adding dependencies won't exceed the hard limit.
- * Called before bulk operations to ensure atomicity.
- */
-export function validateDependencyLimit(
-  currentCount: number,
-  newCount: number,
-  methodName: string,
-  maxDependencies: number = DEFAULT_LIMITS.maxDependencies,
-): void {
-  if (maxDependencies === 0) {
-    return;
-  }
-
-  const totalCount = currentCount + newCount;
-
-  if (totalCount >= maxDependencies) {
-    throw new Error(
-      `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). ` +
-        `Current: ${totalCount}. This is likely a bug in your code.`,
-    );
-  }
-}

package/src/namespaces/EventBusNamespace/validators.ts

@@ -1,36 +0,0 @@
-// packages/core/src/namespaces/EventBusNamespace/validators.ts
-
-/**
- * Static validation functions for EventBusNamespace.
- * Called by Router facade before instance methods.
- */
-
-import { validEventNames } from "../../constants";
-
-import type { EventMethodMap } from "../../types";
-import type { EventName, Plugin } from "@real-router/types";
-
-/**
- * Validates event name is one of the known event names.
- */
-export function validateEventName(eventName: unknown): void {
-  if (!validEventNames.has(eventName as EventName)) {
-    throw new Error(`Invalid event name: ${String(eventName)}`);
-  }
-}
-
-/**
- * Validates addEventListener arguments (event name + callback).
- */
-export function validateListenerArgs<E extends EventName>(
-  eventName: E,
-  cb: Plugin[EventMethodMap[E]],
-): void {
-  validateEventName(eventName);
-
-  if (typeof cb !== "function") {
-    throw new TypeError(
-      `Expected callback to be a function for event ${eventName}`,
-    );
-  }
-}

package/src/namespaces/NavigationNamespace/validators.ts

@@ -1,47 +0,0 @@
-// packages/core/src/namespaces/NavigationNamespace/validators.ts
-
-/**
- * Static validation functions for NavigationNamespace.
- * Called by Router facade before instance methods.
- */
-
-import { getTypeDescription, isNavigationOptions } from "type-guards";
-
-import type { NavigationOptions } from "@real-router/types";
-
-/**
- * Validates navigate route name argument.
- */
-export function validateNavigateArgs(name: unknown): asserts name is string {
-  if (typeof name !== "string") {
-    throw new TypeError(
-      `[router.navigate] Invalid route name: expected string, got ${getTypeDescription(name)}`,
-    );
-  }
-}
-
-/**
- * Validates navigateToDefault arguments.
- */
-export function validateNavigateToDefaultArgs(opts: unknown): void {
-  // If opts is provided, it must be an object (NavigationOptions)
-  if (opts !== undefined && (typeof opts !== "object" || opts === null)) {
-    throw new TypeError(
-      `[router.navigateToDefault] Invalid options: ${getTypeDescription(opts)}. Expected NavigationOptions object.`,
-    );
-  }
-}
-
-/**
- * Validates that opts is a valid NavigationOptions object.
- */
-export function validateNavigationOptions(
-  opts: unknown,
-  methodName: string,
-): asserts opts is NavigationOptions {
-  if (!isNavigationOptions(opts)) {
-    throw new TypeError(
-      `[router.${methodName}] Invalid options: ${getTypeDescription(opts)}. Expected NavigationOptions object.`,
-    );
-  }
-}

package/src/namespaces/RouteLifecycleNamespace/validators.ts

@@ -1,65 +0,0 @@
-// packages/core/src/namespaces/RouteLifecycleNamespace/validators.ts
-
-/**
- * Static validation functions for RouteLifecycleNamespace.
- * Called by Router facade before instance methods.
- */
-
-import { isBoolean, getTypeDescription } from "type-guards";
-
-import { DEFAULT_LIMITS } from "../../constants";
-
-import type { GuardFnFactory } from "../../types";
-import type { DefaultDependencies } from "@real-router/types";
-
-/**
- * Validates that a handler is either a boolean or a factory function.
- */
-export function validateHandler<D extends DefaultDependencies>(
-  handler: unknown,
-  methodName: string,
-): asserts handler is GuardFnFactory<D> | boolean {
-  if (!isBoolean(handler) && typeof handler !== "function") {
-    throw new TypeError(
-      `[router.${methodName}] Handler must be a boolean or factory function, ` +
-        `got ${getTypeDescription(handler)}`,
-    );
-  }
-}
-
-/**
- * Validates that a route is not currently being registered.
- * Prevents self-modification during factory compilation.
- */
-export function validateNotRegistering(
-  isRegistering: boolean,
-  name: string,
-  methodName: string,
-): void {
-  if (isRegistering) {
-    throw new Error(
-      `[router.${methodName}] Cannot modify route "${name}" during its own registration`,
-    );
-  }
-}
-
-/**
- * Validates that adding a new handler won't exceed the hard limit.
- */
-export function validateHandlerLimit(
-  currentCount: number,
-  methodName: string,
-  maxLifecycleHandlers: number = DEFAULT_LIMITS.maxLifecycleHandlers,
-): void {
-  if (maxLifecycleHandlers === 0) {
-    return;
-  }
-
-  if (currentCount >= maxLifecycleHandlers) {
-    throw new Error(
-      `[router.${methodName}] Lifecycle handler limit exceeded (${maxLifecycleHandlers}). ` +
-        `This indicates too many routes with individual handlers. ` +
-        `Consider using plugins for cross-cutting concerns.`,
-    );
-  }
-}