@peter.naydenov/url-pattern 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Naydenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/{readme.md → README.md}

@@ -1,9 +1,9 @@
 # URL Pattern (@peter.naydenov/url-pattern)
 
 [![version](https://img.shields.io/npm/v/@peter.naydenov/url-pattern.svg)](https://www.npmjs.com/package/@peter.naydenov/url-pattern)
-[![license](https://img.shields.io/github/license/PeterNaydenov/git-url-pattern.svg)](https://github.com/PeterNaydenov/git-url-pattern/blob/main/LICENSE)
-[![GitHub issues](https://img.shields.io/github/issues-raw/PeterNaydenov/git-url-pattern.svg)](https://github.com/PeterNaydenov/git-url-pattern/issues)
-[![GitHub top language](https://img.shields.io/github/languages/top/PeterNaydenov/git-url-pattern.svg)](https://github.com/PeterNaydenov/git-url-pattern)
+[![license](https://img.shields.io/github/license/PeterNaydenov/url-pattern.svg)](https://github.com/PeterNaydenov/url-pattern/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues-raw/PeterNaydenov/url-pattern.svg)](https://github.com/PeterNaydenov/url-pattern/issues)
+[![GitHub top language](https://img.shields.io/github/languages/top/PeterNaydenov/url-pattern.svg)](https://github.com/PeterNaydenov/url-pattern)
 [![npm bundle size](https://img.shields.io/bundlejs/size/@peter.naydenov/url-pattern.svg)](https://www.npmjs.com/package/@peter.naydenov/url-pattern)
 
 Easier than regex string matching patterns for urls and other strings. Turn strings into data or data into strings.
@@ -89,6 +89,11 @@ const result = pattern.match ( '/user/john/post/123' )
 console.log ( result )
 // Output: { username: 'john', postId: '123' }
 ```
+## URL Patterns
+
+See [supported URL pattern types with examples](./PATTERNS.md).
+
+
 
 ## API Reference
 
@@ -124,13 +129,21 @@ Generates a URL string from provided data object.
 
 Returns an object with `regex` (compiled RegExp), `segments` (parsed segments array), and `segmentNames` (segment name mappings).
 
-## Links
 
+
+## Links
+- [Supported URL patterns with examples](./PATTERNS.md).
 - [History of changes](CHANGELOG.md)
 - [TypeScript definitions](types/index.d.ts)
 
+
+
 ## Credits
 
 '@peter.naydenov/url-pattern' was created and supported by [Peter Naydenov](https://github.com/PeterNaydenov).
 
+
+
+## License
+
 '@peter.naydenov/url-pattern' is released under the [MIT License](https://github.com/PeterNaydenov/git-url-pattern/blob/main/LICENSE).

package/dist/url-pattern.cjs.js

@@ -0,0 +1,503 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * @fileoverview URL pattern matching library
+ * @module url-pattern
+ */
+
+/**
+ * @typedef {Object} UrlPatternOptions
+ * @property {string} [escapeChar='\\'] - Character used for escaping special characters
+ * @property {string} [segmentNameStartChar=':'] - Character that starts a named segment
+ * @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
+ */
+
+/**
+ * @typedef {Object} ParsedSegment
+ * @property {string} name - Segment name
+ * @property {string} type - Segment type ('named' | 'wildcard' | 'literal')
+ * @property {boolean} [optional=false] - Whether the segment is optional
+ * @property {string} regex - Compiled regex string
+ */
+
+/**
+ * @typedef {Object} SegmentName
+ * @property {string} name - Segment name
+ * @property {number} index - Capture group index
+ * @property {string} type - Segment type ('named' | 'wildcard')
+ */
+
+/**
+ * @typedef {Object} CompiledPattern
+ * @property {string} regex - Compiled regex string
+ * @property {RegExp} regexObj - Compiled regex object
+ * @property {Array<ParsedSegment>} segments - Parsed segments
+ * @property {Array<SegmentName>} segmentNames - Segment name mappings
+ * @property {UrlPatternOptions} options - Options used
+ * @property {boolean} isRegex - Whether pattern was created from regex
+ * @property {string} [pattern] - Original pattern string
+ * @property {Array<string>} [keys] - Keys for regex patterns
+ */
+
+/**
+ * Default options for URL pattern matching
+ * @type {UrlPatternOptions}
+ */
+const DEFAULT_OPTIONS = {
+  escapeChar: '\\',
+  segmentNameStartChar: ':',
+  segmentNameCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',
+  segmentValueCharset: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_~ %',
+  optionalSegmentStartChar: '(',
+  optionalSegmentEndChar: ')',
+  wildcardChar: '*'
+};
+
+/**
+ * Escapes special regex characters in a string
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Merges default options with user provided options
+ * @param {UrlPatternOptions} [userOptions={}] - User provided options
+ * @returns {UrlPatternOptions} Merged options
+ */
+const mergeOptions = (userOptions = {}) => ({
+  ...DEFAULT_OPTIONS,
+  ...userOptions
+});
+
+/**
+ * Finds the position of the next special character in the pattern
+ * @param {string} pattern - Pattern string
+ * @param {number} start - Starting position
+ * @param {UrlPatternOptions} options - Parsing options
+ * @returns {number} Position of next special character
+ */
+const findNextSpecialChar = (pattern, start, options) => {
+  const chars = [
+    options.escapeChar, 
+    options.optionalSegmentStartChar, 
+    options.optionalSegmentEndChar, 
+    options.wildcardChar, 
+    options.segmentNameStartChar
+  ];
+  
+  let minPos = pattern.length;
+  
+  for (let i = 0; i < chars.length; i++) {
+    const char = chars[i];
+    if (!char) continue;
+    const pos = pattern.indexOf(char, start);
+    if (pos !== -1 && pos < minPos) {
+      minPos = pos;
+    }
+  }
+  
+  return minPos;
+};
+
+/**
+ * Parses a pattern string into segments
+ * @param {string} pattern - Pattern string to parse
+ * @param {UrlPatternOptions} options - Parsing options
+ * @returns {Array<ParsedSegment>} Parsed segments
+ */
+const parsePattern = (pattern, options) => {
+  const segments = [];
+  let i = 0;
+  let inOptional = false;
+
+  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.optionalSegmentStartChar) {
+      inOptional = true;
+      i++;
+      continue;
+    }
+
+    if (char === options.optionalSegmentEndChar) {
+      inOptional = false;
+      i++;
+      continue;
+    }
+
+    if (char === options.wildcardChar) {
+      segments.push({
+        type: 'wildcard',
+        name: '_',
+        regex: '.*',
+        optional: inOptional
+      });
+      i++;
+      continue;
+    }
+
+    if (char === options.segmentNameStartChar && i + 1 < pattern.length) {
+      const remaining = pattern.slice(i + 1);
+      let nameEnd = 0;
+      const charset = options.segmentNameCharset || '';
+      
+      for (let j = 0; j < remaining.length; j++) {
+        if (!charset.includes(remaining[j])) {
+          break;
+        }
+        nameEnd = j + 1;
+      }
+      
+      const name = remaining.slice(0, nameEnd);
+      
+      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 valueRegex = `([${escapedValueCharset}]+)`;
+        
+        segments.push({
+          type: 'named',
+          name,
+          regex: valueRegex,
+          optional: inOptional
+        });
+        i += 1 + nameEnd;
+        continue;
+      }
+    }
+
+    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
+      });
+      i = literalEnd;
+      continue;
+    }
+
+    i++;
+  }
+
+  return segments;
+};
+
+/**
+ * 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) => {
+  let regex = '^';
+  let groupIndex = 0;
+  /** @type {Array<SegmentName>} */
+  const segmentNames = [];
+  let i = 0;
+
+  while (i < segments.length) {
+    const segment = segments[i];
+    
+    if (segment.optional) {
+      let optionalPart = '';
+      let j = i;
+      
+      while (j < segments.length && segments[j].optional) {
+        const seg = segments[j];
+        
+        if (seg.type === 'wildcard') {
+          optionalPart += '(.*)';
+          segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+          groupIndex++;
+        } else if (seg.type === 'named') {
+          optionalPart += seg.regex;
+          segmentNames.push({ name: seg.name, index: groupIndex, type: 'named' });
+          groupIndex++;
+        } else {
+          optionalPart += seg.regex;
+        }
+        
+        j++;
+      }
+      
+      regex += `(?:${optionalPart})?`;
+      i = j;
+      continue;
+    }
+
+    if (segment.type === 'wildcard') {
+      regex += '(.*)';
+      segmentNames.push({ name: '_', index: groupIndex, type: 'wildcard' });
+      groupIndex++;
+    } else if (segment.type === 'named') {
+      regex += segment.regex;
+      segmentNames.push({ name: segment.name, index: groupIndex, type: 'named' });
+      groupIndex++;
+    } else {
+      regex += segment.regex;
+    }
+    
+    i++;
+  }
+
+  regex += '$';
+  
+  return { regex, segmentNames };
+};
+
+/**
+ * Creates a compiled pattern from a string
+ * @param {string} pattern - Pattern string
+ * @param {UrlPatternOptions} [options={}] - Options
+ * @returns {CompiledPattern} Compiled pattern
+ */
+const makePattern = (pattern, options = {}) => {
+  const mergedOptions = mergeOptions(options);
+  const segments = parsePattern(pattern, mergedOptions);
+  const { regex, segmentNames } = compileRegex(segments);
+
+  return {
+    regex,
+    regexObj: new RegExp(regex),
+    segments,
+    segmentNames,
+    options: mergedOptions,
+    isRegex: false,
+    pattern
+  };
+};
+
+/**
+ * Creates a compiled pattern from a regex
+ * @param {RegExp} regex - Regex pattern
+ * @param {Array<string>} [keys=[]] - Array of key names for captured groups
+ * @returns {CompiledPattern} Compiled pattern
+ */
+const makePatternFromRegex = (regex, keys = []) => {
+  return {
+    regex: regex.source,
+    regexObj: regex,
+    segments: [],
+    segmentNames: keys.map((name, index) => ({ name, index, type: 'named' })),
+    options: DEFAULT_OPTIONS,
+    isRegex: true,
+    keys
+  };
+};
+
+/**
+ * Matches a string against a compiled pattern
+ * @param {CompiledPattern} compiled - Compiled pattern
+ * @param {string} str - String to match
+ * @returns {Object|null} Extracted values or null if no match
+ */
+const match = (compiled, str) => {
+  const matchResult = compiled.regexObj.exec(str);
+  
+  if (!matchResult) {
+    return null;
+  }
+
+  if (compiled.isRegex) {
+    if (compiled.keys && compiled.keys.length > 0) {
+      const result = {};
+      compiled.keys.forEach((key, index) => {
+        const val = matchResult[index + 1];
+        result[key] = val !== undefined ? val : null;
+      });
+      return result;
+    }
+    return matchResult.slice(1);
+  }
+
+  const result = {};
+  const usedNames = new Set();
+
+  for (let i = 0; i < compiled.segmentNames.length; i++) {
+    const segInfo = compiled.segmentNames[i];
+    const value = matchResult[segInfo.index + 1] || '';
+    
+    if (usedNames.has(segInfo.name)) {
+      if (!Array.isArray(result[segInfo.name])) {
+        result[segInfo.name] = [result[segInfo.name]];
+      }
+      result[segInfo.name].push(value);
+    } else {
+      usedNames.add(segInfo.name);
+      result[segInfo.name] = value;
+    }
+  }
+
+  for (const key in result) {
+    if (result[key] === '') {
+      delete result[key];
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Stringifies a pattern with given values
+ * @param {CompiledPattern} compiled - Compiled pattern
+ * @param {Object} [values={}] - Values to stringify
+ * @returns {string} Generated string
+ * @throws {Error} If required values are missing
+ */
+const stringify = (compiled, values = {}) => {
+  if (compiled.isRegex) {
+    throw new Error('Cannot stringify a pattern created from regex');
+  }
+
+  let result = '';
+  let i = 0;
+  
+  while (i < compiled.segments.length) {
+    const segment = compiled.segments[i];
+    
+    if (segment.optional) {
+      let optionalPart = '';
+      let j = i;
+      
+      while (j < compiled.segments.length && compiled.segments[j].optional) {
+        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 {
+            optionalPart = '';
+            break;
+          }
+        } else if (seg.type === 'wildcard') {
+          const val = values._;
+          if (val !== undefined && val !== null && val !== '') {
+            optionalPart += Array.isArray(val) ? val.join('/') : val;
+          } else {
+            optionalPart = '';
+            break;
+          }
+        }
+        
+        j++;
+      }
+      
+      if (optionalPart !== '') {
+        result += optionalPart;
+      }
+      
+      if (i === j) {
+        i++;
+      } else {
+        i = j;
+      }
+      continue;
+    }
+
+    if (segment.type === 'literal') {
+      result += segment.name;
+    } else if (segment.type === 'named') {
+      const value = values[segment.name];
+      if (value === undefined || value === null || 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 === '') {
+        throw new Error('Missing required wildcard value');
+      }
+      result += Array.isArray(value) ? value.join('/') : value;
+    }
+    
+    i++;
+  }
+
+  return result;
+};
+
+/**
+ * UrlPattern class for matching and generating URLs
+ */
+class UrlPattern {
+  /**
+   * @param {string|RegExp} pattern - Pattern string or regex
+   * @param {UrlPatternOptions|Array<string>} [options={}] - Options or keys (for regex)
+   */
+  constructor(pattern, options = {}) {
+    if (pattern instanceof RegExp) {
+      const keys = Array.isArray(options) ? options : [];
+      /** @type {CompiledPattern} */
+      this.compiled = makePatternFromRegex(pattern, keys);
+    } else {
+      /** @type {CompiledPattern} */
+      this.compiled = makePattern(pattern, /** @type {UrlPatternOptions} */ (options));
+    }
+  }
+
+  /**
+   * Match a string against the pattern
+   * @param {string} str - String to match
+   * @returns {Object|null} Extracted values or null if no match
+   */
+  match(str) {
+    return match(this.compiled, str);
+  }
+
+  /**
+   * Generate a string from the pattern
+   * @param {Object} [values={}] - Values to stringify
+   * @returns {string} Generated string
+   */
+  stringify(values) {
+    return stringify(this.compiled, values);
+  }
+}
+
+/**
+ * Creates a new UrlPattern instance (functional API)
+ * @param {string|RegExp} pattern - Pattern string or regex
+ * @param {UrlPatternOptions|Array<string>} [options={}] - Options or keys
+ * @returns {UrlPattern} UrlPattern instance
+ */
+const urlPattern = (pattern, options = {}) => {
+  return new UrlPattern(pattern, options);
+};
+
+exports.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
+exports.UrlPattern = UrlPattern;
+exports.default = UrlPattern;
+exports.makePattern = makePattern;
+exports.makePatternFromRegex = makePatternFromRegex;
+exports.match = match;
+exports.stringify = stringify;
+exports.urlPattern = urlPattern;