path-tree-matcher 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# path-tree-matcher
+
+A tiny TypeScript path tree matcher for static routes, optional groups, named parameters, and wildcards.
+
+## Quick usage
+
+```ts
+import { PathTree } from "path-tree-matcher"
+
+const tree = new PathTree()
+
+// register patterns
+tree.setPattern("/a/b{/d}/hello")
+tree.setPattern("/a/b/:name/hello")
+tree.setPattern("/a/b/*all")
+
+// match a pathname
+const matches = tree.match("/a/b/d/hello")
+for (const { pattern, params } of matches) {
+  console.log(pattern)
+  console.log(params)
+}
+```
+
+## What these methods do
+
+- `setPattern(pattern, mapper)` registers a route pattern into the tree
+- `match(pathname)` returns all matching route results with parameter values
+
+### Example behaviors
+
+- `/a/b{/d}/hello` matches both `/a/b/hello` and `/a/b/d/hello`
+- `:name` captures a single named segment
+- `*all` captures a wildcard path segment sequence
+
+### Path syntax
+
+- static text: `/users`
+- named parameter: `/:id`
+- wildcard: `/*rest`
+- optional group: `{/segment}`
+
+### Syntax notes
+- Invalid consecutive params: `/users/:id:action`
+  - unable to split path into two variables: `id`, and `action`
+- Repeated variable name: `/users/:id/follow/:id`
+  - params[":id"] === [value0, value1]
+- Pedantic mode: `/users/action` !== `users/action` !== `users/action/` !== `/users/action/`

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { PathTree } from './path-tree.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { PathTree } from './path-tree.js';

package/dist/path-tree.d.ts

@@ -0,0 +1,36 @@
+export type Token = {
+    token: string;
+    type: "param" | "wildcard";
+} | {
+    token: string;
+    type: "group";
+    groups: Token[];
+} | {
+    token: string;
+    type: "literal";
+};
+export type TokenType = Token["type"];
+export type MatchResult = {
+    pattern: string;
+    params: Record<string, string[]>;
+};
+export type PathNode = {
+    literals: Record<string, PathNode>;
+    params: Record<string, PathNode>;
+    wildcards: Record<string, PathNode>;
+    groups: Record<string, PathNode>;
+    expandedFrom: string[];
+};
+export declare class PathTree {
+    root: PathNode;
+    setPattern(path: string, node?: PathNode, expandedFrom?: string): void;
+    collectLiterals(node: PathNode): {
+        startToken: string;
+        lastNode: PathNode;
+        finished?: true;
+    }[];
+    matchRecursive(path: string, root?: PathNode, param?: Record<string, string[]>): Generator<MatchResult>;
+    match(path: string): MatchResult[];
+    parsePathIntoSegments(pathname: string): Generator<string>;
+    parsePathTree(pathname: string, parent?: string): Token[];
+}

package/dist/path-tree.js

