@gipisistemas/ngx-core 1.0.1

package/utils/object.util.d.ts

@@ -0,0 +1,83 @@
+import { Nullable } from '../types/nullable.type';
+export declare class ObjectUtil {
+    /**
+     * Verifica se o valor fornecido é um objeto.
+     *
+     * @param inp O valor a ser verificado.
+     * @param empty Define se o objeto vazio será considerado válido. Se `true`, um objeto vazio será considerado um objeto válido.
+     * @returns `true` se o valor for um objeto (não nulo e não um array), caso contrário, `false`.
+     */
+    static isObject<T = unknown>(inp: T, empty?: boolean): boolean;
+    /**
+     * Verifica se um valor é considerado vazio.
+     *
+     * Um valor é considerado vazio se for:
+     *    -        `null` ou `undefined`
+     *    -        Uma string vazia `""`
+     *    -        Um número `NaN`
+     *    -        Um array vazio `[]`
+     *    -        Um objeto sem propriedades `{}`
+     *    -        Um valor de data inválido
+     *
+     * @param inp O valor a ser verificado.
+     * @returns `true` se o valor for vazio, caso contrário, `false`.
+     */
+    static isEmpty(inp: unknown): inp is null | undefined;
+    static isNewModel(inp: unknown): inp is null | undefined;
+    /**
+     * Mescla dois objetos ou dois valores (strings ou objetos). Caso ambos sejam objetos,
+     * eles serão combinados. Se forem strings, elas serão concatenadas. Se algum dos valores
+     * for `undefined`, o outro valor será retornado.
+     *
+     * @param obj1 O primeiro objeto ou valor.
+     * @param obj2 O segundo objeto ou valor.
+     * @returns O resultado da mesclagem ou o valor que não estiver (`undefined`, `null`...).
+     *
+     * @example
+     * merge({ name: 'John' }, { age: 30 }); // Retorna { name: 'John', age: 30 }.
+     * merge('Hello', 'World'); // Retorna 'Hello World'.
+     * merge(undefined, 'Fallback'); // Retorna 'Fallback'.
+     */
+    static merge<T1 = unknown, T2 = unknown>(obj1?: Nullable<T1>, obj2?: Nullable<T2>): Nullable<unknown>;
+    /**
+     * Verifica se um objeto possui uma propriedade específica.
+     *
+     * @param obj Objeto a ser verificado.
+     * @param property Nome da propriedade a ser verificada.
+     * @returns `true` se a propriedade existir no objeto, caso contrário, `false`.
+     *
+     * @example
+     * const user = { name: 'Alice', age: 25 };
+     * console.log(StorageUtil.hasPropertyInObj(user, 'name')); // true
+     * console.log(StorageUtil.hasPropertyInObj(user, 'email')); // false
+     */
+    static hasPropertyInObj<T = unknown>(obj: T, property: string): boolean;
+    /**
+     * Realiza uma clonagem profunda do objeto fornecido.
+     *
+     * @param obj - Objeto a ser clonado.
+     * @returns Uma cópia profunda do objeto ou `null` se o objeto for vazio.
+     *
+     * Utiliza `structuredClone`, garantindo uma clonagem eficiente e preservando
+     * estruturas complexas como Arrays, Maps e Sets.
+     */
+    static clone<T = unknown>(obj: T): T;
+    /**
+     * Compara dois valores verificando se são iguais em valor (deep equality).
+     *
+     * Faz uma comparação profunda entre os objetos, arrays, datas e expressões regulares,
+     * verificando se os conteúdos são equivalentes, não apenas a referência.
+     * Também trata o caso especial de NaN.
+     *
+     * @param obj1 - Primeiro objeto/valor a ser comparado.
+     * @param obj2 - Segundo objeto/valor a ser comparado.
+     * @returns `true` se os valores forem iguais em conteúdo; `false` caso contrário.
+     *
+     * @example
+     * equals({ a: 1, b: [2, 3] }, { a: 1, b: [2, 3] }); // true
+     * equals(new Date('2020-01-01'), new Date('2020-01-01')); // true
+     * equals(NaN, NaN); // true
+     * equals({ a: 1 }, { a: 2 }); // false
+     */
+    static equals(obj1: unknown, obj2: unknown): boolean;
+}

