feat(routing): add named route path helpers (#149)

* feat: add named route path catalog

* feat: resolve named route path templates

* feat: add named route path helpers

* chore: cover named route path helpers

* chore: code refactoring

* fix: reject duplicate named route paths

Author: imdhemy

src/routing/helpers/create-path-for.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test, vi } from 'vitest';
+import { createPathFor } from './create-path-for';
+import { Get } from './http-verb-helpers';
+import { RouteGroup } from './route-group';
+
+describe('create path for', () => {
+  describe('path resolution', () => {
+    test('it creates a pure path resolver for named routes', () => {
+      const pathFor = createPathFor([
+        Get(
+          '/users/:id',
+          'users.show',
+          vi.fn(async () => undefined),
+        ),
+      ]);
+
+      const path = pathFor('users.show', { id: '42' });
+
+      expect(path).toBe('/users/42');
+    });
+
+    test('it resolves nested grouped route names', () => {
+      const pathFor = createPathFor([
+        RouteGroup(
+          {
+            prefix: '/api',
+            namePrefix: 'api.',
+          },
+          () => [
+            RouteGroup(
+              {
+                prefix: '/users',
+                namePrefix: 'users.',
+              },
+              () => [
+                Get(
+                  '/:id',
+                  'show',
+                  vi.fn(async () => undefined),
+                ),
+              ],
+            ),
+          ],
+        ),
+      ]);
+
+      const path = pathFor('api.users.show', { id: '42' });
+
+      expect(path).toBe('/api/users/42');
+    });
+  });
+
+  describe('errors', () => {
+    test('it throws when the route name does not exist', () => {
+      const pathFor = createPathFor([]);
+
+      const act = () => pathFor('users.show');
+
+      expect(act).toThrow('Unknown route name: users.show.');
+    });
+
+    test('it throws when the named route requires a missing path parameter', () => {
+      const pathFor = createPathFor([
+        Get(
+          '/users/:id',
+          'users.show',
+          vi.fn(async () => undefined),
+        ),
+      ]);
+
+      const act = () => pathFor('users.show');
+
+      expect(act).toThrow('Missing required path parameter: id.');
+    });
+  });
+});

src/routing/helpers/create-path-for.ts

@@ -0,0 +1,25 @@
+import { createPathCatalog } from '@/routing/source/create-path-catalog';
+import { createPathTemplateResolver } from '@/routing/source/resolve-path-template';
+import type { RouteSource } from '@/routing/source/route-source';
+
+type PathParamValue = string | number | boolean;
+type PathParams = Record<string, PathParamValue>;
+type PathFor = (name: string, params?: PathParams) => string;
+
+export function createPathFor(routeSources: RouteSource[]): PathFor {
+  const resolvers = new Map<string, (params?: PathParams) => string>();
+
+  for (const [name, pathTemplate] of createPathCatalog(routeSources)) {
+    resolvers.set(name, createPathTemplateResolver(pathTemplate));
+  }
+
+  return (name: string, params?: PathParams) => {
+    const resolvePath = resolvers.get(name);
+
+    if (resolvePath === undefined) {
+      throw new Error(`Unknown route name: ${name}.`);
+    }
+
+    return resolvePath(params);
+  };
+}

src/routing/index.ts

@@ -1,4 +1,5 @@
 export { Route } from './route';
+export { createPathFor } from './helpers/create-path-for';
 export { RouteGroup } from './helpers/route-group';
 export { Any, Delete, Get, Head, Options, Patch, Post, Put } from './helpers/http-verb-helpers';
 export type { RouteDeclaration } from './route';

src/routing/source/create-path-catalog.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test, vi } from 'vitest';
+import { Get } from '@/routing/helpers/http-verb-helpers';
+import { RouteGroup } from '@/routing/helpers/route-group';
+import { Route } from '@/routing/route';
+import { createPathCatalog } from './create-path-catalog';
+
+describe('create path catalog', () => {
+  test('it collects named route paths from route sources', () => {
+    const routes = [
+      Get(
+        '/users',
+        'users.index',
+        vi.fn(async () => undefined),
+      ),
+      Route({
+        name: 'users.show',
+        method: 'GET',
+        path: '/users/:id',
+        handler: vi.fn(async () => undefined),
+      }),
+    ];
+
+    const catalog = createPathCatalog(routes);
+
+    expect(catalog).toEqual(
+      new Map([
+        ['users.index', '/users'],
+        ['users.show', '/users/:id'],
+      ]),
+    );
+  });
+
+  test('it collects grouped route names using their normalized paths', () => {
+    const routes = [
+      RouteGroup(
+        {
+          prefix: '/api',
+          namePrefix: 'api.',
+        },
+        () => [
+          Get(
+            '/users/:id',
+            'users.show',
+            vi.fn(async () => undefined),
+          ),
+        ],
+      ),
+    ];
+
+    const catalog = createPathCatalog(routes);
+
+    expect(catalog).toEqual(new Map([['api.users.show', '/api/users/:id']]));
+  });
+
+  test('it ignores unnamed routes', () => {
+    const routes = [
+      Get(
+        '/users',
+        vi.fn(async () => undefined),
+      ),
+      Get(
+        '/users/:id',
+        'users.show',
+        vi.fn(async () => undefined),
+      ),
+    ];
+
+    const catalog = createPathCatalog(routes);
+
+    expect(catalog).toEqual(new Map([['users.show', '/users/:id']]));
+  });
+
+  test('it throws when normalized route names are duplicated', () => {
+    const routes = [
+      RouteGroup(
+        {
+          prefix: '/api',
+          namePrefix: 'api.',
+        },
+        () => [
+          Get(
+            '/users',
+            'users.index',
+            vi.fn(async () => undefined),
+          ),
+        ],
+      ),
+      Route({
+        name: 'api.users.index',
+        method: 'GET',
+        path: '/members',
+        handler: vi.fn(async () => undefined),
+      }),
+    ];
+
+    const createCatalog = () => createPathCatalog(routes);
+
+    expect(createCatalog).toThrow('Duplicate route name detected: api.users.index.');
+  });
+});