@@ -0,0 +1,271 @@
+function newNode() {
+    return {
+        literals: {},
+        params: {},
+        wildcards: {},
+        groups: {},
+        expandedFrom: [],
+    };
+}
+function lastIndexOf(str, search) {
+    let lastIndex = -1;
+    let index = str.indexOf(search);
+    while (index !== -1) {
+        lastIndex = index;
+        index = str.indexOf(search, index + 1);
+    }
+    return lastIndex;
+}
+export class PathTree {
+    root = newNode();
+    setPattern(path, node = this.root, expandedFrom) {
+        if (!path) {
+            throw new Error("Path cannot be empty");
+        }
+        const tokens = this.parsePathTree(path);
+        let currentNode = node;
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            currentNode[`${token.type}s`][token.token] ??= newNode();
+            switch (token.type) {
+                case "literal": {
+                    currentNode = currentNode.literals[token.token];
+                    break;
+                }
+                case "param": {
+                    if (token.token.length < 2) {
+                        throw new Error(`Parameter token ${token.token} is too short in path ${path}`);
+                    }
+                    if (tokens[i - 1]?.type === "param" || tokens[i - 1]?.type === "wildcard") {
+                        throw new Error(`Unexpected consecutive parameter tokens : ${token.token} in path ${path}`);
+                    }
+                    currentNode = currentNode.params[token.token];
+                    break;
+                }
+                case "wildcard": {
+                    if (token.token.length < 2) {
+                        throw new Error(`Parameter token ${token.token} is too short in path ${path}`);
+                    }
+                    if (tokens[i - 1]?.type === "param" || tokens[i - 1]?.type === "wildcard") {
+                        throw new Error(`Unexpected consecutive parameter tokens : ${token.token} in path ${path}`);
+                    }
+                    currentNode = currentNode.wildcards[token.token];
+                    break;
+                }
+                case "group": {
+                    const joined = [token.token.slice(1, -1), ...tokens.slice(i + 1).map(e => e.token)].join('');
+                    this.setPattern(joined, currentNode.groups[token.token], expandedFrom ?? path);
+                    break;
+                }
+            }
+        }
+        currentNode.expandedFrom.push(expandedFrom ?? path);
+    }
+    collectLiterals(node) {
+        let toIterate = Object.entries(node.literals).map(([token, node]) => ({
+            startToken: token,
+            lastNode: node,
+        }));
+        let iterateNext;
+        const finished = [];
+        while (toIterate.length) {
+            iterateNext = [];
+            for (const c of toIterate) {
+                for (const [token, node] of Object.entries(c.lastNode.literals)) {
+                    iterateNext.push({
+                        startToken: c.startToken + token,
+                        lastNode: node
+                    });
+                }
+                if (Object.entries(c.lastNode.params).length
+                    || Object.entries(c.lastNode.wildcards).length
+                    || Object.entries(c.lastNode.groups).length
+                    || c.lastNode.expandedFrom.length) {
+                    finished.push({ ...c });
+                }
+            }
+            toIterate = iterateNext;
+        }
+        return finished;
+    }
+    *matchRecursive(path, root = this.root, param = {}) {
+        for (const [token, node] of Object.entries(root.literals)) {
+            if (path === token) {
+                yield* node.expandedFrom.map(p => {
+                    return { pattern: p, params: { ...param } };
+                });
+                continue;
+            }
+            if (path.startsWith(token)) {
+                yield* this.matchRecursive(path.slice(token.length), node, { ...param });
+            }
+        }
+        for (const [token, node] of Object.entries(root.params)) {
+            // must only match literal of '/' next
+            const indexOfSlash = path.indexOf("/");
+            const index = indexOfSlash === -1 ? path.length : indexOfSlash;
+            const paramValue = path.slice(0, index);
+            const newParam = {
+                ...param,
+                [token]: [...(param[token] ?? []), paramValue]
+            };
+            if (path.slice(index)) {
+                yield* this.matchRecursive(path.slice(index), node, newParam);
+            }
+            else {
+                yield* node.expandedFrom.map(p => {
+                    return { pattern: p, params: newParam };
+                });
+            }
+        }
+        for (const [token, node] of Object.entries(root.wildcards)) {
+            const nextLiterals = this.collectLiterals(node);
+            if (!nextLiterals.length) {
+                const newParam = {
+                    ...param,
+                    [token]: [...(param[token] ?? []), path]
+                };
+                yield* node.expandedFrom.map(p => {
+                    return { pattern: p, params: newParam };
+                });
+            }
+            else {
+                for (const { startToken, lastNode } of nextLiterals) {
+                    const index = path.indexOf(startToken);
+                    if (index === -1)
+                        continue;
+                    const paramValue = path.slice(0, index);
+                    const newParam = {
+                        ...param,
+                        [token]: [...(param[token] ?? []), paramValue]
+                    };
+                    const nextPath = path.slice(index + startToken.length);
+                    if (nextPath) {
+                        yield* this.matchRecursive(nextPath, lastNode, newParam);
+                    }
+                    else {
+                        yield* lastNode.expandedFrom.map(p => {
+                            return { pattern: p, params: newParam };
+                        });
+                    }
+                }
+                // Also check if the wildcard node itself is a terminal (has expandedFrom)
+                // This handles cases where the wildcard matches everything
+                if (node.expandedFrom.length) {
+                    const newParam = {
+                        ...param,
+                        [token]: [...(param[token] ?? []), path]
+                    };
+                    yield* node.expandedFrom.map(p => {
+                        return { pattern: p, params: newParam };
+                    });
+                }
+            }
+        }
+        for (const [_, node] of Object.entries(root.groups)) {
+            yield* this.matchRecursive(path, node, { ...param });
+        }
+    }
+    match(path) {
+        return Array.from(this.matchRecursive(path));
+    }
+    *parsePathIntoSegments(pathname) {
+        let lower = 0;
+        let upper = 0;
+        let depth = 0;
+        const delimiter = '/';
+        const groupStart = '{';
+        const groupEnd = '}';
+        const paramDelimiter = ':';
+        const wildcardDelimiter = '*';
+        while (upper < pathname.length) {
+            if (pathname[upper] === groupStart) {
+                if (depth === 0) {
+                    if (pathname.slice(lower, upper)) {
+                        yield pathname.slice(lower, upper);
+                    }
+                    lower = upper;
+                }
+                depth++;
+            }
+            else if (pathname[upper] === groupEnd) {
+                depth--;
+            }
+            else if (depth === 0) {
+                if (pathname[upper - 1] === groupEnd) {
+                    yield pathname.slice(lower, upper);
+                    lower = upper;
+                }
+                if (pathname[upper] === delimiter) {
+                    if (pathname.slice(lower, upper)) {
+                        yield pathname.slice(lower, upper);
+                        lower = upper;
+                    }
+                    yield pathname.slice(lower, upper + 1);
+                    lower = upper + 1;
+                }
+                else if (pathname[upper] === paramDelimiter || pathname[upper] === wildcardDelimiter) {
+                    if (pathname.slice(lower, upper)) {
+                        yield pathname.slice(lower, upper);
+                        lower = upper;
+                    }
+                }
+            }
+            upper++;
+        }
+        if (lower < upper) {
+            yield pathname.slice(lower, upper);
+        }
+    }
+    parsePathTree(pathname, parent) {
+        const splitted = this.parsePathIntoSegments(pathname);
+        const matched = [];
+        for (const split of splitted) {
+            if (split.startsWith("{")) {
+                if (!split.endsWith("}")) {
+                    throw new Error(`Unterminated group of ${split} in path ${parent ?? pathname}`);
+                }
+                const group = split.slice(1, -1);
+                matched.push({ token: split, type: "group", groups: this.parsePathTree(group, parent ?? pathname) });
+                continue;
+            }
+            if (split.startsWith(":")) {
+                if (split.includes('*')) {
+                    throw new Error(`Unexpected token * of ${split}... in path ${parent ?? pathname}`);
+                }
+                const [_, ...tokens] = split.split(':');
+                if (tokens.length > 1) {
+                    throw new Error(`Unexpected next tokens : of ${split} in path ${parent ?? pathname}`);
+                }
+                if (!split.slice(1)) {
+                    throw new Error(`Missing label of ${split} in path ${parent ?? pathname}`);
+                }
+                if (matched.at(-1)?.token === "param" || matched.at(-1)?.token === "wildcard") {
+                    throw new Error(`Unexpected next tokens : of ${split} in path ${parent ?? pathname}`);
+                }
+                matched.push({ type: "param", token: split });
+                continue;
+            }
+            if (split.includes('*')) {
+                if (split.includes(':')) {
+                    throw new Error(`Unexpected token : of ${split}... in path ${parent ?? pathname}`);
+                }
+                const [_, ...wildcards] = split.split('*');
+                if (wildcards.length > 1) {
+                    throw new Error(`Unexpected next token * of ${split}... in path ${parent ?? pathname}`);
+                }
+                if (!split.slice(1)) {
+                    throw new Error(`Missing lable of ${split} in path ${parent ?? pathname}`);
+                }
+                if (matched.at(-1)?.token === "param" || matched.at(-1)?.token === "wildcard") {
+                    throw new Error(`Unexpected next tokens : of ${split} in path ${parent ?? pathname}`);
+                }
+                const wildcard = wildcards[0];
+                matched.push({ type: "wildcard", token: `*${wildcard}` });
+                continue;
+            }
+            matched.push({ token: split, type: "literal" });
+        }
+        return matched;
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "path-tree-matcher",
+  "version": "1.0.0",
+  "description": "Build and match path trees with parameters, wildcards, and optional route segments.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "build": "tsgo -p tsconfig.build.json && node ./bin/playground.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ye-yu/ts-path-tree-matcher.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/ye-yu/ts-path-tree-matcher/issues"
+  },
+  "homepage": "https://github.com/ye-yu/ts-path-tree-matcher#readme",
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "@typescript/native-preview": "^7.0.0-dev.20260511.1"
+  }
+}