utilitify-core 1.0.0

package/dist/string/index.d.cts

@@ -0,0 +1,471 @@
+/**
+ * Convert string to camelCase
+ *
+ * @param str - String to convert
+ * @returns camelCase string
+ *
+ * @example
+ * ```typescript
+ * toCamelCase('hello world'); // 'helloWorld'
+ * toCamelCase('hello-world'); // 'helloWorld'
+ * toCamelCase('HelloWorld');  // 'helloWorld'
+ * ```
+ */
+declare function toCamelCase(str: string): string;
+/**
+ * Convert string to PascalCase
+ *
+ * @param str - String to convert
+ * @returns PascalCase string
+ *
+ * @example
+ * ```typescript
+ * toPascalCase('hello world'); // 'HelloWorld'
+ * toPascalCase('hello-world'); // 'HelloWorld'
+ * ```
+ */
+declare function toPascalCase(str: string): string;
+/**
+ * Convert string to snake_case
+ *
+ * @param str - String to convert
+ * @returns snake_case string
+ *
+ * @example
+ * ```typescript
+ * toSnakeCase('helloWorld');  // 'hello_world'
+ * toSnakeCase('Hello World'); // 'hello_world'
+ * ```
+ */
+declare function toSnakeCase(str: string): string;
+/**
+ * Convert string to kebab-case
+ *
+ * @param str - String to convert
+ * @returns kebab-case string
+ *
+ * @example
+ * ```typescript
+ * toKebabCase('helloWorld');  // 'hello-world'
+ * toKebabCase('Hello World'); // 'hello-world'
+ * ```
+ */
+declare function toKebabCase(str: string): string;
+/**
+ * Convert string to Title Case
+ *
+ * @param str - String to convert
+ * @returns Title Case string
+ *
+ * @example
+ * ```typescript
+ * toTitleCase('hello world');     // 'Hello World'
+ * toTitleCase('the quick brown'); // 'The Quick Brown'
+ * ```
+ */
+declare function toTitleCase(str: string): string;
+/**
+ * Convert string to CONSTANT_CASE
+ *
+ * @param str - String to convert
+ * @returns CONSTANT_CASE string
+ *
+ * @example
+ * ```typescript
+ * toConstantCase('helloWorld');  // 'HELLO_WORLD'
+ * toConstantCase('Hello World'); // 'HELLO_WORLD'
+ * ```
+ */
+declare function toConstantCase(str: string): string;
+/**
+ * Convert string to Sentence case
+ *
+ * @param str - String to convert
+ * @returns Sentence case string
+ *
+ * @example
+ * ```typescript
+ * toSentenceCase('hello World');  // 'Hello world'
+ * toSentenceCase('HELLO WORLD');  // 'Hello world'
+ * ```
+ */
+declare function toSentenceCase(str: string): string;
+/**
+ * Convert string to dot.case
+ *
+ * @param str - String to convert
+ * @returns dot.case string
+ */
+declare function toDotCase(str: string): string;
+/**
+ * Capitalize first letter
+ *
+ * @param str - String to capitalize
+ * @returns Capitalized string
+ */
+declare function capitalize(str: string): string;
+/**
+ * Uncapitalize first letter
+ *
+ * @param str - String to uncapitalize
+ * @returns Uncapitalized string
+ */
+declare function uncapitalize(str: string): string;
+/**
+ * Swap case of each character
+ *
+ * @param str - String to swap
+ * @returns Swapped case string
+ */
+declare function swapCase(str: string): string;
+
+/**
+ * Slug generation options
+ */
+interface SlugOptions {
+    /** Convert to lowercase (default: true) */
+    lowercase?: boolean;
+    /** Separator character (default: '-') */
+    separator?: string;
+    /** Maximum length (default: unlimited) */
+    maxLength?: number;
+    /** Transliterate non-ASCII characters (default: true) */
+    transliterate?: boolean;
+    /** Remove stop words (default: false) */
+    removeStopWords?: boolean;
+}
+/**
+ * Convert string to SEO-friendly slug
+ *
+ * @param str - String to convert
+ * @param options - Slug options
+ * @returns SEO-friendly slug
+ *
+ * @example
+ * ```typescript
+ * toSlug('Hello World!');           // 'hello-world'
+ * toSlug('Café & Restaurant');      // 'cafe-and-restaurant'
+ * toSlug('Hello World', { separator: '_' }); // 'hello_world'
+ * ```
+ */
+declare function toSlug(str: string, options?: SlugOptions): string;
+/**
+ * Transliterate non-ASCII characters to ASCII
+ *
+ * @param str - String to transliterate
+ * @returns Transliterated string
+ */
+declare function transliterate(str: string): string;
+/**
+ * Generate URL-safe slug from string
+ *
+ * @param str - String to slugify
+ * @returns URL-safe slug
+ */
+declare function slugify(str: string): string;
+/**
+ * Generate unique slug by appending number if needed
+ *
+ * @param str - Base string
+ * @param existingSlugs - Set of existing slugs
+ * @param options - Slug options
+ * @returns Unique slug
+ */
+declare function uniqueSlug(str: string, existingSlugs: Set<string> | string[], options?: SlugOptions): string;
+/**
+ * Check if string is a valid slug
+ *
+ * @param str - String to check
+ * @returns true if valid slug
+ */
+declare function isValidSlug(str: string): boolean;
+
+/**
+ * Mask options
+ */
+interface MaskOptions {
+    /** Mask character (default: '*') */
+    maskChar?: string;
+    /** Number of visible chars at start (default: varies by type) */
+    visibleStart?: number;
+    /** Number of visible chars at end (default: varies by type) */
+    visibleEnd?: number;
+    /** Minimum string length to mask (default: 4) */
+    minLength?: number;
+}
+/**
+ * Mask an email address
+ *
+ * @param email - Email to mask
+ * @param options - Mask options
+ * @returns Masked email
+ *
+ * @example
+ * ```typescript
+ * maskEmail('john.doe@gmail.com');  // 'j***@gmail.com'
+ * maskEmail('test@example.com');    // 't***@example.com'
+ * ```
+ */
+declare function maskEmail(email: string, options?: MaskOptions): string;
+/**
+ * Mask a phone number
+ *
+ * @param phone - Phone to mask
+ * @param options - Mask options
+ * @returns Masked phone
+ *
+ * @example
+ * ```typescript
+ * maskPhone('+1 555-123-4567');  // '+1 *** *** 4567'
+ * maskPhone('03001234567');       // '030*****67'
+ * ```
+ */
+declare function maskPhone(phone: string, options?: MaskOptions): string;
+/**
+ * Mask a credit card number
+ *
+ * @param card - Card number to mask
+ * @param options - Mask options
+ * @returns Masked card number
+ *
+ * @example
+ * ```typescript
+ * maskCreditCard('4111 1111 1111 1111');  // '**** **** **** 1111'
+ * maskCreditCard('4111111111111111');     // '************1111'
+ * ```
+ */
+declare function maskCreditCard(card: string, options?: MaskOptions): string;
+/**
+ * Mask a generic string
+ *
+ * @param str - String to mask
+ * @param options - Mask options
+ * @returns Masked string
+ *
+ * @example
+ * ```typescript
+ * maskString('password123', { visibleStart: 2, visibleEnd: 2 });  // 'pa*******23'
+ * maskString('secret', { visibleEnd: 3 });  // '***ret'
+ * ```
+ */
+declare function maskString(str: string, options?: MaskOptions): string;
+/**
+ * Mask IP address
+ *
+ * @param ip - IP address to mask
+ * @returns Masked IP
+ *
+ * @example
+ * ```typescript
+ * maskIP('192.168.1.100');  // '192.168.***.***'
+ * ```
+ */
+declare function maskIP(ip: string): string;
+/**
+ * Mask name (for privacy)
+ *
+ * @param name - Name to mask
+ * @returns Masked name
+ *
+ * @example
+ * ```typescript
+ * maskName('John Doe');  // 'J*** D**'
+ * ```
+ */
+declare function maskName(name: string): string;
+
+/**
+ * Password generation options
+ */
+interface PasswordOptions {
+    /** Password length (default: 16) */
+    length?: number;
+    /** Include uppercase letters (default: true) */
+    uppercase?: boolean;
+    /** Include lowercase letters (default: true) */
+    lowercase?: boolean;
+    /** Include numbers (default: true) */
+    numbers?: boolean;
+    /** Include symbols (default: true) */
+    symbols?: boolean;
+    /** Exclude ambiguous characters like 0, O, l, 1 (default: false) */
+    excludeAmbiguous?: boolean;
+    /** Custom characters to include */
+    customChars?: string;
+    /** Minimum number of each character type */
+    minOfEachType?: number;
+}
+/**
+ * Generate a random password
+ *
+ * @param options - Password options
+ * @returns Generated password
+ *
+ * @example
+ * ```typescript
+ * generatePassword(); // 'Xy7@mK9#pL2$nR4!'
+ * generatePassword({ length: 8, symbols: false }); // 'xY7mK9pL'
+ * ```
+ */
+declare function generatePassword(options?: PasswordOptions): string;
+/**
+ * Generate a random string
+ *
+ * @param length - Length of string
+ * @param charset - Character set to use
+ * @returns Random string
+ *
+ * @example
+ * ```typescript
+ * generateRandomString(10);                    // 'xK7mP9nL2s'
+ * generateRandomString(6, 'abc123');           // 'a1b2c3'
+ * ```
+ */
+declare function generateRandomString(length?: number, charset?: string): string;
+/**
+ * Generate a numeric OTP (One-Time Password)
+ *
+ * @param length - Length of OTP (default: 6)
+ * @returns OTP string
+ *
+ * @example
+ * ```typescript
+ * generateOTP();     // '482957'
+ * generateOTP(4);    // '7382'
+ * ```
+ */
+declare function generateOTP(length?: number): string;
+/**
+ * Generate a memorable passphrase
+ *
+ * @param wordCount - Number of words
+ * @param separator - Word separator
+ * @returns Passphrase
+ *
+ * @example
+ * ```typescript
+ * generatePassphrase(4); // 'correct-horse-battery-staple'
+ * ```
+ */
+declare function generatePassphrase(wordCount?: number, separator?: string): string;
+/**
+ * Generate a hex string
+ *
+ * @param length - Length in bytes (output will be 2x this)
+ * @returns Hex string
+ */
+declare function generateHexString(length?: number): string;
+/**
+ * Generate a base64 string
+ *
+ * @param length - Approximate length
+ * @returns Base64 string
+ */
+declare function generateBase64String(length?: number): string;
+/**
+ * Generate URL-safe random string
+ *
+ * @param length - Length of string
+ * @returns URL-safe random string
+ */
+declare function generateUrlSafeString(length?: number): string;
+
+/**
+ * Truncation options
+ */
+interface TruncateOptions {
+    /** Suffix to append (default: '...') */
+    suffix?: string;
+    /** Preserve word boundaries (default: true) */
+    preserveWords?: boolean;
+    /** Where to truncate: 'end', 'middle', 'start' (default: 'end') */
+    position?: 'end' | 'middle' | 'start';
+    /** Use grapheme-aware truncation for proper emoji handling (default: false) */
+    graphemeAware?: boolean;
+}
+/**
+ * Truncate a string to specified length
+ *
+ * @param str - String to truncate
+ * @param length - Maximum length (including suffix)
+ * @param options - Truncation options
+ * @returns Truncated string
+ *
+ * @example
+ * ```typescript
+ * truncate('Hello World', 8);           // 'Hello...'
+ * truncate('Hello World', 8, { preserveWords: false }); // 'Hello...'
+ * truncate('Hello World', 8, { suffix: '…' }); // 'Hello W…'
+ * ```
+ */
+declare function truncate(str: string, length: number, options?: TruncateOptions): string;
+/**
+ * Truncate by word count
+ *
+ * @param str - String to truncate
+ * @param wordCount - Maximum number of words
+ * @param suffix - Suffix to append (default: '...')
+ * @returns Truncated string
+ *
+ * @example
+ * ```typescript
+ * truncateWords('The quick brown fox jumps', 3); // 'The quick brown...'
+ * ```
+ */
+declare function truncateWords(str: string, wordCount: number, suffix?: string): string;
+/**
+ * Truncate by sentence count
+ *
+ * @param str - String to truncate
+ * @param sentenceCount - Maximum number of sentences
+ * @param suffix - Suffix to append (default: '')
+ * @returns Truncated string
+ *
+ * @example
+ * ```typescript
+ * truncateSentences('Hello. World. Test.', 2); // 'Hello. World.'
+ * ```
+ */
+declare function truncateSentences(str: string, sentenceCount: number, suffix?: string): string;
+/**
+ * Truncate from middle, keeping file extension
+ * Useful for file names
+ *
+ * @param filename - Filename to truncate
+ * @param length - Maximum length
+ * @param separator - Separator to use (default: '...')
+ * @returns Truncated filename
+ *
+ * @example
+ * ```typescript
+ * truncateFilename('very_long_filename.pdf', 15); // 'very_l...me.pdf'
+ * ```
+ */
+declare function truncateFilename(filename: string, length: number, separator?: string): string;
+/**
+ * Ellipsis a string (alias for truncate with default options)
+ *
+ * @param str - String to ellipsis
+ * @param length - Maximum length
+ * @returns Ellipsized string
+ */
+declare function ellipsis(str: string, length: number): string;
+/**
+ * Smart truncate for HTML content (strips tags first)
+ *
+ * @param html - HTML string to truncate
+ * @param length - Maximum length
+ * @param suffix - Suffix to append
+ * @returns Truncated text (no HTML)
+ */
+declare function truncateHtml(html: string, length: number, suffix?: string): string;
+/**
+ * Check if string needs truncation
+ *
+ * @param str - String to check
+ * @param length - Maximum length
+ * @returns true if string exceeds length
+ */
+declare function needsTruncation(str: string, length: number): boolean;
+
+export { type MaskOptions, type PasswordOptions, type SlugOptions, type TruncateOptions, capitalize, ellipsis, generateBase64String, generateHexString, generateOTP, generatePassphrase, generatePassword, generateRandomString, generateUrlSafeString, isValidSlug, maskCreditCard, maskEmail, maskIP, maskName, maskPhone, maskString, needsTruncation, slugify, swapCase, toCamelCase, toConstantCase, toDotCase, toKebabCase, toPascalCase, toSentenceCase, toSlug, toSnakeCase, toTitleCase, transliterate, truncate, truncateFilename, truncateHtml, truncateSentences, truncateWords, uncapitalize, uniqueSlug };