@chaisser/regex-humanizer 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +296 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
# 🔍 @chaisser/regex-humanizer
|
|
2
|
+
|
|
3
|
+
> **Convert regex patterns to human-readable descriptions with English and Turkish support**
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ✨ Features
|
|
8
|
+
|
|
9
|
+
- 🎯 **Type-safe** - Full TypeScript support
|
|
10
|
+
- 🌍 **Multi-locale** - English and Turkish descriptions
|
|
11
|
+
- 📖 **Humanize** - Convert patterns to plain-text descriptions
|
|
12
|
+
- 📋 **Explain** - Detailed token-by-token breakdown
|
|
13
|
+
- 🧩 **Comprehensive** - Supports anchors, character classes, quantifiers, groups, lookaheads, escapes
|
|
14
|
+
- 🪶 **Zero dependencies** - Lightweight and tree-shakeable
|
|
15
|
+
- 🏎️ **ESM + CJS** - Dual module format support
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 📦 Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install @chaisser/regex-humanizer
|
|
23
|
+
# or
|
|
24
|
+
yarn add @chaisser/regex-humanizer
|
|
25
|
+
# or
|
|
26
|
+
pnpm add @chaisser/regex-humanizer
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 🚀 Quick Start
|
|
32
|
+
|
|
33
|
+
```typescript
|
|
34
|
+
import { humanize, explain } from '@chaisser/regex-humanizer';
|
|
35
|
+
|
|
36
|
+
// Simple humanization
|
|
37
|
+
humanize('^\\w+@\\w+\\.\\w+$');
|
|
38
|
+
// "start of string any word character one or more times @ any word character one or more times . any word character one or more times end of string"
|
|
39
|
+
|
|
40
|
+
// Detailed explanation
|
|
41
|
+
const result = explain('\\d{3}-\\d{4}');
|
|
42
|
+
console.log(result.description);
|
|
43
|
+
// "any digit between 3 and 3 times - any digit between 4 and 4 times"
|
|
44
|
+
console.log(result.breakdown);
|
|
45
|
+
// ["\\d → any digit", "{3} → exactly 3 times", "\\d → any digit", "{4} → exactly 4 times"]
|
|
46
|
+
|
|
47
|
+
// Turkish locale
|
|
48
|
+
humanize('^\\w+$', { locale: 'tr' });
|
|
49
|
+
// "satır başı herhangi bir kelime karakteri ... satır sonu"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 📖 What It Does
|
|
55
|
+
|
|
56
|
+
This package converts regular expression patterns into human-readable descriptions. It parses regex tokens — anchors, character classes, quantifiers, groups, lookaheads, and escape sequences — and translates each one into natural language. It also provides a detailed breakdown explaining each token individually.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 🎯 How It Works
|
|
61
|
+
|
|
62
|
+
The package provides two main functions:
|
|
63
|
+
|
|
64
|
+
- **`humanize`** - Parses a regex pattern and produces a single readable description string
|
|
65
|
+
- **`explain`** - Returns both a description and a token-by-token breakdown array
|
|
66
|
+
|
|
67
|
+
Supported token types:
|
|
68
|
+
- **Anchors** - `^`, `$`, `\b`, `\B`
|
|
69
|
+
- **Wildcards** - `.`
|
|
70
|
+
- **Quantifiers** - `*`, `+`, `?`, `{n}`, `{n,}`, `{n,m}`
|
|
71
|
+
- **Character classes** - `[a-z]`, `[A-Z]`, `[0-9]`, and custom classes
|
|
72
|
+
- **Shorthand classes** - `\d`, `\D`, `\w`, `\W`, `\s`, `\S`
|
|
73
|
+
- **Groups** - `(...)`, `(?:...)`, `(?=...)`, `(?!...)`
|
|
74
|
+
- **Escape sequences** - `\n`, `\r`, `\t`
|
|
75
|
+
- **Alternation** - `|`
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 🎨 What It's Useful For
|
|
80
|
+
|
|
81
|
+
- **Documentation** - Auto-generate regex descriptions for API docs
|
|
82
|
+
- **Debugging** - Understand complex regex patterns at a glance
|
|
83
|
+
- **Education** - Teach regex by showing what each token means
|
|
84
|
+
- **Code Review** - Make regex patterns readable in pull requests
|
|
85
|
+
- **Accessibility** - Present regex logic in plain language
|
|
86
|
+
- **Internationalization** - Describe patterns in English or Turkish
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 💡 Usage Examples
|
|
91
|
+
|
|
92
|
+
### Basic Patterns
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
import { humanize } from '@chaisser/regex-humanizer';
|
|
96
|
+
|
|
97
|
+
// Email-like pattern
|
|
98
|
+
humanize('^\\w+@\\w+\\.\\w+$');
|
|
99
|
+
// "start of string any word character one or more times @ ..."
|
|
100
|
+
|
|
101
|
+
// Phone number pattern
|
|
102
|
+
humanize('\\d{3}-\\d{3}-\\d{4}');
|
|
103
|
+
// "any digit exactly 3 times - any digit exactly 3 times - any digit exactly 4 times"
|
|
104
|
+
|
|
105
|
+
// Optional suffix
|
|
106
|
+
humanize('colou?r');
|
|
107
|
+
// "c o l o zero or one time (optional) r"
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Character Classes
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
humanize('[a-zA-Z]+');
|
|
114
|
+
// "any letter one or more times"
|
|
115
|
+
|
|
116
|
+
humanize('[0-9]{2,4}');
|
|
117
|
+
// "any digit between 2 and 4 times"
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Groups and Lookaheads
|
|
121
|
+
|
|
122
|
+
```typescript
|
|
123
|
+
// Capturing group
|
|
124
|
+
humanize('(\\d+)-(\\d+)');
|
|
125
|
+
// "(capturing group: any digit one or more times) - (capturing group: any digit one or more times)"
|
|
126
|
+
|
|
127
|
+
// Non-capturing group
|
|
128
|
+
humanize('(?:ab)+');
|
|
129
|
+
// "(non-capturing group: a b) one or more times"
|
|
130
|
+
|
|
131
|
+
// Positive lookahead
|
|
132
|
+
humanize('\\w+(?=\\.)');
|
|
133
|
+
// "any word character one or more times (positive lookahead: .)"
|
|
134
|
+
|
|
135
|
+
// Negative lookahead
|
|
136
|
+
humanize('foo(?!bar)');
|
|
137
|
+
// "f o o (negative lookahead: b a r)"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Detailed Explanation
|
|
141
|
+
|
|
142
|
+
```typescript
|
|
143
|
+
import { explain } from '@chaisser/regex-humanizer';
|
|
144
|
+
|
|
145
|
+
const result = explain('^\\d{4}-\\d{2}-\\d{2}$');
|
|
146
|
+
|
|
147
|
+
console.log(result.pattern); // "^\\d{4}-\\d{2}-\\d{2}$"
|
|
148
|
+
console.log(result.description); // Full readable description
|
|
149
|
+
console.log(result.breakdown);
|
|
150
|
+
// [
|
|
151
|
+
// "^ → start of string",
|
|
152
|
+
// "\\d → any digit",
|
|
153
|
+
// "{4} → exactly 4 times",
|
|
154
|
+
// "\\d → any digit",
|
|
155
|
+
// "{2} → exactly 2 times",
|
|
156
|
+
// "\\d → any digit",
|
|
157
|
+
// "{2} → exactly 2 times",
|
|
158
|
+
// "$ → end of string"
|
|
159
|
+
// ]
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Turkish Locale
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
humanize('^\\w+$', { locale: 'tr' });
|
|
166
|
+
// "satır başı herhangi bir kelime karakteri bir veya daha fazla kez satır sonu"
|
|
167
|
+
|
|
168
|
+
explain('\\d+', { locale: 'tr' });
|
|
169
|
+
// breakdown: ["\\d → herhangi bir rakam", "+ → bir veya daha fazla kez"]
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## 📚 API Reference
|
|
175
|
+
|
|
176
|
+
### `humanize(pattern, options?)`
|
|
177
|
+
|
|
178
|
+
Converts a regex pattern to a human-readable description string.
|
|
179
|
+
|
|
180
|
+
| Parameter | Type | Description |
|
|
181
|
+
|---|---|---|
|
|
182
|
+
| `pattern` | `string` | The regex pattern to humanize |
|
|
183
|
+
| `options.locale` | `'en' \| 'tr'` | Language for descriptions (default: `'en'`) |
|
|
184
|
+
|
|
185
|
+
**Returns:** `string` — Human-readable description
|
|
186
|
+
|
|
187
|
+
### `explain(pattern, options?)`
|
|
188
|
+
|
|
189
|
+
Returns a detailed breakdown of a regex pattern.
|
|
190
|
+
|
|
191
|
+
| Parameter | Type | Description |
|
|
192
|
+
|---|---|---|
|
|
193
|
+
| `pattern` | `string` | The regex pattern to explain |
|
|
194
|
+
| `options.locale` | `'en' \| 'tr'` | Language for descriptions (default: `'en'`) |
|
|
195
|
+
|
|
196
|
+
**Returns:**
|
|
197
|
+
|
|
198
|
+
```typescript
|
|
199
|
+
{
|
|
200
|
+
pattern: string; // Original pattern
|
|
201
|
+
description: string; // Full human-readable description
|
|
202
|
+
breakdown: string[]; // Token-by-token explanations
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### Supported Tokens
|
|
207
|
+
|
|
208
|
+
| Token | English | Turkish |
|
|
209
|
+
|---|---|---|
|
|
210
|
+
| `^` | start of string | satır başı |
|
|
211
|
+
| `$` | end of string | satır sonu |
|
|
212
|
+
| `.` | any character | herhangi bir karakter |
|
|
213
|
+
| `*` | zero or more times | sıfır veya daha fazla kez |
|
|
214
|
+
| `+` | one or more times | bir veya daha fazla kez |
|
|
215
|
+
| `?` | zero or one time (optional) | sıfır veya bir kez (opsiyonel) |
|
|
216
|
+
| `\|` | or | veya |
|
|
217
|
+
| `\d` | any digit | herhangi bir rakam |
|
|
218
|
+
| `\D` | any non-digit | herhangi bir rakam olmayan |
|
|
219
|
+
| `\w` | any word character | herhangi bir kelime karakteri |
|
|
220
|
+
| `\W` | any non-word character | herhangi bir kelime karakteri olmayan |
|
|
221
|
+
| `\s` | any whitespace | herhangi bir boşluk karakteri |
|
|
222
|
+
| `\S` | any non-whitespace | herhangi bir boşluk olmayan |
|
|
223
|
+
| `\b` | word boundary | kelime sınırı |
|
|
224
|
+
| `\B` | non-word boundary | kelime sınırı değil |
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## 🔗 Related Packages
|
|
229
|
+
|
|
230
|
+
Explore our other utility packages in the @chaisser namespace:
|
|
231
|
+
|
|
232
|
+
- **@chaisser/regex-humanizer** (this package) - Regex to human-readable descriptions
|
|
233
|
+
- [@chaisser/string-wizard](https://www.npmjs.com/package/@chaisser/string-wizard) - Advanced string manipulation
|
|
234
|
+
- [@chaisser/type-guard](https://www.npmjs.com/package/@chaisser/type-guard) - Runtime type guards and validators
|
|
235
|
+
- [@chaisser/uuid-v7](https://www.npmjs.com/package/@chaisser/uuid-v7) - Time-ordered UUID v7 generator
|
|
236
|
+
- [@chaisser/wait-for](https://www.npmjs.com/package/@chaisser/wait-for) - Promise-based wait utilities
|
|
237
|
+
- [@chaisser/human-time](https://www.npmjs.com/package/@chaisser/human-time) - Human-readable time formatting
|
|
238
|
+
- [@chaisser/obj-path](https://www.npmjs.com/package/@chaisser/obj-path) - Object path traversal
|
|
239
|
+
- [@chaisser/debounce-throttle](https://www.npmjs.com/package/@chaisser/debounce-throttle) - Rate limiting utilities
|
|
240
|
+
- [@chaisser/color-utils](https://www.npmjs.com/package/@chaisser/color-utils) - Color conversion utilities
|
|
241
|
+
- [@chaisser/deep-clone](https://www.npmjs.com/package/@chaisser/deep-clone) - Deep cloning functions
|
|
242
|
+
- [@chaisser/array-group-by](https://www.npmjs.com/package/@chaisser/array-group-by) - Array grouping utilities
|
|
243
|
+
- [@chaisser/password-strength](https://www.npmjs.com/package/@chaisser/password-strength) - Password strength checker
|
|
244
|
+
- [@chaisser/merge-objects](https://www.npmjs.com/package/@chaisser/merge-objects) - Object merge utilities
|
|
245
|
+
- [@chaisser/chunk-array](https://www.npmjs.com/package/@chaisser/chunk-array) - Array chunking functions
|
|
246
|
+
- [@chaisser/event-emitter](https://www.npmjs.com/package/@chaisser/event-emitter) - Typed event emitter
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## 🔒 License
|
|
251
|
+
|
|
252
|
+
**MIT** - Free to use in personal and commercial projects
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## 👨 Developed by
|
|
257
|
+
|
|
258
|
+
**Doruk Karaboncuk** <doruk.karaboncuk@interaktifis.com>
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 📄 Repository
|
|
263
|
+
|
|
264
|
+
- **GitHub:** [@chaisser](https://github.com/chaisser)
|
|
265
|
+
- **NPM:** [@chaisser/regex-humanizer](https://www.npmjs.com/package/@chaisser/regex-humanizer)
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## 🤝 Contributing
|
|
270
|
+
|
|
271
|
+
Contributions are welcome! Feel free to:
|
|
272
|
+
- Report bugs
|
|
273
|
+
- Suggest new features
|
|
274
|
+
- Submit pull requests
|
|
275
|
+
- Improve documentation
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## 📞 Support
|
|
280
|
+
|
|
281
|
+
For issues, questions, or suggestions, please reach out through:
|
|
282
|
+
- **Email:** doruk.karaboncuk@interaktifis.com
|
|
283
|
+
- **GitHub Issues:** [Create an issue](https://github.com/chaisser/regex-humanizer/issues)
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
<div align="center">
|
|
288
|
+
|
|
289
|
+
Made with ❤️ by [@chaisser](https://www.npmjs.com/package/@chaisser)
|
|
290
|
+
|
|
291
|
+
[](https://www.npmjs.com/package/@chaisser/regex-humanizer)
|
|
292
|
+
[](https://www.npmjs.com/package/@chaisser/regex-humanizer)
|
|
293
|
+
[](https://www.npmjs.com/package/@chaisser/regex-humanizer)
|
|
294
|
+
[](https://www.npmjs.com/package/@chaisser/regex-humanizer)
|
|
295
|
+
|
|
296
|
+
</div>
|