@marianmeres/simple-router 2.1.0 → 2.2.3

package/dist/route.js

@@ -0,0 +1,248 @@
+export class SimpleRoute {
+    route;
+    /** Separator used to split URL paths into segments */
+    static SPLITTER = "/";
+    /** Wildcard symbol for catch-all routes */
+    static WILDCARD = "*";
+    #parsed;
+    /**
+     * 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)
+     *
+     * @example
+     * ```ts
+     * // URL patterns
+     * new SimpleRoute("/user/[id]");
+     * new SimpleRoute("/post/[id([0-9]+)]");
+     * new SimpleRoute("/api/[...path]");
+     *
+     * // File path patterns
+     * new SimpleRoute("src/[module]/[file].ts");
+     *
+     * // Command patterns
+     * new SimpleRoute("user:delete:[id]");
+     * ```
+     */
+    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()
+            // 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));
+    }
+    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);
+            const 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 {
+                // Starts with at least one word character within brackets
+                const m = segment.match(/^\[(\w.*)]$/);
+                if (m) {
+                    name = m[1];
+                    test = /.+/;
+                    // id([0-9]+)
+                    const m2 = m[1].match(/^(\w.*)\((.+)\)$/);
+                    if (m2) {
+                        name = m2[1];
+                        try {
+                            test = new RegExp("^" + m2[2] + "$");
+                        }
+                        catch (e) {
+                            throw new Error(`Invalid regex in route pattern '${segment}': ${e.message}`);
+                        }
+                    }
+                }
+            }
+            if (wasWildcard) {
+                isOptional = true;
+                test = /.*/;
+            }
+            memo.push({ segment, name, test, isOptional, isSpread });
+            return memo;
+        }, []);
+    }
+    /**
+     * Parses a query string into an object of key-value pairs.
+     * Handles URL decoding of both keys and values.
+     *
+     * @param str - Query string (without leading "?")
+     * @returns Object with parsed query parameters
+     *
+     * @example
+     * ```ts
+     * SimpleRoute.parseQueryString("foo=bar&baz=123");
+     * // Returns: { foo: "bar", baz: "123" }
+     *
+     * SimpleRoute.parseQueryString("name=John%20Doe");
+     * // Returns: { name: "John Doe" }
+     * ```
+     */
+    static parseQueryString(str) {
+        return `${str}`
+            .replace(/^&/, "")
+            .replace(/&$/, "")
+            .split("&")
+            .reduce((memo, kvpair) => {
+            const [k, v = ""] = kvpair.split("=");
+            if (k.length) {
+                try {
+                    const decodedKey = decodeURIComponent(k);
+                    const decodedValue = v ? decodeURIComponent(v) : "";
+                    memo[decodedKey] = decodedValue;
+                }
+                catch {
+                    // Fallback for malformed URI components
+                    memo[k] = v;
+                }
+            }
+            return memo;
+        }, {});
+    }
+    /**
+     * Parses a string against this route pattern.
+     * Returns extracted parameters if the string matches, null otherwise.
+     *
+     * @param url - String to test against the pattern (can be a URL, file path, command, etc.)
+     * @param allowQueryParams - Whether to parse query string parameters (default: true)
+     * @returns Object with extracted parameters, or null if no match
+     *
+     * @example
+     * ```ts
+     * // URL matching
+     * const route = new SimpleRoute("/user/[id]");
+     *
+     * route.parse("/user/123");
+     * // Returns: { id: "123" }
+     *
+     * route.parse("/user/123?tab=profile");
+     * // Returns: { id: "123", tab: "profile" }
+     *
+     * route.parse("/user/123?tab=profile", false);
+     * // Returns: { id: "123?tab=profile" } - query string not parsed
+     *
+     * route.parse("/post/456");
+     * // Returns: null - no match
+     *
+     * // File path matching
+     * const fileRoute = new SimpleRoute("src/[module]/[file].ts");
+     * fileRoute.parse("src/components/Button.ts");
+     * // Returns: { module: "components", file: "Button" }
+     *
+     * // Command matching
+     * const cmdRoute = new SimpleRoute("user:delete:[id]");
+     * cmdRoute.parse("user:delete:123");
+     * // Returns: { id: "123" }
+     * ```
+     */
+    parse(url, allowQueryParams = true) {
+        let matched = {};
+        const qPos = url.indexOf("?");
+        if (allowQueryParams && qPos !== -1) {
+            const _backup = url;
+            url = _backup.slice(0, qPos);
+            matched = SimpleRoute.parseQueryString(_backup.slice(qPos + 1));
+        }
+        let segments = SimpleRoute.#sanitizeAndSplit(url);
+        // 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);
+        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]) {
+                        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 (special case): first segment is a wildcard
+        // (no need to process further)
+        if (this.#parsed?.[0]?.segment === SimpleRoute.WILDCARD) {
+            return matched;
+        }
+        // Minimum required (non-optional) segment count
+        const reqLen = this.#parsed.reduce((memo, p, idx, arr) => {
+            const next = arr[idx + 1];
+            // If segment is not optional or has non-optional segments still to come
+            if (!p.isOptional || (next && !next.isOptional)) {
+                memo++;
+            }
+            return memo;
+        }, 0);
+        // Quick check: if counts don't 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) {
+                try {
+                    matched[decodeURIComponent(p.name)] = decodeURIComponent(s);
+                }
+                catch {
+                    // Fallback for malformed URI components
+                    matched[p.name] = s;
+                }
+            }
+            if (p.segment === SimpleRoute.WILDCARD) {
+                break;
+            }
+        }
+        return matched;
+    }
+}

