@real-router/core 0.38.0 → 0.40.0

package/src/types/RouterValidator.ts

@@ -0,0 +1,155 @@
+/**
+ * RouterValidator interface - defines all validation methods used by the router.
+ *
+ * This interface is implemented by the validation plugin and injected into RouterInternals.
+ * When ctx.validator is null (default), validation is skipped.
+ * When ctx.validator is set (by validation plugin), all methods are called.
+ *
+ * All parameters use `unknown` type to avoid coupling to internal type names.
+ */
+
+export interface RouterValidator {
+  /**
+   * Route validation methods
+   */
+  routes: {
+    validateBuildPathArgs: (route: unknown) => void;
+    validateMatchPathArgs: (path: unknown) => void;
+    validateIsActiveRouteArgs: (
+      name: unknown,
+      params: unknown,
+      strict: unknown,
+      ignoreQP: unknown,
+    ) => void;
+    validateShouldUpdateNodeArgs: (name: unknown) => void;
+    validateStateBuilderArgs: (
+      name: unknown,
+      params: unknown,
+      caller: string,
+    ) => void;
+    validateAddRouteArgs: (routes: unknown) => void;
+    validateRoutes: (routes: unknown[], tree: unknown) => void;
+    validateRemoveRouteArgs: (name: unknown) => void;
+    validateUpdateRouteBasicArgs: (name: unknown, updates: unknown) => void;
+    validateUpdateRoutePropertyTypes: (name: string, updates: unknown) => void;
+    validateUpdateRoute: (
+      name: string,
+      updates: unknown,
+      tree: unknown,
+    ) => void;
+    validateParentOption: (parent: unknown, tree: unknown) => void;
+    validateRouteName: (name: unknown, caller: string) => void;
+    throwIfInternalRoute: (name: unknown, caller: string) => void;
+    throwIfInternalRouteInArray: (routes: unknown[], caller: string) => void;
+    // Retrospective validation
+    validateExistingRoutes: (store: unknown) => void;
+    validateForwardToConsistency: (store: unknown) => void;
+    validateSetRootPathArgs: (rootPath: unknown) => void;
+    guardRouteCallbacks: (route: unknown) => void;
+    guardNoAsyncCallbacks: (route: unknown) => void;
+  };
+
+  /**
+   * Options validation methods
+   */
+  options: {
+    validateLimitValue: (name: string, value: unknown) => void;
+    validateLimits: (limits: unknown) => void;
+    validateOptions: (options: unknown, methodName: string) => void;
+  };
+
+  /**
+   * Dependencies validation methods
+   */
+  dependencies: {
+    validateDependencyName: (name: unknown, caller: string) => void;
+    validateSetDependencyArgs: (
+      name: unknown,
+      value: unknown,
+      caller: string,
+    ) => void;
+    validateDependenciesObject: (deps: unknown, caller: string) => void;
+    validateDependencyExists: (name: string, store: unknown) => void;
+    validateDependencyLimit: (store: unknown, limits: unknown) => void;
+    // Retrospective validation
+    validateDependenciesStructure: (store: unknown) => void;
+    validateDependencyCount: (store: unknown, methodName: string) => void;
+    validateCloneArgs: (dependencies: unknown) => void;
+    warnOverwrite: (name: string, methodName: string) => void;
+    warnBatchOverwrite: (keys: string[], methodName: string) => void;
+    warnRemoveNonExistent: (name: unknown) => void;
+  };
+
+  /**
+   * Plugin validation methods
+   */
+  plugins: {
+    validatePluginLimit: (count: number, limits: unknown) => void;
+    validateNoDuplicatePlugins: (
+      factory: unknown,
+      factories: unknown[],
+    ) => void;
+    validatePluginKeys: (plugin: unknown) => void;
+    validateCountThresholds: (count: number) => void;
+    warnBatchDuplicates: (plugins: unknown[]) => void;
+    warnPluginMethodType: (methodName: string) => void;
+    warnPluginAfterStart: (methodName: string) => void;
+    validateAddInterceptorArgs: (method: unknown, fn: unknown) => void;
+  };
+
+  /**
+   * Lifecycle guard validation methods
+   */
+  lifecycle: {
+    validateHandler: (handler: unknown, caller: string) => void;
+    validateNotRegistering: (
+      name: string,
+      guards: unknown,
+      caller: string,
+    ) => void;
+    validateHandlerLimit: (
+      count: number,
+      limits: unknown,
+      caller: string,
+    ) => void;
+    validateCountThresholds: (count: number, methodName: string) => void;
+    warnOverwrite: (name: string, type: string, methodName: string) => void;
+    warnAsyncGuardSync: (name: string, methodName: string) => void;
+  };
+
+  /**
+   * Navigation validation methods
+   */
+  navigation: {
+    validateNavigateArgs: (name: unknown) => void;
+    validateNavigateToDefaultArgs: (options: unknown) => void;
+    validateNavigationOptions: (options: unknown, caller: string) => void;
+    validateParams: (params: unknown, methodName: string) => void;
+    validateStartArgs: (path: unknown) => void;
+  };
+
+  /**
+   * State validation methods
+   */
+  state: {
+    validateMakeStateArgs: (
+      name: unknown,
+      params: unknown,
+      path: unknown,
+      forceId: unknown,
+    ) => void;
+    validateAreStatesEqualArgs: (
+      s1: unknown,
+      s2: unknown,
+      ignoreQP: unknown,
+    ) => void;
+  };
+
+  /**
+   * Event bus validation methods
+   */
+  eventBus: {
+    validateEventName: (name: unknown) => void;
+    validateListenerArgs: (name: unknown, cb: unknown) => void;
+  };
+}

