🎭 Contextual Faker

Gerador de dados fake realistas com contexto e comportamento coerente

Contextual Faker é uma biblioteca npm que gera dados de teste realistas onde os dados fazem sentido juntos, não apenas valores aleatórios isolados. Diferente de bibliotecas como Faker.js que geram dados genéricos, o Contextual Faker cria cenários completos com comportamento coerente.

✨ Características

• 🎯 Dados contextualizados: Gera dados que fazem sentido juntos
• 🇧🇷 Suporte a dados brasileiros: CPF, CNPJ, CEP, telefones, endereços reais
• 🎲 Determinístico: Mesma seed gera sempre os mesmos dados (perfeito para testes)
• 📊 Comportamento realista: Clientes premium compram mais, gastam mais, têm frete grátis
• 🔗 Relacionamentos: Dados linkados (cliente → pedidos → produtos)
• 🎨 Segmentação: Diferentes perfis de usuários com comportamentos distintos
• 📦 TypeScript: Totalmente tipado

📦 Instalação

npm install contextual-faker

🚀 Uso Básico

E-commerce

import { EcommerceFaker } from 'contextual-faker';

const ecommerce = new EcommerceFaker('pt-BR');

// Gera um cliente premium com preferências específicas
const customer = ecommerce.customer({
  segment: 'premium',
  preferences: ['electronics', 'books']
});

console.log(customer);
// {
//   id: 'cust_7x9k2m',
//   name: 'Maria Silva Santos',
//   email: '[email protected]',
//   cpf: '123.456.789-00',
//   phone: '(11) 98765-4321',
//   address: { ... },
//   segment: 'premium',
//   totalOrders: 47,
//   totalSpent: 15420.50,
//   averageOrderValue: 328.09,
//   favoriteCategories: ['electronics', 'books'],
//   lastPurchase: '2024-01-20T15:45:00Z',
//   loyaltyPoints: 25000
// }

// Gera pedidos realistas para esse cliente
const orders = ecommerce.orders(customer, { count: 3 });

console.log(orders[0]);
// {
//   id: 'ord_a1b2c3',
//   customerId: 'cust_7x9k2m',
//   date: '2024-01-20T15:45:00Z',
//   status: 'delivered',
//   items: [
//     {
//       id: 'prod_electronics_001',
//       name: 'Fone Bluetooth Sony WH-1000XM4',
//       category: 'electronics',
//       quantity: 1,
//       price: 1299.90
//     }
//   ],
//   subtotal: 1299.90,
//   shipping: 0, // Frete grátis para premium
//   discount: 129.99, // 10% desconto premium
//   total: 1169.91,
//   payment: { method: 'credit_card', installments: 3 },
//   shippingInfo: { trackingCode: 'BR123456789BR', ... }
// }

🎯 Principais Funcionalidades

1. Segmentação de Clientes

A biblioteca entende que diferentes tipos de clientes têm comportamentos diferentes:

// Cliente Ocasional: Compra pouco, gasta pouco
const occasional = ecommerce.customer({ segment: 'occasional' });
// totalOrders: 1-5, averageOrderValue: R$ 50-200

// Cliente Regular: Compra regularmente
const regular = ecommerce.customer({ segment: 'regular' });
// totalOrders: 6-30, averageOrderValue: R$ 150-400

// Cliente Premium: Compra muito, gasta muito
const premium = ecommerce.customer({ segment: 'premium' });
// totalOrders: 31-100, averageOrderValue: R$ 300-1000
// + Frete grátis sempre
// + 10% de desconto
// + Pontos de fidelidade

2. Preferências de Categoria

Clientes têm categorias favoritas e tendem a comprar delas:

const customer = ecommerce.customer({
  preferences: ['electronics', 'books']
});

// 70% dos produtos nos pedidos serão dessas categorias
const orders = ecommerce.orders(customer, { count: 5 });

3. Dados Brasileiros Válidos

import { generateCPF, generateCNPJ, formatPhone, formatCEP } from 'contextual-faker';