package/utils/phone.util.d.ts

@@ -0,0 +1,103 @@
+import * as libPhone from 'libphonenumber-js';
+export declare class PhoneUtil {
+    /**
+     * Remove todos os caracteres não numéricos de uma string.
+     *
+     * @param value - O valor de entrada contendo um número de telefone.
+     * @returns Apenas os dígitos do número.
+     *
+     * @example
+     * PhoneUtil.removeCharacters('(11) 91234-5678'); // "11912345678"
+     */
+    static removeCharacters(value: string): string;
+    /**
+     * Gera uma máscara baseada no número de telefone, substituindo os dígitos por zeros.
+     * Útil para criar placeholders no formato do número.
+     *
+     * @param phoneNumber - Número de telefone para gerar a máscara.
+     * @param country - Código do país (padrão: 'BR').
+     * @returns A máscara baseada na formatação nacional.
+     *
+     * @example
+     * PhoneUtil.maskLib('11912345678'); // "(11) 0 0000-0000"
+     */
+    static maskLib(phoneNumber: string, country?: libPhone.CountryCode): string;
+    /**
+     * Formata um número de telefone no padrão nacional do país informado.
+     *
+     * @param phoneNumber - O número de telefone.
+     * @param country - Código do país (padrão: 'BR').
+     * @returns O número formatado.
+     *
+     * @example
+     * PhoneUtil.formatLib('11912345678'); // "(11) 9 1234-5678"
+     */
+    static formatLib(phoneNumber: string, country?: libPhone.CountryCode): string;
+    /**
+     * Formata um número de telefone com base em uma máscara customizada.
+     *
+     * @param number - O número de telefone puro.
+     * @param mask - Máscara a ser aplicada (ex: '(00) 00000-0000').
+     * @returns Número formatado conforme a máscara.
+     *
+     * @example
+     * PhoneUtil.format('11912345678', '(00) 00000-0000'); // "(11) 91234-5678"
+     */
+    static format(number: string, mask?: string): string;
+    /**
+     * Retorna a máscara adequada para o número informado, baseada no seu comprimento e tipo.
+     *
+     * @param phone - Número de telefone puro.
+     * @returns Máscara correspondente ao tipo de número.
+     *
+     * @example
+     * PhoneUtil.mask('11912345678'); // "(11) 0 0000-0000"
+     * PhoneUtil.mask('08001234567'); // "0000 000 0000"
+     */
+    static mask(phone: string): string;
+    /**
+     * Verifica se o número de telefone é possível (conforme regras do país).
+     *
+     * @param phoneNumber - Número a ser verificado.
+     * @param country - Código do país (padrão: 'BR').
+     * @returns Verdadeiro se o número for possível.
+     *
+     * @example
+     * PhoneUtil.isPossible('11912345678'); // true
+     */
+    static isPossible(phoneNumber: string, country?: libPhone.CountryCode): boolean;
+    /**
+     * Verifica se o número de telefone é válido (real e formatado corretamente).
+     *
+     * @param phoneNumber - Número a ser validado.
+     * @param country - Código do país (padrão: 'BR').
+     * @returns Verdadeiro se for válido.
+     *
+     * @example
+     * PhoneUtil.isValid('11912345678'); // true
+     */
+    static isValid(phoneNumber: string, country?: libPhone.CountryCode): boolean;
+    /**
+     * Retorna o tipo do número (mobile, fixed line, etc.).
+     *
+     * @param phoneNumber - Número de telefone.
+     * @param country - Código do país (padrão: 'BR').
+     * @returns Tipo do número, ou null se não for possível determinar.
+     *
+     * @example
+     * PhoneUtil.getType('11912345678'); // "MOBILE"
+     */
+    static getType(phoneNumber: string, country?: libPhone.CountryCode): libPhone.NumberType | null;
+    /**
+     * Compara dois números para verificar se representam o mesmo telefone.
+     *
+     * @param phoneNumber1 - Primeiro número.
+     * @param phoneNumber2 - Segundo número.
+     * @param country - Código do país (padrão: 'BR').
+     * @returns Verdadeiro se forem iguais logicamente (mesmo número real).
+     *
+     * @example
+     * PhoneUtil.isEqual('(11) 91234-5678', '+55 11 91234-5678'); // true
+     */
+    static isEqual(phoneNumber1: string, phoneNumber2: string, country?: libPhone.CountryCode): boolean;
+}

