@real-router/helpers 0.1.4 → 0.1.6

package/dist/cjs/index.d.ts

@@ -1,238 +1,16 @@
-// Generated by dts-bundle-generator v9.5.1
+import { State } from '@real-router/core';
 
-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.
  */
-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);
+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.
  *
@@ -292,7 +70,7 @@ export interface SegmentTestFunction {
  * @see endsWithSegment for suffix matching
  * @see includesSegment for anywhere matching
  */
-export declare const startsWithSegment: SegmentTestFunction;
+declare const startsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name ends with the given segment.
  *
@@ -333,7 +111,7 @@ export declare const startsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see includesSegment for anywhere matching
  */
-export declare const endsWithSegment: SegmentTestFunction;
+declare const endsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name includes the given segment anywhere in its path.
  *
@@ -378,7 +156,8 @@ export declare const endsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see endsWithSegment for suffix matching
  */
-export declare const includesSegment: SegmentTestFunction;
+declare const includesSegment: SegmentTestFunction;
+
 /**
  * Checks if two routes are related in the hierarchy.
  *
@@ -398,6 +177,6 @@ export declare const includesSegment: SegmentTestFunction;
  * areRoutesRelated("users", "admin");          // false (different branches)
  * areRoutesRelated("users.list", "users.view"); // false (siblings)
  */
-export declare function areRoutesRelated(route1: string, route2: string): boolean;
+declare function areRoutesRelated(route1: string, route2: string): boolean;
 
-export {};
+export { type SegmentTestFunction, areRoutesRelated, endsWithSegment, includesSegment, startsWithSegment };

package/dist/esm/index.d.mts

@@ -1,238 +1,16 @@
-// Generated by dts-bundle-generator v9.5.1
+import { State } from '@real-router/core';
 
-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.
  */
-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);
+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.
  *
@@ -292,7 +70,7 @@ export interface SegmentTestFunction {
  * @see endsWithSegment for suffix matching
  * @see includesSegment for anywhere matching
  */
-export declare const startsWithSegment: SegmentTestFunction;
+declare const startsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name ends with the given segment.
  *
@@ -333,7 +111,7 @@ export declare const startsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see includesSegment for anywhere matching
  */
-export declare const endsWithSegment: SegmentTestFunction;
+declare const endsWithSegment: SegmentTestFunction;
 /**
  * Tests if a route name includes the given segment anywhere in its path.
  *
@@ -378,7 +156,8 @@ export declare const endsWithSegment: SegmentTestFunction;
  * @see startsWithSegment for prefix matching
  * @see endsWithSegment for suffix matching
  */
-export declare const includesSegment: SegmentTestFunction;
+declare const includesSegment: SegmentTestFunction;
+
 /**
  * Checks if two routes are related in the hierarchy.
  *
@@ -398,6 +177,6 @@ export declare const includesSegment: SegmentTestFunction;
  * areRoutesRelated("users", "admin");          // false (different branches)
  * areRoutesRelated("users.list", "users.view"); // false (siblings)
  */
-export declare function areRoutesRelated(route1: string, route2: string): boolean;
+declare function areRoutesRelated(route1: string, route2: string): boolean;
 
-export {};
+export { type SegmentTestFunction, areRoutesRelated, endsWithSegment, includesSegment, startsWithSegment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/helpers",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "commonjs",
   "description": "Helper utilities for comparing and checking routes",
   "main": "./dist/cjs/index.js",
@@ -39,7 +39,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.2.3"
+    "@real-router/core": "^0.3.0"
   },
   "scripts": {
     "test": "vitest",