0
# String & Path Utilities
1

2
Text formatting and path manipulation utilities for test output and file system operations. These functions provide cross-platform path handling and consistent text formatting for Jest's output systems.
3

4
## Capabilities
5

6
### Pluralize
7

8
Intelligently pluralizes words based on count, with customizable plural endings for proper grammatical output.
9

10
```typescript { .api }
11
/**
12
 * Pluralizes words based on count
13
 * @param word - Base word to pluralize
14
 * @param count - Count to determine pluralization
15
 * @param ending - Plural ending to append (default: 's')
16
 * @returns Formatted string with count and properly pluralized word
17
 */
18
function pluralize(word: string, count: number, ending = 's'): string;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { pluralize } from "jest-util";
25

26
// Basic pluralization
27
console.log(pluralize("test", 1)); // "1 test"
28
console.log(pluralize("test", 2)); // "2 tests"
29
console.log(pluralize("test", 0)); // "0 tests"
30

31
// Custom plural endings
32
console.log(pluralize("child", 1, "ren")); // "1 child"
33
console.log(pluralize("child", 2, "ren")); // "2 children"
34

35
console.log(pluralize("category", 1, "ies")); // "1 category" 
36
console.log(pluralize("category", 2, "ies")); // "2 categoryies" (Note: removes 'y' and adds ending)
37

38
// Jest test output usage
39
function reportTestResults(passed: number, failed: number, skipped: number) {
40
  console.log(`${pluralize("test", passed)} passed`);
41
  console.log(`${pluralize("test", failed)} failed`);
42
  console.log(`${pluralize("test", skipped)} skipped`);
43
}
44

45
// Examples:
46
// reportTestResults(1, 0, 0) → "1 test passed", "0 tests failed", "0 tests skipped"
47
// reportTestResults(5, 2, 1) → "5 tests passed", "2 tests failed", "1 test skipped"
48

49
// File operation reporting
50
const fileCount = 15;
51
console.log(`Processed ${pluralize("file", fileCount)}`); // "Processed 15 files"
52

53
const errorCount = 1;
54
console.log(`Found ${pluralize("error", errorCount)}`); // "Found 1 error"
55
```
56

57
### Format Time
58

59
Formats time values with appropriate unit prefixes (nanoseconds, microseconds, milliseconds, seconds) for human-readable display.
60

61
```typescript { .api }
62
/**
63
 * Formats time with appropriate unit prefixes
64
 * @param time - Time value to format
65
 * @param prefixPower - Power of 10 prefix (default: -3 for milliseconds)
66
 * @param padLeftLength - Left padding for time value (default: 0)
67
 * @returns Formatted time string with appropriate unit
68
 */
69
function formatTime(time: number, prefixPower = -3, padLeftLength = 0): string;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { formatTime } from "jest-util";
76

77
// Default millisecond formatting
78
console.log(formatTime(1500)); // "1.5 s"
79
console.log(formatTime(250)); // "250 ms"
80
console.log(formatTime(45)); // "45 ms"
81
console.log(formatTime(0.5)); // "500 μs"
82

83
// Nanosecond precision (prefixPower: -9)
84
console.log(formatTime(1000000, -9)); // "1 ms"
85
console.log(formatTime(500000, -9)); // "500 μs"
86
console.log(formatTime(1500, -9)); // "1.5 μs"
87
console.log(formatTime(750, -9)); // "750 ns"
88

89
// Microsecond precision (prefixPower: -6)
90
console.log(formatTime(1000, -6)); // "1 ms"
91
console.log(formatTime(500, -6)); // "500 μs"
92

93
// With padding for aligned output
94
console.log(formatTime(5, -3, 6)); // "     5 ms"
95
console.log(formatTime(150, -3, 6)); // "   150 ms"
96
console.log(formatTime(1200, -3, 6)); // "  1.2 s"
97

98
// Jest test timing usage
99
function reportTestTiming(testName: string, duration: number) {
100
  console.log(`${testName}: ${formatTime(duration)}`);
101
}
102

103
// Examples:
104
// reportTestTiming("API test", 1250) → "API test: 1.25 s"
105
// reportTestTiming("Unit test", 45) → "Unit test: 45 ms"
106
// reportTestTiming("Quick test", 0.8) → "Quick test: 800 μs"
107
```
108

109
### Replace Path Separator For Glob
110

111
Converts Windows-style path separators to forward slashes for use in glob patterns, while preserving regex special characters.
112

