@real-router/core 0.37.0 → 0.39.0

package/README.md

@@ -23,9 +23,11 @@ import { browserPluginFactory } from "@real-router/browser-plugin";
 
 const routes = [
   { name: "home", path: "/" },
-  { name: "users", path: "/users", children: [
-    { name: "profile", path: "/:id" },
-  ]},
+  {
+    name: "users",
+    path: "/users",
+    children: [{ name: "profile", path: "/:id" }],
+  },
 ];
 
 const router = createRouter(routes);
@@ -39,21 +41,21 @@ await router.navigate("users.profile", { id: "123" });
 
 ### Lifecycle
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `start(path)` | `Promise<State>` | Start the router with an initial path |
-| `stop()` | `this` | Stop the router, cancel in-progress transition |
-| `dispose()` | `void` | Permanently terminate (cannot restart) |
-| `isActive()` | `boolean` | Whether the router is started |
+| Method        | Returns          | Description                                    |
+| ------------- | ---------------- | ---------------------------------------------- |
+| `start(path)` | `Promise<State>` | Start the router with an initial path          |
+| `stop()`      | `this`           | Stop the router, cancel in-progress transition |
+| `dispose()`   | `void`           | Permanently terminate (cannot restart)         |
+| `isActive()`  | `boolean`        | Whether the router is started                  |
 
 ### Navigation
 
-| Method | Returns | Description |
-|--------|---------|-------------|
+| Method                              | Returns          | Description                               |
+| ----------------------------------- | ---------------- | ----------------------------------------- |
 | `navigate(name, params?, options?)` | `Promise<State>` | Navigate to a route. Fire-and-forget safe |
