@real-router/types 0.8.0 → 0.9.0

package/dist/cjs/index.d.ts

@@ -233,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');
      *   }
@@ -460,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
@@ -520,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

@@ -233,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');
      *   }
@@ -460,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
@@ -520,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.8.0",
+  "version": "0.9.0",
   "type": "commonjs",
   "description": "Shared TypeScript types for Real Router ecosystem",
   "types": "./dist/esm/index.d.mts",