@marianmeres/simple-router 3.0.1 → 3.3.0

package/dist/router.js

@@ -30,6 +30,8 @@ const PUBSUB_TOPIC = "current";
  *
  * cmdRouter.exec("user:delete:123");
  * ```
+ *
+ * @typeParam T - The return type of route callbacks (default: unknown)
  */
 export class SimpleRouter {
     /**
@@ -40,6 +42,7 @@ export class SimpleRouter {
     static debug = false;
     #routes = [];
     #catchAll = null;
+    #strict = false;
     #current = {
         route: null,
         params: null,
@@ -55,14 +58,14 @@ export class SimpleRouter {
      *
      * @example
      * ```ts
-     * // Simple config (backwards compatible)
-     * const router = new SimpleRouter({
+     * // Typed router - exec() returns Component | false
+     * const router = new SimpleRouter<Component>({
      *   "/": () => HomePage,
      *   "/about": () => AboutPage
      * });
      *
      * // With options object
-     * const router = new SimpleRouter({
+     * const router = new SimpleRouter<Component>({
      *   routes: {
      *     "/": () => HomePage,
      *     "/about": () => AboutPage
@@ -74,11 +77,12 @@ export class SimpleRouter {
     constructor(config = null) {
         let routes = null;
         if (config) {
-            // Check if config is RouterOptions (has 'routes' or 'logger' key)
-            if ("routes" in config || "logger" in config) {
+            // Check if config is RouterOptions (has 'routes', 'logger' or 'strict' key)
+            if ("routes" in config || "logger" in config || "strict" in config) {
                 const options = config;
                 routes = options.routes ?? null;
                 this.#logger = options.logger ?? null;
+                this.#strict = options.strict === true;
             }
             else {
                 // Backwards compatible: treat as RouterConfig
@@ -178,6 +182,7 @@ export class SimpleRouter {
      */
     on(routes, cb, options = {}) {
         const { label = null, allowQueryParams = true } = options;
+        const strict = options.strict ?? this.#strict;
         if (!Array.isArray(routes))
             routes = [routes];
         routes.forEach((route) => {
@@ -185,43 +190,69 @@ export class SimpleRouter {
                 this.#catchAll = cb;
             }
             else {
-                this.#routes.push([
-                    new SimpleRoute(route),
-                    cb,
-                    allowQueryParams,
-                    label,
-                ]);
+                const sr = new SimpleRoute(route, { strict });
+                // Dev-only shadowing warning: if an earlier route would consume the
+                // literal form of this one, the new route is unreachable. Only runs
+                // when debug logging is enabled to avoid per-registration overhead
+                // in production.
+                if (SimpleRouter.debug)
+                    this.#warnIfShadowed(route);
+                this.#routes.push([sr, cb, allowQueryParams, label]);
             }
         });
     }
+    #warnIfShadowed(route) {
+        for (const [existing] of this.#routes) {
+            if (existing.route === route)
+                continue;
+            // If the existing pattern matches the literal text of the new route,
+            // any real input intended for the new route will also match the
+            // existing one first (first-match-wins).
+            let matched = null;
+            try {
+                matched = existing.parse(route);
+            }
+            catch {
+                // ignore — some patterns may not be parseable as inputs
+            }
+            if (matched !== null) {
+                const msg = `[SimpleRouter] route '${route}' is shadowed by earlier ` +
+                    `route '${existing.route}' (first-match-wins). ` +
+                    `Register the more specific route first.`;
+                if (this.#logger)
+                    this.#logger.warn(msg);
+                else
+                    console.warn(msg);
+                break;
+            }
+        }
+    }
     /**
      * Executes pattern matching against the provided string.
-     * Returns the value returned by the matched route's callback.
+     * Returns the value returned by the matched route's callback (type `T`).
      * Routes are tested in registration order - first match wins.
      *
      * @param url - String to match against registered patterns (can be a URL, file path, command, etc.)
      * @param fallbackFn - Optional fallback function if no route matches
-     * @returns The value returned by the matched callback, or false if no match
+     * @returns `T | false` - The value returned by the matched callback, or `false` if no match
      *
      * @example
      * ```ts
-     * // URL matching
-     * router.exec("/users"); // Returns result of callback
+     * // Type-safe routing
+     * const router = new SimpleRouter<Component>({ "/home": () => HomePage });
+     * const result = router.exec("/home"); // Component | false
      *
      * // With query parameters
      * router.exec("/users?sort=name");
      *
-     * // File path matching
-     * router.exec("src/components/Button.ts");
-     *
-     * // Command matching
-     * router.exec("user:delete:123");
-     *
      * // With fallback
-     * router.exec("/unknown", () => console.log("Not found"));
+     * router.exec("/unknown", () => NotFoundPage);
      *
-     * // Can return components, values, etc.
-     * const component = router.exec("/home");
+     * // Check for no match
+     * const component = router.exec("/path");
+     * if (component !== false) {
+     *   render(component);
+     * }
      * ```
      */
     exec(url, fallbackFn) {
@@ -233,7 +264,7 @@ export class SimpleRouter {
             if (params !== null) {
                 this.#publishCurrent(route.route, params, label);
                 this.#dbg(`${dbgPrefix}matches '${route.route}' with`, params);
-                return typeof cb === "function" ? cb(params, route.route) : true;
+                return cb(params, route.route);
             }
         }
         if (typeof fallbackFn === "function") {

package/package.json

@@ -1,20 +1,33 @@
 {
 	"name": "@marianmeres/simple-router",
-	"version": "3.0.1",
+	"version": "3.3.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md",
+		"CLAUDE.md"
+	],
 	"author": "Marian Meres",
 	"license": "MIT",
+	"dependencies": {
+		"@marianmeres/pubsub": "^3.0.0"
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/marianmeres/simple-router.git"
 	},
 	"bugs": {
 		"url": "https://github.com/marianmeres/simple-router/issues"
-	},
-	"dependencies": {
-		"@marianmeres/pubsub": "^2.2.0",
-		"@marianmeres/clog": "^2.3.3"
 	}
-}
+}