@marianmeres/simple-router 2.2.3 → 3.0.1

package/README.md

@@ -1,5 +1,8 @@
 # @marianmeres/simple-router
 
+[![NPM version](https://img.shields.io/npm/v/@marianmeres/simple-router)](https://www.npmjs.com/package/@marianmeres/simple-router)
+[![JSR version](https://jsr.io/badges/@marianmeres/simple-router)](https://jsr.io/@marianmeres/simple-router)
+
 A lightweight, framework-agnostic string pattern matcher and router with support for dynamic parameters, wildcards, query strings, and reactive subscriptions.
 
 Can match any string identifiers - URLs, file paths, command names, or custom patterns. Originally inspired by [Sapper-like regex routes](https://sapper.svelte.dev/docs#Regexes_in_routes). Primarily designed for client-side SPA routing, but flexible enough for any pattern matching needs.
@@ -100,15 +103,30 @@ The default separator is `/`. Multiple separators are normalized to single, and
 
 ## API Reference
 
+For the complete API documentation with all methods, types, and detailed examples, see [API.md](API.md).
+
 ### SimpleRouter
 
 #### Constructor
 
 ```ts
-const router = new SimpleRouter(config?);
+// Simple config (backwards compatible)
+const router = new SimpleRouter({
+	"/": () => HomePage,
+	"/about": () => AboutPage
+});
+
+// With options object (for logger support)
+const router = new SimpleRouter({
+	routes: {
+		"/": () => HomePage,
+		"/about": () => AboutPage
+	},
+	logger: myLogger // optional, compatible with @marianmeres/clog
+});
 ```
 
-- `config` - Optional object mapping route patterns to callbacks
+- `config` - Either a `RouterConfig` object mapping route patterns to callbacks, or a `RouterOptions` object with `routes` and `logger` properties
 
 #### Methods
 
@@ -162,7 +180,7 @@ Returns the value returned by the matched callback, or `false` if no match.
 Subscribe to router state changes. Follows the [Svelte store contract](https://svelte.dev/docs#Store_contract).
 
 ```ts
-const { unsubscribe } = router.subscribe((state) => {
+const unsubscribe = router.subscribe((state) => {
 	console.log("Route:", state.route);
 	console.log("Params:", state.params);
 	console.log("Label:", state.label);
@@ -172,7 +190,7 @@ const { unsubscribe } = router.subscribe((state) => {
 unsubscribe();
 ```
 
-The callback is called immediately with the current state, then on every route change.
+Returns an unsubscribe function directly. The callback is called immediately with the current state, then on every route change.
 
 ##### `reset()`
 
@@ -205,11 +223,11 @@ console.log(router.current);
 
 ##### `static debug`
 
-Enable/disable debug logging.
+Enable/disable debug logging. When enabled, uses the logger instance (if provided) or falls back to `console.log`.
 
 ```ts
 SimpleRouter.debug = true;
-router.exec("/test"); // Logs matching details to console
+router.exec("/test"); // Logs matching details to console (or custom logger)
 ```
 
 ### SimpleRoute
@@ -241,13 +259,15 @@ Full TypeScript support with exported types:
 
 ```ts
 import type {
+	Logger,
 	RouteParams,
 	RouteCallback,
 	RouterConfig,
 	RouterCurrent,
 	RouterOnOptions,
+	RouterOptions,
 	RouterSubscriber,
-	RouterSubscription,
+	RouterUnsubscribe,
 } from "@marianmeres/simple-router";
 ```
 
@@ -346,15 +366,4 @@ dotRouter.exec("app.settings.profile");
 ```
 
 
-## Links
-
-- [Tests](tests/) - Comprehensive test suite with 82+ tests
-- [GitHub Repository](https://github.com/marianmeres/simple-router)
-- [JSR Package](https://jsr.io/@marianmeres/simple-router)
-
-## Package Identity
 
-- **Name:** @marianmeres/simple-router
-- **Author:** Marian Meres
-- **Repository:** https://github.com/marianmeres/simple-router
-- **License:** MIT

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 { RouteCallback, RouterConfig, RouterCurrent, RouterOnOptions, RouterSubscriber, RouterSubscription, } from "./router.js";
+export type { Logger, RouteCallback, RouterConfig, RouterCurrent, RouterOnOptions, RouterOptions, RouterSubscriber, RouterUnsubscribe, } from "./router.js";

package/dist/route.d.ts

@@ -16,9 +16,15 @@ export type RouteParams = Record<string, any>;
 export declare class SimpleRoute {
     #private;
     readonly route: string;
-    /** Separator used to split URL paths into segments */
+    /**
+     * Separator used to split paths into segments.
+     * @default "/"
+     */
     static SPLITTER: string;
-    /** Wildcard symbol for catch-all routes */
+    /**
+     * Wildcard symbol for catch-all routes. Must be used as the last segment.
+     * @default "*"
+     */
     static WILDCARD: string;
     /**
      * Creates a new SimpleRoute instance.

package/dist/route.js

@@ -1,8 +1,14 @@
 export class SimpleRoute {
     route;
-    /** Separator used to split URL paths into segments */
+    /**
+     * Separator used to split paths into segments.
+     * @default "/"
+     */
     static SPLITTER = "/";
-    /** Wildcard symbol for catch-all routes */
+    /**
+     * Wildcard symbol for catch-all routes. Must be used as the last segment.
+     * @default "*"
+     */
     static WILDCARD = "*";
     #parsed;
     /**

package/dist/router.d.ts

@@ -61,13 +61,33 @@ export interface RouterOnOptions {
  */
 export type RouterConfig = Record<string, RouteCallback>;
 /**
- * Subscription object returned by the `subscribe()` method.
- * Follows the Svelte store contract and RxJS Observable interface.
+ * Logger interface compatible with `@marianmeres/clog`.
+ * Provides console-compatible logging methods.
  */
-export interface RouterSubscription {
-    /** Unsubscribe from router state changes */
-    unsubscribe: () => void;
+export interface Logger {
+    /** Log debug level messages */
+    debug: (...args: unknown[]) => unknown;
+    /** Log info level messages */
+    log: (...args: unknown[]) => unknown;
+    /** Log warning level messages */
+    warn: (...args: unknown[]) => unknown;
+    /** Log error level messages */
+    error: (...args: unknown[]) => unknown;
 }
+/**
+ * Options for the SimpleRouter factory/constructor.
+ */
+export interface RouterOptions {
+    /** Route configuration mapping patterns to callbacks */
+    routes?: RouterConfig | null;
+    /** Optional logger instance for debug output (compatible with @marianmeres/clog) */
+    logger?: Logger | null;
+}
+/**
+ * Unsubscribe function returned by the `subscribe()` method.
+ * Follows the Svelte store contract.
+ */
+export type RouterUnsubscribe = () => void;
 /**
  * Subscriber callback function that receives router state changes.
  *
@@ -106,22 +126,37 @@ export type RouterSubscriber = (current: RouterCurrent) => void;
  */
 export declare class SimpleRouter {
     #private;
-    /** Enable/disable console debug logging for route matching */
+    /**
+     * Enable/disable console debug logging for route matching.
+     * When enabled, logs route matching details to the console.
+     * @default false
+     */
     static debug: boolean;
     /**
      * Creates a new SimpleRouter instance.
      *
-     * @param config - Optional configuration object mapping route patterns to callbacks
+     * @param config - Optional configuration: either a RouterConfig object mapping route patterns
+     *                 to callbacks, or a RouterOptions object with routes and logger
      *
      * @example
      * ```ts
+     * // Simple config (backwards compatible)
      * const router = new SimpleRouter({
      *   "/": () => HomePage,
      *   "/about": () => AboutPage
      * });
+     *
+     * // With options object
+     * const router = new SimpleRouter({
+     *   routes: {
+     *     "/": () => HomePage,
+     *     "/about": () => AboutPage
+     *   },
+     *   logger: myLogger // optional, compatible with @marianmeres/clog
+     * });
      * ```
      */
-    constructor(config?: RouterConfig | null);
+    constructor(config?: RouterConfig | RouterOptions | null);
     /**
      * Returns a map of registered route patterns to their labels.
      * Useful for debugging and introspection.
@@ -189,7 +224,7 @@ export declare class SimpleRouter {
      * router.on("*", () => NotFoundPage);
      * ```
      */
-    on(routes: string | string[], cb: RouteCallback, { label, allowQueryParams }?: RouterOnOptions): void;
+    on(routes: string | string[], cb: RouteCallback, options?: RouterOnOptions): void;
     /**
      * Executes pattern matching against the provided string.
      * Returns the value returned by the matched route's callback.
@@ -220,18 +255,17 @@ export declare class SimpleRouter {
      * const component = router.exec("/home");
      * ```
      */
-    exec(url: string, fallbackFn?: RouteCallback): any;
+    exec(url: string, fallbackFn?: RouteCallback): unknown;
     /**
      * Subscribes to router state changes.
      * Follows the Svelte store contract - subscriber is called immediately with current state.
-     * Compatible with RxJS Observables (returns object with `unsubscribe` method).
      *
      * @param subscription - Callback function that receives router state changes
-     * @returns Subscription object with `unsubscribe()` method
+     * @returns Unsubscribe function
      *
      * @example
      * ```ts
-     * const { unsubscribe } = router.subscribe((state) => {
+     * const unsubscribe = router.subscribe((state) => {
      *   console.log("Route changed:", state.route);
      *   console.log("Params:", state.params);
      * });
@@ -242,5 +276,5 @@ export declare class SimpleRouter {
      *
      * @see https://svelte.dev/docs#Store_contract
      */
-    subscribe(subscription: RouterSubscriber): RouterSubscription;
+    subscribe(subscription: RouterSubscriber): RouterUnsubscribe;
 }

package/dist/router.js

@@ -32,7 +32,11 @@ const PUBSUB_TOPIC = "current";
  * ```
  */
 export class SimpleRouter {
-    /** Enable/disable console debug logging for route matching */
+    /**
+     * Enable/disable console debug logging for route matching.
+     * When enabled, logs route matching details to the console.
+     * @default false
+     */
     static debug = false;
     #routes = [];
     #catchAll = null;
@@ -42,26 +46,58 @@ export class SimpleRouter {
         label: null,
     };
     #pubsub = createPubSub();
+    #logger = null;
     /**
      * Creates a new SimpleRouter instance.
      *
-     * @param config - Optional configuration object mapping route patterns to callbacks
+     * @param config - Optional configuration: either a RouterConfig object mapping route patterns
+     *                 to callbacks, or a RouterOptions object with routes and logger
      *
      * @example
      * ```ts
+     * // Simple config (backwards compatible)
      * const router = new SimpleRouter({
      *   "/": () => HomePage,
      *   "/about": () => AboutPage
      * });
+     *
+     * // With options object
+     * const router = new SimpleRouter({
+     *   routes: {
+     *     "/": () => HomePage,
+     *     "/about": () => AboutPage
+     *   },
+     *   logger: myLogger // optional, compatible with @marianmeres/clog
+     * });
      * ```
      */
     constructor(config = null) {
-        Object.entries(config || {}).forEach(([route, cb]) => {
+        let routes = null;
+        if (config) {
+            // Check if config is RouterOptions (has 'routes' or 'logger' key)
+            if ("routes" in config || "logger" in config) {
+                const options = config;
+                routes = options.routes ?? null;
+                this.#logger = options.logger ?? null;
+            }
+            else {
+                // Backwards compatible: treat as RouterConfig
+                routes = config;
+            }
+        }
+        Object.entries(routes || {}).forEach(([route, cb]) => {
             this.on(route, cb);
         });
     }
     #dbg(...a) {
-        SimpleRouter.debug && console.log("[SimpleRouter]", ...a);
+        if (SimpleRouter.debug) {
+            if (this.#logger) {
+                this.#logger.log("[SimpleRouter]", ...a);
+            }
+            else {
+                console.log("[SimpleRouter]", ...a);
+            }
+        }
     }
     /**
      * Returns a map of registered route patterns to their labels.
@@ -140,7 +176,8 @@ export class SimpleRouter {
      * router.on("*", () => NotFoundPage);
      * ```
      */
-    on(routes, cb, { label = null, allowQueryParams = true } = {}) {
+    on(routes, cb, options = {}) {
+        const { label = null, allowQueryParams = true } = options;
         if (!Array.isArray(routes))
             routes = [routes];
         routes.forEach((route) => {
@@ -187,7 +224,6 @@ export class SimpleRouter {
      * const component = router.exec("/home");
      * ```
      */
-    // deno-lint-ignore no-explicit-any
     exec(url, fallbackFn) {
         const dbgPrefix = `'${url}' -> `;
         for (const [route, cb, allowQueryParams, label] of this.#routes) {
@@ -221,14 +257,13 @@ export class SimpleRouter {
     /**
      * Subscribes to router state changes.
      * Follows the Svelte store contract - subscriber is called immediately with current state.
-     * Compatible with RxJS Observables (returns object with `unsubscribe` method).
      *
      * @param subscription - Callback function that receives router state changes
-     * @returns Subscription object with `unsubscribe()` method
+     * @returns Unsubscribe function
      *
      * @example
      * ```ts
-     * const { unsubscribe } = router.subscribe((state) => {
+     * const unsubscribe = router.subscribe((state) => {
      *   console.log("Route changed:", state.route);
      *   console.log("Params:", state.params);
      * });
@@ -246,10 +281,6 @@ export class SimpleRouter {
         const unsubscribe = this.#pubsub.subscribe(PUBSUB_TOPIC, subscription);
         // immediately call with current value (as per store contract)
         subscription(this.#current);
-        // For interoperability with RxJS Observables, the .subscribe method is also
-        // allowed to return an object with an .unsubscribe method
-        return {
-            unsubscribe,
-        };
+        return unsubscribe;
     }
 }

package/package.json

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