@cutticat/contacts

Library for detecting type, normalizing, and formatting contacts (email, phone).

Contents

• Overview
• Installation
• Quick start
• API
• Documentation
• Requirements

Overview

The library provides:

• Type detection — automatically recognizes email or phone from string content
• Validation — checks email and phone format
• Normalization — converts contacts to canonical form (E.164 for phones)
• Formatting — displays contacts in a user-friendly format

For an empty or whitespace-only string, detectContactType returns undefined; in that case normalizeContact and formatContact return the original string unchanged.

Installation

pnpm i @cutticat/contacts

Quick start

import {
  detectContactType,
  isValidContact,
  isValidEmail,
  isValidPhone,
  normalizeContact,
  formatContact,
  formatContactAsYouType,
} from "@cutticat/contacts"

// Type detection
detectContactType("user@example.com") // "email"
detectContactType("+79001234567") // "phone"
detectContactType("") // undefined

// Validation
isValidEmail("user@example.com") // true
isValidPhone("+79001234567") // true
isValidContact("invalid") // false

// Normalization (for storage)
normalizeContact("  User@Example.COM  ") // "user@example.com"
normalizeContact("8 (900) 123-45-67") // "+79001234567"
normalizeContact("") // ""

// Formatting (for display)
formatContact("89001234567") // "+7 900 123 45 67"
formatContact("  User @ Example . COM  ") // "user@example.com"

// As-you-type formatting (for input fields)
formatContactAsYouType("89001234567") // "7 900 123 45 67"

API

Functions

• detectContactType(contact) — detects contact type; returns undefined for empty strings
• isValidEmail(email) — checks email format (lenient validation: [^\s@]+@[^\s@]+)
• isValidPhone(phone, country?) — checks phone number (libphonenumber-js)
• isValidContact(contact, contactType?) — validates contact by type
• normalizeContact(contact, contactType?) — normalizes contact; returns original string when type is undefined
• formatContact(contact, type?) — formats contact for display
• formatContactAsYouType(contact, type?) — formats as you type (phones)
• normalizeEmail(email) — normalizes email
• normalizePhone(phone, country?) — normalizes phone to E.164
• formatEmail(email) — formats email
• formatPhone(phone, country?) — formats phone in international format
• formatPhoneAsYouType(phone, country?) — as-you-type phone formatting

Types

• ContactType — "email" | "phone"; exported for use in types and annotations

Documentation

Detailed documentation:

• Project structure
• Scripts
• Style guide
• Contributing

Full API documentation is available in JSDoc comments.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0