jsegd
Version:
Utilitário de ferramentas para desenvolvimento
307 lines (300 loc) • 10.9 kB
TypeScript
/**
* Contrato de cache genérico com suporte a TTL por entrada.
*/
interface ICache {
/**
* Retorna o valor armazenado para a chave informada, ou `null` se não encontrado ou expirado.
* @param key Chave de identificação da entrada
* @returns Valor armazenado ou `null`
*/
get<T>(key: string): Promise<T | null>;
/**
* Armazena um valor no cache sob a chave informada.
* @param key Chave de identificação da entrada
* @param data Valor a ser armazenado
*/
set<T>(key: string, data: T): Promise<void>;
/**
* Remove a entrada associada à chave informada.
* @param key Chave de identificação da entrada a remover
*/
remove(key: string): Promise<void>;
/**
* Remove todas as entradas do cache.
*/
clear(): Promise<void>;
/**
* Remove as entradas expiradas e retorna a quantidade removida.
* @returns Número de entradas removidas
*/
purgeExpired(): Promise<number>;
}
/**
* Cache com persistência em IndexedDB e TTL configurável por entrada.
* Use {@link LocalCache.getInstance} para obter ou criar uma instância por `storeName`.
* @hideconstructor
*/
declare class LocalCache implements ICache {
private readonly storeName;
private readonly cacheExpirationMs;
private static readonly instances;
private dbPromise;
private constructor();
/**
* Retorna a instância de LocalCache para o `storeName` informado, criando-a se necessário.
* @param storeName Nome do object store no IndexedDB (identificador único do cache)
* @param cacheExpirationMs Tempo de expiração em milissegundos
*/
static getInstance(storeName: string, cacheExpirationMs: number): LocalCache;
private promisifyRequest;
private openDatabase;
/**
* Retorna o valor em cache para a chave informada, ou `null` se não encontrado ou expirado.
*/
get<T = any>(key: string): Promise<T | null>;
/**
* Armazena um valor no cache sob a chave informada.
*/
set<T = any>(key: string, data: T): Promise<void>;
/**
* Remove a entrada em cache para a chave informada.
*/
remove(key: string): Promise<void>;
/**
* Remove todas as entradas do cache.
*/
clear(): Promise<void>;
/**
* Remove todas as entradas expiradas e retorna a quantidade removida.
* @returns Número de entradas removidas
*/
purgeExpired(): Promise<number>;
}
type EventMap = Record<string, any[]>;
type EventCallback<T extends any[]> = (...args: T) => void;
/**
* Barramento de eventos tipado com padrão singleton.
* Permite inscrição, emissão e cancelamento de eventos fortemente tipados.
* @hideconstructor
*/
declare class EventBus<TEvents extends EventMap = EventMap> {
private static instance;
private events;
private constructor();
/**
* Retorna a instância singleton de EventBus.
* Pode ser tipado com um mapa de nomes de eventos e seus argumentos.
* @example
* ```typescript
* type AppEvents = { 'user:login': [userId: string]; 'modal:close': [] }
* const bus = EventBus.getInstance<AppEvents>()
* bus.on('user:login', (userId) => console.log(userId))
* bus.emit('user:login', '42')
* ```
*/
static getInstance<T extends EventMap = EventMap>(): EventBus<T>;
/**
* Inscreve um callback em um evento. Retorna uma função para cancelar a inscrição.
* @example EventBus.getInstance().on('my-event', handler)
*/
on<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): () => void;
/**
* Inscreve um callback que dispara uma única vez e cancela a inscrição automaticamente após a primeira entrega.
* @example EventBus.getInstance().once('init', () => setup())
*/
once<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): () => void;
/**
* Cancela a inscrição de um callback específico em um evento.
* @example EventBus.getInstance().off('my-event', handler)
*/
off<K extends keyof TEvents>(event: K, callback: EventCallback<TEvents[K]>): void;
/**
* Emite um evento, invocando todos os callbacks inscritos com os argumentos fornecidos.
* Erros lançados por callbacks individuais são capturados e registrados sem interromper os demais.
* @example EventBus.getInstance().emit('my-event', arg1, arg2)
*/
emit<K extends keyof TEvents>(event: K, ...args: TEvents[K]): void;
/**
* Remove todos os callbacks de um evento específico, ou remove todos os eventos se nenhum argumento for fornecido.
* @example
* EventBus.getInstance().clear('my-event') // remove um evento
* EventBus.getInstance().clear() // remove todos os eventos
*/
clear(event?: keyof TEvents): void;
}
declare enum DeadlineUnit {
/** Segundo(s). */
Second = 0,
/** Minuto(s). */
Minute = 1,
/** Hora(s). */
Hour = 2,
/** Dia(s). */
Day = 3,
/** Semana(s). */
Week = 4,
/** Mês(es). */
Month = 5,
/** Bimestre(s). */
Bimonth = 6,
/** Trimestre(s). */
Quarter = 7,
/** Semestre(s). */
Semester = 8,
/** Ano(s). */
Year = 9
}
declare enum Currency {
/** Real brasileiro (BRL). */
BRL = 0,
/** Dólar americano (USD). */
USD = 1,
/** Euro (EUR). */
EUR = 2,
/** Iene japonês (JPY). */
JPY = 3,
/** Libra esterlina (GBP). */
GBP = 4,
/** Yuan chinês (CNY). */
CNY = 5
}
/**
* Formata valores monetários, numéricos, de prazo e datas por extenso em português brasileiro.
* Todos os métodos são síncronos e delegam ao módulo WASM (`pkg/jsegd`).
* @hideconstructor
*/
declare abstract class WrittenOut {
/**
* Formata prazo por extenso em português.
* @param value Quantidade da unidade
* @param unit Unidade de tempo (DeadlineUnit)
* @example
* ```typescript
* WrittenOut.formatDeadline(2, DeadlineUnit.Hour) // "duas horas"
* ```
*/
static formatDeadline(value: number, unit: DeadlineUnit): string;
/**
* Formata número por extenso em reais.
* @param value Valor numérico
* @example
* ```typescript
* WrittenOut.formatNumber(1234.56) // "um mil e duzentos e trinta e quatro reais e cinquenta e seis centavos"
* ```
*/
static formatNumber(value: number): string;
/**
* Formata valor monetário por extenso.
* @param value Valor numérico
* @param currency Moeda (Currency enum)
* @example
* ```typescript
* WrittenOut.formatCurrency(1.01, Currency.GBP) // "uma libra e um penny"
* ```
*/
static formatCurrency(value: number, currency: Currency): string;
/**
* Formata data por extenso em português a partir de um objeto Date.
* @param date Objeto Date
* @example
* ```typescript
* WrittenOut.formatDate(new Date("2025-01-25")) // "sábado, vinte e cinco de janeiro de dois mil e vinte e cinco"
* ```
*/
static formatDate(date: Date): string;
}
/**
* Utilitários gerais para formatação numérica e de texto.
* @hideconstructor
*/
declare abstract class Util {
/**
* Converte string numérica (com separadores e símbolos de moeda) para número.
* Suporta BRL, USD, EUR, JPY, GBP, CNY e formatos sem moeda.
* @example Util.parseNumber("R$ 1.250,99") // 1250.99
*/
static parseNumber(value: string): Promise<number>;
/**
* Formata número como valor monetário na moeda especificada.
* @param value Valor numérico a formatar
* @param currency Moeda de destino (padrão: `Currency.BRL`)
* @returns String formatada de acordo com a localidade da moeda
* @example
* Util.convertToMonetaryValue(1250.99) // "R$ 1.250,99"
* Util.convertToMonetaryValue(1250.99, Currency.USD) // "$1,250.99"
* Util.convertToMonetaryValue(1250.99, Currency.GBP) // "£1,250.99"
*/
static convertToMonetaryValue(value: number, currency?: Currency): string;
/**
* Remove acentos diacríticos, normalizando para ASCII.
* @example Util.removeAccents("implementação") // "implementacao"
*/
static removeAccents(value: string): Promise<string>;
/**
* Abrevia termos de logradouros e títulos em endereços brasileiros.
* Normaliza acentos antes da substituição.
* @example Util.abbreviate("Avenida Sítio das Flores") // "AV SIT DAS FLORES"
*/
static abbreviate(text: string): Promise<string>;
}
/**
* Tipo de chave Pix suportada.
*/
declare enum TypePix {
/** Documento (CPF com 11 dígitos ou CNPJ com 14 dígitos). */
DOCUMENT = 0,
/** Endereço de e-mail. */
EMAIL = 1,
/** Número de celular brasileiro com DDD. */
MOBILE = 2,
/** Chave aleatória no formato UUID (EVP). */
EVP = 3
}
/**
* Métodos de validação para formatos comuns no domínio brasileiro.
* @hideconstructor
*/
declare abstract class Validate {
/**
* Valida endereço de e-mail. Suporta TLDs de até 63 caracteres.
* @example Validate.isValidEmail('contato@email.com')
*/
static isValidEmail(email: string): Promise<boolean>;
/**
* Valida número de celular brasileiro (com DDD, 9 dígitos).
* @example Validate.isValidMobile('(11) 91234-5678')
*/
static isValidMobile(mobile: string): Promise<boolean>;
/**
* Valida CNPJ numérico ou alfanumérico (nova regra Receita Federal 2026).
* @example Validate.isValidCNPJ('11.222.333/0001-81')
*/
static isValidCNPJ(cnpj: string): Promise<boolean>;
/**
* Valida CPF com ou sem máscara.
* @example Validate.isValidCPF('529.982.247-25')
*/
static isValidCPF(cpf: string): Promise<boolean>;
/**
* Valida CEP brasileiro (8 dígitos).
* @example Validate.isValidCEP('01310-100')
*/
static isValidCEP(cep: string): Promise<boolean>;
/**
* Valida chave Pix no formato EVP (UUID).
* @example Validate.isValidEVP('123e4567-e89b-12d3-a456-426614174000')
*/
static isValidEVP(evp: string): Promise<boolean>;
/**
* Valida chave PIX de acordo com o tipo informado.
* Para DOCUMENT: aceita CPF (11 dígitos) ou CNPJ (14 dígitos).
* @param type Tipo da chave Pix (TypePix)
* @param key Chave Pix a ser validada
* @returns `true` quando a chave é válida
* @throws {Error} Quando a chave não corresponde ao tipo informado ou contém valor inválido
* @example Validate.isValidPix(TypePix.EMAIL, 'contato@email.com')
*/
static isValidPix(type: TypePix, key: string): Promise<true>;
}
export { Currency, DeadlineUnit, EventBus, LocalCache, TypePix, Util, Validate, WrittenOut };
export type { EventCallback, EventMap, ICache };