@marianmeres/simple-router 2.1.0 → 2.2.3

package/dist/router.js

@@ -0,0 +1,255 @@
+import { SimpleRoute } from "./route.js";
+import { createPubSub } from "@marianmeres/pubsub";
+const PUBSUB_TOPIC = "current";
+/**
+ * A simple, 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.
+ * Primarily designed for client-side SPA routing, but flexible enough for any pattern
+ * matching needs.
+ *
+ * @example
+ * ```ts
+ * import { SimpleRouter } from "@marianmeres/simple-router";
+ *
+ * // URL routing
+ * const router = new SimpleRouter({
+ *   "/": () => console.log("Home"),
+ *   "/user/[id]": (params) => console.log("User:", params?.id),
+ *   "*": () => console.log("Not found")
+ * });
+ *
+ * router.exec("/user/123"); // Logs: "User: 123"
+ *
+ * // Command routing
+ * const cmdRouter = new SimpleRouter({
+ *   "user:create": () => createUser(),
+ *   "user:delete:[id]": ({ id }) => deleteUser(id),
+ * });
+ *
+ * cmdRouter.exec("user:delete:123");
+ * ```
+ */
+export class SimpleRouter {
+    /** Enable/disable console debug logging for route matching */
+    static debug = false;
+    #routes = [];
+    #catchAll = null;
+    #current = {
+        route: null,
+        params: null,
+        label: null,
+    };
+    #pubsub = createPubSub();
+    /**
+     * Creates a new SimpleRouter instance.
+     *
+     * @param config - Optional configuration object mapping route patterns to callbacks
+     *
+     * @example
+     * ```ts
+     * const router = new SimpleRouter({
+     *   "/": () => HomePage,
+     *   "/about": () => AboutPage
+     * });
+     * ```
+     */
+    constructor(config = null) {
+        Object.entries(config || {}).forEach(([route, cb]) => {
+            this.on(route, cb);
+        });
+    }
+    #dbg(...a) {
+        SimpleRouter.debug && console.log("[SimpleRouter]", ...a);
+    }
+    /**
+     * Returns a map of registered route patterns to their labels.
+     * Useful for debugging and introspection.
+     *
+     * @returns Object mapping route patterns to labels
+     *
+     * @example
+     * ```ts
+     * router.on("/users", () => {}, { label: "users-list" });
+     * console.log(router.info()); // { "/users": "users-list" }
+     * ```
+     */
+    info() {
+        return this.#routes.reduce((m, r) => {
+            m[r[0].route] = r[3] || "";
+            return m;
+        }, {});
+    }
+    /**
+     * Clears all registered routes (except catch-all).
+     * Useful for testing or dynamic route reconfiguration.
+     *
+     * @returns The router instance for method chaining
+     *
+     * @example
+     * ```ts
+     * router.reset().on("/new-route", () => {});
+     * ```
+     */
+    reset() {
+        this.#routes = [];
+        return this;
+    }
+    /**
+     * Gets the current router state (last matched route and params).
+     *
+     * @returns Current router state
+     *
+     * @example
+     * ```ts
+     * router.exec("/user/123");
+     * console.log(router.current); // { route: "/user/[id]", params: { id: "123" }, label: null }
+     * ```
+     */
+    get current() {
+        return this.#current;
+    }
+    /**
+     * Registers one or more route patterns with a callback.
+     * Routes are matched in the order they are registered (first match wins).
+     * Use "*" as a catch-all route.
+     *
+     * @param routes - Single route pattern or array of patterns
+     * @param cb - Callback function to execute when route matches
+     * @param options - Optional configuration (label, allowQueryParams)
+     *
+     * @example
+     * ```ts
+     * // Single route
+     * router.on("/users", () => UsersPage);
+     *
+     * // Multiple routes to same handler
+     * router.on(["/", "/home", "/index.html"], () => HomePage);
+     *
+     * // With dynamic parameters
+     * router.on("/user/[id]", (params) => UserPage(params?.id));
+     *
+     * // With regex constraint
+     * router.on("/post/[id([0-9]+)]", (params) => PostPage(params?.id));
+     *
+     * // With label for debugging
+     * router.on("/admin", () => AdminPage, { label: "admin-dashboard" });
+     *
+     * // Catch-all route
+     * router.on("*", () => NotFoundPage);
+     * ```
+     */
+    on(routes, cb, { label = null, allowQueryParams = true } = {}) {
+        if (!Array.isArray(routes))
+            routes = [routes];
+        routes.forEach((route) => {
+            if (route === "*") {
+                this.#catchAll = cb;
+            }
+            else {
+                this.#routes.push([
+                    new SimpleRoute(route),
+                    cb,
+                    allowQueryParams,
+                    label,
+                ]);
+            }
+        });
+    }
+    /**
+     * Executes pattern matching against the provided string.
+     * Returns the value returned by the matched route's callback.
+     * 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
+     *
+     * @example
+     * ```ts
+     * // URL matching
+     * router.exec("/users"); // Returns result of callback
+     *
+     * // 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"));
+     *
+     * // Can return components, values, etc.
+     * 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) {
+            // First match wins
+            // Parse returns null or a params object (which can be empty)
+            const params = route.parse(url, allowQueryParams);
+            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;
+            }
+        }
+        if (typeof fallbackFn === "function") {
+            this.#publishCurrent(null, null, null);
+            this.#dbg(`${dbgPrefix}fallback...`);
+            return fallbackFn(null, "");
+        }
+        if (typeof this.#catchAll === "function") {
+            this.#publishCurrent("*", null, null);
+            this.#dbg(`${dbgPrefix}catchall...`);
+            return this.#catchAll(null, "*");
+        }
+        this.#publishCurrent(null, null, null);
+        this.#dbg(`${dbgPrefix}no match...`);
+        return false;
+    }
+    #publishCurrent(route, params, label) {
+        this.#current = { route, params, label };
+        this.#pubsub.publish(PUBSUB_TOPIC, this.#current);
+    }
+    /**
+     * 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
+     *
+     * @example
+     * ```ts
+     * const { unsubscribe } = router.subscribe((state) => {
+     *   console.log("Route changed:", state.route);
+     *   console.log("Params:", state.params);
+     * });
+     *
+     * // Later, to unsubscribe
+     * unsubscribe();
+     * ```
+     *
+     * @see https://svelte.dev/docs#Store_contract
+     */
+    subscribe(subscription) {
+        if (typeof subscription !== "function") {
+            throw new TypeError("Subscription is not a function");
+        }
+        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,
+        };
+    }
+}

