BCX Utils

Uma biblioteca TypeScript utilitária que fornece classes e tipos auxiliares para manipulação de objetos, arrays, strings e tipagens avançadas com foco em type safety e funcionalidades recursivas.

Instalação

npm install bcx-utils
# ou
yarn add bcx-utils

Visão Geral

A BCX Utils oferece um conjunto abrangente de utilitários organizados em três categorias principais:

• Classes utilitárias: Operações runtime para objetos, arrays e strings
• Tipos avançados: Utility types para transformações complexas em tempo de compilação
• Type guards: Validações em runtime que melhoram a inferência de tipos do TypeScript

Classes Utilitárias

BCXObject

Manipulação avançada de objetos com suporte a operações recursivas controladas.

import { BCXObject } from 'bcx-utils';

// Verificação de tipo e estrutura
BCXObject.isObject({}); // true
BCXObject.isEmpty({}); // true
BCXObject.isNotEmpty({ prop: 1 }); // true

// Operações de seleção
const user = { name: 'John', email: '[email protected]', password: '123' };
BCXObject.pick(user, 'name', 'email'); // { name: 'John', email: '[email protected]' }
BCXObject.omit(user, 'password'); // { name: 'John', email: '[email protected]' }

// Comparação recursiva com controle de profundidade
interface User {
  name: string;
  email: string;
}
const example = { name: '', email: '' };
if (BCXObject.compareType(user, example)) {
  // example é reconhecido como User pelo TypeScript
}

// Validação de chaves e valores
BCXObject.isKeyOf(user, 'name'); // true
BCXObject.isValueOf(user, 'John'); // true

BCXArray

Operações comuns e avançadas para manipulação de arrays.

import { BCXArray } from 'bcx-utils';

// Limpeza e organização
BCXArray.clearDuplicates([1, 2, 2, 3]); // [1, 2, 3]
BCXArray.clearNullables([1, null, 2, undefined]); // [1, 2]

// Divisão e reorganização
BCXArray.chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
BCXArray.shuffle([1, 2, 3, 4]); // [3, 1, 4, 2] (resultado aleatório)

// Seleção aleatória
BCXArray.randomItem(['a', 'b', 'c']); // 'b' (resultado aleatório)
BCXArray.randomIndex(['a', 'b', 'c']); // 1 (resultado aleatório)

// Validação de tipo com type guards
const numbers: unknown[] = [1, 2, 3];
if (BCXArray.isArrayOf(numbers, (v): v is number => typeof v === 'number')) {
  // numbers é reconhecido como number[] pelo TypeScript
}

BCXString

Conversão de casos, limpeza e geração de strings.

import { BCXString } from 'bcx-utils';

// Conversão entre formatos
BCXString.toCamelCase('hello world'); // 'helloWorld'
BCXString.toSnakeCase('Hello World'); // 'hello_world'
BCXString.toKebabCase('hello world'); // 'hello-world'
BCXString.toPascalCase('hello world'); // 'HelloWorld'
BCXString.toCapitalizedCase('hello world'); // 'Hello World'

// Normalização e limpeza
BCXString.clear('  Hello   World  '); // 'Hello World'
BCXString.clear('Café'); // 'Cafe' (remove acentos)

// Geração de strings aleatórias
BCXString.random(); // 'f3K4seR1V' - 9 caracteres com quantidades proporcionais de digitos, minúsculas e maiúsculas
BCXString.random({ length: 12 }); // 'af4E3Rv02DtG'
BCXString.random({ digits: 2, lowercase: 3, uppercase: 2 }); // 'Af3abR1'

// Validação de literais com type guards
const role = 'admin';
if (BCXString.isLiteral(role, 'admin', 'user', 'guest')) {
  // role é reconhecido como 'admin' | 'user' | 'guest'
}

Tipos Utilitários

Tipos de Filtragem por Padrão

import type {
  BCXOmitByPrefix,
  BCXOmitBySubstring,
  BCXOmitBySuffix,
  BCXPickByPrefix,
  BCXPickBySubstring,
  BCXPickBySuffix,
} from 'bcx-utils';

interface User {
  id: string;
  name: string;
  email: string;
  is_active: boolean;
  is_verified: boolean;
  created_at: Date;
  updated_at: Date;
}

// Filtragem por prefixo
type WithoutFlags = BCXOmitByPrefix<User, 'is_'>;
// { id: string; name: string; email: string; created_at: Date; updated_at: Date; }

