random-human

Generate coherent fictional people for tests, mocks, demos, and prototypes. In Node.js it can fetch fresh people from an internet API, save only the useful fields in a compact local cache, and keep working offline.

• Seeded and reproducible
• TypeScript types included
• Zero runtime dependencies
• ESM and CommonJS builds
• Locales: en_US, es_HN, es_MX, and es_ES
• Weighted names for more natural-looking output
• Optional online-first client with automatic offline fallback
• Compact, bounded JSONL cache (about a few hundred KB for thousands of people)

random-human generates synthetic combinations. Do not use its output as real identity data.

Install

npm install random-human

Quick start

import randomHuman from "random-human";

const person = await randomHuman({
  locale: "es_HN",
  gender: "female",
  age: { min: 20, max: 30 },
  seed: "my-test",
});

console.log(person);

Example shape:

{
  firstName: "Andrea",
  lastName: "Rodríguez",
  fullName: "Andrea Rodríguez",
  gender: "female",
  age: 24,
  birthDate: "2002-05-14",
  username: "andrea.rodriguez24",
  email: "[email protected]",
  locale: "es_HN"
}

That is all most users need. The package automatically uses the internet, saves a compact local cache in .random-human/cache.jsonl, and falls back to that cache when offline.

Advanced cache configuration

Use createHumanClient only when you want to change cache behavior:

import { createHumanClient } from "random-human";

const client = createHumanClient({
  cachePath: "./data/random-human.jsonl",
  maxCacheEntries: 2_000,
  timeoutMs: 4_000,
});

const person = await client.human({ locale: "es_HN" });

console.log(person.source); // "api", "cache", or "local"
console.log(person.fullName);

Both the simple function and custom clients use online-first by default:

1. Request one new person from the internet.
2. Keep only eight useful values and append one compact line to the cache.
3. If the request fails, pick a matching person from the cache.
4. If the cache is empty, use the bundled local generator.

The remote request excludes photos, addresses, passwords, and other unused fields. The cache is capped at 2,000 entries by default and automatically keeps only the newest records.

Cache strategies

createHumanClient({ strategy: "online-first" }); // API, then cache, then local
createHumanClient({ strategy: "cache-first" });  // cache first, API if empty
createHumanClient({ strategy: "offline" });      // never uses the internet

Inspect or clear the cache

const stats = await client.cacheStats();
// { entries: 245, bytes: 30120, path: "/.../random-human.jsonl" }

await client.clearCache();

The cache uses compact JSON Lines rather than a verbose copy of the API response. A stored line looks like this:

["es_HN","Lucía","García","female",28,"1998-04-12","lucia.garcia","[email protected]"]

es_HN uses the API's Mexican Spanish name pool because the provider does not expose Honduras as a nationality. The small bundled Honduran dataset remains the final offline fallback.

Reproducible data

Pass a string or number as seed. The same options and seed produce the same result. Since age depends on time, pass referenceDate when you need the whole result to remain stable forever.

const person = human({
  locale: "es_MX",
  seed: 2026,
  referenceDate: "2026-09-21",
});

Individual generators

Pure offline generators are available from random-human/offline:

import {
  randomName,
  randomUsername,
  randomEmail,
  randomAge,
  randomDateOfBirth,
  randomDelay,
} from "random-human/offline";

randomName({ locale: "es_ES", gender: "male" });
randomUsername({ locale: "en_US", seed: 10 });
randomEmail({ locale: "es_HN", emailDomain: "test.local" });
randomAge({ min: 18, max: 40 });
randomDateOfBirth({ min: 18, max: 40 });
await randomDelay({ min: 300, max: 1_200 });

API

randomHuman(options?)

Returns a promise containing a complete fictional person. It automatically handles the API, cache, and local fallback.

| Option | Type | Default | | --- | --- | --- | | locale | en_US \| es_HN \| es_MX \| es_ES | en_US | | gender | female \| male \| any | any | | age | { min?: number; max?: number } | 18–80 | | seed | string \| number | random | | emailDomain | string | reserved example domain | | referenceDate | Date \| string | current date |

Other functions

• randomName(options?)
• randomUsername(options?)
• randomEmail(options?)
• randomAge(options?)
• randomDateOfBirth(options?)
• randomDelay(options?)

Development

npm install
npm test
npm run typecheck
npm run build

Before publishing, confirm the package name is still available, sign in, and run:

npm publish --access public

Data and privacy

The bundled fallback datasets are small, manually curated lists of common names with approximate frequency weights. They contain no scraped profiles or personal records. The email domains are IANA-reserved example domains.

The Node.js client uses Random User Generator and stores synthetic results locally. It does not send data about your application's users to the provider; request options such as locale, gender, and seed are the only query parameters.

Future larger datasets should only be added from public, aggregate sources with a compatible license, and their source and license should be documented in the repository.

License

MIT © Eduardo Castro