@b9g/match-pattern 0.1.6 → 0.2.0-beta.0

package/README.md

@@ -1,10 +1,15 @@
 # MatchPattern
 
-Extended URLPattern for better routing with enhanced search parameter handling.
+High-performance URLPattern-compatible implementation for web routing with enhanced search parameter handling.
 
 ## Overview
 
- MatchPattern is a subclass of URLPattern that fixes its limitations for web routing while maintaining full backward compatibility. It enhances URLPattern with order-independent search parameters, unified parameter extraction, and convenient string pattern syntax.
+This package provides two classes:
+
+- **URLPattern**: A 100% WPT-compliant implementation that's ~40-60x faster than the polyfill/native
+- **MatchPattern**: Same performance with routing enhancements (order-independent search params, unified `params` object)
+
+Both compile patterns directly to RegExp in a single pass, bypassing the multi-stage pipeline used by polyfill/native implementations.
 
 ## Installation
 
@@ -15,19 +20,45 @@ npm install @b9g/match-pattern
 ## Basic Usage
 
 ```javascript
-import { MatchPattern } from '@b9g/match-pattern';
+import {MatchPattern, URLPattern} from '@b9g/match-pattern';
+
+// URLPattern: 100% WPT-compliant, ~60x faster than polyfill/native
+const strict = new URLPattern({ pathname: '/api/posts/:id' });
 
-// Create patterns with enhanced string syntax
+// MatchPattern: Same performance + DX improvements
 const pattern = new MatchPattern('/api/posts/:id&format=:format');
 const url = new URL('http://example.com/api/posts/123?format=json&page=1');
 
 if (pattern.test(url)) {
   const result = pattern.exec(url);
-  console.log(result.params); 
+  console.log(result.params);
   // { id: '123', format: 'json', page: '1' }
 }
 ```
 
