@real-router/core 0.25.4 → 0.27.0

package/README.md

@@ -29,13 +29,16 @@ const routes = [
 
 const router = createRouter(routes);
 
-router.start();
-router.navigate("users.profile", { id: "123" });
+await router.start("/");
+await router.navigate("users.profile", { id: "123" });
 ```
 
 ---
 
-## Essential API
+## Router API
+
+The Router class provides core lifecycle, navigation, state, and subscription methods. 
+Domain-specific operations (routes, dependencies, guards, plugin infrastructure, cloning) are available through standalone API functions for tree-shaking.
 
 ### `createRouter(routes?, options?, dependencies?)`
 
@@ -53,23 +56,23 @@ const router = createRouter(
 
 ### Lifecycle
 
-#### `router.start(startPath?, done?)`
+#### `router.start(path): Promise<State>`
 
-Starts the router. [Wiki](https://github.com/greydragon888/real-router/wiki/start)
+Starts the router with an initial path. Returns a Promise that resolves with the matched state. [Wiki](https://github.com/greydragon888/real-router/wiki/start)
 
 ```typescript
-router.start();
-router.start("/users/123");
-router.start("/users/123", (err, state) => {
-  if (err) console.error(err);
-});
+const state = await router.start("/users/123");
 ```
 
-#### `router.stop()`
+#### `router.stop(): this`
+
+Stops the router. Cancels any in-progress transition. [Wiki](https://github.com/greydragon888/real-router/wiki/stop)
+
+#### `router.dispose(): void`
 
-Stops the router. [Wiki](https://github.com/greydragon888/real-router/wiki/stop)
+Permanently terminates the router. Unlike `stop()`, it cannot be restarted. All mutating methods throw `RouterError(DISPOSED)` after disposal. Idempotent. [Wiki](https://github.com/greydragon888/real-router/wiki/dispose)
 
-#### `router.isActive()`
+#### `router.isActive(): boolean`
 
 Returns whether the router is active (started and has current state). [Wiki](https://github.com/greydragon888/real-router/wiki/isActive)
 
@@ -77,400 +80,246 @@ Returns whether the router is active (started and has current state). [Wiki](htt
 
 ### Navigation
 
-#### `router.navigate(name, params?, options?, done?)`
-
-Navigates to a route by name. Returns a cancel function. [Wiki](https://github.com/greydragon888/real-router/wiki/navigate)
-
-```typescript
-router.navigate("users");
-router.navigate("users.profile", { id: "123" });
-router.navigate("users.profile", { id: "123" }, { replace: true });
-
-// With callback
-router.navigate("users", {}, {}, (err, state) => {
-  if (err) console.error(err);
-});
+All navigation methods return `Promise<State>`.
 
-// Cancellation
-const cancel = router.navigate("users.profile", { id: "123" });
-cancel(); // abort navigation
-```
+#### `router.navigate(name, params?, options?): Promise<State>`
 
-#### `router.getState()`
-
-Returns the current router state. [Wiki](https://github.com/greydragon888/real-router/wiki/getState)
+Navigates to a route by name. [Wiki](https://github.com/greydragon888/real-router/wiki/navigate)
 
 ```typescript
-const state = router.getState();
-// { name: "users.profile", params: { id: "123" }, path: "/users/123" }
-```
-
-#### `router.navigateToDefault(options?, done?)`
+const state = await router.navigate("users.profile", { id: "123" });
 
-Navigates to the default route. [Wiki](https://github.com/greydragon888/real-router/wiki/navigateToDefault)
+// With navigation options
+await router.navigate("users", {}, { replace: true });
 
----
+// Concurrent navigation cancels previous
+router.navigate("slow-route");
+router.navigate("fast-route"); // Previous rejects with TRANSITION_CANCELLED
 
-### Guards
+// Cancel via AbortController
+const controller = new AbortController();
+router.navigate("route", {}, { signal: controller.signal });
+controller.abort(); // rejects with TRANSITION_CANCELLED
 
-#### `router.addActivateGuard(name, guardFactory)`
+// Timeout
+router.navigate("route", {}, { signal: AbortSignal.timeout(5000) });
 
-Registers a guard for route activation. [Wiki](https://github.com/greydragon888/real-router/wiki/canActivate)
-
-```typescript
-router.addActivateGuard("admin", () => (toState, fromState, done) => {
-  if (!isAuthenticated()) {
-    done({ redirect: { name: "login" } });
-  } else {
-    done();
+// Error handling
+try {
+  await router.navigate("admin");
+} catch (err) {
+  if (err instanceof RouterError) {
+    // ROUTE_NOT_FOUND, CANNOT_ACTIVATE, CANNOT_DEACTIVATE,
+    // TRANSITION_CANCELLED, SAME_STATES, ROUTER_DISPOSED
   }
-});
+}
 ```
 
-#### `router.addDeactivateGuard(name, guardFactory)`
+**Fire-and-forget safe:** calling `router.navigate(...)` without `await` suppresses expected errors (`SAME_STATES`, `TRANSITION_CANCELLED`).
 
-Registers a guard for route deactivation. [Wiki](https://github.com/greydragon888/real-router/wiki/canDeactivate)
-
-```typescript
-router.addDeactivateGuard("editor", () => (toState, fromState, done) => {
-  if (hasUnsavedChanges()) {
-    done({ error: new Error("Unsaved changes") });
-  } else {
-    done();
-  }
-});
-```
+#### `router.navigateToDefault(options?): Promise<State>`
 
----
+Navigates to the default route. [Wiki](https://github.com/greydragon888/real-router/wiki/navigateToDefault)
 
-### Events
+#### `router.canNavigateTo(name, params?): boolean`
 
-#### `router.subscribe(listener)`
+Synchronously checks if navigation to a route would be allowed by guards. [Wiki](https://github.com/greydragon888/real-router/wiki/canNavigateTo)
 
-Subscribes to successful transitions. [Wiki](https://github.com/greydragon888/real-router/wiki/subscribe)
+---
 
-```typescript
-const unsubscribe = router.subscribe(({ route, previousRoute }) => {
-  console.log("Navigation:", previousRoute?.name, "→", route.name);
-});
-```
+### State
 
-#### `router.addEventListener(event, listener)`
+#### `router.getState(): State | undefined`
 
-Adds an event listener. Returns an unsubscribe function. [Wiki](https://github.com/greydragon888/real-router/wiki/addEventListener)
+Returns the current router state. [Wiki](https://github.com/greydragon888/real-router/wiki/getState)
 
 ```typescript
-import { events } from "@real-router/core";
-
-const unsubscribe = router.addEventListener(
-  events.TRANSITION_START,
-  (toState, fromState) => {
-    console.log("Starting:", toState.name);
-  },
-);
-
-// To remove listener, call the returned unsubscribe function
-unsubscribe();
-
-// Available events:
-// ROUTER_START, ROUTER_STOP
-// TRANSITION_START, TRANSITION_SUCCESS, TRANSITION_ERROR, TRANSITION_CANCEL
+const state = router.getState();
+// { name: "users.profile", params: { id: "123" }, path: "/users/123" }
 ```
 
----
+#### `router.getPreviousState(): State | undefined`
 
-### Plugins
+Returns the previous router state. [Wiki](https://github.com/greydragon888/real-router/wiki/getPreviousState)
 
-#### `router.usePlugin(pluginFactory)`
+#### `router.areStatesEqual(state1, state2, ignoreQueryParams?): boolean`
 
-Registers a plugin. Returns an unsubscribe function. [Wiki](https://github.com/greydragon888/real-router/wiki/usePlugin)
+Compare two states for equality. Query params ignored by default. [Wiki](https://github.com/greydragon888/real-router/wiki/areStatesEqual)
 
-```typescript
-import { browserPluginFactory } from "@real-router/browser-plugin";
+#### `router.shouldUpdateNode(nodeName): (toState, fromState?) => boolean`
 
-const unsubscribe = router.usePlugin(browserPluginFactory());
-```
+Create a predicate to check if a route node should update during transition. [Wiki](https://github.com/greydragon888/real-router/wiki/shouldUpdateNode)
 
 ---
 
-## Advanced API
-
-### Routes
-
-#### `router.addRoute(route, options?): void`
-
-Add a route definition at runtime.
-
-**Parameters:**
+### Path Operations
 
-- `route: Route | Route[]` — route configuration object(s)
-- `options?: { parent?: string }` — optional parent route fullName
+#### `router.buildPath(name, params?): string`
 
-**Examples:**
+Build URL path from route name. [Wiki](https://github.com/greydragon888/real-router/wiki/buildPath)
 
 ```typescript
-// Add route with children syntax
-router.addRoute({
-  name: "users",
-  path: "/users",
-  children: [{ name: "profile", path: "/:id" }],
-});
-
-// Add route under existing parent using { parent } option
-router.addRoute({ name: "profile", path: "/:id" }, { parent: "users" });
-// Creates "users.profile" fullName
-
-// Batch add under same parent
-router.addRoute(
-  [
-    { name: "profile", path: "/:id" },
-    { name: "settings", path: "/settings" },
-  ],
-  { parent: "users" },
-);
+const path = router.buildPath("users.profile", { id: "123" });
+// "/users/123"
 ```
 
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/addRoute)
-
-#### `router.removeRoute(name: string): void`
-
-Remove a route by name.\
-`name: string` — route name to remove\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/removeRoute)
+#### `router.isActiveRoute(name, params?, strictEquality?, ignoreQueryParams?): boolean`
 
-#### `router.getRoute(name: string): Route | undefined`
+Check if route is currently active. [Wiki](https://github.com/greydragon888/real-router/wiki/isActiveRoute)
 
-Get route definition by name.\
-`name: string` — route name\
-Returns: `Route | undefined`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/getRoute)
-
-#### `router.hasRoute(name: string): boolean`
-
-Check if a route exists.\
-`name: string` — route name\
-Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/hasRoute)
-
-#### `router.clearRoutes(): void`
-
-Remove all routes.
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/clearRoutes)
+---
 
-#### `router.updateRoute(name: string, updates: Partial<Route>): void`
+### Events
 
-Update route configuration.\
-`name: string` — route name\
-`updates: Partial<Route>` — properties to update\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/updateRoute)
+#### `router.subscribe(listener): Unsubscribe`
 
-**Note:** To set up route forwarding (redirect), use the `forwardTo` option in route configuration:
+Subscribes to successful transitions. [Wiki](https://github.com/greydragon888/real-router/wiki/subscribe)
 
 ```typescript
-router.addRoute({ name: "old-url", path: "/old", forwardTo: "new-url" });
-// Or update existing route
-router.updateRoute("old-url", { forwardTo: "new-url" });
+const unsubscribe = router.subscribe(({ route, previousRoute }) => {
+  console.log("Navigation:", previousRoute?.name, "->", route.name);
+});
 ```
 
 ---
 
-### State Utilities
-
-#### `router.getPreviousState(): State | undefined`
-
-Get previous router state.\
-Returns: `State | undefined`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/getPreviousState)
-
-#### `router.shouldUpdateNode(nodeName: string): (toState, fromState?) => boolean`
-
-Create a predicate to check if a route node should update during transition.\
-`nodeName: string` — route node name\
-Returns: predicate function\
-[Wiki](https://github.com/greydragon888/real-router/wiki/shouldUpdateNode)
-
-#### `router.areStatesEqual(state1: State, state2: State, ignoreQueryParams?: boolean): boolean`
-
-Compare two states for equality.\
-`state1: State` — first state\
-`state2: State` — second state\
-`ignoreQueryParams?: boolean` — ignore query params (default: true)\
-Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/areStatesEqual)
-
----
-
-### Path Operations
-
-#### `router.buildPath(name: string, params?: Params): string`
-
-Build URL path from route name.\
-`name: string` — route name\
-`params?: Params` — route parameters\
-Returns: `string`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/buildPath)
+### Plugins
 
-#### `router.buildUrl(name: string, params?: Params, options?: object): string`
+#### `router.usePlugin(...plugins): Unsubscribe`
 
-Build full URL from route name (includes base path and query string).\
-`name: string` — route name\
-`params?: Params` — route parameters\
-`options?: object` — URL building options\
-Returns: `string`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/buildUrl)
+Registers one or more plugins. Returns an unsubscribe function. [Wiki](https://github.com/greydragon888/real-router/wiki/usePlugin)
 
-#### `router.isActiveRoute(name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean): boolean`
+```typescript
+import { browserPluginFactory } from "@real-router/browser-plugin";
 
-Check if route is currently active.\
-`name: string` — route name\
-`params?: Params` — route parameters\
-`strictEquality?: boolean` — exact match (default: false)\
-`ignoreQueryParams?: boolean` — ignore query params (default: true)\
-Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/isActiveRoute)
+const unsubscribe = router.usePlugin(browserPluginFactory());
+```
 
 ---
 
-### Dependencies
+## Standalone API
 
-#### `router.getDependency(name: string): unknown`
+Standalone functions provide domain-specific operations. They are tree-shakeable — only imported functions are bundled.
 
-Get a dependency by name.\
-`name: string` — dependency name\
-Returns: `unknown`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/getDependency)
+### Routes — `getRoutesApi(router)`
 
-#### `router.getDependencies(): Dependencies`
+Runtime route management. [Wiki](https://github.com/greydragon888/real-router/wiki/getRoutesApi)
 
-Get all dependencies.\
-Returns: `Dependencies`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/getDependencies)
-
-#### `router.setDependency(name: string, value: unknown): void`
+```typescript
+import { getRoutesApi } from "@real-router/core";
 
-Set a dependency.\
-`name: string` — dependency name\
-`value: unknown` — dependency value\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/setDependency)
+const routes = getRoutesApi(router);
 
