@real-router/validation-plugin 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/validation-plugin",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "type": "commonjs",
   "description": "Route validation plugin with type guards and parameter validation",
   "main": "./dist/cjs/index.js",
@@ -18,8 +18,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -44,15 +43,15 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.55.0",
+    "@real-router/core": "^0.57.0",
     "@real-router/logger": "^0.3.0"
   },
   "peerDependencies": {
-    "@real-router/core": "^0.55.0"
+    "@real-router/core": "^0.57.0"
   },
   "devDependencies": {
     "route-tree": "^0.3.4",
-    "type-guards": "^0.4.9"
+    "type-guards": "^0.4.10"
   },
   "scripts": {
     "test": "vitest",

package/src/helpers.ts

@@ -1,11 +0,0 @@
-// packages/validation-plugin/src/helpers.ts
-
-export function computeThresholds(limit: number): {
-  warn: number;
-  error: number;
-} {
-  return {
-    warn: Math.floor(limit * 0.2),
-    error: Math.floor(limit * 0.5),
-  };
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-// packages/validation-plugin/src/index.ts
-
-export { validationPlugin } from "./validationPlugin";
-
-export type { RouterValidator } from "@real-router/core/validation";

package/src/validationPlugin.ts

@@ -1,338 +0,0 @@
-// packages/validation-plugin/src/validationPlugin.ts
-
-import { RouterError } from "@real-router/core";
-import { getInternals } from "@real-router/core/validation";
-import {
-  validateRouteName,
-  isState,
-  isBoolean,
-  getTypeDescription,
-} from "type-guards";
-
-import {
-  validateDependencyName,
-  validateSetDependencyArgs as validateSetDependencyArgsRaw,
-  validateDependenciesObject,
-  validateDependencyExists as validateDependencyExistsRaw,
-  validateDependencyCount,
-  validateCloneArgs,
-  warnOverwrite as warnDepsOverwrite,
-  warnBatchOverwrite,
-  warnRemoveNonExistent,
-} from "./validators/dependencies";
-import { validateEventName, validateListenerArgs } from "./validators/eventBus";
-import {
-  validateHandler,
-  validateNotRegistering,
-  validateHandlerLimit,
-  validateLifecycleCountThresholds,
-  warnOverwrite as warnLifecycleOverwrite,
-  warnAsyncGuardSync,
-} from "./validators/lifecycle";
-import {
-  validateNavigateArgs,
-  validateNavigateToDefaultArgs,
-  validateNavigateToStateArgs,
-  validateNavigationOptions,
-  validateNavigateParams,
-  validateStartArgs,
-} from "./validators/navigation";
-import {
-  validateLimitValue,
-  validateLimits,
-  validateOptions,
-} from "./validators/options";
-import {
-  validatePluginLimit,
-  validatePluginKeys,
-  validateCountThresholds as validatePluginCountThresholds,
-  warnBatchDuplicates,
-  warnPluginMethodType,
-  warnPluginAfterStart,
-  validateAddInterceptorArgs,
-} from "./validators/plugins";
-import {
-  validateExistingRoutes,
-  validateForwardToConsistency,
-  validateRoutePropertiesStore,
-  validateForwardToTargetsStore,
-  validateDependenciesStructure,
-  validateLimitsConsistency,
-  validateResolvedDefaultRoute,
-} from "./validators/retrospective";
-import {
-  validateBuildPathArgs,
-  validateMatchPathArgs,
-  validateIsActiveRouteArgs,
-  validateShouldUpdateNodeArgs,
-  validateStateBuilderArgs,
-  validateAddRouteArgs,
-  validateRoutes,
-  validateRemoveRouteArgs,
-  validateUpdateRouteBasicArgs,
-  validateUpdateRoutePropertyTypes,
-  validateUpdateRoute,
-  validateParentOption as validateParentOptionRaw,
-  throwIfInternalRoute,
-  throwIfInternalRouteInArray,
-  validateSetRootPathArgs,
-  guardRouteCallbacks,
-  guardNoAsyncCallbacks,
-} from "./validators/routes";
-import { validateMakeStateArgs } from "./validators/state";
-
-import type { PluginFactory, RouterValidator } from "@real-router/core";
-import type { RouterInternals } from "@real-router/core/validation";
-
-function buildValidatorObject(ctx: RouterInternals): RouterValidator {
-  return {
-    routes: {
-      validateBuildPathArgs,
-      validateMatchPathArgs,
-      validateIsActiveRouteArgs,
-      validateShouldUpdateNodeArgs,
-      validateStateBuilderArgs,
-
-      validateAddRouteArgs(routes) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-        validateAddRouteArgs(routes as any);
-      },
-
-      validateRoutes(routes, store) {
-        const typedStore = store as {
-          tree?: unknown;
-          config?: { forwardMap?: Record<string, string> };
-        };
-
-        validateRoutes(
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-          routes as any,
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-          typedStore.tree as any,
-          typedStore.config?.forwardMap,
-        );
-      },
-      validateRemoveRouteArgs,
-      validateUpdateRouteBasicArgs,
-      validateUpdateRoutePropertyTypes(_name, updates) {
-        const upd = updates as Record<string, unknown>;
-
-        validateUpdateRoutePropertyTypes(
-          upd.forwardTo,
-          upd.defaultParams,
-          upd.decodeParams,
-          upd.encodeParams,
-        );
-      },
-      validateUpdateRoute(name, updates, store) {
-        const typedStore = store as {
-          matcher: {
-            hasRoute: (routeName: string) => boolean;
-            getSegmentsByName: (routeName: string) => unknown;
-          };
-          config: { forwardMap: Record<string, string> };
-        };
-        const forwardTo = (updates as Record<string, unknown>).forwardTo;
-
-        validateUpdateRoute(
-          name,
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-          forwardTo as any,
-          (routeName: string) => typedStore.matcher.hasRoute(routeName),
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-          typedStore.matcher as any,
-          typedStore.config,
-        );
-      },
-      validateParentOption(parent, tree) {
-        validateParentOptionRaw(parent);
-        let node = tree as { children: Map<string, unknown> };
-
-        for (const segment of parent.split(".")) {
-          const child = node.children.get(segment) as
-            | { children: Map<string, unknown> }
-            | undefined;
-
-          if (!child) {
-            throw new ReferenceError(
-              `[router.addRoute] Parent route "${parent}" does not exist`,
-            );
-          }
-
-          node = child;
-        }
-      },
-      validateRouteName(name, caller) {
-        validateRouteName(name, caller);
-      },
-      throwIfInternalRoute(name, caller) {
-        throwIfInternalRoute(name as string, caller);
-      },
-
-      throwIfInternalRouteInArray(routes, caller) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-        throwIfInternalRouteInArray(routes as any, caller);
-      },
-      validateExistingRoutes,
-      validateForwardToConsistency,
-      validateSetRootPathArgs,
-      guardRouteCallbacks,
-      guardNoAsyncCallbacks,
-    },
-    options: {
-      validateLimitValue(name, value) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-        validateLimitValue(name as any, value, "validate");
-      },
-      validateLimits(limits) {
-        validateLimits(limits, "validate");
-      },
-      validateOptions,
-      validateResolvedDefaultRoute,
-    },
-    dependencies: {
-      validateDependencyName,
-      validateSetDependencyArgs(_name, _value, _caller) {
-        validateSetDependencyArgsRaw(_name);
-      },
-      validateDependenciesObject,
-      validateDependencyExists(name, store) {
-        const typedStore = store as { dependencies?: Record<string, unknown> };
-        const value = typedStore.dependencies?.[name];
-
-        validateDependencyExistsRaw(value, name);
-      },
-      // eslint-disable-next-line @typescript-eslint/no-empty-function
-      validateDependencyLimit(_store, _limits) {},
-      validateDependenciesStructure,
-      validateDependencyCount,
-      validateCloneArgs,
-      warnOverwrite: warnDepsOverwrite,
-      warnBatchOverwrite,
-      warnRemoveNonExistent,
-    },
-    plugins: {
-      validatePluginLimit(count, limits) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access
-        validatePluginLimit(count, 1, (limits as any)?.maxPlugins);
-      },
-      // eslint-disable-next-line @typescript-eslint/no-empty-function
-      validateNoDuplicatePlugins(_factory, _factories) {},
-      validatePluginKeys,
-      validateCountThresholds(count) {
-        const maxPlugins = ctx.getOptions().limits?.maxPlugins ?? 50;
-
-        validatePluginCountThresholds(count, maxPlugins);
-      },
-      warnBatchDuplicates,
-      warnPluginMethodType,
-      warnPluginAfterStart,
-      validateAddInterceptorArgs,
-    },
-    lifecycle: {
-      validateHandler,
-      validateNotRegistering(name, _guards, caller) {
-        validateNotRegistering(false, name, caller);
-      },
-      validateHandlerLimit(count, limits, caller) {
-        validateHandlerLimit(
-          count,
-          caller,
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access
-          (limits as any)?.maxLifecycleHandlers,
-        );
-      },
-      validateCountThresholds(count, methodName) {
-        const maxHandlers =
-          ctx.getOptions().limits?.maxLifecycleHandlers ?? 200;
-
-        validateLifecycleCountThresholds(count, methodName, maxHandlers);
-      },
-      warnOverwrite: warnLifecycleOverwrite,
-      warnAsyncGuardSync,
-    },
-    navigation: {
-      validateNavigateArgs,
-      validateNavigateToDefaultArgs,
-      validateNavigateToStateArgs,
-      validateNavigationOptions,
-      validateParams: validateNavigateParams,
-      validateStartArgs,
-    },
-    state: {
-      validateMakeStateArgs,
-      validateAreStatesEqualArgs(s1, s2, ignoreQP) {
-        if (!isState(s1)) {
-          throw new TypeError(
-            `[router.areStatesEqual] Invalid state1: ${getTypeDescription(s1)}. Expected State object.`,
-          );
-        }
-        if (!isState(s2)) {
-          throw new TypeError(
-            `[router.areStatesEqual] Invalid state2: ${getTypeDescription(s2)}. Expected State object.`,
-          );
-        }
-        if (ignoreQP !== undefined && !isBoolean(ignoreQP)) {
-          throw new TypeError(
-            `[router.areStatesEqual] Invalid ignoreQueryParams: ${getTypeDescription(ignoreQP)}. Expected boolean.`,
-          );
-        }
-      },
-    },
-    eventBus: {
-      validateEventName,
-
-      validateListenerArgs(name, cb) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        validateListenerArgs(name as any, cb as any);
-      },
-    },
-  };
-}
-
-export function validationPlugin(): PluginFactory {
-  // eslint-disable-next-line unicorn/consistent-function-scoping
-  return (router) => {
-    const ctx = getInternals(router);
-
-    if (router.isActive()) {
-      throw new RouterError("VALIDATION_PLUGIN_AFTER_START", {
-        message: "validation-plugin must be registered before router.start()",
-      });
-    }
-
-    // RouterInternals.validator is now mutable — direct assignment works
-    ctx.validator = buildValidatorObject(ctx);
-
-    try {
-      const store = ctx.routeGetStore();
-      const deps = ctx.dependenciesGetStore();
-      const options = ctx.getOptions();
-
-      validateExistingRoutes(store);
-      validateForwardToConsistency(store);
-      validateRoutePropertiesStore(store);
-      validateForwardToTargetsStore(store);
-      validateDependenciesStructure(deps);
-      validateLimitsConsistency(options, store, deps);
-      ctx.validator.options.validateOptions(
-        options,
-        "constructor (retrospective)",
-      );
-
-      if (typeof options.defaultRoute === "string") {
-        validateResolvedDefaultRoute(options.defaultRoute, store);
-      }
-    } catch (error) {
-      ctx.validator = null;
-
-      throw error;
-    }
-
-    return {
-      teardown() {
-        ctx.validator = null;
-      },
-    };
-  };
-}

