@marianmeres/simple-router 3.3.0 → 3.4.0

package/AGENTS.md

@@ -109,8 +109,8 @@ methods:
     important: "Routes matched in registration order - first match wins"
 
   - name: "exec"
-    signature: "(url: string, fallbackFn?: RouteCallback<T>) => T | false"
-    description: "Execute pattern matching"
+    signature: "(url: string, fallbackFn?: RouteCallback<T>, options?: { skipCatchAll?: boolean }) => T | false"
+    description: "Execute pattern matching. Pass { skipCatchAll: true } to match only real routes and return false on a miss instead of firing the registered '*' catch-all (an explicit fallbackFn is unaffected)."
     returns: "Callback result (type T), or false if no match"
 
   - name: "subscribe"
@@ -132,6 +132,11 @@ properties:
     type: "RouterCurrent"
     readonly: true
     description: "Current router state"
+
+  - name: "catchAll"
+    type: "RouteCallback<T> | null"
+    readonly: true
+    description: "The registered catch-all ('*') callback, or null. Does NOT execute it — lets a consumer fire the catch-all as a deliberate final step without re-scanning routes."
 ```
 
 ### SimpleRoute

package/API.md

@@ -112,6 +112,25 @@ console.log(router.current);
 // { route: "/user/[id]", params: { id: "123" }, label: null }
 ```
 
+#### `catchAll`
+
+```ts
+get catchAll(): RouteCallback<T> | null
+```
+
+Returns the registered catch-all (`*`) callback, or `null` if none was registered. Does **not** execute it — this lets a consumer fire the catch-all as a deliberate final step (e.g. after an `exec(url, undefined, { skipCatchAll: true })` pass across several routers) without re-scanning the registered routes.
+
+**Returns:** `RouteCallback<T> | null` - The catch-all callback, or `null`
+
+**Example:**
+
+```ts
+const fallback = router.catchAll;
+if (fallback) {
+  const result = fallback(null, "*"); // fire it manually
+}
+```
+
 ### Methods
 
 #### `on()`
@@ -172,7 +191,7 @@ router.on("*", () => NotFoundPage);
 #### `exec()`
 
 ```ts
-exec(url: string, fallbackFn?: RouteCallback<T>): T | false
+exec(url: string, fallbackFn?: RouteCallback<T>, options?: { skipCatchAll?: boolean }): T | false
 ```
 
 Executes pattern matching against the provided string.
@@ -183,15 +202,18 @@ Executes pattern matching against the provided string.
 |------|------|-------------|
 | `url` | `string` | String to match against registered patterns |
 | `fallbackFn` | `RouteCallback<T>` | Optional fallback function if no route matches |
+| `options` | `{ skipCatchAll?: boolean }` | Optional. Set `skipCatchAll: true` to match only real routes and return `false` on a miss instead of firing the registered `*` catch-all. An explicit `fallbackFn` is unaffected. |
 
 **Returns:** `T | false` - The value returned by the matched callback (type `T`), or `false` if no match and no catch-all/fallback.
 
 **Match Priority:**
 1. First registered matching route
 2. Fallback function (if provided)
-3. Catch-all `"*"` route (if registered)
+3. Catch-all `"*"` route (if registered, unless `skipCatchAll: true`)
 4. Returns `false`
 
+When `skipCatchAll` turns a would-be catch-all into a miss, `current` and subscribers receive the same `{ route: null, params: null, label: null }` "no match" state as a true miss.
+
 **Example:**
 
 ```ts
@@ -210,6 +232,9 @@ router.exec("/unknown", (params, route) => {
 // Return values from callbacks
 const component = router.exec("/home");
 render(component);
+
+// Skip the internal catch-all (e.g. when fanning a lookup across multiple routers)
+router.exec("/unknown", undefined, { skipCatchAll: true }); // => false, even if "*" is registered
 ```
 
 ---

package/README.md

@@ -187,7 +187,7 @@ router.on("/raw", (params) => RawPage, { allowQueryParams: false });
 
 **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?)`
+##### `exec(url, fallbackFn?, options?)`
 
 Execute route matching against a URL.
 
@@ -199,10 +199,15 @@ router.exec("/unknown", () => console.log("Not found"));
 
 // With query params
 router.exec("/search?q=hello");
+
+// Skip the internal "*" catch-all: returns false on a miss even if "*" is registered
+router.exec("/unknown", undefined, { skipCatchAll: true });
 ```
 
 Returns the value returned by the matched callback, or `false` if no match.
 
