@thi.ng/router 3.4.0 → 4.0.0

package/basic.js

@@ -15,41 +15,37 @@ import { equiv } from "@thi.ng/equiv";
 import { assert } from "@thi.ng/errors/assert";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { illegalArity } from "@thi.ng/errors/illegal-arity";
+import { illegalState } from "@thi.ng/errors/illegal-state";
 import {
   EVENT_ROUTE_CHANGED,
   EVENT_ROUTE_FAILED
 } from "./api.js";
+import { Trie } from "./trie.js";
 let BasicRouter = class {
-  config;
+  opts;
   current;
-  routeIndex;
+  index = {};
+  routes = new Trie();
   constructor(config) {
-    this.config = {
-      authenticator: (route, _, params) => ({
-        id: route.id,
-        title: route.title,
-        params
-      }),
+    this.opts = {
+      authenticator: (match) => match,
       prefix: "/",
       separator: "/",
-      removeTrailingSlash: true,
+      trim: true,
       ...config
     };
-    this.updateRoutes();
+    this.addRoutes(this.opts.routes);
     assert(
-      this.routeForID(this.config.defaultRouteID) !== void 0,
-      `missing config for default route: '${this.config.defaultRouteID}'`
+      this.routeForID(this.opts.default) !== void 0,
+      `missing config for default route: '${this.opts.default}'`
     );
-    if (config.initialRouteID) {
-      const route = this.routeForID(config.initialRouteID);
+    if (config.initial) {
+      const route = this.routeForID(config.initial);
       assert(
         route !== void 0,
-        `missing config for initial route: ${this.config.initialRouteID}`
-      );
-      assert(
-        !isParametricRoute(route),
-        "initial route MUST not be parametric"
+        `missing config for initial route: ${this.opts.initial}`
       );
+      assert(!route.params, "initial route MUST not be parametric");
     }
   }
   // @ts-ignore: arguments
@@ -64,15 +60,24 @@ let BasicRouter = class {
   notify(event) {
   }
   start() {
-    if (this.config.initialRouteID) {
-      const route = this.routeForID(this.config.initialRouteID);
-      this.current = { id: route.id, title: route.title, params: {} };
+    if (this.opts.initial) {
+      const route = this.routeForID(this.opts.initial);
+      this.current = { id: route.id, params: {} };
       this.notify({ id: EVENT_ROUTE_CHANGED, value: this.current });
     }
   }
-  addRoutes(route) {
-    this.config.routes.push(...route);
-    this.updateRoutes();
+  addRoutes(routes) {
+    for (let r of routes) {
+      try {
+        const route = this.augmentRoute(r);
+        this.routes.set(route.match, route);
+        this.index[route.id] = route;
+      } catch (e) {
+        illegalArgs(
+          `error in route "${r.id}": ${e.origMessage}`
+        );
+      }
+    }
   }
   /**
    * Main router function. Attempts to match given input string against all
@@ -81,21 +86,25 @@ let BasicRouter = class {
    * {@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) {
-    if (this.config.removeTrailingSlash && src.charAt(src.length - 1) === this.config.separator) {
+  route(src, ctx) {
+    if (this.opts.trim && src.charAt(src.length - 1) === this.opts.separator) {
       src = src.substring(0, src.length - 1);
     }
-    src = src.substring(this.config.prefix.length);
-    let match = this.matchRoutes(src);
+    src = src.substring(this.opts.prefix.length);
+    let match = this.matchRoutes(src, ctx);
     if (!match) {
       this.notify({ id: EVENT_ROUTE_FAILED, value: src });
       if (!this.handleRouteFailure()) {
         return;
       }
-      const route = this.routeForID(this.config.defaultRouteID);
-      match = { id: route.id, title: route.title, params: {} };
+      const route = this.routeForID(this.opts.default);
+      match = { id: route.id, redirect: true };
     }
     if (!equiv(match, this.current)) {
       this.current = match;
@@ -104,9 +113,12 @@ let BasicRouter = class {
     return match;
   }
   format(...args) {
-    let [id, params] = args;
+    let [id, params, rest] = args;
     let match;
     switch (args.length) {
+      case 3:
+        match = { id, params, rest };
+        break;
       case 2:
         match = { id, params };
         break;
@@ -118,67 +130,81 @@ let BasicRouter = class {
     }
     const route = this.routeForID(match.id);
     if (route) {
-      const params2 = match.params || {};
-      return this.config.prefix + route.match.map((x) => {
+      const params2 = match.params;
+      let parts = route.match.map((x) => {
         if (isRouteParam(x)) {
           const id2 = x.substring(1);
-          const p = params2[id2];
-          if (p != null)
-            return p;
-          illegalArgs(`missing value for param '${id2}'`);
+          const p = params2?.[id2];
+          if (p == null) {
+            illegalArgs(`missing value for param '${id2}'`);
+          }
+          return p;
         }
         return x;
-      }).join(this.config.separator);
+      });
+      if (route.rest >= 0)
+        parts = parts.slice(0, route.rest).concat(match.rest || []);
+      return this.opts.prefix + parts.join(this.opts.separator);
     } else {
       illegalArgs(`invalid route ID: ${match.id}`);
     }
   }
   routeForID(id) {
-    return this.routeIndex[id];
+    return this.index[id];
   }
-  updateRoutes() {
-    this.config.routes.sort((a, b) => b.length - a.length);
-    this.config.routes.reduce((acc, x) => {
-      const fmt = x.match.map((y) => isRouteParam(y) ? "*" : y).join("/");
-      if (acc[fmt]) {
-        illegalArgs(`duplicate route: ${x.match} (id: ${x.id})`);
+  augmentRoute(route) {
+    const match = isString(route.match) ? route.match.split(this.opts.separator).filter((x) => !!x) : route.match;
+    const existing = this.routes.get(match);
+    if (existing) {
+      illegalArgs(
+        `duplicate route: ${match} (id: ${route.id}, conflicts with: ${existing.id})`
+      );
+    }
+    let hasParams = false;
+    const params = match.reduce((acc, x, i) => {
+      if (isRouteParam(x)) {
+        hasParams = true;
+        acc[i] = x.substring(1);
       }
-      acc[fmt] = true;
       return acc;
     }, {});
-    this.routeIndex = this.config.routes.reduce(
-      (acc, r) => (acc[r.id] = r, acc),
-      {}
-    );
+    return {
+      ...route,
+      match,
+      params: hasParams ? params : void 0,
+      rest: match.indexOf("+")
+    };
   }
-  matchRoutes(src) {
-    const routes = this.config.routes;
-    const curr = src.split(this.config.separator);
-    for (let i = 0, n = routes.length; i < n; i++) {
-      const match = this.matchRoute(curr, routes[i]);
-      if (match) {
-        return match;
-      }
+  matchRoutes(src, ctx) {
+    const curr = src.split(this.opts.separator);
+    const route = this.routes.get(curr);
+    if (!route)
+      return;
+    let params;
+    if (route.params) {
+      params = Object.entries(route.params).reduce(
+        (acc, [i, k]) => (acc[k] = curr[+i], acc),
+        {}
+      );
     }
-  }
-  matchRoute(curr, route) {
-    const match = route.match;
-    const n = match.length;
-    if (curr.length === n) {
-      const params = {};
-      for (let i = 0; i < n; i++) {
-        const m = match[i];
-        if (isRouteParam(m)) {
-          params[m.substring(1)] = curr[i];
-        } else if (curr[i] !== m) {
-          return;
-        }
-      }
-      if (route.validate && !this.validateRouteParams(params, route.validate)) {
-        return;
+    if (route.validate && !this.validateRouteParams(params, route.validate)) {
+      return;
+    }
+    const rest = route.rest >= 0 ? curr.slice(route.rest) : void 0;
+    let match = {
+      id: route.id,
+      params,
+      rest
+    };
+    if (route.auth) {
+      match = this.opts.authenticator(match, route, ctx);
+      if (match && !this.index[match.id]) {
+        illegalState(
+          "auth handler returned invalid route ID: " + match.id
+        );
       }
-      return route.auth ? this.config.authenticator(route, curr, params) : { id: route.id, title: route.title, params };
     }
+    return match;
   }
   validateRouteParams(params, validators) {
     for (let id in validators) {
@@ -201,10 +227,7 @@ let BasicRouter = class {
 BasicRouter = __decorateClass([
   INotifyMixin
 ], BasicRouter);
-const isParametricRoute = (route) => route.match.some(isRouteParam);
 const isRouteParam = (x) => x[0] === "?";
-const defMatch = (pattern, sep = "/") => pattern.split(sep).filter((x) => !!x);
 export {
-  BasicRouter,
-  defMatch
+  BasicRouter
 };

package/history.d.ts

@@ -1,7 +1,7 @@
 import type { Fn } from "@thi.ng/api";
 import type { HTMLRouterConfig } from "./api.js";
 import { BasicRouter } from "./basic.js";
-export declare class HTMLRouter extends BasicRouter {
+export declare class HTMLRouter<T = any> extends BasicRouter<T> {
     protected currentPath: string;
     protected popHandler: Fn<PopStateEvent, void>;
     protected hashHandler: EventListener;
@@ -11,16 +11,19 @@ export declare class HTMLRouter extends BasicRouter {
     start(): void;
     release(): void;
     /**
-     * Like `BasicRouter.route()`, but takes additional arg to control
-     * if this routing operation should manipulate the browser's `history`.
-     * If called from userland, this normally is true. However, we want
-     * to avoid this if called from this router's own event handlers.
+     * Like {@link BasicRouter.route}, but takes additional arg to control if
+     * this routing operation should manipulate the browser's `history`.
+     *
+     * @remarks
+     * If called from userland, this normally is true (also default). However,
+     * we want to avoid this if called from this router's own event handlers.
      *
      * @param src -
+     * @param ctx -
      * @param pushState -
      */
-    route(src: string, pushState?: boolean): import("./api.js").RouteMatch | undefined;
-    routeTo(route: string): void;
+    route(src: string, ctx?: T, pushState?: boolean): import("./api.js").RouteMatch | undefined;
+    routeTo(route: string, ctx?: T): void;
     protected handlePopChange(): Fn<PopStateEvent, void>;
     protected handleHashChange(): EventListener;
     protected handleRouteFailure(): boolean;

package/history.js

@@ -16,14 +16,9 @@ class HTMLRouter extends BasicRouter {
     if (this.useFragment) {
       window.addEventListener("hashchange", this.handleHashChange());
     }
-    if (this.config.initialRouteID) {
-      const route = this.routeForID(this.config.initialRouteID);
-      this.route(
-        this.format({
-          id: route.id,
-          title: route.title
-        })
-      );
+    if (this.opts.initial) {
+      const route = this.routeForID(this.opts.initial);
+      this.route(this.format({ id: route.id }));
     } else {
       this.route(this.useFragment ? location.hash : location.pathname);
     }
@@ -35,39 +30,39 @@ class HTMLRouter extends BasicRouter {
     }
   }
   /**
-   * Like `BasicRouter.route()`, but takes additional arg to control
-   * if this routing operation should manipulate the browser's `history`.
-   * If called from userland, this normally is true. However, we want
-   * to avoid this if called from this router's own event handlers.
+   * Like {@link BasicRouter.route}, but takes additional arg to control if
+   * this routing operation should manipulate the browser's `history`.
+   *
+   * @remarks
+   * If called from userland, this normally is true (also default). However,
+   * we want to avoid this if called from this router's own event handlers.
    *
    * @param src -
+   * @param ctx -
    * @param pushState -
    */
-  route(src, pushState = true) {
+  route(src, ctx, pushState = true) {
     const old = this.current;
-    const route = super.route(src);
+    const route = super.route(src, ctx);
     if (route && !equiv(route, old)) {
       this.currentPath = this.format(route);
       if (pushState) {
-        history.pushState(
-          this.currentPath,
-          route.title || window.document.title || "",
-          this.currentPath
-        );
+        history.pushState(this.currentPath, "", this.currentPath);
       }
     }
     return route;
   }
-  routeTo(route) {
+  routeTo(route, ctx) {
     if (this.useFragment) {
       location.hash = route;
     }
-    this.route(route);
+    this.route(route, ctx);
   }
   handlePopChange() {
     return this.popHandler = this.popHandler || ((e) => {
       this.route(
         e.state || (this.useFragment ? location.hash : location.pathname),
+        void 0,
         false
       );
     }).bind(this);
@@ -77,7 +72,7 @@ class HTMLRouter extends BasicRouter {
       if (!this.ignoreHashChange) {
         const hash = e.newURL.substring(e.newURL.indexOf("#"));
         if (hash !== this.currentPath) {
-          this.route(hash, false);
+          this.route(hash, void 0, false);
         }
       }
     }).bind(this);
@@ -85,7 +80,7 @@ class HTMLRouter extends BasicRouter {
   handleRouteFailure() {
     this.ignoreHashChange = true;
     location.hash = this.format({
-      id: this.routeForID(this.config.defaultRouteID).id
+      id: this.routeForID(this.opts.default).id
     });
     this.ignoreHashChange = false;
     return true;

package/html.d.ts

@@ -0,0 +1,31 @@
+import type { Fn } from "@thi.ng/api";
+import type { HTMLRouterOpts } from "./api.js";
+import { Router } from "./router.js";
+export declare class HTMLRouter<T = any> extends Router<T> {
+    protected currentPath: string;
+    protected popHandler: Fn<PopStateEvent, void>;
+    protected hashHandler: EventListener;
+    protected useFragment: boolean;
+    protected ignoreHashChange: boolean;
+    constructor(config: HTMLRouterOpts);
+    start(): void;
+    release(): void;
+    /**
+     * Like {@link Router.route}, but takes additional arg to control if
+     * this routing operation should manipulate the browser's `history`.
+     *
+     * @remarks
+     * If called from userland, this normally is true (also default). However,
+     * we want to avoid this if called from this router's own event handlers.
+     *
+     * @param src -
+     * @param ctx -
+     * @param pushState -
+     */
+    route(src: string, ctx?: T, pushState?: boolean): import("./api.js").RouteMatch | undefined;
+    routeTo(route: string, ctx?: T): void;
+    protected handlePopChange(): Fn<PopStateEvent, void>;
+    protected handleHashChange(): EventListener;
+    protected handleRouteFailure(): boolean;
+}
+//# sourceMappingURL=html.d.ts.map

package/html.js

@@ -0,0 +1,91 @@
+import { equiv } from "@thi.ng/equiv";
+import { Router } from "./router.js";
+class HTMLRouter extends Router {
+  currentPath;
+  popHandler;
+  hashHandler;
+  useFragment;
+  ignoreHashChange;
+  constructor(config) {
+    super({ prefix: config.useFragment ? "#/" : "/", ...config });
+    this.useFragment = config.useFragment !== false;
+    this.ignoreHashChange = false;
+  }
+  start() {
+    window.addEventListener("popstate", this.handlePopChange());
+    if (this.useFragment) {
+      window.addEventListener("hashchange", this.handleHashChange());
+    }
+    if (this.opts.initial) {
+      const route = this.routeForID(this.opts.initial);
+      this.route(this.format({ id: route.id }));
+    } else {
+      this.route(this.useFragment ? location.hash : location.pathname);
+    }
+  }
+  release() {
+    window.removeEventListener("popstate", this.popHandler);
+    if (this.useFragment) {
+      window.removeEventListener("hashchange", this.hashHandler);
+    }
+  }
+  /**
+   * Like {@link Router.route}, but takes additional arg to control if
+   * this routing operation should manipulate the browser's `history`.
+   *
+   * @remarks
+   * If called from userland, this normally is true (also default). However,
+   * we want to avoid this if called from this router's own event handlers.
+   *
+   * @param src -
+   * @param ctx -
+   * @param pushState -
+   */
+  route(src, ctx, pushState = true) {
+    const old = this.current;
+    const route = super.route(src, ctx);
+    if (route && !equiv(route, old)) {
+      this.currentPath = this.format(route);
+      if (pushState) {
+        history.pushState(this.currentPath, "", this.currentPath);
+      }
+    }
+    return route;
+  }
+  routeTo(route, ctx) {
+    if (this.useFragment) {
+      location.hash = route;
+    }
+    this.route(route, ctx);
+  }
+  handlePopChange() {
+    return this.popHandler = this.popHandler || ((e) => {
+      this.route(
+        e.state || (this.useFragment ? location.hash : location.pathname),
+        void 0,
+        false
+      );
+    }).bind(this);
+  }
+  handleHashChange() {
+    return this.hashHandler = this.hashHandler || ((e) => {
+      if (!this.ignoreHashChange) {
+        const hash = e.newURL.substring(e.newURL.indexOf("#"));
+        if (hash !== this.currentPath) {
+          this.route(hash, void 0, false);
+        }
+      }
+    }).bind(this);
+  }
+  handleRouteFailure() {
+    this.ignoreHashChange = true;
+    location.hash = this.format({
+      id: this.routeForID(this.opts.default).id
+    });
+    this.ignoreHashChange = false;
+    return true;
+  }
+}
+export {
+  HTMLRouter
+};

package/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./api.js";
-export * from "./basic.js";
-export * from "./history.js";
+export * from "./html.js";
+export * from "./router.js";
+export * from "./trie.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,3 +1,4 @@
 export * from "./api.js";
-export * from "./basic.js";
-export * from "./history.js";
+export * from "./html.js";
+export * from "./router.js";
+export * from "./trie.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/router",
-  "version": "3.4.0",
-  "description": "Generic router for browser & non-browser based applications",
+  "version": "4.0.0",
+  "description": "Generic trie-based router with support for wildcards, route param validation/coercion, auth",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -36,18 +36,18 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.29",
-    "@thi.ng/checks": "^3.5.2",
-    "@thi.ng/equiv": "^2.1.51",
-    "@thi.ng/errors": "^2.4.20",
+    "@thi.ng/api": "^8.9.30",
+    "@thi.ng/checks": "^3.5.3",
+    "@thi.ng/equiv": "^2.1.52",
+    "@thi.ng/errors": "^2.5.0",
     "tslib": "^2.6.2"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.40.1",
-    "esbuild": "^0.20.0",
+    "@microsoft/api-extractor": "^7.42.3",
+    "esbuild": "^0.20.1",
     "rimraf": "^5.0.5",
-    "typedoc": "^0.25.7",
-    "typescript": "^5.3.3"
+    "typedoc": "^0.25.12",
+    "typescript": "^5.4.2"
   },
   "keywords": [
     "browser",
@@ -56,10 +56,13 @@
     "history",
     "html",
     "parametric",
+    "pattern",
     "router",
+    "trie",
     "typescript",
     "ui",
-    "validate"
+    "validate",
+    "wildcards"
   ],
   "publishConfig": {
     "access": "public"
@@ -78,11 +81,14 @@
     "./api": {
       "default": "./api.js"
     },
-    "./basic": {
-      "default": "./basic.js"
+    "./html": {
+      "default": "./html.js"
     },
-    "./history": {
-      "default": "./history.js"
+    "./router": {
+      "default": "./router.js"
+    },
+    "./trie": {
+      "default": "./trie.js"
     }
   },
   "thi.ng": {
@@ -92,5 +98,5 @@
     ],
     "year": 2014
   },
-  "gitHead": "c93ab989dd2013dce1a7f7434f42ef3a270b950f\n"
+  "gitHead": "7f3fcbd6c0462b0ce45afa141fe163d1f297fd51\n"
 }

package/router.d.ts

@@ -0,0 +1,46 @@
+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 Router<T = any> implements INotify<RouterEventType> {
+    opts: RouterOpts<T>;
+    current: RouteMatch | undefined;
+    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(routes: Route[]): void;
+    /**
+     * Main router function. Attempts to match given input string against all
+     * configured routes. Before returning, triggers {@link EVENT_ROUTE_CHANGED}
+     * with return value as well. If none of the routes matches, emits
+     * {@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, ctx?: T): RouteMatch | undefined;
+    /**
+     * Returns a formatted version of given {@link RouteMatch}, incl. any
+     * params, or alternatively a registered route ID (and optional route
+     * params). Throws an error if an invalid route `id` is provided.
+     *
+     * @param id -
+     * @param params -
+     * @param rest -
+     */
+    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;
+}
+//# sourceMappingURL=router.d.ts.map