@real-router/core 0.44.2 → 0.45.1

package/src/types/RouterValidator.ts

@@ -1,154 +0,0 @@
-/**
- * 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,
-    ) => 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/types.ts

@@ -1,69 +0,0 @@
-// packages/core/src/types.ts
-
-/**
- * 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.
- */
-
-import type {
-  LimitsConfig,
-  NavigationOptions,
-  Params,
-  RouterError as RouterErrorType,
-  RouteTreeState,
-  State,
-} from "@real-router/types";
-
-// Re-export from @real-router/types (canonical source)
-export type {
-  GuardFnFactory,
-  PluginFactory,
-  Route,
-  RouteConfigUpdate,
-  EventMethodMap,
-} from "@real-router/types";
-
-/**
- * Event argument tuples for the router's 7 events.
- *
- * Uses explicit `| undefined` unions (not optional `?`) to satisfy
- * `exactOptionalPropertyTypes` when passing undefined args from FSM payloads.
- */
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- must be `type` for Record<string, unknown[]> constraint
-export type RouterEventMap = {
-  $start: [];
-  $stop: [];
-  $$start: [toState: State, fromState: State | undefined];
-  $$leaveApprove: [toState: State, fromState: State | undefined];
-  $$success: [
-    toState: State,
-    fromState: State | undefined,
-    opts: NavigationOptions | undefined,
-  ];
-  $$error: [
-    toState: State | undefined,
-    fromState: State | undefined,
-    error: RouterErrorType | undefined,
-  ];
-  $$cancel: [toState: State, fromState: State | undefined];
-};
-
-/**
- * Immutable limits configuration type.
- */
-export type Limits = Readonly<LimitsConfig>;
-
-/**
- * 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
- */
-export interface BuildStateResultWithSegments<P extends Params = Params> {
-  readonly state: RouteTreeState<P>;
-  readonly segments: readonly unknown[];
-}

package/src/utils/getStaticPaths.ts

@@ -1,50 +0,0 @@
-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,5 +0,0 @@
-export { getStaticPaths } from "./getStaticPaths";
-
-export { serializeState } from "./serializeState";
-
-export type { StaticPathEntries } from "./getStaticPaths";

package/src/utils/serializeState.ts

@@ -1,22 +0,0 @@
-/**
- * XSS-safe JSON serialization for embedding data in HTML `<script>` tags.
- *
- * Escapes `<`, `>`, and `&` to their Unicode equivalents to prevent
- * injection via `</script>` or HTML entities inside inline scripts.
- *
- * @example
- * ```typescript
- * const json = serializeState({ name: "home", path: "/" });
- * const html = `<script>window.__STATE__=${json}</script>`;
- * ```
- */
-export function serializeState(data: unknown): string {
-  if (data === undefined) {
-    return "null";
-  }
-
-  return JSON.stringify(data)
-    .replaceAll("<", String.raw`\u003c`)
-    .replaceAll(">", String.raw`\u003e`)
-    .replaceAll("&", String.raw`\u0026`);
-}

package/src/validation.ts

