@kitbag/router 0.26.0 → 0.27.0

package/dist/types/resolved.d.ts

@@ -3,11 +3,25 @@ import { LastInArray } from './utilities';
 import { ExtractRouteStateParamsAsOptional } from './state';
 import { UrlString } from './urlString';
 import { UrlParamsReading } from './url';
-import { GetTitleCallback } from './routeTitle';
+import { GetRouteTitle, GetTitleCallback } from './routeTitle';
+import { Hooks } from '../models/hooks';
 /**
  * The match a route resolved to, which is the last of its matches. Falls back to the wide match type when
  * the matches are not a concrete tuple, so an unregistered router stays assignable.
  */
+export declare const IS_RESOLVED_ROUTE_SYMBOL: unique symbol;
+/**
+ * A type guard for determining if a value is a ResolvedRoute.
+ * @param value - The value to check.
+ * @returns `true` if the value is a ResolvedRoute, otherwise `false`.
+ * @group Type Guards
+ */
+export declare function isResolvedRoute(value: unknown): value is ResolvedRoute & ResolvedRouteInternal;
+export type ResolvedRouteInternal = {
+    [IS_RESOLVED_ROUTE_SYMBOL]: true;
+    hooks: Hooks[];
+    getRouteTitle: GetRouteTitle;
+};
 type MatchedRoute<TMatches> = LastInArray<TMatches, CreatedRouteOptions> extends infer TMatched ? unknown extends TMatched ? CreatedRouteOptions : TMatched : never;
 /**
  * Represents a route that the router has matched to current browser location.
@@ -40,9 +54,15 @@ export type ResolvedRoute<TRoute extends Route = Route> = Readonly<{
      */
     state: ExtractRouteStateParamsAsOptional<TRoute['state']>;
     /**
-     * String value of the resolved URL.
+     * String value of the resolved URL. When the route was matched through an alias this is the alias url,
+     * so navigating to it again stays where the user is.
      */
     href: UrlString;
+    /**
+     * String value of the route's own URL, built from its path and the resolved params. The same as `href`
+     * unless the route was matched through an alias.
+     */
+    canonical: UrlString;
     /**
      * Query value of the route.
      */

package/dist/types/route.d.ts

@@ -12,6 +12,7 @@ import { Hooks } from '../models/hooks';
 import { RouteRedirect } from './redirects';
 import { RouteViews } from './routeViews';
 import { LoadersDataReturnType, RouteLoaders } from './routeLoaders';
