@thi.ng/router 4.0.6 → 4.0.8

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-08T14:59:30Z
+- **Last updated**: 2024-04-20T14:42:45Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ 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.8](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@4.0.8) (2024-04-20)
+
+#### ♻️ Refactoring
+
+- update type usage ([835dfb0](https://github.com/thi-ng/umbrella/commit/835dfb0))
+
 ### [4.0.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/router@4.0.1) (2024-03-13)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 191 standalone projects, maintained as part
+> This is one of 192 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -66,10 +66,10 @@ import * as rou from "@thi.ng/router";
 Browser ESM import:
 
 ```html
-<script type="module" src="https://cdn.skypack.dev/@thi.ng/router"></script>
+<script type="module" src="https://esm.run/@thi.ng/router"></script>
 ```
 
-[Skypack documentation](https://docs.skypack.dev/)
+[JSDelivr documentation](https://www.jsdelivr.com/)
 
 Package sizes (brotli'd, pre-treeshake): ESM: 1.94 KB
 

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { EVENT_ALL, Fn, IObjectOf } from "@thi.ng/api";
+import type { EVENT_ALL, Fn, IObjectOf, Maybe } from "@thi.ng/api";
 /**
  * A validation function for to-be authenticated routes.
  *
@@ -13,7 +13,7 @@ import type { EVENT_ALL, Fn, IObjectOf } from "@thi.ng/api";
  * The optional `ctx` is an arbitrary user provided context value given to
  * {@link Router.route} (e.g. the original request object).
  */
-export type RouteAuthenticator<T = any> = (match: RouteMatch, route: AugmentedRoute, ctx?: T) => RouteMatch | undefined;
+export type RouteAuthenticator<T = any> = (match: RouteMatch, route: AugmentedRoute, ctx?: T) => Maybe<RouteMatch>;
 /**
  * Route validator subspecs are optional and used to coerce and/or validate
  * individual route parameters.

package/html.d.ts

@@ -22,7 +22,7 @@ export declare class HTMLRouter<T = any> extends Router<T> {
      * @param ctx -
      * @param pushState -
      */
-    route(src: string, ctx?: T, pushState?: boolean): import("./api.js").RouteMatch | undefined;
+    route(src: string, ctx?: T, pushState?: boolean): import("@thi.ng/api").Maybe<import("./api.js").RouteMatch>;
     routeTo(route: string, ctx?: T): void;
     protected handlePopChange(): Fn<PopStateEvent, void>;
     protected handleHashChange(): EventListener;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/router",
-  "version": "4.0.6",
+  "version": "4.0.8",
   "description": "Generic trie-based router with support for wildcards, route param validation/coercion, auth",
   "type": "module",
   "module": "./index.js",
@@ -36,10 +36,10 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.10.0",
-    "@thi.ng/checks": "^3.6.0",
-    "@thi.ng/equiv": "^2.1.54",
-    "@thi.ng/errors": "^2.5.3",
+    "@thi.ng/api": "^8.11.0",
+    "@thi.ng/checks": "^3.6.2",
+    "@thi.ng/equiv": "^2.1.56",
+    "@thi.ng/errors": "^2.5.5",
     "tslib": "^2.6.2"
   },
   "devDependencies": {
@@ -98,5 +98,5 @@
     ],
     "year": 2014
   },
-  "gitHead": "85ac4bd4d6d89f8e3689e2863d5bea0cecdb371c\n"
+  "gitHead": "8339d05ecc857e529c7325a9839c0063b89e728d\n"
 }

package/router.d.ts

@@ -1,9 +1,9 @@
-import type { Event, INotify, IObjectOf, Listener, SomeRequired } from "@thi.ng/api";
+import type { Event, INotify, IObjectOf, Listener, Maybe, 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;
+    current: Maybe<RouteMatch>;
     protected index: Record<string, AugmentedRoute>;
     protected routes: Trie<AugmentedRoute>;
     constructor(config: RouterOpts<T>);
@@ -25,7 +25,7 @@ export declare class Router<T = any> implements INotify<RouterEventType> {
      * @param src - route path to match
      * @param ctx - arbitrary user context
      */
-    route(src: string, ctx?: T): RouteMatch | undefined;
+    route(src: string, ctx?: T): Maybe<RouteMatch>;
     /**
      * Returns a formatted version of given {@link RouteMatch}, incl. any
      * params, or alternatively a registered route ID (and optional route
@@ -37,9 +37,9 @@ export declare class Router<T = any> implements INotify<RouterEventType> {
      */
     format(id: string, params?: any, rest?: string[]): string;
     format(match: SomeRequired<RouteMatch, "id">): string;
-    routeForID(id: string): AugmentedRoute | undefined;
+    routeForID(id: string): Maybe<AugmentedRoute>;
     protected augmentRoute(route: Route): AugmentedRoute;
-    protected matchRoutes(src: string, ctx?: T): RouteMatch | undefined;
+    protected matchRoutes(src: string, ctx?: T): Maybe<RouteMatch>;
     protected validateRouteParams(params: any, validators: IObjectOf<Partial<RouteParamValidator>>): boolean;
     protected handleRouteFailure(): boolean;
 }

package/trie.d.ts

@@ -1,3 +1,4 @@
+import type { Maybe } from "@thi.ng/api";
 /**
  * Trie data structure for storing & matching route patterns with wildcards.
  *
@@ -47,8 +48,8 @@
 export declare class Trie<T> {
     n: Record<string, Trie<T>>;
     v?: T;
-    constructor(key?: string[], v?: T | undefined, i?: number);
+    constructor(key?: string[], v?: Maybe<T>, i?: number);
     set(key: string[], v: T, i?: number): void;
-    get(key: string[], i?: number): T | undefined;
+    get(key: string[], i?: number): Maybe<T>;
 }
 //# sourceMappingURL=trie.d.ts.map

package/basic.d.ts

@@ -1,46 +0,0 @@
-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;
-    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=basic.d.ts.map

package/basic.js

@@ -1,233 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result)
-    __defProp(target, key, result);
-  return result;
-};
-import { INotifyMixin } from "@thi.ng/api/mixins/inotify";
-import { isString } from "@thi.ng/checks/is-string";
-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 {
-  opts;
-  current;
-  index = {};
-  routes = new Trie();
-  constructor(config) {
-    this.opts = {
-      authenticator: (match) => match,
-      prefix: "/",
-      separator: "/",
-      trim: true,
-      ...config
-    };
-    this.addRoutes(this.opts.routes);
-    assert(
-      this.routeForID(this.opts.default) !== void 0,
-      `missing config for default route: '${this.opts.default}'`
-    );
-    if (config.initial) {
-      const route = this.routeForID(config.initial);
-      assert(
-        route !== void 0,
-        `missing config for initial route: ${this.opts.initial}`
-      );
-      assert(!route.params, "initial route MUST not be parametric");
-    }
-  }
-  // @ts-ignore: arguments
-  // prettier-ignore
-  addListener(id, fn, scope) {
-  }
-  // @ts-ignore: arguments
-  // prettier-ignore
-  removeListener(id, fn, scope) {
-  }
-  // @ts-ignore: arguments
-  notify(event) {
-  }
-  start() {
-    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(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
-   * 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, ctx) {
-    if (this.opts.trim && src.charAt(src.length - 1) === this.opts.separator) {
-      src = src.substring(0, src.length - 1);
-    }
-    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.opts.default);
-      match = { id: route.id, redirect: true };
-    }
-    if (!equiv(match, this.current)) {
-      this.current = match;
-      this.notify({ id: EVENT_ROUTE_CHANGED, value: match });
-    }
-    return match;
-  }
-  format(...args) {
-    let [id, params, rest] = args;
-    let match;
-    switch (args.length) {
-      case 3:
-        match = { id, params, rest };
-        break;
-      case 2:
-        match = { id, params };
-        break;
-      case 1:
-        match = isString(id) ? { id } : id;
-        break;
-      default:
-        illegalArity(args.length);
-    }
-    const route = this.routeForID(match.id);
-    if (route) {
-      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) {
-            illegalArgs(`missing value for param '${id2}'`);
-          }
-          return p;
-        }
-        return x;
-      });
-      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.index[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);
-      }
-      return acc;
-    }, {});
-    return {
-      ...route,
-      match,
-      params: hasParams ? params : void 0,
-      rest: match.indexOf("+")
-    };
-  }
-  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),
-        {}
-      );
-    }
-    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 match;
-  }
-  validateRouteParams(params, validators) {
-    for (let id in validators) {
-      if (params[id] !== void 0) {
-        const val = validators[id];
-        if (val.coerce) {
-          params[id] = val.coerce(params[id]);
-        }
-        if (val.check && !val.check(params[id])) {
-          return false;
-        }
-      }
-    }
-    return true;
-  }
-  handleRouteFailure() {
-    return true;
-  }
-};
-BasicRouter = __decorateClass([
-  INotifyMixin
-], BasicRouter);
-const isRouteParam = (x) => x[0] === "?";
-export {
-  BasicRouter
-};

package/history.d.ts

@@ -1,31 +0,0 @@
-import type { Fn } from "@thi.ng/api";
-import type { HTMLRouterConfig } from "./api.js";
-import { BasicRouter } from "./basic.js";
-export declare class HTMLRouter<T = any> extends BasicRouter<T> {
-    protected currentPath: string;
-    protected popHandler: Fn<PopStateEvent, void>;
-    protected hashHandler: EventListener;
-    protected useFragment: boolean;
-    protected ignoreHashChange: boolean;
-    constructor(config: HTMLRouterConfig);
-    start(): void;
-    release(): void;
-    /**
-     * 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, 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=history.d.ts.map

package/history.js

@@ -1,91 +0,0 @@
-import { equiv } from "@thi.ng/equiv";
-import { BasicRouter } from "./basic.js";
-class HTMLRouter extends BasicRouter {
-  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 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, 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
-};