nano-faker

nano-faker

Lightweight, tree-shakable fake data generation for modern JavaScript

📦 < 1KB Core
🌳 Tree-Shakable
🎲 Deterministic
⚡ Zero Deps
🎯

Minimal Bundle Size

Core package < 1KB gzipped. Each additional package adds only ~500B. Import only what you need.

🌳

Fully Tree-Shakable

ESM-only with granular exports. Your bundler eliminates unused code automatically.

🎲

Deterministic Output

Same seed always produces same results. Perfect for snapshot testing and reproducible demos.

⚡

Zero Dependencies

No external packages. Works in browsers and Node.js without any additional setup.

📝

TypeScript First

Written in TypeScript with full type definitions. Excellent IDE autocomplete support.

🚀

Modern ESM

Built for modern JavaScript. No legacy CommonJS baggage or compatibility layers.

Quick Example

import { setSeed } from '@nano-faker/core';
import { firstName, lastName } from '@nano-faker/person';
import { email } from '@nano-faker/internet';

// Set seed for deterministic output
setSeed(12345);

console.log(firstName()); // "Alison"
console.log(lastName());  // "Anderson"
console.log(email());     // "alison.anderson42@gmail.com"

Getting Started

Install and start using nano-faker in minutes

Installation

Install only the packages you need using your preferred package manager:

# Using pnpm (recommended)
pnpm add @nano-faker/core @nano-faker/person @nano-faker/internet

# Using npm
npm install @nano-faker/core @nano-faker/person @nano-faker/internet

# Using yarn
yarn add @nano-faker/core @nano-faker/person @nano-faker/internet

Available Packages

@nano-faker/core

Foundation package with seeded RNG and utilities

< 1KB

@nano-faker/number

Numeric data generation (age, id, otp, range)

~500B

@nano-faker/person

Person data with syllable-based names

~500B

@nano-faker/internet

Email, username, domain, URL, IP generation

~500B

@nano-faker/patterns

Format-based generation with placeholders

~500B

Basic Usage

Import functions directly from packages:

import { setSeed, random, int, float } from '@nano-faker/core';
import { firstName, lastName, fullName } from '@nano-faker/person';
import { email, username } from '@nano-faker/internet';

// Set seed for reproducible results
setSeed(12345);

// Generate data
const name = fullName();    // "Marcus Rodriguez"
const addr = email();       // "marcus.rodriguez42@gmail.com"
const user = username();    // "marcus_rodriguez42"

Deterministic Testing

Use seeds for consistent test data:

import { setSeed } from '@nano-faker/core';
import { fullName } from '@nano-faker/person';

describe('User tests', () => {
  beforeEach(() => {
    setSeed(12345); // Same seed = same data
  });

  it('should create user', () => {
    const name = fullName();
    expect(name).toMatchSnapshot(); // Always passes
  });
});

Next Steps

Interactive Playground

Test all functions with live output

Core

random():
int(1, 100):
float(0, 10, 2):

Number

age():
id():
otp():

Person

firstName():
lastName():
fullName():
gender():

Internet

email():
username():
domain():
url():
ipv4():

Patterns

fake("USR-####-@@"):
fake("###-##-####"):
fake("***-***-***"):

API Reference

Complete documentation for all packages

@nano-faker/core

Foundation package with seeded random number generation and utilities.

setSeed(seed: number): void

Set the seed for deterministic random number generation.

Parameters:

  • seed - Positive integer seed value
setSeed(12345);
const value = random(); // Always same with same seed

random(): number

Generate a random float between 0 (inclusive) and 1 (exclusive).

Returns:

Random float [0, 1)

const value = random(); // e.g., 0.7234

int(min: number, max: number): number

Generate a random integer between min and max (both inclusive).

Parameters:

  • min - Minimum value (inclusive)
  • max - Maximum value (inclusive)
const age = int(18, 65);  // e.g., 42
const dice = int(1, 6);   // e.g., 4

float(min: number, max: number, precision?: number): number

Generate a random float between min and max.

Parameters:

  • min - Minimum value (inclusive)
  • max - Maximum value (exclusive)
  • precision - Number of decimal places (default: 2)
const price = float(10.0, 100.0, 2); // e.g., 45.67

pick<T>(array: T[]): T

Pick a random element from an array.

Parameters:

  • array - Array to pick from
const color = pick(['red', 'green', 'blue']); // e.g., 'green'

shuffle<T>(array: T[]): T[]

Shuffle an array using Fisher-Yates algorithm. Returns a new array.

Parameters:

  • array - Array to shuffle
const shuffled = shuffle([1, 2, 3, 4, 5]); // e.g., [3, 1, 5, 2, 4]

@nano-faker/number

Numeric data generation utilities.

age(min?: number, max?: number): number

Generate a random age.

Parameters:

  • min - Minimum age (default: 18)
  • max - Maximum age (default: 80)
const userAge = age();        // e.g., 42
const childAge = age(5, 12);  // e.g., 8

id(length?: number): string

Generate a numeric ID.

Parameters:

  • length - Length of the ID (default: 8)
const userId = id();      // e.g., "47382910"
const orderId = id(12);   // e.g., "847362910485"

