@peter.naydenov/url-pattern 1.0.3 → 1.0.4

package/dist/url-pattern.cjs.js

@@ -9,14 +9,15 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 /**
  * @typedef {Object} UrlPatternOptions
- * @property {string} [escapeChar='\\'] - Character used for escaping special characters
+ * @property {string} [escapeChar='\\'] - Character used for escaping. Only escapes regex metacharacters (`^$.*+?()[]{}|\`); for any other character the backslash is treated as a literal.
  * @property {string} [segmentNameStartChar=':'] - Character that starts a named segment
  * @property {string} [segmentNameEndChar] - Character that ends a named segment. When set, the segment name stops at the first occurrence of this character (instead of stopping at the first character outside `segmentNameCharset`).
  * @property {string} [segmentNameCharset='a-zA-Z0-9_'] - Characters allowed in segment names
  * @property {string} [segmentValueCharset='a-zA-Z0-9-_~ %'] - Characters allowed in segment values
  * @property {string} [optionalSegmentStartChar='('] - Character that starts an optional segment
  * @property {string} [optionalSegmentEndChar=')'] - Character that ends an optional segment
- * @property {string} [wildcardChar='*'] - Character that denotes a wildcard
+ * @property {string} [wildcardChar='*'] - Character that denotes a wildcard in the pattern
+ * @property {string} [wildcardName='_'] - Key under which the wildcard value is stored in the match result
  */
 
 /**
@@ -59,7 +60,8 @@ const DEFAULT_OPTIONS = {
   segmentValueCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %',
   optionalSegmentStartChar: '(',
   optionalSegmentEndChar: ')',
-  wildcardChar: '*'
+  wildcardChar: '*',
+  wildcardName: '_'
 };
 
 /**
@@ -153,10 +155,10 @@ const parsePattern = (pattern, options) => {
       }
       const nextChar = pattern[i + 1];
       // Only treat \ as an escape when followed by a regex metacharacter.
-      // For all other characters the backslash is literal (e.g. '\)' in a URL
-      // is just a backslash followed by ')'). This prevents the escape handler
-      // from accidentally consuming the optional-group close delimiter ')'.
-      const regexMetachars = '^$\.*+?()[]{}|\\';
+      // For any other character the backslash is literal (e.g. '\:' in a URL
+      // is just a backslash followed by ':'). This means `:` cannot be escaped
+      // — it has no special meaning in regex, so the escape adds nothing.
+      const regexMetachars = '^$.*+?()[]{}|\\';
       if (!regexMetachars.includes(nextChar)) {
         // Not a regex metachar: treat the backslash as a literal character,
         // advance past it so the next character is processed normally.
@@ -168,6 +170,7 @@ const parsePattern = (pattern, options) => {
           optionalGroupId: inOptional ? optionalGroupId : undefined
         });
         i += 1;
+        continue;
       } else {
         segments.push({
           type: 'literal',
@@ -202,7 +205,7 @@ const parsePattern = (pattern, options) => {
     if (char === options.wildcardChar) {
       segments.push({
         type: 'wildcard',
-        name: '_',
+        name: options.wildcardName,
         regex: '.*',
         optional: inOptional,
         optionalGroupId: inOptional ? optionalGroupId : undefined
@@ -278,7 +281,6 @@ const parsePattern = (pattern, options) => {
   return segments;
 };
 
-/**
 /**
  * Returns true when a value should be treated as "absent" for an optional segment.
  * @param {*} val - Value to inspect
@@ -286,6 +288,9 @@ const parsePattern = (pattern, options) => {
  */
 const isAbsentValue = (val) => {
   if (val === undefined || val === null || val === '') return true;
+  // Number.isNaN catches numeric NaN values that would otherwise stringify to
+  // the literal string "NaN" in a generated URL.
+  if (typeof val === 'number' && Number.isNaN(val)) return true;
   if (Array.isArray(val) && val.length === 0) return true;
   return false;
 };
