@b9g/match-pattern 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# MatchPattern
+
+Extended URLPattern for better 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.
+
+## Installation
+
+```bash
+npm install @b9g/match-pattern
+```
+
+## Basic Usage
+
+```javascript
+import { MatchPattern } from '@b9g/match-pattern';
+
+// Create patterns with enhanced string syntax
+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); 
+  // { id: '123', format: 'json', page: '1' }
+}
+```
+
+## Key Differences from URLPattern
+
+### 1. Order-Independent Search Parameters
+
+URLPattern requires exact parameter order. MatchPattern allows any order:
+
+```javascript
+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
+```
+
+### 2. Non-Exhaustive Search Matching
+
+URLPattern rejects extra parameters. MatchPattern captures them:
+
+```javascript
+const pattern = new MatchPattern({ search: 'q=:query' });
+const result = pattern.exec('/?q=hello&page=1&limit=10');
+
+// URLPattern: Fails or captures 'hello&page=1&limit=10' as query value
+// MatchPattern: { q: 'hello', page: '1', limit: '10' }
+console.log(result.params);
+```
+
+### 3. Unified Parameter Object
+
+URLPattern separates pathname and search groups. MatchPattern merges everything:
+
+```javascript
+const pattern = new MatchPattern('/api/:version/posts/:id&format=:format');
+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' }
+```
+
+### 4. Enhanced String Pattern Syntax
+
+MatchPattern supports convenient string patterns with `&` separator:
+
+```javascript
+// Pathname only
+new MatchPattern('/api/posts/:id')
+
+// Pathname with search parameters  
+new MatchPattern('/api/posts/:id&format=:format&page=:page')
+
+// Search parameters only
+new MatchPattern('&q=:query&sort=:sort')
+
+// Full URL patterns
+new MatchPattern('https://api.example.com/v1/posts/:id&format=:format')
+
+// Object syntax (same as URLPattern, enhanced behavior)
+new MatchPattern({ 
+  pathname: '/api/posts/:id',
+  search: 'format=:format' 
+})
+```
+
+## Trailing Slash Normalization
+
+URLPattern has inconsistent behavior with trailing slashes that can cause unexpected matches.
+
+**Issue:** [kenchris/urlpattern-polyfill#131](https://github.com/kenchris/urlpattern-polyfill/issues/131)
+
+**Solution:** ✅ Automatic trailing slash normalization implemented
+
+```javascript
+const pattern = new MatchPattern('/api/posts/:id');
+
+// Both match consistently
+pattern.test('/api/posts/123');   // ✅ true
+pattern.test('/api/posts/123/');  // ✅ true (normalized)
+```
+
+## Known Limitations
+
+### Cross-Implementation Differences
+
+The polyfill and native browser implementations can return different results for edge cases.
+
+**Issue:** [kenchris/urlpattern-polyfill#129](https://github.com/kenchris/urlpattern-polyfill/issues/129)
+
+**Impact:** Results may vary between Node.js, browsers, and other runtimes.
+
+**Testing:** Use Playwright for cross-browser validation in production applications.
+
+### TypeScript Compatibility
+
+Node.js and polyfill URLPattern types have slight differences in their TypeScript definitions.
+
+**Issue:** [kenchris/urlpattern-polyfill#135](https://github.com/kenchris/urlpattern-polyfill/issues/135)
+
+**Solution:** MatchPattern uses canonical WHATWG specification types internally.
+
+## API Reference
+
+### Constructor
+
+```typescript
+new MatchPattern(input: string | URLPatternInit, baseURL?: string)
+```
+
+### Methods
+
+```typescript
+// Enhanced methods with unified params
+test(input: string | URL): boolean
+exec(input: string | URL): MatchPatternResult | null
+```
+
+### Types
+
+```typescript
+interface MatchPatternResult extends URLPatternResult {
+  params: Record<string, string>;  // Unified parameters from all sources
+}
+```
+
+## 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
+- **TypeScript**: 5.0+ recommended
+
+## Contributing
+
+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
+- Performance issues with complex patterns
+- Cross-runtime behavior differences
+
+## 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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@b9g/match-pattern",
+  "version": "0.1.0",
+  "devDependencies": {
+    "@b9g/libuild": "^0.1.10"
+  },
+  "type": "module",
+  "types": "src/index.d.ts",
+  "module": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./index": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./index.js": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./match-pattern": {
+      "types": "./src/match-pattern.d.ts",
+      "import": "./src/match-pattern.js"
+    },
+    "./match-pattern.js": {
+      "types": "./src/match-pattern.d.ts",
+      "import": "./src/match-pattern.js"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export { MatchPattern, type MatchPatternResult } from "./match-pattern.ts";

package/src/index.js

@@ -0,0 +1,6 @@
+/// <reference types="./index.d.ts" />
+// src/index.ts
+import { MatchPattern } from "./match-pattern.js";
+export {
+  MatchPattern
+};

package/src/match-pattern.d.ts

@@ -0,0 +1,43 @@
+declare let URLPattern: any;
+type URLPatternInput = URLPatternInit | string;
+interface URLPatternComponentResult {
+    input: string;
+    groups: Record<string, string | undefined>;
+}
+interface URLPatternResult {
+    inputs: URLPatternInput[];
+    protocol: URLPatternComponentResult;
+    username: URLPatternComponentResult;
+    password: URLPatternComponentResult;
+    hostname: URLPatternComponentResult;
+    port: URLPatternComponentResult;
+    pathname: URLPatternComponentResult;
+    search: URLPatternComponentResult;
+    hash: URLPatternComponentResult;
+}
+/**
+ * Enhanced URLPattern result that includes unified params
+ */
+export interface MatchPatternResult extends URLPatternResult {
+    params: Record<string, string>;
+}
+/**
+ * MatchPattern extends URLPattern with enhanced routing capabilities:
+ * - Order-independent search parameter matching
+ * - Non-exhaustive search matching (extra params allowed)
+ * - Unified parameter extraction (pathname + search + extras)
+ * - Enhanced string pattern parsing with & syntax
+ */
+export declare class MatchPattern extends URLPattern {
+    private _originalInput;
+    constructor(input: string | URLPatternInit, baseURL?: string);
+    /**
+     * Enhanced exec that returns unified params object with trailing slash normalization
+     */
+    exec(input: string | URL): MatchPatternResult | null;
+    /**
+     * Enhanced test with order-independent search parameter matching and trailing slash normalization
+     */
+    test(input: string | URL): boolean;
+}
+export {};

package/src/match-pattern.js

@@ -0,0 +1,214 @@
+/// <reference types="./match-pattern.d.ts" />
+// src/match-pattern.ts
+var URLPattern = globalThis.URLPattern;
+if (!URLPattern) {
+  await import("urlpattern-polyfill");
+  URLPattern = globalThis.URLPattern;
+}
+var MatchPattern = class extends URLPattern {
+  _originalInput;
+  constructor(input, baseURL) {
+    let processedInput = input;
+    if (typeof input === "string") {
+      processedInput = parseStringPattern(input);
+    }
+    const normalizedInput = normalizePatternTrailingSlash(processedInput);
+    if (baseURL !== void 0) {
+      super(normalizedInput, baseURL);
+    } else {
+      super(normalizedInput);
+    }
+    this._originalInput = normalizedInput;
+  }
+  /**
+   * Enhanced exec that returns unified params object with trailing slash normalization
+   */
+  exec(input) {
+    if (!this.test(input)) {
+      return null;
+    }
+    const url = typeof input === "string" ? new URL(input) : input;
+    const normalizedUrl = normalizeTrailingSlash(url);
+    const result = super.exec(normalizedUrl);
+    if (result) {
+      const enhancedResult = {
+        ...result,
+        params: extractUnifiedParams(result, input)
+        // Use original input for search params
+      };
+      return enhancedResult;
+    }
+    return buildCustomResult(this, input);
+  }
+  /**
+   * Enhanced test with order-independent search parameter matching and trailing slash normalization
+   */
+  test(input) {
+    const url = typeof input === "string" ? new URL(input) : input;
+    const normalizedUrl = normalizeTrailingSlash(url);
+    if (!this.search || this.search === "*") {
+      return super.test(normalizedUrl);
+    }
+    const pathPatternInit = typeof this._originalInput === "string" ? { pathname: this._originalInput } : { ...this._originalInput, search: void 0 };
+    const normalizedPattern = normalizePatternTrailingSlash(pathPatternInit);
+    const pathPattern = new URLPattern(normalizedPattern);
+    if (!pathPattern.test(normalizedUrl)) {
+      return false;
+    }
+    return testSearchParameters(this.search, url.searchParams);
+  }
+};
+function parseStringPattern(pattern) {
+  if (pattern.includes("://")) {
+    const ampIndex2 = pattern.indexOf("&");
+    if (ampIndex2 === -1) {
+      return pattern;
+    }
+    const urlPart = pattern.slice(0, ampIndex2);
+    const search2 = pattern.slice(ampIndex2 + 1);
+    try {
+      const url = new URL(urlPart.replace(/:(\w+)/g, "placeholder"));
+      return {
+        protocol: urlPart.split("://")[0],
+        hostname: url.hostname,
+        pathname: url.pathname.replace(/placeholder/g, ":$1"),
+        // Restore params
+        search: search2
+      };
+    } catch {
+      return pattern;
+    }
+  }
+  const ampIndex = pattern.indexOf("&");
+  if (ampIndex === -1) {
+    return { pathname: pattern };
+  }
+  if (ampIndex === 0) {
+    return { search: pattern.slice(1) };
+  }
+  const pathname = pattern.slice(0, ampIndex);
+  const search = pattern.slice(ampIndex + 1);
+  return { pathname, search };
+}
+function extractUnifiedParams(result, url) {
+  const params = {};
+  if (result.pathname?.groups) {
+    for (const [key, value] of Object.entries(result.pathname.groups)) {
+      if (value !== void 0) {
+        params[key] = value;
+      }
+    }
+  }
+  if (result.search?.groups) {
+    const actualUrl = typeof url === "string" ? new URL(url) : url;
+    const searchParams = actualUrl.searchParams;
+    for (const [key, value] of searchParams) {
+      params[key] = value;
+    }
+  } else if (typeof url !== "string") {
+    const actualUrl = url instanceof URL ? url : new URL(url);
+    for (const [key, value] of actualUrl.searchParams) {
+      params[key] = value;
+    }
+  }
+  return params;
+}
+function normalizeTrailingSlash(url) {
+  const normalized = new URL(url.href);
+  if (normalized.pathname === "/") {
+    return normalized;
+  }
+  if (normalized.pathname.endsWith("/")) {
+    normalized.pathname = normalized.pathname.slice(0, -1);
+  }
+  return normalized;
+}
+function normalizePatternTrailingSlash(patternInit) {
+  if (typeof patternInit === "string") {
+    if (patternInit === "/" || patternInit === "") {
+      return patternInit;
+    }
+    return patternInit.endsWith("/") ? patternInit.slice(0, -1) : patternInit;
+  }
+  const normalized = { ...patternInit };
+  if (normalized.pathname && normalized.pathname !== "/") {
+    if (normalized.pathname.endsWith("/")) {
+      normalized.pathname = normalized.pathname.slice(0, -1);
+    }
+  }
+  return normalized;
+}
+function buildCustomResult(pattern, input) {
+  const url = typeof input === "string" ? new URL(input) : input;
+  const result = {
+    inputs: [input],
+    pathname: { input: url.pathname, groups: {} },
+    search: { input: url.search, groups: {} },
+    hash: { input: url.hash, groups: {} },
+    protocol: { input: url.protocol, groups: {} },
+    hostname: { input: url.hostname, groups: {} },
+    port: { input: url.port, groups: {} },
+    username: { input: url.username, groups: {} },
+    password: { input: url.password, groups: {} },
+    params: {}
+  };
+  if (pattern.pathname && pattern.pathname !== "*") {
+    const pathPattern = new URLPattern({ pathname: pattern.pathname });
+    const pathResult = pathPattern.exec(url);
+    if (pathResult?.pathname?.groups) {
+      result.pathname.groups = pathResult.pathname.groups;
+    }
+  }
+  if (pattern.search && pattern.search !== "*") {
+    const searchParams = parseSearchPattern(pattern.search);
+    const actualParams = url.searchParams;
+    for (const [key, paramDef] of searchParams) {
+      if (actualParams.has(key)) {
+        if (paramDef.type === "named" && paramDef.name) {
+          result.search.groups[paramDef.name] = actualParams.get(key);
+        }
+      }
+    }
+  }
+  result.params = extractUnifiedParams(result, input);
+  return result;
+}
+function testSearchParameters(searchPattern, actualParams) {
+  const patternParams = parseSearchPattern(searchPattern);
+  for (const [key, paramPattern] of patternParams) {
+    if (!actualParams.has(key)) {
+      return false;
+    }
+    if (paramPattern.type === "literal") {
+      if (actualParams.get(key) !== paramPattern.value) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function parseSearchPattern(pattern) {
+  const params = /* @__PURE__ */ new Map();
+  const parts = pattern.split("&");
+  for (const part of parts) {
+    const [key, value] = part.split("=");
+    if (!key || !value)
+      continue;
+    if (value.startsWith(":")) {
+      const isOptional = value.endsWith("?");
+      params.set(key, {
+        type: "named",
+        name: value.slice(1, isOptional ? -1 : void 0),
+        optional: isOptional
+      });
+    } else if (value === "*") {
+      params.set(key, { type: "wildcard" });
+    } else {
+      params.set(key, { type: "literal", value });
+    }
+  }
+  return params;
+}
+export {
+  MatchPattern
+};