@wavelengthusaf/client-router 0.0.1

package/src/utils/__tests__/matchRoute.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect } from 'vitest';
+import { matchRoute } from '../matchRoute.ts';
+
+function route(path: string, paramNames: string[] = []) {
+    return {
+        routeDefinition: { path },
+        pattern: new RegExp(`^${path.replace(':id', '([^/]+)')}$`),
+        paramNames,
+    };
+}
+
+describe('matchRoute', () => {
+    describe('basic matching', () => {
+        it.each([
+            {
+                routes: [route('/home')],
+                path: '/home',
+                expected: '/home',
+            },
+            {
+                routes: [route('/about')],
+                path: '/about',
+                expected: '/about',
+            },
+        ])('matches static route %#', ({ routes, path, expected }) => {
+            // @ts-expect-error (passing wrong parameters)
+            const result = matchRoute(routes, path);
+
+            expect(result?.routeDefinition.path).toBe(expected);
+        });
+    });
+
+    describe('params', () => {
+        it('extracts single param', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/users/:id' },
+                    pattern: /^\/users\/([^/]+)$/,
+                    paramNames: ['id'],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            const result = matchRoute(routes, '/users/123');
+
+            expect(result?.routeParams).toEqual({
+                id: '123',
+            });
+        });
+
+        it('extracts multiple params', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/a/:x/b/:y' },
+                    pattern: /^\/a\/([^/]+)\/b\/([^/]+)$/,
+                    paramNames: ['x', 'y'],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            const result = matchRoute(routes, '/a/1/b/2');
+
+            expect(result?.routeParams).toEqual({
+                x: '1',
+                y: '2',
+            });
+        });
+    });
+
+    describe('priority', () => {
+        it('returns first matching route', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/users' },
+                    pattern: /^\/users$/,
+                    paramNames: [],
+                },
+                {
+                    routeDefinition: { path: '/users/:id' },
+                    pattern: /^\/users\/([^/]+)$/,
+                    paramNames: ['id'],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            const result = matchRoute(routes, '/users');
+
+            expect(result?.routeDefinition.path).toBe('/users');
+        });
+    });
+
+    describe('no match', () => {
+        it('returns null when no routes match', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/a' },
+                    pattern: /^\/a$/,
+                    paramNames: [],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            const result = matchRoute(routes, '/b');
+
+            expect(result).toBeNull();
+        });
+    });
+
+    describe('decodeURIComponent', () => {
+        it('decodes encoded values', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/search/:query' },
+                    pattern: /^\/search\/([^/]+)$/,
+                    paramNames: ['query'],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            const result = matchRoute(routes, '/search/hello%20world');
+
+            expect(result?.routeParams.query).toBe('hello world');
+        });
+    });
+    
+    describe('undefined capture safety', () => {
+        it('skips param assignment when capture group is undefined', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/test/:id/:missing' },
+                    pattern: /^\/test\/([^/]+)$/,
+                    paramNames: ['id', 'missing'],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            const result = matchRoute(routes, '/test/123');
+
+            expect(result).not.toBeNull();
+            expect(result!.routeParams).toEqual({
+                id: '123',
+                // missing should NOT exist
+            });
+        });
+    });
+
+    describe('malformed encoding', () => {
+        it('does not throw on bad encoding', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/test/:id' },
+                    pattern: /^\/test\/([^/]+)$/,
+                    paramNames: ['id'],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            const bad = () => matchRoute(routes, '/test/%E0%A4%A');
+
+            expect(bad).not.toThrow();
+        });
+    });
+
+    describe('strict matching', () => {
+        it('does not match partial paths', () => {
+            const routes = [
+                {
+                    routeDefinition: { path: '/users/:id' },
+                    pattern: /^\/users\/([^/]+)$/,
+                    paramNames: ['id'],
+                },
+            ];
+
+            // @ts-expect-error (passing wrong parameters)
+            expect(matchRoute(routes, '/users/123/extra')).toBeNull();
+            // @ts-expect-error (passing wrong parameters)
+            expect(matchRoute(routes, '/users')).toBeNull();
+        });
+    });
+});

package/src/utils/compileRoute.ts

@@ -0,0 +1,37 @@
+import type { CompiledRoute, RouteDefinition } from '../models/index.ts';
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function compileRoute(routeDefinition: RouteDefinition): CompiledRoute {
+  const paramNames: string[] = [];
+
+  if (routeDefinition.path === '*') {
+    return {
+      routeDefinition,
+      pattern: /^.*$/,
+      paramNames,
+    };
+  }
+
+  const pattern = routeDefinition.path
+      .split('/')
+      .map((segment) => {
+          const match = /^:([a-zA-Z_]\w*)$/.exec(segment);
+
+        if (match) {
+          paramNames.push(match[1]!);
+          return '([^/]+)';
+        }
+
+        return escapeRegex(segment);
+      })
+      .join('\\/');
+
+  return {
+    routeDefinition,
+    pattern: new RegExp(`^${pattern}$`),
+    paramNames,
+  };
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+import { compileRoute } from './compileRoute.ts';
+import { matchRoute } from './matchRoute.ts';
+
+export { compileRoute, matchRoute };

package/src/utils/matchRoute.ts

@@ -0,0 +1,37 @@
+import type {
+  CompiledRoute,
+  MatchedRoute,
+  RouteParams,
+} from '../models/index.ts';
+
+export function matchRoute(
+    compiledRoutes: CompiledRoute[],
+    pathname: string,
+): MatchedRoute | null {
+  for (const compiledRoute of compiledRoutes) {
+    const match: RegExpMatchArray | null = compiledRoute.pattern.exec(pathname);
+
+    if (!match) continue;
+
+    const routeParams: RouteParams = {};
+
+    compiledRoute.paramNames.forEach((name, i) => {
+      const value: string | undefined = match[i + 1];
+
+      if (value === undefined) return;
+
+      try {
+        routeParams[name] = decodeURIComponent(value);
+      } catch {
+        routeParams[name] = value;
+      }
+    });
+
+    return {
+      routeDefinition: compiledRoute.routeDefinition,
+      routeParams,
+    };
+  }
+
+  return null;
+}

package/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "coverage",
+    "vitest.config.ts",
+    "vitest.setup.ts",
+    "vitest.shims.d.ts",
+    ".storybook",
+    "**/*.test.ts",
+    "src/**/*.stories.ts"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,55 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": ".",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "allowImportingTsExtensions": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    // "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "coverage",
+    "vitest.config.ts",
+    "vitest.setup.ts",
+    "vitest.shims.d.ts",
+    ".storybook"
+  ]
+}

package/vitest.config.ts

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+const dirname =
+  typeof __dirname !== 'undefined'
+    ? __dirname
+    : path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': path.resolve(dirname, './src'),
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./vitest.setup.ts'],
+    include: ['src/**/*.test.ts'],
+    browser: {
+      enabled: false,
+    },
+    coverage: {
+      provider: 'v8',
+      thresholds: {
+        lines: 90,
+        functions: 90,
+        branches: 90,
+        statements: 90,
+      },
+    }
+  },
+});

package/vitest.setup.ts

@@ -0,0 +1,3 @@
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+GlobalRegistrator.register();

package/vitest.shims.d.ts

@@ -0,0 +1 @@
+/// <reference types="@vitest/browser-playwright" />