🔍 @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 [email protected]

📄 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: [email protected]
• GitHub Issues: Create an issue

Made with ❤️ by @chaisser