ui5-lib-guard-router 1.3.2 → 1.5.0

package/README.md

@@ -27,6 +27,9 @@ This library solves all three by intercepting at the router level, before any ro
 npm install ui5-lib-guard-router
 ```
 
+> [!NOTE]
+> The npm package is ~150 KB compressed (~670 KB unpacked) because it ships both pre-built distributables (`dist/`) and TypeScript sources (`src/`) to support multiple [serving options](#serving-the-library). At runtime, the browser loads only the `library-preload.js` bundle (~25 KB).
+
 ### TypeScript
 
 Add the library to `compilerOptions.types` so TypeScript can resolve the type declarations. If your app does not already depend on UI5 typings, install them too (`@sapui5/types` works as well):
@@ -215,14 +218,15 @@ All guard registration and removal methods return `this` for chaining. `navigati
 
 Every guard receives a `GuardContext` object:
 
-| Property      | Type                                               | Description                                                       |
-| ------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
-| `toRoute`     | `string`                                           | Target route name (empty if no match)                             |
-| `toHash`      | `string`                                           | Raw hash being navigated to                                       |
-| `toArguments` | `Record<string, string \| Record<string, string>>` | Parsed route parameters                                           |
-| `fromRoute`   | `string`                                           | Current route name (empty on first navigation)                    |
-| `fromHash`    | `string`                                           | Current hash                                                      |
-| `signal`      | `AbortSignal`                                      | Aborted when navigation is superseded, or on `stop()`/`destroy()` |
+| Property      | Type                                               | Description                                                               |
+| ------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
+| `toRoute`     | `string`                                           | Target route name (empty if no match)                                     |
+| `toHash`      | `string`                                           | Raw hash being navigated to                                               |
+| `toArguments` | `Record<string, string \| Record<string, string>>` | Parsed route parameters                                                   |
+| `fromRoute`   | `string`                                           | Current route name (empty on first navigation)                            |
+| `fromHash`    | `string`                                           | Current hash                                                              |
+| `signal`      | `AbortSignal`                                      | Aborted when navigation is superseded, or on `stop()`/`destroy()`         |
+| `bag`         | `Map<string, unknown>`                             | Shared mutable store for inter-guard data passing within one pipeline run |
 
 ### Return values (`GuardResult`)
 
@@ -279,6 +283,7 @@ const result: NavigationResult = await router.navigationSettled();
 | `NavigationOutcome.Blocked`    | A guard blocked navigation; previous route stays active                                                 |
 | `NavigationOutcome.Redirected` | A guard redirected navigation to a different route                                                      |
 | `NavigationOutcome.Cancelled`  | Navigation was cancelled before settling (superseded, stopped, or destroyed)                            |
+| `NavigationOutcome.Error`      | A guard threw or rejected; previous route stays active. `result.error` holds the thrown value           |
 
 A guard redirect that fails to trigger a follow-up navigation settles as `Blocked` because no route change commits. A nonexistent route name is the most common cause, and the router logs the target name to help diagnose it.
 
@@ -314,6 +319,9 @@ switch (result.status) {
 	case NavigationOutcome.Redirected:
 		MessageToast.show(`Redirected to ${result.route}`);
 		break;
+	case NavigationOutcome.Error:
+		MessageBox.error("Navigation failed: " + String(result.error));
+		break;
 	case NavigationOutcome.Cancelled:
 		break; // superseded by a newer navigation
 }
