@neetru/db-fixtures

Gerador de dados sinteticos deterministico para as suites de teste do Neetru Core DB. Um faker minusculo: um PRNG semeado mais geradores de campo.

O que e

As suites de teste precisam de dados falsos reproduziveis. A mesma semente precisa sempre produzir exatamente as mesmas linhas, em qualquer sistema operacional, toda execucao. Este pacote entrega isso — e nada alem disso.

A garantia central:

• O PRNG e o mulberry32, um gerador conhecido, minusculo e com boa distribuicao, com estado de 32 bits.
• Nada de Math.random, Date.now nem crypto. So aritmetica inteira/float pura. O determinismo cross-OS e o produto.
• Sementes string sao hasheadas via FNV-1a 32 bits; sementes numericas sao coagidas para uint32.

Funcoes puras, zero dependencias de runtime.

API

import {
  createRng,
  fakeFullName,
  fakeEmail,
  fakeUuid,
  fakeIsoDate,
  fakeSentence,
  fakeInt,
  generateRows,
} from '@neetru/db-fixtures';

createRng(seed)

Cria um SeededRng deterministico. seed pode ser string ou number.

interface SeededRng {
  next(): number;                          // float em [0, 1)
  int(min: number, max: number): number;   // inteiro, inclusivo nas duas pontas
  bool(): boolean;                         // next() < 0.5
  pick<T>(arr: readonly T[]): T;            // um elemento do array
}

• int lanca se min > max ou se min/max nao forem inteiros finitos.
• pick lanca se o array for vazio.

Geradores de campo

Cada gerador consome estado do SeededRng que recebe — chamadas sucessivas avancam o gerador.

| Funcao | Retorno | |---|---| | fakeFullName(rng) | "<First> <Last>" | | fakeEmail(rng) | first.last<n>@<dominio>, minusculo, forma valida | | fakeUuid(rng) | string no formato UUID v4, deterministica (NAO crypto.randomUUID) | | fakeIsoDate(rng) | string ISO 8601 numa faixa plausivel (2020-2026) | | fakeSentence(rng) | frase curta capitalizada terminada em . | | fakeInt(rng, min, max) | inteiro em [min, max] |

generateRows(spec, count, seed)

Gera count linhas aplicando um spec de geradores de campo.

const userSpec = {
  id: (rng) => fakeUuid(rng),
  name: (rng) => fakeFullName(rng),
  email: (rng) => fakeEmail(rng),
  age: (rng) => fakeInt(rng, 18, 80),
};

const rows = generateRows(userSpec, 100, 'seed-da-suite');
// mesma (spec, count, seed) -> sempre as mesmas 100 linhas

• count deve ser um inteiro nao-negativo; count === 0 devolve [].
• O spec nunca e mutado.
• As chaves do spec sao iteradas em ordem estavel (Object.keys(spec).sort()), de modo que a ordem de consumo do rng — e portanto a saida — nao depende da ordem de insercao das chaves no objeto spec.

A garantia de determinismo

Para a mesma (spec, count, seed), generateRows devolve uma saida deeply-equal em toda chamada, em qualquer maquina. Um unico SeededRng e criado da semente e reutilizado por todas as linhas e campos; a ordem de iteracao das chaves e ordenada. Nada le o relogio, o ambiente ou uma fonte de entropia. Sementes diferentes produzem dados diferentes.

Desenvolvimento

npm run build   # tsc -> dist/
npm test        # vitest run