package/utils/states.util.d.ts

@@ -0,0 +1,182 @@
+export declare const STATES_DATA: {
+    AC: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    AL: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    AP: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    AM: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    BA: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number[];
+        name: string;
+    };
+    CE: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    DF: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    ES: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    GO: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    MA: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    MG: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    MT: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    MS: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    PA: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    PB: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    PE: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    PI: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    PR: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    RJ: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    RN: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number[];
+        name: string;
+    };
+    RO: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    RS: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    RR: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    SC: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    SE: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    SP: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number;
+        name: string;
+    };
+    TO: {
+        code: string;
+        areaCodes: number[];
+        ieLength: number[];
+        name: string;
+    };
+};
+export type tUFState = keyof typeof STATES_DATA;
+export type tStateName = 'Acre' | 'Alagoas' | 'Amapá' | 'Amazonas' | 'Bahia' | 'Ceará' | 'Distrito Federal' | 'Espírito Santo' | 'Goiás' | 'Maranhão' | 'Minas Gerais' | 'Mato Grosso' | 'Mato Grosso do Sul' | 'Pará' | 'Paraíba' | 'Pernambuco' | 'Piauí' | 'Paraná' | 'Rio de Janeiro' | 'Rio Grande do Norte' | 'Rondônia' | 'Rio Grande do Sul' | 'Roraima' | 'Santa Catarina' | 'Sergipe' | 'São Paulo' | 'Tocantins';
+export declare const stateNamesMap: Record<tUFState, tStateName>;
+export declare class StateUtil {
+    /**
+     * Retorna o nome do estado brasileiro com base na sigla (UF).
+     *
+     * @param uf - Sigla do estado (por exemplo: 'SP', 'RJ', 'MG').
+     * @param full - Define se o retorno deve incluir o formato completo com a sigla (ex: '(SP) - São Paulo').
+     *               Caso `false` ou não informado, retorna apenas o nome (ex: 'São Paulo').
+     * @returns O nome do estado no formato simples ou completo, ou `uf` se a sigla for inválida.
+     *
+     * @example
+     * StateUtil.stateName('SP'); // 'São Paulo'
+     * StateUtil.stateName('SP', true); // '(SP) - São Paulo'
+     */
+    static stateName(uf: tUFState, full?: boolean): string;
+}

package/utils/storage.util.d.ts