otp(length?: number): string

Generate a one-time password.

Parameters:

  • length - Length of the OTP (default: 6)
const code = otp();     // e.g., "472839"
const pin = otp(4);     // e.g., "8473"

range(min: number, max: number): number

Generate a number within range.

Parameters:

  • min - Minimum value (inclusive)
  • max - Maximum value (inclusive)
const score = range(0, 100); // e.g., 73

@nano-faker/person

Person data generation with syllable-based procedural names.

firstName(): string

Generate a procedural first name.

const name = firstName(); // e.g., "Alison", "Marcus"

lastName(): string

Generate a procedural last name.

const surname = lastName(); // e.g., "Anderson", "Rodriguez"

fullName(): string

Generate a full name (first + last).

const name = fullName(); // e.g., "Sarah Johnson"

gender(): string

Generate a random gender.

Returns:

One of: "male", "female", "non-binary", "other"

const g = gender(); // e.g., "female"

@nano-faker/internet

Internet-related data generation.

email(): string

Generate a random email address.

const addr = email(); // e.g., "sarah.johnson42@gmail.com"

username(): string

Generate a random username.

const user = username(); // e.g., "sarah_johnson42"

domain(): string

Generate a random domain name.

const d = domain(); // e.g., "example.com"

url(): string

Generate a random URL.

const link = url(); // e.g., "https://example.com"

ipv4(): string

Generate a random IPv4 address.

const ip = ipv4(); // e.g., "192.168.1.42"

@nano-faker/patterns

Pattern-based fake data generation.

fake(pattern: string): string

Generate fake data based on a pattern string.

Placeholders:

  • # → Random digit (0-9)
  • @ → Random lowercase letter (a-z)
  • * → Random alphanumeric character
  • \ → Escape character
fake("USR-####-@@");    // e.g., "USR-4728-ab"
fake("###-##-####");    // e.g., "472-83-9102"
fake("***-***-***");    // e.g., "a7X-9Bz-K4m"
fake("\\#\\#\\#");      // "###" (escaped)

Examples

Common use cases and patterns

Testing with Snapshots

Use deterministic seeds for consistent test data:

import { setSeed } from '@nano-faker/core';
import { fullName, email } from '@nano-faker/person';

describe('User creation', () => {
  beforeEach(() => {
    setSeed(12345); // Same seed = same data
  });

  it('should create user with valid data', () => {
    const user = {
      name: fullName(),
      email: email(),
    };
    
    expect(user).toMatchSnapshot();
    // Snapshot will always match
  });
});

Generating Test Data Arrays

Create arrays of fake data for testing:

import { setSeed } from '@nano-faker/core';
import { fullName, email } from '@nano-faker/person';
import { age } from '@nano-faker/number';

setSeed(12345);

const users = Array.from({ length: 10 }, (_, i) => ({
  id: i + 1,
  name: fullName(),
  email: email(),
  age: age(18, 65),
}));

console.log(users);
// Always generates same 10 users with same seed

Custom ID Formats

Use patterns to generate custom ID formats:

import { fake } from '@nano-faker/patterns';

// User IDs
const userId = fake("USR-####-@@@@");
// "USR-4728-abcd"

// Order numbers
const orderNum = fake("ORD-########");
// "ORD-47382910"

// License keys
const license = fake("****-****-****-****");
// "a7X9-BzK4-mP2q-R8vN"

// SSN-like patterns
const ssn = fake("###-##-####");
// "472-83-9102"

Mock API Responses

Generate realistic mock data for API development:

import { setSeed } from '@nano-faker/core';
import { fullName, email } from '@nano-faker/person';
import { age, id } from '@nano-faker/number';
import { ipv4 } from '@nano-faker/internet';

setSeed(Date.now()); // Different data each time

const mockUser = {
  id: id(8),
  name: fullName(),
  email: email(),
  age: age(18, 65),
  lastLoginIp: ipv4(),
  createdAt: new Date().toISOString(),
};

// Use in mock API handler
app.get('/api/users/:id', (req, res) => {
  res.json(mockUser);
});

Seeded Randomization

Use seeds to create reproducible random data:

import { setSeed, shuffle, pick } from '@nano-faker/core';

const items = ['apple', 'banana', 'cherry', 'date', 'elderberry'];

// Same seed = same shuffle
setSeed(100);
console.log(shuffle(items));
// Always: ['cherry', 'apple', 'elderberry', 'date', 'banana']

setSeed(100);
console.log(shuffle(items));
// Same result again

// Different seed = different shuffle
setSeed(200);
console.log(shuffle(items));
// Different order

Combining Packages

Mix and match functions from different packages:

import { setSeed } from '@nano-faker/core';
import { firstName, lastName } from '@nano-faker/person';
import { domain } from '@nano-faker/internet';
import { fake } from '@nano-faker/patterns';

setSeed(12345);

// Create a complete user profile
const profile = {
  firstName: firstName(),
  lastName: lastName(),
  username: `${firstName().toLowerCase()}_${fake("####")}`,
  email: `${firstName().toLowerCase()}@${domain()}`,
  userId: fake("USR-########"),
  apiKey: fake("****-****-****-****"),
};

console.log(profile);