@peter.naydenov/url-pattern 1.0.2 → 1.0.4

package/dist/url-pattern.es.js

@@ -5,13 +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} [segmentNameCharset='a-zA-Z0-9'] - Characters allowed in segment names
+ * @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
  */
 
 /**
@@ -19,6 +21,7 @@
  * @property {string} name - Segment name
  * @property {string} type - Segment type ('named' | 'wildcard' | 'literal')
  * @property {boolean} [optional=false] - Whether the segment is optional
+ * @property {number} [optionalGroupId] - Identifier of the optional group this segment belongs to; absent for required segments
  * @property {string} regex - Compiled regex string
  */
 
@@ -48,11 +51,13 @@
 const DEFAULT_OPTIONS = {
   escapeChar: '\\',
   segmentNameStartChar: ':',
-  segmentNameCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',
+  segmentNameEndChar: undefined,
+  segmentNameCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_',
   segmentValueCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %',
   optionalSegmentStartChar: '(',
   optionalSegmentEndChar: ')',
-  wildcardChar: '*'
+  wildcardChar: '*',
+  wildcardName: '_'
 };
 
 /**
@@ -62,6 +67,26 @@ const DEFAULT_OPTIONS = {
  */
 const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+/**
+ * Builds a safe regex character class body from a charset string.
+ *
+ * The charset is treated as a list of explicit characters — range notation
+ * (`a-z`) is NOT interpreted as a range. To match the same set of chars
+ * with range syntax, expand it (e.g. `a-z` → `abcdefghijklmnopqrstuvwxyz`).
+ *
+ * The following chars are escaped because they are special inside `[...]`:
+ * `\`, `]`, `^`, and `-`.
+ * @param {string} charset - Character class body
+ * @returns {string} Safe char class body
+ */
+const escapeCharClass = (charset) => {
+  let escaped = charset.replace(/\\/g, '\\\\');
+  escaped = escaped.replace(/\]/g, '\\]');
+  escaped = escaped.replace(/\^/g, '\\^');
+  escaped = escaped.replace(/-/g, '\\-');
+  return escaped;
+};
+
 /**
  * Merges default options with user provided options
  * @param {UrlPatternOptions} [userOptions={}] - User provided options
@@ -112,29 +137,63 @@ const parsePattern = (pattern, options) => {
   const segments = [];
   let i = 0;
   let inOptional = false;
+  let optionalGroupId = 0;
+  let parenDepth = 0;
 
   while (i < pattern.length) {
     const char = pattern[i];
 
-    if (char === options.escapeChar && i + 1 < pattern.length) {
-      segments.push({
-        type: 'literal',
-        name: pattern[i + 1],
-        regex: escapeRegex(pattern[i + 1]),
-        optional: inOptional
-      });
-      i += 2;
-      continue;
+    if (char === options.escapeChar) {
+      // Throw when the escape char is at the end of the pattern — nothing follows
+      // it to escape, and the resulting regex would be broken.
+      if (i + 1 >= pattern.length) {
+        throw new Error(`Invalid pattern: '\\' at position ${i} has nothing to escape`);
+      }
+      const nextChar = pattern[i + 1];
+      // Only treat \ as an escape when followed by a regex metacharacter.
+      // 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.
+        segments.push({
+          type: 'literal',
+          name: '\\',
+          regex: '\\\\',
+          optional: inOptional,
+          optionalGroupId: inOptional ? optionalGroupId : undefined
+        });
+        i += 1;
+        continue;
+      } else {
+        segments.push({
+          type: 'literal',
+          name: nextChar,
+          regex: escapeRegex(nextChar),
+          optional: inOptional,
+          optionalGroupId: inOptional ? optionalGroupId : undefined
+        });
+        i += 2;
+        continue;
+      }
     }
 
     if (char === options.optionalSegmentStartChar) {
       inOptional = true;
+      optionalGroupId++;
+      parenDepth++;
       i++;
       continue;
     }
 
     if (char === options.optionalSegmentEndChar) {
+      if (parenDepth === 0) {
+        throw new Error(`Invalid pattern: unmatched '${char}' at position ${i}`);
+      }
       inOptional = false;
+      parenDepth--;
       i++;
       continue;
     }
@@ -142,9 +201,10 @@ const parsePattern = (pattern, options) => {
     if (char === options.wildcardChar) {
       segments.push({
         type: 'wildcard',
-        name: '_',
+        name: options.wildcardName,
         regex: '.*',
-        optional: inOptional
+        optional: inOptional,
+        optionalGroupId: inOptional ? optionalGroupId : undefined
       });
       i++;
       continue;
@@ -154,8 +214,12 @@ const parsePattern = (pattern, options) => {
       const remaining = pattern.slice(i + 1);
       let nameEnd = 0;
       const charset = options.segmentNameCharset || '';
-      
+      const endChar = options.segmentNameEndChar;
+
       for (let j = 0; j < remaining.length; j++) {
+        if (endChar && remaining[j] === endChar) {
+          break;
+        }
         if (!charset.includes(remaining[j])) {
           break;
         }
@@ -163,54 +227,77 @@ const parsePattern = (pattern, options) => {
       }
       
       const name = remaining.slice(0, nameEnd);
-      
+      const consumeEndChar = !!(endChar && remaining[nameEnd] === endChar);
+
       if (name.length > 0) {
-        let valueCharset = options.segmentValueCharset || '';
-        if (valueCharset.includes('-') && valueCharset.indexOf('-') > 0 && valueCharset.indexOf('-') < valueCharset.length - 1) {
-          valueCharset = valueCharset.replace(/-/g, '');
-          valueCharset += '-';
-        }
-        const escapedValueCharset = valueCharset.replace(/\]/g, '\\]');
+        const valueCharset = options.segmentValueCharset || '';
+        const escapedValueCharset = escapeCharClass(valueCharset);
         const valueRegex = `([${escapedValueCharset}]+)`;
-        
+
         segments.push({
           type: 'named',
           name,
           regex: valueRegex,
-          optional: inOptional
+          optional: inOptional,
+          optionalGroupId: inOptional ? optionalGroupId : undefined
         });
-        i += 1 + nameEnd;
+        i += 1 + nameEnd + (consumeEndChar ? 1 : 0);
         continue;
       }
+
+      // segmentNameStartChar at end of pattern, or followed by a non-charset
+      // character that is also a special char (e.g. ':)').
+      throw new Error(`Invalid pattern: '${char}' at position ${i} has no segment name`);
     }
 
     const literalEnd = findNextSpecialChar(pattern, i, options);
-    
+
     if (literalEnd > i) {
       const literal = pattern.slice(i, literalEnd);
       segments.push({
         type: 'literal',
         name: literal,
         regex: escapeRegex(literal),
-        optional: inOptional
+        optional: inOptional,
+        optionalGroupId: inOptional ? optionalGroupId : undefined
       });
       i = literalEnd;
       continue;
     }
 
-    i++;
+    // literalEnd === i: current char itself is a special char with no
+    // name/value following. Throw for clarity.
+    throw new Error(`Invalid pattern: '${char}' at position ${i} has no segment name`);
+  }
+
+  if (parenDepth !== 0) {
+    throw new Error(`Invalid pattern: unclosed '${options.optionalSegmentStartChar}'`);
   }
 
   return segments;
 };
 
+/**
+ * Returns true when a value should be treated as "absent" for an optional segment.
+ * @param {*} val - Value to inspect
+ * @returns {boolean}
+ */
+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;
+};
+
 /**
  * Compiles segments into a regex pattern
  * @param {Array<ParsedSegment>} segments - Parsed segments
  * @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>} */