package/src/utils/getStaticPaths.ts

@@ -0,0 +1,50 @@
+import { getPluginApi } from "../api/getPluginApi";
+
+import type { DefaultDependencies, Router } from "@real-router/types";
+import type { RouteTree } from "route-tree";
+
+export type StaticPathEntries = Record<
+  string,
+  () => Promise<Record<string, string>[]>
+>;
+
+function getLeafRouteNames(node: RouteTree): string[] {
+  const result: string[] = [];
+
+  for (const child of node.children.values()) {
+    if (child.children.size === 0) {
+      result.push(child.fullName);
+    } else {
+      result.push(...getLeafRouteNames(child));
+    }
+  }
+
+  return result;
+}
+
+export async function getStaticPaths<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  router: Router<Dependencies>,
+  entries?: StaticPathEntries,
+): Promise<string[]> {
+  const tree = getPluginApi(router).getTree();
+  const leafRoutes = getLeafRouteNames(tree);
+  const paths: string[] = [];
+
+  for (const routeName of leafRoutes) {
+    const entryFn = entries?.[routeName];
+
+    if (entryFn) {
+      const paramSets = await entryFn();
+
+      for (const params of paramSets) {
+        paths.push(router.buildPath(routeName, params));
+      }
+    } else {
+      paths.push(router.buildPath(routeName, {}));
+    }
+  }
+
+  return paths;
+}

package/src/utils/index.ts

@@ -1 +1,5 @@
+export { getStaticPaths } from "./getStaticPaths";
+
 export { serializeState } from "./serializeState";
+
+export type { StaticPathEntries } from "./getStaticPaths";

package/src/validation.ts

@@ -0,0 +1,12 @@
+/**
+ * Subpath export for @real-router/validation-plugin.
+ *
+ * Provides access to router internals so the plugin can install
+ * ctx.validator and run retrospective validation at registration time.
+ */
+
+export type { RouterValidator } from "./types/RouterValidator";
+
+export { getInternals } from "./internals";
+
+export type { RouterInternals } from "./internals";

package/src/wiring/RouterWiringBuilder.ts

@@ -2,7 +2,6 @@
 
 import { getInternals } from "../internals";
 import { resolveOption } from "../namespaces/OptionsNamespace";
-import { validateStateBuilderArgs } from "../namespaces/RoutesNamespace/validators";
 
 import type { EventBusNamespace } from "../namespaces";
 import type { WiringOptions } from "./types";
@@ -59,15 +58,25 @@ export class RouterWiringBuilder<
     };
 
     this.routeLifecycle.setDependencies(routeLifecycleDeps);
+    this.routeLifecycle.setValidatorGetter(
+      /* v8 ignore next 3 -- @preserve: returns null during construction (before registerInternals) */
+      () => {
+        try {
+          return getInternals(this.router).validator;
+        } catch {
+          return null;
+        }
+      },
+    );
   }
 
   wireRoutesDeps(): void {
     const routesDeps: RoutesDependencies<Dependencies> = {
       addActivateGuard: (name, handler) => {
-        this.routeLifecycle.addCanActivate(name, handler, true, true);
+        this.routeLifecycle.addCanActivate(name, handler, true);
       },
       addDeactivateGuard: (name, handler) => {
-        this.routeLifecycle.addCanDeactivate(name, handler, true, true);
+        this.routeLifecycle.addCanDeactivate(name, handler, true);
       },
       makeState: (name, params, path, meta) =>
         this.state.makeState(name, params, path, meta),
@@ -79,9 +88,11 @@ export class RouterWiringBuilder<
       forwardState: <P extends Params = Params>(name: string, params: P) => {
         const ctx = getInternals(this.router);
 
-        if (!ctx.noValidate) {
-          validateStateBuilderArgs(name, params, "forwardState");
-        }
+        ctx.validator?.routes.validateStateBuilderArgs(
+          name,
+          params,
+          "forwardState",
+        );
 
         return ctx.forwardState(name, params);
       },
@@ -100,6 +111,16 @@ export class RouterWiringBuilder<
     };
 
     this.plugins.setDependencies(pluginsDeps);
+    this.plugins.setValidatorGetter(
+      /* v8 ignore next 3 -- @preserve: returns null during construction (before registerInternals) */
+      () => {
+        try {
+          return getInternals(this.router).validator;
+        } catch {
+          return null;
+        }
+      },
+    );
   }
 
   wireNavigationDeps(): void {
@@ -113,9 +134,11 @@ export class RouterWiringBuilder<
       buildNavigateState: (routeName, routeParams) => {
         const ctx = getInternals(this.router);
 
-        if (!ctx.noValidate) {
-          validateStateBuilderArgs(routeName, routeParams, "navigate");
-        }
+        ctx.validator?.routes.validateStateBuilderArgs(
+          routeName,
+          routeParams,
+          "navigate",
+        );
 
         const { name, params } = ctx.forwardState(routeName, routeParams);
         const meta = this.routes.getMetaForState(name);

package/dist/cjs/index.d-DDimDpYc.d.ts

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