@@ -0,0 +1,78 @@
+import { Nullable } from '../types/nullable.type';
+/** Classe utilitária para manipulação do `sessionStorage` e `localStorage`. */
+export declare class StorageUtil {
+    /**
+     * Armazena um item no `sessionStorage`.
+     *
+     * @param key Chave associada ao valor armazenado.
+     * @param value Valor a ser armazenado (qualquer tipo de dado).
+     *
+     * @example
+     * StorageUtil.setSessionItem('user', { name: 'Alice', age: 25 });
+     */
+    static setSessionItem<T = unknown>(key: string, value: T): void;
+    /**
+     * Obtém um item armazenado no `sessionStorage`.
+     *
+     * @param key Chave do item a ser recuperado.
+     * @returns O valor armazenado convertido para o tipo correspondente ou `null` caso não exista.
+     *
+     * @example
+     * const user = StorageUtil.getSessionItem<{ name: string; age: number }>('user');
+     * console.log(user); // { name: 'Alice', age: 25 } ou null se não existir.
+     */
+    static getSessionItem<T = unknown>(key: string): Nullable<T>;
+    /**
+     * Armazena um item no `localStorage`.
+     *
+     * @param key Chave associada ao valor armazenado.
+     * @param value Valor a ser armazenado (qualquer tipo de dado).
+     *
+     * @example
+     * StorageUtil.setLocalItem('theme', 'dark');
+     */
+    static setLocalItem<T = unknown>(key: string, value: T): void;
+    /**
+     * Obtém um item armazenado no `localStorage`.
+     *
+     * @param key Chave do item a ser recuperado.
+     * @returns O valor armazenado convertido para o tipo correspondente ou `null` caso não exista.
+     *
+     * @example
+     * const theme = StorageUtil.getLocalItem<string>('theme');
+     * console.log(theme); // 'dark' ou null se não existir.
+     */
+    static getLocalItem<T = unknown>(key: string): Nullable<T>;
+    /**
+     * Remove um item específico do `sessionStorage`.
+     *
+     * @param key Chave do item a ser removido.
+     *
+     * @example
+     * StorageUtil.removeSessionItem('user');
+     */
+    static removeSessionItem(key: string): void;
+    /**
+     * Remove um item específico do `localStorage`.
+     *
+     * @param key Chave do item a ser removido.
+     *
+     * @example
+     * StorageUtil.removeLocalItem('theme');
+     */
+    static removeLocalItem(key: string): void;
+    /**
+     * Limpa todos os dados armazenados no `sessionStorage`.
+     *
+     * @example
+     * StorageUtil.clearSession();
+     */
+    static clearSession(): void;
+    /**
+     * Limpa todos os dados armazenados no `localStorage`.
+     *
+     * @example
+     * StorageUtil.clearLocal();
+     */
+    static clearLocal(): void;
+}

package/utils/string.util.d.ts

