ui5-lib-guard-router 1.5.2 → 1.5.3

package/README.md

@@ -715,6 +715,39 @@ export default class HomeController extends BaseController {
 >
 > In FLP apps with `sap-keep-alive` enabled, the component persists when navigating to other apps. Guards remain registered since the same instance is reused.
 
+### Metadata-driven guards via manifest
+
+For common patterns like "this route requires authentication", you can store per-route metadata in a custom manifest section and use a single global guard instead of writing repetitive per-route guards:
+
+```json
+{
+	"ui5.guard.router": {
+		"routeMeta": {
+			"admin": { "requiresAuth": true, "roles": ["admin"] },
+			"profile": { "requiresAuth": true },
+			"home": { "public": true }
+		}
+	}
+}
+```
+
+```typescript
+// Component.ts — read the custom section via getManifestEntry (typed path lookup)
+type RouteMeta = Record<string, Record<string, unknown>>;
+const routeMeta = (this.getManifestEntry("/ui5.guard.router/routeMeta") ?? {}) as RouteMeta;
+
+router.addGuard((context) => {
+	const meta = routeMeta[context.toRoute] ?? {};
+	if (meta.requiresAuth && !authModel.getProperty("/isLoggedIn")) return "login";
+	if (meta.roles && !hasAnyRole(meta.roles as string[])) return "forbidden";
+	return true;
+});
+```
+
+`getManifestEntry()` accepts a path string (starting with `/`) to reach into nested manifest sections. The return type is `any`, so the local `RouteMeta` alias provides type safety at the consumption site.
+
+This keeps guard logic in one place and route annotations in the manifest where they're visible and auditable. The custom namespace `ui5.guard.router` is ignored by the UI5 framework -- it's a convention for your application data.
+
 ### Native alternative for leave guards: Fiori Launchpad data loss prevention
 
 If your app runs inside SAP Fiori Launchpad (FLP), the shell provides built-in data loss protection through two public APIs on `sap.ushell.Container`:

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

@@ -16,7 +16,7 @@
 	},
 	"buildManifest": {
 		"manifestVersion": "0.2",
-		"timestamp": "2026-03-24T13:12:12.834Z",
+		"timestamp": "2026-03-25T20:16:53.021Z",
 		"versions": {
 			"builderVersion": "4.1.4",
 			"projectVersion": "4.0.13",
@@ -31,7 +31,7 @@
 			"includedTasks": [],
 			"excludedTasks": []
 		},
-		"version": "1.5.2",
+		"version": "1.5.3",
 		"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/Router.d.ts"/>
-/// <reference path="./resources/ui5/guard/router/types.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/NavigationOutcome.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.5.2</version>
+	<version>1.5.3</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

@@ -383,10 +383,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      * @since 1.0.1
      */
     addGuard: function _addGuard(guard) {
-      if (typeof guard !== "function") {
-        Log.warning("addGuard: not a function, ignoring", undefined, LOG_COMPONENT);
-        return this;
-      }
+      if (!this._isFn(guard, "addGuard")) return this;
       this._pipeline.addGlobalGuard(guard);
       return this;
     },
@@ -398,10 +395,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      * @since 1.0.1
      */
     removeGuard: function _removeGuard(guard) {
-      if (typeof guard !== "function") {
-        Log.warning("removeGuard: not a function, ignoring", undefined, LOG_COMPONENT);
-        return this;
-      }
+      if (!this._isFn(guard, "removeGuard")) return this;
       this._pipeline.removeGlobalGuard(guard);
       return this;
     },
@@ -424,17 +418,13 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
         let hasHandler = false;
         if (guard.beforeEnter !== undefined) {
           hasHandler = true;
-          if (typeof guard.beforeEnter !== "function") {
-            Log.warning("addRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
-          } else {
+          if (this._isFn(guard.beforeEnter, "addRouteGuard", routeName)) {
             this._pipeline.addEnterGuard(routeName, guard.beforeEnter);
           }
         }
         if (guard.beforeLeave !== undefined) {
           hasHandler = true;
-          if (typeof guard.beforeLeave !== "function") {
-            Log.warning("addRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
-          } else {
+          if (this._isFn(guard.beforeLeave, "addRouteGuard", routeName)) {
             this._pipeline.addLeaveGuard(routeName, guard.beforeLeave);
           }
         }
@@ -444,10 +434,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
         }
         return this;
       }
-      if (typeof guard !== "function") {
-        Log.warning("addRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
-        return this;
-      }
+      if (!this._isFn(guard, "addRouteGuard", routeName)) return this;
       if (!this._handleUnknownRouteRegistration(routeName, "addRouteGuard")) {
         return this;
       }
@@ -476,10 +463,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
         }
         return this;
       }
-      if (typeof guard !== "function") {
-        Log.warning("removeRouteGuard: not a function, ignoring", routeName, LOG_COMPONENT);
-        return this;
-      }
+      if (!this._isFn(guard, "removeRouteGuard", routeName)) return this;
       this._pipeline.removeEnterGuard(routeName, guard);
       return this;
     },
@@ -496,16 +480,40 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      * @since 1.0.1
      */
     addLeaveGuard: function _addLeaveGuard(routeName, guard) {
-      if (typeof guard !== "function") {
-        Log.warning("addLeaveGuard: not a function, ignoring", routeName, LOG_COMPONENT);
-        return this;
-      }
+      if (!this._isFn(guard, "addLeaveGuard", routeName)) return this;
       if (!this._handleUnknownRouteRegistration(routeName, "addLeaveGuard")) {
         return this;
       }
       this._pipeline.addLeaveGuard(routeName, guard);
       return this;
     },
+    /**
+     * Disambiguate the `navTo()` overload shapes into resolved arguments.
+     *
+     * UI5's native `navTo` has two signatures where the third parameter is either
+     * `componentTargetInfo` (object) or `bReplace` (boolean). This method normalizes
+     * both forms so the rest of `navTo` can work with a single set of variables.
+     */
+    _resolveNavToArgs: function _resolveNavToArgs(componentTargetInfoOrReplace, replaceOrOptions, options) {
+      if (typeof componentTargetInfoOrReplace === "boolean") {
+        // Short form: navTo(name, params, replace, options?)
+        return {
+          replace: componentTargetInfoOrReplace,
+          guardOptions: typeof replaceOrOptions === "object" && replaceOrOptions !== null ? replaceOrOptions : undefined
+        };
+      }
+      // Long form: navTo(name, params, componentTargetInfo, replace, options?)
+      return {
+        componentTargetInfo: componentTargetInfoOrReplace,
+        replace: typeof replaceOrOptions === "boolean" ? replaceOrOptions : undefined,
+        guardOptions: options
+      };
+    },
+    /** Return `true` when the value is a function; otherwise log a warning. */_isFn: function _isFn(value, method, detail) {
+      if (typeof value === "function") return true;
+      Log.warning(`${method}: not a function, ignoring`, detail, LOG_COMPONENT);
+      return false;
+    },
     /**
      * Handle guard registration for a potentially unknown route.
      * Returns `true` if registration should proceed, `false` if not.
@@ -532,10 +540,7 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
      * @since 1.0.1
      */
     removeLeaveGuard: function _removeLeaveGuard(routeName, guard) {
-      if (typeof guard !== "function") {
-        Log.warning("removeLeaveGuard: not a function, ignoring", routeName, LOG_COMPONENT);
-        return this;
-      }
+      if (!this._isFn(guard, "removeLeaveGuard", routeName)) return this;
       this._pipeline.removeLeaveGuard(routeName, guard);
       return this;
     },
@@ -596,20 +601,11 @@ sap.ui.define(["sap/m/routing/Router", "sap/base/Log", "sap/ui/core/library", ".
       this.fireEvent("navigationSettled", result);
     },
     navTo: function _navTo(routeName, parameters, componentTargetInfoOrReplace, replaceOrOptions, options) {
-      // Normalize the overload shapes into a single set of arguments.
-      let componentTargetInfo;
-      let replace;
-      let guardOptions;
-      if (typeof componentTargetInfoOrReplace === "boolean") {
-        // Short form: navTo(name, params, replace, options?)
-        replace = componentTargetInfoOrReplace;
-        guardOptions = typeof replaceOrOptions === "object" && replaceOrOptions !== null ? replaceOrOptions : undefined;
-      } else {
-        // Long form: navTo(name, params, componentTargetInfo, replace, options?)
-        componentTargetInfo = componentTargetInfoOrReplace;
-        replace = typeof replaceOrOptions === "boolean" ? replaceOrOptions : undefined;
-        guardOptions = options;
-      }
+      const {
+        componentTargetInfo,
+        replace,
+        guardOptions
+      } = this._resolveNavToArgs(componentTargetInfoOrReplace, replaceOrOptions, options);
 
       // Redirect path: _redirect() calls this.navTo() while in committing/redirect phase.
       // Bypass preflight -- parse() will commit directly via the committing phase.