@real-router/core 0.22.0 → 0.23.0

package/src/namespaces/RoutesNamespace/validators.ts

@@ -0,0 +1,331 @@
+// packages/core/src/namespaces/RoutesNamespace/validators.ts
+
+/**
+ * Static validation functions for RoutesNamespace.
+ * Called by Router facade before instance methods.
+ *
+ * Extracted from RoutesNamespace class for better separation of concerns.
+ */
+
+import { validateRoute } from "route-tree";
+import {
+  isString,
+  validateRouteName,
+  isParams,
+  getTypeDescription,
+} from "type-guards";
+
+import { validateRouteProperties, validateForwardToTargets } from "./helpers";
+
+import type { Route, RouteConfigUpdate } from "../../types";
+import type { DefaultDependencies } from "@real-router/types";
+import type { RouteTree } from "route-tree";
+
+/**
+ * Validates removeRoute arguments.
+ */
+export function validateRemoveRouteArgs(name: unknown): asserts name is string {
+  validateRouteName(name, "removeRoute");
+}
+
+/**
+ * Validates setRootPath arguments.
+ */
+export function validateSetRootPathArgs(
+  rootPath: unknown,
+): asserts rootPath is string {
+  if (typeof rootPath !== "string") {
+    throw new TypeError(
+      `[router.setRootPath] rootPath must be a string, got ${getTypeDescription(rootPath)}`,
+    );
+  }
+}
+
+/**
+ * Validates addRoute arguments (route structure and properties).
+ * State-dependent validation (duplicates, tree) happens in instance method.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Route type
+export function validateAddRouteArgs(routes: readonly Route<any>[]): void {
+  for (const route of routes) {
+    // First check if route is an object (before accessing route.name)
+    // Runtime check for invalid types passed via `as any`
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime check
+    if (route === null || typeof route !== "object" || Array.isArray(route)) {
+      throw new TypeError(
+        `[router.addRoute] Route must be an object, got ${getTypeDescription(route)}`,
+      );
+    }
+
+    // Validate route properties (canActivate, canDeactivate, defaultParams, async checks)
+    // Note: validateRouteProperties handles children recursively
+    validateRouteProperties(route, route.name);
+  }
+}
+
+/**
+ * Validates parent option for addRoute.
+ */
+export function validateParentOption(
+  parent: unknown,
+): asserts parent is string {
+  if (typeof parent !== "string" || parent === "") {
+    throw new TypeError(
+      `[router.addRoute] parent option must be a non-empty string, got ${getTypeDescription(parent)}`,
+    );
+  }
+
+  // Validate parent is a valid route name format (can contain dots — it's a fullName reference)
+  validateRouteName(parent, "addRoute");
+}
+
+/**
+ * Validates isActiveRoute arguments.
+ */
+export function validateIsActiveRouteArgs(
+  name: unknown,
+  params: unknown,
+  strictEquality: unknown,
+  ignoreQueryParams: unknown,
+): void {
+  // Validate name - non-string throws
+  if (!isString(name)) {
+    throw new TypeError(`Route name must be a string`);
+  }
+
+  // Validate params if provided
+  if (params !== undefined && !isParams(params)) {
+    throw new TypeError(`[router.isActiveRoute] Invalid params structure`);
+  }
+
+  // Validate strictEquality if provided
+  if (strictEquality !== undefined && typeof strictEquality !== "boolean") {
+    throw new TypeError(
+      `[router.isActiveRoute] strictEquality must be a boolean, got ${typeof strictEquality}`,
+    );
+  }
+
+  // Validate ignoreQueryParams if provided
+  if (
+    ignoreQueryParams !== undefined &&
+    typeof ignoreQueryParams !== "boolean"
+  ) {
+    throw new TypeError(
+      `[router.isActiveRoute] ignoreQueryParams must be a boolean, got ${typeof ignoreQueryParams}`,
+    );
+  }
+}
+
+/**
+ * Validates forwardState/buildState arguments.
+ */
+export function validateStateBuilderArgs(
+  routeName: unknown,
+  routeParams: unknown,
+  methodName: string,
+): void {
+  if (!isString(routeName)) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid routeName: ${getTypeDescription(routeName)}. Expected string.`,
+    );
+  }
+
+  if (!isParams(routeParams)) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid routeParams: ${getTypeDescription(routeParams)}. Expected plain object.`,
+    );
+  }
+}
+
+/**
+ * Validates updateRoute basic arguments (name and updates object structure).
+ * Does NOT read property values to allow caller to cache them first.
+ */
+export function validateUpdateRouteBasicArgs<
+  Dependencies extends DefaultDependencies,
+>(
+  name: unknown,
+  updates: unknown,
+): asserts updates is RouteConfigUpdate<Dependencies> {
+  // Validate name
+  validateRouteName(name, "updateRoute");
+
+  if (name === "") {
+    throw new ReferenceError(
+      `[router.updateRoute] Invalid name: empty string. Cannot update root node.`,
+    );
+  }
+
+  // Validate updates is not null
+
+  if (updates === null) {
+    throw new TypeError(
+      `[real-router] updateRoute: updates must be an object, got null`,
+    );
+  }
+
+  // Validate updates is an object (not array)
+  if (typeof updates !== "object" || Array.isArray(updates)) {
+    throw new TypeError(
+      `[real-router] updateRoute: updates must be an object, got ${getTypeDescription(updates)}`,
+    );
+  }
+}
+
+/**
+ * Asserts that a function is not async (native or transpiled).
+ * Checks both constructor name and toString() for __awaiter pattern.
+ */
+/* v8 ignore next 12 -- @preserve: transpiled async (__awaiter) branch tested in addRoute */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type -- needs constructor.name access
+function assertNotAsync(value: Function, paramName: string): void {
+  if (
+    (value as { constructor: { name: string } }).constructor.name ===
+      "AsyncFunction" ||
+    (value as { toString: () => string }).toString().includes("__awaiter")
+  ) {
+    throw new TypeError(
+      `[real-router] updateRoute: ${paramName} cannot be an async function`,
+    );
+  }
+}
+
+/**
+ * Validates that a value is a non-async function, if provided.
+ */
+function validateFunctionParam(value: unknown, paramName: string): void {
+  if (value === undefined || value === null) {
+    return;
+  }
+
+  if (typeof value !== "function") {
+    throw new TypeError(
+      `[real-router] updateRoute: ${paramName} must be a function or null, got ${typeof value}`,
+    );
+  }
+
+  assertNotAsync(value, paramName);
+}
+
+/**
+ * Validates updateRoute property types using pre-cached values.
+ * Called AFTER properties are cached to ensure getters are called only once.
+ */
+export function validateUpdateRoutePropertyTypes(
+  forwardTo: unknown,
+  defaultParams: unknown,
+  decodeParams: unknown,
+  encodeParams: unknown,
+): void {
+  // Validate forwardTo type (existence check is done by instance method)
+  if (forwardTo !== undefined && forwardTo !== null) {
+    if (typeof forwardTo !== "string" && typeof forwardTo !== "function") {
+      throw new TypeError(
+        `[real-router] updateRoute: forwardTo must be a string, function, or null, got ${getTypeDescription(forwardTo)}`,
+      );
+    }
+
+    if (typeof forwardTo === "function") {
+      assertNotAsync(forwardTo, "forwardTo callback");
+    }
+  }
+
+  // Validate defaultParams
+  if (
+    defaultParams !== undefined &&
+    defaultParams !== null &&
+    (typeof defaultParams !== "object" || Array.isArray(defaultParams))
+  ) {
+    throw new TypeError(
+      `[real-router] updateRoute: defaultParams must be an object or null, got ${getTypeDescription(defaultParams)}`,
+    );
+  }
+
+  validateFunctionParam(decodeParams, "decodeParams");
+  validateFunctionParam(encodeParams, "encodeParams");
+}
+
+/**
+ * Validates buildPath arguments.
+ */
+export function validateBuildPathArgs(route: unknown): asserts route is string {
+  if (!isString(route) || route === "") {
+    throw new TypeError(
+      `[real-router] buildPath: route must be a non-empty string, got ${typeof route === "string" ? '""' : typeof route}`,
+    );
+  }
+}
+
+/**
+ * Validates matchPath arguments.
+ */
+export function validateMatchPathArgs(path: unknown): asserts path is string {
+  if (!isString(path)) {
+    throw new TypeError(
+      `[real-router] matchPath: path must be a string, got ${typeof path}`,
+    );
+  }
+}
+
+/**
+ * Validates shouldUpdateNode arguments.
+ */
+export function validateShouldUpdateNodeArgs(
+  nodeName: unknown,
+): asserts nodeName is string {
+  if (!isString(nodeName)) {
+    throw new TypeError(
+      `[router.shouldUpdateNode] nodeName must be a string, got ${typeof nodeName}`,
+    );
+  }
+}
+
+/**
+ * Validates routes for addition to the router.
+ * Checks parent existence, duplicates, and forwardTo targets/cycles.
+ *
+ * @param routes - Routes to validate
+ * @param tree - Current route tree (optional for initial validation)
+ * @param forwardMap - Current forward map for cycle detection
+ * @param parentName - Optional parent route fullName for nesting via addRoute({ parent })
+ */
+export function validateRoutes<Dependencies extends DefaultDependencies>(
+  routes: Route<Dependencies>[],
+  tree?: RouteTree,
+  forwardMap?: Record<string, string>,
+  parentName?: string,
+): void {
+  // Validate parent route exists in tree
+  if (parentName && tree) {
+    let node: RouteTree | undefined = tree;
+
+    for (const segment of parentName.split(".")) {
+      node = node.children.get(segment);
+
+      if (!node) {
+        throw new Error(
+          `[router.addRoute] Parent route "${parentName}" does not exist`,
+        );
+      }
+    }
+  }
+
+  // Tracking sets for duplicate detection
+  const seenNames = new Set<string>();
+  const seenPathsByParent = new Map<string, Set<string>>();
+
+  for (const route of routes) {
+    validateRoute(
+      route,
+      "addRoute",
+      tree,
+      parentName ?? "",
+      seenNames,
+      seenPathsByParent,
+    );
+  }
+
+  if (tree && forwardMap) {
+    validateForwardToTargets(routes, forwardMap, tree);
+  }
+}

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -0,0 +1,317 @@
+// packages/core/src/namespaces/StateNamespace/StateNamespace.ts
+
+import {
+  getTypeDescription,
+  isParams,
+  isString,
+  validateState,
+} from "type-guards";
+
+import { areParamValuesEqual, getUrlParamsFromMeta } from "./helpers";
+import { constants } from "../../constants";
+import { freezeStateInPlace } from "../../helpers";
+
+import type { StateNamespaceDependencies } from "./types";
+import type {
+  NavigationOptions,
+  Params,
+  State,
+  StateMetaInput,
+} from "@real-router/types";
+import type { RouteTreeStateMeta } from "route-tree";
+
+/**
+ * Independent namespace for managing router state storage and creation.
+ *
+ * Static methods handle validation (called by facade).
+ * Instance methods handle state storage, freezing, and creation.
+ */
+export class StateNamespace {
+  /**
+   * Auto-incrementing state ID for tracking navigation history.
+   */
+  #stateId = 0;
+
+  /**
+   * Cached frozen state - avoids structuredClone on every getState() call.
+   */
+  #frozenState: State | undefined = undefined;
+
+  /**
+   * Previous state before the last setState call.
+   */
+  #previousState: State | undefined = undefined;
+
+  /**
+   * Dependencies injected from Router.
+   */
+  #deps!: StateNamespaceDependencies;
+
+  /**
+   * Cache for URL params by route name.
+   */
+  readonly #urlParamsCache = new Map<string, string[]>();
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // =========================================================================
+
+  /**
+   * Validates makeState arguments.
+   */
+  static validateMakeStateArgs(
+    name: unknown,
+    params: unknown,
+    path: unknown,
+    forceId: unknown,
+  ): void {
+    // Validate name is a string
+    if (!isString(name)) {
+      throw new TypeError(
+        `[router.makeState] Invalid name: ${getTypeDescription(name)}. Expected string.`,
+      );
+    }
+
+    // Validate params if provided
+    if (params !== undefined && !isParams(params)) {
+      throw new TypeError(
+        `[router.makeState] Invalid params: ${getTypeDescription(params)}. Expected plain object.`,
+      );
+    }
+
+    // Validate path if provided
+    if (path !== undefined && !isString(path)) {
+      throw new TypeError(
+        `[router.makeState] Invalid path: ${getTypeDescription(path)}. Expected string.`,
+      );
+    }
+
+    // Validate forceId if provided
+    if (forceId !== undefined && typeof forceId !== "number") {
+      throw new TypeError(
+        `[router.makeState] Invalid forceId: ${getTypeDescription(forceId)}. Expected number.`,
+      );
+    }
+  }
+
+  /**
+   * Validates areStatesEqual arguments.
+   */
+  static validateAreStatesEqualArgs(
+    state1: unknown,
+    state2: unknown,
+    ignoreQueryParams: unknown,
+  ): void {
+    // null/undefined are valid (represent "no state")
+    if (state1 != null) {
+      validateState(state1, "areStatesEqual");
+    }
+
+    if (state2 != null) {
+      validateState(state2, "areStatesEqual");
+    }
+
+    if (
+      ignoreQueryParams !== undefined &&
+      typeof ignoreQueryParams !== "boolean"
+    ) {
+      throw new TypeError(
+        `[router.areStatesEqual] Invalid ignoreQueryParams: ${getTypeDescription(ignoreQueryParams)}. Expected boolean.`,
+      );
+    }
+  }
+
+  // =========================================================================
+  // Instance methods (trust input - already validated by facade)
+  // =========================================================================
+
+  /**
+   * Returns the current router state.
+   *
+   * The returned state is deeply frozen (immutable) for safety.
+   * Returns `undefined` if the router has not been started or has been stopped.
+   */
+  get<P extends Params = Params, MP extends Params = Params>():
+    | State<P, MP>
+    | undefined {
+    return this.#frozenState as State<P, MP> | undefined;
+  }
+
+  /**
+   * Sets the current router state.
+   *
+   * The state is deeply frozen before storage to ensure immutability.
+   * The previous state is preserved and accessible via `getPrevious()`.
+   *
+   * @param state - Already validated by facade, or undefined to clear
+   */
+  set(state: State | undefined): void {
+    // Preserve current state as previous before updating
+    this.#previousState = this.#frozenState;
+
+    // If state is already frozen (from makeState()), use it directly.
+    // For external states, freeze in place without cloning.
+    this.#frozenState = state ? freezeStateInPlace(state) : undefined;
+  }
+
+  /**
+   * Returns the previous router state (before the last navigation).
+   */
+  getPrevious<P extends Params = Params, MP extends Params = Params>():
+    | State<P, MP>
+    | undefined {
+    return this.#previousState as State<P, MP> | undefined;
+  }
+
+  reset(): void {
+    this.#frozenState = undefined;
+    this.#previousState = undefined;
+    this.#urlParamsCache.clear();
+    this.#stateId = 0;
+  }
+
+  // =========================================================================
+  // Dependency Injection
+  // =========================================================================
+
+  /**
+   * Sets dependencies for state creation methods.
+   * Must be called before using makeState, areStatesEqual, etc.
+   */
+  setDependencies(deps: StateNamespaceDependencies): void {
+    this.#deps = deps;
+  }
+
+  // =========================================================================
+  // State Creation Methods
+  // =========================================================================
+
+  /**
+   * Creates a frozen state object for a route.
+   */
+  makeState<P extends Params = Params, MP extends Params = Params>(
+    name: string,
+    params?: P,
+    path?: string,
+    meta?: StateMetaInput<MP>,
+    forceId?: number,
+  ): State<P, MP> {
+    const madeMeta = meta
+      ? {
+          ...meta,
+          id: forceId ?? ++this.#stateId,
+          params: meta.params,
+          options: meta.options,
+        }
+      : undefined;
+
+    // Optimization: O(1) lookup instead of O(depth) ancestor iteration
+    const defaultParamsConfig = this.#deps.getDefaultParams();
+    const hasDefaultParams = Object.hasOwn(defaultParamsConfig, name);
+
+    // Conditional allocation: avoid spreading when no defaultParams exist
+    let mergedParams: P;
+
+    if (hasDefaultParams) {
+      mergedParams = { ...defaultParamsConfig[name], ...params } as P;
+    } else if (params) {
+      mergedParams = { ...params };
+    } else {
+      mergedParams = {} as P;
+    }
+
+    const state: State<P, MP> = {
+      name,
+      params: mergedParams,
+      path: path ?? this.#deps.buildPath(name, params),
+      meta: madeMeta,
+    };
+
+    return freezeStateInPlace(state);
+  }
+
+  /**
+   * Creates a frozen state object for the "not found" route.
+   */
+  makeNotFoundState(path: string, options: NavigationOptions): State {
+    return this.makeState<{ path: string }>(
+      constants.UNKNOWN_ROUTE,
+      { path },
+      path,
+      {
+        options,
+        params: {},
+      },
+    );
+  }
+
+  // =========================================================================
+  // State Comparison Methods
+  // =========================================================================
+
+  /**
+   * Compares two states for equality.
+   * By default, ignores query params (only compares URL params).
+   */
+  areStatesEqual(
+    state1: State | undefined,
+    state2: State | undefined,
+    ignoreQueryParams = true,
+  ): boolean {
+    if (!state1 || !state2) {
+      return !!state1 === !!state2;
+    }
+
+    if (state1.name !== state2.name) {
+      return false;
+    }
+
+    if (ignoreQueryParams) {
+      const stateMeta = (state1.meta?.params ?? state2.meta?.params) as
+        | RouteTreeStateMeta
+        | undefined;
+
+      const urlParams = stateMeta
+        ? getUrlParamsFromMeta(stateMeta)
+        : this.#getUrlParams(state1.name);
+
+      return urlParams.every((param) =>
+        areParamValuesEqual(state1.params[param], state2.params[param]),
+      );
+    }
+
+    const state1Keys = Object.keys(state1.params);
+    const state2Keys = Object.keys(state2.params);
+
+    if (state1Keys.length !== state2Keys.length) {
+      return false;
+    }
+
+    return state1Keys.every(
+      (param) =>
+        param in state2.params &&
+        areParamValuesEqual(state1.params[param], state2.params[param]),
+    );
+  }
+
+  // =========================================================================
+  // Private Helpers
+  // =========================================================================
+
+  /**
+   * Gets URL params for a route name, using cache for performance.
+   */
+  #getUrlParams(name: string): string[] {
+    const cached = this.#urlParamsCache.get(name);
+
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const result = this.#deps.getUrlParams(name);
+
+    this.#urlParamsCache.set(name, result);
+
+    return result;
+  }
+}