-#### `router.setDependencies(deps: Dependencies): void`
+// Add routes
+routes.add({ name: "settings", path: "/settings" });
+routes.add({ name: "profile", path: "/:id" }, { parent: "users" });
 
-Set multiple dependencies.\
-`deps: Dependencies` — dependencies object\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/setDependencies)
+// Query
+routes.has("users"); // true
+routes.get("users"); // Route | undefined
 
-#### `router.hasDependency(name: string): boolean`
+// Modify
+routes.update("users", { forwardTo: "users.list" });
+routes.remove("settings");
+routes.clear();
+```
 
-Check if dependency exists.\
-`name: string` — dependency name\
-Returns: `boolean`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/hasDependency)
+**Methods:** `add`, `remove`, `update`, `clear`, `has`, `get`, `getConfig`
 
-#### `router.removeDependency(name: string): void`
+### Dependencies — `getDependenciesApi(router)`
 
-Remove a dependency.\
-`name: string` — dependency name\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/removeDependency)
+Dependency injection container. [Wiki](https://github.com/greydragon888/real-router/wiki/getDependenciesApi)
 
-#### `router.resetDependencies(): void`
+```typescript
+import { getDependenciesApi } from "@real-router/core";
 
-Remove all dependencies.\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/resetDependencies)
+const deps = getDependenciesApi(router);
 
