normalize-string

Universal String Normalization & Sanitization for Security-Hardened Applications

⚠️ WARNING — READ FIRST ⚠️

This library provides robust, composable, and battle-tested normalization helpers for user input.

Normalization is NOT validation.
Normalization is NOT output escaping.

This library is designed to prepare untrusted input for validation, storage, and later context-specific output encoding (like HTML escaping, SQL parameterization, etc.).

Use this library before your validation layer to clean and standardize user input.
It removes hidden, obfuscated, dangerous characters — but does not validate format correctness.

What does it do?

• Strips control & zero-width characters
• Normalizes Unicode (prevents homoglyph attacks)
• Optionally forces ASCII-only output
• Optional emoji removal
• Optional whitespace handling
• Optional bidirectional character removal
• Enforces safe length limits
• Preserves user intent unless dangerous
• Provides specialized helpers for common types like email, username, slug, URL, phone, search query, filename, comment

Options Interface

export interface NormalizeInputOptions {
  trim?: boolean; // Remove leading/trailing whitespace (default: true)
  removeControlChars?: boolean; // Remove invisible control characters (default: true)
  removeZeroWidth?: boolean; // Remove zero-width characters (default: true)
  normalizeUnicode?: "NFC" | "NFD" | "NFKC" | "NFKD" | false; // Unicode normalization form (default: "NFC")
  toLowerCase?: boolean; // Convert to lowercase (default: false)
  asciiOnly?: boolean; // Remove non-ASCII characters (default: false)
  removeEmojis?: boolean; // Remove emojis (default: false)
  removeWhitespace?: boolean; // Remove all whitespaces (default: false)
  collapseWhitespace?: boolean; // Collapse multiple whitespaces to a single space (default: false)
  removeWhitespace?: boolean; // Remove all whitespace (default: false)
  removeDirectionOverrides?: boolean; // Remove bidirectional override characters (default: false)
  preserveNewlines?: boolean; // Keep \n and \r while removing other control characters (default: false)
  maxLength?: number | null; // Truncate to max length if specified (default: null)
}

Usage Examples

import {
  normalizeEmail,
  normalizeUsername,
  normalizeSlug,
  normalizeSearchQuery,
  normalizePhone,
  normalizeURL,
  normalizeFilename,
  normalizeComment,
} from "@valentech/normalize-string";

normalizeEmail

normalizeEmail("   EXAMPLE@ＧＭＡＩＬ.com​  ");
// → "[email protected]"

normalizeUsername

normalizeUsername("   𝗐𝗲𝗬
𝗲𝗬  ")
// → "𝗐𝗲𝗬𝗲𝗬"

normalizeSlug

normalizeSlug("Best   Offer 💣 2025!");
// → "best-offer-2025"

normalizeSearchQuery

normalizeSearchQuery(" Best   🦡 Price EVER ");
// → "best 🦡 price ever"

normalizePhone

normalizePhone("+49 (0) 123 / 456-7890", "DE");
// → "+491234567890"

normalizeURL

normalizeURL("   https://example.com/ path  ‮ ");
// → "https://example.com/path"

normalizeFilename

normalizeFilename("../../../My Résumé💾pdf");
// → "My_Resume.pdf"

normalizeComment

normalizeComment("Great   product!​‌\nHighly recommended.");
// → "Great product! Highly recommended."

Install

npm install @valentech/normalize-string

yarn add @valentech/normalize-string

Final Note

Always combine normalization → validation → context-escaping.

This library cleans input.
It does not validate correctness.
It does not prevent XSS or SQLi unless paired with proper output escaping.

→ Normalize to make input sane.
→ Validate to ensure input shape.
→ Escape to ensure output safety.

License

MIT