src/routing/source/create-path-catalog.ts

@@ -0,0 +1,20 @@
+import { normalizeRouteSources } from '@/routing/source/normalize-route-sources';
+import type { RouteSource } from '@/routing/source/route-source';
+
+export function createPathCatalog(routeSources: RouteSource[]): Map<string, string> {
+  const catalog = new Map<string, string>();
+
+  for (const route of normalizeRouteSources(routeSources)) {
+    if (route.name === undefined) {
+      continue;
+    }
+
+    if (catalog.has(route.name)) {
+      throw new Error(`Duplicate route name detected: ${route.name}.`);
+    }
+
+    catalog.set(route.name, route.path);
+  }
+
+  return catalog;
+}

src/routing/source/resolve-path-template.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'vitest';
+import { createPathTemplateResolver, resolvePathTemplate } from './resolve-path-template';
+
+describe('resolve path template', () => {
+  describe('path resolution', () => {
+    test('it returns a static path unchanged', () => {
+      const path = resolvePathTemplate('/users');
+
+      expect(path).toBe('/users');
+    });
+
+    test('it returns an empty path template unchanged', () => {
+      const path = resolvePathTemplate('');
+
+      expect(path).toBe('');
+    });
+
+    test('it replaces a path parameter with its value', () => {
+      const path = resolvePathTemplate('/users/:id', { id: '42' });
+
+      expect(path).toBe('/users/42');
+    });
+
+    test('it replaces multiple path parameters', () => {
+      const path = resolvePathTemplate('/teams/:teamId/users/:userId', {
+        teamId: 'alpha',
+        userId: '42',
+      });
+
+      expect(path).toBe('/teams/alpha/users/42');
+    });
+
+    test('it resolves a template that starts with a path parameter', () => {
+      const path = resolvePathTemplate(':id/details', { id: '42' });
+
+      expect(path).toBe('42/details');
+    });
+
+    test('it creates a reusable resolver for a path template', () => {
+      const resolvePath = createPathTemplateResolver('/teams/:teamId/users/:userId');
+
+      const path = resolvePath({
+        teamId: 'alpha',
+        userId: '42',
+      });
+
+      expect(path).toBe('/teams/alpha/users/42');
+    });
+  });
+
+  describe('errors', () => {
+    test('it throws when a required path parameter is missing', () => {
+      const act = () => resolvePathTemplate('/users/:id');
+
+      expect(act).toThrow('Missing required path parameter: id.');
+    });
+  });
+});

src/routing/source/resolve-path-template.ts

@@ -0,0 +1,84 @@
+type PathParamValue = string | number | boolean;
+type PathParams = Record<string, PathParamValue>;
+type PathSegment =
+  | {
+      kind: 'static';
+      value: string;
+    }
+  | {
+      kind: 'param';
+      key: string;
+    };
+
+export function resolvePathTemplate(pathTemplate: string, params: PathParams = {}): string {
+  return createPathTemplateResolver(pathTemplate)(params);
+}
+
+export function createPathTemplateResolver(pathTemplate: string): (params?: PathParams) => string {
+  const segments = parsePathTemplate(pathTemplate);
+
+  return (params: PathParams = {}) => {
+    let path = '';
+
+    for (const segment of segments) {
+      if (segment.kind === 'static') {
+        path += segment.value;
+        continue;
+      }
+
+      const value = params[segment.key];
+
+      if (value === undefined) {
+        throw new Error(`Missing required path parameter: ${segment.key}.`);
+      }
+
+      path += encodeURIComponent(String(value));
+    }
+
+    return path;
+  };
+}
+
+function parsePathTemplate(pathTemplate: string): PathSegment[] {
+  const segments: PathSegment[] = [];
+  const pattern = /:([A-Za-z0-9_]+)/g;
+  let lastIndex = 0;
+
+  for (const match of pathTemplate.matchAll(pattern)) {
+    const index = match.index as number;
+    const placeholder = match[0];
+    const key = match[1] as string;
+
+    if (index > lastIndex) {
+      segments.push({
+        kind: 'static',
+        value: pathTemplate.slice(lastIndex, index),
+      });
+    }
+
+    segments.push({
+      kind: 'param',
+      key,
+    });
+
+    lastIndex = index + placeholder.length;
+  }
+
+  if (lastIndex < pathTemplate.length) {
+    segments.push({
+      kind: 'static',
+      value: pathTemplate.slice(lastIndex),
+    });
+  }
+
+  if (segments.length === 0) {
+    return [
+      {
+        kind: 'static',
+        value: pathTemplate,
+      },
+    ];
+  }
+
+  return segments;
+}