@real-router/core 0.38.0 → 0.40.0

package/README.md

@@ -114,18 +114,27 @@ import {
 
 ## Utilities
 
-SSR helpers imported from `@real-router/core/utils`.
+SSR/SSG helpers imported from `@real-router/core/utils`.
 
 ```typescript
-import { serializeState } from "@real-router/core/utils";
+import { getStaticPaths, serializeState } from "@real-router/core/utils";
 
+// SSR: XSS-safe data embedding
 const json = serializeState({ name: "home", path: "/" });
 const html = `<script>window.__STATE__=${json}</script>`;
+
+// SSG: enumerate all URLs for pre-rendering
+const paths = await getStaticPaths(router, {
+  "users.profile": async () => [{ id: "1" }, { id: "2" }],
+});
+// → ["/", "/users", "/users/1", "/users/2"]
 ```
 
-| Function               | Purpose                                                           |
-| ---------------------- | ----------------------------------------------------------------- |
-| `serializeState(data)` | XSS-safe JSON serialization for embedding in HTML `<script>` tags |
+| Function                           | Purpose                                                                                     |
+| ---------------------------------- | ------------------------------------------------------------------------------------------- |
+| `serializeState(data)`             | XSS-safe JSON serialization for embedding in HTML `<script>` tags                           |
+| `getStaticPaths(router, entries?)` | Enumerate leaf routes and build URLs for SSG pre-rendering                                  |
+| `StaticPathEntries` (type)         | Type for the `entries` parameter: `Record<string, () => Promise<Record<string, string>[]>>` |
 
 ### `getNavigator(router)` (main entry)
 
@@ -209,6 +218,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)

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;