@@ -223,13 +310,14 @@ const compileRegex = (segments, _options) => {
     if (segment.optional) {
       let optionalPart = '';
       let j = i;
-      
-      while (j < segments.length && segments[j].optional) {
+      const currentGroupId = segment.optionalGroupId;
+
+      while (j < segments.length && segments[j].optional && segments[j].optionalGroupId === currentGroupId) {
         const seg = segments[j];
         
         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;
@@ -249,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;
@@ -276,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,
@@ -296,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,
@@ -314,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) {
@@ -325,20 +432,40 @@ const match = (compiled, str) => {
       const result = {};
       compiled.keys.forEach((key, index) => {
         const val = matchResult[index + 1];
-        result[key] = val !== undefined ? val : null;
+        // Undefined means the optional group didn't participate — omit the key
+        // so this is consistent with string-pattern behaviour.
+        if (val !== undefined) {
+          result[key] = val;
+        }
       });
       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);
   }
 
   const result = {};
   const usedNames = new Set();
 
+  // Track which segment names are wildcards so their empty-string captures survive
+  // the cleanup loop. An empty wildcard result (e.g. '/files/*' on '/files/')
+  // is a valid match result.
+  const wildcardNames = new Set();
+  for (const seg of compiled.segmentNames) {
+    if (seg.type === 'wildcard') wildcardNames.add(seg.name);
+  }
+
   for (let i = 0; i < compiled.segmentNames.length; i++) {
     const segInfo = compiled.segmentNames[i];
-    const value = matchResult[segInfo.index + 1] || '';
-    
+    const hasCapture = segInfo.index + 1 in matchResult;
+    // When an optional group didn't participate, the regex returns undefined.
+    // Normalize to '' so both non-isRegex and isRegex paths behave the same.
+    const rawValue = hasCapture ? matchResult[segInfo.index + 1] : '';
+    const value = rawValue === undefined ? '' : rawValue;
+
     if (usedNames.has(segInfo.name)) {
       if (!Array.isArray(result[segInfo.name])) {
         result[segInfo.name] = [result[segInfo.name]];
@@ -350,8 +477,19 @@ const match = (compiled, str) => {
     }
   }
 
+  // Delete empty-string entries, but preserve wildcards — an empty capture is
+  // a valid match result for wildcards. Also clean null/undefined from arrays.
   for (const key in result) {
-    if (result[key] === '') {
+    const val = result[key];
+    if (Array.isArray(val)) {
+      // Filter out empty-string entries from arrays (but preserve wildcards).
+      const filtered = val.filter(v => v !== '' || wildcardNames.has(key));
+      if (filtered.length === 0) {
+        delete result[key];
+      } else {
+        result[key] = filtered;
+      }
+    } else if (val === '' && !wildcardNames.has(key)) {
       delete result[key];
     }
   }
@@ -380,37 +518,38 @@ const stringify = (compiled, values = {}) => {
     if (segment.optional) {
       let optionalPart = '';
       let j = i;
-      
-      while (j < compiled.segments.length && compiled.segments[j].optional) {
+      const currentGroupId = segment.optionalGroupId;
+
+      while (j < compiled.segments.length && compiled.segments[j].optional && compiled.segments[j].optionalGroupId === currentGroupId) {
         const seg = compiled.segments[j];
-        
+
         if (seg.type === 'literal') {
           optionalPart += seg.name;
         } else if (seg.type === 'named') {
           const val = values[seg.name];
-          if (val !== undefined && val !== null && val !== '') {
-            optionalPart += Array.isArray(val) ? val.join('/') : val;
-          } else {
+          if (isAbsentValue(val)) {
             optionalPart = '';
             break;
           }
+          optionalPart += Array.isArray(val) ? val.join('/') : val;
         } else if (seg.type === 'wildcard') {
-          const val = values._;
-          if (val !== undefined && val !== null && val !== '') {
-            optionalPart += Array.isArray(val) ? val.join('/') : val;
-          } else {
+          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;
           }
+          optionalPart += Array.isArray(val) ? val.join('/') : val;
         }
-        
+
         j++;
       }
-      
+
       if (optionalPart !== '') {
         result += optionalPart;
       }
-      
+
       if (i === j) {
         i++;
       } else {
@@ -423,13 +562,15 @@ const stringify = (compiled, values = {}) => {
       result += segment.name;
     } else if (segment.type === 'named') {
       const value = values[segment.name];
-      if (value === undefined || value === null || value === '') {
+      if (isAbsentValue(value)) {
         throw new Error(`Missing required value for segment: ${segment.name}`);
       }
       result += Array.isArray(value) ? value.join('/') : value;
     } else if (segment.type === 'wildcard') {
-      const value = values._;
-      if (value === undefined || value === null || value === '') {
+      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) {
         throw new Error('Missing required wildcard value');
       }
       result += Array.isArray(value) ? value.join('/') : value;
@@ -458,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);
   }
 
   /**
@@ -489,4 +636,4 @@ const urlPattern = (pattern, options = {}) => {
   return new UrlPattern(pattern, options);
 };
 
-export { DEFAULT_OPTIONS, UrlPattern, UrlPattern as default, makePattern, makePatternFromRegex, match, stringify, urlPattern };
+export { DEFAULT_OPTIONS, UrlPattern, urlPattern as default, makePattern, makePatternFromRegex, match, stringify, urlPattern };

package/dist/url-pattern.umd.js

@@ -1 +1 @@
-!function(e,n){"object"==typeof exports&&"undefined"!=typeof module?n(exports):"function"==typeof define&&define.amd?define(["exports"],n):n((e="undefined"!=typeof globalThis?globalThis:e||self).urlPattern={})}(this,function(e){"use strict";const n={escapeChar:"\\",segmentNameStartChar:":",segmentNameCharset:"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",segmentValueCharset:"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %",optionalSegmentStartChar:"(",optionalSegmentEndChar:")",wildcardChar:"*"},t=e=>e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),r=(e,n,t)=>{const r=[t.escapeChar,t.optionalSegmentStartChar,t.optionalSegmentEndChar,t.wildcardChar,t.segmentNameStartChar];let a=e.length;for(let t=0;t<r.length;t++){const s=r[t];if(!s)continue;const i=e.indexOf(s,n);-1!==i&&i<a&&(a=i)}return a},a=(e,a={})=>{const s=((e={})=>({...n,...e}))(a),i=((e,n)=>{const a=[];let s=0,i=!1;for(;s<e.length;){const o=e[s];if(o===n.escapeChar&&s+1<e.length){a.push({type:"literal",name:e[s+1],regex:t(e[s+1]),optional:i}),s+=2;continue}if(o===n.optionalSegmentStartChar){i=!0,s++;continue}if(o===n.optionalSegmentEndChar){i=!1,s++;continue}if(o===n.wildcardChar){a.push({type:"wildcard",name:"_",regex:".*",optional:i}),s++;continue}if(o===n.segmentNameStartChar&&s+1<e.length){const t=e.slice(s+1);let r=0;const o=n.segmentNameCharset||"";for(let e=0;e<t.length&&o.includes(t[e]);e++)r=e+1;const l=t.slice(0,r);if(l.length>0){let e=n.segmentValueCharset||"";e.includes("-")&&e.indexOf("-")>0&&e.indexOf("-")<e.length-1&&(e=e.replace(/-/g,""),e+="-");const t=`([${e.replace(/\]/g,"\\]")}]+)`;a.push({type:"named",name:l,regex:t,optional:i}),s+=1+r;continue}}const l=r(e,s,n);if(l>s){const n=e.slice(s,l);a.push({type:"literal",name:n,regex:t(n),optional:i}),s=l;continue}s++}return a})(e,s),{regex:o,segmentNames:l}=(e=>{let n="^",t=0;const r=[];let a=0;for(;a<e.length;){const s=e[a];if(s.optional){let s="",i=a;for(;i<e.length&&e[i].optional;){const n=e[i];"wildcard"===n.type?(s+="(.*)",r.push({name:"_",index:t,type:"wildcard"}),t++):"named"===n.type?(s+=n.regex,r.push({name:n.name,index:t,type:"named"}),t++):s+=n.regex,i++}n+=`(?:${s})?`,a=i;continue}"wildcard"===s.type?(n+="(.*)",r.push({name:"_",index:t,type:"wildcard"}),t++):"named"===s.type?(n+=s.regex,r.push({name:s.name,index:t,type:"named"}),t++):n+=s.regex,a++}return n+="$",{regex:n,segmentNames:r}})(i);return{regex:o,regexObj:new RegExp(o),segments:i,segmentNames:l,options:s,isRegex:!1,pattern:e}},s=(e,t=[])=>({regex:e.source,regexObj:e,segments:[],segmentNames:t.map((e,n)=>({name:e,index:n,type:"named"})),options:n,isRegex:!0,keys:t}),i=(e,n)=>{const t=e.regexObj.exec(n);if(!t)return null;if(e.isRegex){if(e.keys&&e.keys.length>0){const n={};return e.keys.forEach((e,r)=>{const a=t[r+1];n[e]=void 0!==a?a:null}),n}return t.slice(1)}const r={},a=new Set;for(let n=0;n<e.segmentNames.length;n++){const s=e.segmentNames[n],i=t[s.index+1]||"";a.has(s.name)?(Array.isArray(r[s.name])||(r[s.name]=[r[s.name]]),r[s.name].push(i)):(a.add(s.name),r[s.name]=i)}for(const e in r)""===r[e]&&delete r[e];return r},o=(e,n={})=>{if(e.isRegex)throw new Error("Cannot stringify a pattern created from regex");let t="",r=0;for(;r<e.segments.length;){const a=e.segments[r];if(a.optional){let a="",s=r;for(;s<e.segments.length&&e.segments[s].optional;){const t=e.segments[s];if("literal"===t.type)a+=t.name;else if("named"===t.type){const e=n[t.name];if(null==e||""===e){a="";break}a+=Array.isArray(e)?e.join("/"):e}else if("wildcard"===t.type){const e=n._;if(null==e||""===e){a="";break}a+=Array.isArray(e)?e.join("/"):e}s++}""!==a&&(t+=a),r===s?r++:r=s;continue}if("literal"===a.type)t+=a.name;else if("named"===a.type){const e=n[a.name];if(null==e||""===e)throw new Error(`Missing required value for segment: ${a.name}`);t+=Array.isArray(e)?e.join("/"):e}else if("wildcard"===a.type){const e=n._;if(null==e||""===e)throw new Error("Missing required wildcard value");t+=Array.isArray(e)?e.join("/"):e}r++}return t};class l{constructor(e,n={}){if(e instanceof RegExp){const t=Array.isArray(n)?n:[];this.compiled=s(e,t)}else this.compiled=a(e,n)}match(e){return i(this.compiled,e)}stringify(e){return o(this.compiled,e)}}e.DEFAULT_OPTIONS=n,e.UrlPattern=l,e.default=l,e.makePattern=a,e.makePatternFromRegex=s,e.match=i,e.stringify=o,e.urlPattern=(e,n={})=>new l(e,n),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.2",
+  "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",
@@ -46,11 +46,11 @@
   },
   "devDependencies": {
     "@rollup/plugin-terser": "^1.0.0",
-    "@vitest/coverage-v8": "^4.1.7",
-    "oxlint": "^1.68.0",
-    "rollup": "^4.61.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "@vitest/coverage-v8": "^4.1.10",
+    "oxlint": "^1.73.0",
+    "rollup": "^4.62.2",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "allowScripts": {
     "fsevents@2.3.3": true

package/{README.md → readme.md}

@@ -59,7 +59,7 @@ const pattern = urlPattern ( '/files/*' )
 const result = pattern.match ( '/files/images/photo.jpg' )
 
 console.log ( result )
-// Output: { '*': 'images/photo.jpg' }
+// Output: { _: 'images/photo.jpg' }
 ```
 
 ### Generate URL from data
@@ -106,35 +106,51 @@ 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`)
-- **segmentNameCharset** `{string}` - Characters allowed in segment names (default: `'a-zA-Z0-9'`)
-- **segmentValueCharset** `{string}` - Characters allowed in segment values (default: `'a-zA-Z0-9-_~ %'`)
+- **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)`
 
 Generates a URL string from provided data object.
 
-#### `pattern.compile()`
+#### `pattern.compiled`
 
-Returns an object with `regex` (compiled RegExp), `segments` (parsed segments array), and `segmentNames` (segment name mappings).
+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)