@real-router/helpers 0.1.1 → 0.1.3

package/README.md

@@ -1,20 +1,9 @@
 # @real-router/helpers
 
-[![npm version](https://badge.fury.io/js/@real-router%2Fhelpers.svg)](https://www.npmjs.com/package/@real-router/helpers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
 
-> High-performance route segment testing utilities for Real-Router
-
-## Overview
-
-`@real-router/helpers` provides efficient utilities for testing route name segments in Real-Router applications. These helpers are essential for:
-
-- Conditional rendering based on route hierarchy
-- Active navigation menu items
-- Breadcrumb construction
-- Route-based access guards
-- UI component visibility logic
+Route segment testing utilities for Real-Router. Useful for navigation menus, breadcrumbs, conditional rendering, and route guards.
 
 ## Installation
 
@@ -38,247 +27,113 @@ import {
   areRoutesRelated,
 } from "@real-router/helpers";
 
-// Check if route starts with segment
-startsWithSegment("users.profile.edit", "users"); // true
-startsWithSegment("admin.dashboard", "users"); // false
-
-// Check if route ends with segment
-endsWithSegment("users.profile.edit", "edit"); // true
-endsWithSegment("users.profile.edit", "view"); // false
-
-// Check if route includes segment anywhere
-includesSegment("users.profile.edit", "profile"); // true
-includesSegment("users.profile.edit", "admin"); // false
-
-// Check if routes are related (parent-child or same)
-areRoutesRelated("users", "users.list"); // true
-areRoutesRelated("users", "admin"); // false
+startsWithSegment("users.profile.edit", "users");     // true
+endsWithSegment("users.profile.edit", "edit");        // true
+includesSegment("users.profile.edit", "profile");     // true
+areRoutesRelated("users", "users.profile");           // true
 ```
 
-## API Reference
-
-### `startsWithSegment(route, segment?)`
-
-Tests if a route name starts with the given segment.
-
-**Parameters:**
-
-- `route: State | string` - Route state object or route name string
-- `segment?: string | null` - Segment to test (optional for curried form)
+---
 
-**Returns:**
+## API
 
-- `boolean` - True if route starts with segment
-- `(segment: string) => boolean` - Tester function if segment omitted
-- `false` - If segment is null or empty string
+### `startsWithSegment(route: State | string, segment?: string | null): boolean | ((segment: string) => boolean)`
 
-**Examples:**
+Tests if route name starts with segment.\
+`route: State | string` — route state object or route name string\
+`segment?: string | null` — segment to test (optional for curried form)\
+Returns: `boolean` (true if starts with segment, false if segment is null/empty) or `(segment: string) => boolean` (tester function if segment omitted)
 
 ```typescript
 // Direct usage
-startsWithSegment("users.list", "users"); // true
-startsWithSegment("users.list", "admin"); // false
-
-// Multi-segment matching
-startsWithSegment("users.profile.edit", "users.profile"); // true
+startsWithSegment("users.list", "users");           // true
+startsWithSegment("users.profile", "users.profile"); // true (multi-segment)
 
 // With State object
-const state = { name: "users.list", params: {}, path: "/users" };
-startsWithSegment(state, "users"); // true
+startsWithSegment({ name: "users.list", params: {}, path: "/" }, "users"); // true
 
 // Curried form
 const tester = startsWithSegment("users.profile.edit");
-tester("users"); // true
-tester("admin"); // false
-
-// Edge cases
-startsWithSegment("users", ""); // false
-startsWithSegment("users", null); // false
-```
-
-**Use Cases:**
-
-```typescript
-// Active navigation menu
-const isAdminSection = startsWithSegment(currentRoute, 'admin');
-
-// Conditional rendering
-{startsWithSegment(route, 'users') && <UsersToolbar />}
-
-// Access guards
-if (!startsWithSegment(route, 'admin')) {
-  throw new UnauthorizedError();
-}
+tester("users");  // true
+tester("admin");  // false
 ```
 
----
+### `endsWithSegment(route: State | string, segment?: string | null): boolean | ((segment: string) => boolean)`
 
-### `endsWithSegment(route, segment?)`
-
-Tests if a route name ends with the given segment.
-
-**Parameters:**
-
-- `route: State | string` - Route state object or route name string
-- `segment?: string | null` - Segment to test (optional for curried form)
-
-**Returns:**
-
-- `boolean` - True if route ends with segment
-- `(segment: string) => boolean` - Tester function if segment omitted
-- `false` - If segment is null or empty string
-
-**Examples:**
+Tests if route name ends with segment.\
+`route: State | string` — route state object or route name string\
+`segment?: string | null` — segment to test (optional for curried form)\
+Returns: `boolean` (true if ends with segment, false if segment is null/empty) or `(segment: string) => boolean` (tester function if segment omitted)
 
 ```typescript
-// Direct usage
-endsWithSegment("users.profile.edit", "edit"); // true
-endsWithSegment("users.profile.edit", "view"); // false
-
-// Multi-segment matching
-endsWithSegment("a.b.c.d", "c.d"); // true
+endsWithSegment("users.profile.edit", "edit");  // true
+endsWithSegment("a.b.c.d", "c.d");               // true (multi-segment)
 
 // Curried form
 const tester = endsWithSegment("users.list");
-tester("list"); // true
-tester("edit"); // false
-```
-
-**Use Cases:**
-
-```typescript
-// Detect edit pages
-const isEditPage = endsWithSegment(route, 'edit');
-
-// Page type detection
-const pageType = ['view', 'edit', 'create'].find(
-  type => endsWithSegment(route, type)
-);
-
-// Conditional toolbar
-{endsWithSegment(route, 'edit') && <EditToolbar />}
+tester("list");  // true
 ```
 
----
-
-### `includesSegment(route, segment?)`
-
-Tests if a route name includes the given segment anywhere in its path.
-
-**Parameters:**
-
-- `route: State | string` - Route state object or route name string
-- `segment?: string | null` - Segment to test (optional for curried form)
-
-**Returns:**
+### `includesSegment(route: State | string, segment?: string | null): boolean | ((segment: string) => boolean)`
 
-- `boolean` - True if route includes segment
-- `(segment: string) => boolean` - Tester function if segment omitted
-- `false` - If segment is null or empty string
-
-**Examples:**
+Tests if route name includes segment anywhere.\
+`route: State | string` — route state object or route name string\
+`segment?: string | null` — segment to test (optional for curried form)\
+Returns: `boolean` (true if includes segment, false if segment is null/empty) or `(segment: string) => boolean` (tester function if segment omitted)
 
 ```typescript
-// Direct usage
-includesSegment("admin.users.profile", "users"); // true
-includesSegment("admin.users.profile", "profile"); // true
-includesSegment("admin.users.profile", "settings"); // false
-
-// Multi-segment matching (contiguous)
-includesSegment("a.b.c.d", "b.c"); // true
-includesSegment("a.b.c.d", "a.c"); // false (not contiguous)
+includesSegment("admin.users.profile", "users");    // true
+includesSegment("a.b.c.d", "b.c");                   // true (contiguous)
+includesSegment("a.b.c.d", "a.c");                   // false (not contiguous)
 
 // Curried form
 const tester = includesSegment("admin.users.profile");
-tester("users"); // true
-tester("settings"); // false
+tester("users");     // true
+tester("settings");  // false
 ```
 
-**Use Cases:**
-
-```typescript
-// Check if anywhere in users section
-const inUsersSection = includesSegment(route, "users");
-
-// Feature detection
-const hasProfileFeature = includesSegment(route, "profile");
-
-// Analytics tracking
-if (includesSegment(route, "checkout")) {
-  analytics.track("checkout_flow");
-}
-```
-
----
+### `areRoutesRelated(route1: string, route2: string): boolean`
 
-### `areRoutesRelated(route1, route2)`
-
-Tests if two routes are related in the hierarchy (same, parent-child, or child-parent).
-
-**Parameters:**
-
-- `route1: string` - First route name
-- `route2: string` - Second route name
-
-**Returns:**
-
-- `boolean` - True if routes are related
-
-**Examples:**
+Tests if routes are in same hierarchy (parent-child, child-parent, or same).\
+`route1: string` — first route name\
+`route2: string` — second route name\
+Returns: `boolean` — true if routes are related (same, parent-child, or child-parent)
 
 ```typescript
-// Same route
-areRoutesRelated("users", "users"); // true
-
 // Parent-child relationship
-areRoutesRelated("users", "users.list"); // true
+areRoutesRelated("users", "users.list");       // true
 areRoutesRelated("users", "users.profile.edit"); // true
 
 // Child-parent relationship
-areRoutesRelated("users.list", "users"); // true
+areRoutesRelated("users.list", "users");       // true
 areRoutesRelated("users.profile.edit", "users"); // true
 
-// Different branches (not related)
-areRoutesRelated("users", "admin"); // false
-areRoutesRelated("users.list", "admin.dashboard"); // false
+// Same route
+areRoutesRelated("users", "users");            // true
 
 // Siblings (not related)
-areRoutesRelated("users.list", "users.view"); // false
-areRoutesRelated("users.profile", "users.settings"); // false
-```
-
-**Use Cases:**
-
-```typescript
-// Optimized re-rendering (only update when route is related)
-const shouldUpdate = areRoutesRelated(newRoute, watchedRoute);
-
-// Navigation menu highlighting
-const isInSection = areRoutesRelated(currentRoute, "admin");
+areRoutesRelated("users.list", "users.view");  // false
 
-// Breadcrumb visibility
-const showBreadcrumb = areRoutesRelated(currentRoute, basePath);
+// Different branches (not related)
+areRoutesRelated("users", "admin");            // false
 ```
 
 ---
 
-## Real-World Examples
-
-### Active Navigation Menu
+## Usage Examples
 
-```typescript
-import { startsWithSegment } from '@real-router/helpers';
+### Navigation Menu
 
+```tsx
 function NavigationMenu({ currentRoute }) {
-  const menuItems = [
-    { name: 'Dashboard', route: 'dashboard' },
-    { name: 'Users', route: 'users' },
-    { name: 'Settings', route: 'settings' },
+  const items = [
+    { name: "Dashboard", route: "dashboard" },
+    { name: "Users", route: "users" },
   ];
 
   return (
     <nav>
-      {menuItems.map(item => (
+      {items.map((item) => (
         <MenuItem
           key={item.route}
           active={startsWithSegment(currentRoute, item.route)}
@@ -291,44 +146,11 @@ function NavigationMenu({ currentRoute }) {
 }
 ```
 
-### Breadcrumbs
-
-```typescript
-import { startsWithSegment } from '@real-router/helpers';
-
-function Breadcrumbs({ currentRoute }) {
-  const segments = currentRoute.split('.');
-  const breadcrumbs = segments.reduce((acc, segment, index) => {
-    const path = segments.slice(0, index + 1).join('.');
-    return [...acc, {
-      path,
-      label: segment,
-      isActive: path === currentRoute,
-    }];
-  }, []);
-
-  return (
-    <nav>
-      {breadcrumbs.map(crumb => (
-        <Breadcrumb
-          key={crumb.path}
-          active={crumb.isActive}
-        >
-          {crumb.label}
-        </Breadcrumb>
-      ))}
-    </nav>
-  );
-}
-```
-
-### Route Guards
+### Route Guard
 
 ```typescript
-import { startsWithSegment } from "@real-router/helpers";
-
 const adminGuard = (router) => (toState, fromState, done) => {
-  if (startsWithSegment(toState, "admin") && !userHasAdminRole()) {
+  if (startsWithSegment(toState, "admin") && !isAdmin()) {
     done({ redirect: { name: "unauthorized" } });
   } else {
     done();
@@ -340,236 +162,62 @@ router.useMiddleware(adminGuard);
 
 ### Conditional Rendering
 
-```typescript
-import { startsWithSegment, includesSegment, endsWithSegment } from '@real-router/helpers';
-
-function PageLayout({ route, children }) {
+```tsx
+function Layout({ route, children }) {
   return (
     <div>
-      {/* Show admin sidebar only in admin section */}
-      {startsWithSegment(route, 'admin') && <AdminSidebar />}
-
-      {/* Show edit toolbar on edit pages */}
-      {endsWithSegment(route, 'edit') && <EditToolbar />}
-
-      {/* Show user profile widget in user-related pages */}
-      {includesSegment(route, 'users') && <UserProfileWidget />}
-
+      {startsWithSegment(route, "admin") && <AdminSidebar />}
+      {endsWithSegment(route, "edit") && <EditToolbar />}
       <main>{children}</main>
     </div>
   );
 }
 ```
 
-### Analytics Tracking
-
-```typescript
-import { startsWithSegment, includesSegment } from "@real-router/helpers";
-
-router.subscribe((state) => {
-  const routeName = state.route.name;
-
-  // Track section
-  if (startsWithSegment(routeName, "admin")) {
-    analytics.track("admin_section_view");
-  }
-
-  // Track feature usage
-  if (includesSegment(routeName, "checkout")) {
-    analytics.track("checkout_flow_step", {
-      step: routeName.split(".").pop(),
-    });
-  }
-});
-```
-
 ---
 
-## Validation & Security
-
-### Automatic Validation
-
-All segment inputs are automatically validated for security and correctness:
-
-**Character Whitelist:**
-
-- Allowed: `a-z`, `A-Z`, `0-9`, `.` (dot), `-` (dash), `_` (underscore)
-- Disallowed: Special characters, spaces, slashes, etc.
-
-**Length Limits:**
-
-- Maximum segment length: 10,000 characters
-- Empty segments are rejected
-
-**Examples:**
-
-```typescript
-// Valid segments
-startsWithSegment("route", "users"); // OK
-startsWithSegment("route", "admin-panel"); // OK
-startsWithSegment("route", "users_v2"); // OK
-startsWithSegment("route", "app.settings"); // OK
-
-// Invalid segments (throw TypeError)
-startsWithSegment("route", "invalid!char"); // Throws
-startsWithSegment("route", "has space"); // Throws
-startsWithSegment("route", "path/segment"); // Throws
-startsWithSegment("route", "ns:segment"); // Throws
-
-// Too long (throw RangeError)
-startsWithSegment("route", "a".repeat(10001)); // Throws
-
-// Empty (returns false)
-startsWithSegment("route", ""); // false
-startsWithSegment("route", null); // false
-```
-
-### Error Handling
-
-```typescript
-try {
-  startsWithSegment("route", "invalid!segment");
-} catch (error) {
-  if (error instanceof TypeError) {
-    console.error("Invalid segment:", error.message);
-    // "Segment contains invalid characters. Allowed: a-z, A-Z, 0-9, dot (.), dash (-), underscore (_)"
-  }
-}
-
-try {
-  startsWithSegment("route", "a".repeat(10001));
-} catch (error) {
-  if (error instanceof RangeError) {
-    console.error("Segment too long:", error.message);
-    // "Segment exceeds maximum length of 10000 characters"
-  }
-}
-```
-
----
-
-## TypeScript Support
-
-Full TypeScript support with type definitions included.
-
-```typescript
-import type { State } from "@real-router/core";
-import { startsWithSegment } from "@real-router/helpers";
-
-// Type inference works correctly
-const result: boolean = startsWithSegment("route", "segment");
+## Validation
 
-// Curried form also typed
-const tester: (segment: string) => boolean = startsWithSegment("route");
+Segments are validated for security:
 
-// Works with State objects
-const state: State = { name: "route", params: {}, path: "/route" };
-const matches: boolean = startsWithSegment(state, "segment");
-```
-
-### Type Definitions
+- **Allowed:** `a-z`, `A-Z`, `0-9`, `.`, `-`, `_`
+- **Max length:** 10,000 characters
+- **Empty/null:** Returns `false`
+- **Invalid chars:** Throws `TypeError`
 
 ```typescript
-export interface SegmentTestFunction {
-  (route: State | string): (segment: string) => boolean;
-  (route: State | string, segment: string): boolean;
-  (route: State | string, segment: null): false;
-  (
-    route: State | string,
-    segment?: string | null,
-  ): boolean | ((segment: string) => boolean);
-}
+startsWithSegment("route", "valid-segment_v2");  // OK
+startsWithSegment("route", "invalid!char");       // Throws TypeError
+startsWithSegment("route", "");                   // false
 ```
 
 ---
 
-## Documentation
-
-Full documentation available on the [Real-Router Wiki](https://github.com/greydragon888/real-router/wiki):
-
-- [startsWithSegment](https://github.com/greydragon888/real-router/wiki/startsWithSegment)
-- [endsWithSegment](https://github.com/greydragon888/real-router/wiki/endsWithSegment)
-- [includesSegment](https://github.com/greydragon888/real-router/wiki/includesSegment)
-- [areRoutesRelated](https://github.com/greydragon888/real-router/wiki/areRoutesRelated)
-
----
-
-## Related Packages
-
-- [@real-router/core](https://www.npmjs.com/package/@real-router/core) - Core router
-- [@real-router/react](https://www.npmjs.com/package/@real-router/react) - React integration
-- [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin) - Browser integration
-
----
-
 ## Migration from router5-helpers
 
-### Import Changes
-
-```diff
-- import { startsWithSegment, endsWithSegment, includesSegment } from 'router5-helpers';
-+ import { startsWithSegment, endsWithSegment, includesSegment } from '@real-router/helpers';
-```
-
-### Removed: `redirect`
-
-The `redirect` helper has been removed. Use router guards instead:
-
-```diff
-- import { redirect } from 'router5-helpers';
--
-- router.canActivate('protected', () => redirect('login'));
-+ router.canActivate('protected', (toState, fromState, done) => {
-+   done({ redirect: { name: 'login' } });
-+ });
-```
-
-### New: `areRoutesRelated`
-
-New helper function for checking route hierarchy:
-
-```typescript
-import { areRoutesRelated } from "@real-router/helpers";
-
-areRoutesRelated("users", "users.profile"); // true (parent-child)
-areRoutesRelated("users.profile", "users"); // true (child-parent)
-areRoutesRelated("users", "admin"); // false (different branches)
-```
-
-### New: Input Validation
-
-@real-router/helpers validates segment inputs for security:
-
-```typescript
-// Valid segments
-startsWithSegment("route", "users");
-startsWithSegment("route", "admin-panel");
-
-// Throws TypeError (invalid characters)
-startsWithSegment("route", "invalid!char");
-startsWithSegment("route", "has space");
-```
-
-### Full Migration Example
-
 ```diff
 - import { startsWithSegment, redirect } from 'router5-helpers';
 + import { startsWithSegment } from '@real-router/helpers';
 
-  // Segment testing - unchanged
-  if (startsWithSegment(route, 'admin')) {
-    // ...
-  }
+// Segment testing — unchanged
+startsWithSegment(route, 'admin');
 
-  // Redirects - use guards instead
-- router.canActivate('old-page', () => redirect('new-page'));
-+ router.canActivate('old-page', (toState, fromState, done) => {
-+   done({ redirect: { name: 'new-page' } });
+// redirect removed — use guards:
+- router.canActivate('old', () => redirect('new'));
++ router.canActivate('old', (to, from, done) => {
++   done({ redirect: { name: 'new' } });
 + });
 ```
 
+**New:** `areRoutesRelated()` for hierarchy checks.
+
 ---
 
+## Related Packages
+
+- [@real-router/core](https://www.npmjs.com/package/@real-router/core) — Core router
+- [@real-router/react](https://www.npmjs.com/package/@real-router/react) — React integration
+
 ## License
 
 MIT © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.d.ts

@@ -1,16 +1,238 @@
-import { State } from '@real-router/core';
+// Generated by dts-bundle-generator v9.5.1
 
+export interface State<P extends Params = Params, MP extends Params = Params> {
+	name: string;
+	params: P;
+	path: string;
+	meta?: StateMeta<MP> | undefined;
+}
+export interface StateMeta<P extends Params = Params> {
+	id: number;
+	params: P;
+	options: NavigationOptions;
+	redirected: boolean;
+	source?: string | undefined;
+}
+/**
+ * Configuration options that control navigation transition behavior.
+ *
+ * @description
+ * NavigationOptions provides fine-grained control over how the router performs navigation
+ * transitions. These options affect history management, transition lifecycle execution,
+ * guard enforcement, and state comparison logic.
+ *
+ * All options are optional and have sensible defaults. Options can be combined to achieve
+ * complex navigation behaviors. The options object is stored in state.meta.options and is
+ * available to middleware, guards, and event listeners.
+ *
+ * @see {@link Router.navigate} for navigation method that accepts these options
+ * @see {@link State.meta} for where options are stored after navigation
+ */
+export interface NavigationOptions {
+	[key: string]: string | number | boolean | Record<string, unknown> | undefined;
+	/**
+	 * Replace the current history entry instead of pushing a new one.
+	 *
+	 * @description
+	 * When `true`, the navigation will replace the current entry in browser history instead
+	 * of adding a new entry. This is typically used by history plugins (browser plugin) to
+	 * control how navigation affects the browser's back/forward buttons.
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Redirect after login - prevent back button to login page
+	 * router.navigate('dashboard', {}, { replace: true });
+	 *
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState}
+	 */
+	replace?: boolean | undefined;
+	/**
+	 * Force reload of the current route even if states are equal.
+	 *
+	 * @description
+	 * When `true`, bypasses the "same state" check that normally prevents navigation when
+	 * the target state equals the current state. This forces a full transition lifecycle
+	 * execution, allowing route components to reload with the same parameters.
+	 *
+	 * Without `reload`:
+	 * - Navigation to current route throws SAME_STATES error
+	 * - No lifecycle hooks or middleware execute
+	 * - No events are fired
+	 *
+	 * With `reload`:
+	 * - Full transition executes (deactivate → activate → middleware)
+	 * - All lifecycle hooks run again
+	 * - TRANSITION_SUCCESS event fires with same state
+	 * - State object is recreated (new reference)
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Refresh current page data
+	 * router.navigate(currentRoute.name, currentRoute.params, { reload: true });
+	 *
+	 * @example
+	 * // Force re-fetch on same route with different query params
+	 * // Note: query params are in path, not checked for equality
+	 * router.navigate('search', { term: 'react' }, { reload: true });
+	 *
+	 * @see {@link force} for alternative that forces transition
+	 * @see {@link Router.areStatesEqual} for state comparison logic
+	 */
+	reload?: boolean | undefined;
+	/**
+	 * Preview navigation without any side effects (dry-run mode).
+	 *
+	 * @description
+	 * When `true`, returns the would-be target state via callback WITHOUT:
+	 * - Executing canDeactivate/canActivate guards
+	 * - Executing middleware
+	 * - Updating router state (`router.getState()` remains unchanged)
+	 * - Emitting any transition events (TRANSITION_START, TRANSITION_SUCCESS, etc.)
+	 *
+	 * The callback receives `(undefined, toState)` where `toState` is the computed
+	 * target state that WOULD result from this navigation.
+	 *
+	 * @default false
+	 *
+	 * @remarks
+	 * This option is useful for:
+	 * - Validating that a route exists and params are correct
+	 * - SSR: previewing state for pre-rendering without side effects
+	 * - Dry-run before actual navigation
+	 *
+	 * @deprecated Consider using `router.buildState()` + `router.makeState()` instead
+	 * for clearer intent. This option may be removed in a future major version.
+	 *
+	 * @example
+	 * // Preview navigation - router.getState() is NOT changed
+	 * router.navigate('users.view', { id: 123 }, { skipTransition: true }, (err, previewState) => {
+	 *   console.log(previewState);        // { name: 'users.view', params: { id: 123 }, path: '/users/view/123', ... }
+	 *   console.log(router.getState());   // Still the previous state!
+	 * });
+	 *
+	 * @example
+	 * // Recommended alternative (clearer intent)
+	 * const route = router.buildState('users.view', { id: 123 });
+	 * if (route) {
+	 *   const path = router.buildPath(route.name, route.params);
+	 *   const previewState = router.makeState(route.name, route.params, path, { params: route.meta });
+	 * }
+	 *
+	 * @see {@link forceDeactivate} for skipping only canDeactivate guards
+	 * @see {@link force} for forcing navigation while preserving lifecycle
+	 */
+	skipTransition?: boolean | undefined;
+	/**
+	 * Force navigation even if target state equals current state.
+	 *
+	 * @description
+	 * When `true`, bypasses the "same state" equality check but still executes the full
+	 * transition lifecycle (unlike `skipTransition`). Similar to `reload` but can be used
+	 * for any forced navigation scenario.
+	 *
+	 * Difference from `reload`:
+	 * - `reload`: semantic meaning is "refresh current route"
+	 * - `force`: general-purpose bypass of equality check
+	 * - Both have identical implementation effect
+	 *
+	 * The equality check compares:
+	 * - state.name (route name)
+	 * - state.params (route parameters, shallow comparison)
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Force transition for tracking even if params didn't change
+	 * router.navigate('analytics', { event: 'pageview' }, { force: true });
+	 *
+	 * @see {@link reload} for semantic equivalent (preferred for refresh scenarios)
+	 * @see {@link skipTransition} for bypassing entire lifecycle
+	 */
+	force?: boolean | undefined;
+	/**
+	 * Skip canDeactivate guards during transition.
+	 *
+	 * @description
+	 * When `true`, bypasses only the canDeactivate lifecycle hooks for segments being
+	 * deactivated. canActivate guards and middleware still execute normally. This allows
+	 * forcing navigation away from routes with confirmation dialogs or unsaved changes.
+	 *
+	 * Skipped vs executed:
+	 * ```
+	 * // Normal transition
+	 * deactivate(fromSegments) → activate(toSegments) → middleware → success
+	 *
+	 * // With forceDeactivate: true
+	 * [skip deactivate] → activate(toSegments) → middleware → success
+	 * ```
+	 *
+	 * ⚠️ Data loss risk: Bypassing canDeactivate means unsaved changes will be lost
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Force logout even with unsaved changes
+	 * function forceLogout() {
+	 *   router.navigate('login', {}, {
+	 *     forceDeactivate: true,
+	 *     replace: true
+	 *   });
+	 * }
+	 *
+	 * @see {@link skipTransition} for bypassing all guards and middleware
+	 * @see {@link Router.clearCanDeactivate} for programmatically clearing guards
+	 */
+	forceDeactivate?: boolean | undefined;
+	/**
+	 * Internal flag indicating navigation is result of a redirect.
+	 *
+	 * @internal
+	 *
+	 * @description
+	 * Automatically set by the router when a navigation is triggered by a redirect from
+	 * middleware or lifecycle hooks. This flag is used internally to track redirect chains
+	 * and is stored in state.meta.redirected.
+	 *
+	 * @default false (auto-set by router during redirects)
+	 *
+	 * @example
+	 * // Middleware triggers automatic redirect
+	 * router.useMiddleware((toState, fromState, opts) => {
+	 *   if (!isAuthenticated && toState.name !== 'login') {
+	 *     // Router will automatically set redirected: true
+	 *     return { name: 'login', params: { next: toState.path } };
+	 *   }
+	 * });
+	 *
+	 * @example
+	 * // Accessing redirect flag in lifecycle
+	 * router.canActivate('dashboard', (toState, fromState) => {
+	 *   if (toState.meta?.redirected) {
+	 *     console.log('This navigation is from a redirect');
+	 *   }
+	 *   return true;
+	 * });
+	 *
+	 * @see {@link Router.navigate} for redirect handling implementation
+	 * @see {@link State.meta.redirected} for redirect flag in state
+	 */
+	redirected?: boolean | undefined;
+}
+export interface Params {
+	[key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
+}
 /**
  * Type definition for segment test functions.
  * These functions can be called directly with a segment, or curried for later use.
  */
-interface SegmentTestFunction {
-    (route: State | string): (segment: string) => boolean;
-    (route: State | string, segment: string): boolean;
-    (route: State | string, segment: null): false;
-    (route: State | string, segment?: string | null): boolean | ((segment: string) => boolean);
+export interface SegmentTestFunction {
+	(route: State | string): (segment: string) => boolean;
+	(route: State | string, segment: string): boolean;
+	(route: State | string, segment: null): false;
+	(route: State | string, segment?: string | null): boolean | ((segment: string) => boolean);
 }
-
 /**
  * Tests if a route name starts with the given segment.
  *
@@ -70,7 +292,7 @@ interface SegmentTestFunction {
  * @see endsWithSegment for suffix matching
  * @see includesSegment for anywhere matching
  */
-declare const startsWithSegment: SegmentTestFunction;
+export declare const startsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name ends with the given segment.
  *
@@ -111,7 +333,7 @@ declare const startsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see includesSegment for anywhere matching
  */
-declare const endsWithSegment: SegmentTestFunction;
+export declare const endsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name includes the given segment anywhere in its path.
  *
@@ -156,8 +378,7 @@ declare const endsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see endsWithSegment for suffix matching
  */
-declare const includesSegment: SegmentTestFunction;
-
+export declare const includesSegment: SegmentTestFunction;
 /**
  * Checks if two routes are related in the hierarchy.
  *
@@ -177,6 +398,6 @@ declare const includesSegment: SegmentTestFunction;
  * areRoutesRelated("users", "admin");          // false (different branches)
  * areRoutesRelated("users.list", "users.view"); // false (siblings)
  */
-declare function areRoutesRelated(route1: string, route2: string): boolean;
+export declare function areRoutesRelated(route1: string, route2: string): boolean;
 
-export { type SegmentTestFunction, areRoutesRelated, endsWithSegment, includesSegment, startsWithSegment };
+export {};

package/dist/esm/index.d.mts

@@ -1,16 +1,238 @@
-import { State } from '@real-router/core';
+// Generated by dts-bundle-generator v9.5.1
 
+export interface State<P extends Params = Params, MP extends Params = Params> {
+	name: string;
+	params: P;
+	path: string;
+	meta?: StateMeta<MP> | undefined;
+}
+export interface StateMeta<P extends Params = Params> {
+	id: number;
+	params: P;
+	options: NavigationOptions;
+	redirected: boolean;
+	source?: string | undefined;
+}
+/**
+ * Configuration options that control navigation transition behavior.
+ *
+ * @description
+ * NavigationOptions provides fine-grained control over how the router performs navigation
+ * transitions. These options affect history management, transition lifecycle execution,
+ * guard enforcement, and state comparison logic.
+ *
+ * All options are optional and have sensible defaults. Options can be combined to achieve
+ * complex navigation behaviors. The options object is stored in state.meta.options and is
+ * available to middleware, guards, and event listeners.
+ *
+ * @see {@link Router.navigate} for navigation method that accepts these options
+ * @see {@link State.meta} for where options are stored after navigation
+ */
+export interface NavigationOptions {
+	[key: string]: string | number | boolean | Record<string, unknown> | undefined;
+	/**
+	 * Replace the current history entry instead of pushing a new one.
+	 *
+	 * @description
+	 * When `true`, the navigation will replace the current entry in browser history instead
+	 * of adding a new entry. This is typically used by history plugins (browser plugin) to
+	 * control how navigation affects the browser's back/forward buttons.
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Redirect after login - prevent back button to login page
+	 * router.navigate('dashboard', {}, { replace: true });
+	 *
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState}
+	 */
+	replace?: boolean | undefined;
+	/**
+	 * Force reload of the current route even if states are equal.
+	 *
+	 * @description
+	 * When `true`, bypasses the "same state" check that normally prevents navigation when
+	 * the target state equals the current state. This forces a full transition lifecycle
+	 * execution, allowing route components to reload with the same parameters.
+	 *
+	 * Without `reload`:
+	 * - Navigation to current route throws SAME_STATES error
+	 * - No lifecycle hooks or middleware execute
+	 * - No events are fired
+	 *
+	 * With `reload`:
+	 * - Full transition executes (deactivate → activate → middleware)
+	 * - All lifecycle hooks run again
+	 * - TRANSITION_SUCCESS event fires with same state
+	 * - State object is recreated (new reference)
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Refresh current page data
+	 * router.navigate(currentRoute.name, currentRoute.params, { reload: true });
+	 *
+	 * @example
+	 * // Force re-fetch on same route with different query params
+	 * // Note: query params are in path, not checked for equality
+	 * router.navigate('search', { term: 'react' }, { reload: true });
+	 *
+	 * @see {@link force} for alternative that forces transition
+	 * @see {@link Router.areStatesEqual} for state comparison logic
+	 */
+	reload?: boolean | undefined;
+	/**
+	 * Preview navigation without any side effects (dry-run mode).
+	 *
+	 * @description
+	 * When `true`, returns the would-be target state via callback WITHOUT:
+	 * - Executing canDeactivate/canActivate guards
+	 * - Executing middleware
+	 * - Updating router state (`router.getState()` remains unchanged)
+	 * - Emitting any transition events (TRANSITION_START, TRANSITION_SUCCESS, etc.)
+	 *
+	 * The callback receives `(undefined, toState)` where `toState` is the computed
+	 * target state that WOULD result from this navigation.
+	 *
+	 * @default false
+	 *
+	 * @remarks
+	 * This option is useful for:
+	 * - Validating that a route exists and params are correct
+	 * - SSR: previewing state for pre-rendering without side effects
+	 * - Dry-run before actual navigation
+	 *
+	 * @deprecated Consider using `router.buildState()` + `router.makeState()` instead
+	 * for clearer intent. This option may be removed in a future major version.
+	 *
+	 * @example
+	 * // Preview navigation - router.getState() is NOT changed
+	 * router.navigate('users.view', { id: 123 }, { skipTransition: true }, (err, previewState) => {
+	 *   console.log(previewState);        // { name: 'users.view', params: { id: 123 }, path: '/users/view/123', ... }
+	 *   console.log(router.getState());   // Still the previous state!
+	 * });
+	 *
+	 * @example
+	 * // Recommended alternative (clearer intent)
+	 * const route = router.buildState('users.view', { id: 123 });
+	 * if (route) {
+	 *   const path = router.buildPath(route.name, route.params);
+	 *   const previewState = router.makeState(route.name, route.params, path, { params: route.meta });
+	 * }
+	 *
+	 * @see {@link forceDeactivate} for skipping only canDeactivate guards
+	 * @see {@link force} for forcing navigation while preserving lifecycle
+	 */
+	skipTransition?: boolean | undefined;
+	/**
+	 * Force navigation even if target state equals current state.
+	 *
+	 * @description
+	 * When `true`, bypasses the "same state" equality check but still executes the full
+	 * transition lifecycle (unlike `skipTransition`). Similar to `reload` but can be used
+	 * for any forced navigation scenario.
+	 *
+	 * Difference from `reload`:
+	 * - `reload`: semantic meaning is "refresh current route"
+	 * - `force`: general-purpose bypass of equality check
+	 * - Both have identical implementation effect
+	 *
+	 * The equality check compares:
+	 * - state.name (route name)
+	 * - state.params (route parameters, shallow comparison)
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Force transition for tracking even if params didn't change
+	 * router.navigate('analytics', { event: 'pageview' }, { force: true });
+	 *
+	 * @see {@link reload} for semantic equivalent (preferred for refresh scenarios)
+	 * @see {@link skipTransition} for bypassing entire lifecycle
+	 */
+	force?: boolean | undefined;
+	/**
+	 * Skip canDeactivate guards during transition.
+	 *
+	 * @description
+	 * When `true`, bypasses only the canDeactivate lifecycle hooks for segments being
+	 * deactivated. canActivate guards and middleware still execute normally. This allows
+	 * forcing navigation away from routes with confirmation dialogs or unsaved changes.
+	 *
+	 * Skipped vs executed:
+	 * ```
+	 * // Normal transition
+	 * deactivate(fromSegments) → activate(toSegments) → middleware → success
+	 *
+	 * // With forceDeactivate: true
+	 * [skip deactivate] → activate(toSegments) → middleware → success
+	 * ```
+	 *
+	 * ⚠️ Data loss risk: Bypassing canDeactivate means unsaved changes will be lost
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * // Force logout even with unsaved changes
+	 * function forceLogout() {
+	 *   router.navigate('login', {}, {
+	 *     forceDeactivate: true,
+	 *     replace: true
+	 *   });
+	 * }
+	 *
+	 * @see {@link skipTransition} for bypassing all guards and middleware
+	 * @see {@link Router.clearCanDeactivate} for programmatically clearing guards
+	 */
+	forceDeactivate?: boolean | undefined;
+	/**
+	 * Internal flag indicating navigation is result of a redirect.
+	 *
+	 * @internal
+	 *
+	 * @description
+	 * Automatically set by the router when a navigation is triggered by a redirect from
+	 * middleware or lifecycle hooks. This flag is used internally to track redirect chains
+	 * and is stored in state.meta.redirected.
+	 *
+	 * @default false (auto-set by router during redirects)
+	 *
+	 * @example
+	 * // Middleware triggers automatic redirect
+	 * router.useMiddleware((toState, fromState, opts) => {
+	 *   if (!isAuthenticated && toState.name !== 'login') {
+	 *     // Router will automatically set redirected: true
+	 *     return { name: 'login', params: { next: toState.path } };
+	 *   }
+	 * });
+	 *
+	 * @example
+	 * // Accessing redirect flag in lifecycle
+	 * router.canActivate('dashboard', (toState, fromState) => {
+	 *   if (toState.meta?.redirected) {
+	 *     console.log('This navigation is from a redirect');
+	 *   }
+	 *   return true;
+	 * });
+	 *
+	 * @see {@link Router.navigate} for redirect handling implementation
+	 * @see {@link State.meta.redirected} for redirect flag in state
+	 */
+	redirected?: boolean | undefined;
+}
+export interface Params {
+	[key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
+}
 /**
  * Type definition for segment test functions.
  * These functions can be called directly with a segment, or curried for later use.
  */
-interface SegmentTestFunction {
-    (route: State | string): (segment: string) => boolean;
-    (route: State | string, segment: string): boolean;
-    (route: State | string, segment: null): false;
-    (route: State | string, segment?: string | null): boolean | ((segment: string) => boolean);
+export interface SegmentTestFunction {
+	(route: State | string): (segment: string) => boolean;
+	(route: State | string, segment: string): boolean;
+	(route: State | string, segment: null): false;
+	(route: State | string, segment?: string | null): boolean | ((segment: string) => boolean);
 }
-
 /**
  * Tests if a route name starts with the given segment.
  *
@@ -70,7 +292,7 @@ interface SegmentTestFunction {
  * @see endsWithSegment for suffix matching
  * @see includesSegment for anywhere matching
  */
-declare const startsWithSegment: SegmentTestFunction;
+export declare const startsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name ends with the given segment.
  *
@@ -111,7 +333,7 @@ declare const startsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see includesSegment for anywhere matching
  */
-declare const endsWithSegment: SegmentTestFunction;
+export declare const endsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name includes the given segment anywhere in its path.
  *
@@ -156,8 +378,7 @@ declare const endsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see endsWithSegment for suffix matching
  */
-declare const includesSegment: SegmentTestFunction;
-
+export declare const includesSegment: SegmentTestFunction;
 /**
  * Checks if two routes are related in the hierarchy.
  *
@@ -177,6 +398,6 @@ declare const includesSegment: SegmentTestFunction;
  * areRoutesRelated("users", "admin");          // false (different branches)
  * areRoutesRelated("users.list", "users.view"); // false (siblings)
  */
-declare function areRoutesRelated(route1: string, route2: string): boolean;
+export declare function areRoutesRelated(route1: string, route2: string): boolean;
 
-export { type SegmentTestFunction, areRoutesRelated, endsWithSegment, includesSegment, startsWithSegment };
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/helpers",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "commonjs",
   "description": "Helper utilities for comparing and checking routes",
   "main": "./dist/cjs/index.js",