package/package.json

@@ -1,51 +1,20 @@
 {
 	"name": "@marianmeres/simple-router",
-	"version": "2.1.0",
-	"description": "Minimalistic route parser for sapper-like regex routes",
+	"version": "2.2.3",
 	"type": "module",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"exports": {
-		"require": "./dist/index.cjs",
-		"import": "./dist/index.js"
-	},
-	"types": "./dist/index.d.ts",
-	"files": [
-		"dist"
-	],
-	"scripts": {
-		"clean": "rimraf dist/*",
-		"build": "npm run clean && rollup -c",
-		"dev": "npm run clean && rollup -c -w",
-		"prettier": "prettier --write \"{src,tests,examples}/**/*.{js,ts,json}\"",
-		"release": "release -v minor",
-		"release:patch": "release -v patch",
-		"test": "test-runner",
-		"test:watch": "nodemon -q -w dist -w tests -x test-runner --"
-	},
+	"main": "dist/mod.js",
+	"types": "dist/mod.d.ts",
+	"author": "Marian Meres",
+	"license": "MIT",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/marianmeres/simple-router.git"
 	},
-	"keywords": [
-		"router"
-	],
-	"author": "Marian Meres <marian@meres.sk>",
-	"license": "WTFPL",
 	"bugs": {
 		"url": "https://github.com/marianmeres/simple-router/issues"
 	},
-	"homepage": "https://github.com/marianmeres/simple-router#readme",
-	"devDependencies": {
-		"@marianmeres/release": "^1.1.2",
-		"@marianmeres/test-runner": "^2.0.8",
-		"@rollup/plugin-typescript": "^9.0.2",
-		"@types/node": "^14.18.33",
-		"lodash": "^4.17.21",
-		"prettier": "^2.2.1",
-		"rimraf": "^3.0.2",
-		"rollup": "^3.3.0",
-		"tslib": "^2.4.1",
-		"typescript": "^4.8.4"
+	"dependencies": {
+		"@marianmeres/pubsub": "^2.2.0",
+		"@marianmeres/clog": "^2.3.3"
 	}
-}
+}

package/dist/index.cjs