----
+deps.set("authService", authService);
+deps.get("authService"); // authService
+deps.has("authService"); // true
+deps.getAll(); // { authService: ... }
+deps.remove("authService");
+deps.reset();
+```
 
-### Options
+**Methods:** `get`, `getAll`, `set`, `setAll`, `remove`, `reset`, `has`
 
-#### `router.getOptions(): Options`
+### Guards — `getLifecycleApi(router)`
 
-Get all router options.\
-Returns: `Options`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/getOptions)
+Route activation/deactivation guards. [Wiki](https://github.com/greydragon888/real-router/wiki/getLifecycleApi)
 
----
+```typescript
+import { getLifecycleApi } from "@real-router/core";
 
-### Other
+const lifecycle = getLifecycleApi(router);
 
-#### `router.clone(dependencies?: Dependencies): Router`
+// Guard returns boolean or Promise<boolean> (true = allow, false = block)
+lifecycle.addActivateGuard("admin", () => (toState, fromState) => {
+  return isAuthenticated(); // sync
+});
 
-Clone router for SSR.\
-`dependencies?: Dependencies` — override dependencies\
-Returns: `Router`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/clone)
+lifecycle.addDeactivateGuard("editor", () => async (toState, fromState) => {
+  return !(await checkUnsavedChanges()); // async
+});
 
