TS Guard Utils

Conjunto de utilitários TypeScript focados em segurança de tipo (type-safety) e praticidade. Esta biblioteca fornece funções auxiliares para validação, formatação e manipulação de objetos, arrays e strings no dia a dia do desenvolvimento.

import { typeOf, pick, omit } from 'ts-guard-utils';

// 1. typeOf: Type Guard seguro para múltiplos tipos
const processId = (id: unknown) => {
  if (typeOf(id, 'string', 'number')) {
    // Aqui o TypeScript sabe que 'id' é string | number
    console.log(`Processando ID: ${id}`);
  }
};

// 2. pick: Extraindo propriedades específicas de forma tipada
const user = { id: 1, name: 'John Doe', role: 'admin', active: true };
const publicProfile = pick(user, 'name', 'role');
// Resultado: { name: 'John Doe', role: 'admin' }

// 3. omit: Removendo dados sensíveis
const account = { username: 'john_doe', password: '123', token: 'abc' };
const safeAccount = omit(account, 'password', 'token');
// Resultado: { username: 'john_doe' }

import { clearDuplicates, chunk, shuffle } from 'ts-guard-utils';

// 1. clearDuplicates: Removendo itens repetidos
const numbers = [1, 2, 2, 3, 4, 4, 5];
const uniqueNumbers = clearDuplicates(numbers);
// Resultado: [1, 2, 3, 4, 5]

// 2. chunk: Dividindo um array em lotes (paginação ou processamento em massa)
const data = ['a', 'b', 'c', 'd', 'e'];
const batches = chunk(data, 2);
// Resultado: [['a', 'b'], ['c', 'd'], ['e']]

// 3. shuffle: Embaralhando itens sem alterar o array original
const deck = ['Carta 1', 'Carta 2', 'Carta 3'];
const randomDeck = shuffle(deck);
// Resultado: Itens em ordem aleatória, ex: ['Carta 3', 'Carta 1', 'Carta 2']

import { toCamelCase, clearText, strRandom } from 'ts-guard-utils';

// 1. toCamelCase e clearText: Padronização de textos e variáveis
const rawInput = '  Ação e  Reação  ';
console.log(clearText(rawInput));
// Resultado: 'Acao e Reacao'

const filename = 'User_profile-image';
console.log(toCamelCase(filename));
// Resultado: 'userProfileImage'

// 2. strRandom: Geração de senhas, tokens ou IDs aleatórios
const randomToken = strRandom({ length: 12 });
// Resultado: String aleatória de 12 caracteres balanceada (letras e números)

const customPassword = strRandom({ digits: 4, uppercases: 2, lowercases: 2 });
// Resultado: String aleatória contendo exatamente 4 números, 2 maiúsculas e 2 minúsculas

Get Started

Você pode instalar a biblioteca utilizando:

npm install ts-guard-utils
# ou
pnpm add ts-guard-utils
# ou
yarn add ts-guard-utils

Utilitários para manipulação de Objetos

Funções importadas a partir do módulo object para verificar tipos, validar propriedades e transformar estruturas de objetos de forma imutável e tipada.

| Utilitário | Descrição | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | typeOf | Verifica de forma segura se um valor corresponde a um ou mais tipos específicos listados no TypeMap customizado. | | isObject | Determina se o valor fornecido é estritamente um objeto (exclui null). | | isPlainObject | Valida se um valor é um objeto simples (literal) sem um protótipo complexo instanciado. | | isEmpty | Checa se um objeto plano está completamente vazio (sem chaves próprias). | | isNotEmpty | Verifica se um objeto plano possui ao menos uma chave. | | pick | Cria um novo objeto extraindo e contendo apenas as propriedades especificadas da origem. | | omit | Cria um novo objeto omitindo/excluindo as propriedades especificadas da origem. | | isKeyOf | Valida (como Type Guard) se um valor desconhecido é uma chave existente válida dentro do objeto alvo. | | isValueOf | Valida (como Type Guard) se um valor está presente entre os valores mapeados nas propriedades do objeto. |

Utilitários para manipulação de Arrays

Funções do módulo array que facilitam a limpeza, fragmentação, sorteio e validação de listas.

| Utilitário | Descrição | | --------------------- | -------------------------------------------------------------------------------------------------------------------- | | clearDuplicates | Remove todos os elementos duplicados de um array (comparações de objetos são feitas por referência). | | clearNullables | Filtra e remove os valores null e undefined de um array, garantindo a tipagem dos itens restantes. | | chunk | Divide um array em partes menores (fragmentos ou chunks) com base em um tamanho máximo definido. | | randomIndex | Gera e retorna um índice numérico aleatório válido com base no comprimento do array fornecido. | | randomItem | Seleciona e retorna um elemento aleatório de dentro do array. | | shuffle | Embaralha os elementos de um array utilizando o algoritmo Fisher-Yates, retornando uma cópia imutável. | | typeOfArray | Valida se uma estrutura é um array e se todos os seus itens pertencem aos tipos primitivos informados. | | isArrayOf | Aplica uma função de validação (Type Guard customizado) para checar se todos os itens de um array atendem à regra. |

Utilitários para manipulação de Strings

O módulo string engloba validadores literais, normalizadores de texto, conversores de formato (cases) e geradores de texto aleatório.

| Utilitário | Descrição | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | | isLiteral | Valida se uma string arbitrária corresponde a um dos valores de uma união de strings literais. | | literalIsIn | Verifica se um literal de um tipo base pertence a um subconjunto específico de literais. | | literalIsNotIn | Verifica se um literal não pertence a um subconjunto, permitindo sua exclusão do tipo via inferência. | | toCapitalizedCase | Converte a primeira letra de cada palavra de uma string para maiúscula (Title Case). | | clearText | Normaliza um texto removendo acentuações (diacríticos) e reduzindo espaços em branco excessivos. | | toCamelCase | Transforma o formato da string para camelCase, removendo acentos e símbolos no processo. | | toSnakeCase | Transforma a string para snake_case. Possui suporte opcional para CONSTANT_CASE. | | toKebabCase | Transforma a string para kebab-case. Possui suporte opcional para versão uppercase. | | toPascalCase | Transforma o formato da string para PascalCase com as iniciais sempre maiúsculas. | | strRandom | Gera de forma imprevisível uma string aleatória baseada no comprimento total ou numa contagem exata de letras e dígitos. |

Contribuições e Licenciamento

Se você encontrar um bug ou tiver uma ideia de melhoria, sinta-se à vontade para abrir uma Issue ou enviar um Pull Request no repositório oficial.

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para mais detalhes.

Nota da Autora

Feito com ❤️☕ e TypeScript por Bia Maxine.

Espero que este conjunto de utilitários acelere e traga mais segurança e padronização para o seu código, assim como traz para os meus projetos pessoais!