@peter.naydenov/url-pattern 1.0.2 → 1.0.4

package/dist/url-pattern.cjs.js

@@ -9,13 +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} [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
  */
 
 /**
@@ -23,6 +25,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
  * @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
  */
 
@@ -52,11 +55,13 @@ Object.defineProperty(exports, '__esModule', { value: true });
 const DEFAULT_OPTIONS = {
   escapeChar: '\\',
   segmentNameStartChar: ':',
-  segmentNameCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',
+  segmentNameEndChar: undefined,
+  segmentNameCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_',
   segmentValueCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %',
   optionalSegmentStartChar: '(',
   optionalSegmentEndChar: ')',
-  wildcardChar: '*'
+  wildcardChar: '*',
+  wildcardName: '_'
 };
 
 /**
@@ -66,6 +71,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
@@ -116,29 +141,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;
     }
@@ -146,9 +205,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;
@@ -158,8 +218,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;
         }
@@ -167,54 +231,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>} */
@@ -227,13 +314,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;
@@ -253,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;
@@ -280,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,
@@ -300,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,
@@ -318,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) {
@@ -329,20 +436,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]];
@@ -354,8 +481,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];
     }
   }
@@ -384,37 +522,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 {
@@ -427,13 +566,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;
@@ -462,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);
   }
 
   /**
@@ -495,9 +642,11 @@ const urlPattern = (pattern, options = {}) => {
 
 exports.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
 exports.UrlPattern = UrlPattern;
-exports.default = UrlPattern;
+exports.default = urlPattern;
 exports.makePattern = makePattern;
 exports.makePatternFromRegex = makePatternFromRegex;
 exports.match = match;
 exports.stringify = stringify;
 exports.urlPattern = urlPattern;
+
+module.exports = Object.assign(module.exports.default, module.exports);