@@ -1,12 +0,0 @@
-/**
- * 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

@@ -1,261 +0,0 @@
-// packages/core/src/wiring/RouterWiringBuilder.ts
-
-import { getInternals } from "../internals";
-import { resolveOption } from "../namespaces/OptionsNamespace";
-
-import type { EventBusNamespace } from "../namespaces";
-import type { WiringOptions } from "./types";
-import type { NavigationDependencies } from "../namespaces/NavigationNamespace";
-import type { PluginsDependencies } from "../namespaces/PluginsNamespace";
-import type { RouteLifecycleDependencies } from "../namespaces/RouteLifecycleNamespace";
-import type { RouterLifecycleDependencies } from "../namespaces/RouterLifecycleNamespace";
-import type { RoutesDependencies } from "../namespaces/RoutesNamespace";
-import type { DefaultDependencies, Params } from "@real-router/types";
-
-export class RouterWiringBuilder<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  private readonly router: WiringOptions<Dependencies>["router"];
-  private readonly options: WiringOptions<Dependencies>["options"];
-  private readonly limits: WiringOptions<Dependencies>["limits"];
-  private readonly dependenciesStore: WiringOptions<Dependencies>["dependenciesStore"];
-  private readonly state: WiringOptions<Dependencies>["state"];
-  private readonly routes: WiringOptions<Dependencies>["routes"];
-  private readonly routeLifecycle: WiringOptions<Dependencies>["routeLifecycle"];
-  private readonly plugins: WiringOptions<Dependencies>["plugins"];
-  private readonly navigation: WiringOptions<Dependencies>["navigation"];
-  private readonly lifecycle: WiringOptions<Dependencies>["lifecycle"];
-  private readonly eventBus: EventBusNamespace;
-
-  constructor(wiringOptions: WiringOptions<Dependencies>) {
-    this.router = wiringOptions.router;
-    this.options = wiringOptions.options;
-    this.limits = wiringOptions.limits;
-    this.dependenciesStore = wiringOptions.dependenciesStore;
-    this.state = wiringOptions.state;
-    this.routes = wiringOptions.routes;
-    this.routeLifecycle = wiringOptions.routeLifecycle;
-    this.plugins = wiringOptions.plugins;
-    this.navigation = wiringOptions.navigation;
-    this.lifecycle = wiringOptions.lifecycle;
-    this.eventBus = wiringOptions.eventBus;
-  }
-
-  wireLimits(): void {
-    this.dependenciesStore.limits = this.limits;
-    this.plugins.setLimits(this.limits);
-    this.eventBus.setLimits({
-      maxListeners: this.limits.maxListeners,
-      warnListeners: this.limits.warnListeners,
-      maxEventDepth: this.limits.maxEventDepth,
-    });
-    this.routeLifecycle.setLimits(this.limits);
-  }
-
-  wireRouteLifecycleDeps(): void {
-    const routeLifecycleDeps: RouteLifecycleDependencies<Dependencies> = {
-      compileFactory: this.createCompileFactory(),
-    };
-
-    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);
-      },
-      addDeactivateGuard: (name, handler) => {
-        this.routeLifecycle.addCanDeactivate(name, handler, true);
-      },
-      makeState: (name, params, path, meta) =>
-        this.state.makeState(name, params, path, meta),
-      getState: () => this.state.get(),
-      areStatesEqual: (state1, state2, ignoreQueryParams) =>
-        this.state.areStatesEqual(state1, state2, ignoreQueryParams),
-      getDependency: (name) =>
-        this.dependenciesStore.dependencies[name] as Dependencies[typeof name],
-      forwardState: <P extends Params = Params>(name: string, params: P) => {
-        const ctx = getInternals(this.router);
-
-        ctx.validator?.routes.validateStateBuilderArgs(
-          name,
-          params,
-          "forwardState",
-        );
-
-        return ctx.forwardState(name, params);
-      },
-    };
-
-    this.routes.setDependencies(routesDeps);
-    this.routes.setLifecycleNamespace(this.routeLifecycle);
-  }
-
-  wirePluginsDeps(): void {
-    const pluginsDeps: PluginsDependencies<Dependencies> = {
-      addEventListener: (eventName, cb) =>
-        this.eventBus.addEventListener(eventName, cb),
-      canNavigate: () => this.eventBus.canBeginTransition(),
-      compileFactory: this.createCompileFactory(),
-    };
-
-    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 {
-    const navigationDeps: NavigationDependencies = {
-      getOptions: () => this.options.get(),
-      hasRoute: (name) => this.routes.hasRoute(name),
-      getState: () => this.state.get(),
-      setState: (state) => {
-        this.state.set(state);
-      },
-      buildNavigateState: (routeName, routeParams) => {
-        const ctx = getInternals(this.router);
-
-        ctx.validator?.routes.validateStateBuilderArgs(
-          routeName,
-          routeParams,
-          "navigate",
-        );
-
-        const { name, params } = ctx.forwardState(routeName, routeParams);
-        const meta = this.routes.getMetaForState(name);
-
-        if (meta === undefined) {
-          return;
-        }
-
-        const path = ctx.buildPath(name, params);
-
-        return this.state.makeState(name, params, path, meta, true);
-      },
-      resolveDefault: () => {
-        const options = this.options.get();
-
-        return {
-          route: resolveOption(
-            options.defaultRoute,
-            (name: string) =>
-              this.dependenciesStore.dependencies[name as keyof Dependencies],
-          ),
-          params: resolveOption(
-            options.defaultParams,
-            /* v8 ignore next -- @preserve: unreachable unless defaultParams is a callback that calls getDependency */
-            (name: string) =>
-              this.dependenciesStore.dependencies[name as keyof Dependencies],
-          ),
-        };
-      },
-      startTransition: (toState, fromState) => {
-        this.eventBus.sendNavigate(toState, fromState);
-      },
-      cancelNavigation: () => {
-        const toState = this.eventBus.getCurrentToState();
-
-        /* v8 ignore next -- @preserve: getCurrentToState() guaranteed set before TRANSITION_STARTED */
-        if (toState === undefined) {
-          return;
-        }
-
-        this.eventBus.sendCancel(toState, this.state.get());
-      },
-      sendTransitionDone: (state, fromState, opts) => {
-        this.eventBus.sendComplete(state, fromState, opts);
-      },
-      sendTransitionFail: (toState, fromState, error) => {
-        this.eventBus.sendFail(toState, fromState, error);
-      },
-      emitTransitionError: (toState, fromState, error) => {
-        this.eventBus.sendFailSafe(toState, fromState, error);
-      },
-      emitTransitionSuccess: (toState, fromState, opts) => {
-        this.eventBus.emitTransitionSuccess(toState, fromState, opts);
-      },
-      sendLeaveApprove: (toState, fromState) => {
-        this.eventBus.sendLeaveApprove(toState, fromState);
-      },
-      canNavigate: () => this.eventBus.canBeginTransition(),
-      getLifecycleFunctions: () => this.routeLifecycle.getFunctions(),
-      isActive: () => this.router.isActive(),
-      isTransitioning: () => this.eventBus.isTransitioning(),
-      clearCanDeactivate: (name: string) => {
-        this.routeLifecycle.clearCanDeactivate(name);
-      },
-    };
-
-    this.navigation.setDependencies(navigationDeps);
-  }
-
-  wireLifecycleDeps(): void {
-    const lifecycleDeps: RouterLifecycleDependencies = {
-      getOptions: () => this.options.get(),
-      navigate: (name, params, opts) =>
-        this.navigation.navigate(name, params, opts),
-      navigateToNotFound: (path) => this.navigation.navigateToNotFound(path),
-      clearState: () => {
-        this.state.set(undefined);
-      },
-      matchPath: (path) => this.routes.matchPath(path, this.options.get()),
-      completeStart: () => {
-        this.eventBus.sendStarted();
-      },
-      emitTransitionError: (toState, fromState, error) => {
-        this.eventBus.sendFail(toState, fromState, error);
-      },
-    };
-
-    this.lifecycle.setDependencies(lifecycleDeps);
-  }
-
-  wireStateDeps(): void {
-    this.state.setDependencies({
-      getDefaultParams: () => this.routes.getStore().config.defaultParams,
-      buildPath: (name, params) => {
-        const ctx = getInternals(this.router);
-
-        return ctx.buildPath(name, params);
-      },
-      getUrlParams: (name) => this.routes.getUrlParams(name),
-    });
-  }
-
-  private createCompileFactory() {
-    const { router, dependenciesStore } = this;
-
-    return <T>(
-      factory: (
-        router: WiringOptions<Dependencies>["router"],
-        getDependency: <K extends keyof Dependencies>(
-          name: K,
-        ) => Dependencies[K],
-      ) => T,
-    ): T =>
-      factory(
-        router,
-        <K extends keyof Dependencies>(name: K) =>
-          dependenciesStore.dependencies[name] as Dependencies[K],
-      );
-  }
-}