const cpf = generateCPF();        // "123.456.789-00" (válido)
const cnpj = generateCNPJ();      // "12.345.678/0001-90" (válido)
const phone = formatPhone(...);   // "(11) 98765-4321"
const cep = formatCEP(...);       // "01310-100"

4. Comportamento Realista em Pedidos

// Status do pedido baseado na data
// - Pedidos recentes: 'pending' ou 'processing'
// - Pedidos de 1-3 dias: 'processing' ou 'shipped'
// - Pedidos de 3-7 dias: 'shipped' ou 'delivered'
// - Pedidos antigos: 95% 'delivered', 5% 'cancelled'

// Frete grátis em condições realistas
// - Clientes premium: sempre grátis
// - Outros: grátis acima de R$ 200

// Métodos de pagamento coerentes
// - Premium: preferencialmente PIX ou cartão em poucas parcelas
// - Regular/Ocasional: incluem boleto e mais parcelamento

5. Seeds para Testes Determinísticos

// Usando seed, sempre gera os mesmos dados
const ecommerce1 = new EcommerceFaker('pt-BR', 'test-seed-123');
const ecommerce2 = new EcommerceFaker('pt-BR', 'test-seed-123');

const customer1 = ecommerce1.customer();
const customer2 = ecommerce2.customer();

// customer1 e customer2 são idênticos!
// Perfeito para testes unitários

📚 API Completa

EcommerceFaker

constructor(locale?, seed?)

const faker = new EcommerceFaker('pt-BR', 'optional-seed');

customer(options?)

Gera um cliente de e-commerce.

Opções:

• segment: 'occasional' | 'regular' | 'premium'
• preferences: string[] - Categorias favoritas
• registeredDaysAgo: number - Dias desde o cadastro

Retorna: EcommerceCustomer

orders(customer, options?)

Gera pedidos para um cliente.

Opções:

• count: number - Quantidade de pedidos (padrão: 3-10)
• status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled'
• daysRange: number - Intervalo de dias para os pedidos

Retorna: Order[]

getCategories()

Retorna todas as categorias disponíveis.

Retorna: string[]

getProductsByCategory(category)

Retorna produtos de uma categoria específica.

Retorna: Product[]

🗺️ Roadmap

Próximas implementações planejadas:

Social Media Faker

import { SocialMediaFaker } from 'contextual-faker';

const social = new SocialMediaFaker('pt-BR');

const user = social.user({
  type: 'influencer',
  niche: 'tech'
});
// Gera usuário com seguidores, engajamento realista, bio contextualizada

const posts = social.posts(user, { count: 5 });
// Posts com engajamento coerente ao perfil do usuário

Banking Faker

import { BankingFaker } from 'contextual-faker';

const banking = new BankingFaker('pt-BR');

const account = banking.account({
  type: 'checking',
  profile: 'active'
});
// Conta com banco real brasileiro, saldos realistas

const transactions = banking.transactions(account, { days: 30 });
// Transações com categorias realistas, contas recorrentes, padrões de gastos

🎨 Categorias de Produtos

Atualmente disponíveis:

• electronics - Eletrônicos
• books - Livros
• clothing - Roupas
• home - Casa e Decoração
• sports - Esportes
• beauty - Beleza
• toys - Brinquedos
• food - Alimentos

🧪 Testes

npm test

🤝 Contribuindo

Contribuições são bem-vindas! Áreas que precisam de ajuda:

1. Novos geradores: Social Media, Banking, etc.
2. Mais locales: en-US, es-ES, etc.
3. Mais produtos: Expandir catálogo
4. Testes: Aumentar cobertura
5. Documentação: Mais exemplos

📄 Licença

MIT

🙏 Agradecimentos

Inspirado por:

• Faker.js - Para geração de dados aleatórios
• Necessidade real de dados de teste mais contextualizados e realistas

Feito com ❤️ para desenvolvedores que precisam de dados de teste realistas