0
# Jest Regex Util
1

2
Jest Regex Util provides essential regular expression utilities for the Jest testing framework, specifically designed to handle cross-platform file path operations. It offers three core functions for escaping paths and strings for use in regular expressions, with special handling for cross-platform path separators.
3

4
## Package Information
5

6
- **Package Name**: jest-regex-util
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jest-regex-util`
10

11
## Core Imports
12

13
```typescript
14
import { escapePathForRegex, escapeStrForRegex, replacePathSepForRegex } from "jest-regex-util";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { escapePathForRegex, escapeStrForRegex, replacePathSepForRegex } = require("jest-regex-util");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { escapePathForRegex, escapeStrForRegex, replacePathSepForRegex } from "jest-regex-util";
27

28
// Escape a file path for regex use (cross-platform)
29
const safePath = escapePathForRegex("/path/to/file.js");
30
const regex = new RegExp(safePath);
31

32
// Escape a string with regex special characters
33
const safeString = escapeStrForRegex("file(1).js");
34
// Result: "file\\(1\\)\\.js"
35

36
// Convert path separators for regex compatibility
37
const regexPath = replacePathSepForRegex("/path/with/slashes");
38
// On Windows: "\\\\path\\\\with\\\\slashes"
39
// On POSIX: "/path/with/slashes" (unchanged)
40
```
41

42
## Capabilities
43

44
### Path Escaping
45

46
Escapes a complete file path for use in regular expressions with cross-platform path separator handling.
47

48
```typescript { .api }
49
/**
50
 * Escapes a file path for use in regular expressions with cross-platform handling
51
 * @param dir - File path to escape
52
 * @returns Escaped path suitable for regex patterns
53
 */
54
function escapePathForRegex(dir: string): string;
55
```
56

57
This function handles the complete workflow of preparing a file path for regex use:
58
1. On Windows, converts backslashes to forward slashes to prevent double-escaping
59
2. Escapes all regex special characters using `escapeStrForRegex`
60
3. Converts path separators to platform-appropriate regex patterns using `replacePathSepForRegex`
61

62
### String Escaping
63

64
Escapes special regex characters in a string to make it literal for use in regular expressions.
65

66
```typescript { .api }
67
/**
68
 * Escapes special regex characters in a string to make it literal
69
 * @param string - String to escape
70
 * @returns String with regex characters escaped
71
 */
72
function escapeStrForRegex(string: string): string;
73
```
74

75
Escapes the following regex special characters: `$()*+.?[\]^{|}`
76

77
**Usage Example:**
78

79
```typescript
80
import { escapeStrForRegex } from "jest-regex-util";
81

82
const userInput = "user(name).txt";
83
const escaped = escapeStrForRegex(userInput);
84
// Result: "user\\(name\\)\\.txt"
85

86
// Safe to use in regex
87
const regex = new RegExp(escaped);
88
```
89

90
### Path Separator Replacement
91

92
Converts path separators to be regex-compatible across different platforms (Windows vs POSIX).
93

94
```typescript { .api }
95
/**
96
 * Converts path separators to be regex-compatible across platforms
97
 * @param string - String containing path separators
98
 * @returns String with platform-appropriate escaped separators
99
 */
100
function replacePathSepForRegex(string: string): string;
101
```
102

103
**Platform Behavior:**
104
- **POSIX systems**: Returns the string unchanged (forward slashes are regex-safe)
105
- **Windows systems**: Converts both forward slashes and backslashes to escaped backslashes (`\\\\`)
106

107
**Special handling on Windows:**
108
- Preserves already-escaped regex characters to avoid double-escaping
109
- Handles edge cases like escaped dots (`\\.`) and other regex symbols
110
- Correctly processes path separators within character classes (`[/\\]`)
111

112
**Usage Example:**
113

114
```typescript
115
import { replacePathSepForRegex } from "jest-regex-util";
116

117
// On Windows
118
const windowsPath = replacePathSepForRegex("src/utils/helper.js");
119
// Result: "src\\\\utils\\\\helper.js"
120

121
// On POSIX
122
const posixPath = replacePathSepForRegex("src/utils/helper.js");
123
// Result: "src/utils/helper.js" (unchanged)
124
```