+## Performance
+
+MatchPattern compiles patterns directly to optimized RegExp in a single pass, while the URLPattern polyfill uses a multi-stage pipeline (lexer → parser → RegExp generator). This results in **~40-60x faster** pattern matching:
+
+| Benchmark | URLPattern | MatchPattern | Polyfill | Native |
+|-----------|------------|--------------|----------|--------|
+| Static test() | 37ns | 72ns | 3.02µs | 2.32µs |
+| Dynamic exec() | 304ns | 483ns | 2.45µs | 2.42µs |
+| Construction | 760ns | 634ns | 16.58µs | 16.17µs |
+
+*Benchmarks run on Apple M1, Bun 1.3.3. See `bench/urlpattern.bench.js`.*
+
+MatchPattern adds ~35ns overhead for order-independent search parameter matching - a feature the [URLPattern spec explicitly doesn't support](https://github.com/whatwg/urlpattern/discussions/60).
+
+All URLPattern syntax is fully supported including:
+- Named parameters with regex constraints: `:id(\d+)`
+- Optional parameters: `:id?`
+- Repeat modifiers: `:path+`, `:path*`
+- Wildcards: `*`
+- Regex groups: `(\d+)`
+- Explicit delimiters: `{/old}?`
+- Escaped characters: `\.`
+
 ## Key Differences from URLPattern
 
 ### 1. Order-Independent Search Parameters
@@ -35,25 +66,36 @@ if (pattern.test(url)) {
 URLPattern requires exact parameter order. MatchPattern allows any order:
 
 ```javascript
-const pattern = new MatchPattern({ search: 'type=:type&sort=:sort' });
+const pattern = new MatchPattern({search: 'type=:type&sort=:sort'});
 
 // URLPattern: Only first URL matches
 // MatchPattern: Both URLs match
-pattern.test('/?type=blog&sort=date');  // ✅ Both: true  
-pattern.test('/?sort=date&type=blog');  // ✅ MatchPattern: true, URLPattern: false
+pattern.test('/?type=blog&sort=date');  // Both: true
+pattern.test('/?sort=date&type=blog');  // MatchPattern: true, URLPattern: false
 ```
 
 ### 2. Non-Exhaustive Search Matching
 
-URLPattern rejects extra parameters. MatchPattern captures them:
+URLPattern uses greedy capture that lumps extra params into the last parameter value. MatchPattern properly parses them:
 
 ```javascript
-const pattern = new MatchPattern({ search: 'q=:query' });
+const pattern = new MatchPattern({search: 'q=:query'});
+
+// URLPattern greedy capture issue
+const urlPattern = new URLPattern({search: 'q=:query'});
+urlPattern.exec('?q=hello&page=1').search.groups;  // { query: "hello&page=1" }
+
+// MatchPattern proper parsing
 const result = pattern.exec('/?q=hello&page=1&limit=10');
+console.log(result.params);  // {q: 'hello', page: '1', limit: '10'}
+```
+
+Required parameters must be present, but extra parameters are allowed:
 
-// URLPattern: Fails or captures 'hello&page=1&limit=10' as query value
-// MatchPattern: { q: 'hello', page: '1', limit: '10' }
-console.log(result.params);
+```javascript
+pattern.test('/search');                         // false (q missing)
+pattern.test('/search?q=hello');                 // true
+pattern.test('/search?q=hello&page=1&limit=10'); // true (extras captured)
 ```
 
 ### 3. Unified Parameter Object
@@ -66,18 +108,18 @@ const result = pattern.exec('/api/v1/posts/123?format=json&page=1');
 
 // URLPattern: result.pathname.groups + result.search.groups (separate)
 // MatchPattern: result.params (unified)
-console.log(result.params); // { version: 'v1', id: '123', format: 'json', page: '1' }
+console.log(result.params); // {version: 'v1', id: '123', format: 'json', page: '1'}
 ```
 
 ### 4. Enhanced String Pattern Syntax
 
-MatchPattern supports convenient string patterns with `&` separator:
+It's not possible to separate pathname from search with `?` because the syntax is used to indicate optionality, so MatchPattern supports convenient string patterns with `&` separator:
 
 ```javascript
-// Pathname only
+// Pathname only (URLPattern throws a TypeError when passing a relative path without a baseURL)
 new MatchPattern('/api/posts/:id')
 
-// Pathname with search parameters  
+// Pathname with search parameters
 new MatchPattern('/api/posts/:id&format=:format&page=:page')
 
 // Search parameters only
@@ -87,9 +129,9 @@ new MatchPattern('&q=:query&sort=:sort')
 new MatchPattern('https://api.example.com/v1/posts/:id&format=:format')
 
 // Object syntax (same as URLPattern, enhanced behavior)
-new MatchPattern({ 
+new MatchPattern({
   pathname: '/api/posts/:id',
-  search: 'format=:format' 
+  search: 'format=:format'
 })
 ```
 
@@ -100,69 +142,155 @@ MatchPattern does not automatically normalize trailing slashes. Use explicit pat
 ```javascript
 // Exact matching
 const exactPattern = new MatchPattern('/api/posts/:id');
-exactPattern.test('/api/posts/123');   // ✅ true
-exactPattern.test('/api/posts/123/');  // ❌ false
+exactPattern.test('/api/posts/123');   // true
+exactPattern.test('/api/posts/123/');  // false
 
 // Optional trailing slash
 const flexiblePattern = new MatchPattern('/api/posts/:id{/}?');
-flexiblePattern.test('/api/posts/123');   // ✅ true
-flexiblePattern.test('/api/posts/123/');  // ✅ true
+flexiblePattern.test('/api/posts/123');   // true
+flexiblePattern.test('/api/posts/123/');  // true
 ```
 
-## Known Limitations
+## Implementation Notes
+
+### Direct RegExp Compilation
 
-### Cross-Implementation Differences
+MatchPattern compiles URLPattern syntax directly to RegExp in a single pass, while the URLPattern polyfill uses a multi-stage pipeline (lexer → parser → RegExp generator). This approach provides:
+- **Performance**: ~40-60x faster than the URLPattern polyfill and native implementations
+- **Consistency**: Same behavior across all JavaScript runtimes
+- **Zero dependencies**: No polyfill required
+- **Simplicity**: Direct pattern-to-RegExp compilation with minimal overhead
 
-The polyfill and native browser implementations can return different results for edge cases.
+### URLPattern Spec Compliance
 
-**Issue:** [kenchris/urlpattern-polyfill#129](https://github.com/kenchris/urlpattern-polyfill/issues/129)
+The `URLPattern` class passes 100% of the Web Platform Tests (755 tests). It implements the full URLPattern specification:
 
-**Impact:** Results may vary between Node.js, browsers, and other runtimes.
+- Named parameters: `:id`, `:id(\d+)`
+- Optional parameters: `:id?`
+- Repeat modifiers: `:path+`, `:path*`
+- Wildcards: `*`
+- Regex groups: `(\d+)`
+- Explicit delimiters: `{/old}?`
+- Escaped characters: `\.`
+- Protocol, hostname, port, pathname, search, and hash matching
+- baseURL parameter for relative pattern resolution
+- ignoreCase option
 
-**Testing:** Use Playwright for cross-browser validation in production applications.
+`MatchPattern` intentionally deviates from strict spec compliance in two areas to provide better routing ergonomics:
+- Allows relative patterns without baseURL (convenience for routing)
+- Order-independent search parameter matching
+
+## Exports
+
+### Classes
+
+- `URLPattern` - 100% WPT-compliant URLPattern implementation
+- `MatchPattern` - URLPattern with routing enhancements (order-independent search params, unified params)
+
+### Types
 
-### TypeScript Compatibility
+- `MatchPatternResult` - Result type for MatchPattern.exec()
+- `URLPatternOptions` - Options for URLPattern constructor (ignoreCase, etc.)
+- `ParsedPattern` - Parsed pattern structure
+- `PatternSegment` - Individual segment of a parsed pattern
+- `CompiledPattern` - Internal compiled pattern representation
 
-Node.js and polyfill URLPattern types have slight differences in their TypeScript definitions.
+### Utility Functions
 
-**Issue:** [kenchris/urlpattern-polyfill#135](https://github.com/kenchris/urlpattern-polyfill/issues/135)
+Advanced functions for pattern inspection and compilation for optimized routers
 
-**Solution:** MatchPattern uses canonical WHATWG specification types internally.
+- `isSimplePattern(pathname: string): boolean` - Check if pathname is a simple pattern (no regex features)
+- `parseSimplePattern(pathname: string): ParsedPattern | null` - Parse a simple pattern into segments
+- `compilePathname(pathname: string, options?: object): CompiledPattern` - Compile a pathname pattern to RegExp
 
 ## API Reference
 
-### Constructor
+### URLPattern
 
 ```typescript
-new MatchPattern(input: string | URLPatternInit, baseURL?: string)
+class URLPattern {
+  constructor(input?: string | URLPatternInit, baseURL?: string, options?: URLPatternOptions)
+
+  test(input: string | URL | URLPatternInit, baseURL?: string): boolean
+  exec(input: string | URL | URLPatternInit, baseURL?: string): URLPatternResult | null
+
+  readonly protocol: string
+  readonly username: string
+  readonly password: string
+  readonly hostname: string
+  readonly port: string
+  readonly pathname: string
+  readonly search: string
+  readonly hash: string
+}
+```
+
+### MatchPattern
+
+```typescript
+class MatchPattern {
+  constructor(input: string | URLPatternInit, baseURL?: string)
+
+  test(input: string | URL): boolean
+  exec(input: string | URL): MatchPatternResult | null
+}
 ```
 
-### Methods
+### Utility Functions
+
+Advanced functions for pattern inspection and compilation (used by router optimizations):
 
 ```typescript
-// Enhanced methods with unified params
-test(input: string | URL): boolean
-exec(input: string | URL): MatchPatternResult | null
+// Check if a pathname pattern contains only literal segments and named parameters
+function isSimplePattern(pathname: string): boolean
+
+// Parse a simple pattern into its component segments
+function parseSimplePattern(pathname: string): ParsedPattern | null
+
+// Compile a pathname pattern to optimized RegExp
+function compilePathname(
+  pathname: string,
+  options?: { ignoreCase?: boolean }
+): CompiledPattern
 ```
 
 ### Types
 
 ```typescript
 interface MatchPatternResult extends URLPatternResult {
-  params: Record<string, string>;  // Unified parameters from all sources
+  params: Record<string, string>;  // Unified parameters from pathname and search
+}
+
+interface URLPatternOptions {
+  ignoreCase?: boolean;  // Case-insensitive matching
+}
+
+interface ParsedPattern {
+  segments: PatternSegment[];
+  paramNames: string[];
+}
+
+type PatternSegment =
+  | { type: 'literal'; value: string }
+  | { type: 'param'; name: string; pattern?: string }
+  | { type: 'wildcard' }
+  | { type: 'group'; segments: PatternSegment[] }
+
+interface CompiledPattern {
+  regexp: RegExp;
+  paramNames: string[];
 }
 ```
 
 ## Compatibility
 
-- **Node.js**: 18+ (with URLPattern support) or any version with polyfill
-- **Browsers**: Chrome 95+, or any browser with polyfill  
-- **Runtimes**: Deno, Bun, Cloudflare Workers, Edge Runtime
+- **Runtimes**: Node, Deno, Bun, Cloudflare Workers, Edge Runtime, any JavaScript environment
+- **Browsers**: All browsers (no polyfill required)
 - **TypeScript**: 5.0+ recommended
 
 ## Contributing
 
-MatchPattern follows the [WHATWG URLPattern specification](https://urlpattern.spec.whatwg.org/) while extending it for routing use cases. 
+MatchPattern follows the [WHATWG URLPattern specification](https://urlpattern.spec.whatwg.org/) while extending it for routing use cases.
 
 Report issues related to:
 - URLPattern compatibility problems
@@ -171,10 +299,4 @@ Report issues related to:
 
 ## License
 
-MIT - see LICENSE file for details.
-
-## Acknowledgments
-
-- URLPattern specification by WHATWG
-- [urlpattern-polyfill](https://github.com/kenchris/urlpattern-polyfill) by Ken Christensen
-- Web Platform community
+MIT

package/package.json

@@ -1,34 +1,25 @@
 {
   "name": "@b9g/match-pattern",
-  "version": "0.1.6",
+  "version": "0.2.0-beta.0",
   "devDependencies": {
-    "@b9g/libuild": "^0.1.11",
-    "bun-types": "latest"
-  },
-  "peerDependencies": {
-    "urlpattern-polyfill": "^10.0.0"
-  },
-  "peerDependenciesMeta": {
-    "urlpattern-polyfill": {
-      "optional": true
-    }
+    "@b9g/libuild": "^0.1.18"
   },
   "type": "module",
-  "types": "src/match-pattern.d.ts",
-  "module": "src/match-pattern.js",
+  "types": "src/index.d.ts",
+  "module": "src/index.js",
   "exports": {
-    "./match-pattern": {
-      "types": "./src/match-pattern.d.ts",
-      "import": "./src/match-pattern.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
     },
-    "./match-pattern.js": {
-      "types": "./src/match-pattern.d.ts",
-      "import": "./src/match-pattern.js"
+    "./index": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
     },
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./src/match-pattern.d.ts",
-      "import": "./src/match-pattern.js"
-    }
+    "./index.js": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./package.json": "./package.json"
   }
 }

package/src/index.d.ts

@@ -0,0 +1,168 @@
+/**
+ * High-performance URLPattern-compatible implementation for web routing with
+ * enhanced search parameter handling.
+ */
+/**
+ * Result of pattern matching
+ */
+export interface MatchPatternResult {
+    params: Record<string, string>;
+    pathname: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    search: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    protocol: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    hostname: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    port: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    username: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    password: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    hash: {
+        input: string;
+        groups: Record<string, string>;
+    };
+    inputs: (string | URLPatternInit)[];
+}
+/**
+ * Compiled pattern for fast matching
+ */
+export interface CompiledPattern {
+    regex: RegExp;
+    paramNames: string[];
+    hasWildcard: boolean;
+}
+/**
+ * Segment types for parsed patterns
+ */
+export type PatternSegment = {
+    type: "static";
+    value: string;
+} | {
+    type: "param";
+    name: string;
+} | {
+    type: "wildcard";
+};
+/**
+ * Result of parsing a simple pattern
+ */
+export interface ParsedPattern {
+    segments: PatternSegment[];
+    paramNames: string[];
+    hasWildcard: boolean;
+}
+/**
+ * Check if a pathname pattern is "simple" (can be handled by radix tree)
+ * Simple patterns only have:
+ * - Static segments: /api/users
+ * - Basic named params: :id, :slug
+ * - Trailing wildcard: /*
+ *
+ * Complex patterns (return false) have:
+ * - Param constraints: :id(\d+)
+ * - Param modifiers: :path+, :path*, :id?
+ * - Regex groups: (\d+)
+ * - Optional groups: {/prefix}?
+ * - Escaped characters: \.
+ */
+export declare function isSimplePattern(pathname: string): boolean;
+/**
+ * Parse a simple pathname pattern into segments for radix tree insertion
+ * Returns null if the pattern is complex (use regex instead)
+ *
+ * Examples:
+ * - "/api/users" -> [{ type: "static", value: "/api/users" }]
+ * - "/users/:id" -> [{ type: "static", value: "/users/" }, { type: "param", name: "id" }]
+ * - "/files/*" -> [{ type: "static", value: "/files/" }, { type: "wildcard" }]
+ */
+export declare function parseSimplePattern(pathname: string): ParsedPattern | null;
+/**
+ * Compile pathname pattern to RegExp with full URLPattern syntax support
+ * @param pathname The pathname pattern to compile
+ * @param encodeChars Whether to percent-encode characters that aren't allowed in URL paths (default true)
+ * @param ignoreCase Whether to make the regex case-insensitive
+ */
+export declare function compilePathname(pathname: string, encodeChars?: boolean, ignoreCase?: boolean): CompiledPattern;
+/**
+ * Options for URLPattern/MatchPattern construction
+ */
+export interface URLPatternOptions {
+    ignoreCase?: boolean;
+}
+/**
+ * Input type for URLPattern/MatchPattern
+ */
+type URLPatternInit = {
+    protocol?: string;
+    hostname?: string;
+    port?: string;
+    pathname?: string;
+    search?: string;
+    hash?: string;
+    username?: string;
+    password?: string;
+    baseURL?: string;
+};
+/**
+ * URLPattern - Strict WPT-compliant URL pattern matching
+ *
+ * Differences from MatchPattern:
+ * - Throws for relative patterns without baseURL
+ * - Uses regex for search matching (order-dependent)
+ * - No & syntax support
+ */
+export declare class URLPattern {
+    #private;
+    get pathname(): string;
+    get search(): string;
+    get protocol(): string;
+    get hostname(): string;
+    get port(): string;
+    get username(): string;
+    get password(): string;
+    get hash(): string;
+    constructor(input?: string | URLPatternInit, baseURLOrOptions?: string | URLPatternOptions, options?: URLPatternOptions);
+    test(input?: string | URL | URLPatternInit, baseURL?: string): boolean;
+    exec(input: string | URL | URLPatternInit, baseURL?: string): MatchPatternResult | null;
+}
+/**
+ * MatchPattern - URL pattern matching with conveniences for routing
+ *
+ * Features:
+ * - Relative paths without baseURL ("/users/:id" works)
+ * - & syntax for search params ("/api&format=json")
+ * - Order-independent search matching
+ */
+export declare class MatchPattern {
+    #private;
+    get pathname(): string;
+    get search(): string | undefined;
+    get protocol(): string | undefined;
+    get hostname(): string | undefined;
+    get port(): string | undefined;
+    get username(): string | undefined;
+    get password(): string | undefined;
+    get hash(): string | undefined;
+    constructor(input?: string | URLPatternInit, baseURLOrOptions?: string | URLPatternOptions, options?: URLPatternOptions);
+    test(input?: string | URL | URLPatternInit, baseURL?: string): boolean;
+    exec(input: string | URL | URLPatternInit, baseURL?: string): MatchPatternResult | null;
+}
+export {};