@real-router/validation-plugin 0.0.1

package/src/validators/routes.ts

@@ -0,0 +1,578 @@
+// packages/validation-plugin/src/validators/routes.ts
+
+/**
+ * DX-only validator functions for RoutesNamespace.
+ * Copied from packages/core/src/namespaces/RoutesNamespace/validators.ts
+ * (excludes validateRemoveRoute/validateClearRoutes — those are in routeGuards.ts)
+ */
+
+import { resolveForwardChain } from "@real-router/core";
+import { validateRoute } from "route-tree";
+import {
+  isString,
+  validateRouteName,
+  isParams,
+  getTypeDescription,
+} from "type-guards";
+
+import { validateForwardToTargets, validateRouteProperties } from "./forwardTo";
+
+import type {
+  Route,
+  RouteConfigUpdate,
+  DefaultDependencies,
+  Params,
+} from "@real-router/core";
+import type { Matcher, RouteTree } from "route-tree";
+
+// Internal constant (matches core's INTERNAL_ROUTE_PREFIX)
+const INTERNAL_ROUTE_PREFIX = "@@";
+
+// Minimal local type — only the forwardMap field used by this file
+// (RouteConfig from core is not exported from @real-router/core public API)
+interface RouteConfigLike {
+  forwardMap: Record<string, string>;
+}
+
+// Local type - matches ForwardToCallback from @real-router/types
+// (@real-router/types is not a direct dependency of this package)
+type ForwardToCallback<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = (
+  getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K],
+  params: Params,
+) => string;
+
+export function throwIfInternalRoute(name: string, methodName: string): void {
+  if (name.startsWith(INTERNAL_ROUTE_PREFIX)) {
+    throw new Error(
+      `[router.${methodName}] Route name "${name}" uses the reserved "${INTERNAL_ROUTE_PREFIX}" prefix. Routes with this prefix are internal and cannot be modified through the public API.`,
+    );
+  }
+}
+
+export function throwIfInternalRouteInArray(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Route type
+  routes: readonly Route<any>[],
+  methodName: string,
+): void {
+  for (const route of routes) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime safety
+    if (route && typeof route === "object" && typeof route.name === "string") {
+      throwIfInternalRoute(route.name, methodName);
+
+      if (route.children) {
+        throwIfInternalRouteInArray(route.children, methodName);
+      }
+    }
+  }
+}
+
+/**
+ * Validates removeRoute arguments.
+ */
+export function validateRemoveRouteArgs(name: unknown): asserts name is string {
+  validateRouteName(name, "removeRoute");
+}
+
+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)}`,
+    );
+  }
+}
+
+function isAsyncFunction(fn: unknown): boolean {
+  return (
+    (fn as { constructor: { name: string } }).constructor.name ===
+      "AsyncFunction" || String(fn).includes("__awaiter")
+  );
+}
+
+export function guardRouteCallbacks(route: unknown): void {
+  const routeObj = route as { canActivate?: unknown; canDeactivate?: unknown };
+
+  if (
+    routeObj.canActivate !== undefined &&
+    typeof routeObj.canActivate !== "function"
+  ) {
+    throw new TypeError(
+      `[router.addRoute] canActivate must be a function, got ${getTypeDescription(routeObj.canActivate)}`,
+    );
+  }
+
+  if (
+    routeObj.canDeactivate !== undefined &&
+    typeof routeObj.canDeactivate !== "function"
+  ) {
+    throw new TypeError(
+      `[router.addRoute] canDeactivate must be a function, got ${getTypeDescription(routeObj.canDeactivate)}`,
+    );
+  }
+}
+
+export function guardNoAsyncCallbacks(route: unknown): void {
+  const routeObj = route as {
+    decodeParams?: unknown;
+    encodeParams?: unknown;
+    forwardTo?: unknown;
+    name?: unknown;
+  };
+  const routeName = routeObj.name;
+
+  if (
+    routeObj.decodeParams !== undefined &&
+    isAsyncFunction(routeObj.decodeParams)
+  ) {
+    throw new TypeError(
+      `[router.addRoute] decodeParams cannot be async for route "${String(routeName)}"`,
+    );
+  }
+
+  if (
+    routeObj.encodeParams !== undefined &&
+    isAsyncFunction(routeObj.encodeParams)
+  ) {
+    throw new TypeError(
+      `[router.addRoute] encodeParams cannot be async for route "${String(routeName)}"`,
+    );
+  }
+
+  if (
+    typeof routeObj.forwardTo === "function" &&
+    isAsyncFunction(routeObj.forwardTo)
+  ) {
+    throw new TypeError(
+      `[router.addRoute] forwardTo callback cannot be async for route "${String(routeName)}"`,
+    );
+  }
+}
+
+/**
+ * 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(
+      `[router.isActiveRoute] name must be a string, got ${typeof name}`,
+    );
+  }
+
+  // Validate params if provided
+  if (params !== undefined && !isParams(params)) {
+    throw new TypeError(
+      `[router.isActiveRoute] params must be a plain object, got ${getTypeDescription(params)}`,
+    );
+  }
+
+  // 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(
+      `[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(
+      `[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.
+ */
+// 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(
+      `[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(
+      `[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(
+        `[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(
+      `[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(
+      `[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(
+      `[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 ReferenceError(
+          `[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);
+  }
+}
+
+// ============================================================================
+// Instance-level validators (moved from routesCrud.ts)
+// ============================================================================
+
+/**
+ * Collects URL params from segments into a Set.
+ */
+function collectUrlParams(segments: readonly RouteTree[]): Set<string> {
+  const params = new Set<string>();
+
+  for (const segment of segments) {
+    for (const param of segment.paramMeta.urlParams) {
+      params.add(param);
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Validates that forwardTo target doesn't require params that source doesn't have.
+ *
+ * @param sourceName - Source route name
+ * @param targetName - Target route name
+ * @param matcher - Current route matcher
+ */
+export function validateForwardToParamCompatibility(
+  sourceName: string,
+  targetName: string,
+  matcher: Matcher,
+): void {
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const sourceSegments = matcher.getSegmentsByName(
+    sourceName,
+  )! as readonly RouteTree[];
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const targetSegments = matcher.getSegmentsByName(
+    targetName,
+  )! as readonly RouteTree[];
+
+  // Get source URL params as a Set for O(1) lookup
+  const sourceParams = collectUrlParams(sourceSegments);
+
+  // Build target URL params array (inline — no separate helper needed)
+  const targetParams: string[] = [];
+
+  for (const segment of targetSegments) {
+    for (const param of segment.paramMeta.urlParams) {
+      targetParams.push(param);
+    }
+  }
+
+  // Check if target requires params that source doesn't have
+  const missingParams = targetParams.filter(
+    (param) => !sourceParams.has(param),
+  );
+
+  if (missingParams.length > 0) {
+    throw new Error(
+      `[router.addRoute] forwardTo target "${targetName}" requires params ` +
+        `[${missingParams.join(", ")}] that are not available in source route "${sourceName}"`,
+    );
+  }
+}
+
+/**
+ * Validates that adding forwardTo doesn't create a cycle.
+ * Creates a test map with the new entry and uses resolveForwardChain
+ * to detect cycles before any mutation happens.
+ *
+ * @param sourceName - Source route name
+ * @param targetName - Target route name
+ * @param config - Current route config (forwardMap read-only in this call)
+ */
+export function validateForwardToCycle(
+  sourceName: string,
+  targetName: string,
+  config: RouteConfigLike,
+): void {
+  // Create a test map with the new entry to validate BEFORE mutation
+  const testMap = {
+    ...config.forwardMap,
+    [sourceName]: targetName,
+  };
+
+  // resolveForwardChain will throw if cycle is detected or max depth exceeded
+  resolveForwardChain(sourceName, testMap);
+}
+
+/**
+ * Validates updateRoute instance-level constraints (route existence, forwardTo).
+ *
+ * @param name - Route name (already validated by static method)
+ * @param forwardTo - Cached forwardTo value
+ * @param hasRoute - Function to check route existence
+ * @param matcher - Current route matcher
+ * @param config - Current route config
+ */
+export function validateUpdateRoute<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  name: string,
+  forwardTo: string | ForwardToCallback<Dependencies> | null | undefined,
+  hasRoute: (n: string) => boolean,
+  matcher: Matcher,
+  config: RouteConfigLike,
+): void {
+  // Validate route exists
+  if (!hasRoute(name)) {
+    throw new ReferenceError(
+      `[router.updateRoute] route "${name}" does not exist`,
+    );
+  }
+
+  // Validate forwardTo target exists and is valid (only for string forwardTo)
+  if (
+    forwardTo !== undefined &&
+    forwardTo !== null &&
+    typeof forwardTo === "string"
+  ) {
+    if (!hasRoute(forwardTo)) {
+      throw new Error(
+        `[router.updateRoute] forwardTo target "${forwardTo}" does not exist`,
+      );
+    }
+
+    // Check forwardTo param compatibility
+    validateForwardToParamCompatibility(name, forwardTo, matcher);
+
+    // Check for cycle detection
+    validateForwardToCycle(name, forwardTo, config);
+  }
+}

package/src/validators/state.ts

@@ -0,0 +1,34 @@
+// packages/validation-plugin/src/validators/state.ts
+
+import { isString, isParams, getTypeDescription } from "type-guards";
+
+export function validateMakeStateArgs(
+  name: unknown,
+  params: unknown,
+  path: unknown,
+  forceId: unknown,
+): void {
+  if (!isString(name)) {
+    throw new TypeError(
+      `[router.makeState] Invalid name: ${getTypeDescription(name)}. Expected string.`,
+    );
+  }
+
+  if (params !== undefined && !isParams(params)) {
+    throw new TypeError(
+      `[router.makeState] Invalid params: ${getTypeDescription(params)}. Expected plain object.`,
+    );
+  }
+
+  if (path !== undefined && !isString(path)) {
+    throw new TypeError(
+      `[router.makeState] Invalid path: ${getTypeDescription(path)}. Expected string.`,
+    );
+  }
+
+  if (forceId !== undefined && typeof forceId !== "number") {
+    throw new TypeError(
+      `[router.makeState] Invalid forceId: ${getTypeDescription(forceId)}. Expected number.`,
+    );
+  }
+}