113
```typescript { .api }
114
/**
115
 * Converts Windows path separators to forward slashes for glob patterns
116
 * @param path - Path to convert
117
 * @returns Path with forward slashes, preserving regex special characters
118
 */
119
function replacePathSepForGlob(path: string): string;
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
import { replacePathSepForGlob } from "jest-util";
126

127
// Windows path conversion
128
console.log(replacePathSepForGlob("src\\components\\Button.tsx")); 
129
// "src/components/Button.tsx"
130

131
console.log(replacePathSepForGlob("C:\\Projects\\MyApp\\test\\*.spec.js"));
132
// "C:/Projects/MyApp/test/*.spec.js"
133

134
// Unix paths remain unchanged
135
console.log(replacePathSepForGlob("src/components/Button.tsx"));
136
// "src/components/Button.tsx"
137

138
// Preserves regex special characters
139
console.log(replacePathSepForGlob("src\\test\\**\\*.{js,ts}"));
140
// "src/test/**/*.{js,ts}"
141

142
// Jest test pattern usage
143
const testPatterns = [
144
  "src\\__tests__\\**\\*.test.js",
145
  "tests\\integration\\*.spec.ts",
146
  "**\\__mocks__\\**\\*"
147
];
148

149
const normalizedPatterns = testPatterns.map(replacePathSepForGlob);
150
// [
151
//   "src/__tests__/**/*.test.js",
152
//   "tests/integration/*.spec.ts", 
153
//   "**/__mocks__/**/*"
154
// ]
155
```
156

157
### Globs To Matcher
158

159
Converts an array of glob patterns into an optimized matching function, with support for negated patterns and caching.
160

161
```typescript { .api }
162
/**
163
 * Converts glob patterns to optimized matching function
164
 * @param globs - Array of glob patterns (supports negation with '!')
165
 * @returns Matcher function that tests paths against patterns
166
 */
167
function globsToMatcher(globs: Array<string>): Matcher;
168

169
type Matcher = (str: string) => boolean;
170
```
171

172
**Usage Examples:**
173

174
```typescript
175
import { globsToMatcher } from "jest-util";
176

177
// Basic pattern matching
178
const matcher = globsToMatcher(["**/*.test.js", "**/*.spec.js"]);
179

180
console.log(matcher("src/utils.test.js")); // true
181
console.log(matcher("src/component.spec.js")); // true
182
console.log(matcher("src/utils.js")); // false
183

184
// Negated patterns (exclusions)
185
const testMatcher = globsToMatcher([
186
  "**/*.test.js",
187
  "**/*.spec.js", 
188
  "!**/node_modules/**",
189
  "!**/build/**"
190
]);
191

192
console.log(testMatcher("src/utils.test.js")); // true
193
console.log(testMatcher("node_modules/lib/test.js")); // false (excluded)
194
console.log(testMatcher("build/test.spec.js")); // false (excluded)
195

196
// Complex Jest configuration
197
const jestMatcher = globsToMatcher([
198
  "src/**/*.{js,ts}",
199
  "test/**/*.{js,ts}",
200
  "!**/*.d.ts",
201
  "!**/node_modules/**",
202
  "!**/coverage/**",
203
  "!**/build/**"
204
]);
205

206
// Test file discovery
207
const candidateFiles = [
208
  "src/components/Button.js",
209
  "src/types.d.ts",
210
  "test/Button.test.js",
211
  "node_modules/react/index.js",
212
  "coverage/report.js",
213
  "build/main.js"
214
];
215

216
const matchingFiles = candidateFiles.filter(jestMatcher);
217
// ["src/components/Button.js", "test/Button.test.js"]
218

219
// Performance optimization - matcher is cached internally
220
const largeMatcher = globsToMatcher([
221
  "**/*.{js,jsx,ts,tsx}",
222
  "!**/node_modules/**",
223
  "!**/dist/**",
224
  "!**/*.min.js"
225
]);
226

227
// Multiple calls reuse compiled patterns for efficiency
228
const results = candidateFiles.map(file => largeMatcher(file));
229
```
230

231
**Pattern Syntax:**
232
- `*` - Matches any characters except path separators
233
- `**` - Matches any characters including path separators (recursive)
234
- `?` - Matches single character
235
- `{a,b}` - Matches either 'a' or 'b'
236
- `!pattern` - Negates the pattern (excludes matches)
237
- `[abc]` - Matches any character in brackets
238

239
**Performance Features:**
240
- **Pattern Caching**: Compiled patterns are cached for repeated use
241
- **Optimized Ordering**: Positive patterns are checked before negative patterns
242
- **Early Exit**: Returns false immediately when excluded by negated pattern
243

244
## Types
245

246
```typescript { .api }
247
type Matcher = (str: string) => boolean;
248
```