ui5-lib-guard-router 1.5.0 → 1.5.1

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

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

package/dist/index.d.ts

@@ -32,8 +32,8 @@
 //   - @types/istanbul-lib-report@3.0.3
 //   - @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/library.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"/>
+/// <reference path="./resources/ui5/guard/router/types.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/NavigationOutcome.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/GuardPipeline.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.5.0</version>
+	<version>1.5.1</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/Router-dbg.js

@@ -84,6 +84,11 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
       exportKey
     };
   }
+  /** Log a warning about a guard module entry in the manifest. */
+  function guardWarning(modulePath, detail) {
+    Log.warning(`guardRouter.guards: "${modulePath}" ${detail}`, undefined, LOG_COMPONENT);
+  }
+
   /**
    * Detect the export shape of a loaded guard module and extract guard functions.
    *
@@ -101,7 +106,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
     // Shape 1: function
     if (typeof moduleExport === "function") {
       if (exportKey !== undefined) {
-        Log.debug(`guardRouter.guards: "${modulePath}#${exportKey}" exports a single function, ignoring export key`, undefined, LOG_COMPONENT);
+        Log.debug(`guardRouter.guards: "${modulePath}#${exportKey}" is a single function, ignoring export key`, undefined, LOG_COMPONENT);
       }
       return [{
         name: descriptorName,
@@ -112,18 +117,18 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
     // Shape 2: array
     if (Array.isArray(moduleExport)) {
       if (moduleExport.length === 0) {
-        Log.warning(`guardRouter.guards: module "${modulePath}" exported an empty array, skipping`, undefined, LOG_COMPONENT);
+        guardWarning(modulePath, "exported an empty array, skipping");
         return [];
       }
       if (exportKey !== undefined) {
         const index = parseInt(exportKey, 10);
         if (Number.isNaN(index) || index < 0 || index >= moduleExport.length) {
-          Log.warning(`guardRouter.guards: "${modulePath}#${exportKey}" - index out of range or invalid, skipping`, undefined, LOG_COMPONENT);
+          guardWarning(modulePath, `#${exportKey} - index out of range, skipping`);
           return [];
         }
         const entry = moduleExport[index];
         if (typeof entry !== "function") {
-          Log.warning(`guardRouter.guards: "${modulePath}#${exportKey}" is not a function, skipping`, undefined, LOG_COMPONENT);
+          guardWarning(modulePath, `#${exportKey} is not a function, skipping`);
           return [];
         }
         return [{
@@ -135,7 +140,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
       for (let i = 0; i < moduleExport.length; i++) {
         const entry = moduleExport[i];
         if (typeof entry !== "function") {
-          Log.warning(`guardRouter.guards: "${modulePath}"[${i}] is not a function, skipping`, undefined, LOG_COMPONENT);
+          guardWarning(modulePath, `[${i}] is not a function, skipping`);
           continue;
         }
         results.push({
@@ -150,7 +155,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
     if (isRecord(moduleExport)) {
       const entries = Object.entries(moduleExport);
       if (entries.length === 0) {
-        Log.warning(`guardRouter.guards: module "${modulePath}" exported an empty object, skipping`, undefined, LOG_COMPONENT);
+        guardWarning(modulePath, "exported an empty object, skipping");
         return [];
       }
       if (exportKey !== undefined) {
@@ -165,11 +170,11 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
           }
         }
         if (value === undefined) {
-          Log.warning(`guardRouter.guards: "${modulePath}#${exportKey}" - key not found, skipping`, undefined, LOG_COMPONENT);
+          guardWarning(modulePath, `#${exportKey} - key not found, skipping`);
           return [];
         }
         if (typeof value !== "function") {
-          Log.warning(`guardRouter.guards: "${modulePath}#${exportKey}" is not a function, skipping`, undefined, LOG_COMPONENT);
+          guardWarning(modulePath, `#${exportKey} is not a function, skipping`);
           return [];
         }
         return [{
@@ -180,7 +185,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
       const results = [];
       for (const [key, value] of entries) {
         if (typeof value !== "function") {
-          Log.warning(`guardRouter.guards: "${modulePath}".${key} is not a function, skipping`, undefined, LOG_COMPONENT);
+          guardWarning(modulePath, `.${key} is not a function, skipping`);
           continue;
         }
         results.push({
@@ -190,7 +195,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
       }
       return results;
     }
-    Log.warning(`guardRouter.guards: module "${modulePath}" did not export a function, array, or plain object, skipping`, undefined, LOG_COMPONENT);
+    guardWarning(modulePath, "did not export a function, array, or plain object, skipping");
     return [];
   }
 
@@ -389,7 +394,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      */
     addGuard: function _addGuard(guard) {
       if (typeof guard !== "function") {
-        Log.warning("addGuard called with invalid guard, ignoring", undefined, LOG_COMPONENT);
+        Log.warning("addGuard: not a function, ignoring", undefined, LOG_COMPONENT);
         return this;
       }
       this._pipeline.addGlobalGuard(guard);
@@ -403,7 +408,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      */
     removeGuard: function _removeGuard(guard) {
       if (typeof guard !== "function") {
-        Log.warning("removeGuard called with invalid guard, ignoring", undefined, LOG_COMPONENT);
+        Log.warning("removeGuard: not a function, ignoring", undefined, LOG_COMPONENT);
         return this;
       }
       this._pipeline.removeGlobalGuard(guard);
@@ -428,7 +433,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
         if (guard.beforeEnter !== undefined) {
           hasHandler = true;
           if (typeof guard.beforeEnter !== "function") {
-            Log.warning("addRouteGuard called with invalid guard, ignoring", routeName, LOG_COMPONENT);
+            Log.warning("addRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
           } else {
             this._pipeline.addEnterGuard(routeName, guard.beforeEnter);
           }
@@ -436,19 +441,19 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
         if (guard.beforeLeave !== undefined) {
           hasHandler = true;
           if (typeof guard.beforeLeave !== "function") {
-            Log.warning("addRouteGuard called with invalid guard, ignoring", routeName, LOG_COMPONENT);
+            Log.warning("addRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
           } else {
             this._pipeline.addLeaveGuard(routeName, guard.beforeLeave);
           }
         }
         if (!hasHandler) {
-          Log.info("addRouteGuard called with config missing both beforeEnter and beforeLeave", routeName, LOG_COMPONENT);
+          Log.info("addRouteGuard: config has no beforeEnter or beforeLeave", routeName, LOG_COMPONENT);
           return this;
         }
         return this;
       }
       if (typeof guard !== "function") {
-        Log.warning("addRouteGuard called with invalid guard, ignoring", routeName, LOG_COMPONENT);
+        Log.warning("addRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
         return this;
       }
       if (!this._handleUnknownRouteRegistration(routeName, "addRouteGuard")) {
@@ -479,7 +484,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
         return this;
       }
       if (typeof guard !== "function") {
-        Log.warning("removeRouteGuard called with invalid guard, ignoring", routeName, LOG_COMPONENT);
+        Log.warning("removeRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
         return this;
       }
       this._pipeline.removeEnterGuard(routeName, guard);
@@ -498,7 +503,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      */
     addLeaveGuard: function _addLeaveGuard(routeName, guard) {
       if (typeof guard !== "function") {
-        Log.warning("addLeaveGuard called with invalid guard, ignoring", routeName, LOG_COMPONENT);
+        Log.warning("addLeaveGuard: not a function, ignoring", routeName, LOG_COMPONENT);
         return this;
       }
       if (!this._handleUnknownRouteRegistration(routeName, "addLeaveGuard")) {
@@ -520,7 +525,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
           throw new Error(`${methodName} called for unknown route "${routeName}". ` + `Set guardRouter.unknownRouteGuardRegistration to "warn" or "ignore" to allow this.`);
         case "warn":
         default:
-          Log.warning(`${methodName} called for unknown route; guard will still register. ` + `If the route is added later via addRoute(), this warning can be ignored.`, routeName, LOG_COMPONENT);
+          Log.warning(`${methodName}: unknown route, guard registered anyway`, routeName, LOG_COMPONENT);
           return true;
       }
     },
@@ -533,7 +538,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      */
     removeLeaveGuard: function _removeLeaveGuard(routeName, guard) {
       if (typeof guard !== "function") {
-        Log.warning("removeLeaveGuard called with invalid guard, ignoring", routeName, LOG_COMPONENT);
+        Log.warning("removeLeaveGuard: not a function, ignoring", routeName, LOG_COMPONENT);
         return this;
       }
       this._pipeline.removeLeaveGuard(routeName, guard);
@@ -682,15 +687,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
           generation
         }
       };
-      const context = {
-        toRoute,
-        toHash: targetHash,
-        toArguments: routeInfo?.arguments ?? {},
-        fromRoute: this._currentRoute,
-        fromHash: this._currentHash ?? "",
-        signal: controller.signal,
-        bag: new Map()
-      };
+      const context = this._createGuardContext(toRoute, targetHash, routeInfo, controller.signal);
       const decision = this._pipeline.evaluate(context);
       if (isPromiseLike(decision)) {
         decision.then(d => {
@@ -749,25 +746,8 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
           this._blockNavigation(targetHash, false);
           break;
         case "redirect":
-          {
-            // Safe: sync path sets phase to evaluating; async .then() checks kind before calling here.
-            const {
-              attempt
-            } = this._phase;
-            const visited = new Set();
-            visited.add(targetHash);
-            this._redirect(decision.target, {
-              visited,
-              attemptedHash: targetHash,
-              restoreHash: false,
-              fromRoute: this._currentRoute,
-              fromHash: this._currentHash ?? "",
-              signal: attempt.controller.signal,
-              generation: attempt.generation,
-              bag
-            });
-            break;
-          }
+          this._startRedirectChain(decision.target, targetHash, false, bag);
+          break;
         case "error":
           this._errorNavigation(decision.error, targetHash, false);
           break;
@@ -815,15 +795,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
           generation
         }
       };
-      const context = {
-        toRoute,
-        toHash: newHash,
-        toArguments: routeInfo?.arguments ?? {},
-        fromRoute: this._currentRoute,
-        fromHash: this._currentHash ?? "",
-        signal: controller.signal,
-        bag: new Map()
-      };
+      const context = this._createGuardContext(toRoute, newHash, routeInfo, controller.signal);
       const decision = this._pipeline.evaluate(context);
       if (isPromiseLike(decision)) {
         decision.then(d => {
@@ -899,25 +871,8 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
           this._blockNavigation(hash);
           break;
         case "redirect":
-          {
-            // Safe: sync path sets phase to evaluating; async .then() checks kind before calling here.
-            const {
-              attempt
-            } = this._phase;
-            const visited = new Set();
-            visited.add(hash);
-            this._redirect(decision.target, {
-              visited,
-              attemptedHash: hash,
-              restoreHash: true,
-              fromRoute: this._currentRoute,
-              fromHash: this._currentHash ?? "",
-              signal: attempt.controller.signal,
-              generation: attempt.generation,
-              bag
-            });
-            break;
-          }
+          this._startRedirectChain(decision.target, hash, true, bag);
+          break;
         case "error":
           this._errorNavigation(decision.error, hash);
           break;
@@ -1106,6 +1061,44 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
           break;
       }
     },
+    /**
+     * Build a guard context for a new navigation.
+     * Called by {@link navTo} (preflight path) and {@link parse} (browser-initiated path).
+     */
+    _createGuardContext: function _createGuardContext(toRoute, toHash, routeInfo, signal) {
+      return {
+        toRoute,
+        toHash,
+        toArguments: routeInfo?.arguments ?? {},
+        fromRoute: this._currentRoute,
+        fromHash: this._currentHash ?? "",
+        signal,
+        bag: new Map()
+      };
+    },
+    /**
+     * Start a new redirect chain from the current evaluating phase.
+     * Called by {@link _applyPreflightDecision} and {@link _applyDecision}
+     * when a guard returns a redirect. Delegates to {@link _redirect} with
+     * a fresh {@link RedirectChainContext}.
+     */
+    _startRedirectChain: function _startRedirectChain(target, hash, restoreHash, bag) {
+      const {
+        attempt
+      } = this._phase;
+      const visited = new Set();
+      visited.add(hash);
+      this._redirect(target, {
+        visited,
+        attemptedHash: hash,
+        restoreHash,
+        fromRoute: this._currentRoute,
+        fromHash: this._currentHash ?? "",
+        signal: attempt.controller.signal,
+        generation: attempt.generation,
+        bag
+      });
+    },
     /**
      * Clear pending state and flush a Blocked settlement.
      * When `restoreHash` is true (default), also restores the browser hash
@@ -1123,7 +1116,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
     },
     /**
      * Clear pending state and flush an Error settlement.
-     * Same structure as `_blockNavigation` but with `NavigationOutcome.Error`
+     * Same structure as {@link _blockNavigation} but with `NavigationOutcome.Error`
      * and the error that caused the failure.
      */
     _errorNavigation: function _errorNavigation(error, attemptedHash, restoreHash = true) {