package/src/namespaces/StateNamespace/helpers.ts

@@ -0,0 +1,43 @@
+// packages/core/src/namespaces/StateNamespace/helpers.ts
+
+import type { RouteTreeStateMeta } from "route-tree";
+
+/**
+ * Extracts URL param names from RouteTreeStateMeta.
+ * This is an O(segments × params) operation but avoids tree traversal.
+ */
+export function getUrlParamsFromMeta(meta: RouteTreeStateMeta): string[] {
+  const urlParams: string[] = [];
+
+  for (const segmentName in meta) {
+    const paramMap = meta[segmentName];
+
+    for (const param in paramMap) {
+      if (paramMap[param] === "url") {
+        urlParams.push(param);
+      }
+    }
+  }
+
+  return urlParams;
+}
+
+/**
+ * Compares two parameter values for equality.
+ * Supports deep equality for arrays (common in route params like tags, ids).
+ */
+export function areParamValuesEqual(val1: unknown, val2: unknown): boolean {
+  if (val1 === val2) {
+    return true;
+  }
+
+  if (Array.isArray(val1) && Array.isArray(val2)) {
+    if (val1.length !== val2.length) {
+      return false;
+    }
+
+    return val1.every((v, i) => areParamValuesEqual(v, val2[i]));
+  }
+
+  return false;
+}

package/src/namespaces/StateNamespace/index.ts

@@ -0,0 +1,5 @@
+// packages/core/src/namespaces/StateNamespace/index.ts
+
+export { StateNamespace } from "./StateNamespace";
+
+export type { StateNamespaceDependencies } from "./types";

package/src/namespaces/StateNamespace/types.ts

@@ -0,0 +1,15 @@
+// packages/core/src/namespaces/StateNamespace/types.ts
+
+import type { Params } from "@real-router/types";
+
+/**
+ * Dependencies injected from Router for state creation.
+ */
+export interface StateNamespaceDependencies {
+  /** Get defaultParams config for a route */
+  getDefaultParams: () => Record<string, Params>;
+  /** Build URL path for a route */
+  buildPath: (name: string, params?: Params) => string;
+  /** Get URL params for a route (for areStatesEqual) */
+  getUrlParams: (name: string) => string[];
+}