@voltts/router 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@voltts/router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "High-performance radix-tree and static-table HTTP router for Volt",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './trie';
+export * from './router';

package/src/router.ts

@@ -0,0 +1,90 @@
+import { TrieRouter } from './trie';
+import { HttpMethod, RouteMatch, RouterOptions } from './types';
+
+export class Router<T = unknown> {
+  private trie: TrieRouter<T>;
+  private prefix: string;
+
+  constructor(options: RouterOptions = {}, prefix = '') {
+    this.trie = new TrieRouter<T>(options);
+    this.prefix = prefix;
+  }
+
+  private joinPath(prefix: string, path: string): string {
+    const p1 = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+    const p2 = path.startsWith('/') ? path : '/' + path;
+    const full = p1 + p2;
+    return full === '' ? '/' : full;
+  }
+
+  add(method: HttpMethod | string, path: string, handler: T): this {
+    const fullPath = this.joinPath(this.prefix, path);
+    this.trie.add(method, fullPath, handler);
+    return this;
+  }
+
+  get(path: string, handler: T): this {
+    return this.add('GET', path, handler);
+  }
+
+  post(path: string, handler: T): this {
+    return this.add('POST', path, handler);
+  }
+
+  put(path: string, handler: T): this {
+    return this.add('PUT', path, handler);
+  }
+
+  delete(path: string, handler: T): this {
+    return this.add('DELETE', path, handler);
+  }
+
+  patch(path: string, handler: T): this {
+    return this.add('PATCH', path, handler);
+  }
+
+  head(path: string, handler: T): this {
+    return this.add('HEAD', path, handler);
+  }
+
+  options(path: string, handler: T): this {
+    return this.add('OPTIONS', path, handler);
+  }
+
+  all(path: string, handler: T): this {
+    return this.add('ALL', path, handler);
+  }
+
+  group(prefix: string, fn: (group: Router<T>) => void): this {
+    const subRouter = new Router<T>({}, this.joinPath(this.prefix, prefix));
+    fn(subRouter);
+    for (const r of subRouter.getRoutes()) {
+      this.trie.add(r.method, r.path, r.handler);
+    }
+    return this;
+  }
+
+  match(method: HttpMethod | string, path: string): RouteMatch<T> | null {
+    return this.trie.match(method, path);
+  }
+
+  getAllowedMethods(path: string): string[] {
+    return this.trie.getAllowedMethods(path);
+  }
+
+  getRoutes(): Array<{ method: string; path: string; handler: T; pattern: string }> {
+    return this.trie.getRoutes();
+  }
+
+  getStaticGetMap(): Map<string, RouteMatch<T>> {
+    return this.trie.getStaticGetMap();
+  }
+
+  getStaticPostMap(): Map<string, RouteMatch<T>> {
+    return this.trie.getStaticPostMap();
+  }
+
+  getFastGetParamRoutes(): import('./types').FastParamRoute<T>[] {
+    return this.trie.getFastGetParamRoutes();
+  }
+}

package/src/trie.ts