----
+// Guards receive AbortSignal for cooperative cancellation
+lifecycle.addActivateGuard("dashboard", () => async (toState, fromState, signal) => {
+  const res = await fetch("/api/auth", { signal }); // auto-cancelled on abort
+  return res.ok;
+});
 
-## Plugin Development API
+// Remove guards
+lifecycle.removeActivateGuard("admin");
+lifecycle.removeDeactivateGuard("editor");
+```
 
-The following methods are designed for **plugin authors**. They provide low-level access for advanced use cases like browser history integration, persistent parameters, and custom navigation sources.
+**Methods:** `addActivateGuard`, `addDeactivateGuard`, `removeActivateGuard`, `removeDeactivateGuard`
 
-These methods are stable but intended for plugin development, not application code.
+### Plugin Infrastructure — `getPluginApi(router)`
 
-#### `router.matchPath(path: string): State | undefined`
+Low-level API for plugin authors. Provides access to state building, path matching, event system, and navigation. [Wiki](https://github.com/greydragon888/real-router/wiki/getPluginApi)
 
-Match URL path to route state.\
-`path: string` — URL path to match\
-Returns: `State | undefined`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/matchPath)
+```typescript
+import { getPluginApi } from "@real-router/core";
 
-#### `router.makeState(name, params?, path?, meta?, forceId?): State`
+const api = getPluginApi(router);
 
