@heliomarpm/helpers
Version:
A library with many useful features
208 lines (207 loc) • 8.44 kB
TypeScript
export declare const Format: {
/**
* Formatações em português brasileiro.
*/
ptBr: {
cnpj: (value: string, fallback?: string) => string;
cpf: (value: string, fallback?: string) => string;
cep: (value: string, fallback?: string) => string;
/**
* Formata um número de telefone com DDD.
* Se o valor informado tiver entre 8 e 11 dígitos, ele
* será formatado com DDD.
* Caso o valor tenha 8 ou 9 dígitos, ele usará o DDD
* informado como parâmetro.
* @param {string} value O valor a ser formatado.
* @param {string} [defaultAreaCode=''] DDD padrão a ser usado.
* @param {boolean} [suppressError=false] Se verdadeiro, retorna o valor sem formatação em vez de lançar um erro.
* @returns {string} O valor formatado.
* @throws {Error} Se o valor informado tiver menos de 8 ou mais de 11 dígitos.
*/
telefone: (value: string, defaultAreaCode?: string, fallback?: string) => string;
/**
* Converte um valor em uma string escrita por extenso.
*
* @param value O valor a ser convertido.
* @returns Uma string com o valor escrito por extenso.
*
* @example
* ```js
* Format.valorPorExtenso(1000); // Output: "mil"
* Format.valorPorExtenso(1000000); // Output: "um milhão"
* Format.valorPorExtenso(1000000000); // Output: "um bilhão"
* Format.valorPorExtenso(1000000001); // Output: "um bilhão e um"
* Format.valorPorExtenso(2_000_000_000_000_000); // Output: "dois quatrilhões"
* ```
*/
valorPorExtenso: (value: number) => string;
};
/**
* Formats a Date object into a string according to the specified format.
* Supported formats are:
* - 'a': 'am' or 'pm' in lowercase
* - 'A': 'AM' or 'PM' in uppercase
* - 'hh': two-digit hours in 12h format (01-12)
* - 'h': hours in 12h format (1-12)
* - 'HH': two-digit hours in 24h format (00-23)
* - 'H': hours in 24h format (0-23)
* - 'MM': two-digit minutes (00-59)
* - 'ss': two-digit seconds (00-59)
* - 'SSS': three-digit milliseconds (000-999)
* - 'yyyy': four-digit year (2024)
* - 'yy': two-digit year (24)
* - 'mmmm': full month name (January, February, ...)
* - 'mmm': full month name abbreviated month (Jan, Feb, ...)
* - 'mm': two-digit month (01-12)
* - 'dddd': full weekday name (Sun, Mon, ...)
* - 'ddd': abbreviated weekday name (Sun, Mon, ...)
* - 'dd': two-digit day (01-31)
*
* @param {string|Date} date - The date to format.
* @param {string} format - The desired format for the output string.
* @param {string} locale - The locale to use.
* @returns {string} The date formatted as a string.
*
* @example
* ```js
* Format.date('2025-03-02', 'dddd, dd mmmm yyyy', 'en-US'); // Output: 'Sunday, 02 March 2025'
* ```
*
* @see https://www.w3schools.com/jsref/jsref_tolocalestring.asp
*/
date: (date: Date | string, format: string, locale?: Intl.LocalesArgument) => string;
/**
* Formats a number as currency.
* @param value The number to format.
* @param options Options for formatting. These include the locale and currency.
* @returns The formatted string.
*
* @example
* ```js
* Format.currency(123456.78); // 'R$ 123.456,78'Format.currency(1234.56);
* // Output: R$ 1.234,56
* ```
*
* @see https://www.w3schools.com/jsref/jsref_tolocalestring.asp
*/
currency: (value: number, options?: {
locale: Intl.LocalesArgument;
currency: string;
}) => string;
/**
* Formats a number according to the given locale.
* @param value The number to format.
* @param locale The locale to use.
* @returns The formatted string.
*
* @example
* ```js
* Format.number(123456.78); // '123.456,78'Format.number(1234.56);
* // Output: 1.234,56
* ```
*
* @see https://www.w3schools.com/jsref/jsref_tolocalestring.asp
*/
number: (value: number, locale?: Intl.LocalesArgument) => string;
/**
* Abbreviates a number by adding a suffix based on its magnitude.
*
* This function takes a number and returns a string with the number abbreviated
* using metric suffixes (e.g., K for thousand, M for million).
*
* @param value - The number to abbreviate.
* @param options - Options for abbreviation, including:
* - `fractionDigits`: Number of decimal places to include in the abbreviated value.
* - `removeEndZero`: Whether to remove trailing zeros after the decimal point.
* @returns A string representing the abbreviated number with a suffix.
*
* @example
* ```typescript
* abbreviateNumber(1500); // '1.50K'
* abbreviateNumber(2000000); // '2.00M'
* abbreviateNumber(123_456_789); // '123.46M'
* abbreviateNumber(1e33); // '1.00D'
* ```
*/
abbreviateNumber: (value: number, { fractionDigits, removeEndZero }?: {
fractionDigits?: number | undefined;
removeEndZero?: boolean | undefined;
}) => string;
/**
* Removes all non-numeric characters from a string.
*
* @param {string} value The string to remove non-numeric characters from.
* @returns {string} The resulting string with only numeric characters.
*
* @example
* ```js
* onlyNumbers('123abc'); // '123'
* onlyNumbers('abc'); // ''
* ```
*/
onlyNumbers: (value: string) => string;
/**
* Pads a number with leading zeros to match the number of digits in a given maximum value.
*
* @param {number} value The number to be padded with leading zeros.
* @param {number} refValue The reference value for determining the maximum length for adding leading zeros.
*
* @returns {string} the input number padded with leading zeros to match the number of digits in the maximum value.
*
* @example
* ```js
* Format.padZerosByRef(2, 90); // '02'
* Format.padZerosByRef(12, 110); // '012'
* ```
*/
padZerosByRef(value: number, refValue: number): string;
/**
* Capitalizes the first letter of the full name
* while maintaining lowercase for specified conjunctions.
*
* @param {string} name - The full name string to format.
* @returns {string} The formatted name in title case.
*
* @example
* ```ts
* titleCase('john doe de souza'); // 'John Doe de Souza'
* titleCase('maria da silva'); // 'Maria da Silva'
* ```
*/
titleCase(name: string): string;
/**
* Masks a substring of a string with a specified character.
*
* @param {string} value - The original string to mask.
* @param {string} [maskChar='*''] - The character to use for masking.
* @param {number} [startIndex=0] - The starting index of the substring to mask (inclusive).
* @param {number | null} [finalIndex=null] - The ending index of the substring to mask (exclusive). If null, masks until the end of the string.
* @returns {string} The masked string.
*
* @example
* ```js
* maskIt('1234567890', '*', 2, 5); // '12*****90'
* maskIt('1234567890', '#', 3); // '123########'
* ```
* @throws {Error} Invalid start or final index.
* @throws {Error} maskChar must be a single character
*/
maskIt(value: string, maskChar?: string, startIndex?: number, finalIndex?: number | null): string;
/**
* Masks a part of a string with a specified character.
*
* @param {string} text - The original string to mask.
* @param {string} [maskChar='*'] - The character to use for masking.
* @param {number} [visibleChars=1] - The number of visible characters in the masked part.
* @returns {string} The masked string.
*
* @example
* ```js
* maskItParts('Heliomar P. Marques', '*', 1); // 'H******* P. M******'
* maskItParts('+55 (11) 91888-0000', '#', 1); // '+5# (1#) 9####-0###'
* maskItParts('123.444.555-67', '_', 2); // '12_.44_.55_-67'
* ```
* @throws {Error} maskChar must be a single character
*/
maskItParts(text: string, maskChar?: string, visibleChars?: number): string;
};