textConvert

textConvert is a lightweight, dependency-free TypeScript library for text conversion, validation, and analysis — including redact(), which masks PII embedded in free-form text before it hits a log or a database.

import { redact } from 'textconvert';

redact('Contact me at jordan@example.com or 555-123-4567');
// 'Contact me at jo**************** or 55**********'

📚 Table of Contents

📚 Table of Contents
🚀 Getting Started
- Installation
- Usage
- CLI
✨ Features
Why Use textConvert?
📋 API Reference
Quick Examples
Advanced Examples
Contributing
Changelog
Migration Guide
License
Contributors ✨

🚀 Getting Started

Installation

npm install textconvert

Usage

import * as convert from 'textconvert';

CLI

A redact command is included for sanitizing PII/secrets from the command line — no JS required:

npx textconvert redact input.log
npx textconvert redact input.log --types email,phone --mask-char '#'
cat input.log | npx textconvert redact > output.log

Reads from the given file, or from stdin if no file is given; always writes to stdout. Run npx textconvert --help for the full option list.

✨ Features

PII redaction: mask emails, phone numbers, credit card numbers, and (opt-in) public IPv4 addresses, API keys/tokens, and JWTs embedded in free-form text, or partially mask a known value for display
scan(): the same PII/secret detection as redact(), returned as structured { type, value, start, end } matches instead of masked in place
sanitize() pipeline: trim, normalize whitespace, redact PII, and escape HTML in one configurable call, composed from the functions above
XSS-safe HTML escaping: escape/unescape the five HTML special characters per OWASP's XSS Prevention Cheat Sheet, without a dedicated escaping library
CLI: npx textconvert redact <file> sanitizes a file (or stdin) from the command line, no JS required
Case conversion: camelCase, PascalCase, snake_case, kebab-case, slugify, capitalize, Title Case
Validation: email addresses, URLs, and phone numbers
Extraction: pull email addresses, URLs, @mentions, and #hashtags out of a block of text
Text analysis: word/letter/sentence/paragraph counting, reading time, readability scoring, palindrome checking, word frequency, etc.
Text utilities: truncate with word-boundary awareness
Language detection: English, French, Spanish, German, Italian, Portuguese, Dutch
Number to words: Converts numbers < 100 million to English words
Words to number: Parses English number-words back into a number, e.g. 'twelve thousand three hundred and forty-five' -> 12345
Ordinal suffixes: turns 21 into '21st'
Ordinal words: turns 21 into 'twenty-first'
Number formatting: adds thousands separators, e.g. 1234567.89 -> '1,234,567.89'
Number parsing: turns '1,234,567.89' back into 1234567.89
Generation: cryptographically secure random strings for IDs, tokens, or test fixtures
Grammar: pluralize English words for UI copy like "1 item" / "5 items"
Normalization: strip diacritics, collapse whitespace, and normalize line endings
Pure, dependency-free, and TypeScript-ready

Why Use textConvert?

PII Redaction Built In: Mask emails and phone numbers embedded in free-form text — sanitize logs and user content without reaching for a full NLP-based PII detector or a paid API.
Lightweight & Dependency-Free: No external dependencies, fast and easy to use.
Comprehensive Text Utilities: Covers case conversion, text analysis, language detection, and more.
TypeScript Support: Fully typed for safe and productive development.
Modern API: Designed for clarity, performance, and extensibility.
Actively Maintained: Open to contributions and new features.

📋 API Reference

Function	Description
`camelCase(text)`	Convert to camelCase
`pascalCase(text)`	Convert to PascalCase
`snakeCase(text)`	Convert to snake_case
`kebabCase(text)`	Convert to kebab-case
`slugify(text)`	Convert to a URL-safe slug
`capitalize(text)`	Capitalize only the first letter
`titleCase(text)`	Capitalize the first letter of every word
`clear(text)`	Remove punctuation from text
`count(text, countNumbers?)`	Count letters (optionally including numbers)
`countWords(text)`	Count words
`countSentences(text)`	Count sentences
`reverse(text)`	Reverse a string (grapheme-cluster aware)
`spread(text, clear?)`	Split a string into an array of characters
`truncate(text, maxLength, options?)`	Shorten text to a max length, with an ellipsis (grapheme-safe cut)
`maskText(text, options?)`	Partially mask a string for display
`redact(text, options?)`	Mask PII/secrets embedded in text
`scan(text, options?)`	Find PII/secrets embedded in text as structured matches
`getTextStats(text, wordsPerMinute?)`	Full text statistics (counts, averages, reading time, readability)
`isPalindrome(text)`	Check if text is a palindrome
`wordFrequency(text)`	Count how many times each word appears
`detectLanguage(text, minLength?, options?)`	Detect the language of a piece of text
`numbersToWords(number)`	Convert a number under 100 million to English words
`wordsToNumber(text)`	Parse English number-words back into a number
`ordinal(number)`	Get a number's ordinal suffix form (`21` -> `'21st'`)
`ordinalToWords(number)`	Get a number's ordinal word form (`21` -> `'twenty-first'`)
`formatNumber(number, options?)`	Add thousands separators to a number
`parseNumber(text)`	Parse a formatted number string back into a number
`randomString(length, options?)`	Generate a cryptographically secure random string
`pluralize(word, count?)`	Return the plural form of an English word
`removeDiacritics(text)`	Strip accents from accented characters
`normalizeWhitespace(text)`	Collapse whitespace runs into a single space
`normalizeLineEndings(text)`	Normalize CRLF/CR line endings to LF
`isEmail(text)`	Validate an email address
`isUrl(text)`	Validate a URL
`isPhoneNumber(text)`	Validate a phone number
`extractEmails(text)`	Extract all email addresses found in a block of text
`extractUrls(text)`	Extract all URLs found in a block of text
`extractMentions(text)`	Extract all @mentions found in a block of text
`extractHashtags(text)`	Extract all #hashtags found in a block of text
`escapeHtml(text)`	Escape the five HTML special characters
`unescapeHtml(text)`	Reverse `escapeHtml`'s escaping
`sanitize(text, options?)`	Trim, normalize, redact, and escape in one configurable pipeline

See docs/API.md for full parameter, return type, and edge-case details on every function, or browse the auto-generated API reference site.

Quick Examples

import { redact, camelCase, count, isEmail, isUrl, isPhoneNumber } from 'textconvert';

redact('Contact me at jordan@example.com or 555-123-4567');
// 'Contact me at jo**************** or 55**********'
camelCase('hello world'); // 'helloWorld'
count('Hello, world!'); // 10
isEmail('user@example.com'); // true
isUrl('https://example.com/path?query=123'); // true
isPhoneNumber('+1-202-555-0173'); // true

See docs/API.md for a usage example, parameters, and edge cases for every function.

Advanced Examples

// Detect language with options
import { detectLanguage, Language } from 'textconvert';
const result = detectLanguage('Hola mundo', 4, { maxCharsToAnalyze: 300 });
if (result.language === Language.Spanish) {
  console.log('Spanish detected!');
}

// Get detailed text statistics
const stats = convert.getTextStats('Hello world. This is a test.');
console.log(stats.wordCount, stats.readingTimeFormatted);

// Convert numbers to words
console.log(convert.numbersToWords(987654));
// "nine hundred eighty-seven thousand six hundred and fifty-four"