@real-router/types 0.7.0 → 0.9.0

package/dist/cjs/index.d.ts

@@ -151,55 +151,12 @@ interface NavigationOptions {
      * @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
+     * transition lifecycle. Similar to `reload` but can be used
      * for any forced navigation scenario.
      *
      * Difference from `reload`:
@@ -218,7 +175,6 @@ interface NavigationOptions {
      * 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;
     /**
@@ -251,7 +207,6 @@ interface NavigationOptions {
      *   });
      * }
      *
-     * @see {@link skipTransition} for bypassing all guards and middleware
      * @see {@link Router.clearCanDeactivate} for programmatically clearing guards
      */
     forceDeactivate?: boolean | undefined;
@@ -278,7 +233,7 @@ interface NavigationOptions {
      *
      * @example
      * // Accessing redirect flag in lifecycle
-     * router.canActivate('dashboard', (toState, fromState) => {
+     * router.addActivateGuard('dashboard', (toState, fromState) => {
      *   if (toState.meta?.redirected) {
      *     console.log('This navigation is from a redirect');
      *   }
@@ -505,8 +460,69 @@ interface Navigator {
     navigate: (routeName: string, routeParamsOrDone?: Params | DoneFn, optionsOrDone?: NavigationOptions | DoneFn, done?: DoneFn) => CancelFn;
     getState: () => State | undefined;
     isActiveRoute: (name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
+    canNavigateTo: (name: string, params?: Params) => boolean;
     subscribe: (listener: SubscribeFn) => Unsubscribe;
 }
+/**
+ * Router interface - public API for route navigation and lifecycle management.
+ *
+ * Defines the contract for router implementations. The actual Router class in
+ * @real-router/core implements this interface with full functionality.
+ *
+ * This interface uses `ActivationFn | boolean` for guard types to avoid circular
+ * dependencies. The concrete Router class in @real-router/core narrows this to
+ * `ActivationFnFactory | boolean` for more precise type checking.
+ */
+interface Router {
+    /**
+     * Register an activation guard for a route.
+     *
+     * @param name - Route name
+     * @param guard - Guard function or boolean
+     * @returns this for method chaining
+     */
+    addActivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    /**
+     * Register a deactivation guard for a route.
+     *
+     * @param name - Route name
+     * @param guard - Guard function or boolean
+     * @returns this for method chaining
+     */
+    addDeactivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    /**
+     * Remove an activation guard from a route.
+     *
+     * @param name - Route name
+     */
+    removeActivateGuard: (name: string) => void;
+    /**
+     * Remove a deactivation guard from a route.
+     *
+     * @param name - Route name
+     */
+    removeDeactivateGuard: (name: string) => void;
+    /**
+     * Check if navigation to a route is allowed without performing actual navigation.
+     *
+     * Synchronously checks all activation and deactivation guards in the transition path.
+     * Async guards return false with a console warning.
+     *
+     * @param name - Route name to check
+     * @param params - Route parameters (optional)
+     * @returns true if navigation is allowed, false otherwise
+     */
+    canNavigateTo: (name: string, params?: Params) => boolean;
+    /**
+     * Get a minimal, safe Navigator interface for passing to components.
+     *
+     * The returned Navigator object is frozen and includes only essential methods:
+     * navigate, getState, isActiveRoute, canNavigateTo, subscribe.
+     *
+     * @returns Frozen Navigator object
+     */
+    getNavigator: () => Navigator;
+}
 
 /**
  * Plugin lifecycle method names
@@ -565,4 +581,4 @@ interface ErrorCodeToValueMap {
     TRANSITION_CANCELLED: "CANCELLED";
 }
 
-export type { ActivationFn, CancelFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DoneFn, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };
+export type { ActivationFn, CancelFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DoneFn, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };

package/dist/cjs/metafile-cjs.json

@@ -1 +1 @@
-{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/index.ts":{"bytes":1238,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}
+{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/index.ts":{"bytes":1248,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}

package/dist/esm/index.d.mts

@@ -151,55 +151,12 @@ interface NavigationOptions {
      * @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
+     * transition lifecycle. Similar to `reload` but can be used
      * for any forced navigation scenario.
      *
      * Difference from `reload`:
@@ -218,7 +175,6 @@ interface NavigationOptions {
      * 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;
     /**
@@ -251,7 +207,6 @@ interface NavigationOptions {
      *   });
      * }
      *
-     * @see {@link skipTransition} for bypassing all guards and middleware
      * @see {@link Router.clearCanDeactivate} for programmatically clearing guards
      */
     forceDeactivate?: boolean | undefined;
@@ -278,7 +233,7 @@ interface NavigationOptions {
      *
      * @example
      * // Accessing redirect flag in lifecycle
-     * router.canActivate('dashboard', (toState, fromState) => {
+     * router.addActivateGuard('dashboard', (toState, fromState) => {
      *   if (toState.meta?.redirected) {
      *     console.log('This navigation is from a redirect');
      *   }
@@ -505,8 +460,69 @@ interface Navigator {
     navigate: (routeName: string, routeParamsOrDone?: Params | DoneFn, optionsOrDone?: NavigationOptions | DoneFn, done?: DoneFn) => CancelFn;
     getState: () => State | undefined;
     isActiveRoute: (name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean) => boolean;
+    canNavigateTo: (name: string, params?: Params) => boolean;
     subscribe: (listener: SubscribeFn) => Unsubscribe;
 }
+/**
+ * Router interface - public API for route navigation and lifecycle management.
+ *
+ * Defines the contract for router implementations. The actual Router class in
+ * @real-router/core implements this interface with full functionality.
+ *
+ * This interface uses `ActivationFn | boolean` for guard types to avoid circular
+ * dependencies. The concrete Router class in @real-router/core narrows this to
+ * `ActivationFnFactory | boolean` for more precise type checking.
+ */
+interface Router {
+    /**
+     * Register an activation guard for a route.
+     *
+     * @param name - Route name
+     * @param guard - Guard function or boolean
+     * @returns this for method chaining
+     */
+    addActivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    /**
+     * Register a deactivation guard for a route.
+     *
+     * @param name - Route name
+     * @param guard - Guard function or boolean
+     * @returns this for method chaining
+     */
+    addDeactivateGuard: (name: string, guard: ActivationFn | boolean) => this;
+    /**
+     * Remove an activation guard from a route.
+     *
+     * @param name - Route name
+     */
+    removeActivateGuard: (name: string) => void;
+    /**
+     * Remove a deactivation guard from a route.
+     *
+     * @param name - Route name
+     */
+    removeDeactivateGuard: (name: string) => void;
+    /**
+     * Check if navigation to a route is allowed without performing actual navigation.
+     *
+     * Synchronously checks all activation and deactivation guards in the transition path.
+     * Async guards return false with a console warning.
+     *
+     * @param name - Route name to check
+     * @param params - Route parameters (optional)
+     * @returns true if navigation is allowed, false otherwise
+     */
+    canNavigateTo: (name: string, params?: Params) => boolean;
+    /**
+     * Get a minimal, safe Navigator interface for passing to components.
+     *
+     * The returned Navigator object is frozen and includes only essential methods:
+     * navigate, getState, isActiveRoute, canNavigateTo, subscribe.
+     *
+     * @returns Frozen Navigator object
+     */
+    getNavigator: () => Navigator;
+}
 
 /**
  * Plugin lifecycle method names
@@ -565,4 +581,4 @@ interface ErrorCodeToValueMap {
     TRANSITION_CANCELLED: "CANCELLED";
 }
 
-export type { ActivationFn, CancelFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DoneFn, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };
+export type { ActivationFn, CancelFn, Config, DefaultDependencies, DefaultParamsCallback, DefaultRouteCallback, DoneFn, ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventName, EventToNameMap, EventToPluginMap, EventsKeys, ForwardToCallback, LimitsConfig, Listener, Middleware, NavigationOptions, Navigator, Options, Params, Plugin, PluginMethod, QueryParamsMode, QueryParamsOptions, RouteTreeState, Router, RouterError, SimpleState, State, StateMeta, StateMetaInput, SubscribeFn, SubscribeState, Subscription, Unsubscribe };

package/dist/esm/metafile-esm.json

@@ -1 +1 @@
-{"inputs":{"src/index.ts":{"bytes":1238,"imports":[],"format":"esm"}},"outputs":{"dist/esm/index.mjs":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}
+{"inputs":{"src/index.ts":{"bytes":1248,"imports":[],"format":"esm"}},"outputs":{"dist/esm/index.mjs":{"imports":[],"exports":[],"entryPoint":"src/index.ts","inputs":{"src/index.ts":{"bytesInOutput":0}},"bytes":0}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/types",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "commonjs",
   "description": "Shared TypeScript types for Real Router ecosystem",
   "types": "./dist/esm/index.d.mts",