0
# To Regex Range
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: to-regex-range
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install to-regex-range`
10

11
## Core Imports
12

13
```javascript
14
const toRegexRange = require("to-regex-range");
15
```
16

17
## Basic Usage
18

19
```javascript
20
const toRegexRange = require("to-regex-range");
21

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

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

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

36
// Adjacent numbers
37
const adjacent = toRegexRange("5", "6");
38
//=> "5|6"
39
```
40

41
## Capabilities
42

43
### Range Generation
44

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

47
```javascript { .api }
48
/**
49
 * Generate regex-compatible source string for matching numeric ranges
50
 * @param {number|string} min - Minimum value of the range
51
 * @param {number|string} [max] - Maximum value of the range (optional, defaults to min)
52
 * @param {RangeOptions} [options] - Configuration options
53
 * @returns {string} Regex pattern string
54
 * @throws {TypeError} When min or max arguments are not numbers
55
 */
56
function toRegexRange(min, max?, options?);
57

58
interface RangeOptions {
59
  /** Wrap result in capturing parentheses when multiple conditions exist */
60
  capture?: boolean;
61
  /** Use \\d shorthand instead of [0-9] for digit ranges */
62
  shorthand?: boolean;
63
  /** Allow flexible matching for zero-padded numbers (default: true) */
64
  relaxZeros?: boolean;
65
  /** Legacy option - sets relaxZeros to opposite value */
66
  strictZeros?: boolean;
67
  /** Wrap result in non-capturing group when multiple conditions (default: true) */
68
  wrap?: boolean;
69
}
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
// Single argument (max undefined)
76
toRegexRange("42");
77
//=> "42"
78

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

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

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

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

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

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

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

108
### Cache Management
109

110
Built-in caching system for performance optimization.
111

112
```javascript { .api }
113
/**
114
 * Internal cache object storing computed regex patterns
115
 * @type {Object}
116
 */
117
toRegexRange.cache;
118

119
/**
120
 * Clear the internal pattern cache
121
 * @returns {void}
122
 */
123
toRegexRange.clearCache();
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
// Access cache (readonly)
130
console.log(Object.keys(toRegexRange.cache));
131

132
// Clear cache when needed
133
toRegexRange.clearCache();
134
console.log(Object.keys(toRegexRange.cache)); //=> []
135
```
136

137
## Error Handling
138

139
The library throws `TypeError` exceptions for invalid input arguments:
140

141
```javascript
142
// TypeError: toRegexRange: expected the first argument to be a number
143
toRegexRange();
144
toRegexRange("invalid");
145

146
// TypeError: toRegexRange: expected the second argument to be a number.
147
toRegexRange(1, {});
148
toRegexRange(1, "invalid");
149
```
150

151
## Performance Features
152

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

158
## Range Behavior
159

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

168
## Types
169

170
```javascript { .api }
171
/**
172
 * Configuration options for range generation
173
 */
174
interface RangeOptions {
175
  /** Wrap result in capturing parentheses when multiple conditions exist */
176
  capture?: boolean;
177
  /** Use \\d shorthand instead of [0-9] for digit ranges */
178
  shorthand?: boolean;
179
  /** Allow flexible matching for zero-padded numbers (default: true) */
180
  relaxZeros?: boolean;
181
  /** Legacy option - sets relaxZeros to opposite value */
182
  strictZeros?: boolean;
183
  /** Wrap result in non-capturing group when multiple conditions (default: true) */
184
  wrap?: boolean;
185
}
186
```