+The optional `{ skipCatchAll: true }` flag matches **only real routes** and returns `false` on a miss, instead of falling back to the registered `*` catch-all. An explicitly passed `fallbackFn` is unaffected. This is useful when fanning a single lookup across multiple routers ("try real routes in A, then B, … and fire a catch-all only if none matched") — see the [`catchAll`](#catchall) getter for firing the deferred catch-all yourself.
+
 ##### `subscribe(callback)`
 
 Subscribe to router state changes. Follows the [Svelte store contract](https://svelte.dev/docs#Store_contract).
@@ -249,6 +254,15 @@ console.log(router.current);
 // { route: "/user/[id]", params: { id: "123" }, label: null }
 ```
 
+##### `catchAll`
+
+Gets the registered catch-all (`*`) callback, or `null` if none was registered (readonly). Does **not** execute it — this lets you fire the catch-all as a deliberate final step (e.g. after a multi-router `exec(url, undefined, { skipCatchAll: true })` pass) without re-scanning routes.
+
+```ts
+const fallback = router.catchAll;
+if (fallback) fallback(null, "*");
+```
+
 ##### `static debug`
 
 Enable/disable debug logging. When enabled, uses the logger instance (if provided) or falls back to `console.log`.

package/dist/router.d.ts

@@ -213,6 +213,13 @@ export declare class SimpleRouter<T = unknown> {
      * ```
      */
     get current(): RouterCurrent;
+    /**
+     * The registered catch-all (`*`) callback, or `null` if none was registered.
+     * Does NOT execute it — lets a consumer fire the catch-all as a deliberate
+     * final step (e.g. after `exec(url, undefined, { skipCatchAll: true })`)
+     * without re-scanning the registered routes.
+     */
+    get catchAll(): RouteCallback<T> | null;
     /**
      * Registers one or more route patterns with a callback.
      * Routes are matched in the order they are registered (first match wins).
@@ -251,6 +258,11 @@ export declare class SimpleRouter<T = unknown> {
      *
      * @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
+     * @param options - Optional execution options. Set `skipCatchAll: true` to match
+     *                   only real routes and return `false` on a miss instead of falling
+     *                   back to the registered `*` catch-all. An explicitly passed
+     *                   `fallbackFn` is unaffected. Useful when fanning a single lookup
+     *                   across multiple routers and deferring the catch-all decision.
      * @returns `T | false` - The value returned by the matched callback, or `false` if no match
      *
      * @example
@@ -265,6 +277,9 @@ export declare class SimpleRouter<T = unknown> {
      * // With fallback
      * router.exec("/unknown", () => NotFoundPage);
      *
+     * // Skip the internal catch-all: a miss returns false even if "*" is registered
+     * router.exec("/unknown", undefined, { skipCatchAll: true });
+     *
      * // Check for no match
      * const component = router.exec("/path");
      * if (component !== false) {
@@ -272,7 +287,9 @@ export declare class SimpleRouter<T = unknown> {
      * }
      * ```
      */
-    exec(url: string, fallbackFn?: RouteCallback<T>): T | false;
+    exec(url: string, fallbackFn?: RouteCallback<T>, options?: {
+        skipCatchAll?: boolean;
+    }): T | false;
     /**
      * Subscribes to router state changes.
      * Follows the Svelte store contract - subscriber is called immediately with current state.

package/dist/router.js

@@ -150,6 +150,15 @@ export class SimpleRouter {
     get current() {
         return this.#current;
     }
+    /**
+     * The registered catch-all (`*`) callback, or `null` if none was registered.
+     * Does NOT execute it — lets a consumer fire the catch-all as a deliberate
+     * final step (e.g. after `exec(url, undefined, { skipCatchAll: true })`)
+     * without re-scanning the registered routes.
+     */
+    get catchAll() {
+        return this.#catchAll;
+    }
     /**
      * Registers one or more route patterns with a callback.
      * Routes are matched in the order they are registered (first match wins).
@@ -234,6 +243,11 @@ export class SimpleRouter {
      *
      * @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
+     * @param options - Optional execution options. Set `skipCatchAll: true` to match
+     *                   only real routes and return `false` on a miss instead of falling
+     *                   back to the registered `*` catch-all. An explicitly passed
+     *                   `fallbackFn` is unaffected. Useful when fanning a single lookup
+     *                   across multiple routers and deferring the catch-all decision.
      * @returns `T | false` - The value returned by the matched callback, or `false` if no match
      *
      * @example
@@ -248,6 +262,9 @@ export class SimpleRouter {
      * // With fallback
      * router.exec("/unknown", () => NotFoundPage);
      *
+     * // Skip the internal catch-all: a miss returns false even if "*" is registered
+     * router.exec("/unknown", undefined, { skipCatchAll: true });
+     *
      * // Check for no match
      * const component = router.exec("/path");
      * if (component !== false) {
@@ -255,7 +272,7 @@ export class SimpleRouter {
      * }
      * ```
      */
-    exec(url, fallbackFn) {
+    exec(url, fallbackFn, options) {
         const dbgPrefix = `'${url}' -> `;
         for (const [route, cb, allowQueryParams, label] of this.#routes) {
             // First match wins
@@ -272,7 +289,7 @@ export class SimpleRouter {
             this.#dbg(`${dbgPrefix}fallback...`);
             return fallbackFn(null, "");
         }
-        if (typeof this.#catchAll === "function") {
+        if (!options?.skipCatchAll && typeof this.#catchAll === "function") {
             this.#publishCurrent("*", null, null);
             this.#dbg(`${dbgPrefix}catchall...`);
             return this.#catchAll(null, "*");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/simple-router",
-	"version": "3.3.0",
+	"version": "3.4.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",