@marianmeres/simple-router 2.0.1 → 2.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Marian Meres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,79 +1,360 @@
 # @marianmeres/simple-router
 
-Small path-like string parser. Originally inspired by
-[sapper-like regex routes](https://sapper.svelte.dev/docs#Regexes_in_routes).
-Intended primarily for - but not limited to - client side SPA routing.
+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.
+
+## Features
+
+- ✨ Dynamic route parameters with optional regex constraints
+- 🎯 Wildcard and catch-all routes
+- 📦 Spread parameters for multi-segment matching
+- 🔍 Query string parsing (with option to disable per route)
+- 🔄 Reactive subscriptions (Svelte store contract compatible)
+- 🪶 Zero dependencies (except `@marianmeres/pubsub` for subscriptions)
+- 📘 Full TypeScript support
+- 🎨 Framework-agnostic
 
 ## Installation
 
 ```shell
-npm i @marianmeres/simple-router
+deno add "jsr:@marianmeres/simple-router"
+```
+
+```shell
+npm install @marianmeres/simple-router
+```
+
+```ts
+import { SimpleRouter } from "@marianmeres/simple-router";
+```
+
+## Quick Example
+
+```ts
+import { SimpleRouter } from "@marianmeres/simple-router";
+
+// Routes can be defined via constructor config
+const router = new SimpleRouter({
+	"/": () => HomePage,
+	"/about": () => AboutPage,
+	"*": () => NotFoundPage, // catch-all fallback
+});
+
+// Or via the "on" API
+router.on("/user/[id([0-9]+)]", (params) => {
+	console.log("User ID:", params?.id);
+	return UserPage(params?.id);
+});
+
+router.on("/article/[id]/[slug]", ({ id, slug }) => {
+	return ArticlePage(id, slug);
+});
+
+// Execute route matching
+const component = router.exec("/user/123");
+
+// Use with hash routing
+window.onhashchange = () => {
+	const component = router.exec(location.hash.slice(1));
+	render(component);
+};
+```
+
+## Route Patterns
+
+### Basic Segments
+
+- `exact` - Matches exactly "exact"
+- `[name]` - Matches any segment, captured as `{ name: "value" }`
+- `[name(regex)]` - Matches if regex test passes
+- `[name]?` - Optional segment
+- `[...name]` - Spread params (matches multiple segments)
+- `*` - Wildcard (matches zero or more segments)
+
+### Separators
+
+The default separator is `/`. Multiple separators are normalized to single, and separators are trimmed from both ends before matching.
+
+## Pattern Examples
+
+| Route Pattern                 | URL Input          | Params Result                    |
+| ----------------------------- | ------------------ | -------------------------------- |
+| `/foo`                        | `/bar`             | `null` (no match)                |
+| `/foo`                        | (empty)            | `null`                           |
+| `/foo/[bar]`                  | `/foo`             | `null`                           |
+| `/`                           | (empty)            | `{}`                             |
+| `foo`                         | `foo`              | `{}`                             |
+| `//foo///bar.baz/`            | `foo/bar.baz`      | `{}`                             |
+| `/[foo]`                      | `/bar`             | `{ foo: "bar" }`                 |
+| `#/[foo]/[bar]`               | `#/baz/bat`        | `{ foo: "baz", bar: "bat" }`     |
+| `/[id([0-9]+)]`               | `/123`             | `{ id: "123" }`                  |
+| `/[id([0-9]+)]`               | `/foo`             | `null` (regex fails)             |
+| `/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" }`                 |
+
+## API Reference
+
+### SimpleRouter
+
+#### Constructor
+
+```ts
+const router = new SimpleRouter(config?);
+```
+
+- `config` - Optional object mapping route patterns to callbacks
+
+#### Methods
+
+##### `on(routes, callback, options?)`
+
+Register one or more route patterns with a callback.
+
+```ts
+router.on("/users", () => UsersPage);
+
+// Multiple routes to same handler
+router.on(["/", "/home", "/index.html"], () => HomePage);
+
+// With dynamic params
+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" });
+
+// Disable query param parsing for this route
+router.on("/raw", (params) => RawPage, { allowQueryParams: false });
+```
+
+**Options:**
+- `label` - Optional label for debugging (visible via `info()`)
+- `allowQueryParams` - Whether to parse query parameters (default: `true`)
+
+**Important:** Routes are matched in registration order. First match wins!
+
+##### `exec(url, fallbackFn?)`
+
+Execute route matching against a URL.
+
+```ts
+const result = router.exec("/users");
+
+// With fallback
+router.exec("/unknown", () => console.log("Not found"));
+
+// With query params
+router.exec("/search?q=hello");
+```
+
+Returns the value returned by the matched callback, or `false` if no match.
+
+##### `subscribe(callback)`
+
+Subscribe to router state changes. Follows the [Svelte store contract](https://svelte.dev/docs#Store_contract).
+
+```ts
+const { unsubscribe } = router.subscribe((state) => {
+	console.log("Route:", state.route);
+	console.log("Params:", state.params);
+	console.log("Label:", state.label);
+});
+
+// Later
+unsubscribe();
+```
+
+The callback is called immediately with the current state, then on every route change.
+
+##### `reset()`
+
+Clears all registered routes (except catch-all).
+
+```ts
+router.reset().on("/new-route", () => NewPage);
+```
+
+##### `info()`
+
+Returns a map of registered routes to their labels (for debugging).
+
+```ts
+router.on("/users", () => {}, { label: "users-list" });
+console.log(router.info()); // { "/users": "users-list" }
+```
+
+#### Properties
+
+##### `current`
+
+Gets the current router state (readonly).
+
+```ts
+router.exec("/user/123");
+console.log(router.current);
+// { route: "/user/[id]", params: { id: "123" }, label: null }
+```
+
+##### `static debug`
+
+Enable/disable debug logging.
+
+```ts
+SimpleRouter.debug = true;
+router.exec("/test"); // Logs matching details to console
 ```
 
-## Quick example
+### SimpleRoute
+
+Low-level route parser. Usually you don't need to use this directly.
+
+```ts
+import { SimpleRoute } from "@marianmeres/simple-router";
 
-```js
-// routes definitions can be added via ctor config object
+const route = new SimpleRoute("/user/[id([0-9]+)]");
+const params = route.parse("/user/123");
+console.log(params); // { id: "123" }
+```
+
+#### Static Methods
+
+##### `parseQueryString(str)`
+
+Parse a query string into an object.
+
+```ts
+SimpleRoute.parseQueryString("foo=bar&baz=123");
+// Returns: { foo: "bar", baz: "123" }
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```ts
+import type {
+	RouteParams,
+	RouteCallback,
+	RouterConfig,
+	RouterCurrent,
+	RouterOnOptions,
+	RouterSubscriber,
+	RouterSubscription,
+} from "@marianmeres/simple-router";
+```
+
+## Advanced Examples
+
+### SPA with Hash Routing
+
+```ts
 const router = new SimpleRouter({
-    '/': () => pageIndex(),
-    '*': () => page404(), // catch all (last resort fallback)
+	"/": () => HomePage,
+	"/about": () => AboutPage,
+	"/user/[id]": (params) => UserPage(params?.id),
+	"*": () => NotFoundPage,
+});
+
+function render(component) {
+	document.getElementById("app").innerHTML = component;
+}
+
+window.addEventListener("hashchange", () => {
+	const path = location.hash.slice(1) || "/";
+	const component = router.exec(path);
+	render(component);
+});
+
+// Trigger initial render
+window.dispatchEvent(new HashChangeEvent("hashchange"));
+```
+
+### Route Priority
+
+Routes are matched in registration order (first match wins):
+
+```ts
+const router = new SimpleRouter();
+
+// Register generic route first
+router.on("/user/[id]", (params) => {
+	console.log("Generic:", params?.id); // This will match
 });
 
-// or via "on" api
-router.on(
-    '/article/[id([0-9]+)]/[slug]',
-    ({ id, slug }) => pageArticle(id, slug)
-);
-
-// finally, perform route match (execute router)
-// (example here returns "component" which is then "rendered")
-window.onhashchange = () => render(router.exec(location.hash));
-```
-
-See [tests](tests) or [examples](examples) for more.
-
-## Route matching
-
-Route segments:
-- `exact` matches `exact`
-- `[name]` matches `any` and is resolved as `{ name: 'any' }` param
-- `[name(regex)]` matches if `regex.test(segment)` is truthy
-- `exact?` or `[name]?` marks segment as optional
-- `[...name]` matches "rest segments"
-- `*` matches zero or more following segments
-
-Few notes on segments separators (which is slash `/` by default):
-- multiple ones are always normalized to single,
-- separator is always trimmed (both left and right) before matching
-
-| Example route definition  | Example input      | Result                      |
-| ------------------------- | ------------------ | --------------------------- |
-| `/foo`                    | `/bar`             | `null`                      |
-| `/foo`                    | (empty string)     | `null`                      |
-| `/foo/[bar]`              | `/foo`             | `null`                      |
-| `/[foo]/bar`              | `/foo`             | `null`                      |
-| `/[foo]/[bar]`            | `/foo`             | `null`                      |
-| `/`                       | (empty string)     | `{}`                        |
-| (empty string)            | `///`              | `{}`                        |
-| `foo`                     | `foo`              | `{}`                        |
-| `//foo///bar.baz/`        | `foo/bar.baz`      | `{}`                        |
-| `foo/bar/baz`             | `//foo//bar/baz//` | `{}`                        |
-| `/[foo]`                  | `/bar`             | `{"foo":"bar"}`             |
-| `#/foo/[bar]`             | `#/foo/bat`        | `{"bar":"bat"}`             |
-| `#/[foo]/[bar]`           | `#/baz/bat`        | `{"foo":"baz","bar":"bat"}` |
-| `#/[foo]/bar`             | `#/baz/bar`        | `{"foo":"baz"}`             |
-| `/[id([0-9]+)]`           | `/123`             | `{"id":"123"}`              |
-| `/[id(\d-\d)]`            | `/1-2`             | `{"id":"1-2"}`              |
-| `/[id([0-9]+)]`           | `/foo`             | `null`                      |
-| `/foo/[bar]/[id([0-9]+)]` | `/foo/baz/123`     | `{"bar":"baz","id":"123"}`  |
-| `/foo/[id([0-9]+)]/[bar]` | `/foo/bar/baz`     | `null`                      |
-| `/foo/[([0-9]+)]`         | `/foo/123`         | `null` (missing name before regex) |
-| `/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" }`            |
-| `/*`                      | `/foo/bar`         | `{}`                        |
-See [tests](tests) or [examples](examples) for more.
+// Specific route registered second (won't match "/user/admin")
+router.on("/user/admin", () => {
+	console.log("Admin"); // This won't be reached
+});
+
+router.exec("/user/admin"); // Logs: "Generic: admin"
+```
+
+To fix, register more specific routes first:
+
+```ts
+router.on("/user/admin", () => console.log("Admin"));
+router.on("/user/[id]", (params) => console.log("User:", params?.id));
+```
+
+### Beyond URLs: General Pattern Matching
+
+The router can match any string patterns, not just URLs:
+
+```ts
+// File path routing
+const fileRouter = new SimpleRouter({
+	"src/[module]/[file].ts": ({ module, file }) =>
+		console.log(`Module: ${module}, File: ${file}`),
+	"assets/images/[...path]": ({ path }) =>
+		console.log(`Image path: ${path}`),
+});
+
+fileRouter.exec("src/components/Button.ts");
+// Logs: "Module: components, File: Button"
+
+fileRouter.exec("assets/images/icons/user.png");
+// Logs: "Image path: icons/user.png"
+
+// Command routing
+const cmdRouter = new SimpleRouter({
+	"user:create": () => createUser(),
+	"user:delete:[id([0-9]+)]": ({ id }) => deleteUser(id),
+	"cache:clear:[type(redis|memcached)]?": ({ type = "all" }) =>
+		clearCache(type),
+});
+
+cmdRouter.exec("user:delete:123");
+cmdRouter.exec("cache:clear:redis");
+cmdRouter.exec("cache:clear"); // type defaults to "all"
+
+// Custom separator (anything that's not a special regex char works)
+const dotRouter = new SimpleRouter({
+	"app.settings.theme": () => "Theme settings",
+	"app.settings.[section]": ({ section }) => `Settings: ${section}`,
+});
+
+dotRouter.exec("app.settings.profile");
+// Returns: "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

@@ -0,0 +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";

package/dist/mod.js

@@ -0,0 +1,3 @@
+// Main classes
+export { SimpleRoute } from "./route.js";
+export { SimpleRouter } from "./router.js";

package/dist/route.d.ts

@@ -1,19 +1,98 @@
+/**
+ * Configuration for a single route segment.
+ * @internal
+ */
 export interface RouteConfig {
     segment: string;
-    name: string;
+    name: string | null;
     test: RegExp;
     isOptional: boolean;
     isSpread: boolean;
 }
+/**
+ * Route parameters extracted from URL segments and query strings.
+ */
+export type RouteParams = Record<string, any>;
 export declare class SimpleRoute {
-    readonly route: any;
+    #private;
+    readonly route: string;
+    /** Separator used to split URL paths into segments */
     static SPLITTER: string;
+    /** Wildcard symbol for catch-all routes */
     static WILDCARD: string;
-    protected _parsed: RouteConfig[];
-    constructor(route: any);
-    protected static _escapeRegExp(str: string): string;
-    protected static _sanitizeAndSplit(str: any): string[];
-    protected static _parse(route: any): any[];
-    static parseQueryString(str: any): {};
-    parse(url: any, allowQueryParams?: boolean): {};
+    /**
+     * 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: string);
+    /**
+     * 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: string): RouteParams;
+    /**
+     * 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: string, allowQueryParams?: boolean): RouteParams | null;
 }