@real-router/helpers 0.1.2 → 0.1.4

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.2",
+  "version": "0.1.4",
   "type": "commonjs",
   "description": "Helper utilities for comparing and checking routes",
   "main": "./dist/cjs/index.js",
@@ -37,6 +37,10 @@
     "url": "https://github.com/greydragon888/real-router/issues"
   },
   "homepage": "https://github.com/greydragon888/real-router",
+  "sideEffects": false,
+  "dependencies": {
+    "@real-router/core": "^0.2.3"
+  },
   "scripts": {
     "test": "vitest",
     "build": "tsup",
@@ -44,9 +48,5 @@
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
     "lint:package": "publint",
     "lint:types": "attw --pack ."
-  },
-  "sideEffects": false,
-  "dependencies": {
-    "@real-router/core": "workspace:^"
   }
-}
+}