@@ -343,6 +351,10 @@ router.attachNavigationSettled((event) => {
 
 Use `detachNavigationSettled(fnFunction, oListener)` to remove the listener. The same function and listener references must match those passed to `attachNavigationSettled`. The event uses UI5's native `EventProvider` mechanism, so the standard `attachEvent` / `detachEvent` pattern also works.
 
+### Error handling
+
+When a guard throws or its Promise rejects, the navigation settles as `Error` with `result.error` containing the thrown value. The previous route stays active. This is distinct from `Blocked` (intentional denial) — `Error` indicates an unexpected failure.
+
 ### Execution order
 
 1. **Leave guards** for the current route (registration order)
@@ -350,6 +362,232 @@ Use `detachNavigationSettled(fnFunction, oListener)` to remove the listener. The
 3. **Route-specific enter guards** for the target (registration order)
 4. Pipeline **short-circuits** at the first non-`true` result
 
+Each phase short-circuits on the first non-`true` result. If a leave guard blocks, no enter guards run. If a global guard redirects, route-specific guards are skipped.
+
+## Manifest Configuration
+
+Guards can be declared directly in `manifest.json` using the `guardRouter` block inside `sap.ui5.routing.config`. This eliminates boilerplate in `Component.ts` for common guard patterns.
+
+```json
+{
+	"sap.ui5": {
+		"routing": {
+			"config": {
+				"routerClass": "ui5.guard.router.Router",
+				"guardRouter": {
+					"unknownRouteGuardRegistration": "warn",
+					"navToPreflight": "guard",
+					"guardLoading": "lazy",
+					"guards": {
+						"*": ["guards.authGuard"],
+						"admin": {
+							"enter": ["guards.adminGuard"],
+							"leave": ["guards.unsavedChangesGuard"]
+						}
+					}
+				}
+			}
+		}
+	}
+}
+```
+
+### Router options
+
+| Option                          | Values                              | Default   | Description                                                                                                                                                                                                                                                   |
+| ------------------------------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unknownRouteGuardRegistration` | `"ignore"` \| `"warn"` \| `"throw"` | `"warn"`  | What to do when a guard is declared for a route name that doesn't exist in the manifest                                                                                                                                                                       |
+| `navToPreflight`                | `"guard"` \| `"bypass"` \| `"off"`  | `"guard"` | Whether `navTo()` calls run through the guard pipeline (`"guard"`), skip guards (`"bypass"`), or the preflight is disabled entirely (`"off"`)                                                                                                                 |
+| `guardLoading`                  | `"block"` \| `"lazy"`               | `"lazy"`  | `"lazy"`: registers lazy wrappers, loads modules on first navigation; a preload hint fires in the constructor to warm the cache; `initialize()` is always synchronous. `"block"`: loads all modules before `initialize()` completes; `initialize()` is async. |
+
+### Declarative guards
+
+The `guards` map wires guard modules to routes without writing code in `Component.ts`.
+
+**Global guards** run on every navigation and are declared under the `"*"` key:
+
+```json
+"guards": {
+	"*": ["guards.authGuard"]
+}
+```
+
+**Per-route guards** use the route name as the key. The shorthand array form registers enter guards only:
+
+```json
+"guards": {
+	"admin": ["guards.adminGuard"]
+}
+```
+
+The full object form with `enter` and `leave` keys registers both enter and leave guards:
+
+```json
+"guards": {
+	"admin": {
+		"enter": ["guards.adminGuard"],
+		"leave": ["guards.unsavedChangesGuard"]
+	}
+}
+```
+
+**Module paths** use dot notation and are resolved relative to `sap.app.id`. Given `sap.app.id = "com.example.app"`, the path `"guards.authGuard"` resolves to `"com/example/app/guards/authGuard"`.
+
+To use an absolute module path, prefix it with `"module:"`:
+
+```json
+"*": ["module:com/shared/guards/authGuard"]
+```
+
+### Complete example
+
+manifest.json:
+
+```json
+{
+	"sap.ui5": {
+		"routing": {
+			"config": {
+				"routerClass": "ui5.guard.router.Router",
+				"guardRouter": {
+					"guards": {
+						"*": ["guards.authGuard"],
+						"admin": { "enter": ["guards.roleGuard"], "leave": ["guards.unsavedGuard"] }
+					}
+				}
+			}
+		}
+	}
+}
+```
+
+guards/authGuard.ts:
+
+```typescript
+import type { GuardContext, GuardResult } from "ui5/guard/router/types";
+
+export default function authGuard(context: GuardContext): GuardResult {
+	if (!isAuthenticated()) return "login";
+	return true;
+}
+```
+
+The router loads `guards.authGuard` relative to `sap.app.id`. For `sap.app.id = "com.example.app"`, this resolves to `com/example/app/guards/authGuard`.
+
+### Guard module format
+
+Each entry in the guard array is a module whose default export is one of three shapes:
+
+**Shape 1: Function (single guard)**
+
+```typescript
+// guards/auth.ts
+import type { GuardContext, GuardResult } from "ui5/guard/router/types";
+
+export default function authGuard(context: GuardContext): GuardResult {
+	return isAuthenticated() ? true : "login";
+}
+```
+
+**Shape 2: Array (ordered guards)**
+
+```typescript
+// guards/checks.ts — registered as "checks#0", "checks#1"
+import type { GuardContext, GuardResult } from "ui5/guard/router/types";
+
+export default [
+	function checkAuth(context: GuardContext): GuardResult {
+		return true;
+	},
+	function checkRole(context: GuardContext): GuardResult {
+		return false;
+	},
+];
+```
+
+**Shape 3: Plain Object (named guards)**
+
+```typescript
+// guards/security.ts — registered as "checkAuth", "checkRole"
+import type { GuardContext, GuardResult } from "ui5/guard/router/types";
+
+export default {
+	checkAuth(context: GuardContext): GuardResult {
+		/* ... */ return true;
+	},
+	checkRole(context: GuardContext): GuardResult {
+		/* ... */ return false;
+	},
+};
+```
+
+Detection: function produces a single guard, `Array` produces ordered guards, and a plain object produces named guards in key order. Non-function entries in arrays and objects are warned and skipped. Empty arrays and objects are warned and produce no guards.
+
+### Cherry-pick syntax
+
+When a module exports multiple guards, you can register a subset using `#` to select by name or index:
+
+```json
+{
+	"guards": {
+		"admin": ["guards.security#checkAuth", "guards.security#checkRole"],
+		"dashboard": ["guards.security"],
+		"settings": ["guards.checks#1"],
+		"*": ["guards.logging"]
+	}
+}
+```
+
+| Syntax                               | Behavior                                      |
+| ------------------------------------ | --------------------------------------------- |
+| `"guards.security"`                  | Register all exports (key/array order)        |
+| `"guards.security#checkAuth"`        | Register only that named export               |
+| `"guards.security#1"`                | Register by index (array or object key order) |
+| `"module:some.lib.guards#checkAuth"` | `module:` prefix composes with `#`            |
+
+When `#` is used on a single-function module, the export key is ignored with a debug message and the function is still registered.
+
+### Guard context `bag`
+
+Guards in the same pipeline can share data through `context.bag`, a `Map<string, unknown>` that is created fresh for each navigation and shared across all guards in that pipeline:
+
+```typescript
+export default function firstGuard(context: GuardContext): GuardResult {
+	context.bag.set("userId", getCurrentUserId());
+	return true;
+}
+
+export default function secondGuard(context: GuardContext): GuardResult {
+	const userId = context.bag.get("userId") as string | undefined;
+	if (!userId) return "login";
+	return true;
+}
+```
+
+The bag is typed as `Map<string, unknown>`, so consumers cast on `.get()`. This matches how UI5 handles untyped model data (`getProperty()` returns `any`) and avoids generic complexity that can't flow through UI5's class system.
+
+This is useful for avoiding repeated work (such as fetching the current user) when multiple guards need the same data in a single navigation.
+
+### `skipGuards` option
+
+Pass `{ skipGuards: true }` as the fourth argument to `navTo()` to bypass all guards for a single call. Use this for internal redirects or navigations that should not be subject to guard logic:
+
+```typescript
+router.navTo("settings", {}, false, { skipGuards: true });
+```
+
+### Mixing declarative and programmatic guards
+
+Manifest guards and programmatic guards coexist on the same pipeline. Manifest guards are registered during `initialize()` (before the first navigation), and programmatic guards are added whenever `addGuard()` / `addRouteGuard()` / `addLeaveGuard()` is called.
+
+**Execution order:** manifest guards run first (in declaration order), then programmatic guards (in registration order). For the same route, both sets execute — they are additive, not exclusive.
+
+A common pattern is to declare static guards in the manifest and add context-dependent guards programmatically:
+
+- **Manifest:** guards that don't need component state (simple blocks, redirects, logging)
+- **Programmatic:** guards that close over models, services, or runtime state
+- **Controller-level:** guards tied to a specific view's lifecycle (registered in `onInit`, removed in `onExit`)
+
 ## Examples
 
 ### Async guard with AbortSignal
@@ -408,7 +646,7 @@ export function createDirtyFormGuard(formModel: JSONModel): LeaveGuardFn {
 
 ### Object form with RouteGuardConfig
 
-The runnable demo uses the same object form in `packages/demo-app/webapp/Component.ts`, pairing an async permission check with a leave guard on the `protected` route.
+The object form is useful when registering both enter and leave guards for the same route in a single call:
 
 ```typescript
 import type { RouteGuardConfig } from "ui5/guard/router/types";
@@ -537,33 +775,25 @@ No `toRoute` check or FLP detection is needed in the leave guard. Cross-app navi
 
 See the [FLP Dirty State Research](../../docs/research/flp-dirty-state.md) for a detailed analysis of the FLP internals.
 
-## Limitations
-
-### Redirect targets bypass guards
+## Redirect chains
 
-When a guard redirects navigation from route A to route B, route B's guards are **not** evaluated. The redirect commits immediately.
-
-This matters when the redirect target has its own guards. For example:
+When a guard redirects navigation from route A to route B, the router evaluates route B's guards before committing. If route B also redirects, the chain continues. Leave guards are skipped on redirect hops (they only run on the first navigation), but global and route-specific enter guards run on every hop.
 
 ```
 User navigates to "dashboard"
   → dashboard guard checks permissions, returns "profile"
-  → profile guard checks onboarding status ← this guard is SKIPPED
-  → profile view renders
+  → profile guard checks onboarding status ← this guard RUNS
+  → onboarding guard allows → onboarding view renders
 ```
 
-This is intentional. Evaluating guards on redirect targets introduces the risk of infinite loops (`A → B → A → B → ...`). While solvable with a visited-set that detects cycles, the implementation adds significant complexity. This is particularly true when redirect targets have **async** guards, since the redirect chain can no longer be bracketed in a single synchronous call stack. The chain state must then persist across async boundaries and be cleared only by terminal events (commit, block, or loop detection).
+Two safeguards prevent infinite redirect loops:
 
-In practice, redirect targets are typically "safe" routes like `home` or `login` that don't have guards of their own. If you need guard logic on a redirect target, run the check inline before returning the redirect:
+- **Visited-set detection**: The router tracks every hash evaluated in the current chain. Revisiting a hash is treated as a loop and blocks the navigation.
+- **Depth cap** (10 hops): Chains that exceed 10 redirect hops are blocked, even if every hash is unique. This guards against unbounded chains with parameterized routes.
 
-```typescript
-router.addRouteGuard("dashboard", (context) => {
-	if (!hasPermission()) {
-		return isOnboarded() ? "profile" : "onboarding";
-	}
-	return true;
-});
-```
+Both safeguards log an error and settle the navigation as `Blocked`.
+
+## Limitations
 
 ### History guarantees differ by navigation source
 
@@ -642,36 +872,16 @@ Or set the global log level via URL parameter (per-component filtering is only a
 
 > **Note**: UI5 1.120+ uses kebab-case URL parameters (`sap-ui-log-level`). Older versions use camelCase (`sap-ui-logLevel`).
 
-### Log reference
-
-| Level   | Message                                                                             | Trigger                                                                                             |
-| ------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| warning | `addGuard called with invalid guard, ignoring`                                      | Non-function passed to `addGuard()`                                                                 |
-| warning | `addRouteGuard called with invalid guard, ignoring`                                 | Non-function `beforeEnter`, `beforeLeave`, or direct guard                                          |
-| info    | `addRouteGuard called with config missing both beforeEnter and beforeLeave`         | Empty `RouteGuardConfig` object (no handlers)                                                       |
-| warning | `addLeaveGuard called with invalid guard, ignoring`                                 | Non-function passed to `addLeaveGuard()`                                                            |
-| warning | `removeGuard called with invalid guard, ignoring`                                   | Non-function passed to `removeGuard()`                                                              |
-| warning | `removeRouteGuard called with invalid guard, ignoring`                              | Non-function passed to `removeRouteGuard()`                                                         |
-| warning | `removeLeaveGuard called with invalid guard, ignoring`                              | Non-function passed to `removeLeaveGuard()`                                                         |
-| warning | `{method} called for unknown route; guard will still register...`                   | Route name not found at registration time                                                           |
-| warning | `Guard returned invalid value, treating as block`                                   | Enter guard returned something other than `true`, `false`, a non-empty string, or a `GuardRedirect` |
-| warning | `Leave guard returned non-boolean value, treating as block`                         | Leave guard returned something other than `true` or `false`                                         |
-| warning | `Guard redirect target "{route}" did not produce a navigation, treating as blocked` | Redirect target did not trigger a follow-up navigation (most commonly an unknown route name)        |
-| error   | `Guard pipeline failed for "{hash}", blocking navigation`                           | Async guard pipeline rejected in `parse()` fallback path                                            |
-| error   | `Async preflight guard failed for route "{route}", blocking navigation`             | Async guard pipeline rejected in `navTo()` preflight path                                           |
-| error   | `Enter guard [{n}] on route "{route}" threw, blocking navigation`                   | Sync or async enter guard threw an exception                                                        |
-| error   | `Leave guard [{n}] on route "{route}" threw, blocking navigation`                   | Sync or async leave guard threw an exception                                                        |
-| debug   | `Async guard result discarded (superseded by newer navigation)`                     | A newer navigation invalidated the pending async result (`parse()` path)                            |
-| debug   | `Async preflight result discarded (superseded by newer navigation)`                 | A newer navigation invalidated the pending async result (`navTo()` path)                            |
-
 ### Common issues
 
-**Guards not running**: Verify the route name passed to `addRouteGuard()` matches the route name in `manifest.json`, not the pattern or target name. If the guard is on a redirect target, it does not run -- see [Redirect targets bypass guards](#redirect-targets-bypass-guards).
+**Guards not running**: Verify the route name passed to `addRouteGuard()` matches the route name in `manifest.json`, not the pattern or target name. Guards on redirect targets do run; if a redirect chain is blocked by loop detection, check the error log for details -- see [Redirect chains](#redirect-chains).
 
 **Navigation blocked unexpectedly**: Only a strict `true` return value allows navigation. Returning `undefined`, `null`, or omitting a return statement blocks. Enable debug-level logging to identify which guard blocked.
 
 **Redirect treated as blocked**: The redirect did not trigger a follow-up navigation. Most often the target route name is wrong, but a same-hash no-op can look similar. The router logs the target name so you can verify the route and parameters.
 
+**Async guard hangs indefinitely**: `context.signal` only aborts on supersede or router stop/destroy, not on "too slow." If a guard's `fetch` targets a dead endpoint, the navigation stays in the evaluating phase forever. Combine `context.signal` with `AbortSignal.timeout()` to enforce a hard deadline: `signal: AbortSignal.any([context.signal, AbortSignal.timeout(10_000)])`. See the [async guard timeout pattern](../../docs/guides/integration-patterns.md#async-guard-timeout) for the full example and a compatibility fallback for older browsers.
+
 **Async guard result discarded**: A newer navigation started before the async guard resolved. The router uses a generation counter to discard stale results. This is expected behavior during rapid sequential navigations. The debug log confirms when this occurs.
 
 **URL bar shows target hash, then reverts**: This is expected for async guards. The `HashChanger` updates the URL before `parse()` runs. See [URL bar shows target hash during async guards](#url-bar-shows-target-hash-during-async-guards) for the architectural explanation and the busy-indicator pattern.

package/dist/.ui5/build-manifest.json

@@ -16,7 +16,7 @@
 	},
 	"buildManifest": {
 		"manifestVersion": "0.2",
-		"timestamp": "2026-03-22T11:02:53.747Z",
+		"timestamp": "2026-03-23T12:27:04.576Z",
 		"versions": {
 			"builderVersion": "4.1.4",
 			"projectVersion": "4.0.13",
@@ -31,7 +31,7 @@
 			"includedTasks": [],
 			"excludedTasks": []
 		},
-		"version": "1.3.2",
+		"version": "1.5.0",
 		"namespace": "ui5/guard/router",
 		"tags": {
 			"/resources/ui5/guard/router/GuardPipeline-dbg.js": {

package/dist/index.d.ts

@@ -33,7 +33,7 @@
 //   - @types/istanbul-lib-coverage@2.0.6
 //   - @types/qunit@2.19.13
 /// <reference path="./resources/ui5/guard/router/NavigationOutcome.d.ts"/>
-/// <reference path="./resources/ui5/guard/router/types.d.ts"/>
-/// <reference path="./resources/ui5/guard/router/Router.d.ts"/>
 /// <reference path="./resources/ui5/guard/router/library.d.ts"/>
-/// <reference path="./resources/ui5/guard/router/GuardPipeline.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/Router.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/GuardPipeline.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/types.d.ts"/>

package/dist/resources/ui5/guard/router/.library

@@ -2,7 +2,7 @@
 <library xmlns="http://www.sap.com/sap.ui.library.xsd">
 	<name>ui5.guard.router</name>
 	<vendor>Marco</vendor>
-	<version>1.3.2</version>
+	<version>1.5.0</version>
 	<copyright></copyright>
 	<title>UI5 Router extension with async navigation guards</title>
 	<documentation>Extends sap.m.routing.Router with async navigation guards, running before route matching begins.</documentation>

package/dist/resources/ui5/guard/router/GuardPipeline-dbg.js

@@ -43,24 +43,56 @@ sap.ui.define(["sap/base/Log"], function (Log) {
     _globalGuards = [];
     _enterGuards = new Map();
     _leaveGuards = new Map();
+
+    /** Register a guard that runs for every navigation. */
     addGlobalGuard(guard) {
       this._globalGuards.push(guard);
     }
+
+    /** Remove a previously registered global guard by reference. */
     removeGlobalGuard(guard) {
       const index = this._globalGuards.indexOf(guard);
       if (index !== -1) {
         this._globalGuards.splice(index, 1);
       }
     }
+
+    /**
+     * Register an enter guard for a specific route.
+     *
+     * @param route - Route name as defined in `manifest.json`.
+     * @param guard - Guard function to register.
+     */
     addEnterGuard(route, guard) {
       this._addToGuardMap(this._enterGuards, route, guard);
     }
+
+    /**
+     * Remove a previously registered enter guard by reference.
+     *
+     * @param route - Route name.
+     * @param guard - Guard function to remove.
+     */
     removeEnterGuard(route, guard) {
       this._removeFromGuardMap(this._enterGuards, route, guard);
     }
+
+    /**
+     * Register a leave guard for a specific route.
+     *
+     * @param route - Route name as defined in `manifest.json`.
+     * @param guard - Leave guard function to register.
+     */
     addLeaveGuard(route, guard) {
       this._addToGuardMap(this._leaveGuards, route, guard);
     }
+
+    /**
+     * Remove a previously registered leave guard by reference.
+     *
+     * @param route - Route name.
+     * @param guard - Leave guard function to remove.
+     */
     removeLeaveGuard(route, guard) {
       this._removeFromGuardMap(this._leaveGuards, route, guard);
     }
@@ -81,9 +113,15 @@ sap.ui.define(["sap/base/Log"], function (Log) {
      *
      * @param context - Complete guard context including AbortSignal.
      *   `context.fromRoute` controls leave-guard lookup: empty string skips leave guards.
+     * @param options - Optional evaluation options.
+     * @param options.skipLeaveGuards - When true, leave guards are skipped even if
+     *   `context.fromRoute` is set. Used by redirect chain hops to avoid re-running
+     *   leave guards while still preserving `fromRoute` in the context.
+     * @returns A synchronous {@link GuardDecision} when all guards return plain values,
+     *   or a `Promise<GuardDecision>` when at least one guard returns a thenable.
      */
-    evaluate(context) {
-      const hasLeaveGuards = context.fromRoute !== "" && this._leaveGuards.has(context.fromRoute);
+    evaluate(context, options) {
+      const hasLeaveGuards = !options?.skipLeaveGuards && context.fromRoute !== "" && this._leaveGuards.has(context.fromRoute);
       const hasEnterGuards = this._globalGuards.length > 0 || context.toRoute !== "" && this._enterGuards.has(context.toRoute);
       if (!hasLeaveGuards && !hasEnterGuards) {
         return {
@@ -103,6 +141,11 @@ sap.ui.define(["sap/base/Log"], function (Log) {
               action: "redirect",
               target: r
             };
+          }).catch(error => {
+            return {
+              action: "error",
+              error
+            };
           });
         }
         if (enterResult === true) return {
@@ -120,24 +163,36 @@ sap.ui.define(["sap/base/Log"], function (Log) {
         const enterResult = this._runEnterGuards(context.toRoute, context);
         return processEnterResult(enterResult);
       };
-      if (hasLeaveGuards) {
-        const leaveResult = this._runLeaveGuards(context);
-        if (isPromiseLike(leaveResult)) {
-          return leaveResult.then(allowed => {
-            if (allowed !== true) return {
-              action: "block"
-            };
-            if (context.signal.aborted) return {
-              action: "block"
-            };
-            return runEnterPhase();
-          });
+      try {
+        if (hasLeaveGuards) {
+          const leaveResult = this._runLeaveGuards(context);
+          if (isPromiseLike(leaveResult)) {
+            return leaveResult.then(allowed => {
+              if (allowed !== true) return {
+                action: "block"
+              };
+              if (context.signal.aborted) return {
+                action: "block"
+              };
+              return runEnterPhase();
+            }).catch(error => {
+              return {
+                action: "error",
+                error
+              };
+            });
+          }
+          if (leaveResult !== true) return {
+            action: "block"
+          };
         }
-        if (leaveResult !== true) return {
-          action: "block"
+        return runEnterPhase();
+      } catch (error) {
+        return {
+          action: "error",
+          error
         };
       }
-      return runEnterPhase();
     }
     _addToGuardMap(map, key, guard) {
       let guards = map.get(key);
@@ -174,8 +229,9 @@ sap.ui.define(["sap/base/Log"], function (Log) {
           }
           if (result !== true) return this._validateLeaveGuardResult(result);
         } catch (error) {
-          Log.error(`Leave guard [${i}] on route "${context.fromRoute}" threw, blocking navigation`, String(error), LOG_COMPONENT);
-          return false;
+          Log.error(`Leave guard [${i}] on route "${context.fromRoute}" threw, navigation failed`, String(error), LOG_COMPONENT);
+          if (context.signal.aborted) return false;
+          throw error;
         }
       }
       return true;
@@ -218,8 +274,9 @@ sap.ui.define(["sap/base/Log"], function (Log) {
           }
           if (result !== true) return this._validateGuardResult(result);
         } catch (error) {
-          Log.error(`Enter guard [${i}] on route "${context.toRoute}" threw, blocking navigation`, String(error), LOG_COMPONENT);
-          return false;
+          Log.error(`Enter guard [${i}] on route "${context.toRoute}" threw, navigation failed`, String(error), LOG_COMPONENT);
+          if (context.signal.aborted) return false;
+          throw error;
         }
       }
       return true;
@@ -252,7 +309,8 @@ sap.ui.define(["sap/base/Log"], function (Log) {
       } catch (error) {
         if (!context.signal.aborted) {
           const route = isLeaveGuard ? context.fromRoute : context.toRoute;
-          Log.error(`${label} [${guardIndex}] on route "${route}" threw, blocking navigation`, String(error), LOG_COMPONENT);
+          Log.error(`${label} [${guardIndex}] on route "${route}" threw, navigation failed`, String(error), LOG_COMPONENT);
+          throw error;
         }
         return false;
       }