route-parser-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marko Stijak (https://github.com/mstijak)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# route-parser-ts
+
+A TypeScript URL routing library that parses route patterns and matches them against URL paths. Supports named parameters, splat (wildcard) parameters, and optional segments.
+
+Based on [route-parser](https://github.com/rcs/route-parser) by Ryan Sorensen.
+
+## Installation
+
+```bash
+npm install route-parser-ts
+```
+
+## Usage
+
+```typescript
+import Route from 'route-parser-ts';
+
+// Create a route
+const route = Route('/users/:id');
+
+// Match a path
+const result = route.match('/users/123');
+// => { id: '123' }
+
+// Reverse a route
+const path = route.reverse({ id: '456' });
+// => '/users/456'
+```
+
+## Route Patterns
+
+### Static Paths
+
+Match exact paths:
+
+```typescript
+const route = Route('/foo');
+
+route.match('/foo');      // => {}
+route.match('/foo?query'); // => {} (query strings are ignored)
+route.match('/bar');      // => false
+route.match('/foobar');   // => false
+```
+
+### Named Parameters
+
+Capture path segments with `:param` syntax:
+
+```typescript
+const route = Route('/users/:id');
+
+route.match('/users/123');  // => { id: '123' }
+route.match('/users/abc');  // => { id: 'abc' }
+route.match('/users/');     // => false
+```
+
+Multiple parameters:
+
+```typescript
+const route = Route('/users/:userId/posts/:postId');
+
+route.match('/users/1/posts/42');
+// => { userId: '1', postId: '42' }
+```
+
+### Splat Parameters
+
+Capture multiple path segments with `*param` syntax:
+
+```typescript
+const route = Route('/files/*path');
+
+route.match('/files/images/photo.jpg');
+// => { path: 'images/photo.jpg' }
+```
+
+Multiple splats:
+
+```typescript
+const route = Route('/*a/foo/*b');
+
+route.match('/zoo/woo/foo/bar/baz');
+// => { a: 'zoo/woo', b: 'bar/baz' }
+```
+
+### Mixed Parameters
+
+Combine splats and named parameters:
+
+```typescript
+const route = Route('/books/*section/:title');
+
+route.match('/books/some/section/last-words-a-memoir');
+// => { section: 'some/section', title: 'last-words-a-memoir' }
+```
+
+### Optional Segments
+
+Make parts of the route optional with parentheses:
+
+```typescript
+const route = Route('/users/:id(/style/:style)');
+
+route.match('/users/3');
+// => { id: '3', style: undefined }
+
+route.match('/users/3/style/pirate');
+// => { id: '3', style: 'pirate' }
+```
+
+Optional segments starting with a word:
+
+```typescript
+const route = Route('/things/(option/:first)');
+
+route.match('/things/option/bar');
+// => { first: 'bar' }
+```
+
+Nested optional segments:
+
+```typescript
+const route = Route('/users/:id(/style/:style(/more/:param))');
+
+route.match('/users/3');
+// => { id: '3', style: undefined, param: undefined }
+
+route.match('/users/3/style/pirate');
+// => { id: '3', style: 'pirate', param: undefined }
+
+route.match('/users/3/style/pirate/more/things');
+// => { id: '3', style: 'pirate', param: 'things' }
+```
+
+## API
+
+### `Route(spec: string)`
+
+Creates a new route parser. Can be called with or without `new`.
+
+```typescript
+const route1 = Route('/users/:id');
+const route2 = new Route('/users/:id');
+```
+
+Throws an error if `spec` is not provided.
+
+### `route.match(path: string): object | false`
+
+Matches a path against the route pattern. Returns an object with the captured parameters on success, or `false` if the path doesn't match.
+
+```typescript
+const route = Route('/users/:id');
+
+route.match('/users/123');  // => { id: '123' }
+route.match('/posts/123');  // => false
+```
+
+### `route.reverse(params?: object): string | false`
+
+Generates a path from the route pattern and provided parameters. Returns the path string on success, or `false` if required parameters are missing.
+
+```typescript
+const route = Route('/users/:id/posts/:postId');
+
+route.reverse({ id: '1', postId: '42' });
+// => '/users/1/posts/42'
+
+route.reverse({ id: '1' });
+// => false (missing required parameter)
+```
+
+With optional segments:
+
+```typescript
+const route = Route('/things/(option/:first)');
+
+route.reverse({ first: 'bar' });
+// => '/things/option/bar'
+
+route.reverse();
+// => '/things/' (optional segment omitted)
+```
+
+Falsy values (like `0`) are handled correctly:
+
+```typescript
+const route = Route('/items/:id?page=:page');
+
+route.reverse({ id: 1, page: 0 });
+// => '/items/1?page=0'
+```
+
+## TypeScript
+
+The library is written in TypeScript and includes type definitions.
+
+```typescript
+import Route, { RouteParams } from 'route-parser-ts';
+
+const route = Route('/users/:id');
+const params: RouteParams | false = route.match('/users/123');
+
+if (params) {
+  console.log(params.id); // '123'
+}
+```
+
+## Acknowledgments
+
+This library is a TypeScript reimplementation of [route-parser](https://github.com/rcs/route-parser) by [Ryan Sorensen](https://github.com/rcs). The original library provides the same functionality in JavaScript.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Route Parser - A TypeScript URL routing library
+ * Supports named parameters (:param), splats (*param), and optional segments (())
+ */
+export interface RouteParams {
+    [key: string]: string | number | undefined;
+}
+/**
+ * RouteParser class
+ */
+declare class RouteParser {
+    spec: string;
+    private tokens;
+    private regex;
+    private paramNames;
+    constructor(spec: string);
+    /**
+     * Match a path against this route
+     * Returns params object on match, false otherwise
+     */
+    match(path: string): RouteParams | false;
+    /**
+     * Reverse the route with given parameters
+     * Returns the path string on success, false otherwise
+     */
+    reverse(params?: RouteParams): string | false;
+    /**
+     * Check if required params (non-optional) can be fulfilled
+     */
+    private canFulfillRequired;
+}
+interface RouteParserConstructor {
+    new (spec: string): RouteParser;
+    (spec: string): RouteParser;
+}
+declare const Route: RouteParserConstructor;
+export default Route;
+export { Route, RouteParser };

package/dist/index.js

@@ -0,0 +1,254 @@
+/**
+ * Route Parser - A TypeScript URL routing library
+ * Supports named parameters (:param), splats (*param), and optional segments (())
+ */
+/**
+ * Parse a route specification into tokens
+ */
+function tokenize(spec) {
+    const tokens = [];
+    let i = 0;
+    while (i < spec.length) {
+        const char = spec[i];
+        if (char === ':') {
+            // Named parameter
+            i++;
+            let name = '';
+            while (i < spec.length && /[\w]/.test(spec[i])) {
+                name += spec[i];
+                i++;
+            }
+            if (name) {
+                tokens.push({ type: 'param', value: name });
+            }
+        }
+        else if (char === '*') {
+            // Splat parameter
+            i++;
+            let name = '';
+            while (i < spec.length && /[\w]/.test(spec[i])) {
+                name += spec[i];
+                i++;
+            }
+            if (name) {
+                tokens.push({ type: 'splat', value: name });
+            }
+        }
+        else if (char === '(') {
+            // Optional segment - find matching closing paren
+            i++;
+            let depth = 1;
+            let optionalContent = '';
+            while (i < spec.length && depth > 0) {
+                if (spec[i] === '(')
+                    depth++;
+                else if (spec[i] === ')')
+                    depth--;
+                if (depth > 0) {
+                    optionalContent += spec[i];
+                }
+                i++;
+            }
+            // Recursively parse the optional content
+            const children = tokenize(optionalContent);
+            tokens.push({ type: 'optional', value: optionalContent, children });
+        }
+        else {
+            // Static text - consume until we hit a special character
+            let text = '';
+            while (i < spec.length && !':*()'.includes(spec[i])) {
+                text += spec[i];
+                i++;
+            }
+            if (text) {
+                tokens.push({ type: 'static', value: text });
+            }
+        }
+    }
+    return tokens;
+}
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Build a regex pattern from tokens
+ */
+function buildRegex(tokens) {
+    let pattern = '';
+    const paramNames = [];
+    for (const token of tokens) {
+        switch (token.type) {
+            case 'static':
+                pattern += escapeRegex(token.value);
+                break;
+            case 'param':
+                // Named parameter matches one path segment (no slashes)
+                pattern += '([^/]+)';
+                paramNames.push(token.value);
+                break;
+            case 'splat':
+                // Splat matches any characters including slashes (non-greedy within constraints)
+                pattern += '(.+?)';
+                paramNames.push(token.value);
+                break;
+            case 'optional':
+                // Optional segment - recursively build and wrap in optional group
+                if (token.children) {
+                    const { pattern: childPattern, paramNames: childNames } = buildRegex(token.children);
+                    pattern += `(?:${childPattern})?`;
+                    paramNames.push(...childNames);
+                }
+                break;
+        }
+    }
+    return { pattern, paramNames };
+}
+/**
+ * Attempt to reverse a route with given parameters
+ */
+function reverseTokens(tokens, params) {
+    let result = '';
+    for (const token of tokens) {
+        switch (token.type) {
+            case 'static':
+                result += token.value;
+                break;
+            case 'param':
+            case 'splat': {
+                const value = params[token.value];
+                if (value === undefined || value === null || value === '') {
+                    return false;
+                }
+                result += String(value);
+                break;
+            }
+            case 'optional':
+                if (token.children) {
+                    // Try to fill the optional segment
+                    const optionalResult = reverseTokens(token.children, params);
+                    if (optionalResult !== false) {
+                        result += optionalResult;
+                    }
+                    // If it fails, just skip the optional part (don't return false)
+                }
+                break;
+        }
+    }
+    return result;
+}
+/**
+ * Check if tokens can be fulfilled with the given params
+ */
+function canFulfill(tokens, params) {
+    for (const token of tokens) {
+        if (token.type === 'param' || token.type === 'splat') {
+            const value = params[token.value];
+            if (value === undefined || value === null || value === '') {
+                return false;
+            }
+        }
+        else if (token.type === 'optional' && token.children) {
+            // Optional segments don't need to be fulfilled
+            continue;
+        }
+    }
+    return true;
+}
+/**
+ * RouteParser class
+ */
+class RouteParser {
+    spec;
+    tokens;
+    regex;
+    paramNames;
+    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;
+    }
+    /**
+     * Match a path against this route
+     * Returns params object on match, false otherwise
+     */
+    match(path) {
+        const match = this.regex.exec(path);
+        if (!match) {
+            return false;
+        }
+        const params = {};
+        for (let i = 0; i < this.paramNames.length; i++) {
+            params[this.paramNames[i]] = match[i + 1];
+        }
+        return params;
+    }
+    /**
+     * Reverse the route with given parameters
+     * Returns the path string on success, false otherwise
+     */
+    reverse(params = {}) {
+        // Check if required (non-optional) params can be fulfilled
+        if (!this.canFulfillRequired(this.tokens, params)) {
+            return false;
+        }
+        return reverseTokens(this.tokens, params);
+    }
+    /**
+     * Check if required params (non-optional) can be fulfilled
+     */
+    canFulfillRequired(tokens, params) {
+        for (const token of tokens) {
+            if (token.type === 'param' || token.type === 'splat') {
+                const value = params[token.value];
+                if (value === undefined || value === null || value === '') {
+                    return false;
+                }
+            }
+            // Optional segments don't need to be checked at top level
+        }
+        return true;
+    }
+}
+const RouteParserFactory = function (spec) {
+    if (this instanceof RouteParser) {
+        // Called with 'new'
+        return new RouteParser(spec);
+    }
+    // Called without 'new'
+    return new RouteParser(spec);
+};
+// Set the prototype so instanceof works
+RouteParserFactory.prototype = RouteParser.prototype;
+// Re-implement to allow both calling conventions
+function createRouteParser(spec) {
+    return new RouteParser(spec);
+}
+// Export a wrapper that supports both calling conventions
+const Route = function (spec) {
+    if (!(this instanceof Route)) {
+        return new Route(spec);
+    }
+    if (!spec) {
+        throw new Error('spec is required');
+    }
+    const parser = new RouteParser(spec);
+    // Copy properties to this instance
+    this.spec = parser.spec;
+    this.match = parser.match.bind(parser);
+    this.reverse = parser.reverse.bind(parser);
+    return this;
+};
+// Ensure prototype chain works for instanceof
+Route.prototype = Object.create(Object.prototype);
+Route.prototype.constructor = Route;
+export default Route;
+export { Route, RouteParser };

package/dist/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test.js

@@ -0,0 +1,149 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import Route from './index.js';
+describe('Route', () => {
+    it('should create', () => {
+        assert.ok(Route('/foo'));
+    });
+    it('should create with new', () => {
+        assert.ok(new Route('/foo'));
+    });
+    it('should have proper prototype', () => {
+        const routeInstance = new Route('/foo');
+        assert.ok(routeInstance instanceof Route);
+    });
+    it('should throw on no spec', () => {
+        assert.throws(() => { Route(); }, /spec is required/);
+    });
+    describe('basic', () => {
+        it('should match /foo with a path of /foo', () => {
+            const route = Route('/foo');
+            assert.ok(route.match('/foo'));
+        });
+        it('should match /foo with a path of /foo?query', () => {
+            const route = Route('/foo');
+            assert.ok(route.match('/foo?query'));
+        });
+        it("shouldn't match /foo with a path of /bar/foo", () => {
+            const route = Route('/foo');
+            assert.strictEqual(route.match('/bar/foo'), false);
+        });
+        it("shouldn't match /foo with a path of /foobar", () => {
+            const route = Route('/foo');
+            assert.strictEqual(route.match('/foobar'), false);
+        });
+        it("shouldn't match /foo with a path of /bar", () => {
+            const route = Route('/foo');
+            assert.strictEqual(route.match('/bar'), false);
+        });
+    });
+    describe('basic parameters', () => {
+        it('should match /users/:id with a path of /users/1', () => {
+            const route = Route('/users/:id');
+            assert.ok(route.match('/users/1'));
+        });
+        it('should not match /users/:id with a path of /users/', () => {
+            const route = Route('/users/:id');
+            assert.strictEqual(route.match('/users/'), false);
+        });
+        it('should match /users/:id with a path of /users/1 and get parameters', () => {
+            const route = Route('/users/:id');
+            assert.deepStrictEqual(route.match('/users/1'), { id: '1' });
+        });
+        it('should match deep pathing and get parameters', () => {
+            const route = Route('/users/:id/comments/:comment/rating/:rating');
+            assert.deepStrictEqual(route.match('/users/1/comments/cats/rating/22222'), { id: '1', comment: 'cats', rating: '22222' });
+        });
+    });
+    describe('splat parameters', () => {
+        it('should handle double splat parameters', () => {
+            const route = Route('/*a/foo/*b');
+            assert.deepStrictEqual(route.match('/zoo/woo/foo/bar/baz'), { a: 'zoo/woo', b: 'bar/baz' });
+        });
+    });
+    describe('mixed', () => {
+        it('should handle mixed splat and named parameters', () => {
+            const route = Route('/books/*section/:title');
+            assert.deepStrictEqual(route.match('/books/some/section/last-words-a-memoir'), { section: 'some/section', title: 'last-words-a-memoir' });
+        });
+    });
+    describe('optional', () => {
+        it('should allow and match optional routes without optional part', () => {
+            const route = Route('/users/:id(/style/:style)');
+            assert.deepStrictEqual(route.match('/users/3'), { id: '3', style: undefined });
+        });
+        it('should allow and match optional routes with optional part', () => {
+            const route = Route('/users/:id(/style/:style)');
+            assert.deepStrictEqual(route.match('/users/3/style/pirate'), { id: '3', style: 'pirate' });
+        });
+        it('allows optional branches that start with a word character', () => {
+            const route = Route('/things/(option/:first)');
+            assert.deepStrictEqual(route.match('/things/option/bar'), { first: 'bar' });
+        });
+        describe('nested', () => {
+            it('allows nested', () => {
+                const route = Route('/users/:id(/style/:style(/more/:param))');
+                const result = route.match('/users/3/style/pirate');
+                const expected = { id: '3', style: 'pirate', param: undefined };
+                assert.deepStrictEqual(result, expected);
+            });
+            it('fetches the correct params from nested', () => {
+                const route = Route('/users/:id(/style/:style(/more/:param))');
+                assert.deepStrictEqual(route.match('/users/3/style/pirate/more/things'), { id: '3', style: 'pirate', param: 'things' });
+            });
+        });
+    });
+    describe('tilde prefix', () => {
+        it('should match routes starting with ~/', () => {
+            const route = Route('~/foo');
+            assert.ok(route.match('~/foo'));
+        });
+        it('should match ~/users/:id with parameters', () => {
+            const route = Route('~/users/:id');
+            assert.deepStrictEqual(route.match('~/users/123'), { id: '123' });
+        });
+        it('should reverse routes starting with ~/', () => {
+            const route = Route('~/users/:id');
+            assert.strictEqual(route.reverse({ id: '456' }), '~/users/456');
+        });
+    });
+    describe('reverse', () => {
+        it('reverses routes without params', () => {
+            const route = Route('/foo');
+            assert.strictEqual(route.reverse(), '/foo');
+        });
+        it('reverses routes with simple params', () => {
+            const route = Route('/:foo/:bar');
+            assert.strictEqual(route.reverse({ foo: '1', bar: '2' }), '/1/2');
+        });
+        it('reverses routes with optional params', () => {
+            const route = Route('/things/(option/:first)');
+            assert.strictEqual(route.reverse({ first: 'bar' }), '/things/option/bar');
+        });
+        it('reverses routes with unfilled optional params', () => {
+            const route = Route('/things/(option/:first)');
+            assert.strictEqual(route.reverse(), '/things/');
+        });
+        it("reverses routes with optional params that can't fulfill the optional branch", () => {
+            const route = Route('/things/(option/:first(/second/:second))');
+            assert.strictEqual(route.reverse({ second: 'foo' }), '/things/');
+        });
+        it("returns false for routes that can't be fulfilled", () => {
+            const route = Route('/foo/:bar');
+            assert.strictEqual(route.reverse({}), false);
+        });
+        it("returns false for routes with splat params that can't be fulfilled", () => {
+            const route = Route('/foo/*bar');
+            assert.strictEqual(route.reverse({}), false);
+        });
+        it('allows reversing falsy valued params', () => {
+            const path = '/account/json/wall/post/:id/comments/?start=:start&max=:max';
+            const vars = {
+                id: 50,
+                start: 0,
+                max: 12
+            };
+            assert.strictEqual(Route(path).reverse(vars), '/account/json/wall/post/50/comments/?start=0&max=12');
+        });
+    });
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "route-parser-ts",
+  "version": "1.0.0",
+  "description": "A TypeScript URL routing library with support for named parameters, splats, and optional segments",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "route",
+    "router",
+    "url",
+    "parser",
+    "typescript"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist"
+  ]
+}