feat(router): improve type inference for routing functions

Author: dvcol

demo/App.svelte

@@ -35,7 +35,7 @@
     Any: 'Any',
   } as const;
 
-  type Routes = (typeof RouteName)[keyof typeof RouteName] | string;
+  type Routes = (typeof RouteName)[keyof typeof RouteName] | (string & {});
 
   let beforeChecked = false;
 

package.json

@@ -121,7 +121,7 @@
     "svelte": ">=5"
   },
   "dependencies": {
-    "@dvcol/common-utils": "^1.31.1",
+    "@dvcol/common-utils": "^1.31.2",
     "@dvcol/svelte-utils": "^1.17.1",
     "svelte": "^5.32.1"
   },

pnpm-lock.yaml

@@ -32,7 +32,7 @@ import { getRouter } from '~/router/context.svelte.js';
  * ```
  */
 export const active: Action<HTMLElement, ActiveOptions | undefined> = (node: HTMLElement, options: ActiveOptions | undefined = {}) => {
-  const router = getRouter();
+  const router = options?.router || getRouter();
   if (!ensureRouter(node, router)) return {};
 
   let _options = $state(options);

src/lib/action/active.action.svelte.ts

@@ -1,11 +1,12 @@
 import type { Action } from 'svelte/action';
 
+import type { RouteName } from '~/models/index.js';
 import type { LinkNavigateFunction, LinkNavigateOptions } from '~/models/link.model.js';
 
 import { getLinkNavigateFunction, getResolveFunction, normalizeLinkAttributes } from '~/models/link.model.js';
 import { Logger } from '~/utils/logger.utils.js';
 
-export type LinkActionOptions = LinkNavigateOptions;
+export type LinkActionOptions<Name extends RouteName = RouteName, Path extends string = string> = LinkNavigateOptions<Name, Path>;
 
 /**
  * A svelte action to add to an element to navigate to a new location using the router.

src/lib/action/link.action.svelte.ts

@@ -1,12 +1,13 @@
 import type { Action } from 'svelte/action';
 
+import type { RouteName } from '~/models/index.js';
 import type { LinkNavigateFunction, LinkNavigateOptions } from '~/models/link.model.js';
 
 import { getLinkNavigateFunction, getResolveFunction, parseBooleanAttribute } from '~/models/link.model.js';
 import { Logger } from '~/utils/logger.utils.js';
 
 export type NodeConditionFn = (node: HTMLElement) => boolean;
-export interface LinksActionOptions {
+export interface LinksActionOptions<Name extends RouteName = RouteName, Path extends string = string> {
   /**
    * Whether the target node should be considered a link.
    */
@@ -18,7 +19,7 @@ export interface LinksActionOptions {
   /**
    * The navigate options to use for the navigation.
    */
-  navigate?: LinkNavigateOptions;
+  navigate?: LinkNavigateOptions<Name, Path>;
 }
 
 function isLinkNode(node: HTMLElement, apply?: LinksActionOptions['apply']): boolean {

src/lib/action/links.action.svelte.ts

@@ -8,7 +8,7 @@ import { Matcher } from '~/models/index.js';
 import { getRouter } from '~/router/context.svelte.js';
 
 export function useActive(options: ActiveOptions): Attachment {
-  const router = getRouter();
+  const router = options?.router || getRouter();
 
   return (element) => {
     if (!ensureRouter(element, router)) return;

src/lib/attachment/active.attachment.svelte.ts

@@ -5,6 +5,11 @@ import type { IRouter } from '~/models/router.model.js';
 import { Logger } from '~/utils/logger.utils.js';
 
 export interface ActiveOptions<Name extends RouteName = RouteName> {
+  /**
+   * Optional router instance to use for matching.
+   * If not provided, the router will be extracted from the context.
+   */
+  router?: IRouter<Name>;
   /**
    * Route name to match against.
    * This takes precedence over the path option.

src/lib/models/action.model.ts

@@ -1,5 +1,5 @@
 import type { CommonRouteNavigation, ResolvedRoute, RouteName, RouteNavigation } from '~/models/route.model.js';
-import type { ResolvedRouterLocationSnapshot, RouterNavigationOptions } from '~/models/router.model.js';
+import type { IRouter, ResolvedRouterLocationSnapshot, RouterNavigationOptions } from '~/models/router.model.js';
 
 import { resolveComponent } from '@dvcol/svelte-utils/component';
 
@@ -79,7 +79,7 @@ export type LinkNavigateFunction = <Action extends 'replace' | 'push' | 'resolve
  * @throws {MissingRouterContextError} - If the router context is not found
  */
 export function getLinkNavigateFunction(options: LinkNavigateOptions = {}): LinkNavigateFunction {
-  const router = getRouter();
+  const router = options?.router || getRouter();
   if (!router) throw new MissingRouterContextError();
 
   return async (event, node, action) => {
@@ -155,8 +155,13 @@ export function normalizeLinkAttributes(node: HTMLElement, options: LinkNavigate
   return { node, options };
 }
 
-export interface LinkNavigateOptions<Name extends RouteName = RouteName> extends CommonRouteNavigation,
+export interface LinkNavigateOptions<Name extends RouteName = RouteName, Path extends string = string> extends CommonRouteNavigation<Path>,
   RouterNavigationOptions {
+  /**
+   * Optional router instance to use for matching.
+   * If not provided, the router will be extracted from the context.
+   */
+  router?: IRouter<Name>;
   /**
    * Whether to resolve the link on hover or focus.
    * If a string is provided, it will be used as the name of the view to resolve instead of the link's target.
@@ -173,7 +178,7 @@ export interface LinkNavigateOptions<Name extends RouteName = RouteName> extends
   /**
    * The path of the route to navigate to.
    */
-  path?: string;
+  path?: Path;
   /**
    * Whether the link is disabled.
    */

src/lib/models/link.model.ts

@@ -137,8 +137,8 @@ export function templateToParams(template: string) {
 }
 
 export interface PathParamsResult {
-  params: Record<string, string | number | boolean | undefined | null>;
-  wildcards: Record<string, string | number | boolean | undefined | null>;
+  params: Record<string, string | number | boolean | undefined>;
+  wildcards: Record<string, string | number | boolean | undefined>;
 }
 export interface IMatcher {
   /**