🔍 @chaisser/regex-humanizer

Convert regex patterns to human-readable descriptions with English and Turkish support

---

✨ Features

• 🎯 Type-safe - Full TypeScript support
• 🌍 Multi-locale - English and Turkish descriptions
• 📖 Humanize - Convert patterns to plain-text descriptions
• 📋 Explain - Detailed token-by-token breakdown
• 🧩 Comprehensive - Supports anchors, character classes, quantifiers, groups, lookaheads, escapes
• 🪶 Zero dependencies - Lightweight and tree-shakeable
• 🏎️ ESM + CJS - Dual module format support

---

📦 Installation

npm install @chaisser/regex-humanizer
# or
yarn add @chaisser/regex-humanizer
# or
pnpm add @chaisser/regex-humanizer

---

🚀 Quick Start

import { humanize, explain } from '@chaisser/regex-humanizer';

// Simple humanization
humanize('^\\w+@\\w+\\.\\w+$');
// "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"

// Detailed explanation
const result = explain('\\d{3}-\\d{4}');
console.log(result.description);
// "any digit between 3 and 3 times - any digit between 4 and 4 times"
console.log(result.breakdown);
// ["\\d → any digit", "{3} → exactly 3 times", "\\d → any digit", "{4} → exactly 4 times"]

// Turkish locale
humanize('^\\w+$', { locale: 'tr' });
// "satır başı herhangi bir kelime karakteri ... satır sonu"

---

📖 What It Does

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.

---

🎯 How It Works

The package provides two main functions:

• humanize - Parses a regex pattern and produces a single readable description string
• explain - Returns both a description and a token-by-token breakdown array

Supported token types:

• Anchors - ^, $, \b, \B
• Wildcards - .
• Quantifiers - *, +, ?, {n}, {n,}, {n,m}
• Character classes - [a-z], [A-Z], [0-9], and custom classes
• Shorthand classes - \d, \D, \w, \W, \s, \S
• Groups - (...), (?:...), (?=...), (?!...)
• Escape sequences - \n, \r, \t
• Alternation - |

---

🎨 What It's Useful For

• Documentation - Auto-generate regex descriptions for API docs
• Debugging - Understand complex regex patterns at a glance
• Education - Teach regex by showing what each token means
• Code Review - Make regex patterns readable in pull requests
• Accessibility - Present regex logic in plain language
• Internationalization - Describe patterns in English or Turkish

---

💡 Usage Examples

Basic Patterns

import { humanize } from '@chaisser/regex-humanizer';

// Email-like pattern
humanize('^\\w+@\\w+\\.\\w+$');
// "start of string any word character one or more times @ ..."

// Phone number pattern
humanize('\\d{3}-\\d{3}-\\d{4}');
// "any digit exactly 3 times - any digit exactly 3 times - any digit exactly 4 times"

// Optional suffix
humanize('colou?r');
// "c o l o zero or one time (optional) r"

Character Classes

humanize('[a-zA-Z]+');
// "any letter one or more times"

humanize('[0-9]{2,4}');
// "any digit between 2 and 4 times"

Groups and Lookaheads

// Capturing group
humanize('(\\d+)-(\\d+)');
// "(capturing group: any digit one or more times) - (capturing group: any digit one or more times)"

// Non-capturing group
humanize('(?:ab)+');
// "(non-capturing group: a b) one or more times"

// Positive lookahead
humanize('\\w+(?=\\.)');
// "any word character one or more times (positive lookahead: .)"

// Negative lookahead
humanize('foo(?!bar)');
// "f o o (negative lookahead: b a r)"

Detailed Explanation

import { explain } from '@chaisser/regex-humanizer';

const result = explain('^\\d{4}-\\d{2}-\\d{2}$');

console.log(result.pattern);    // "^\\d{4}-\\d{2}-\\d{2}$"
console.log(result.description); // Full readable description
console.log(result.breakdown);
// [
//   "^ → start of string",
//   "\\d → any digit",
//   "{4} → exactly 4 times",
//   "\\d → any digit",
//   "{2} → exactly 2 times",
//   "\\d → any digit",
//   "{2} → exactly 2 times",
//   "$ → end of string"
// ]

Turkish Locale

humanize('^\\w+$', { locale: 'tr' });
// "satır başı herhangi bir kelime karakteri bir veya daha fazla kez satır sonu"

explain('\\d+', { locale: 'tr' });
// breakdown: ["\\d → herhangi bir rakam", "+ → bir veya daha fazla kez"]

---

📚 API Reference

humanize(pattern, options?)

Converts a regex pattern to a human-readable description string.

Parameter	Type	Description
pattern	string	The regex pattern to humanize
options.locale	'en' | 'tr'	Language for descriptions (default: 'en')

Returns: string — Human-readable description

explain(pattern, options?)

Returns a detailed breakdown of a regex pattern.

Parameter	Type	Description
pattern	string	The regex pattern to explain
options.locale	'en' | 'tr'	Language for descriptions (default: 'en')

Returns:

{
  pattern: string;      // Original pattern
  description: string;  // Full human-readable description
  breakdown: string[];  // Token-by-token explanations
}

Supported Tokens

Token	English	Turkish
^	start of string	satır başı
$	end of string	satır sonu
.	any character	herhangi bir karakter
*	zero or more times	sıfır veya daha fazla kez
+	one or more times	bir veya daha fazla kez
?	zero or one time (optional)	sıfır veya bir kez (opsiyonel)
|	or	veya
\d	any digit	herhangi bir rakam
\D	any non-digit	herhangi bir rakam olmayan
\w	any word character	herhangi bir kelime karakteri
\W	any non-word character	herhangi bir kelime karakteri olmayan
\s	any whitespace	herhangi bir boşluk karakteri
\S	any non-whitespace	herhangi bir boşluk olmayan
\b	word boundary	kelime sınırı
\B	non-word boundary	kelime sınırı değil

---

🔗 Related Packages

Explore our other utility packages in the @chaisser namespace:

• @chaisser/regex-humanizer (this package) - Regex to human-readable descriptions
• @chaisser/string-wizard - Advanced string manipulation
• @chaisser/type-guard - Runtime type guards and validators
• @chaisser/uuid-v7 - Time-ordered UUID v7 generator
• @chaisser/wait-for - Promise-based wait utilities
• @chaisser/human-time - Human-readable time formatting
• @chaisser/obj-path - Object path traversal
• @chaisser/debounce-throttle - Rate limiting utilities
• @chaisser/color-utils - Color conversion utilities
• @chaisser/deep-clone - Deep cloning functions
• @chaisser/array-group-by - Array grouping utilities
• @chaisser/password-strength - Password strength checker
• @chaisser/merge-objects - Object merge utilities
• @chaisser/chunk-array - Array chunking functions
• @chaisser/event-emitter - Typed event emitter

---

🔒 License

MIT - Free to use in personal and commercial projects

---

👨 Developed by

Doruk Karaboncuk doruk.karaboncuk@interaktifis.com

---

📄 Repository

• GitHub: @chaisser
• NPM: @chaisser/regex-humanizer

---

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

---

📞 Support

For issues, questions, or suggestions, please reach out through:

• Email: doruk.karaboncuk@interaktifis.com
• GitHub Issues: Create an issue

---

Made with ❤️ by @chaisser