route-parser-ts 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -11,8 +11,10 @@ export interface RouteParams {
 declare class RouteParser {
     spec: string;
     private tokens;
-    private regex;
-    private paramNames;
+    private pathRegex;
+    private pathParamNames;
+    private queryParamDefs;
+    private hasQueryInSpec;
     constructor(spec: string);
     /**
      * Match a path against this route

package/dist/index.js

@@ -53,10 +53,15 @@ function tokenize(spec) {
             const children = tokenize(optionalContent);
             tokens.push({ type: 'optional', value: optionalContent, children });
         }
+        else if (char === '?' || char === '&') {
+            // Query separator - mark it specially
+            tokens.push({ type: 'querySeparator', value: char });
+            i++;
+        }
         else {
             // Static text - consume until we hit a special character
             let text = '';
-            while (i < spec.length && !':*()'.includes(spec[i])) {
+            while (i < spec.length && !':*()&?'.includes(spec[i])) {
                 text += spec[i];
                 i++;
             }
@@ -67,6 +72,79 @@ function tokenize(spec) {
     }
     return tokens;
 }
+/**
+ * Check if tokens contain any query-related content (? or &)
+ */
+function hasQueryTokens(tokens) {
+    for (const token of tokens) {
+        if (token.type === 'querySeparator')
+            return true;
+        if (token.type === 'optional' && token.children && hasQueryTokens(token.children))
+            return true;
+    }
+    return false;
+}
+/**
+ * Extract query parameter definitions from tokens
+ */
+function extractQueryParams(tokens, optional = false) {
+    const params = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === 'param') {
+            // Look back for the key name (e.g., 'page=' before ':page')
+            let key = token.value; // Default to param name
+            if (i > 0) {
+                const prevToken = tokens[i - 1];
+                if (prevToken.type === 'static' && prevToken.value.endsWith('=')) {
+                    // Extract key from "key="
+                    const match = prevToken.value.match(/([^=&?]+)=$/);
+                    if (match) {
+                        key = match[1];
+                    }
+                }
+            }
+            params.push({ name: token.value, key, optional });
+        }
+        else if (token.type === 'optional' && token.children) {
+            // Recursively extract from optional segments
+            params.push(...extractQueryParams(token.children, true));
+        }
+    }
+    return params;
+}
+/**
+ * Split tokens into path tokens and query tokens
+ */
+function splitPathAndQuery(tokens) {
+    const pathTokens = [];
+    const queryTokens = [];
+    let inQuery = false;
+    for (const token of tokens) {
+        if (token.type === 'querySeparator' && token.value === '?') {
+            inQuery = true;
+            queryTokens.push(token);
+        }
+        else if (inQuery) {
+            queryTokens.push(token);
+        }
+        else if (token.type === 'optional' && token.children) {
+            // Check if this optional contains query content
+            if (hasQueryTokens(token.children)) {
+                // This optional is part of query
+                queryTokens.push(token);
+                inQuery = true; // After query optional, we're in query mode
+            }
+            else {
+                pathTokens.push(token);
+            }
+        }
+        else {
+            pathTokens.push(token);
+        }
+    }
+    return { pathTokens, queryTokens };
+}
 /**
  * Escape special regex characters in a string
  */
@@ -74,9 +152,9 @@ function escapeRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 /**
- * Build a regex pattern from tokens
+ * Build a regex pattern from path tokens only (no query handling)
  */