package/src/validators/dependencies.ts

@@ -1,159 +0,0 @@
-// packages/validation-plugin/src/validators/dependencies.ts
-
-import { logger } from "@real-router/logger";
-import { getTypeDescription } from "type-guards";
-
-import { computeThresholds } from "../helpers";
-
-const DEFAULT_MAX_DEPENDENCIES = 100;
-
-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}`,
-    );
-  }
-}
-
-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}`,
-    );
-  }
-}
-
-export function validateDependenciesObject(
-  deps: unknown,
-  methodName: string,
-): asserts deps is Record<string, unknown> {
-  if (!(deps && typeof deps === "object" && deps.constructor === Object)) {
-    throw new TypeError(
-      `[router.${methodName}] Invalid argument: expected plain object, received ${getTypeDescription(deps)}`,
-    );
-  }
-
-  for (const key in deps) {
-    if (Object.getOwnPropertyDescriptor(deps, key)?.get) {
-      throw new TypeError(
-        `[router.${methodName}] Getters not allowed: "${key}"`,
-      );
-    }
-  }
-}
-
-export function validateDependencyExists(
-  value: unknown,
-  dependencyName: string,
-): asserts value is NonNullable<unknown> {
-  if (value === undefined) {
-    throw new ReferenceError(
-      `[router.getDependency] dependency "${dependencyName}" not found`,
-    );
-  }
-}
-
-export function validateDependencyLimit(
-  currentCount: number,
-  newCount: number,
-  methodName: string,
-  maxDependencies: number = DEFAULT_MAX_DEPENDENCIES,
-): void {
-  if (maxDependencies === 0) {
-    return;
-  }
-
-  const totalCount = currentCount + newCount;
-
-  if (totalCount >= maxDependencies) {
-    throw new RangeError(
-      `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). ` +
-        `Current: ${totalCount}. This is likely a bug in your code.`,
-    );
-  }
-}
-
-export function validateDependencyCount(
-  store: unknown,
-  methodName: string,
-): void {
-  const typedStore = store as {
-    dependencies: Record<string, unknown>;
-    limits?: { maxDependencies?: number };
-  };
-  const maxDependencies =
-    typedStore.limits?.maxDependencies ?? DEFAULT_MAX_DEPENDENCIES;
-
-  if (maxDependencies === 0) {
-    return;
-  }
-
-  const currentCount = Object.keys(typedStore.dependencies).length;
-  const { warn, error } = computeThresholds(maxDependencies);
-
-  if (currentCount >= maxDependencies) {
-    throw new RangeError(
-      `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). Current: ${currentCount}.`,
-    );
-  } else if (currentCount === error) {
-    logger.error(
-      `router.${methodName}`,
-      `${currentCount} dependencies registered! This indicates architectural problems. Hard limit at ${maxDependencies}.`,
-    );
-  } else if (currentCount === warn) {
-    logger.warn(
-      `router.${methodName}`,
-      `${currentCount} dependencies registered. Consider if all are necessary.`,
-    );
-  }
-}
-
-export function validateCloneArgs(dependencies: unknown): void {
-  if (dependencies === undefined) {
-    return;
-  }
-
-  if (
-    !(
-      dependencies &&
-      typeof dependencies === "object" &&
-      dependencies.constructor === Object
-    )
-  ) {
-    throw new TypeError(
-      `[cloneRouter] Invalid dependencies: expected plain object or undefined, received ${typeof dependencies}`,
-    );
-  }
-
-  for (const key in dependencies as Record<string, unknown>) {
-    if (Object.getOwnPropertyDescriptor(dependencies, key)?.get) {
-      throw new TypeError(
-        `[cloneRouter] Getters not allowed in dependencies: "${key}"`,
-      );
-    }
-  }
-}
-
-export function warnOverwrite(name: string, methodName: string): void {
-  logger.warn(
-    `router.${methodName}`,
-    "Router dependency already exists and is being overwritten:",
-    name,
-  );
-}
-
-export function warnBatchOverwrite(keys: string[], methodName: string): void {
-  logger.warn(`router.${methodName}`, "Overwritten:", keys.join(", "));
-}
-
-export function warnRemoveNonExistent(name: unknown): void {
-  logger.warn(
-    "router.removeDependency",
-    `Attempted to remove non-existent dependency: "${typeof name === "string" ? name : String(name)}"`,
-  );
-}