+import { RouteAlias } from './routeAlias';
 export declare const IS_ROUTE_SYMBOL: unique symbol;
 export declare function isRoute(value: unknown): value is Route & RouteInternal;
 export type RouteInternal = {
@@ -20,6 +21,7 @@ export type RouteInternal = {
     hooks: Hooks[];
     redirect: RouteRedirect;
     getTitle: GetRouteTitle;
+    aliases: RouteAlias[];
 };
 /**
  * Represents an immutable array of Route instances. Return value of `createRoute`, expected param for `createRouter`.

package/dist/types/routeAlias.d.ts

@@ -0,0 +1,41 @@
+import { Url } from './url';
+/**
+ * What an alias transform is given: the url that matched and the params the alias pattern parsed from it.
+ *
+ * @template TParams - The alias's own params, typed by the alias pattern.
+ */
+export type AliasTransformContext<TParams = Record<string, unknown>> = {
+    /**
+     * The url that matched the alias.
+     */
+    url: string;
+    /**
+     * The params the alias pattern parsed from the url, typed by the alias's own params rather than the
+     * route's.
+     */
+    params: TParams;
+};
+/**
+ * Maps what an alias matched into the params the route declares. Runs synchronously during matching. Any
+ * param the route declares that the alias pattern does not carry must be supplied here.
+ *
+ * @template TParams - The alias's own params.
+ * @template TRouteParams - The params of the route the alias belongs to.
+ */
+export type AliasTransform<TParams = Record<string, unknown>, TRouteParams = Record<string, unknown>> = (context: AliasTransformContext<TParams>) => TRouteParams;
+/**
+ * An alias combined with every ancestor into a single url the router can match, plus the transform that
+ * maps everything that url parsed into the route's params. The transform is the composition of each
+ * level's own transform, so it stays local to the segment each level aliased.
+ */
+export type RouteAlias = {
+    url: Url;
+    transform: (url: string, params: Record<string, unknown>) => Record<string, unknown>;
+};
+/**
+ * An alias a url matched and the params that alias parsed from it.
+ */
+export type RouteAliasMatch = {
+    url: RouteAlias['url'];
+    params: Record<string, unknown>;
+};

package/dist/types/routeCallbackContext.d.ts

@@ -16,6 +16,7 @@ export type RouteCallbackContext<TRoute extends Route> = {
     push: RouterPush<[TRoute] | RouteContextToRoute<TRoute['context']>>;
     replace: RouterReplace<[TRoute] | RouteContextToRoute<TRoute['context']>>;
     update: RouteUpdate<ResolvedRoute<TRoute>>;
+    signal: AbortSignal;
     parent: RouteCallbackParent<TRoute>;
 };
 /**

package/dist/types/routeWithMethods.d.ts

@@ -1,3 +1,4 @@
+import { RouteAddAlias } from './addAlias';
 import { RouteAddLoader } from './addLoader';
 import { RouteAddView } from './addView';
 import { InternalRouteHooks } from './hooks';
@@ -6,11 +7,11 @@ import { CreatedRouteOptions, Route } from './route';
 import { RouteSetTitle } from './routeTitle';
 import { Url } from './url';
 /**
- * A route plus every chainable/available method: addView, addLoader, hooks, redirects, and title. The type
+ * A route plus every chainable/available method: addView, addLoader, addAlias, hooks, redirects, and title. The type
  * level counterpart to `withRouteMethods`.
  *
  * Takes the url and matches rather than an assembled route so that adding a view or a loader can rebuild
  * from them directly. Taking the route would mean re-deriving the url from it on every call, and that
  * reference is what made chained calls nest one inside the last.
  */
-export type RouteWithMethods<TUrl extends Url = Url, TMatches extends CreatedRouteOptions[] = CreatedRouteOptions[]> = Route<TUrl, TMatches> & RouteAddView<TUrl, TMatches> & RouteAddLoader<TUrl, TMatches> & InternalRouteHooks<Route<TUrl, TMatches>, Route<TUrl, TMatches>['context']> & RouteRedirects<Route<TUrl, TMatches>> & RouteSetTitle<Route<TUrl, TMatches>>;
+export type RouteWithMethods<TUrl extends Url = Url, TMatches extends CreatedRouteOptions[] = CreatedRouteOptions[]> = Route<TUrl, TMatches> & RouteAddView<TUrl, TMatches> & RouteAddLoader<TUrl, TMatches> & RouteAddAlias<TUrl, TMatches> & InternalRouteHooks<Route<TUrl, TMatches>, Route<TUrl, TMatches>['context']> & RouteRedirects<Route<TUrl, TMatches>> & RouteSetTitle<Route<TUrl, TMatches>>;

package/dist/types/routerLink.d.ts

@@ -3,7 +3,7 @@ import { UrlString } from './urlString';
 import { ResolvedRoute } from './resolved';
 import { Router } from './router';
 import { RouterPushOptions } from './routerPush';
-export type ToCallback<TRouter extends Router> = (resolve: TRouter['resolve']) => ResolvedRoute | UrlString | undefined;
+export type ToCallback<TRouter extends Router> = (resolve: TRouter['resolve']) => ResolvedRoute | UrlString;
 export type RouterLinkProps<TRouter extends Router> = RouterPushOptions & {
     /**
      * The url string to navigate to or a callback that returns a url string

package/dist/types/routerNavigationInternal.d.ts

@@ -0,0 +1,29 @@
+import { ResolvedRoute } from './resolved';
+import { Routes } from './route';
+import { RedirectStatus } from './router';
+import { RouterPush, RouterPushOptions } from './routerPush';
+import { RouterReplace, RouterReplaceOptions } from './routerReplace';
+import { RouteParamsByKey } from './routeWithParams';
+import { RoutesName } from './routesMap';
+import { RouteStateByName } from './state';
+import { UrlString } from './urlString';
+/**
+ * Push and replace as the router itself calls them, which may carry the status a server responds with for
+ * the redirect. The router exposes {@link RouterPush} and {@link RouterReplace} instead.
+ */
+export type RouterPushOptionsInternal<TState = unknown> = RouterPushOptions<TState> & {
+    redirectStatus?: RedirectStatus;
+};
+export type RouterReplaceOptionsInternal<TState = unknown> = RouterReplaceOptions<TState> & {
+    redirectStatus?: RedirectStatus;
+};
+export type RouterPushInternal<TRoutes extends Routes> = RouterPush<TRoutes> & {
+    <TSource extends RoutesName<TRoutes>>(name: TSource, params: RouteParamsByKey<TRoutes, TSource> | undefined, options: RouterPushOptionsInternal<RouteStateByName<TRoutes, TSource>>): Promise<void>;
+    (route: ResolvedRoute, options: RouterPushOptionsInternal): Promise<void>;
+    (url: UrlString, options: RouterPushOptionsInternal): Promise<void>;
+};
+export type RouterReplaceInternal<TRoutes extends Routes> = RouterReplace<TRoutes> & {
+    <TSource extends RoutesName<TRoutes>>(name: TSource, params: RouteParamsByKey<TRoutes, TSource> | undefined, options: RouterReplaceOptionsInternal<RouteStateByName<TRoutes, TSource>>): Promise<void>;
+    (route: ResolvedRoute, options: RouterReplaceOptionsInternal): Promise<void>;
+    (url: UrlString, options: RouterReplaceOptionsInternal): Promise<void>;
+};

package/dist/types/routerRoute.d.ts

@@ -29,9 +29,13 @@ export type RouterRoute<TRoute extends ResolvedRoute = ResolvedRoute> = {
      */
     readonly update: RouteUpdate<TRoute>;
     /**
-     * String value of the resolved URL.
+     * String value of the resolved URL. When the route was matched through an alias this is the alias url.
      */
     readonly href: TRoute['href'];
+    /**
+     * String value of the route's own URL. The same as `href` unless the route was matched through an alias.
+     */
+    readonly canonical: TRoute['canonical'];
     /**
      * Title of the route.
      */

package/dist/utilities/components.d.ts

@@ -10,9 +10,13 @@ export declare function isAsyncComponent(component: Component): component is Com
  * Decides which of a route's views to load.
  */
 export type AsyncComponentFilter = (match: CreatedRouteOptions, view: RouteView<unknown>) => boolean;
+/**
+ * The async components a route renders, or only those the filter keeps.
+ */
+export declare function getAsyncComponents(route: ResolvedRoute, filter?: AsyncComponentFilter): ComponentWithAsyncLoader[];
 /**
  * Loads the async components a route renders, or only those the filter keeps, so they are ready to render
- * synchronously.
+ * synchronously. Each load is reported on its own.
  */
-export declare function loadAsyncComponents(route: ResolvedRoute, filter?: AsyncComponentFilter): Promise<unknown>;
+export declare function loadAsyncComponents(route: ResolvedRoute, filter?: AsyncComponentFilter): Promise<unknown>[];
 export {};

package/dist/utilities/getRegexMatcher.d.ts

@@ -0,0 +1 @@
+export declare function getRegexMatcher(regex: RegExp): RegExp;

package/dist/utilities/getRegexMatcher.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utilities/percentEncoding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encodes the characters in a param value that would otherwise be read as syntax: a percent sign starts
+ * an escape, and square brackets mark a param. Everything else is left for the url to encode.
+ */
+export declare function encodeParamValue(value: string): string;
+/**
+ * Decodes a param value taken from a url. A malformed escape is kept as written rather than thrown on,
+ * and a missing value stays missing.
+ */
+export declare function decodeParamValue(value: string | undefined): string | undefined;

package/dist/utilities/percentEncoding.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kitbag/router",
   "private": false,
-  "version": "0.26.0",
+  "version": "0.27.0",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/kitbagjs/router/issues"
@@ -46,20 +46,20 @@
     "@kitbag/eslint-config": "1.0.6",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vue/language-core": "^3.3.11",
-    "@vue/test-utils": "^2.5.0",
-    "arktype": "^2.2.3",
+    "@vue/test-utils": "^2.5.1",
+    "arktype": "^2.2.5",
     "eslint": "^9.39.5",
     "globals": "^17.12.0",
-    "happy-dom": "^20.14.3",
+    "happy-dom": "^20.14.5",
     "typedoc": "^0.28.20",
-    "typedoc-plugin-markdown": "^4.13.0",
+    "typedoc-plugin-markdown": "^4.13.1",
     "typedoc-vitepress-theme": "^1.1.4",
     "typescript": "^6.0.3",
     "valibot": "^1.0.0",
     "vite": "^8.2.0",
     "vite-plugin-dts": "^5.0.3",
     "vitepress": "^1.6.4",
-    "vitest": "^5.0.0",
+    "vitest": "^5.0.1",
     "vue-tsc": "^3.3.8",
     "zod": "4.0.0"
   },

package/dist/services/createNavigationIds.d.ts

@@ -1,6 +0,0 @@
-export type NavigationIds = {
-    getNavigationId: () => string;
-    isCurrentNavigationId: (id: string) => boolean;
-    stopNavigationIds: () => void;
-};
-export declare function createNavigationIds(): NavigationIds;