feat(matcher): encode query params & parse params when matching

Author: dvcol

README.md

@@ -812,15 +812,15 @@ This means navigation will be a three-step process:
 - Parameters can be optional by adding a question mark.
 
 ```
-/path/:param?
+/path/:param:?
 ```
 
 Parameters can also have a type constraint by adding `:{string}` or `:{number}` before the parameter name.
 
 The router will only match the route if the parameter matches the type constraint.
 
 ```
-/path/:{string}:param?
+/path/:{string}:param:?
 ```
 
 Will match `/path/param` but not `/path/1`.

src/lib/models/matcher.model.ts

@@ -1,4 +1,4 @@
-import type { Route, RouteName, RouteParams } from '~/models/route.model.js';
+import type { Route, RouteName, RouteParams, RouteParamValue } from '~/models/route.model.js';
 
 import { MatcherInvalidPathError, ParsingMissingRequiredParamError } from '~/models/error.model.js';
 
@@ -59,6 +59,20 @@ export function replaceTitleParams(title: string, params: RouteParams = {}) {
     .trim();
 }
 
+const nullRegex = /^\d+(?:\.\d+)?$/;
+const booleanRegex = /^(?:true|false)$/i;
+function decodeValue(value?: string): RouteParamValue {
+  if (value === undefined || value === null) return value;
+  if (nullRegex.test(value)) return Number(value);
+  if (booleanRegex.test(value)) return value.toLowerCase() === 'true';
+  return decodeURIComponent(value);
+}
+
+function encodeValue(value?: RouteParamValue): string {
+  if (value === undefined || value === null) return '';
+  return encodeURIComponent(String(value));
+}
+
 /**
  * Replaces template params with their values
  * @param template
@@ -69,12 +83,12 @@ export function replaceTemplateParams(template: string, params: RouteParams = {}
   return template?.replace(templateParamRegexPrefix, templateParamReplacePrefix).replace(templateParamRegex, (match) => {
     const { param, value, optional } = replacer(match, params);
 
-    if (value === undefined) {
+    if (value === undefined || value === null) {
       if (optional) return '';
       throw new ParsingMissingRequiredParamError({ template, missing: param, params });
     }
 
-    return `/${value}`;
+    return `/${encodeValue(value)}`;
   });
 }
 
@@ -86,8 +100,7 @@ export function replaceTemplateParams(template: string, params: RouteParams = {}
 export function templateToRegex(template: string) {
   let _template = template?.trim();
   if (!_template?.length) throw new MatcherInvalidPathError(template);
-  if (relativePathRegex.test(_template))
-    throw new MatcherInvalidPathError(template, `Path should be absolute, but "${_template}" seems to be relative.`);
+  if (relativePathRegex.test(_template)) throw new MatcherInvalidPathError(template, `Path should be absolute, but "${_template}" seems to be relative.`);
   if (!_template.startsWith('/')) _template = `/${_template}`;
 
   const strRegex = _template
@@ -124,8 +137,8 @@ export function templateToParams(template: string) {
 }
 
 export interface PathParamsResult {
-  params: Record<string, string>;
-  wildcards: Record<string, string>;
+  params: Record<string, string | number | boolean | undefined | null>;
+  wildcards: Record<string, string | number | boolean | undefined | null>;
 }
 export interface IMatcher {
   /**
@@ -182,8 +195,8 @@ export class Matcher<Name extends RouteName = RouteName> implements IMatcher {
       if (index === 0) return;
       if (index > this.#params.length) return;
       const paramName = this.#params[index - 1];
-      if (paramName === '*') result.wildcards[index] = match;
-      else result.params[paramName] = match;
+      if (paramName === '*') result.wildcards[index] = decodeValue(match);
+      else result.params[paramName] = decodeValue(match);
     });
     return result;
   }

src/lib/models/route.model.ts

@@ -25,10 +25,10 @@ export type HistoryState<Key extends string | number = string | number> = {
 type PrimitiveKey = string | number | symbol;
 export type RouteName = PrimitiveKey;
 export type RouteMeta<T = unknown> = Record<PrimitiveKey, T>;
-export type RouteParamValue = string | number | boolean;
+export type RouteParamValue = string | number | boolean | undefined | null;
 export type RouteQuery = Record<string, RouteParamValue>;
 export type RouteParams = Record<string, RouteParamValue>;
-export type RouteWildcards = Record<string, string>;
+export type RouteWildcards = Record<string, RouteParamValue>;
 
 export interface RouteNavigationOptions {
   /**

test/router/matcher.test.ts

@@ -37,6 +37,16 @@ describe('matcher', () => {
       expect(replaceTemplateParams(template, params)).toBe(path);
     });
 
+    it('should replace template params with valid URI component', () => {
+      expect.assertions(1);
+
+      const template = '/base/path/:id/:lastName/end';
+      const params = { id: 12, lastName: "Hello World!@#$%^&*()_+[]{}|;:',.<>?/`~ =" };
+      const path = `/base/path/12/${encodeURIComponent(params.lastName)}/end`;
+
+      expect(replaceTemplateParams(template, params)).toBe(path);
+    });
+
     it('should strip the type from the template path then replace path params with the provided params', () => {
       expect.assertions(1);
 
@@ -684,7 +694,16 @@ describe('matcher', () => {
         expect.assertions(1);
         const matcher = new Matcher(template);
         const path = '/base/path/something/12/path/john/doe/end';
-        const params = { id: '12', name: 'john', lastName: 'doe' };
+        const params = { id: 12, name: 'john', lastName: 'doe' };
+        const wildcards = { 1: 'something' };
+        expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
+      });
+
+      it('should extract params from a location with uri component params', () => {
+        expect.assertions(1);
+        const matcher = new Matcher(template);
+        const params = { id: 12, name: 'john', lastName: "Hello World!@#$%^&*()_+[]{}|;:',.<>?/`~ =" };
+        const path = `/base/path/something/12/path/john/${encodeURIComponent(params.lastName)}/end`;
         const wildcards = { 1: 'something' };
         expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
       });
@@ -693,7 +712,7 @@ describe('matcher', () => {
         expect.assertions(1);
         const matcher = new Matcher('/base/path/:{number}:id/end');
         const path = '/base/path/12/end';
-        const params = { id: '12' };
+        const params = { id: 12 };
         const wildcards = {};
         expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
       });
@@ -729,7 +748,7 @@ describe('matcher', () => {
         expect.assertions(1);
         const matcher = new Matcher('/base/path/:{number}:id/:{string}:name/end');
         const path = '/base/path/12/john/end';
-        const params = { id: '12', name: 'john' };
+        const params = { id: 12, name: 'john' };
         const wildcards = {};
         expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
       });
@@ -738,7 +757,7 @@ describe('matcher', () => {
         expect.assertions(1);
         const matcher = new Matcher('/base/path/:id/:first:?/:name/end');
         const path = '/base/path/12/john/doe/end';
-        const params = { id: '12', first: 'john', name: 'doe' };
+        const params = { id: 12, first: 'john', name: 'doe' };
         const wildcards = {};
         expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
       });
@@ -747,26 +766,26 @@ describe('matcher', () => {
         expect.assertions(1);
         const matcher = new Matcher('/base/path/:id/:first:?/:name/end');
         const path = '/base/path/12/doe/end';
-        const params = { id: '12', first: undefined, name: 'doe' };
+        const params = { id: 12, first: undefined, name: 'doe' };
         const wildcards = {};
         expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
       });
 
       it('should extract params from a location with wildcards', () => {
         expect.assertions(1);
-        const matcher = new Matcher('/base/path/*/segment/*/end');
-        const path = '/base/path/something/segment/else/end';
-        const params = {};
-        const wildcards = { 1: 'something', 2: 'else' };
+        const matcher = new Matcher('/base/:boolean/path/*/segment/*/end');
+        const path = '/base/FALSE/path/something/segment/else/end';
+        const params = { boolean: false };
+        const wildcards = { 2: 'something', 3: 'else' };
         expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
       });
 
       it('should extract params from a location with params and wildcards', () => {
         expect.assertions(1);
-        const matcher = new Matcher('/base/path/*/segment/:id/*');
-        const path = '/base/path/something/segment/12/segment/end';
-        const params = { id: '12' };
-        const wildcards = { 1: 'something', 3: 'segment/end' };
+        const matcher = new Matcher('/base/:boolean/path/*/segment/:id/*');
+        const path = '/base/true/path/something/segment/12/segment/end';
+        const params = { id: 12, boolean: true };
+        const wildcards = { 2: 'something', 4: 'segment/end' };
         expect(matcher.extract(path)).toStrictEqual({ params, wildcards });
       });
 

test/router/router.test.ts

@@ -743,7 +743,7 @@ describe('router', () => {
         expect(route.name).toBe(ParamRoute.name);
         expect(route.path).toBe(path);
         expect(route.route.path).toBe(ParamRoute.path);
-        expect(route.params).toStrictEqual({ id: '2', firstName: 'Jane', lastName: 'Smith' });
+        expect(route.params).toStrictEqual({ id: 2, firstName: 'Jane', lastName: 'Smith' });
       });
 
       it('should resolve a route from a name with default parameters', async () => {
@@ -755,7 +755,7 @@ describe('router', () => {
         expect(route.name).toBe(ParamRoute.name);
         expect(route.path).toBe('/param/1/user/John/Doe');
         expect(route.route.path).toBe(ParamRoute.path);
-        expect(route.params).toStrictEqual({ id: '1', firstName: 'John', lastName: 'Doe' });
+        expect(route.params).toStrictEqual({ id: 1, firstName: 'John', lastName: 'Doe' });
       });
 
       it('should resolve a route from a location with query parameters', async () => {
@@ -792,7 +792,7 @@ describe('router', () => {
         expect(route.name).toBe(ParamQueryRoute.name);
         expect(route.path).toBe(path);
         expect(route.route.path).toBe(ParamQueryRoute.path);
-        expect(route.params).toStrictEqual({ id: '2', firstName: 'Jane', lastName: 'Smith' });
+        expect(route.params).toStrictEqual({ id: 2, firstName: 'Jane', lastName: 'Smith' });
         expect(route.query).toStrictEqual({ page: '2', limit: '5' });
       });