@@ -296,7 +301,7 @@ const isAbsentValue = (val) => {
  * @param {UrlPatternOptions} options - Options
  * @returns {{regex: string, segmentNames: Array<SegmentName>}} Compiled regex and segment names
  */
-const compileRegex = (segments, _options) => {
+const compileRegex = (segments, options) => {
   let regex = '^';
   let groupIndex = 0;
   /** @type {Array<SegmentName>} */
@@ -316,7 +321,7 @@ const compileRegex = (segments, _options) => {
         
         if (seg.type === 'wildcard') {
           optionalPart += '(.*)';
-          segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+          segmentNames.push({ name: options.wildcardName, index: groupIndex, type: 'wildcard' });
           groupIndex++;
         } else if (seg.type === 'named') {
           optionalPart += seg.regex;
@@ -336,7 +341,7 @@ const compileRegex = (segments, _options) => {
 
     if (segment.type === 'wildcard') {
       regex += '(.*)';
-      segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+      segmentNames.push({ name: options.wildcardName, index: groupIndex, type: 'wildcard' });
       groupIndex++;
     } else if (segment.type === 'named') {
       regex += segment.regex;
@@ -363,7 +368,7 @@ const compileRegex = (segments, _options) => {
 const makePattern = (pattern, options = {}) => {
   const mergedOptions = mergeOptions(options);
   const segments = parsePattern(pattern, mergedOptions);
-  const { regex, segmentNames } = compileRegex(segments);
+  const { regex, segmentNames } = compileRegex(segments, mergedOptions);
 
   return {
     regex,
@@ -383,9 +388,20 @@ const makePattern = (pattern, options = {}) => {
  * @returns {CompiledPattern} Compiled pattern
  */
 const makePatternFromRegex = (regex, keys = []) => {
+  // Strip the `g` and `y` flags. The `g` flag makes `RegExp.prototype.exec`
+  // advance `lastIndex` between calls, which would cause subsequent matches
+  // to start from the wrong position. The `y` (sticky) flag requires a match
+  // starting exactly at `lastIndex`, which is incompatible with our
+  // anchored, single-match contract. Other flags (`i`, `m`, `s`, `d`, `u`)
+  // are preserved.
+  const safeFlags = regex.flags.replace(/[gy]/g, '');
+  const regexObj = safeFlags === regex.flags
+    ? regex
+    : new RegExp(regex.source, safeFlags);
+
   return {
     regex: regex.source,
-    regexObj: regex,
+    regexObj,
     segments: [],
     segmentNames: keys.map((name, index) => ({ name, index, type: 'named' })),
     options: DEFAULT_OPTIONS,
@@ -401,6 +417,14 @@ const makePatternFromRegex = (regex, keys = []) => {
  * @returns {Object|null} Extracted values or null if no match
  */
 const match = (compiled, str) => {
+  // Guard against non-string input. `RegExp.prototype.exec` coerces with
+  // String(), so `match(123)` would silently try to match "123" — almost
+  // certainly not what the caller meant. Throw a TypeError so the misuse
+  // surfaces immediately.
+  if (typeof str !== 'string') {
+    throw new TypeError(`pattern.match() requires a string, got ${typeof str}`);
+  }
+
   const matchResult = compiled.regexObj.exec(str);
   
   if (!matchResult) {
@@ -420,6 +444,10 @@ const match = (compiled, str) => {
       });
       return result;
     }
+    // No keys, no groups → return the captured values as an array. If the
+    // regex had no capture groups, this is an empty array; we keep the
+    // existing behaviour (documented in the README's regex example) rather
+    // than coercing to `{}` and breaking callers that rely on the array.
     return matchResult.slice(1);
   }
 
@@ -509,9 +537,9 @@ const stringify = (compiled, values = {}) => {
           }
           optionalPart += Array.isArray(val) ? val.join('/') : val;
         } else if (seg.type === 'wildcard') {
-          const val = values._;
-          // Original behaviour: wildcards are skipped in optional groups (values._
-          // is never used here). If wildcard is absent, wipe the group.
+          const val = values[compiled.options.wildcardName];
+          // Wildcards inside an optional group still consume values[wildcardName]
+          // when present; if absent, the whole group is wiped.
           if (isAbsentValue(val)) {
             optionalPart = '';
             break;
@@ -543,7 +571,7 @@ const stringify = (compiled, values = {}) => {
       }
       result += Array.isArray(value) ? value.join('/') : value;
     } else if (segment.type === 'wildcard') {
-      const value = values._;
+      const value = values[compiled.options.wildcardName];
       // Empty string is a valid wildcard match result (e.g. '/files/*' on '/files/')
       // and should be allowed without throwing.
       if (value === undefined || value === null) {
@@ -575,6 +603,12 @@ class UrlPattern {
       /** @type {CompiledPattern} */
       this.compiled = makePattern(pattern, /** @type {UrlPatternOptions} */ (options));
     }
+    // The compiled state is exposed as a read-only introspection field; freeze
+    // it (and the nested `options` object) so accidental mutation fails loudly
+    // instead of silently desynchronising the cached regex. `Object.freeze`
+    // is shallow, so we explicitly freeze `options` too.
+    Object.freeze(this.compiled.options);
+    Object.freeze(this.compiled);
   }
 
   /**

package/dist/url-pattern.es.js

@@ -5,14 +5,15 @@
 
 /**
  * @typedef {Object} UrlPatternOptions
- * @property {string} [escapeChar='\\'] - Character used for escaping special characters
+ * @property {string} [escapeChar='\\'] - Character used for escaping. Only escapes regex metacharacters (`^$.*+?()[]{}|\`); for any other character the backslash is treated as a literal.
  * @property {string} [segmentNameStartChar=':'] - Character that starts a named segment
  * @property {string} [segmentNameEndChar] - Character that ends a named segment. When set, the segment name stops at the first occurrence of this character (instead of stopping at the first character outside `segmentNameCharset`).
  * @property {string} [segmentNameCharset='a-zA-Z0-9_'] - Characters allowed in segment names
  * @property {string} [segmentValueCharset='a-zA-Z0-9-_~ %'] - Characters allowed in segment values
  * @property {string} [optionalSegmentStartChar='('] - Character that starts an optional segment
  * @property {string} [optionalSegmentEndChar=')'] - Character that ends an optional segment
- * @property {string} [wildcardChar='*'] - Character that denotes a wildcard
+ * @property {string} [wildcardChar='*'] - Character that denotes a wildcard in the pattern
+ * @property {string} [wildcardName='_'] - Key under which the wildcard value is stored in the match result
  */
 
 /**
@@ -55,7 +56,8 @@ const DEFAULT_OPTIONS = {
   segmentValueCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %',
   optionalSegmentStartChar: '(',
   optionalSegmentEndChar: ')',
-  wildcardChar: '*'
+  wildcardChar: '*',
+  wildcardName: '_'
 };
 
 /**
@@ -149,10 +151,10 @@ const parsePattern = (pattern, options) => {
       }
       const nextChar = pattern[i + 1];
       // Only treat \ as an escape when followed by a regex metacharacter.
-      // For all other characters the backslash is literal (e.g. '\)' in a URL
-      // is just a backslash followed by ')'). This prevents the escape handler
-      // from accidentally consuming the optional-group close delimiter ')'.
-      const regexMetachars = '^$\.*+?()[]{}|\\';
+      // For any other character the backslash is literal (e.g. '\:' in a URL
+      // is just a backslash followed by ':'). This means `:` cannot be escaped
+      // — it has no special meaning in regex, so the escape adds nothing.
+      const regexMetachars = '^$.*+?()[]{}|\\';
       if (!regexMetachars.includes(nextChar)) {
         // Not a regex metachar: treat the backslash as a literal character,
         // advance past it so the next character is processed normally.
@@ -164,6 +166,7 @@ const parsePattern = (pattern, options) => {
           optionalGroupId: inOptional ? optionalGroupId : undefined
         });
         i += 1;
+        continue;
       } else {
         segments.push({
           type: 'literal',
@@ -198,7 +201,7 @@ const parsePattern = (pattern, options) => {
     if (char === options.wildcardChar) {
       segments.push({
         type: 'wildcard',
-        name: '_',
+        name: options.wildcardName,
         regex: '.*',
         optional: inOptional,
         optionalGroupId: inOptional ? optionalGroupId : undefined
@@ -274,7 +277,6 @@ const parsePattern = (pattern, options) => {
   return segments;
 };
 
-/**
 /**
  * Returns true when a value should be treated as "absent" for an optional segment.
  * @param {*} val - Value to inspect
@@ -282,6 +284,9 @@ const parsePattern = (pattern, options) => {
  */
 const isAbsentValue = (val) => {
   if (val === undefined || val === null || val === '') return true;
+  // Number.isNaN catches numeric NaN values that would otherwise stringify to
+  // the literal string "NaN" in a generated URL.
+  if (typeof val === 'number' && Number.isNaN(val)) return true;
   if (Array.isArray(val) && val.length === 0) return true;
   return false;
 };
@@ -292,7 +297,7 @@ const isAbsentValue = (val) => {
  * @param {UrlPatternOptions} options - Options
  * @returns {{regex: string, segmentNames: Array<SegmentName>}} Compiled regex and segment names
  */
-const compileRegex = (segments, _options) => {
+const compileRegex = (segments, options) => {
   let regex = '^';
   let groupIndex = 0;
   /** @type {Array<SegmentName>} */
@@ -312,7 +317,7 @@ const compileRegex = (segments, _options) => {
         
         if (seg.type === 'wildcard') {
           optionalPart += '(.*)';
-          segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+          segmentNames.push({ name: options.wildcardName, index: groupIndex, type: 'wildcard' });
           groupIndex++;
         } else if (seg.type === 'named') {
           optionalPart += seg.regex;
@@ -332,7 +337,7 @@ const compileRegex = (segments, _options) => {
 
     if (segment.type === 'wildcard') {
       regex += '(.*)';
-      segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+      segmentNames.push({ name: options.wildcardName, index: groupIndex, type: 'wildcard' });
       groupIndex++;
     } else if (segment.type === 'named') {
       regex += segment.regex;
@@ -359,7 +364,7 @@ const compileRegex = (segments, _options) => {
 const makePattern = (pattern, options = {}) => {
   const mergedOptions = mergeOptions(options);
   const segments = parsePattern(pattern, mergedOptions);
-  const { regex, segmentNames } = compileRegex(segments);
+  const { regex, segmentNames } = compileRegex(segments, mergedOptions);
 
   return {
     regex,
@@ -379,9 +384,20 @@ const makePattern = (pattern, options = {}) => {
  * @returns {CompiledPattern} Compiled pattern
  */
 const makePatternFromRegex = (regex, keys = []) => {
+  // Strip the `g` and `y` flags. The `g` flag makes `RegExp.prototype.exec`
+  // advance `lastIndex` between calls, which would cause subsequent matches
+  // to start from the wrong position. The `y` (sticky) flag requires a match
+  // starting exactly at `lastIndex`, which is incompatible with our
+  // anchored, single-match contract. Other flags (`i`, `m`, `s`, `d`, `u`)
+  // are preserved.
+  const safeFlags = regex.flags.replace(/[gy]/g, '');
+  const regexObj = safeFlags === regex.flags
+    ? regex
+    : new RegExp(regex.source, safeFlags);
+
   return {
     regex: regex.source,
-    regexObj: regex,
+    regexObj,
     segments: [],
     segmentNames: keys.map((name, index) => ({ name, index, type: 'named' })),
     options: DEFAULT_OPTIONS,
@@ -397,6 +413,14 @@ const makePatternFromRegex = (regex, keys = []) => {
  * @returns {Object|null} Extracted values or null if no match
  */
 const match = (compiled, str) => {
+  // Guard against non-string input. `RegExp.prototype.exec` coerces with
+  // String(), so `match(123)` would silently try to match "123" — almost
+  // certainly not what the caller meant. Throw a TypeError so the misuse
+  // surfaces immediately.
+  if (typeof str !== 'string') {
+    throw new TypeError(`pattern.match() requires a string, got ${typeof str}`);
+  }
+
   const matchResult = compiled.regexObj.exec(str);
   
   if (!matchResult) {
@@ -416,6 +440,10 @@ const match = (compiled, str) => {
       });
       return result;
     }
+    // No keys, no groups → return the captured values as an array. If the
+    // regex had no capture groups, this is an empty array; we keep the
+    // existing behaviour (documented in the README's regex example) rather
+    // than coercing to `{}` and breaking callers that rely on the array.
     return matchResult.slice(1);
   }
 
@@ -505,9 +533,9 @@ const stringify = (compiled, values = {}) => {
           }
           optionalPart += Array.isArray(val) ? val.join('/') : val;
         } else if (seg.type === 'wildcard') {
-          const val = values._;
-          // Original behaviour: wildcards are skipped in optional groups (values._
-          // is never used here). If wildcard is absent, wipe the group.
+          const val = values[compiled.options.wildcardName];
+          // Wildcards inside an optional group still consume values[wildcardName]
+          // when present; if absent, the whole group is wiped.
           if (isAbsentValue(val)) {
             optionalPart = '';
             break;
@@ -539,7 +567,7 @@ const stringify = (compiled, values = {}) => {
       }
       result += Array.isArray(value) ? value.join('/') : value;
     } else if (segment.type === 'wildcard') {
-      const value = values._;
+      const value = values[compiled.options.wildcardName];
       // Empty string is a valid wildcard match result (e.g. '/files/*' on '/files/')
       // and should be allowed without throwing.
       if (value === undefined || value === null) {
@@ -571,6 +599,12 @@ class UrlPattern {
       /** @type {CompiledPattern} */
       this.compiled = makePattern(pattern, /** @type {UrlPatternOptions} */ (options));
     }
+    // The compiled state is exposed as a read-only introspection field; freeze
+    // it (and the nested `options` object) so accidental mutation fails loudly
+    // instead of silently desynchronising the cached regex. `Object.freeze`
+    // is shallow, so we explicitly freeze `options` too.
+    Object.freeze(this.compiled.options);
+    Object.freeze(this.compiled);
   }
 
   /**

package/dist/url-pattern.umd.js

@@ -1 +1 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).urlPattern={})}(this,function(e){"use strict";const t={escapeChar:"\\",segmentNameStartChar:":",segmentNameEndChar:void 0,segmentNameCharset:"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_",segmentValueCharset:"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %",optionalSegmentStartChar:"(",optionalSegmentEndChar:")",wildcardChar:"*"},n=e=>e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),r=e=>{let t=e.replace(/\\/g,"\\\\");return t=t.replace(/\]/g,"\\]"),t=t.replace(/\^/g,"\\^"),t=t.replace(/-/g,"\\-"),t},a=(e,t,n)=>{const r=[n.escapeChar,n.optionalSegmentStartChar,n.optionalSegmentEndChar,n.wildcardChar,n.segmentNameStartChar];let a=e.length;for(let n=0;n<r.length;n++){const o=r[n];if(!o)continue;const i=e.indexOf(o,t);-1!==i&&i<a&&(a=i)}return a},o=e=>null==e||""===e||!(!Array.isArray(e)||0!==e.length),i=(e,o={})=>{const i=((e={})=>({...t,...e}))(o),s=((e,t)=>{const o=[];let i=0,s=!1,l=0,p=0;for(;i<e.length;){const m=e[i];if(m===t.escapeChar){if(i+1>=e.length)throw new Error(`Invalid pattern: '\\' at position ${i} has nothing to escape`);const t=e[i+1];if("^$.*+?()[]{}|\\".includes(t)){o.push({type:"literal",name:t,regex:n(t),optional:s,optionalGroupId:s?l:void 0}),i+=2;continue}o.push({type:"literal",name:"\\",regex:"\\\\",optional:s,optionalGroupId:s?l:void 0}),i+=1}if(m===t.optionalSegmentStartChar){s=!0,l++,p++,i++;continue}if(m===t.optionalSegmentEndChar){if(0===p)throw new Error(`Invalid pattern: unmatched '${m}' at position ${i}`);s=!1,p--,i++;continue}if(m===t.wildcardChar){o.push({type:"wildcard",name:"_",regex:".*",optional:s,optionalGroupId:s?l:void 0}),i++;continue}if(m===t.segmentNameStartChar&&i+1<e.length){const n=e.slice(i+1);let a=0;const p=t.segmentNameCharset||"",d=t.segmentNameEndChar;for(let e=0;e<n.length&&(!d||n[e]!==d)&&p.includes(n[e]);e++)a=e+1;const c=n.slice(0,a),g=!(!d||n[a]!==d);if(c.length>0){const e=t.segmentValueCharset||"",n=`([${r(e)}]+)`;o.push({type:"named",name:c,regex:n,optional:s,optionalGroupId:s?l:void 0}),i+=1+a+(g?1:0);continue}throw new Error(`Invalid pattern: '${m}' at position ${i} has no segment name`)}const d=a(e,i,t);if(d>i){const t=e.slice(i,d);o.push({type:"literal",name:t,regex:n(t),optional:s,optionalGroupId:s?l:void 0}),i=d;continue}throw new Error(`Invalid pattern: '${m}' at position ${i} has no segment name`)}if(0!==p)throw new Error(`Invalid pattern: unclosed '${t.optionalSegmentStartChar}'`);return o})(e,i),{regex:l,segmentNames:p}=(e=>{let t="^",n=0;const r=[];let a=0;for(;a<e.length;){const o=e[a];if(o.optional){let i="",s=a;const l=o.optionalGroupId;for(;s<e.length&&e[s].optional&&e[s].optionalGroupId===l;){const t=e[s];"wildcard"===t.type?(i+="(.*)",r.push({name:"_",index:n,type:"wildcard"}),n++):"named"===t.type?(i+=t.regex,r.push({name:t.name,index:n,type:"named"}),n++):i+=t.regex,s++}t+=`(?:${i})?`,a=s;continue}"wildcard"===o.type?(t+="(.*)",r.push({name:"_",index:n,type:"wildcard"}),n++):"named"===o.type?(t+=o.regex,r.push({name:o.name,index:n,type:"named"}),n++):t+=o.regex,a++}return t+="$",{regex:t,segmentNames:r}})(s);return{regex:l,regexObj:new RegExp(l),segments:s,segmentNames:p,options:i,isRegex:!1,pattern:e}},s=(e,n=[])=>({regex:e.source,regexObj:e,segments:[],segmentNames:n.map((e,t)=>({name:e,index:t,type:"named"})),options:t,isRegex:!0,keys:n}),l=(e,t)=>{const n=e.regexObj.exec(t);if(!n)return null;if(e.isRegex){if(e.keys&&e.keys.length>0){const t={};return e.keys.forEach((e,r)=>{const a=n[r+1];void 0!==a&&(t[e]=a)}),t}return n.slice(1)}const r={},a=new Set,o=new Set;for(const t of e.segmentNames)"wildcard"===t.type&&o.add(t.name);for(let t=0;t<e.segmentNames.length;t++){const o=e.segmentNames[t],i=o.index+1 in n?n[o.index+1]:"",s=void 0===i?"":i;a.has(o.name)?(Array.isArray(r[o.name])||(r[o.name]=[r[o.name]]),r[o.name].push(s)):(a.add(o.name),r[o.name]=s)}for(const e in r){const t=r[e];if(Array.isArray(t)){const n=t.filter(t=>""!==t||o.has(e));0===n.length?delete r[e]:r[e]=n}else""!==t||o.has(e)||delete r[e]}return r},p=(e,t={})=>{if(e.isRegex)throw new Error("Cannot stringify a pattern created from regex");let n="",r=0;for(;r<e.segments.length;){const a=e.segments[r];if(a.optional){let i="",s=r;const l=a.optionalGroupId;for(;s<e.segments.length&&e.segments[s].optional&&e.segments[s].optionalGroupId===l;){const n=e.segments[s];if("literal"===n.type)i+=n.name;else if("named"===n.type){const e=t[n.name];if(o(e)){i="";break}i+=Array.isArray(e)?e.join("/"):e}else if("wildcard"===n.type){const e=t._;if(o(e)){i="";break}i+=Array.isArray(e)?e.join("/"):e}s++}""!==i&&(n+=i),r===s?r++:r=s;continue}if("literal"===a.type)n+=a.name;else if("named"===a.type){const e=t[a.name];if(o(e))throw new Error(`Missing required value for segment: ${a.name}`);n+=Array.isArray(e)?e.join("/"):e}else if("wildcard"===a.type){const e=t._;if(null==e)throw new Error("Missing required wildcard value");n+=Array.isArray(e)?e.join("/"):e}r++}return n};class m{constructor(e,t={}){if(e instanceof RegExp){const n=Array.isArray(t)?t:[];this.compiled=s(e,n)}else this.compiled=i(e,t)}match(e){return l(this.compiled,e)}stringify(e){return p(this.compiled,e)}}const d=(e,t={})=>new m(e,t);e.DEFAULT_OPTIONS=t,e.UrlPattern=m,e.default=d,e.makePattern=i,e.makePatternFromRegex=s,e.match=l,e.stringify=p,e.urlPattern=d,Object.defineProperty(e,"__esModule",{value:!0})});
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).urlPattern={})}(this,function(e){"use strict";const t={escapeChar:"\\",segmentNameStartChar:":",segmentNameEndChar:void 0,segmentNameCharset:"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_",segmentValueCharset:"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %",optionalSegmentStartChar:"(",optionalSegmentEndChar:")",wildcardChar:"*",wildcardName:"_"},n=e=>e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),r=e=>{let t=e.replace(/\\/g,"\\\\");return t=t.replace(/\]/g,"\\]"),t=t.replace(/\^/g,"\\^"),t=t.replace(/-/g,"\\-"),t},a=(e,t,n)=>{const r=[n.escapeChar,n.optionalSegmentStartChar,n.optionalSegmentEndChar,n.wildcardChar,n.segmentNameStartChar];let a=e.length;for(let n=0;n<r.length;n++){const o=r[n];if(!o)continue;const i=e.indexOf(o,t);-1!==i&&i<a&&(a=i)}return a},o=e=>null==e||""===e||(!("number"!=typeof e||!Number.isNaN(e))||!(!Array.isArray(e)||0!==e.length)),i=(e,o={})=>{const i=((e={})=>({...t,...e}))(o),s=((e,t)=>{const o=[];let i=0,s=!1,l=0,p=0;for(;i<e.length;){const d=e[i];if(d===t.escapeChar){if(i+1>=e.length)throw new Error(`Invalid pattern: '\\' at position ${i} has nothing to escape`);const t=e[i+1];if("^$.*+?()[]{}|\\".includes(t)){o.push({type:"literal",name:t,regex:n(t),optional:s,optionalGroupId:s?l:void 0}),i+=2;continue}o.push({type:"literal",name:"\\",regex:"\\\\",optional:s,optionalGroupId:s?l:void 0}),i+=1;continue}if(d===t.optionalSegmentStartChar){s=!0,l++,p++,i++;continue}if(d===t.optionalSegmentEndChar){if(0===p)throw new Error(`Invalid pattern: unmatched '${d}' at position ${i}`);s=!1,p--,i++;continue}if(d===t.wildcardChar){o.push({type:"wildcard",name:t.wildcardName,regex:".*",optional:s,optionalGroupId:s?l:void 0}),i++;continue}if(d===t.segmentNameStartChar&&i+1<e.length){const n=e.slice(i+1);let a=0;const p=t.segmentNameCharset||"",c=t.segmentNameEndChar;for(let e=0;e<n.length&&(!c||n[e]!==c)&&p.includes(n[e]);e++)a=e+1;const m=n.slice(0,a),g=!(!c||n[a]!==c);if(m.length>0){const e=t.segmentValueCharset||"",n=`([${r(e)}]+)`;o.push({type:"named",name:m,regex:n,optional:s,optionalGroupId:s?l:void 0}),i+=1+a+(g?1:0);continue}throw new Error(`Invalid pattern: '${d}' at position ${i} has no segment name`)}const c=a(e,i,t);if(c>i){const t=e.slice(i,c);o.push({type:"literal",name:t,regex:n(t),optional:s,optionalGroupId:s?l:void 0}),i=c;continue}throw new Error(`Invalid pattern: '${d}' at position ${i} has no segment name`)}if(0!==p)throw new Error(`Invalid pattern: unclosed '${t.optionalSegmentStartChar}'`);return o})(e,i),{regex:l,segmentNames:p}=((e,t)=>{let n="^",r=0;const a=[];let o=0;for(;o<e.length;){const i=e[o];if(i.optional){let s="",l=o;const p=i.optionalGroupId;for(;l<e.length&&e[l].optional&&e[l].optionalGroupId===p;){const n=e[l];"wildcard"===n.type?(s+="(.*)",a.push({name:t.wildcardName,index:r,type:"wildcard"}),r++):"named"===n.type?(s+=n.regex,a.push({name:n.name,index:r,type:"named"}),r++):s+=n.regex,l++}n+=`(?:${s})?`,o=l;continue}"wildcard"===i.type?(n+="(.*)",a.push({name:t.wildcardName,index:r,type:"wildcard"}),r++):"named"===i.type?(n+=i.regex,a.push({name:i.name,index:r,type:"named"}),r++):n+=i.regex,o++}return n+="$",{regex:n,segmentNames:a}})(s,i);return{regex:l,regexObj:new RegExp(l),segments:s,segmentNames:p,options:i,isRegex:!1,pattern:e}},s=(e,n=[])=>{const r=e.flags.replace(/[gy]/g,""),a=r===e.flags?e:new RegExp(e.source,r);return{regex:e.source,regexObj:a,segments:[],segmentNames:n.map((e,t)=>({name:e,index:t,type:"named"})),options:t,isRegex:!0,keys:n}},l=(e,t)=>{if("string"!=typeof t)throw new TypeError("pattern.match() requires a string, got "+typeof t);const n=e.regexObj.exec(t);if(!n)return null;if(e.isRegex){if(e.keys&&e.keys.length>0){const t={};return e.keys.forEach((e,r)=>{const a=n[r+1];void 0!==a&&(t[e]=a)}),t}return n.slice(1)}const r={},a=new Set,o=new Set;for(const t of e.segmentNames)"wildcard"===t.type&&o.add(t.name);for(let t=0;t<e.segmentNames.length;t++){const o=e.segmentNames[t],i=o.index+1 in n?n[o.index+1]:"",s=void 0===i?"":i;a.has(o.name)?(Array.isArray(r[o.name])||(r[o.name]=[r[o.name]]),r[o.name].push(s)):(a.add(o.name),r[o.name]=s)}for(const e in r){const t=r[e];if(Array.isArray(t)){const n=t.filter(t=>""!==t||o.has(e));0===n.length?delete r[e]:r[e]=n}else""!==t||o.has(e)||delete r[e]}return r},p=(e,t={})=>{if(e.isRegex)throw new Error("Cannot stringify a pattern created from regex");let n="",r=0;for(;r<e.segments.length;){const a=e.segments[r];if(a.optional){let i="",s=r;const l=a.optionalGroupId;for(;s<e.segments.length&&e.segments[s].optional&&e.segments[s].optionalGroupId===l;){const n=e.segments[s];if("literal"===n.type)i+=n.name;else if("named"===n.type){const e=t[n.name];if(o(e)){i="";break}i+=Array.isArray(e)?e.join("/"):e}else if("wildcard"===n.type){const n=t[e.options.wildcardName];if(o(n)){i="";break}i+=Array.isArray(n)?n.join("/"):n}s++}""!==i&&(n+=i),r===s?r++:r=s;continue}if("literal"===a.type)n+=a.name;else if("named"===a.type){const e=t[a.name];if(o(e))throw new Error(`Missing required value for segment: ${a.name}`);n+=Array.isArray(e)?e.join("/"):e}else if("wildcard"===a.type){const r=t[e.options.wildcardName];if(null==r)throw new Error("Missing required wildcard value");n+=Array.isArray(r)?r.join("/"):r}r++}return n};class d{constructor(e,t={}){if(e instanceof RegExp){const n=Array.isArray(t)?t:[];this.compiled=s(e,n)}else this.compiled=i(e,t);Object.freeze(this.compiled.options),Object.freeze(this.compiled)}match(e){return l(this.compiled,e)}stringify(e){return p(this.compiled,e)}}const c=(e,t={})=>new d(e,t);e.DEFAULT_OPTIONS=t,e.UrlPattern=d,e.default=c,e.makePattern=i,e.makePatternFromRegex=s,e.match=l,e.stringify=p,e.urlPattern=c,Object.defineProperty(e,"__esModule",{value:!0})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.naydenov/url-pattern",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Matching patterns for urls and other strings. Turn strings into data or data into strings.",
   "type": "module",
   "main": "./src/main.js",

package/readme.md

@@ -106,20 +106,21 @@ Creates a new pattern instance.
 
 #### Options
 
-- **escapeChar** `{string}` - Character used for escaping special characters (default: `'\\'`)
+- **escapeChar** `{string}` - Character used for escaping (default: `'\\'`). Only escapes regex metacharacters (`^$.*+?()[]{}|\`); the backslash is kept literal for any other following character.
 - **segmentNameStartChar** `{string}` - Character that starts a named segment (default: `':'`)
 - **segmentNameEndChar** `{string}` - Character that ends a named segment (default: `undefined`). When set, the segment name stops at the first occurrence of this character instead of at the first character outside `segmentNameCharset`.
 - **segmentNameCharset** `{string}` - Characters allowed in segment names (default: `'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_'`). Treated as a list of explicit characters; range notation is not interpreted.
 - **segmentValueCharset** `{string}` - Characters allowed in segment values (default: `'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %'`). Treated as a list of explicit characters; range notation is not interpreted.
 - **optionalSegmentStartChar** `{string}` - Character that starts an optional segment (default: `'('`)
 - **optionalSegmentEndChar** `{string}` - Character that ends an optional segment (default: `')'`)
-- **wildcardChar** `{string}` - Character that denotes a wildcard (default: `'*'`)
+- **wildcardChar** `{string}` - Character that denotes a wildcard in the pattern (default: `'*'`)
+- **wildcardName** `{string}` - Key under which the wildcard value is stored in the match result (default: `'_'`). Change this to avoid colliding with a named segment that also uses `_`, or to give wildcards a more descriptive key.
 
 ### Pattern Methods
 
 #### `pattern.match(string)`
 
-Matches a string against the pattern and returns an object with captured values, or `null` if no match.
+Matches a string against the pattern and returns an object with captured values, or `null` if no match. Throws a `TypeError` if the argument is not a string.
 
 #### `pattern.stringify(data)`
 
@@ -127,14 +128,29 @@ Generates a URL string from provided data object.
 
 #### `pattern.compiled`
 
-Read-only object exposing the internal compiled state: `regex` (regex source), `regexObj` (compiled `RegExp`), `segments` (parsed segments array), `segmentNames` (segment name → capture-group mappings), `options` (merged options), `isRegex` (whether the pattern was created from a regex), and `pattern` (the original pattern string). Useful for introspection; do not mutate.
+Read-only object exposing the internal compiled state: `regex` (regex source), `regexObj` (compiled `RegExp`), `segments` (parsed segments array), `segmentNames` (segment name → capture-group mappings), `options` (merged options), `isRegex` (whether the pattern was created from a regex), and `pattern` (the original pattern string). The object is frozen — any attempt to mutate it will throw in strict mode (or fail silently elsewhere). Useful for introspection; do not mutate.
+
+## Notes
+
+### Wildcard result key
+
+Wildcards are stored under the key `_` by default. If a pattern has both a wildcard and a named segment that resolves to `_` (e.g. `/api/:_/files/*`), both values end up under the same key — the second one is appended, producing an array. To avoid this, configure the wildcard key with the `wildcardName` option:
+
+```js
+const pattern = urlPattern('/api/:id/files/*', { wildcardName: 'rest' })
+pattern.match('/api/42/files/a/b')   // → { id: '42', rest: 'a/b' }
+```
+
+### Regex patterns
+
+When you pass a `RegExp` to `urlPattern`, the `g` and `y` flags are stripped. They are incompatible with this library's anchored, single-match contract: `g` would make `exec` advance `lastIndex` between calls (so the second `match()` would return `null`); `y` (sticky) requires a match starting exactly at `lastIndex`. Other flags (`i`, `m`, `s`, `d`, `u`) are preserved. The original regex object you passed in is not mutated — the library creates a fresh `RegExp` internally.
 
 
 
 ## Links
 - [Supported URL patterns with examples](./PATTERNS.md).
 - [History of changes](CHANGELOG.md)
-- [TypeScript definitions](types/index.d.ts)
+- [TypeScript definitions](types/main.d.ts)
 
 
 

package/src/main.js

@@ -5,14 +5,15 @@
 
 /**
  * @typedef {Object} UrlPatternOptions
- * @property {string} [escapeChar='\\'] - Character used for escaping special characters
+ * @property {string} [escapeChar='\\'] - Character used for escaping. Only escapes regex metacharacters (`^$.*+?()[]{}|\`); for any other character the backslash is treated as a literal.
  * @property {string} [segmentNameStartChar=':'] - Character that starts a named segment
  * @property {string} [segmentNameEndChar] - Character that ends a named segment. When set, the segment name stops at the first occurrence of this character (instead of stopping at the first character outside `segmentNameCharset`).
  * @property {string} [segmentNameCharset='a-zA-Z0-9_'] - Characters allowed in segment names
  * @property {string} [segmentValueCharset='a-zA-Z0-9-_~ %'] - Characters allowed in segment values
  * @property {string} [optionalSegmentStartChar='('] - Character that starts an optional segment
  * @property {string} [optionalSegmentEndChar=')'] - Character that ends an optional segment
- * @property {string} [wildcardChar='*'] - Character that denotes a wildcard
+ * @property {string} [wildcardChar='*'] - Character that denotes a wildcard in the pattern
+ * @property {string} [wildcardName='_'] - Key under which the wildcard value is stored in the match result
  */
 
 /**
@@ -55,7 +56,8 @@ const DEFAULT_OPTIONS = {
   segmentValueCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %',
   optionalSegmentStartChar: '(',
   optionalSegmentEndChar: ')',
-  wildcardChar: '*'
+  wildcardChar: '*',
+  wildcardName: '_'
 };
 
 /**
@@ -149,10 +151,10 @@ const parsePattern = (pattern, options) => {
       }
       const nextChar = pattern[i + 1];
       // Only treat \ as an escape when followed by a regex metacharacter.
-      // For all other characters the backslash is literal (e.g. '\)' in a URL
-      // is just a backslash followed by ')'). This prevents the escape handler
-      // from accidentally consuming the optional-group close delimiter ')'.
-      const regexMetachars = '^$\.*+?()[]{}|\\';
+      // For any other character the backslash is literal (e.g. '\:' in a URL
+      // is just a backslash followed by ':'). This means `:` cannot be escaped
+      // — it has no special meaning in regex, so the escape adds nothing.
+      const regexMetachars = '^$.*+?()[]{}|\\';
       if (!regexMetachars.includes(nextChar)) {
         // Not a regex metachar: treat the backslash as a literal character,
         // advance past it so the next character is processed normally.
@@ -164,6 +166,7 @@ const parsePattern = (pattern, options) => {
           optionalGroupId: inOptional ? optionalGroupId : undefined
         });
         i += 1;
+        continue;
       } else {
         segments.push({
           type: 'literal',
@@ -198,7 +201,7 @@ const parsePattern = (pattern, options) => {
     if (char === options.wildcardChar) {
       segments.push({
         type: 'wildcard',
-        name: '_',
+        name: options.wildcardName,
         regex: '.*',
         optional: inOptional,
         optionalGroupId: inOptional ? optionalGroupId : undefined
@@ -274,7 +277,6 @@ const parsePattern = (pattern, options) => {
   return segments;
 };
 
-/**
 /**
  * Returns true when a value should be treated as "absent" for an optional segment.
  * @param {*} val - Value to inspect
@@ -282,6 +284,9 @@ const parsePattern = (pattern, options) => {
  */
 const isAbsentValue = (val) => {
   if (val === undefined || val === null || val === '') return true;
+  // Number.isNaN catches numeric NaN values that would otherwise stringify to
+  // the literal string "NaN" in a generated URL.
+  if (typeof val === 'number' && Number.isNaN(val)) return true;
   if (Array.isArray(val) && val.length === 0) return true;
   return false;
 };
@@ -292,7 +297,7 @@ const isAbsentValue = (val) => {
  * @param {UrlPatternOptions} options - Options
  * @returns {{regex: string, segmentNames: Array<SegmentName>}} Compiled regex and segment names
  */
-const compileRegex = (segments, _options) => {
+const compileRegex = (segments, options) => {
   let regex = '^';
   let groupIndex = 0;
   /** @type {Array<SegmentName>} */
@@ -312,7 +317,7 @@ const compileRegex = (segments, _options) => {
         
         if (seg.type === 'wildcard') {
           optionalPart += '(.*)';
-          segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+          segmentNames.push({ name: options.wildcardName, index: groupIndex, type: 'wildcard' });
           groupIndex++;
         } else if (seg.type === 'named') {
           optionalPart += seg.regex;
@@ -332,7 +337,7 @@ const compileRegex = (segments, _options) => {
 
     if (segment.type === 'wildcard') {
       regex += '(.*)';
-      segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+      segmentNames.push({ name: options.wildcardName, index: groupIndex, type: 'wildcard' });
       groupIndex++;
     } else if (segment.type === 'named') {
       regex += segment.regex;
@@ -379,9 +384,20 @@ const makePattern = (pattern, options = {}) => {
  * @returns {CompiledPattern} Compiled pattern
  */
 const makePatternFromRegex = (regex, keys = []) => {
+  // Strip the `g` and `y` flags. The `g` flag makes `RegExp.prototype.exec`
+  // advance `lastIndex` between calls, which would cause subsequent matches
+  // to start from the wrong position. The `y` (sticky) flag requires a match
+  // starting exactly at `lastIndex`, which is incompatible with our
+  // anchored, single-match contract. Other flags (`i`, `m`, `s`, `d`, `u`)
+  // are preserved.
+  const safeFlags = regex.flags.replace(/[gy]/g, '');
+  const regexObj = safeFlags === regex.flags
+    ? regex
+    : new RegExp(regex.source, safeFlags);
+
   return {
     regex: regex.source,
-    regexObj: regex,
+    regexObj,
     segments: [],
     segmentNames: keys.map((name, index) => ({ name, index, type: 'named' })),
     options: DEFAULT_OPTIONS,
@@ -397,6 +413,14 @@ const makePatternFromRegex = (regex, keys = []) => {
  * @returns {Object|null} Extracted values or null if no match
  */
 const match = (compiled, str) => {
+  // Guard against non-string input. `RegExp.prototype.exec` coerces with
+  // String(), so `match(123)` would silently try to match "123" — almost
+  // certainly not what the caller meant. Throw a TypeError so the misuse
+  // surfaces immediately.
+  if (typeof str !== 'string') {
+    throw new TypeError(`pattern.match() requires a string, got ${typeof str}`);
+  }
+
   const matchResult = compiled.regexObj.exec(str);
   
   if (!matchResult) {
@@ -416,6 +440,10 @@ const match = (compiled, str) => {
       });
       return result;
     }
+    // No keys, no groups → return the captured values as an array. If the
+    // regex had no capture groups, this is an empty array; we keep the
+    // existing behaviour (documented in the README's regex example) rather
+    // than coercing to `{}` and breaking callers that rely on the array.
     return matchResult.slice(1);
   }
 
@@ -505,9 +533,9 @@ const stringify = (compiled, values = {}) => {
           }
           optionalPart += Array.isArray(val) ? val.join('/') : val;
         } else if (seg.type === 'wildcard') {
-          const val = values._;
-          // Original behaviour: wildcards are skipped in optional groups (values._
-          // is never used here). If wildcard is absent, wipe the group.
+          const val = values[compiled.options.wildcardName];
+          // Wildcards inside an optional group still consume values[wildcardName]
+          // when present; if absent, the whole group is wiped.
           if (isAbsentValue(val)) {
             optionalPart = '';
             break;
@@ -539,7 +567,7 @@ const stringify = (compiled, values = {}) => {
       }
       result += Array.isArray(value) ? value.join('/') : value;
     } else if (segment.type === 'wildcard') {
-      const value = values._;
+      const value = values[compiled.options.wildcardName];
       // Empty string is a valid wildcard match result (e.g. '/files/*' on '/files/')
       // and should be allowed without throwing.
       if (value === undefined || value === null) {
@@ -571,6 +599,12 @@ class UrlPattern {
       /** @type {CompiledPattern} */
       this.compiled = makePattern(pattern, /** @type {UrlPatternOptions} */ (options));
     }
+    // The compiled state is exposed as a read-only introspection field; freeze
+    // it (and the nested `options` object) so accidental mutation fails loudly
+    // instead of silently desynchronising the cached regex. `Object.freeze`
+    // is shallow, so we explicitly freeze `options` too.
+    Object.freeze(this.compiled.options);
+    Object.freeze(this.compiled);
   }
 
   /**

package/types/main.d.ts

@@ -4,7 +4,7 @@
  */
 export type UrlPatternOptions = {
     /**
-     * - Character used for escaping special characters
+     * - Character used for escaping. Only escapes regex metacharacters (`^$.*+?()[]{}|\`); for any other character the backslash is treated as a literal.
      */
     escapeChar?: string;
     /**
@@ -32,9 +32,13 @@ export type UrlPatternOptions = {
      */
     optionalSegmentEndChar?: string;
     /**
-     * - Character that denotes a wildcard
+     * - Character that denotes a wildcard in the pattern
      */
     wildcardChar?: string;
+    /**
+     * - Key under which the wildcard value is stored in the match result
+     */
+    wildcardName?: string;
 };
 export type ParsedSegment = {
     /**
@@ -108,14 +112,15 @@ export type CompiledPattern = {
 };
 /**
  * @typedef {Object} UrlPatternOptions
- * @property {string} [escapeChar='\\'] - Character used for escaping special characters
+ * @property {string} [escapeChar='\\'] - Character used for escaping. Only escapes regex metacharacters (`^$.*+?()[]{}|\`); for any other character the backslash is treated as a literal.
  * @property {string} [segmentNameStartChar=':'] - Character that starts a named segment
  * @property {string} [segmentNameEndChar] - Character that ends a named segment. When set, the segment name stops at the first occurrence of this character (instead of stopping at the first character outside `segmentNameCharset`).
  * @property {string} [segmentNameCharset='a-zA-Z0-9_'] - Characters allowed in segment names
  * @property {string} [segmentValueCharset='a-zA-Z0-9-_~ %'] - Characters allowed in segment values
  * @property {string} [optionalSegmentStartChar='('] - Character that starts an optional segment
  * @property {string} [optionalSegmentEndChar=')'] - Character that ends an optional segment
- * @property {string} [wildcardChar='*'] - Character that denotes a wildcard
+ * @property {string} [wildcardChar='*'] - Character that denotes a wildcard in the pattern
+ * @property {string} [wildcardName='_'] - Key under which the wildcard value is stored in the match result
  */
 /**
  * @typedef {Object} ParsedSegment