pragi-string/index.d.ts

A package to modify strings

interface PragiStringOptions {
    /**
     * Whether to trim whitespace from the input string
     */
    trim?: boolean;
    /**
     * Words to exclude from capitalization in titlecase
     */
    excludeWords?: string[];
    /**
     * Maximum length for truncation
     */
    truncate?: number;
    /**
     * Suffix to use when truncating text (defaults to "...")
     */
    suffix?: string;
}

declare class PragiString {
    /**
     * Truncates text at word boundaries
     * @param text - The input string to truncate
     * @param maxLength - Maximum length of the output string
     * @param suffix - Suffix to append to truncated text (defaults to "...")
     */
    static smartTruncate(text: string, maxLength: number, suffix?: string): string;

    /**
     * Internal helper to format text with common options
     */
    static formatText(text: string, transformFn: (text: string) => string, options?: PragiStringOptions): string;

    /**
     * Converts text to uppercase
     * @param text - The input string to convert
     * @param options - Optional configuration options
     * @throws {Error} If input is not a string
     */
    static uppercase(text: string, options?: PragiStringOptions): string;

    /**
     * Converts text to lowercase
     * @param text - The input string to convert
     * @param options - Optional configuration options
     * @throws {Error} If input is not a string
     */
    static lowercase(text: string, options?: PragiStringOptions): string;

    /**
     * Converts text to title case
     * @param text - The input string to convert
     * @param options - Optional configuration options
     * @throws {Error} If input is not a string
     */
    static titleCase(text: string, options?: PragiStringOptions): string;

    /**
     * Converts text to sentence case
     */
    static sentenceCase(text: string, options?: PragiStringOptions): string;

    /**
     * Converts text to camel case
     */
    static camelCase(text: string, options?: PragiStringOptions): string;

    /**
     * Converts text to snake case
     */
    static snakeCase(text: string, options?: PragiStringOptions): string;

    /**
     * Converts text to kebab case
     */
    static kebabCase(text: string, options?: PragiStringOptions): string;

    /**
     * Converts a number to its word representation
     * @param num - The number to convert to words
     * @returns The number spelled out in words
     * @example toWords(42) => "forty two"
     */
    static toWords(num: number): string;

    /**
     * Converts word numbers to their numeric representation
     * @param text - The text containing word numbers to convert
     * @throws {Error} If an unknown word is encountered
     * @example toNumbers("forty two") => 42
     */
    static toNumbers(text: string): number;

    /**
     * Converts a number to its ordinal representation
     * @param num - The number to convert
     * @throws {Error} If input is not a positive integer
     * @example toOrdinal(42) => "42nd"
     */
    static toOrdinal(num: number): string;

    /**
     * Converts a number to Roman numerals
     * @param num - The number to convert (must be positive)
     * @throws {Error} If input is not a positive number
     */
    static toRoman(num: number): string;

    /**
     * Converts Roman numerals to a number
     * @param roman - The Roman numeral string to convert
     */
    static fromRoman(roman: string): number;

    /**
     * Converts a number to a human-readable format with suffixes (K, M, B, T)
     * @param num - The number to humanize
     * @throws {Error} If input is not a number
     * @example humanizeNumber(1234) => "1.2K"
     */
    static humanizeNumber(num: number): string;

    /**
     * Converts seconds to a human-readable duration
     * @param seconds - The number of seconds to convert
     * @throws {Error} If input is negative or not a number
     * @example humanizeDuration(3665) => "1 hour, 1 minute, 5 seconds"
     */
    static humanizeDuration(seconds: number): string;

    /**
     * Converts seconds to digital time format (HH:MM:SS)
     * @param seconds - The number of seconds to convert
     * @throws {Error} If input is negative or not a number
     * @example toDigitalTime(3665) => "01:01:05"
     */
    static toDigitalTime(seconds: number): string;
}

export = PragiString;