-| `navigateToDefault(options?)` | `Promise<State>` | Navigate to the default route |
-| `navigateToNotFound(path?)` | `State` | Synchronously set UNKNOWN_ROUTE state |
-| `canNavigateTo(name, params?)` | `boolean` | Check if guards allow navigation |
+| `navigateToDefault(options?)`       | `Promise<State>` | Navigate to the default route             |
+| `navigateToNotFound(path?)`         | `State`          | Synchronously set UNKNOWN_ROUTE state     |
+| `canNavigateTo(name, params?)`      | `boolean`        | Check if guards allow navigation          |
 
 ```typescript
 await router.navigate("users.profile", { id: "123" });
@@ -67,20 +69,20 @@ controller.abort();
 
 ### State
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `getState()` | `State \| undefined` | Current router state (deeply frozen) |
-| `getPreviousState()` | `State \| undefined` | Previous router state |
-| `areStatesEqual(s1, s2, ignoreQP?)` | `boolean` | Compare two states |
-| `isActiveRoute(name, params?, strict?, ignoreQP?)` | `boolean` | Check if route is active |
-| `buildPath(name, params?)` | `string` | Build URL path from route name |
+| Method                                             | Returns              | Description                          |
+| -------------------------------------------------- | -------------------- | ------------------------------------ |
+| `getState()`                                       | `State \| undefined` | Current router state (deeply frozen) |
+| `getPreviousState()`                               | `State \| undefined` | Previous router state                |
+| `areStatesEqual(s1, s2, ignoreQP?)`                | `boolean`            | Compare two states                   |
+| `isActiveRoute(name, params?, strict?, ignoreQP?)` | `boolean`            | Check if route is active             |
+| `buildPath(name, params?)`                         | `string`             | Build URL path from route name       |
 
 ### Events & Plugins
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `subscribe(listener)` | `Unsubscribe` | Listen to successful transitions |
-| `usePlugin(...plugins)` | `Unsubscribe` | Register plugin factories |
+| Method                  | Returns       | Description                      |
+| ----------------------- | ------------- | -------------------------------- |
+| `subscribe(listener)`   | `Unsubscribe` | Listen to successful transitions |
+| `usePlugin(...plugins)` | `Unsubscribe` | Register plugin factories        |
 
 ```typescript
 const unsub = router.subscribe(({ route, previousRoute }) => {
@@ -102,13 +104,28 @@ import {
 } from "@real-router/core/api";
 ```
 
-| Function | Purpose | Key methods |
-|----------|---------|-------------|
-| `getRoutesApi(router)` | Dynamic route CRUD | `add`, `remove`, `update`, `replace`, `has`, `get` |
-| `getDependenciesApi(router)` | Dependency injection | `get`, `set`, `setAll`, `remove`, `has` |
-| `getLifecycleApi(router)` | Guard registration | `addActivateGuard`, `addDeactivateGuard`, `remove*` |
-| `getPluginApi(router)` | Plugin infrastructure | `makeState`, `matchPath`, `addInterceptor`, `extendRouter`, `getRouteConfig` |
-| `cloneRouter(router, deps?)` | SSR cloning | Shares route definitions, independent state |
+| Function                     | Purpose               | Key methods                                                                  |
+| ---------------------------- | --------------------- | ---------------------------------------------------------------------------- |
+| `getRoutesApi(router)`       | Dynamic route CRUD    | `add`, `remove`, `update`, `replace`, `has`, `get`                           |
+| `getDependenciesApi(router)` | Dependency injection  | `get`, `set`, `setAll`, `remove`, `has`                                      |
+| `getLifecycleApi(router)`    | Guard registration    | `addActivateGuard`, `addDeactivateGuard`, `remove*`                          |
+| `getPluginApi(router)`       | Plugin infrastructure | `makeState`, `matchPath`, `addInterceptor`, `extendRouter`, `getRouteConfig` |
+| `cloneRouter(router, deps?)` | SSR cloning           | Shares route definitions, independent state                                  |
+
+## Utilities
+
+SSR helpers imported from `@real-router/core/utils`.
+
+```typescript
+import { serializeState } from "@real-router/core/utils";
+
+const json = serializeState({ name: "home", path: "/" });
+const html = `<script>window.__STATE__=${json}</script>`;
+```
+
+| Function               | Purpose                                                           |
+| ---------------------- | ----------------------------------------------------------------- |
+| `serializeState(data)` | XSS-safe JSON serialization for embedding in HTML `<script>` tags |
 
 ### `getNavigator(router)` (main entry)
 
@@ -152,7 +169,11 @@ const routes: Route[] = [
       return getDep("authService").isAdmin();
     },
     children: [
-      { name: "dashboard", path: "/dashboard", defaultParams: { tab: "overview" } },
+      {
+        name: "dashboard",
+        path: "/dashboard",
+        defaultParams: { tab: "overview" },
+      },
     ],
   },
   {
@@ -188,6 +209,19 @@ try {
 
 See [RouterError](https://github.com/greydragon888/real-router/wiki/RouterError) and [Error Codes](https://github.com/greydragon888/real-router/wiki/error-codes) for the full reference.
 
+## Validation
+
+Runtime argument validation is available via [@real-router/validation-plugin](https://www.npmjs.com/package/@real-router/validation-plugin):
+
+```typescript
+import { validationPlugin } from "@real-router/validation-plugin";
+
+router.usePlugin(validationPlugin()); // register before start()
+await router.start("/");
+```
+
+The plugin adds descriptive error messages for every public API call. Register it in development, skip in production.
+
 ## Documentation
 
 Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
@@ -201,15 +235,15 @@ Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
 ## Related Packages
 
-| Package | Description |
-|---------|-------------|
-| [@real-router/react](https://www.npmjs.com/package/@real-router/react) | React integration (`RouterProvider`, hooks, `Link`, `RouteView`) |
-| [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin) | Browser History API and URL synchronization |
-| [@real-router/hash-plugin](https://www.npmjs.com/package/@real-router/hash-plugin) | Hash-based routing |
-| [@real-router/rx](https://www.npmjs.com/package/@real-router/rx) | Observable API (`state$`, `events$`, TC39 Observable) |
-| [@real-router/logger-plugin](https://www.npmjs.com/package/@real-router/logger-plugin) | Development logging |
-| [@real-router/persistent-params-plugin](https://www.npmjs.com/package/@real-router/persistent-params-plugin) | Parameter persistence |
-| [@real-router/route-utils](https://www.npmjs.com/package/@real-router/route-utils) | Route tree queries and segment testing |
+| Package                                                                                                      | Description                                                      |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| [@real-router/react](https://www.npmjs.com/package/@real-router/react)                                       | React integration (`RouterProvider`, hooks, `Link`, `RouteView`) |
+| [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin)                     | Browser History API and URL synchronization                      |
+| [@real-router/hash-plugin](https://www.npmjs.com/package/@real-router/hash-plugin)                           | Hash-based routing                                               |
+| [@real-router/rx](https://www.npmjs.com/package/@real-router/rx)                                             | Observable API (`state$`, `events$`, TC39 Observable)            |
+| [@real-router/logger-plugin](https://www.npmjs.com/package/@real-router/logger-plugin)                       | Development logging                                              |
+| [@real-router/persistent-params-plugin](https://www.npmjs.com/package/@real-router/persistent-params-plugin) | Parameter persistence                                            |
+| [@real-router/route-utils](https://www.npmjs.com/package/@real-router/route-utils)                           | Route tree queries and segment testing                           |
 
 ## Contributing
 

package/dist/cjs/Router-B-Pev7K2.d.ts

@@ -0,0 +1,46 @@
+import { DefaultDependencies, Router as Router$1, Route, Options, Params, State, PluginFactory, Unsubscribe, SubscribeFn, NavigationOptions } from '@real-router/types';
+
+/**
+ * Router class with integrated namespace architecture.
+ *
+ * All functionality is provided by namespace classes:
+ * - OptionsNamespace: getOptions (immutable)
+ * - DependenciesStore: get/set/remove dependencies
+ * - EventEmitter: subscribe
+ * - StateNamespace: state storage (getState, setState, getPreviousState)
+ * - RoutesNamespace: route tree operations
+ * - RouteLifecycleNamespace: canActivate/canDeactivate guards
+ * - PluginsNamespace: plugin lifecycle
+ * - NavigationNamespace: navigate
+ * - RouterLifecycleNamespace: start, stop, isStarted
+ *
+ * @internal This class implementation is internal. Use createRouter() instead.
+ */
+declare class Router<Dependencies extends DefaultDependencies = DefaultDependencies> implements Router$1<Dependencies> {
+    #private;
+    [key: string]: unknown;
+    /**
+     * @param routes - Route definitions
+     * @param options - Router options
+     * @param dependencies - DI dependencies
+     */
+    constructor(routes?: Route<Dependencies>[], options?: Partial<Options>, dependencies?: Dependencies);
+    isActiveRoute(name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean): boolean;
+    buildPath(route: string, params?: Params): string;
+    getState<P extends Params = Params, MP extends Params = Params>(): State<P, MP> | undefined;
+    getPreviousState(): State | undefined;
+    areStatesEqual(state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean): boolean;
+    shouldUpdateNode(nodeName: string): (toState: State, fromState?: State) => boolean;
+    isActive(): boolean;
+    start(startPath: string): Promise<State>;
+    stop(): this;
+    dispose(): void;
+    canNavigateTo(name: string, params?: Params): boolean;
+    usePlugin(...plugins: (PluginFactory<Dependencies> | false | null | undefined)[]): Unsubscribe;
+    subscribe(listener: SubscribeFn): Unsubscribe;
+    navigate(routeName: string, routeParams?: Params, options?: NavigationOptions): Promise<State>;
+    navigateToDefault(options?: NavigationOptions): Promise<State>;
+    navigateToNotFound(path?: string): State;
+}
+
+export { Router as R };

package/dist/cjs/RouterValidator-mx2Zooya.d.ts

@@ -0,0 +1,136 @@
+import { Params, RouteTreeState, LimitsConfig } from '@real-router/types';
+
+/**
+ * Core-internal types + re-exports from @real-router/types.
+ *
+ * Factory types (PluginFactory, GuardFnFactory) and
+ * route config types (Route, RouteConfigUpdate) are canonical in @real-router/types
+ * and re-exported here for backward compatibility.
+ */
+
+/**
+ * Immutable limits configuration type.
+ */
+type Limits = Readonly<LimitsConfig>;
+/**
+ * Extended build result that includes segments for path building.
+ * Used internally to avoid duplicate getSegmentsByName calls.
+ *
+ * @param segments - Route segments from getSegmentsByName (typed as unknown[] for cross-package compatibility)
+ * @internal
+ */
+interface BuildStateResultWithSegments<P extends Params = Params> {
+    readonly state: RouteTreeState<P>;
+    readonly segments: readonly unknown[];
+}
+
+/**
+ * RouterValidator interface - defines all validation methods used by the router.
+ *
+ * This interface is implemented by the validation plugin and injected into RouterInternals.
+ * When ctx.validator is null (default), validation is skipped.
+ * When ctx.validator is set (by validation plugin), all methods are called.
+ *
+ * All parameters use `unknown` type to avoid coupling to internal type names.
+ */
+interface RouterValidator {
+    /**
+     * Route validation methods
+     */
+    routes: {
+        validateBuildPathArgs: (route: unknown) => void;
+        validateMatchPathArgs: (path: unknown) => void;
+        validateIsActiveRouteArgs: (name: unknown, params: unknown, strict: unknown, ignoreQP: unknown) => void;
+        validateShouldUpdateNodeArgs: (name: unknown) => void;
+        validateStateBuilderArgs: (name: unknown, params: unknown, caller: string) => void;
+        validateAddRouteArgs: (routes: unknown) => void;
+        validateRoutes: (routes: unknown[], tree: unknown) => void;
+        validateRemoveRouteArgs: (name: unknown) => void;
+        validateUpdateRouteBasicArgs: (name: unknown, updates: unknown) => void;
+        validateUpdateRoutePropertyTypes: (name: string, updates: unknown) => void;
+        validateUpdateRoute: (name: string, updates: unknown, tree: unknown) => void;
+        validateParentOption: (parent: unknown, tree: unknown) => void;
+        validateRouteName: (name: unknown, caller: string) => void;
+        throwIfInternalRoute: (name: unknown, caller: string) => void;
+        throwIfInternalRouteInArray: (routes: unknown[], caller: string) => void;
+        validateExistingRoutes: (store: unknown) => void;
+        validateForwardToConsistency: (store: unknown) => void;
+        validateSetRootPathArgs: (rootPath: unknown) => void;
+        guardRouteCallbacks: (route: unknown) => void;
+        guardNoAsyncCallbacks: (route: unknown) => void;
+    };
+    /**
+     * Options validation methods
+     */
+    options: {
+        validateLimitValue: (name: string, value: unknown) => void;
+        validateLimits: (limits: unknown) => void;
+        validateOptions: (options: unknown, methodName: string) => void;
+    };
+    /**
+     * Dependencies validation methods
+     */
+    dependencies: {
+        validateDependencyName: (name: unknown, caller: string) => void;
+        validateSetDependencyArgs: (name: unknown, value: unknown, caller: string) => void;
+        validateDependenciesObject: (deps: unknown, caller: string) => void;
+        validateDependencyExists: (name: string, store: unknown) => void;
+        validateDependencyLimit: (store: unknown, limits: unknown) => void;
+        validateDependenciesStructure: (store: unknown) => void;
+        validateDependencyCount: (store: unknown, methodName: string) => void;
+        validateCloneArgs: (dependencies: unknown) => void;
+        warnOverwrite: (name: string, methodName: string) => void;
+        warnBatchOverwrite: (keys: string[], methodName: string) => void;
+        warnRemoveNonExistent: (name: unknown) => void;
+    };
+    /**
+     * Plugin validation methods
+     */
+    plugins: {
+        validatePluginLimit: (count: number, limits: unknown) => void;
+        validateNoDuplicatePlugins: (factory: unknown, factories: unknown[]) => void;
+        validatePluginKeys: (plugin: unknown) => void;
+        validateCountThresholds: (count: number) => void;
+        warnBatchDuplicates: (plugins: unknown[]) => void;
+        warnPluginMethodType: (methodName: string) => void;
+        warnPluginAfterStart: (methodName: string) => void;
+        validateAddInterceptorArgs: (method: unknown, fn: unknown) => void;
+    };
+    /**
+     * Lifecycle guard validation methods
+     */
+    lifecycle: {
+        validateHandler: (handler: unknown, caller: string) => void;
+        validateNotRegistering: (name: string, guards: unknown, caller: string) => void;
+        validateHandlerLimit: (count: number, limits: unknown, caller: string) => void;
+        validateCountThresholds: (count: number, methodName: string) => void;
+        warnOverwrite: (name: string, type: string, methodName: string) => void;
+        warnAsyncGuardSync: (name: string, methodName: string) => void;
+    };
+    /**
+     * Navigation validation methods
+     */
+    navigation: {
+        validateNavigateArgs: (name: unknown) => void;
+        validateNavigateToDefaultArgs: (options: unknown) => void;
+        validateNavigationOptions: (options: unknown, caller: string) => void;
+        validateParams: (params: unknown, methodName: string) => void;
+        validateStartArgs: (path: unknown) => void;
+    };
+    /**
+     * State validation methods
+     */
+    state: {
+        validateMakeStateArgs: (name: unknown, params: unknown, path: unknown, forceId: unknown) => void;
+        validateAreStatesEqualArgs: (s1: unknown, s2: unknown, ignoreQP: unknown) => void;
+    };
+    /**
+     * Event bus validation methods
+     */
+    eventBus: {
+        validateEventName: (name: unknown) => void;
+        validateListenerArgs: (name: unknown, cb: unknown) => void;
+    };
+}
+
+export type { BuildStateResultWithSegments as B, Limits as L, RouterValidator as R };

package/dist/cjs/api.d.ts

@@ -1,6 +1,7 @@
 import { PluginApi as PluginApi$1, DefaultDependencies, Router, RoutesApi, DependenciesApi, LifecycleApi } from '@real-router/types';
 export { DependenciesApi, LifecycleApi, RoutesApi } from '@real-router/types';
-import { a as RouteTree, R as Router$1 } from './index.d-DDimDpYc.js';
+import { R as RouteTree } from './index.d-y2b-8_3Y.js';
+import { R as Router$1 } from './Router-B-Pev7K2.js';
 
 interface PluginApi extends Omit<PluginApi$1, "getTree"> {
     getTree: () => RouteTree;