@@ -0,0 +1,89 @@
+export declare class StringUtil {
+    /**
+     * Verifica se um valor é considerado vazio.
+     *
+     * Um valor é considerado vazio se for:
+     *    -        `null` ou `undefined`
+     *    -        Uma string vazia `""`
+     *    -        Um número `NaN`
+     *    -        Um array vazio `[]`
+     *    -        Um objeto sem propriedades `{}`
+     *    -        Um valor de data inválido
+     *
+     * @param inp O valor a ser verificado.
+     * @returns `true` se o valor for vazio, caso contrário, `false`.
+     */
+    static isEmpty(inp: unknown): inp is null | undefined;
+    /**
+     * Remove os acentos (diacríticos) de uma string.
+     * A função tenta usar a normalização Unicode Property Escapes para uma remoção mais eficiente de acentos.
+     * Caso o ambiente não suporte, utiliza a normalização NFD e remove os acentos de forma tradicional.
+     *
+     * @param inp A string da qual os acentos serão removidos.
+     * @returns A string sem os acentos.
+     *
+     * @example
+     * removeAccents('café'); // Retorna 'cafe'.
+     * removeAccents('ação'); // Retorna 'acao'.
+     */
+    static removeAccents(inp: string): string;
+    /**
+     * Trunca uma string para um tamanho máximo especificado e adiciona um sufixo (por padrão, '...') caso o limite seja ultrapassado.
+     *
+     * @param inp A string que será truncada.
+     * @param maxLength O tamanho máximo da string antes do truncamento. (padrão é 50)
+     * @param suffix O sufixo que será adicionado após o truncamento. (padrão é '...').
+     * @returns A string truncada com o sufixo, se necessário.
+     *
+     * @example
+     * truncateWithSuffix('Lorem ipsum dolor sit amet', 5); // Retorna 'Lorem...'.
+     * truncateWithSuffix('Short text', 20); // Retorna 'Short text' (não há truncamento).
+     */
+    static truncateWithSuffix(inp: string, maxLength?: number, suffix?: string): string;
+    /**
+     * Divide uma string em substrings de um tamanho máximo especificado.
+     * A função cria um array com as substrings resultantes da divisão da string original.
+     *
+     * @param inp A string a ser dividida.
+     * @param split O tamanho máximo de cada substring.
+     * @returns Um array com as substrings divididas.
+     *
+     * @example
+     * split('abcdefg', 3); // Retorna ['abc', 'def', 'g'].
+     * split('hello', 2); // Retorna ['he', 'll', 'o'].
+     */
+    static split(inp: string, split: number): string[];
+    /**
+     * A função capitaliza todas as palavras da string, exceto preposições e acrônimos.
+     * @param inp A string a ser capitalizada.
+     * @param lowerCaseWords Uma lista de preposições que devem ser mantidas em minúsculas.
+     * @param upperCaseWords Uma lista de acrônimos que devem ser mantidos em maiúsculas.
+     * @returns A string com as palavras capitalizadas.
+     * @example
+     * capitalize('lorem ipsum dolor sit amet'); // Retorna 'Lorem Ipsum Dolor Sit Amet'.
+     * capitalize('lorem ipsum cia dolor sit amet'); // Retorna 'Lorem Ipsum cia Dolor Sit Amet'.
+     * capitalize('lorem ipsum cia dolor sit amet', ['cia'], ['cia']); // Retorna 'Lorem Ipsum cia Dolor Sit Amet'.
+     */
+    static capitalize(inp: string, lowerCaseWords?: string[], upperCaseWords?: string[]): string;
+    /**
+     * Gera uma string composta por espaços Unicode repetidos, conforme a quantidade e tipo especificado.
+     *
+     * #### Tipos de espaço Unicode:
+     * - \u00A0 → Non-breaking space (como espaço normal, mas não quebra linha)
+     * - \u2002 → En space (meio espaço)
+     * - \u2003 → Em space (espaço largo) [padrão]
+     * - \u2009 → Thin space (espaço fino)
+     *
+     * @param quantity Quantidade de vezes que o caractere de espaço será repetido. Padrão: 1
+     * @param space Unicode do tipo de espaço. Padrão: '\u2003' (Em space)
+     * @returns Uma string com os espaços desejados.
+     *
+     * @example
+     * ```ts
+     * unicodeSpacer(); // '\u2003'
+     * unicodeSpacer(3); // '\\u2003\\u2003\\u2003'
+     * unicodeSpacer(2, '\u2009'); // '\\u2009\\u2009'
+     * ```
+     */
+    static spacer(quantity?: number, space?: '\u00A0' | '\u2002' | '\u2003' | '\u2009'): string;
+}

package/utils/uuid.util.d.ts

@@ -0,0 +1,33 @@
+import { GIPIUuid } from '../types/uuid.type';
+export declare class UUIDUtil {
+    /**
+     * Valida se o identificador (UUID) fornecido é válido.
+     *
+     * @param id O identificador (UUID) a ser validado.
+     * @returns Um valor booleano indicando se o identificador é válido:
+     * - Retorna `false` se o identificador for vazio, nulo ou inválido.
+     * - Retorna `true` se o identificador for um número positivo ou uma string não vazia.
+     *
+     * @example
+     * isValid('123e4567-e89b-12d3-a456-426614174000'); // true
+     * isValid(12345); // true
+     * isValid(''); // false
+     * isValid(null); // false
+     */
+    static isValid(id: GIPIUuid): boolean;
+    /**
+     * Verifica se um valor é considerado vazio.
+     *
+     * Um valor é considerado vazio se for:
+     *    -        `null` ou `undefined`
+     *    -        Uma string vazia `""`
+     *    -        Um número `NaN`
+     *    -        Um array vazio `[]`
+     *    -        Um objeto sem propriedades `{}`
+     *    -        Um valor de data inválido
+     *
+     * @param inp O valor a ser verificado.
+     * @returns `true` se o valor for vazio, caso contrário, `false`.
+     */
+    static isEmpty(inp: unknown): inp is null | undefined;
+}