package/src/validators/eventBus.ts

@@ -1,50 +0,0 @@
-// packages/validation-plugin/src/validators/eventBus.ts
-
-import type { Plugin } from "@real-router/core";
-
-// Local types — mirrors EventName and EventMethodMap from @real-router/types
-// (@real-router/types is not a direct dependency of this package)
-interface EventMethodMap {
-  $start: "onStart";
-  $stop: "onStop";
-  $$start: "onTransitionStart";
-  $$leaveApprove: "onTransitionLeaveApprove";
-  $$cancel: "onTransitionCancel";
-  $$success: "onTransitionSuccess";
-  $$error: "onTransitionError";
-}
-
-type EventName = keyof EventMethodMap;
-
-// Local set — mirrors validEventNames from @real-router/core/constants
-// (not exported from @real-router/core public API)
-const validEventNames = new Set<EventName>([
-  "$start",
-  "$stop",
-  "$$start",
-  "$$leaveApprove",
-  "$$cancel",
-  "$$success",
-  "$$error",
-]);
-
-export function validateEventName(eventName: unknown): void {
-  if (!validEventNames.has(eventName as EventName)) {
-    throw new TypeError(
-      `[router.addEventListener] Invalid event name: ${String(eventName)}. Must be one of: $start, $stop, $$start, $$leaveApprove, $$cancel, $$success, $$error`,
-    );
-  }
-}
-
-export function validateListenerArgs<E extends EventName>(
-  eventName: E,
-  cb: Plugin[EventMethodMap[E]],
-): void {
-  validateEventName(eventName);
-
-  if (typeof cb !== "function") {
-    throw new TypeError(
-      `[router.addEventListener] callback must be a function, got ${typeof cb}`,
-    );
-  }
-}