type ActiveAndVerified = BCXPickByPrefix<User, 'is_'>;
// { is_active: boolean; is_verified: boolean; }

// Filtragem por sufixo
type WithoutTimestamps = BCXOmitBySuffix<User, '_at'>;
// { id: string; name: string; email: string; is_active: boolean; is_verified: boolean; }

type Timestamps = BCXPickBySuffix<User, '_at'>;
// { created_at: Date; updated_at: Date; }

// Filtragem por substring
type NameProperties = BCXPickBySubstring<User, 'name'>;
// { name: string; }

Tipos de Seleção e Omissão Avançados

import type { BCXOmitOneOf, BCXPickOneOf } from 'bcx-utils';

interface User {
  id: string;
  name: string;
  email: string;
  phone: string;
}

// União onde cada variante omite uma propriedade diferente
type WithoutOneIdentifier = BCXOmitOneOf<User, 'id' | 'email' | 'phone'>;
// { email: string; phone: string } |
// { id: string; phone: string } |
// { id: string; email: string }

// União onde cada variante contém apenas uma propriedade
type SingleIdentifier = BCXPickOneOf<User, 'id' | 'email' | 'phone'>;
// { id: string } | { email: string } | { phone: string }

Tipos Recursivos em Cascata

import type {
  BCXCascadeRequired,
  BCXCascadePartial,
  BCXCascadeReadonly,
} from 'bcx-utils';

interface User {
  profile?: {
    name?: string;
    contact?: {
      email?: string;
      phone?: string;
    };
  };
  settings?: {
    theme?: string;
  };
}

// Todas as propriedades se tornam obrigatórias recursivamente
type RequiredUser = BCXCascadeRequired<User>;
// {
//   profile: {
//     name: string;
//     contact: {
//       email: string;
//       phone: string;
//     };
//   };
//   settings: {
//     theme: string;
//   };
// }

// Todas as propriedades se tornam opcionais recursivamente
type PartialUser = BCXCascadePartial<User>;
// {
//   profile?: {
//     name?: string;
//     contact?: {
//       email?: string;
//       phone?: string;
//     };
//   };
//   settings?: {
//     theme?: string;
//   };
// }

// Todas as propriedades se tornam readonly recursivamente
type ReadonlyUser = BCXCascadeReadonly<User>;
// {
//   readonly profile?: {
//     readonly name?: string;
//     readonly contact?: {
//       readonly email?: string;
//       readonly phone?: string;
//     };
//   };
//   readonly settings?: {
//     readonly theme?: string;
//   };
// }

Estrutura de Exportação

A biblioteca oferece pontos de entrada organizados por categoria:

// Todas as exportações
import { BCXObject, BCXArray, BCXString } from 'bcx-utils';
import type { BCXCascadeRequired, BCXOmitByPrefix } from 'bcx-utils';

// Apenas classes utilitárias
import { BCXObject, BCXArray, BCXString } from 'bcx-utils/classes';

// Apenas tipos utilitários
import type {
  BCXCascadeRequired,
  BCXOmitByPrefix,
  BCXPickBySuffix,
} from 'bcx-utils/types';

Características Principais

• Type Safety Completo: Desenvolvida inteiramente em TypeScript com tipagem forte e generics
• Type Guards Avançados: Métodos que atuam como type guards para melhor inferência de tipos
• Recursão Controlada: Operações recursivas com controle de profundidade e tratamento de erro
• Performance Otimizada: Implementações eficientes para operações comuns
• API Consistente: Interface fluente e previsível em todos os utilitários
• Documentação Abrangente: Exemplos detalhados e documentação completa com exemplos de uso

Casos de Uso Recomendados

• Validação de Dados: Verificação de estrutura e tipo em dados dinâmicos
• Transformação de Objetos: Operações de pick, omit e filtragem por padrão
• Normalização de Dados: Limpeza e formatação consistente de strings
• Manipulação de Arrays: Operações comuns com type safety
• Tipagens Avançadas: Transformações complexas de tipos em tempo de compilação

Desenvolvimento

# Instalar dependências
npm install

# Desenvolvimento com watch mode
npm run dev

# Build do projeto
npm run build

# Preparar para publicação
npm run prepublishOnly

Licença

MIT License © Bia Maxine - Dev Fullstack & UX Designer