package/src/wiring/index.ts

@@ -1,7 +0,0 @@
-// packages/core/src/wiring/index.ts
-
-export { RouterWiringBuilder } from "./RouterWiringBuilder";
-
-export { wireRouter } from "./wireRouter";
-
-export type { WiringOptions } from "./types";

package/src/wiring/types.ts

@@ -1,47 +0,0 @@
-// packages/core/src/wiring/types.ts
-
-import type {
-  EventBusNamespace,
-  NavigationNamespace,
-  OptionsNamespace,
-  PluginsNamespace,
-  RouteLifecycleNamespace,
-  RouterLifecycleNamespace,
-  RoutesNamespace,
-  StateNamespace,
-} from "../namespaces";
-import type { DependenciesStore } from "../namespaces/DependenciesNamespace/dependenciesStore";
-import type { Router } from "../Router";
-import type { Limits } from "../types";
-import type { DefaultDependencies } from "@real-router/types";
-
-/**
- * Constructor options bag for RouterWiringBuilder.
- *
- * Contains all namespaces, FSM, emitter, and accessors needed to wire
- * inter-namespace dependencies.
- */
-export interface WiringOptions<Dependencies extends DefaultDependencies> {
-  /** Router instance — passed to namespaces for factory initialization */
-  router: Router<Dependencies>;
-  /** Options namespace */
-  options: OptionsNamespace;
-  /** Immutable limits configuration */
-  limits: Limits;
-  /** Dependencies store */
-  dependenciesStore: DependenciesStore<Dependencies>;
-  /** State namespace */
-  state: StateNamespace;
-  /** Routes namespace */
-  routes: RoutesNamespace<Dependencies>;
-  /** Route lifecycle namespace (canActivate/canDeactivate guards) */
-  routeLifecycle: RouteLifecycleNamespace<Dependencies>;
-  /** Plugins namespace */
-  plugins: PluginsNamespace<Dependencies>;
-  /** Navigation namespace */
-  navigation: NavigationNamespace;
-  /** Router lifecycle namespace (start/stop) */
-  lifecycle: RouterLifecycleNamespace;
-  /** EventBus namespace — unified FSM + EventEmitter abstraction */
-  eventBus: EventBusNamespace;
-}

