@thi.ng/router 3.1.8 → 3.2.2

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-06-09T16:14:01Z
+- **Last updated**: 2022-08-01T14:54:00Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,19 @@ 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.
 
+## [3.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@3.2.0) (2022-06-17)
+
+#### 🚀 Features
+
+- update format(), hash/prefix handling ([724b3ad](https://github.com/thi-ng/umbrella/commit/724b3ad))
+  - update HTMLRouter default prefix to "#/" if `useFragment` is true
+  - remove obsolete `HTMLRouter.format()` (now the same as BasicRouter)
+  - update BasicRouter.format() to throw error for missing route param value
+- add trailing slash option, optimize routeForID() ([c003dc2](https://github.com/thi-ng/umbrella/commit/c003dc2))
+  - update BasicRouter default config init
+  - pre-build `routeIndex` in ctor
+  - optimize `routeForID()` to use new `routeIndex`
+
 ### [3.1.5](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@3.1.5) (2022-04-07)
 
 #### ♻️ Refactoring

package/README.md

@@ -70,7 +70,7 @@ node --experimental-repl-await
 > const router = await import("@thi.ng/router");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.56 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.54 KB
 
 ## Dependencies
 
@@ -114,10 +114,10 @@ const config = {
     // Optional route path component separator. Default: `/`
     separator: "/",
 
-    // Route prefix. Default: `/`. All routes to be parsed by `route()`
-    // are assumed to have this prefix. All routes returned by
-    // `format()` will include this prefix.
-    prefix: "/",
+    // Route prefix. Default: `/` (or `#/` if `useFragment` is enabled).
+    // All routes to be parsed by `route()` are assumed to have this prefix.
+    // All routes returned by `format()` will include this prefix.
+    prefix: "#/",
 
     // actual route defs
     // these are checked in given order
@@ -185,9 +185,6 @@ router.addListener(EVENT_ROUTE_CHANGED, console.log);
 router.start();
 ```
 
-See [further comments in source
-code](https://github.com/thi-ng/umbrella/blob/develop/packages/router/src/api.ts)
-
 ## Authors
 
 Karsten Schmidt

package/api.d.ts

@@ -1,16 +1,16 @@
 import type { Fn, IID, IObjectOf } from "@thi.ng/api";
 /**
- * A validation function to for 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 configure default fallback route.
+ * 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}).
  */
 export declare type RouteAuthenticator = (route: Route, curr: string[], params: any) => RouteMatch;
 /**
- * Route validator subspecs are optional and used to coerce and/or
- * validate individual route parameters.
+ * Route validator subspecs are optional and used to coerce and/or validate
+ * individual route parameters.
  */
 export interface RouteParamValidator {
     /**
@@ -18,30 +18,28 @@ export interface RouteParamValidator {
      */
     coerce?: Fn<string, any>;
     /**
-     * Optional arbitrary value validation. If any validator
-     * returns non-true result, the currently checked route
-     * becomes unmatched/invalid and the router continues
-     * checking other routes.
+     * Optional arbitrary value validation (applied *after* coercion, if any).
+     * If a validator returns non-true result, the currently checked route
+     * becomes unmatched/invalid and the router continues checking other routes.
      */
     check: Fn<any, boolean>;
 }
 /**
- * A Route describes an application path (possibly parameterized),
- * incl. parameter coercion, validation and overall route
- * authentication. Apart from `id` and `match` all other fields
- * are optional.
+ * A Route describes an application path (possibly parameterized), incl.
+ * parameter coercion, validation and overall route authentication. Apart from
+ * `id` and `match` all other fields are optional.
  */
 export interface Route extends IID<string> {
     /**
-     * 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:
+     * 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:
      *
      * - `projects/123`
      * - `projects/abcde`
      *
-     * `validate` options can then be used to further restrict the
-     * possible value range of the `id` value...
+     * `validate` options can then be used to further restrict the possible
+     * value range of the `id` value...
      */
     match: string[];
     /**
@@ -57,14 +55,14 @@ export interface Route extends IID<string> {
      * }
      * ```
      *
-     * This will first coerce the `id` route param to a number and then
-     * only allow the route to be matched if `id < 100`.
+     * This will first coerce the `id` route param to a number and then only
+     * allow the route to be matched if `id < 100`.
      */
     validate?: IObjectOf<RouteParamValidator>;
     /**
      * Flag to indicate if this route should be passed to the globally
-     * configured authentication function. Only matched and validated
-     * routes are processed.
+     * configured authentication function. Only matched and validated routes are
+     * processed.
      */
     auth?: boolean;
     /**
@@ -94,26 +92,25 @@ export interface RouteMatch extends IID<string> {
  */
 export interface RouterConfig {
     /**
-     * An array of route specs, which are being attempted to be matched
-     * in order of appearance.
+     * An array of route specs, which are being attempted to be matched in order
+     * of appearance.
      */
     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.
+     * 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;
     /**
-     * Optional initial route to trigger when router starts. If given,
-     * this MUST be a route without params.
+     * Optional initial route to trigger when router starts. If given, this MUST
+     * be a route without params.
      */
     initialRouteID?: 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.
+     * 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;
     /**
@@ -122,16 +119,27 @@ export interface RouterConfig {
     separator?: string;
     /**
      * 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:1)} will include
-     * this prefix.
+     * {@link BasicRouter.route} are assumed to have this prefix. All routes
+     * returned by {@link (BasicRouter.format:1)} will include this prefix.
      */
     prefix?: string;
+    /**
+     * If true (default), the trailing slash (actually
+     * {@link RouterConfig.separator}) of a given route string will be removed
+     * before matching.
+     */
+    removeTrailingSlash?: boolean;
 }
 export interface HTMLRouterConfig extends RouterConfig {
     /**
-     * Optional flag to indicate if URL hash fragment should be used for
-     * routes.
+     * Same as {@link RouterConfig.prefix}. If
+     * {@link HTMLRouterConfig.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.
+     */
+    prefix?: string;
+    /**
+     * Optional flag to indicate if URL hash fragment should be used for routes.
      */
     useFragment?: boolean;
 }

package/basic.d.ts

@@ -3,6 +3,7 @@ import { Route, RouteMatch, RouteParamValidator, RouterConfig } from "./api.js";
 export declare class BasicRouter implements INotify {
     config: RouterConfig;
     current: RouteMatch | undefined;
+    routeIndex: Record<string, Route>;
     constructor(config: RouterConfig);
     /** {@inheritDoc @thi.ng/api#INotify.addListener} */
     addListener(id: string, fn: Listener, scope?: any): boolean;
@@ -17,19 +18,19 @@ export declare class BasicRouter implements INotify {
      * to default route. Before returning, triggers event with
      * return value as well.
      *
-     * @param raw - route path to match
+     * @param src - route path to match
      */
     route(src: string): RouteMatch | undefined;
     /**
-     * Returns a formatted version of given {@link RouteMatch}, incl. any params.
-     * Throw an error if an invalid route `id` is provided.
+     * 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 match -
+     * @param id -
      * @param params -
-     * @param hash - if true, prepends `#` to results
      */
-    format(id: string, params?: any, hash?: boolean): string;
-    format(match: Partial<RouteMatch>, hash?: boolean): string;
+    format(id: string, params?: any): string;
+    format(match: Partial<RouteMatch>): string;
     routeForID(id: string): Route | undefined;
     protected matchRoutes(src: string): RouteMatch | undefined;
     protected matchRoute(curr: string[], route: Route): RouteMatch | undefined;

package/basic.js

@@ -8,16 +8,18 @@ import { illegalArity } from "@thi.ng/errors/illegal-arity";
 import { EVENT_ROUTE_CHANGED, } from "./api.js";
 let BasicRouter = class BasicRouter {
     constructor(config) {
-        config.authenticator =
-            config.authenticator ||
-                ((route, _, params) => ({
-                    id: route.id,
-                    title: route.title,
-                    params,
-                }));
-        config.prefix = config.prefix === undefined ? "/" : config.prefix;
-        config.separator = config.separator || "/";
-        this.config = config;
+        this.config = {
+            authenticator: (route, _, params) => ({
+                id: route.id,
+                title: route.title,
+                params,
+            }),
+            prefix: "/",
+            separator: "/",
+            removeTrailingSlash: true,
+            ...config,
+        };
+        this.routeIndex = this.config.routes.reduce((acc, r) => ((acc[r.id] = r), acc), {});
         assert(this.routeForID(this.config.defaultRouteID) !== undefined, `missing config for default route: '${this.config.defaultRouteID}'`);
         if (config.initialRouteID) {
             const route = this.routeForID(config.initialRouteID);
@@ -47,11 +49,12 @@ let BasicRouter = class BasicRouter {
      * to default route. Before returning, triggers event with
      * return value as well.
      *
-     * @param raw - route path to match
+     * @param src - route path to match
      */
     route(src) {
-        if (src.charAt(0) === "#") {
-            src = src.substring(1);
+        if (this.config.removeTrailingSlash &&
+            src.charAt(src.length - 1) === this.config.separator) {
+            src = src.substring(0, src.length - 1);
         }
         src = src.substring(this.config.prefix.length);
         let match = this.matchRoutes(src);
@@ -69,20 +72,11 @@ let BasicRouter = class BasicRouter {
         return match;
     }
     format(...args) {
-        let [id, params, hash] = args;
+        let [id, params] = args;
         let match;
         switch (args.length) {
-            case 3:
-                match = { id, params };
-                break;
             case 2:
-                if (isString(id)) {
-                    match = { id, params };
-                }
-                else {
-                    hash = params;
-                    match = id;
-                }
+                match = { id, params };
                 break;
             case 1:
                 match = isString(id) ? { id } : id;
@@ -93,14 +87,18 @@ let BasicRouter = class BasicRouter {
         const route = this.routeForID(match.id);
         if (route) {
             const params = match.params || {};
-            return ((hash ? "#" : "") +
-                this.config.prefix +
+            return (this.config.prefix +
                 route.match
-                    .map((x) => x.charAt(0) === "?"
-                    ? (x = params[x.substring(1)]) != null
-                        ? x
-                        : "NULL"
-                    : x)
+                    .map((x) => {
+                    if (isRouteParam(x)) {
+                        const id = x.substring(1);
+                        const p = params[id];
+                        if (p != null)
+                            return p;
+                        illegalArgs(`missing value for param '${id}'`);
+                    }
+                    return x;
+                })
                     .join(this.config.separator));
         }
         else {
@@ -108,7 +106,7 @@ let BasicRouter = class BasicRouter {
         }
     }
     routeForID(id) {
-        return this.config.routes.find((route) => route.id === id);
+        return this.routeIndex[id];
     }
     matchRoutes(src) {
         const routes = this.config.routes;
@@ -121,12 +119,13 @@ let BasicRouter = class BasicRouter {
         }
     }
     matchRoute(curr, route) {
-        const match = route.match, n = match.length;
+        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 (m.charAt(0) === "?") {
+                if (isRouteParam(m)) {
                     params[m.substring(1)] = curr[i];
                 }
                 else if (curr[i] !== m) {
@@ -164,4 +163,5 @@ BasicRouter = __decorate([
     INotifyMixin
 ], BasicRouter);
 export { BasicRouter };
-const isParametricRoute = (route) => route.match.some((p) => p.charAt(0) === "?");
+const isParametricRoute = (route) => route.match.some(isRouteParam);
+const isRouteParam = (x) => x[0] === "?";

package/history.d.ts

@@ -1,5 +1,5 @@
 import type { Fn } from "@thi.ng/api";
-import type { HTMLRouterConfig, RouteMatch } from "./api.js";
+import type { HTMLRouterConfig } from "./api.js";
 import { BasicRouter } from "./basic.js";
 export declare class HTMLRouter extends BasicRouter {
     protected currentPath: string;
@@ -16,13 +16,11 @@ export declare class HTMLRouter extends BasicRouter {
      * If called from userland, this normally is true. However, we want
      * to avoid this if called from this router's own event handlers.
      *
-     * @param raw -
+     * @param src -
      * @param pushState -
      */
-    route(src: string, pushState?: boolean): RouteMatch | undefined;
+    route(src: string, pushState?: boolean): import("./api.js").RouteMatch | undefined;
     routeTo(route: string): void;
-    format(id: PropertyKey, params?: any): string;
-    format(match: Partial<RouteMatch>): string;
     protected handlePopChange(): Fn<PopStateEvent, void>;
     protected handleHashChange(): EventListener;
     protected handleRouteFailure(): boolean;

package/history.js

@@ -1,10 +1,8 @@
-import { isString } from "@thi.ng/checks/is-string";
 import { equiv } from "@thi.ng/equiv";
-import { illegalArity } from "@thi.ng/errors/illegal-arity";
 import { BasicRouter } from "./basic.js";
 export class HTMLRouter extends BasicRouter {
     constructor(config) {
-        super(config);
+        super({ prefix: config.useFragment ? "#/" : "/", ...config });
         this.useFragment = config.useFragment !== false;
         this.ignoreHashChange = false;
     }
@@ -36,7 +34,7 @@ export class HTMLRouter extends BasicRouter {
      * If called from userland, this normally is true. However, we want
      * to avoid this if called from this router's own event handlers.
      *
-     * @param raw -
+     * @param src -
      * @param pushState -
      */
     route(src, pushState = true) {
@@ -56,20 +54,6 @@ export class HTMLRouter extends BasicRouter {
         }
         this.route(route);
     }
-    format(...args) {
-        let match;
-        switch (args.length) {
-            case 2:
-                match = { id: args[0], params: args[1] };
-                break;
-            case 1:
-                match = isString(args[0]) ? { id: args[0] } : args[0];
-                break;
-            default:
-                illegalArity(args.length);
-        }
-        return super.format(match, this.useFragment);
-    }
     handlePopChange() {
         return (this.popHandler =
             this.popHandler ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/router",
-  "version": "3.1.8",
+  "version": "3.2.2",
   "description": "Generic router for browser & non-browser based applications",
   "type": "module",
   "module": "./index.js",
@@ -34,19 +34,19 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.3.7",
-    "@thi.ng/checks": "^3.2.1",
-    "@thi.ng/equiv": "^2.1.7",
-    "@thi.ng/errors": "^2.1.7",
+    "@thi.ng/api": "^8.3.9",
+    "@thi.ng/checks": "^3.2.3",
+    "@thi.ng/equiv": "^2.1.9",
+    "@thi.ng/errors": "^2.1.9",
     "tslib": "^2.4.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.25.0",
-    "@thi.ng/testament": "^0.2.8",
+    "@thi.ng/testament": "^0.2.10",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.22.17",
-    "typescript": "^4.7.3"
+    "typescript": "^4.7.4"
   },
   "keywords": [
     "browser",
@@ -91,5 +91,5 @@
     ],
     "year": 2014
   },
-  "gitHead": "ab0188234419f2d9f471de80871df930e5555bd6\n"
+  "gitHead": "976ccd698cedaa60dcef2e69030a5eb98898cc4a\n"
 }