@real-router/core 0.38.0 → 0.40.0

package/src/namespaces/OptionsNamespace/validators.ts

@@ -1,252 +1,13 @@
 // packages/core/src/namespaces/OptionsNamespace/validators.ts
 
 /**
- * Static validation functions for OptionsNamespace.
- * Called by Router facade before instance methods.
+ * Minimal crash guard for options.
+ * Full DX validation moved to @real-router/validation-plugin (retrospective pattern).
  */
-
-import { isObjKey, getTypeDescription } from "type-guards";
-
-import {
-  defaultOptions,
-  VALID_OPTION_VALUES,
-  VALID_QUERY_PARAMS,
-} from "./constants";
-import { LIMIT_BOUNDS } from "../../constants";
-
-import type { LimitsConfig, Options } from "@real-router/types";
-
-/**
- * Validates that value is a plain object without getters.
- */
-export function validatePlainObject(
-  value: unknown,
-  optionName: string,
-  methodName: string,
-): asserts value is Record<string, unknown> {
-  if (!value || typeof value !== "object" || value.constructor !== Object) {
-    throw new TypeError(
-      `[router.${methodName}] Invalid type for "${optionName}": ` +
-        `expected plain object, got ${getTypeDescription(value)}`,
-    );
-  }
-
-  // Getters can throw, return different values, or have side effects
-  for (const key in value) {
-    if (Object.getOwnPropertyDescriptor(value, key)?.get) {
-      throw new TypeError(
-        `[router.${methodName}] Getters not allowed in "${optionName}": "${key}"`,
-      );
-    }
-  }
-}
-
-/**
- * Validates queryParams keys and values against allowed enums.
- */
-export function validateQueryParams(
-  value: Record<string, unknown>,
-  methodName: string,
-): void {
-  for (const key in value) {
-    if (!isObjKey(key, VALID_QUERY_PARAMS)) {
-      const validKeys = Object.keys(VALID_QUERY_PARAMS)
-        .map((k) => `"${k}"`)
-        .join(", ");
-
-      throw new TypeError(
-        `[router.${methodName}] Unknown queryParams key: "${key}". ` +
-          `Valid keys: ${validKeys}`,
-      );
-    }
-
-    const paramValue = value[key];
-    const validValues = VALID_QUERY_PARAMS[key];
-    const isValid = (validValues as readonly string[]).includes(
-      paramValue as string,
-    );
-
-    if (!isValid) {
-      const allowedValues = validValues.map((v) => `"${v}"`).join(", ");
-
-      throw new TypeError(
-        `[router.${methodName}] Invalid value for queryParams.${key}: ` +
-          `expected one of ${allowedValues}, got "${String(paramValue)}"`,
-      );
-    }
-  }
-}
-
-/**
- * Validates string enum options against allowed values.
- */
-export function validateEnumOption(
-  optionName: keyof typeof VALID_OPTION_VALUES,
-  value: unknown,
-  methodName: string,
-): void {
-  const validValues = VALID_OPTION_VALUES[optionName];
-  const isValid = (validValues as readonly string[]).includes(value as string);
-
-  if (!isValid) {
-    const allowedValues = validValues.map((v) => `"${v}"`).join(", ");
-
-    throw new TypeError(
-      `[router.${methodName}] Invalid value for "${optionName}": ` +
-        `expected one of ${allowedValues}, got "${String(value)}"`,
-    );
-  }
-}
-
-/**
- * Validates a single option value against expected type and constraints.
- * Skips validation for unknown options - validateOptionExists handles that.
- */
-export function validateOptionValue(
-  optionName: keyof Options,
-  value: unknown,
-  methodName: string,
-): void {
-  // Allow callback functions for dynamic default route/params options
-  // MUST be first check — before object branch (L140) which would reject
-  // functions via validatePlainObject for defaultParams (default = {})
-  if (
-    typeof value === "function" &&
-    (optionName === "defaultRoute" || optionName === "defaultParams")
-  ) {
-    return; // Valid — callback resolved at runtime
-  }
-
-  const expectedValue = defaultOptions[optionName];
-
-  // For object options - ensure plain objects only (not null, arrays, Date, etc)
-  if (expectedValue && typeof expectedValue === "object") {
-    validatePlainObject(value, optionName, methodName);
-
-    if (optionName === "queryParams") {
-      validateQueryParams(value, methodName);
-    }
-
-    return;
-  }
-
-  // For primitives - typeof check first
-  if (typeof value !== typeof expectedValue) {
-    throw new TypeError(
-      `[router.${methodName}] Invalid type for "${optionName}": ` +
-        `expected ${typeof expectedValue}, got ${typeof value}`,
-    );
-  }
-
-  // For string enum options - validate against allowed values
-  if (optionName in VALID_OPTION_VALUES) {
-    validateEnumOption(
-      optionName as keyof typeof VALID_OPTION_VALUES,
-      value,
-      methodName,
-    );
-  }
-}
-
-/**
- * Validates optional fields not in defaultOptions.
- * Note: logger is handled before validateOptions in Router constructor.
- */
-function validateOptionalField(
-  key: string,
-  value: unknown,
-  methodName: string,
-): boolean {
-  if (key === "limits") {
-    if (value !== undefined) {
-      validateLimits(value, methodName);
-    }
-
-    return true;
-  }
-
-  throw new TypeError(`[router.${methodName}] Unknown option: "${key}"`);
-}
-
-/**
- * Validates a partial options object.
- * Called by facade before constructor/withOptions.
- */
-export function validateOptions(
+export function validateOptionsIsObject(
   options: unknown,
-  methodName: string,
-): asserts options is Partial<Options> {
-  if (
-    !options ||
-    typeof options !== "object" ||
-    options.constructor !== Object
-  ) {
-    throw new TypeError(
-      `[router.${methodName}] Invalid options: expected plain object, got ${getTypeDescription(options)}`,
-    );
-  }
-
-  for (const [key, value] of Object.entries(options)) {
-    // Skip optional fields that aren't in defaultOptions (limits, logger, etc.)
-    if (!isObjKey(key, defaultOptions)) {
-      validateOptionalField(key, value, methodName);
-      continue;
-    }
-
-    // Skip undefined values for conditional configuration
-    if (value === undefined) {
-      continue;
-    }
-
-    validateOptionValue(key, value, methodName);
-  }
-}
-
-/**
- * Validates that a limit value is within bounds.
- */
-export function validateLimitValue(
-  limitName: keyof LimitsConfig,
-  value: unknown,
-  methodName: string,
-): void {
-  if (typeof value !== "number" || !Number.isInteger(value)) {
-    throw new TypeError(
-      `[router.${methodName}]: limit "${limitName}" must be an integer, got ${String(value)}`,
-    );
-  }
-
-  const bounds = LIMIT_BOUNDS[limitName];
-
-  if (value < bounds.min || value > bounds.max) {
-    throw new RangeError(
-      `[router.${methodName}]: limit "${limitName}" must be between ${bounds.min} and ${bounds.max}, got ${value}`,
-    );
-  }
-}
-
-/**
- * Validates a partial limits object.
- */
-export function validateLimits(
-  limits: unknown,
-  methodName: string,
-): asserts limits is Partial<LimitsConfig> {
-  if (!limits || typeof limits !== "object" || limits.constructor !== Object) {
-    throw new TypeError(
-      `[router.${methodName}]: invalid limits: expected plain object, got ${typeof limits}`,
-    );
-  }
-
-  for (const [key, value] of Object.entries(limits)) {
-    if (!Object.hasOwn(LIMIT_BOUNDS, key)) {
-      throw new TypeError(`[router.${methodName}]: unknown limit: "${key}"`);
-    }
-
-    if (value === undefined) {
-      continue;
-    }
-
-    validateLimitValue(key as keyof LimitsConfig, value, methodName);
+): asserts options is Record<string, unknown> {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("[router.constructor] options must be a plain object");
   }
 }

package/src/namespaces/PluginsNamespace/PluginsNamespace.ts

@@ -3,16 +3,12 @@
 import { logger } from "@real-router/logger";
 
 import { EVENTS_MAP, EVENT_METHOD_NAMES, LOGGER_CONTEXT } from "./constants";
-import {
-  validatePlugin,
-  validatePluginLimit,
-  validateUsePluginArgs,
-} from "./validators";
+import { validatePlugin } from "./validators";
 import { DEFAULT_LIMITS } from "../../constants";
-import { computeThresholds } from "../../helpers";
 
 import type { PluginsDependencies } from "./types";
 import type { Limits, PluginFactory } from "../../types";
+import type { RouterValidator } from "../../types/RouterValidator";
 import type {
   DefaultDependencies,
   Plugin,
@@ -33,30 +29,17 @@ export class PluginsNamespace<
 
   #deps!: PluginsDependencies<Dependencies>;
   #limits: Limits = DEFAULT_LIMITS;
+  #getValidator: (() => RouterValidator | null) | null = null;
 
   // =========================================================================
   // Static validation methods (called by facade before instance methods)
   // Proxy to functions in validators.ts for separation of concerns
   // =========================================================================
 
-  static validateUsePluginArgs<D extends DefaultDependencies>(
-    plugins: unknown[],
-  ): asserts plugins is PluginFactory<D>[] {
-    validateUsePluginArgs<D>(plugins);
-  }
-
   static validatePlugin(plugin: Plugin): void {
     validatePlugin(plugin);
   }
 
-  static validatePluginLimit(
-    currentCount: number,
-    newCount: number,
-    maxPlugins?: number,
-  ): void {
-    validatePluginLimit(currentCount, newCount, maxPlugins);
-  }
-
   static validateNoDuplicatePlugins<D extends DefaultDependencies>(
     newFactories: PluginFactory<D>[],
     hasPlugin: (factory: PluginFactory<D>) => boolean,
@@ -81,6 +64,12 @@ export class PluginsNamespace<
 
   setLimits(limits: Limits): void {
     this.#limits = limits;
+    // eslint-disable-next-line sonarjs/void-use -- @preserve: limits passed to validator via RouterInternals; void suppresses TS6133 until plugin implements validateCountThresholds
+    void this.#limits;
+  }
+
+  setValidatorGetter(getter: () => RouterValidator | null): void {
+    this.#getValidator = getter;
   }
 
   // =========================================================================
@@ -91,6 +80,7 @@ export class PluginsNamespace<
    * Returns the number of registered plugins.
    * Used by facade for limit validation.
    */
+  /* v8 ignore next 3 -- @preserve: only called via validator interface (ctx.validator?.plugins.validatePluginLimit), not reachable without validation plugin */
   count(): number {
     return this.#plugins.size;
   }
@@ -104,7 +94,9 @@ export class PluginsNamespace<
    */
   use(...factories: PluginFactory<Dependencies>[]): Unsubscribe {
     // Emit warnings for count thresholds (not validation, just warnings)
-    this.#checkCountThresholds(factories.length);
+    this.#getValidator?.()?.plugins.validateCountThresholds(
+      this.#plugins.size + factories.length,
+    );
 
     // Fast path for single plugin (common case)
     if (factories.length === 1) {
@@ -209,6 +201,7 @@ export class PluginsNamespace<
    * Checks if a plugin factory is registered.
    * Used internally by validation to avoid array allocation.
    */
+  /* v8 ignore next 3 -- @preserve: only called via validator interface, not reachable without validation plugin */
   has(factory: PluginFactory<Dependencies>): boolean {
     return this.#plugins.has(factory);
   }
@@ -233,32 +226,6 @@ export class PluginsNamespace<
   // Private methods
   // =========================================================================
 
-  #checkCountThresholds(newCount: number): void {
-    const maxPlugins = this.#limits.maxPlugins;
-
-    if (maxPlugins === 0) {
-      return;
-    }
-
-    const totalCount = newCount + this.#plugins.size;
-
-    const { warn, error } = computeThresholds(maxPlugins);
-
-    if (totalCount >= error) {
-      logger.error(
-        LOGGER_CONTEXT,
-        `${totalCount} plugins registered! ` +
-          `This is excessive and will impact performance. ` +
-          `Hard limit at ${maxPlugins}.`,
-      );
-    } else if (totalCount >= warn) {
-      logger.warn(
-        LOGGER_CONTEXT,
-        `${totalCount} plugins registered. ` + `Consider if all are necessary.`,
-      );
-    }
-  }
-
   /**
    * Deduplicates batch with warning for duplicates within batch.
    * Validation (existing duplicates) is done by facade.
@@ -270,10 +237,7 @@ export class PluginsNamespace<
 
     for (const plugin of plugins) {
       if (seenInBatch.has(plugin)) {
-        logger.warn(
-          LOGGER_CONTEXT,
-          "Duplicate factory in batch, will be registered once",
-        );
+        this.#getValidator?.()?.plugins.warnBatchDuplicates(plugins);
       } else {
         seenInBatch.add(plugin);
       }
@@ -286,6 +250,7 @@ export class PluginsNamespace<
     const appliedPlugin = this.#deps.compileFactory(pluginFactory);
 
     PluginsNamespace.validatePlugin(appliedPlugin);
+    this.#getValidator?.()?.plugins.validatePluginKeys(appliedPlugin);
 
     Object.freeze(appliedPlugin);
 
@@ -304,16 +269,10 @@ export class PluginsNamespace<
           );
 
           if (methodName === "onStart" && this.#deps.canNavigate()) {
-            logger.warn(
-              LOGGER_CONTEXT,
-              "Router already started, onStart will not be called",
-            );
+            this.#getValidator?.()?.plugins.warnPluginAfterStart(methodName);
           }
         } else {
-          logger.warn(
-            LOGGER_CONTEXT,
-            `Property '${methodName}' is not a function, skipping`,
-          );
+          this.#getValidator?.()?.plugins.warnPluginMethodType(methodName);
         }
       }
     }

package/src/namespaces/PluginsNamespace/constants.ts

@@ -1,7 +1,5 @@
 // packages/core/src/namespaces/PluginsNamespace/constants.ts
 
-import { isObjKey } from "type-guards";
-
 import {
   events as EVENTS_CONST,
   plugins as PLUGINS_CONST,
@@ -27,9 +25,8 @@ export const EVENTS_MAP = {
 /**
  * Plugin method names that correspond to router events.
  */
-export const EVENT_METHOD_NAMES = Object.keys(EVENTS_MAP).filter(
-  (eventName): eventName is keyof typeof EVENTS_MAP =>
-    isObjKey<typeof EVENTS_MAP>(eventName, EVENTS_MAP),
-);
+export const EVENT_METHOD_NAMES = Object.keys(
+  EVENTS_MAP,
+) as (keyof typeof EVENTS_MAP)[];
 
 export const LOGGER_CONTEXT = "router.usePlugin";

package/src/namespaces/PluginsNamespace/validators.ts

@@ -5,28 +5,7 @@
  * Called by Router facade before instance methods.
  */
 
-import { getTypeDescription, isObjKey } from "type-guards";
-
-import { EVENTS_MAP } from "./constants";
-import { DEFAULT_LIMITS } from "../../constants";
-
-import type { PluginFactory } from "../../types";
-import type { DefaultDependencies, Plugin } from "@real-router/types";
-
-/**
- * Validates usePlugin arguments - all must be functions.
- */
-export function validateUsePluginArgs<D extends DefaultDependencies>(
-  plugins: unknown[],
-): asserts plugins is PluginFactory<D>[] {
-  for (const [i, plugin] of plugins.entries()) {
-    if (typeof plugin !== "function") {
-      throw new TypeError(
-        `[router.usePlugin] Expected plugin factory function at index ${i}, got ${getTypeDescription(plugin)}`,
-      );
-    }
-  }
-}
+import type { Plugin } from "@real-router/types";
 
 /**
  * Validates that a plugin factory returned a valid plugin object.
@@ -35,9 +14,7 @@ export function validatePlugin(plugin: Plugin): void {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (!(plugin && typeof plugin === "object") || Array.isArray(plugin)) {
     throw new TypeError(
-      `[router.usePlugin] Plugin factory must return an object, got ${getTypeDescription(
-        plugin,
-      )}`,
+      `[router.usePlugin] Plugin factory must return an object, got ${typeof plugin}`,
     );
   }
 
@@ -48,36 +25,4 @@ export function validatePlugin(plugin: Plugin): void {
         `Factory returned a Promise instead of a plugin object.`,
     );
   }
-
-  for (const key in plugin) {
-    if (!(key === "teardown" || isObjKey<typeof EVENTS_MAP>(key, EVENTS_MAP))) {
-      throw new TypeError(
-        `[router.usePlugin] Unknown property '${key}'. ` +
-          `Plugin must only contain event handlers and optional teardown.`,
-      );
-    }
-  }
-}
-
-/**
- * Validates that adding new plugins won't exceed the hard limit.
- */
-export function validatePluginLimit(
-  currentCount: number,
-  newCount: number,
-  maxPlugins: number = DEFAULT_LIMITS.maxPlugins,
-): void {
-  if (maxPlugins === 0) {
-    return;
-  }
-
-  const totalCount = currentCount + newCount;
-
-  if (totalCount > maxPlugins) {
-    throw new Error(
-      `[router.usePlugin] Plugin limit exceeded (${maxPlugins}). ` +
-        `Current: ${currentCount}, Attempting to add: ${newCount}. ` +
-        `This indicates an architectural problem. Consider consolidating plugins.`,
-    );
-  }
 }