package/src/wiring/wireRouter.ts

@@ -1,26 +0,0 @@
-// packages/core/src/wiring/wireRouter.ts
-
-import type { RouterWiringBuilder } from "./RouterWiringBuilder";
-import type { DefaultDependencies } from "@real-router/types";
-
-/**
- * Director function — calls RouterWiringBuilder methods in the correct dependency order.
- *
- * ORDER MATTERS:
- * - `wireLimits()` first: all namespaces must have limits before any other setup
- * - `wireRouteLifecycleDeps()` BEFORE `wireRoutesDeps()`: RoutesNamespace.setDependencies()
- *   registers pending canActivate handlers which require RouteLifecycleNamespace to be ready
- * - `wireNavigationDeps()` BEFORE `wireLifecycleDeps()`: lifecycle deps reference
- *   NavigationNamespace.navigate() which requires navigation deps to be set
- */
-export function wireRouter<Dependencies extends DefaultDependencies>(
-  builder: RouterWiringBuilder<Dependencies>,
-): void {
-  builder.wireLimits();
-  builder.wireRouteLifecycleDeps();
-  builder.wireRoutesDeps();
-  builder.wirePluginsDeps();
-  builder.wireNavigationDeps();
-  builder.wireLifecycleDeps();
-  builder.wireStateDeps();
-}