-function buildRegex(tokens) {
+function buildPathRegex(tokens) {
     let pattern = '';
     const paramNames = [];
     for (const token of tokens) {
@@ -97,19 +175,41 @@ function buildRegex(tokens) {
             case 'optional':
                 // Optional segment - recursively build and wrap in optional group
                 if (token.children) {
-                    const { pattern: childPattern, paramNames: childNames } = buildRegex(token.children);
+                    const { pattern: childPattern, paramNames: childNames } = buildPathRegex(token.children);
                     pattern += `(?:${childPattern})?`;
                     paramNames.push(...childNames);
                 }
                 break;
+            case 'querySeparator':
+                // Should not appear in path tokens
+                break;
         }
     }
     return { pattern, paramNames };
 }
+/**
+ * Parse a query string into key-value pairs
+ */
+function parseQueryString(queryString) {
+    const params = new Map();
+    if (!queryString)
+        return params;
+    // Remove leading ? if present
+    const qs = queryString.startsWith('?') ? queryString.slice(1) : queryString;
+    if (!qs)
+        return params;
+    for (const pair of qs.split('&')) {
+        const [key, value] = pair.split('=');
+        if (key) {
+            params.set(key, value || '');
+        }
+    }
+    return params;
+}
 /**
  * Attempt to reverse a route with given parameters
  */
-function reverseTokens(tokens, params) {
+function reverseTokens(tokens, params, isFirstQueryParam) {
     let result = '';
     for (const token of tokens) {
         switch (token.type) {
@@ -125,10 +225,31 @@ function reverseTokens(tokens, params) {
                 result += String(value);
                 break;
             }
+            case 'querySeparator':
+                // For reverse, we handle ? and & smartly
+                if (token.value === '?') {
+                    if (isFirstQueryParam.value) {
+                        result += '?';
+                        isFirstQueryParam.value = false;
+                    }
+                    else {
+                        result += '&';
+                    }
+                }
+                else if (token.value === '&') {
+                    if (isFirstQueryParam.value) {
+                        result += '?';
+                        isFirstQueryParam.value = false;
+                    }
+                    else {
+                        result += '&';
+                    }
+                }
+                break;
             case 'optional':
                 if (token.children) {
                     // Try to fill the optional segment
-                    const optionalResult = reverseTokens(token.children, params);
+                    const optionalResult = reverseTokens(token.children, params, isFirstQueryParam);
                     if (optionalResult !== false) {
                         result += optionalResult;
                     }
@@ -163,31 +284,61 @@ function canFulfill(tokens, params) {
 class RouteParser {
     spec;
     tokens;
-    regex;
-    paramNames;
+    pathRegex;
+    pathParamNames;
+    queryParamDefs;
+    hasQueryInSpec;
     constructor(spec) {
         if (!spec) {
             throw new Error('spec is required');
         }
         this.spec = spec;
         this.tokens = tokenize(spec);
-        const { pattern, paramNames } = buildRegex(this.tokens);
-        // Match from start to end, with optional query string
-        this.regex = new RegExp(`^${pattern}(?:\\?.*)?$`);
-        this.paramNames = paramNames;
+        // Split into path and query parts
+        const { pathTokens, queryTokens } = splitPathAndQuery(this.tokens);
+        // Build regex for path part only
+        const { pattern, paramNames } = buildPathRegex(pathTokens);
+        this.pathRegex = new RegExp(`^${pattern}(?:\\?.*)?$`);
+        this.pathParamNames = paramNames;
+        // Extract query parameter definitions
+        this.queryParamDefs = extractQueryParams(queryTokens);
+        this.hasQueryInSpec = queryTokens.length > 0;
     }
     /**
      * Match a path against this route
      * Returns params object on match, false otherwise
      */
     match(path) {
-        const match = this.regex.exec(path);
+        // Split path into pathname and query string
+        const queryIndex = path.indexOf('?');
+        const pathname = queryIndex >= 0 ? path.slice(0, queryIndex) : path;
+        const queryString = queryIndex >= 0 ? path.slice(queryIndex + 1) : '';
+        // Match only the pathname part (not query string) to avoid capturing ? in params
+        const match = this.pathRegex.exec(pathname);
         if (!match) {
             return false;
         }
         const params = {};
-        for (let i = 0; i < this.paramNames.length; i++) {
-            params[this.paramNames[i]] = match[i + 1];
+        // Extract path parameters
+        for (let i = 0; i < this.pathParamNames.length; i++) {
+            params[this.pathParamNames[i]] = match[i + 1];
+        }
+        // If route has query params in spec, match them from URL's query string
+        if (this.hasQueryInSpec) {
+            const urlQueryParams = parseQueryString(queryString);
+            for (const paramDef of this.queryParamDefs) {
+                const value = urlQueryParams.get(paramDef.key);
+                if (value !== undefined) {
+                    params[paramDef.name] = value;
+                }
+                else if (paramDef.optional) {
+                    params[paramDef.name] = undefined;
+                }
+                else {
+                    // Required query param not found
+                    return false;
+                }
+            }
         }
         return params;
     }
@@ -200,7 +351,8 @@ class RouteParser {
         if (!this.canFulfillRequired(this.tokens, params)) {
             return false;
         }
-        return reverseTokens(this.tokens, params);
+        const isFirstQueryParam = { value: true };
+        return reverseTokens(this.tokens, params, isFirstQueryParam);
     }
     /**
      * Check if required params (non-optional) can be fulfilled

package/dist/test.js

@@ -107,6 +107,118 @@ describe('Route', () => {
             assert.strictEqual(route.reverse({ id: '456' }), '~/users/456');
         });
     });
+    describe('query parameters', () => {
+        it('should match a path with query string when route has no query params', () => {
+            const route = Route('/foo');
+            assert.deepStrictEqual(route.match('/foo?a=1&b=2'), {});
+        });
+        it('should match a path without query string when route has no query params', () => {
+            const route = Route('/foo');
+            assert.deepStrictEqual(route.match('/foo'), {});
+        });
+        it('should match query parameters in same order', () => {
+            const route = Route('/?a=:a&b=:b');
+            assert.deepStrictEqual(route.match('/?a=1&b=2'), { a: '1', b: '2' });
+        });
+        it('should match query parameters in different order (issue #17)', () => {
+            const route = Route('/?a=:a&b=:b');
+            // This test documents the expected behavior - query order should not matter
+            assert.deepStrictEqual(route.match('/?b=2&a=1'), { a: '1', b: '2' });
+        });
+        it('should match path with parameters and query string', () => {
+            const route = Route('/users/:id');
+            assert.deepStrictEqual(route.match('/users/123?tab=profile'), { id: '123' });
+        });
+        it('should match path with parameters and multiple query params', () => {
+            const route = Route('/users/:id');
+            assert.deepStrictEqual(route.match('/users/123?tab=profile&view=grid'), { id: '123' });
+        });
+    });
+    describe('optional query parameters', () => {
+        it('should match route with optional query part - without query', () => {
+            const route = Route('/search(?q=:query)');
+            assert.deepStrictEqual(route.match('/search'), { query: undefined });
+        });
+        it('should match route with optional query part - with query', () => {
+            const route = Route('/search(?q=:query)');
+            assert.deepStrictEqual(route.match('/search?q=test'), { query: 'test' });
+        });
+        it('should match route with optional query params - without any query', () => {
+            const route = Route('/api/items(?page=:page(&limit=:limit))');
+            assert.deepStrictEqual(route.match('/api/items'), { page: undefined, limit: undefined });
+        });
+        it('should match route with optional query params - with first param only', () => {
+            const route = Route('/api/items(?page=:page(&limit=:limit))');
+            assert.deepStrictEqual(route.match('/api/items?page=1'), { page: '1', limit: undefined });
+        });
+        it('should match route with optional query params - with all params', () => {
+            const route = Route('/api/items(?page=:page(&limit=:limit))');
+            assert.deepStrictEqual(route.match('/api/items?page=1&limit=10'), { page: '1', limit: '10' });
+        });
+        it('should reverse route with optional query part - without params', () => {
+            const route = Route('/search(?q=:query)');
+            assert.strictEqual(route.reverse({}), '/search');
+        });
+        it('should reverse route with optional query part - with params', () => {
+            const route = Route('/search(?q=:query)');
+            assert.strictEqual(route.reverse({ query: 'test' }), '/search?q=test');
+        });
+        it('should reverse route with nested optional query params - partial', () => {
+            const route = Route('/api/items(?page=:page(&limit=:limit))');
+            assert.strictEqual(route.reverse({ page: '1' }), '/api/items?page=1');
+        });
+        it('should reverse route with nested optional query params - all', () => {
+            const route = Route('/api/items(?page=:page(&limit=:limit))');
+            assert.strictEqual(route.reverse({ page: '1', limit: '10' }), '/api/items?page=1&limit=10');
+        });
+        describe('independently optional query parameters', () => {
+            // Pattern: /search(?param1=:param1)(&param2=:param2)
+            // The ? and & should be intelligently handled during matching
+            it('should match with no query params', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                assert.deepStrictEqual(route.match('/search'), { param1: undefined, param2: undefined });
+            });
+            it('should match with first param only', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                assert.deepStrictEqual(route.match('/search?param1=foo'), { param1: 'foo', param2: undefined });
+            });
+            it('should match with second param only', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                // When only second param present, ? should be used instead of &
+                assert.deepStrictEqual(route.match('/search?param2=bar'), { param1: undefined, param2: 'bar' });
+            });
+            it('should match with both params', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                assert.deepStrictEqual(route.match('/search?param1=foo&param2=bar'), { param1: 'foo', param2: 'bar' });
+            });
+            it('should match with both params in different order', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                assert.deepStrictEqual(route.match('/search?param2=bar&param1=foo'), { param1: 'foo', param2: 'bar' });
+            });
+            it('should reverse with no params', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                assert.strictEqual(route.reverse({}), '/search');
+            });
+            it('should reverse with first param only', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                assert.strictEqual(route.reverse({ param1: 'foo' }), '/search?param1=foo');
+            });
+            it('should reverse with both params', () => {
+                const route = Route('/search(?param1=:param1)(&param2=:param2)');
+                assert.strictEqual(route.reverse({ param1: 'foo', param2: 'bar' }), '/search?param1=foo&param2=bar');
+            });
+            // Route defined with params in reverse order - ? and & should not affect matching
+            it('should match when route defines params in reverse order', () => {
+                const route = Route('/search(?param2=:param2)(&param1=:param1)');
+                // URL has param1 first, route has param2 first - should still match
+                assert.deepStrictEqual(route.match('/search?param1=foo&param2=bar'), { param1: 'foo', param2: 'bar' });
+            });
+            it('should match when route and URL have same reverse order', () => {
+                const route = Route('/search(?param2=:param2)(&param1=:param1)');
+                assert.deepStrictEqual(route.match('/search?param2=bar&param1=foo'), { param1: 'foo', param2: 'bar' });
+            });
+        });
+    });
     describe('reverse', () => {
         it('reverses routes without params', () => {
             const route = Route('/foo');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "route-parser-ts",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A TypeScript URL routing library with support for named parameters, splats, and optional segments",
   "type": "module",
   "main": "dist/index.js",