@real-router/validation-plugin

Runtime validation plugin for Real-Router. Activates descriptive type errors and argument checks across all router operations.

Installation

npm install @real-router/validation-plugin

Peer dependency: @real-router/core

Quick Start

import { createRouter } from "@real-router/core";
import { validationPlugin } from "@real-router/validation-plugin";

const router = createRouter(routes);

// Register before start()
router.usePlugin(validationPlugin());

await router.start();

That's it. From this point on, every router call validates its arguments and throws a descriptive TypeError or RouterError on bad input.

What It Does

Without this plugin, core has structural guards (constructor, plugin registration, dispose) and two invariant guards (subscribe — deferred crash hint, navigateToNotFound — silent corruption prevention). No argument validation for navigation methods. With this plugin, you get the full DX layer:

• Descriptive error messages with method names and received values
• Argument shape checks for every public API call
• forwardTo target existence, param compatibility, and cycle detection
• Decoder/encoder async detection (sync required for matchPath/buildPath)
• Dependency store structure validation
• Limits consistency checks

The plugin also runs a retrospective pass at registration time, validating routes and dependencies that were added before usePlugin() was called.

Note on Crash Guards

Core's crash guards always run, regardless of whether this plugin is installed. They prevent the router from crashing on null or completely wrong types. This plugin adds the descriptive error layer on top. You don't need this plugin for crash prevention in production.

API Reference

validationPlugin()

function validationPlugin(): PluginFactory;

Returns a PluginFactory to pass to router.usePlugin(). Takes no arguments.

Throws RouterError("VALIDATION_PLUGIN_AFTER_START") if the router is already active. Always register before router.start().

// Correct
router.usePlugin(validationPlugin());
await router.start();

// Throws VALIDATION_PLUGIN_AFTER_START
await router.start();
router.usePlugin(validationPlugin()); // too late

RouterValidator type

import type { RouterValidator } from "@real-router/validation-plugin";

The full validator interface that core calls into. Re-exported from @real-router/core/validation. Useful if you're building a custom validator or testing validator functions directly.

Retrospective Validation

When you register the plugin, it immediately validates the current state of the router before start() runs. This catches problems in routes or dependencies that were added before usePlugin():

const router = createRouter([
  { name: "home", path: "/" },
  { name: "home", path: "/duplicate" }, // duplicate name — caught retrospectively
]);

router.usePlugin(validationPlugin()); // throws here

If the retrospective pass fails, the plugin rolls back cleanly. The router is left without validation active, and the error propagates to your code.

What Gets Validated

| Namespace | Validated operations | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Routes | buildPath, matchPath, isActiveRoute, shouldUpdateNode, addRoute, removeRoute, updateRoute, forwardTo targets and cycles | | Options | limits object shape, individual limit values | | Dependencies | setDependency args, dependency name format, full store structure | | Plugins | Plugin count vs maxPlugins limit, addInterceptor args (method enum + function type) | | Lifecycle | Guard/hook handler type, count vs maxLifecycleHandlers | | Navigation | navigate args, navigateToDefault args, NavigationOptions shape, params validation (navigate, buildPath, canNavigateTo), start path validation | | State | makeState args, areStatesEqual args | | Event bus | Event name format, listener args | | Retrospective | Existing route tree integrity, forwardTo consistency, decoder/encoder types, dependency store structure, limits consistency |

Error Messages

All errors from this plugin use a [router.METHOD] prefix so you can immediately tell which call failed.

[router.navigate] Invalid route name: expected string, got number
[router.navigate] params must be a plain object, got string
[router.start] path must start with "/", got "users/profile"
[router.addInterceptor] Invalid method: "intercept". Must be one of: start, buildPath, forwardState
[router.usePlugin] Plugin limit exceeded (50). Current: 50, Attempting to add: 1.

Error types:

• TypeError — wrong argument type or shape (navigate(42), addInterceptor("x", "notAFn"))
• ReferenceError — resource not found (getDependency("missing"), updateRoute("nonexistent", ...))
• RangeError — limit exceeded (usePlugin() past maxPlugins, addActivateGuard() past maxLifecycleHandlers)

Retrospective validation errors use [validation-plugin] prefix instead, since no specific method was called:

[validation-plugin] validateExistingRoutes: duplicate route name "home"

Related Packages

| Package | Description | | ---------------------------------------------------------------------------------------- | -------------------------------------------- | | @real-router/core | Core router (required peer dependency) | | @real-router/logger-plugin | Development logging with transition tracking | | @real-router/browser-plugin | Browser History API integration |

Contributing

See contributing guidelines for development setup and PR process.

License

MIT © Oleg Ivanov