Realistic Faker fixtures

This adapter targets @faker-js/faker@10.5.0 without making Faker a core dependency. Randomness and the reference date belong to a scoped generation session, not the process-wide Faker singleton or the wall clock. No fixtures are cryptographic secrets.

import { fromFaker, fakerAdapter } from '@mimlet/faker';

const options = { fingerprint: 'users/v1' };
const provider = fakerAdapter(options);
const users = fromFaker(
  (faker) => ({
    id: faker.string.uuid(),
    name: faker.person.fullName(),
    email: faker.internet.email(),
    joined: faker.date.recent(),
  }),
  options
);
const session = provider.session(42, { referenceTime: '2026-01-01T00:00:00.000Z' });
const fixtures = users.with({ name: 'Ada' }).buildList(3, session);

Sessions are required by the builder: there is no hidden generator that survives between tests. Save session.snapshot() before a batch and use restoreSession(snapshot, provider.identity) to replay it. Include schema/factory changes in fingerprint, additional settings in configuration, and custom locale changes and fallback order in localeIdentity. Upgrading Faker can change results; its exact version is part of the provider identity.

For named field isolation use provider.instance(session, 'email') and provider.instance(session, 'name') separately. Inserting draws into one named stream does not perturb the other. Repeated draws within one namespace advance that namespace. Sharing a namespace across concurrent callbacks remains dependent on their execution order; allocate separate scopes for independent concurrent work.

English is the default locale. Pass locale: [nl_BE, nl, en] and an explicit localeIdentity for customized fallback behavior. Locale definitions are trusted, caller-owned data; their contents must not be mutated during generation. Faker instances are fresh, while their session stream persists. Reseeding a returned instance is deliberately rejected; create or restore a session instead. Explicitly changing its date configuration or using ambient randomness in your own callback is outside the replay guarantee. The session's default reference date is fixed, not today.

fromFakerSchema(schema, factory, options) generates the validator's input type and retains the separately inferred output type. Unvalidated builds are available for negative fixtures; validated builds call the original Standard Schema entry once. No schema is weakened and no explicit override is automatically repaired. Async factories retain async-only builder capabilities. Factories, transforms and native parsing callbacks remain trusted code; allocation/random-draw budgets are not a timeout for arbitrary application callbacks.

pnpm test:optional compiles declarations and runs this integration from actual package tarballs against the locked Faker version, including locale isolation, reference dates, replay, async capabilities, failures and session exhaustion.