or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-to-regex-range

Generate regex-compatible source strings for matching numeric ranges with high performance and optimization.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/to-regex-range@5.0.x

To install, run

npx @tessl/cli install tessl/npm-to-regex-range@5.0.0

index.mddocs/

To Regex Range

To Regex Range is a high-performance utility library that generates regex-compatible source strings for matching numeric ranges. It converts two numbers into an optimized regular expression pattern that matches all numbers within the specified range, with support for negative numbers, zero-padding, and various optimization options.

Package Information

  • Package Name: to-regex-range
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install to-regex-range

Core Imports

const toRegexRange = require("to-regex-range");

Basic Usage

const toRegexRange = require("to-regex-range");

// Generate regex pattern for range 15-95
const source = toRegexRange("15", "95");
//=> "1[5-9]|[2-8][0-9]|9[0-5]"

// Use with RegExp constructor
const regex = new RegExp(`^${source}$`);
console.log(regex.test("50")); //=> true
console.log(regex.test("14")); //=> false
console.log(regex.test("96")); //=> false

// Single number (min equals max)
const single = toRegexRange("5", "5");
//=> "5"

// Adjacent numbers
const adjacent = toRegexRange("5", "6");
//=> "5|6"

Capabilities

Range Generation

Generates optimized regex patterns for numeric ranges with various configuration options.

/**
 * Generate regex-compatible source string for matching numeric ranges
 * @param {number|string} min - Minimum value of the range
 * @param {number|string} [max] - Maximum value of the range (optional, defaults to min)
 * @param {RangeOptions} [options] - Configuration options
 * @returns {string} Regex pattern string
 * @throws {TypeError} When min or max arguments are not numbers
 */
function toRegexRange(min, max?, options?);

interface RangeOptions {
  /** Wrap result in capturing parentheses when multiple conditions exist */
  capture?: boolean;
  /** Use \\d shorthand instead of [0-9] for digit ranges */
  shorthand?: boolean;
  /** Allow flexible matching for zero-padded numbers (default: true) */
  relaxZeros?: boolean;
  /** Legacy option - sets relaxZeros to opposite value */
  strictZeros?: boolean;
  /** Wrap result in non-capturing group when multiple conditions (default: true) */
  wrap?: boolean;
}

Usage Examples:

// Single argument (max undefined)
toRegexRange("42");
//=> "42"

// Basic range
toRegexRange("1", "100");
//=> "[1-9]|[1-9][0-9]|100"

// With capture option
toRegexRange("-10", "10", { capture: true });
//=> "(-[1-9]|-?10|[0-9])"

// With shorthand option
toRegexRange("0", "999999", { shorthand: true });
//=> "\\d|[1-9]\\d{1,5}"

// Zero-padded ranges with relaxZeros (default: true)
toRegexRange("001", "100");
//=> "(?:0{0,2}[1-9]|0?[1-9][0-9]|100)"

// Strict zero matching  
toRegexRange("-0010", "0010", { relaxZeros: false });
//=> Complex pattern enforcing exact zero-padding

// Without wrapping (disables default non-capturing groups)
toRegexRange("1", "3", { wrap: false });
//=> "[1-3]"

// Arguments automatically swapped when min > max
toRegexRange("10", "5"); 
//=> "(?:[5-9]|10)" (same as toRegexRange("5", "10"))

Cache Management

Built-in caching system for performance optimization.

/**
 * Internal cache object storing computed regex patterns
 * @type {Object}
 */
toRegexRange.cache;

/**
 * Clear the internal pattern cache
 * @returns {void}
 */
toRegexRange.clearCache();

Usage Examples:

// Access cache (readonly)
console.log(Object.keys(toRegexRange.cache));

// Clear cache when needed
toRegexRange.clearCache();
console.log(Object.keys(toRegexRange.cache)); //=> []

Error Handling

The library throws TypeError exceptions for invalid input arguments:

// TypeError: toRegexRange: expected the first argument to be a number
toRegexRange();
toRegexRange("invalid");

// TypeError: toRegexRange: expected the second argument to be a number.
toRegexRange(1, {});
toRegexRange(1, "invalid");

Performance Features

  • Fragment Caching: Identical range patterns are cached to avoid recomputation
  • Pattern Optimization: Uses quantifiers and character classes for compact patterns
  • Smart Conditional Logic: Handles positive/negative number ranges efficiently
  • Duplicate Reduction: Eliminates redundant pattern sequences

Range Behavior

  • Single Argument: When max is undefined, returns min as a string
  • Argument Order: When min > max, arguments are automatically swapped
  • Single Values: When min equals max, returns the number as a string
  • Adjacent Numbers: Special handling for consecutive numbers (e.g., "5|6")
  • Negative Ranges: Full support for negative number ranges
  • Zero Padding: Automatic detection and handling of zero-padded inputs
  • Wrapping: Results are wrapped in non-capturing groups (?:...) by default when multiple conditions exist, unless wrap: false is specified

Types

/**
 * Configuration options for range generation
 */
interface RangeOptions {
  /** Wrap result in capturing parentheses when multiple conditions exist */
  capture?: boolean;
  /** Use \\d shorthand instead of [0-9] for digit ranges */
  shorthand?: boolean;
  /** Allow flexible matching for zero-padded numbers (default: true) */
  relaxZeros?: boolean;
  /** Legacy option - sets relaxZeros to opposite value */
  strictZeros?: boolean;
  /** Wrap result in non-capturing group when multiple conditions (default: true) */
  wrap?: boolean;
}