@@ -1,251 +0,0 @@
-'use strict';
-
-class SimpleRoute {
-    route;
-    static SPLITTER = '/';
-    static WILDCARD = '*';
-    _parsed;
-    constructor(route) {
-        this.route = route;
-        this._parsed = SimpleRoute._parse(route);
-    }
-    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
-    static _escapeRegExp(str) {
-        return str.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&');
-    }
-    static _sanitizeAndSplit(str) {
-        const s = SimpleRoute._escapeRegExp(SimpleRoute.SPLITTER);
-        return (`${str}`
-            .trim()
-            // splitter trim left and right
-            .replace(new RegExp(`^(${s})+`), '')
-            .replace(new RegExp(`(${s})+$`), '')
-            .split(SimpleRoute.SPLITTER)
-            // remove empty segments... will "normalize" multiple splitters into one
-            .filter(Boolean));
-    }
-    static _parse(route) {
-        let wasSpread = false;
-        let wasWildcard = false;
-        return SimpleRoute._sanitizeAndSplit(route).reduce((memo, segment, idx, all) => {
-            let name = null;
-            // if optional, remove trailing '?' marker
-            let isOptional = segment.endsWith('?');
-            if (isOptional)
-                segment = segment.slice(0, -1);
-            let isSpread = segment.startsWith('[...');
-            if (isSpread) {
-                if (isOptional) {
-                    throw new Error('Spread segment must not be marked as optional');
-                }
-                if (wasSpread) {
-                    throw new Error('Multiple spread segments are invalid');
-                }
-                wasSpread = true;
-                segment = '[' + segment.slice(4);
-            }
-            let test = new RegExp('^' + SimpleRoute._escapeRegExp(segment) + '$');
-            // catch all wildcard
-            if (segment === SimpleRoute.WILDCARD) {
-                if (idx < all.length - 1) {
-                    throw new Error(`Wildcard '${SimpleRoute.WILDCARD}' can be used only as a last segment`);
-                }
-                wasWildcard = true;
-            }
-            else {
-                // starting with at least one word char within brackets...
-                let m = segment.match(/^\[(\w.*)]$/);
-                if (m) {
-                    name = m[1];
-                    test = /.+/;
-                    // id([0-9]+)
-                    let m2 = m[1].match(/^(\w.*)\((.+)\)$/);
-                    if (m2) {
-                        name = m2[1];
-                        test = new RegExp('^' + m2[2] + '$');
-                    }
-                }
-            }
-            if (wasWildcard) {
-                isOptional = true;
-                test = /.*/;
-            }
-            memo.push({ segment, name, test, isOptional, isSpread });
-            return memo;
-        }, []);
-    }
-    static parseQueryString(str) {
-        return `${str}`
-            .replace(/^&/, '')
-            .replace(/&$/, '')
-            .split('&')
-            .reduce((memo, kvpair) => {
-            const [k, v] = kvpair.split('=').map(decodeURIComponent);
-            if (k.length)
-                memo[k] = v;
-            return memo;
-        }, {});
-    }
-    parse(url, allowQueryParams = true) {
-        let matched = {};
-        const qPos = url.indexOf('?');
-        if (allowQueryParams && ~qPos) {
-            const _backup = url;
-            url = _backup.slice(0, qPos);
-            matched = SimpleRoute.parseQueryString(_backup.slice(qPos + 1));
-        }
-        let segments = SimpleRoute._sanitizeAndSplit(url);
-        // SPREAD PARAMS DANCING BLOCK - if there are "spread" definitions we need to adjust input
-        // that is "group" (join) segments that were initially splitted
-        const hasSpread = !!this._parsed.filter((v) => v.isSpread).length;
-        if (hasSpread) {
-            let newSegments = [];
-            this._parsed.forEach((p, i) => {
-                if (p.isSpread) {
-                    // there are defined segments after the "spread" definition
-                    if (this._parsed[i + 1]) {
-                        // SimpleRoute
-                        newSegments.push(segments.slice(0, this._parsed.length - i).join(SimpleRoute.SPLITTER));
-                        segments = segments.slice(this._parsed.length - i);
-                    }
-                    // there are no more defined segments
-                    else {
-                        newSegments.push(segments.join(SimpleRoute.SPLITTER));
-                    }
-                }
-                else {
-                    newSegments = newSegments.concat(segments.slice(0, 1));
-                    segments = segments.slice(1);
-                }
-            });
-            segments = newSegments;
-        }
-        // return early no-op special case: first segment is a wildcard
-        // (no need to process further)
-        if (this._parsed?.[0]?.segment === SimpleRoute.WILDCARD) {
-            return matched;
-        }
-        // minimum required (not optional) segments length
-        const reqLen = this._parsed.reduce((memo, p, idx, arr) => {
-            const next = arr[idx + 1];
-            // if is not optional or has not optional still to come
-            if (!p.isOptional || (next && !next.isOptional)) {
-                memo++;
-            }
-            return memo;
-        }, 0);
-        // quick cheap check: if counts dont match = no match
-        if (segments.length < reqLen) {
-            return null;
-        }
-        for (const [i, s] of segments.entries()) {
-            const p = this._parsed[i];
-            if (!p || !p.test.test(s)) {
-                return null;
-            }
-            if (p.name) {
-                matched[decodeURIComponent(p.name)] = decodeURIComponent(s);
-            }
-            if (p.segment === SimpleRoute.WILDCARD) {
-                break;
-            }
-        }
-        return matched;
-    }
-}
-
-class SimpleRouter {
-    // console log debug on/off switch
-    static debug = false;
-    _routes = [];
-    _catchAll;
-    // current (last matched) route and params (in the shape { route: "...", params: {} } )
-    _current = {
-        route: null,
-        params: null,
-        label: null,
-    };
-    // https://svelte.dev/docs#Store_contract
-    _subscriptions = new Set();
-    constructor(config = null) {
-        Object.entries(config || {}).forEach(([route, cb]) => {
-            this.on(route, cb);
-        });
-    }
-    _dbg(...a) {
-        SimpleRouter.debug && console.log('[SimpleRouter]', ...a);
-    }
-    /** Will report map of registered routes and their labels. Intended for debugging. */
-    info() {
-        return this._routes.reduce((m, r) => {
-            m[r[0].route] = r[3];
-            return m;
-        }, {});
-    }
-    reset() {
-        this._routes = [];
-        return this;
-    }
-    get current() {
-        return this._current;
-    }
-    on(routes, cb, { label = null, allowQueryParams = true } = {}) {
-        if (!Array.isArray(routes))
-            routes = [routes];
-        routes.forEach((route) => {
-            if (route === '*') {
-                this._catchAll = cb;
-            }
-            else {
-                this._routes.push([new SimpleRoute(route), cb, allowQueryParams, label]);
-            }
-        });
-    }
-    exec(url, fallbackFn) {
-        const dbgPrefix = `'${url}' -> `;
-        const isFn = (v) => typeof v === 'function';
-        for (const [route, cb, allowQueryParams, label] of this._routes) {
-            // first match wins
-            // parse returns null or params object (which can be empty)
-            const params = route.parse(url, allowQueryParams);
-            if (params) {
-                this._publishCurrent(route.route, params, label);
-                this._dbg(`${dbgPrefix}matches '${route.route}' with`, params);
-                return isFn(cb) ? cb(params, route.route) : true;
-            }
-        }
-        if (isFn(fallbackFn)) {
-            this._publishCurrent(null, null, null);
-            this._dbg(`${dbgPrefix}fallback...`);
-            return fallbackFn();
-        }
-        if (isFn(this._catchAll)) {
-            this._publishCurrent('*', null, null);
-            this._dbg(`${dbgPrefix}catchall...`);
-            return this._catchAll(null, '*');
-        }
-        this._publishCurrent(null, null, null);
-        this._dbg(`${dbgPrefix}no match...`);
-        return false;
-    }
-    _publishCurrent(route, params, label) {
-        this._current = { route, params, label };
-        this._subscriptions.forEach((cb) => cb(this._current));
-    }
-    // https://svelte.dev/docs#Store_contract
-    subscribe(subscription) {
-        if (typeof subscription !== 'function') {
-            throw new TypeError('Subscription is not a function');
-        }
-        this._subscriptions.add(subscription);
-        subscription(this._current);
-        // For interoperability with RxJS Observables, the .subscribe method is also
-        // allowed to return an object with an .unsubscribe method
-        return {
-            unsubscribe: () => this._subscriptions.delete(subscription),
-        };
-    }
-}
-
-exports.SimpleRoute = SimpleRoute;
-exports.SimpleRouter = SimpleRouter;

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export { SimpleRoute } from './route';
-export { SimpleRouter } from './router';