@marianmeres/simple-router 3.0.1 → 3.3.0

package/README.md

@@ -77,7 +77,35 @@ window.onhashchange = () => {
 
 ### Separators
 
-The default separator is `/`. Multiple separators are normalized to single, and separators are trimmed from both ends before matching.
+The default separator is `/`. By default (non-strict mode), multiple consecutive separators are collapsed into a single one, and separators are trimmed from both ends before matching. So `/foo//bar` and `/foo/bar/` both resolve to `/foo/bar`.
+
+If you need to treat consecutive separators as significant (for example, to canonicalize URLs and prevent accidental shadow-matching), enable **strict mode**:
+
+```ts
+// At router level (propagates to every route):
+const router = new SimpleRouter({ strict: true, routes: { "/a/b": handler } });
+router.exec("/a/b");   // matches
+router.exec("/a//b");  // false (no match)
+
+// Per-route override:
+router.on("/legacy", handler, { strict: true });
+
+// Or directly on SimpleRoute:
+new SimpleRoute("/a/b", { strict: true });
+```
+
+### Optional segments
+
+Optional segments (`[name]?`) are only allowed in **trailing position** (or directly before a trailing wildcard `*`). Optional-followed-by-required patterns are rejected at construction:
+
+```ts
+new SimpleRoute("/foo/[bar]?/baz");
+// Throws: optional segment '[bar]?' must not be followed by a required segment
+
+// Instead, register two routes:
+router.on("/foo/[bar]/baz", handler);
+router.on("/foo/baz",       handler);
+```
 
 ## Pattern Examples
 
@@ -96,7 +124,6 @@ The default separator is `/`. Multiple separators are normalized to single, and
 | `/foo/[bar]/[id([0-9]+)]`     | `/foo/baz/123`     | `{ bar: "baz", id: "123" }`      |
 | `/foo/[bar]?`                 | `/foo`             | `{}`                             |
 | `/foo/[bar]?`                 | `/foo/bar`         | `{ bar: "bar" }`                 |
-| `/foo/[bar]?/baz`             | `/foo/bar/baz`     | `{ bar: "bar" }`                 |
 | `/[...path]/[file]`           | `/foo/bar/baz.js`  | `{ path: "foo/bar", file: "baz.js" }` |
 | `/foo/*`                      | `/foo/bar/baz.js`  | `{}`                             |
 | `/[foo]/*`                    | `/foo/bar`         | `{ foo: "foo" }`                 |
@@ -126,7 +153,7 @@ const router = new SimpleRouter({
 });
 ```
 
-- `config` - Either a `RouterConfig` object mapping route patterns to callbacks, or a `RouterOptions` object with `routes` and `logger` properties
+- `config` - Either a `RouterConfig` object mapping route patterns to callbacks, or a `RouterOptions` object with `routes`, `logger`, and `strict` properties
 
 #### Methods
 
@@ -156,8 +183,9 @@ router.on("/raw", (params) => RawPage, { allowQueryParams: false });
 **Options:**
 - `label` - Optional label for debugging (visible via `info()`)
 - `allowQueryParams` - Whether to parse query parameters (default: `true`)
+- `strict` - Per-route strict matching (overrides router default)
 
-**Important:** Routes are matched in registration order. First match wins!
+**Important:** Routes are matched in registration order. First match wins! When `SimpleRouter.debug` is enabled, a warning is logged at registration time if a new route would be shadowed by an already-registered one.
 
 ##### `exec(url, fallbackFn?)`
 
@@ -255,19 +283,46 @@ SimpleRoute.parseQueryString("foo=bar&baz=123");
 
 ## TypeScript
 
-Full TypeScript support with exported types:
+Full TypeScript support with generic types for type-safe route callbacks and `exec()` return values.
+
+### Generic Router
+
+`SimpleRouter<T>` is generic over `T`, the return type of route callbacks:
+
+```ts
+// Typed router - all callbacks must return Component, exec() returns Component | false
+const router = new SimpleRouter<Component>({
+	"/": () => HomePage,
+	"/about": () => AboutPage,
+	"*": () => NotFoundPage,
+});
+
+const result = router.exec("/about"); // Component | false
+if (result !== false) {
+	render(result); // result is Component
+}
+
+// Without explicit type - T is inferred from callbacks (or defaults to unknown)
+const router2 = new SimpleRouter({
+	"/": () => "home",
+	"/about": () => "about",
+});
+```
+
+### Exported Types
 
 ```ts
 import type {
 	Logger,
 	RouteParams,
-	RouteCallback,
-	RouterConfig,
+	RouteCallback,      // RouteCallback<T = unknown>
+	RouterConfig,       // RouterConfig<T = unknown>
 	RouterCurrent,
 	RouterOnOptions,
-	RouterOptions,
+	RouterOptions,      // RouterOptions<T = unknown>
 	RouterSubscriber,
 	RouterUnsubscribe,
+	SimpleRouteOptions, // { strict?: boolean }
 } from "@marianmeres/simple-router";
 ```
 
@@ -276,21 +331,24 @@ import type {
 ### SPA with Hash Routing
 
 ```ts
-const router = new SimpleRouter({
+// Type-safe router with Component return type
+const router = new SimpleRouter<Component>({
 	"/": () => HomePage,
 	"/about": () => AboutPage,
 	"/user/[id]": (params) => UserPage(params?.id),
 	"*": () => NotFoundPage,
 });
 
-function render(component) {
-	document.getElementById("app").innerHTML = component;
+function render(component: Component) {
+	document.getElementById("app").innerHTML = component.render();
 }
 
 window.addEventListener("hashchange", () => {
 	const path = location.hash.slice(1) || "/";
-	const component = router.exec(path);
-	render(component);
+	const component = router.exec(path); // Component | false
+	if (component !== false) {
+		render(component);
+	}
 });
 
 // Trigger initial render
@@ -365,5 +423,19 @@ dotRouter.exec("app.settings.profile");
 // Returns: "Settings: profile"
 ```
 
+## Security notes
+
+Regex constraints inside a route pattern (e.g. `[id([0-9]+)]`) are compiled with `RegExp`, so any valid JavaScript regex is accepted. A handful of patterns — typically nested quantifiers such as `(a+)+` — can exhibit catastrophic backtracking (ReDoS) on crafted inputs.
+
+- Route patterns are author-controlled: **never** accept them from untrusted input.
+- Prefer simple character classes (`[0-9]+`, `[a-z]+`) over nested quantifiers.
+- If you need a complex constraint, test it against adversarial inputs first.
+
+## Breaking changes
+
+### 3.2.0
 
+- **Optional-followed-by-required is now rejected at construction.** Patterns like `/foo/[bar]?/baz` previously parsed but silently treated the optional marker as required — `/foo/baz` never matched. Such patterns now throw with a clear error. Register two separate routes instead (`/foo/[bar]/baz` and `/foo/baz`).
+- **Parameter names are no longer URI-decoded.** A pattern like `/foo/[id%20x]` used to produce the key `id x` in the params object; it now produces `id%20x`. Param values are still decoded. Parameter names in a named constraint (`[name(regex)]`) must now match `\w+`.
+- **Regex constraints with parentheses now work correctly.** Patterns like `/[id((?:a|b)+)]` previously produced garbage regexes or threw obscure "Invalid regular expression" errors; they now parse and match as expected.
 

package/dist/mod.d.ts

@@ -1,4 +1,4 @@
 export { SimpleRoute } from "./route.js";
 export { SimpleRouter } from "./router.js";
-export type { RouteConfig, RouteParams } from "./route.js";
+export type { RouteConfig, RouteParams, SimpleRouteOptions } from "./route.js";
 export type { Logger, RouteCallback, RouterConfig, RouterCurrent, RouterOnOptions, RouterOptions, RouterSubscriber, RouterUnsubscribe, } from "./router.js";

package/dist/route.d.ts

@@ -13,6 +13,17 @@ export interface RouteConfig {
  * Route parameters extracted from URL segments and query strings.
  */
 export type RouteParams = Record<string, any>;
+/**
+ * Options for the `SimpleRoute` constructor.
+ */
+export interface SimpleRouteOptions {
+    /**
+     * When true, empty segments (caused by consecutive separators) are preserved
+     * rather than silently collapsed. In strict mode, inputs like `/a//b` will
+     * NOT match a pattern `/a/b`. Default: false.
+     */
+    strict?: boolean;
+}
 export declare class SimpleRoute {
     #private;
     readonly route: string;
@@ -30,7 +41,9 @@ export declare class SimpleRoute {
      * Creates a new SimpleRoute instance.
      *
      * @param route - Pattern string to match against (URL, file path, command, or any string identifier)
-     * @throws {Error} If route pattern is invalid (e.g., multiple spread segments)
+     * @param options - Optional configuration (e.g. `{ strict: true }` to disable empty-segment collapsing)
+     * @throws {Error} If route pattern is invalid (multiple spread segments, optional
+     * segment followed by a required one, invalid regex constraint, etc.)
      *
      * @example
      * ```ts
@@ -44,9 +57,12 @@ export declare class SimpleRoute {
      *
      * // Command patterns
      * new SimpleRoute("user:delete:[id]");
+     *
+     * // Strict mode: '/a//b' will NOT match '/a/b'
+     * new SimpleRoute("/a/b", { strict: true });
      * ```
      */
-    constructor(route: string);
+    constructor(route: string, options?: SimpleRouteOptions);
     /**
      * Parses a query string into an object of key-value pairs.
      * Handles URL decoding of both keys and values.

package/dist/route.js

@@ -11,11 +11,14 @@ export class SimpleRoute {
      */
     static WILDCARD = "*";
     #parsed;
+    #strict;
     /**
      * Creates a new SimpleRoute instance.
      *
      * @param route - Pattern string to match against (URL, file path, command, or any string identifier)
-     * @throws {Error} If route pattern is invalid (e.g., multiple spread segments)
+     * @param options - Optional configuration (e.g. `{ strict: true }` to disable empty-segment collapsing)
+     * @throws {Error} If route pattern is invalid (multiple spread segments, optional
+     * segment followed by a required one, invalid regex constraint, etc.)
      *
      * @example
      * ```ts
@@ -29,31 +32,54 @@ export class SimpleRoute {
      *
      * // Command patterns
      * new SimpleRoute("user:delete:[id]");
+     *
+     * // Strict mode: '/a//b' will NOT match '/a/b'
+     * new SimpleRoute("/a/b", { strict: true });
      * ```
      */
-    constructor(route) {
+    constructor(route, options = {}) {
         this.route = route;
-        this.#parsed = SimpleRoute.#parse(route);
+        this.#strict = options.strict === true;
+        this.#parsed = SimpleRoute.#parse(route, this.#strict);
     }
     // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
     static #escapeRegExp(str) {
         return str.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&");
     }
-    static #sanitizeAndSplit(str) {
+    static #sanitizeAndSplit(str, strict) {
         const s = SimpleRoute.#escapeRegExp(SimpleRoute.SPLITTER);
-        return (`${str}`
+        let out = `${str}`
             .trim()
             // Trim splitters from left and right
             .replace(new RegExp(`^(${s})+`), "")
             .replace(new RegExp(`(${s})+$`), "")
-            .split(SimpleRoute.SPLITTER)
-            // Remove empty segments (normalizes multiple splitters into one)
-            .filter(Boolean));
+            .split(SimpleRoute.SPLITTER);
+        // In non-strict mode, empty (internal) segments are silently collapsed.
+        // In strict mode, they are preserved and treated as literal empty segments
+        // (which generally will not match any parameterized pattern position).
+        if (!strict)
+            out = out.filter(Boolean);
+        return out;
+    }
+    /**
+     * Splits a bracketed definition like "name(regex)" into its two parts.
+     * Uses balanced-paren tracking so nested groups in the regex are preserved.
+     * Returns null if the input is not in the name(...)  shape.
+     */
+    static #splitNamedConstraint(inner) {
+        const open = inner.indexOf("(");
+        if (open <= 0)
+            return null;
+        if (!inner.endsWith(")"))
+            return null;
+        const name = inner.slice(0, open);
+        const regex = inner.slice(open + 1, -1);
+        return { name, regex };
     }
-    static #parse(route) {
+    static #parse(route, strict) {
         let wasSpread = false;
         let wasWildcard = false;
-        return SimpleRoute.#sanitizeAndSplit(route).reduce((memo, segment, idx, all) => {
+        const parsed = SimpleRoute.#sanitizeAndSplit(route, strict).reduce((memo, segment, idx, all) => {
             let name = null;
             // If optional, remove trailing '?' marker
             let isOptional = segment.endsWith("?");
@@ -84,12 +110,16 @@ export class SimpleRoute {
                 if (m) {
                     name = m[1];
                     test = /.+/;
-                    // id([0-9]+)
-                    const m2 = m[1].match(/^(\w.*)\((.+)\)$/);
-                    if (m2) {
-                        name = m2[1];
+                    // Named constraint: [id([0-9]+)], [s((?:a|b)+)], ...
+                    // Split on first '(' (balanced-paren-safe).
+                    const split = SimpleRoute.#splitNamedConstraint(m[1]);
+                    if (split) {
+                        if (!/^\w+$/.test(split.name)) {
+                            throw new Error(`Invalid parameter name '${split.name}' in route pattern '${segment}' (must match /^\\w+$/)`);
+                        }
+                        name = split.name;
                         try {
-                            test = new RegExp("^" + m2[2] + "$");
+                            test = new RegExp("^" + split.regex + "$");
                         }
                         catch (e) {
                             throw new Error(`Invalid regex in route pattern '${segment}': ${e.message}`);
@@ -104,6 +134,24 @@ export class SimpleRoute {
             memo.push({ segment, name, test, isOptional, isSpread });
             return memo;
         }, []);
+        // An optional segment may only appear in trailing position (or directly
+        // before a wildcard, which itself is optional). Otherwise the 'optional'
+        // marker is misleading — it can never actually be skipped.
+        for (let i = 0; i < parsed.length; i++) {
+            const p = parsed[i];
+            if (!p.isOptional)
+                continue;
+            // segment is optional — all following segments must also be optional
+            for (let j = i + 1; j < parsed.length; j++) {
+                if (!parsed[j].isOptional) {
+                    throw new Error(`Invalid route '${route}': optional segment '${p.segment}?' must not be followed by a required segment ('${parsed[j].segment}'). ` +
+                        `Optional segments are only allowed in trailing position. ` +
+                        `Register separate routes instead.`);
+                }
+            }
+            break;
+        }
+        return parsed;
     }
     /**
      * Parses a query string into an object of key-value pairs.
@@ -186,7 +234,7 @@ export class SimpleRoute {
             url = _backup.slice(0, qPos);
             matched = SimpleRoute.parseQueryString(_backup.slice(qPos + 1));
         }
-        let segments = SimpleRoute.#sanitizeAndSplit(url);
+        let segments = SimpleRoute.#sanitizeAndSplit(url, this.#strict);
         // If there are spread definitions, we need to adjust input by grouping
         // (joining) segments that were initially split
         const hasSpread = this.#parsed.some((v) => v.isSpread);
@@ -238,7 +286,7 @@ export class SimpleRoute {
             }
             if (p.name) {
                 try {
-                    matched[decodeURIComponent(p.name)] = decodeURIComponent(s);
+                    matched[p.name] = decodeURIComponent(s);
                 }
                 catch {
                     // Fallback for malformed URI components

package/dist/router.d.ts

@@ -12,19 +12,20 @@ export type RouteParams = Record<string, any>;
 /**
  * Callback function executed when a route matches.
  *
+ * @typeParam T - The return type of the callback
  * @param params - Extracted route parameters (null if no match)
  * @param route - The matched route pattern string
  * @returns Any value - useful for returning components, data, or control flow values
  *
  * @example
  * ```ts
- * const callback: RouteCallback = (params, route) => {
+ * const callback: RouteCallback<MyComponent> = (params, route) => {
  *   console.log(`Matched ${route} with params:`, params);
  *   return MyComponent;
  * };
  * ```
  */
-export type RouteCallback = (params: RouteParams | null, route: string) => any;
+export type RouteCallback<T = unknown> = (params: RouteParams | null, route: string) => T;
 /**
  * Represents the current router state including the matched route,
  * extracted parameters, and optional label.
@@ -45,21 +46,28 @@ export interface RouterOnOptions {
     label?: string | null;
     /** Whether to parse query parameters (default: true) */
     allowQueryParams?: boolean;
+    /**
+     * Strict matching mode for this route (overrides router-level default).
+     * See `RouterOptions.strict`.
+     */
+    strict?: boolean;
 }
 /**
  * Configuration object for initializing the router with routes.
  * Maps route patterns to their callback functions.
  *
+ * @typeParam T - The return type of route callbacks
+ *
  * @example
  * ```ts
- * const config: RouterConfig = {
+ * const config: RouterConfig<Component> = {
  *   "/": () => HomePage,
  *   "/user/[id]": (params) => UserPage(params?.id),
  *   "*": () => NotFoundPage
  * };
  * ```
  */
-export type RouterConfig = Record<string, RouteCallback>;
+export type RouterConfig<T = unknown> = Record<string, RouteCallback<T>>;
 /**
  * Logger interface compatible with `@marianmeres/clog`.
  * Provides console-compatible logging methods.
@@ -76,12 +84,21 @@ export interface Logger {
 }
 /**
  * Options for the SimpleRouter factory/constructor.
+ *
+ * @typeParam T - The return type of route callbacks
  */
-export interface RouterOptions {
+export interface RouterOptions<T = unknown> {
     /** Route configuration mapping patterns to callbacks */
-    routes?: RouterConfig | null;
+    routes?: RouterConfig<T> | null;
     /** Optional logger instance for debug output (compatible with @marianmeres/clog) */
     logger?: Logger | null;
+    /**
+     * Strict matching mode. When true, empty segments in inputs (caused by
+     * consecutive separators like `/a//b`) are NOT silently collapsed — such
+     * inputs will not match the canonical pattern `/a/b`. Propagates to every
+     * route registered via this router. Default: false.
+     */
+    strict?: boolean;
 }
 /**
  * Unsubscribe function returned by the `subscribe()` method.
@@ -123,8 +140,10 @@ export type RouterSubscriber = (current: RouterCurrent) => void;
  *
  * cmdRouter.exec("user:delete:123");
  * ```
+ *
+ * @typeParam T - The return type of route callbacks (default: unknown)
  */
-export declare class SimpleRouter {
+export declare class SimpleRouter<T = unknown> {
     #private;
     /**
      * Enable/disable console debug logging for route matching.
@@ -140,14 +159,14 @@ export declare 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
@@ -156,7 +175,7 @@ export declare class SimpleRouter {
      * });
      * ```
      */
-    constructor(config?: RouterConfig | RouterOptions | null);
+    constructor(config?: RouterConfig<T> | RouterOptions<T> | null);
     /**
      * Returns a map of registered route patterns to their labels.
      * Useful for debugging and introspection.
@@ -224,38 +243,36 @@ export declare class SimpleRouter {
      * router.on("*", () => NotFoundPage);
      * ```
      */
-    on(routes: string | string[], cb: RouteCallback, options?: RouterOnOptions): void;
+    on(routes: string | string[], cb: RouteCallback<T>, options?: RouterOnOptions): void;
     /**
      * 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: string, fallbackFn?: RouteCallback): unknown;
+    exec(url: string, fallbackFn?: RouteCallback<T>): T | false;
     /**
      * Subscribes to router state changes.
      * Follows the Svelte store contract - subscriber is called immediately with current state.