@thi.ng/router 3.3.0 → 4.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-09T16:05:59Z
+- **Last updated**: 2024-03-13T14:04:31Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,54 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [4.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@4.0.0) (2024-03-13)
+
+#### 🛑 Breaking changes
+
+- trie-based route matching & wildcard support ([f1ab427](https://github.com/thi-ng/umbrella/commit/f1ab427))
+- BREAKING CHANGES: update types, args, rename option fields
+  - add `Trie` data structure for route storage & matching
+  - add support for `+` wildcards to match arbitrary length routes
+  - update `BasicRouter.route()` & replace `.matchRoutes()` with new impl
+  - add `AugmentedRoute` interface & pre-process routes to compute
+    wildcard indices for faster matching (along with using the trie)
+  - update `Route.match` to be initially specified as string
+  - update `RouteMatch` to include `.rest` args (if any)
+  - add optional `RouteMatch.redirect` flag
+  - REMOVE `Route.title` & `RouteMatch.title` (obsolete since only used
+    by `HTMLRouter`, but usage unsupported by browsers now
+    (`history.pushState()` doesn't support title anymore)
+  - RENAME `RouterConfig` => `RouterOpts` (align naming convention)
+  - RENAME `RouterOpts.defaultRouteID` => `RouterOpts.default`
+  - RENAME `RouterOpts.initialRouteID` => `RouterOpts.initial`
+  - RENAME `RouterOpts.removeTrailingSlash` => `RouterOpts.trim`
+  - REMOVE obsolete `defMatch()` helper
+  - add/update tests
+- rename BasicRouter => Router ([4d14aab](https://github.com/thi-ng/umbrella/commit/4d14aab))
+- BREAKING CHANGE: rename BasicRouter => Router
+  - update all refs
+
+#### 🚀 Features
+
+- update RouteAuthenticator and .route() args ([f009afb](https://github.com/thi-ng/umbrella/commit/f009afb))
+  - add support for optional arbitrary user context object passed
+    to .route() and global auth handler
+  - update optional args for HTMLRouter.route()/.routeTo()
+- update/improve wildcard priority handling ([59c2557](https://github.com/thi-ng/umbrella/commit/59c2557))
+  - implement wildcard fallback logic in `Trie.get()`
+  - add docs
+  - add tests
+
+## [3.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@3.4.0) (2024-03-10)
+
+#### 🚀 Features
+
+- add defMatch() helper ([12134b6](https://github.com/thi-ng/umbrella/commit/12134b6))
+
+#### 🩹 Bug fixes
+
+- rebuild index in updateRoutes() ([deb494e](https://github.com/thi-ng/umbrella/commit/deb494e))
+
 ## [3.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@3.3.0) (2024-03-09)
 
 #### 🚀 Features

package/README.md

@@ -21,25 +21,24 @@
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
+- [Benchmarks](#benchmarks)
 - [Authors](#authors)
 - [License](#license)
 
 ## About
 
-Generic router for browser & non-browser based applications.
+Generic trie-based router with support for wildcards, route param validation/coercion, auth.
 
-- Declarative route definitions
-- Parametric routes, each param with optional value coercion &
-  validation
-- Route authentication handler to enable/disable routes based on other
-  state factors
-- Fallback route
+- **Not bound to any environment**, usable on both client & server side
+- Declarative route definitions, incl. [wildcards for matching rest
+  args](https://docs.thi.ng/umbrella/router/classes/Trie.html)
+- Parametric routes, each param with optional value coercion & validation
+- Route authentication handler to enable/disable routes based on other state
+  factors
+- Fallback route redirect
 - Enforced initial route (optional)
-- Route formatting (with params)
-- HTML5 history & hash fragment support
-
-Partially based on the Clojure implementation in
-[thi.ng/domus](https://github.com/thi-ng/domus/blob/develop/src/router.org).
+- Route formatting (with params & rest args)
+- Optional HTML5 history & hash fragment support
 
 ## Status
 
@@ -72,7 +71,7 @@ For Node.js REPL:
 const router = await import("@thi.ng/router");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.66 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.93 KB
 
 ## Dependencies
 
@@ -97,19 +96,21 @@ directory is using this package:
 [Generated API docs](https://docs.thi.ng/umbrella/router/)
 
 ```ts tangle:export/readme.ts
-import { HTMLRouter, EVENT_ROUTE_CHANGED } from "@thi.ng/router";
+import {
+    HTMLRouter, HTMLRouterOpts, EVENT_ROUTE_CHANGED,
+} from "@thi.ng/router";
+import { isUUID } from "@thi.ng/checks";
 
 // router configuration
-const config = {
-
+const config: HTMLRouterOpts = {
     // use hash fragment for routes
     useFragment: true,
 
     // fallback route (when no other matches)
-    defaultRouteID: "home",
+    default: "home",
 
     // optional enforced route when router starts
-    initialRouteID: "home",
+    initial: "home",
 
     // Optional route path component separator. Default: `/`
     separator: "/",
@@ -120,70 +121,114 @@ const config = {
     prefix: "#/",
 
     // actual route defs
-    // An array of route specs which route input strings will be matched
-    // against. Routes will be sorted from longest to shortest.
+    // An array of route specs which route input strings will be matched against.
+    // Given routes will be pre-processed and stored in a Trie for fast matching.
+    // Additional routes can be dynamically added at a later time via .addRoutes()
     routes: [
         {
             // each route MUST have an ID
             id: "home",
-            // optional title for UI purposes (no internal function)
-            title: "Home page",
             // this array defines the route path items
-            match: ["home"]
+            match: "/home",
         },
         {
             id: "user-profile",
             // this rule is parametric
             // variable items are prefixed with `?`
-            match: ["users", "?id"],
+            match: "/users/?id",
             // coercion & validation handlers for "?id" param
             // coercion fn is applied BEFORE validator
             validate: {
                 id: {
                     coerce: (x) => parseInt(x),
-                    check: (x)=> x > 0 && x < 100
-                }
-            }
+                    check: (x) => x > 0 && x < 100,
+                },
+            },
         },
         {
             id: "image",
             // this route has 2 params and matches (for example):
             // "/images/07a9d87b-c07a-42e3-82cf-baea2f94facc/xl"
-            match: ["images", "?id", "?size"],
+            match: "/images/?id/?size",
             validate: {
                 id: {
-                    check: (x)=> isUUID(x)
+                    check: (x) => isUUID(x),
                 },
                 size: {
-                    check: (x)=> /^(s|m|l|xl)$/.test(x)
-                }
+                    check: (x) => /^(s|m|l|xl)$/.test(x),
+                },
             },
-            // enable auth for this route
-            // (see info about authenticator functions below)
-            auth: true
         },
         {
             id: "group-list",
             // matches only: "/users" or "/images"
-            match: ["?type"],
+            match: "/?type",
             validate: {
                 type: {
-                    check: (x) => /^(users|images)$/.test(x)
-                }
+                    check: (x) => /^(users|images)$/.test(x),
+                },
             },
-            auth: true
         },
-    ]
+    ],
 };
 
 // `HTMLRouter` ONLY works in browser environments
-// for non-browser use cases use `BasicRouter`
+// for non-browser use cases use `Router`
 const router = new HTMLRouter(config);
 router.addListener(EVENT_ROUTE_CHANGED, console.log);
 
 router.start();
 ```
 
+## Benchmarks
+
+The below benchmarks are ported from
+[router-benchmark](https://github.com/delvedor/router-benchmark), showing
+**highly competitive** results for this package. The
+[benchmark](https://github.com/thi-ng/umbrella/blob/develop/packages/router/bench/index.ts)
+itself can be run from the repo root like so:
+
+```bash
+bun packages/router/bench/index.ts
+```
+
+```text
+benchmarking: short static
+        warmup... 133.48ms (0.1 runs)
+        total: 113.79ms, runs: 1 (@ 1 calls/iter)
+        freq: 8788202.11 ops/sec
+
+benchmarking: static with same radix
+        warmup... 166.98ms (0.1 runs)
+        total: 161.89ms, runs: 1 (@ 1 calls/iter)
+        freq: 6176873.20 ops/sec
+
+benchmarking: dynamic route
+        warmup... 378.30ms (0.1 runs)
+        total: 374.80ms, runs: 1 (@ 1 calls/iter)
+        freq: 2668082.83 ops/sec
+
+benchmarking: mixed static dynamic
+        warmup... 344.19ms (0.1 runs)
+        total: 340.33ms, runs: 1 (@ 1 calls/iter)
+        freq: 2938310.18 ops/sec
+
+benchmarking: long static
+        warmup... 326.61ms (0.1 runs)
+        total: 327.84ms, runs: 1 (@ 1 calls/iter)
+        freq: 3050259.51 ops/sec
+
+benchmarking: wildcard
+        warmup... 207.84ms (0.1 runs)
+        total: 207.49ms, runs: 1 (@ 1 calls/iter)
+        freq: 4819484.22 ops/sec
+
+benchmarking: all together
+        warmup... 1525.05ms (0.1 runs)
+        total: 1532.24ms, runs: 1 (@ 1 calls/iter)
+        freq: 652640.66 ops/sec
+```
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/api.d.ts

@@ -1,13 +1,19 @@
-import type { EVENT_ALL, Fn, IID, IObjectOf } from "@thi.ng/api";
+import type { EVENT_ALL, Fn, IObjectOf } from "@thi.ng/api";
 /**
- * A validation function for to-be authenticated routes. If this function
- * determines that the user is not allowed to access this route, it should
- * return nothing or a {@link RouteMatch} object for redirecting (e.g. to a
- * login, home page or other non-protected route). If nothing is returned and no
- * other routes can be matched, the router will eventually return the configured
- * default fallback route (see {@link RouterConfig.defaultRouteID}).
+ * A validation function for to-be authenticated routes.
+ *
+ * @remarks
+ * If this function determines that the user is not allowed to access this
+ * route, it should return nothing or a {@link RouteMatch} object for
+ * redirecting (e.g. to a login, home page or other non-protected route). If
+ * nothing is returned and no other routes can be matched, the router will
+ * eventually return the configured default fallback route (see
+ * {@link RouterOpts.default}).
+ *
+ * The optional `ctx` is an arbitrary user provided context value given to
+ * {@link BasicRouter.route} (e.g. the original request object).
  */
-export type RouteAuthenticator = (route: Route, curr: string[], params: any) => RouteMatch;
+export type RouteAuthenticator<T = any> = (match: RouteMatch, route: AugmentedRoute, ctx?: T) => RouteMatch | undefined;
 /**
  * Route validator subspecs are optional and used to coerce and/or validate
  * individual route parameters.
@@ -29,19 +35,29 @@ export interface RouteParamValidator {
  * parameter coercion, validation and overall route authentication. Apart from
  * `id` and `match` all other fields are optional.
  */
-export interface Route extends IID<string> {
+export interface Route {
     /**
-     * Array of path components. If a value is prefixed with `?` this path
-     * component will be captured under that name. E.g. `["projects", "?id"]`
-     * will match any of these routes:
+     * Unique ID for this route. This value will be returned as part of a
+     * {@link RouteMatch} resulting from {@link BasicRouter.route} and also used
+     * to look up routes in {@link BasicRouter.routeForID} and
+     * {@link BasicRouter.format}.
+     */
+    id: string;
+    /**
+     * Array or string of path components, incl. wildcards. If a value is
+     * prefixed with `?` this path component will be captured under that name. A
+     * `+` component matches one or more rest args.
+     *
+     * @remarks
+     * See {@link Trie} for rules & comments on wildcard priorities & handling.
      *
-     * - `projects/123`
-     * - `projects/abcde`
+     * E.g. `/projects/?pid` will match routes: `/projects/123` or
+     * `/projects/abcde`, but NOT: `/projects`...
      *
-     * `validate` options can then be used to further restrict the possible
-     * value range of the `id` value...
+     * {@link Route.validate} options can then be used to further restrict the
+     * possible value range of the `pid` param value and/or coerce it...
      */
-    match: string[];
+    match: string | string[];
     /**
      * This object specifies coercions and validators for variable /
      * parameterized path components, e.g.
@@ -50,7 +66,7 @@ export interface Route extends IID<string> {
      * {
      *  id: {
      *          coerce: (x) => parseInt(x,10),
-     *          validate: (x)=> x < 100
+     *          check: (x)=> x < 100
      *      }
      * }
      * ```
@@ -66,53 +82,84 @@ export interface Route extends IID<string> {
      */
     auth?: boolean;
     /**
-     * Optional route title (passed to {@link RouteMatch})
+     * Reserved property.
+     *
+     * @internal used by {@link AugmentedRoute}
      */
-    title?: string;
+    rest?: never;
     /**
-     * Allow route objects to be extented w/ custom data
+     * Reserved property.
+     *
+     * @internal used by {@link AugmentedRoute}
      */
-    [id: string]: any;
+    params?: never;
+}
+export interface AugmentedRoute extends Omit<Route, "match" | "rest" | "params"> {
+    match: string[];
+    params?: Record<number, string>;
+    rest: number;
 }
 /**
  * Result object returned by a routing operation and event value for
  * {@link EVENT_ROUTE_CHANGED}. Contains the matched route ID and any route
  * params.
  */
-export interface RouteMatch extends IID<string> {
-    title?: string;
+export interface RouteMatch {
     /**
-     * Matched & processed route params.
+     * ID of matched {@link Route}.
+     */
+    id: string;
+    /**
+     * Matched & processed/coerced route params.
      */
     params?: any;
+    /**
+     * Only used for `*` wildcard routes. Contains remaining route elements.
+     */
+    rest?: string[];
+    /**
+     * If true, indicates the ID of this route match is a redirect (e.g.
+     * triggered by the {@link RouteAuthenticator} or if no route matched and
+     * the {@link RouterOpts.default} was triggered).
+     *
+     * @remarks
+     * Only intended for client purposes, not used internally. I.e. clients
+     * should check if this flag is set and take appropriate redirect measures.
+     */
+    redirect?: true;
 }
 /**
  * Configuration object for {@link BasicRouter} and {@link HTMLRouter}
  * instances.
  */
-export interface RouterConfig {
+export interface RouterOpts<T = any> {
     /**
      * An array of route specs which route input strings will be matched
-     * against. Routes will be sorted from longest to shortest.
+     * against. Given routes will be pre-processed and stored in a {@link Trie}
+     * for fast matching.
+     *
+     * @remarks
+     * Additional routes can be dynamically added at a later time via
+     * {@link Router.addRoutes}.
      */
     routes: Route[];
     /**
      * Fallback route ID (MUST exist in `routes`), used if none of the defined
      * routes could be matched against user input, e.g. a home or error page.
      */
-    defaultRouteID: string;
+    default: string;
     /**
      * Optional initial route to trigger when router starts. If given, this MUST
      * be a route without params.
      */
-    initialRouteID?: string;
+    initial?: string;
     /**
      * Optional route authentication function. See {@link RouteAuthenticator}
      * for further details. If no authenticator is given, all matched routes
      * will always succeed, regardless if a rule's `auth` flag is enabled or
      * not.
      */
-    authenticator?: RouteAuthenticator;
+    authenticator?: RouteAuthenticator<T>;
     /**
      * Optional route path component separator. Default: `/`
      */
@@ -121,19 +168,22 @@ export interface RouterConfig {
      * Route prefix. Default: `/`. All routes to be parsed by
      * {@link BasicRouter.route} are assumed to have this prefix. All routes
      * returned by {@link BasicRouter.format} will include this prefix.
+     *
+     * @remarks
+     * If given, the prefix MUST end with {@link RouterOpts.separator}.
      */
     prefix?: string;
     /**
      * If true (default), the trailing slash (actually
-     * {@link RouterConfig.separator}) of a given route string will be removed
-     * before matching.
+     * {@link RouterOpts.separator}) of a given route input string will be
+     * removed before matching.
      */
-    removeTrailingSlash?: boolean;
+    trim?: boolean;
 }
-export interface HTMLRouterConfig extends RouterConfig {
+export interface HTMLRouterOpts<T = any> extends RouterOpts<T> {
     /**
-     * Same as {@link RouterConfig.prefix}. If
-     * {@link HTMLRouterConfig.useFragment} is true, then the default changes to
+     * Same as {@link RouterOpts.prefix}. If
+     * {@link HTMLRouterOpts.useFragment} is true, then the default changes to
      * `#/`. If `useFragment` is enabled and a custom prefix is given, it MUST
      * include the leading `#` as well.
      */

package/basic.d.ts

@@ -1,15 +1,17 @@
-import type { Event, INotify, IObjectOf, Listener } from "@thi.ng/api";
-import { type Route, type RouteMatch, type RouteParamValidator, type RouterConfig, type RouterEventType } from "./api.js";
-export declare class BasicRouter implements INotify<RouterEventType> {
-    config: RouterConfig;
+import type { Event, INotify, IObjectOf, Listener, SomeRequired } from "@thi.ng/api";
+import { type AugmentedRoute, type Route, type RouteMatch, type RouteParamValidator, type RouterEventType, type RouterOpts } from "./api.js";
+import { Trie } from "./trie.js";
+export declare class BasicRouter<T = any> implements INotify<RouterEventType> {
+    opts: RouterOpts<T>;
     current: RouteMatch | undefined;
-    routeIndex: Record<string, Route>;
-    constructor(config: RouterConfig);
+    protected index: Record<string, AugmentedRoute>;
+    protected routes: Trie<AugmentedRoute>;
+    constructor(config: RouterOpts<T>);
     addListener(id: RouterEventType, fn: Listener<RouterEventType>, scope?: any): boolean;
     removeListener(id: RouterEventType, fn: Listener<RouterEventType>, scope?: any): boolean;
     notify(event: Event<RouterEventType>): boolean;
     start(): void;
-    addRoutes(route: Route[]): void;
+    addRoutes(routes: Route[]): void;
     /**
      * Main router function. Attempts to match given input string against all
      * configured routes. Before returning, triggers {@link EVENT_ROUTE_CHANGED}
@@ -17,9 +19,13 @@ export declare class BasicRouter implements INotify<RouterEventType> {
      * {@link EVENT_ROUTE_FAILED} and then falls back to configured default
      * route.
      *
+     * @remarks
+     * See {@link RouteAuthenticator} for details about `ctx` handling.
+     *
      * @param src - route path to match
+     * @param ctx - arbitrary user context
      */
-    route(src: string): RouteMatch | undefined;
+    route(src: string, ctx?: T): RouteMatch | undefined;
     /**
      * Returns a formatted version of given {@link RouteMatch}, incl. any
      * params, or alternatively a registered route ID (and optional route
@@ -27,13 +33,13 @@ export declare class BasicRouter implements INotify<RouterEventType> {
      *
      * @param id -
      * @param params -
+     * @param rest -
      */
-    format(id: string, params?: any): string;
-    format(match: Partial<RouteMatch>): string;
-    routeForID(id: string): Route | undefined;
-    protected updateRoutes(): void;
-    protected matchRoutes(src: string): RouteMatch | undefined;
-    protected matchRoute(curr: string[], route: Route): RouteMatch | undefined;
+    format(id: string, params?: any, rest?: string[]): string;
+    format(match: SomeRequired<RouteMatch, "id">): string;
+    routeForID(id: string): AugmentedRoute | undefined;
+    protected augmentRoute(route: Route): AugmentedRoute;
+    protected matchRoutes(src: string, ctx?: T): RouteMatch | undefined;
     protected validateRouteParams(params: any, validators: IObjectOf<Partial<RouteParamValidator>>): boolean;
     protected handleRouteFailure(): boolean;
 }