package/dist/router.d.ts

@@ -1,33 +1,246 @@
-import { SimpleRoute } from './route';
+/**
+ * Route parameters extracted from the URL path and query string.
+ * Keys are parameter names, values are the extracted string values.
+ *
+ * @example
+ * ```ts
+ * // For route "/user/[id]" matching "/user/123"
+ * const params: RouteParams = { id: "123" };
+ * ```
+ */
+export type RouteParams = Record<string, any>;
+/**
+ * Callback function executed when a route matches.
+ *
+ * @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) => {
+ *   console.log(`Matched ${route} with params:`, params);
+ *   return MyComponent;
+ * };
+ * ```
+ */
+export type RouteCallback = (params: RouteParams | null, route: string) => any;
+/**
+ * Represents the current router state including the matched route,
+ * extracted parameters, and optional label.
+ */
+export interface RouterCurrent {
+    /** The matched route pattern, "*" for catch-all, or null if no match */
+    route: string | null;
+    /** Extracted parameters from the URL, or null if no match */
+    params: RouteParams | null;
+    /** Optional label associated with the route for debugging */
+    label: string | null;
+}
+/**
+ * Options for registering routes with the `on()` method.
+ */
+export interface RouterOnOptions {
+    /** Optional label for debugging - useful for identifying routes */
+    label?: string | null;
+    /** Whether to parse query parameters (default: true) */
+    allowQueryParams?: boolean;
+}
+/**
+ * Configuration object for initializing the router with routes.
+ * Maps route patterns to their callback functions.
+ *
+ * @example
+ * ```ts
+ * const config: RouterConfig = {
+ *   "/": () => HomePage,
+ *   "/user/[id]": (params) => UserPage(params?.id),
+ *   "*": () => NotFoundPage
+ * };
+ * ```
+ */
+export type RouterConfig = Record<string, RouteCallback>;
+/**
+ * Subscription object returned by the `subscribe()` method.
+ * Follows the Svelte store contract and RxJS Observable interface.
+ */
+export interface RouterSubscription {
+    /** Unsubscribe from router state changes */
+    unsubscribe: () => void;
+}
+/**
+ * Subscriber callback function that receives router state changes.
+ *
+ * @param current - The current router state
+ */
+export type RouterSubscriber = (current: RouterCurrent) => void;
+/**
+ * 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 declare class SimpleRouter {
+    #private;
+    /** Enable/disable console debug logging for route matching */
     static debug: boolean;
-    protected _routes: [SimpleRoute, Function, boolean, string][];
-    protected _catchAll: Function;
-    protected _current: {
-        route: string;
-        params: any;
-        label: string;
-    };
-    protected _subscriptions: Set<Function>;
-    constructor(config?: {
-        [route: string]: Function;
-    });
-    protected _dbg(...a: any[]): void;
-    /** Will report map of registered routes and their labels. Intended for debugging. */
+    /**
+     * 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?: RouterConfig | null);
+    /**
+     * 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(): Record<string, string>;
+    /**
+     * 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;
-    get current(): {
-        route: string;
-        params: any;
-        label: string;
-    };
-    on(routes: string | string[], cb: Function, { label, allowQueryParams }?: {
-        label?: any;
-        allowQueryParams?: boolean;
-    }): void;
-    exec(url: string, fallbackFn?: Function): any;
-    protected _publishCurrent(route: any, params: any, label: any): void;
-    subscribe(subscription: Function): {
-        unsubscribe: () => boolean;
-    };
+    /**
+     * 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(): RouterCurrent;
+    /**
+     * 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: string | string[], cb: RouteCallback, { label, allowQueryParams }?: RouterOnOptions): void;
+    /**
+     * 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");
+     * ```
+     */
+    exec(url: string, fallbackFn?: RouteCallback): any;
+    /**
+     * 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: RouterSubscriber): RouterSubscription;
 }