-Create State with custom `meta.id` for history restoration.\
-`name: string` — route name\
-`params?: Params` — route parameters\
-`path?: string` — URL path\
-`meta?: object` — metadata\
-`forceId?: number` — force specific `meta.id` value\
-Returns: `State`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/makeState)
+// State building
+const state = api.matchPath("/users/123");
+const builtState = api.makeState("users.profile", { id: "123" });
 
-#### `router.buildState(name: string, params?: Params): State | undefined`
+// Event system
+const unsub = api.addEventListener(events.TRANSITION_START, (toState, fromState) => {
+  console.log("Starting:", toState.name);
+});
 
-Validate route and build state with segment metadata.\
-`name: string` — route name\
-`params?: Params` — route parameters\
-Returns: `State | undefined`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/buildState)
+// Navigation with pre-built state
+await api.navigateToState(toState, fromState, opts);
 
-#### `router.forwardState(name: string, params: Params): { name: string; params: Params }`
+// Root path management
+api.setRootPath("/app");
+api.getRootPath(); // "/app"
 
-Resolve route forwarding and merge default params.\
-`name: string` — route name\
-`params: Params` — route parameters\
-Returns: `{ name, params }` — resolved route name and merged params\
-[Wiki](https://github.com/greydragon888/real-router/wiki/forwardState)
+// Forward state interception (used by persistent-params-plugin)
+api.setForwardState((name, params) => ({ name, params: withPersistent(params) }));
+```
 
-#### `router.navigateToState(toState, fromState, opts, done, emitSuccess): CancelFn`
+**Methods:** `makeState`, `buildState`, `buildNavigationState`, `forwardState`, `matchPath`, `setRootPath`, `getRootPath`, `navigateToState`, `addEventListener`, `getOptions`, `getTree`, `getForwardState`, `setForwardState`
 
-Navigate with pre-built State object.\
-`toState: State` — target state\
-`fromState: State | undefined` — current state\
-`opts: NavigationOptions` — navigation options\
-`done: DoneFn` — callback\
-`emitSuccess: boolean` — whether to emit TRANSITION_SUCCESS\
-Returns: `CancelFn`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/navigateToState)
+### SSR Cloning — `cloneRouter(router, deps?)`
 
-#### `router.setRootPath(rootPath: string): void`
+Clone router for server-side rendering. [Wiki](https://github.com/greydragon888/real-router/wiki/cloneRouter)
 
-Dynamically modify router base path.\
-`rootPath: string` — new root path prefix\
-Returns: `void`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/setRootPath)
+```typescript
+import { cloneRouter } from "@real-router/core";
 
-#### `router.getRootPath(): string`
+// Server: clone router per request
+const serverRouter = cloneRouter(router, { request: req });
+await serverRouter.start(req.url);
+```
 
-Read current base path.\
-Returns: `string`\
-[Wiki](https://github.com/greydragon888/real-router/wiki/getRootPath)
+Shares immutable route tree (O(1)), copies mutable state (dependencies, options, plugins, guards).
 
 ---
 
@@ -508,22 +357,25 @@ Navigation errors are instances of `RouterError`:
 ```typescript
 import { RouterError, errorCodes } from "@real-router/core";
 
-router.navigate("users", {}, {}, (err, state) => {
+try {
+  await router.navigate("users");
+} catch (err) {
   if (err instanceof RouterError) {
     console.log(err.code, err.message);
   }
-});
+}
 ```
 
-| Code                | Description                    |
-| ------------------- | ------------------------------ |
-| `ROUTE_NOT_FOUND`   | Route doesn't exist            |
-| `CANNOT_ACTIVATE`   | Blocked by canActivate guard   |
-| `CANNOT_DEACTIVATE` | Blocked by canDeactivate guard |
-| `CANCELLED`         | Navigation was cancelled       |
-| `SAME_STATES`       | Already at target route        |
-| `NOT_STARTED`       | Router not started             |
-| `ALREADY_STARTED`   | Router already started         |
+| Code                  | Description                    |
+| --------------------- | ------------------------------ |
+| `ROUTE_NOT_FOUND`     | Route doesn't exist            |
+| `CANNOT_ACTIVATE`     | Blocked by canActivate guard   |
+| `CANNOT_DEACTIVATE`   | Blocked by canDeactivate guard |
+| `CANCELLED`           | Navigation was cancelled       |
+| `SAME_STATES`         | Already at target route        |
+| `NOT_STARTED`         | Router not started             |
+| `ALREADY_STARTED`     | Router already started         |
+| `DISPOSED`            | Router has been disposed       |
 
 See [RouterError](https://github.com/greydragon888/real-router/wiki/RouterError) and [Error Codes](https://github.com/greydragon888/real-router/wiki/error-codes) for details.