@@ -0,0 +1,344 @@
+import { HttpMethod, RouteConflictError, RouteMatch, FastParamRoute } from './types';
+
+export class TrieNode<T> {
+  segment: string;
+  isParam = false;
+  paramName: string | null = null;
+  isWildcard = false;
+  wildcardName = 'wildcard';
+  staticChildren = new Map<string, TrieNode<T>>();
+  paramChild: TrieNode<T> | null = null;
+  wildcardChild: TrieNode<T> | null = null;
+  handlers = new Map<string, { handler: T; pattern: string }>();
+
+  constructor(segment = '') {
+    this.segment = segment;
+  }
+}
+
+const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
+
+function splitSegments(path: string): string[] {
+  const segments: string[] = [];
+  let start = 0;
+  const len = path.length;
+  while (start < len && path.charCodeAt(start) === 47) start++;
+  while (start < len) {
+    let end = path.indexOf('/', start);
+    if (end === -1) end = len;
+    if (end > start) {
+      segments.push(path.slice(start, end));
+    }
+    start = end + 1;
+  }
+  return segments;
+}
+
+export class TrieRouter<T = unknown> {
+  private root = new TrieNode<T>();
+  private staticRoutes = new Map<string, { handler: T; pattern: string; method: string }>();
+  private staticGetRoutes = new Map<string, RouteMatch<T>>();
+  private staticPostRoutes = new Map<string, RouteMatch<T>>();
+  private fastGetParamRoutes: FastParamRoute<T>[] = [];
+  private allRoutes: Array<{ method: string; path: string; handler: T; pattern: string }> = [];
+
+  constructor(private options: { strictTrailingSlash?: boolean; caseSensitive?: boolean } = {}) {}
+
+  private normalizePath(path: string): string {
+    if (!path.startsWith('/')) {
+      path = '/' + path;
+    }
+    if (!this.options.strictTrailingSlash && path.length > 1 && path.endsWith('/')) {
+      path = path.slice(0, -1);
+    }
+    if (!this.options.caseSensitive) {
+      // Keep case as is for segments, but match case-insensitively if needed
+    }
+    return path;
+  }
+
+  add(method: HttpMethod | string, path: string, handler: T): void {
+    const normalized = this.normalizePath(path);
+    const m = method.toUpperCase();
+    const pattern = normalized;
+
+    this.allRoutes.push({ method: m, path: normalized, handler, pattern });
+
+    // Check if route is pure static (no : or *)
+    const isDynamic = normalized.includes(':') || normalized.includes('*');
+    if (!isDynamic) {
+      const staticKey = `${m}:${normalized}`;
+      const existing = this.staticRoutes.get(staticKey);
+      if (existing) {
+        throw new RouteConflictError(existing.pattern, normalized, m);
+      }
+      this.staticRoutes.set(staticKey, { handler, pattern, method: m });
+
+      const prebuiltMatch: RouteMatch<T> = {
+        handler,
+        params: EMPTY_PARAMS,
+        pattern,
+        method: m,
+      };
+
+      if (m === 'GET') {
+        this.staticGetRoutes.set(normalized, prebuiltMatch);
+      } else if (m === 'POST') {
+        this.staticPostRoutes.set(normalized, prebuiltMatch);
+      }
+    } else {
+      // Fast single suffix-param detection (e.g. /users/:id or /api/items/:slug)
+      const colonIdx = normalized.indexOf(':');
+      if (
+        colonIdx > 0 &&
+        !normalized.includes('*') &&
+        normalized.indexOf(':', colonIdx + 1) === -1 &&
+        normalized.indexOf('/', colonIdx) === -1
+      ) {
+        const prefix = normalized.slice(0, colonIdx);
+        const paramName = normalized.slice(colonIdx + 1);
+        const createParams = (val: string): Record<string, string> => ({ [paramName]: val });
+        if (m === 'GET' || m === 'ALL') {
+          this.fastGetParamRoutes.push({
+            prefix,
+            prefixLen: prefix.length,
+            paramName,
+            createParams,
+            handler,
+            pattern,
+            method: m,
+          });
+        }
+      }
+    }
+
+    // Always insert into Trie for uniform tree lookup and dynamic matching
+    const segments = normalized.split('/').filter(Boolean);
+    let current = this.root;
+
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i]!;
+
+      if (seg.startsWith('*')) {
+        const wildcardName = seg.length > 1 ? seg.slice(1) : 'wildcard';
+        if (!current.wildcardChild) {
+          const node = new TrieNode<T>(seg);
+          node.isWildcard = true;
+          node.wildcardName = wildcardName;
+          current.wildcardChild = node;
+        } else if (current.wildcardChild.wildcardName !== wildcardName) {
+          // Warning or conflict if name differs
+        }
+        current = current.wildcardChild;
+        break; // Wildcard absorbs remaining segments
+      } else if (seg.startsWith(':')) {
+        const paramName = seg.slice(1);
+        if (!current.paramChild) {
+          const node = new TrieNode<T>(seg);
+          node.isParam = true;
+          node.paramName = paramName;
+          current.paramChild = node;
+        } else if (current.paramChild.paramName !== paramName) {
+          throw new RouteConflictError(
+            `:${current.paramChild.paramName}`,
+            `:${paramName}`,
+            m
+          );
+        }
+        current = current.paramChild;
+      } else {
+        let child = current.staticChildren.get(seg);
+        if (!child) {
+          child = new TrieNode<T>(seg);
+          current.staticChildren.set(seg, child);
+        }
+        current = child;
+      }
+    }
+
+    const existingHandler = current.handlers.get(m);
+    if (existingHandler && !isDynamic) {
+      // Handled above in static check
+    } else if (existingHandler && isDynamic) {
+      throw new RouteConflictError(existingHandler.pattern, normalized, m);
+    }
+    current.handlers.set(m, { handler, pattern });
+  }
+
+  match(method: HttpMethod | string, path: string): RouteMatch<T> | null {
+    const normalized = this.normalizePath(path);
+
+    // 1. Ultra-fast direct static route lookup without string concatenation
+    if (method === 'GET') {
+      const match = this.staticGetRoutes.get(normalized);
+      if (match) return match;
+    } else if (method === 'POST') {
+      const match = this.staticPostRoutes.get(normalized);
+      if (match) return match;
+    }
+
+    const m = method.toUpperCase();
+    const staticKey = `${m}:${normalized}`;
+    const staticMatch = this.staticRoutes.get(staticKey);
+    if (staticMatch) {
+      return {
+        handler: staticMatch.handler,
+        params: EMPTY_PARAMS,
+        pattern: staticMatch.pattern,
+        method: m,
+      };
+    }
+
+    // Check HEAD fallback to GET for static routes
+    if (m === 'HEAD') {
+      const getStatic = this.staticRoutes.get(`GET:${normalized}`);
+      if (getStatic) {
+        return {
+          handler: getStatic.handler,
+          params: EMPTY_PARAMS,
+          pattern: getStatic.pattern,
+          method: 'GET',
+        };
+      }
+    }
+
+    // 2. Ultra-fast single-parameter GET route match (avoids trie search and segment splitting)
+    if (m === 'GET') {
+      const fastRoutes = this.fastGetParamRoutes;
+      const count = fastRoutes.length;
+      for (let i = 0; i < count; i++) {
+        const r = fastRoutes[i]!;
+        if (normalized.length > r.prefixLen && normalized.startsWith(r.prefix) && normalized.indexOf('/', r.prefixLen) === -1) {
+          return {
+            handler: r.handler,
+            params: { [r.paramName]: normalized.slice(r.prefixLen) },
+            pattern: r.pattern,
+            method: 'GET',
+          };
+        }
+      }
+    }
+
+    // 3. Dynamic Trie Search using fast segment extraction and non-closure traversal
+    const segments = splitSegments(normalized);
+    const params: Record<string, string> = {};
+
+    const result = this.matchDynamic(this.root, segments, 0, m, params);
+    if (result) {
+      const h = result.node.handlers.get(m) ?? result.node.handlers.get('ALL') ?? (m === 'HEAD' ? result.node.handlers.get('GET') : undefined);
+      if (h) {
+        return {
+          handler: h.handler,
+          params,
+          pattern: h.pattern,
+          method: m,
+        };
+      }
+    }
+
+    // 3. Fallback for OPTIONS (discover allowed methods)
+    if (m === 'OPTIONS') {
+      const allowed = this.getAllowedMethods(normalized);
+      if (allowed.length > 0) {
+        return {
+          handler: null as unknown as T,
+          params,
+          pattern: normalized,
+          method: 'OPTIONS',
+        };
+      }
+    }
+
+    return null;
+  }
+
+  private matchDynamic(
+    node: TrieNode<T>,
+    segments: string[],
+    index: number,
+    m: string,
+    params: Record<string, string>
+  ): { node: TrieNode<T>; pattern: string } | null {
+    if (index === segments.length) {
+      if (node.handlers.has(m) || node.handlers.has('ALL')) {
+        const h = node.handlers.get(m) ?? node.handlers.get('ALL');
+        return { node, pattern: h!.pattern };
+      }
+      if (m === 'HEAD' && node.handlers.has('GET')) {
+        const h = node.handlers.get('GET');
+        return { node, pattern: h!.pattern };
+      }
+      return null;
+    }
+
+    const seg = segments[index]!;
+
+    // 1. Static child match
+    const staticChild = node.staticChildren.get(seg);
+    if (staticChild) {
+      const res = this.matchDynamic(staticChild, segments, index + 1, m, params);
+      if (res) return res;
+    }
+
+    // 2. Param child match
+    if (node.paramChild) {
+      params[node.paramChild.paramName!] = seg;
+      const res = this.matchDynamic(node.paramChild, segments, index + 1, m, params);
+      if (res) return res;
+      delete params[node.paramChild.paramName!];
+    }
+
+    // 3. Wildcard child match
+    if (node.wildcardChild) {
+      const rest = segments.slice(index).join('/');
+      params[node.wildcardChild.wildcardName] = rest;
+      if (node.wildcardChild.handlers.has(m) || node.wildcardChild.handlers.has('ALL')) {
+        const h = node.wildcardChild.handlers.get(m) ?? node.wildcardChild.handlers.get('ALL');
+        return { node: node.wildcardChild, pattern: h!.pattern };
+      }
+      if (m === 'HEAD' && node.wildcardChild.handlers.has('GET')) {
+        const h = node.wildcardChild.handlers.get('GET');
+        return { node: node.wildcardChild, pattern: h!.pattern };
+      }
+      delete params[node.wildcardChild.wildcardName];
+    }
+
+    return null;
+  }
+
+  getAllowedMethods(path: string): string[] {
+    const normalized = this.normalizePath(path);
+    const methods = new Set<string>();
+
+    for (const r of this.allRoutes) {
+      if (r.path === normalized) {
+        methods.add(r.method);
+      }
+    }
+
+    if (methods.size > 0 && methods.has('GET')) {
+      methods.add('HEAD');
+    }
+    if (methods.size > 0) {
+      methods.add('OPTIONS');
+    }
+
+    return Array.from(methods);
+  }
+
+  getRoutes(): Array<{ method: string; path: string; handler: T; pattern: string }> {
+    return [...this.allRoutes];
+  }
+
+  getStaticGetMap(): Map<string, RouteMatch<T>> {
+    return this.staticGetRoutes;
+  }
+
+  getStaticPostMap(): Map<string, RouteMatch<T>> {
+    return this.staticPostRoutes;
+  }
+
+  getFastGetParamRoutes(): FastParamRoute<T>[] {
+    return this.fastGetParamRoutes;
+  }
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+export type HttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'DELETE'
+  | 'PATCH'
+  | 'HEAD'
+  | 'OPTIONS'
+  | 'ALL';
+
+export interface RouteMatch<T = unknown> {
+  handler: T;
+  params: Record<string, string>;
+  pattern: string;
+  method: HttpMethod | string;
+  isZeroArg?: boolean;
+}
+
+export interface FastParamRoute<T = unknown> {
+  prefix: string;
+  prefixLen: number;
+  paramName: string;
+  createParams: (val: string) => Record<string, string>;
+  handler: T;
+  pattern: string;
+  method: string;
+}
+
+export interface RouteRecord<T = unknown> {
+  method: HttpMethod | string;
+  path: string;
+  handler: T;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RouterOptions {
+  strictTrailingSlash?: boolean;
+  caseSensitive?: boolean;
+}
+
+export class RouteConflictError extends Error {
+  constructor(public existingPath: string, public newPath: string, public method: string) {
+    super(`Route conflict detected: '${method} ${newPath}' conflicts with existing route '${method} ${existingPath}'`);
+    this.name = 'RouteConflictError';
+  }
+}

package/test/router.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'bun:test';
+import { RouteConflictError, Router, TrieRouter } from '../src/index';
+
+describe('@voltts/router', () => {
+  it('matches static routes with high speed O(1) table', () => {
+    const router = new Router<() => string>();
+    router.get('/health', () => 'ok');
+    router.post('/login', () => 'logged in');
+
+    const match1 = router.match('GET', '/health');
+    expect(match1).not.toBeNull();
+    expect(match1?.pattern).toBe('/health');
+    expect(match1?.handler()).toBe('ok');
+
+    const match2 = router.match('POST', '/login');
+    expect(match2).not.toBeNull();
+    expect(match2?.pattern).toBe('/login');
+
+    const matchMiss = router.match('GET', '/not-found');
+    expect(matchMiss).toBeNull();
+  });
+
+  it('matches dynamic parameters', () => {
+    const router = new Router();
+    router.get('/users/:id', () => 'user');
+    router.get('/posts/:postId/comments/:commentId', () => 'comment');
+
+    const m1 = router.match('GET', '/users/42');
+    expect(m1).not.toBeNull();
+    expect(m1?.params).toEqual({ id: '42' });
+
+    const m2 = router.match('GET', '/posts/10/comments/99');
+    expect(m2).not.toBeNull();
+    expect(m2?.params).toEqual({ postId: '10', commentId: '99' });
+  });
+
+  it('matches wildcards', () => {
+    const router = new Router();
+    router.get('/static/*', () => 'wildcard');
+    router.get('/files/*filepath', () => 'files');
+
+    const m1 = router.match('GET', '/static/css/style.css');
+    expect(m1).not.toBeNull();
+    expect(m1?.params.wildcard).toBe('css/style.css');
+
+    const m2 = router.match('GET', '/files/images/logo.png');
+    expect(m2).not.toBeNull();
+    expect(m2?.params.filepath).toBe('images/logo.png');
+  });
+
+  it('handles route groups and nested prefixes', () => {
+    const router = new Router();
+
+    router.group('/api/v1', (v1) => {
+      v1.get('/users', () => 'users');
+      v1.group('/admin', (admin) => {
+        admin.post('/settings', () => 'settings');
+      });
+    });
+
+    const m1 = router.match('GET', '/api/v1/users');
+    expect(m1).not.toBeNull();
+    expect(m1?.pattern).toBe('/api/v1/users');
+
+    const m2 = router.match('POST', '/api/v1/admin/settings');
+    expect(m2).not.toBeNull();
+    expect(m2?.pattern).toBe('/api/v1/admin/settings');
+  });
+
+  it('detects route conflicts', () => {
+    const trie = new TrieRouter();
+    trie.add('GET', '/users/:userId', () => {});
+
+    // Conflicting parameter name on the same segment
+    expect(() => {
+      trie.add('GET', '/users/:id', () => {});
+    }).toThrow(RouteConflictError);
+  });
+
+  it('falls back HEAD requests to GET', () => {
+    const router = new Router();
+    router.get('/ping', () => 'pong');
+
+    const headMatch = router.match('HEAD', '/ping');
+    expect(headMatch).not.toBeNull();
+    expect(headMatch?.method).toBe('GET');
+  });
+
+  it('discovers allowed methods for OPTIONS requests', () => {
+    const router = new Router();
+    router.get('/items', () => {});
+    router.post('/items', () => {});
+    router.delete('/items', () => {});
+
+    const allowed = router.getAllowedMethods('/items');
+    expect(allowed).toContain('GET');
+    expect(allowed).toContain('POST');
+    expect(allowed).toContain('DELETE');
+    expect(allowed).toContain('HEAD');
+    expect(allowed).toContain('OPTIONS');
+  });
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.