Zig Faker

A high-performance, lightweight fake data generator for Zig, inspired by ts-mocker. Generate realistic fake data for testing, prototyping, and development.

Features

High Performance: Optimized for speed with minimal allocations
Comprehensive Data: 20+ major data categories with thousands of data points
Extensive Locale Support: 55 locales (27 base + 28 regional variants)
Seeded Generation: Reproducible random data with optional seeding
Type Safe: Fully typed Zig API
Zero External Dependencies: Pure Zig implementation
Modular Design: Use only what you need

Installation

Add zig-faker to your build.zig.zon:

.dependencies = .{
    .@"zig-faker" = .{
        .url = "https://github.com/yourusername/zig-faker/archive/main.tar.gz",
        .hash = "...",
    },
},

Then in your build.zig:

const zig_faker = b.dependency("zig-faker", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("zig-faker", zig_faker.module("zig-faker"));

Quick Start

const std = @import("std");
const Faker = @import("zig-faker").Faker;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Initialize faker (no seed = random data)
    var faker = Faker.init(allocator, null, null);

    // Generate data
    const name = try faker.person.fullName(.{});
    defer allocator.free(name);

    const email = try faker.internet.email();
    defer allocator.free(email);

    const phone = try faker.phone.phoneNumber();
    defer allocator.free(phone);

    std.debug.print("Name: {s}\n", .{name});
    std.debug.print("Email: {s}\n", .{email});
    std.debug.print("Phone: {s}\n", .{phone});
}

API Reference

Person Module

// First name with optional gender
const first = faker.person.firstName(.{ .gender = .male });

// Last name
const last = faker.person.lastName();

// Full name with options
const full = try faker.person.fullName(.{
    .prefix = true,   // Add Mr./Mrs./etc.
    .suffix = false,  // Add Jr./Sr./etc.
    .gender = .female,
});
defer allocator.free(full);

// Name components
const prefix = faker.person.prefix();    // Mr., Mrs., Dr., etc.
const suffix = faker.person.suffix();    // Jr., Sr., III, etc.
const gender = faker.person.gender();    // Male, Female, Non-binary, etc.
const job = faker.person.jobTitle();     // Software Engineer, etc.

Address Module

// City, state, country
const city = faker.address.city();
const state = faker.address.state();
const state_abbr = faker.address.stateAbbr();
const country = faker.address.country();

// Street address
const street = try faker.address.streetAddress(.{
    .use_full_address = false,
});
defer allocator.free(street);

// Full address
const address = try faker.address.fullAddress();
defer allocator.free(address);

// Postal code
const zip = try faker.address.postalCode();
defer allocator.free(zip);

// Direction
const direction = faker.address.direction(); // North, South, etc.

Company Module

// Company name
const company = try faker.company.name();
defer allocator.free(company);

// Company components
const suffix = faker.company.suffix();       // Inc, LLC, Corp, etc.
const industry = faker.company.industry();   // Technology, Finance, etc.
const buzzword = faker.company.buzzword();   // synergy, leverage, etc.
const descriptor = faker.company.descriptor(); // innovative, leading, etc.

// Catch phrase
const phrase = try faker.company.catchPhrase();
defer allocator.free(phrase);

Internet Module

// Email addresses
const email = try faker.internet.email();
defer allocator.free(email);

const free_email = try faker.internet.freeEmail();
defer allocator.free(free_email);

// Domain components
const domain = try faker.internet.domainName();
defer allocator.free(domain);

const domain_word = faker.internet.domainWord();
const domain_suffix = faker.internet.domainSuffix();

// URLs
const url = try faker.internet.url();
defer allocator.free(url);

// Username
const username = try faker.internet.username();
defer allocator.free(username);

// Password
const password = try faker.internet.password(8, 16); // min, max length
defer allocator.free(password);

Phone Module

// Phone number (locale-specific format)
const phone = try faker.phone.phoneNumber();
defer allocator.free(phone);

String Module

// UUID v4
const uuid = try faker.string.uuid();
defer allocator.free(uuid);

// Nanoid (URL-friendly unique ID)
const nanoid = try faker.string.nanoid(21);
defer allocator.free(nanoid);

// Random strings
const alphanum = try faker.string.alphanumeric(16);
defer allocator.free(alphanum);

const alpha = try faker.string.alpha(10);
defer allocator.free(alpha);

const numeric = try faker.string.numeric(8);
defer allocator.free(numeric);

const hex = try faker.string.hexadecimal(32);
defer allocator.free(hex);

Seeded Generation

For reproducible random data (useful for testing):

// Same seed = same data
var faker1 = Faker.init(allocator, 12345, null);
var faker2 = Faker.init(allocator, 12345, null);

const name1 = faker1.person.firstName(.{});
const name2 = faker2.person.firstName(.{});
// name1 == name2 (guaranteed)

// Change seed at runtime
faker1.seed(54321);
const name3 = faker1.person.firstName(.{});
// name3 will be different

Locale Support

const locales = @import("zig-faker").locales;

// Use specific locale (base locale)
var faker = Faker.init(allocator, null, &locales.en);

// Or use regional variant
var faker_us = Faker.init(allocator, null, &locales.en_US);
var faker_uk = Faker.init(allocator, null, &locales.en_GB);

// Change locale at runtime
faker.setLocale(&locales.es); // Switch to Spanish

Available Locales (55 Total)

27 Base Locales:

af (Afrikaans), ar (Arabic), az (Azerbaijani), cs (Czech), da (Danish)
de (German), en (English), eo (Esperanto), es (Spanish), fa (Persian)
fi (Finnish), fr (French), he (Hebrew), hi (Hindi), it (Italian)
ja (Japanese), ko (Korean), nl (Dutch), no (Norwegian), pl (Polish)
pt (Portuguese), sv (Swedish), tl (Tagalog), tr (Turkish), uk (Ukrainian)
zh (Chinese), zu (Zulu)

28 Regional Variants:

English (11): en_US, en_GB, en_AU, en_CA, en_GH, en_HK, en_IE, en_IN, en_NG, en_ZA
German (3): de_AT (Austria), de_CH (Switzerland), de_DE (Germany)
Spanish (2): es_ES (Spain), es_MX (Mexico)
French (6): fr_BE (Belgium), fr_CA (Canada), fr_CH (Switzerland), fr_FR (France), fr_LU (Luxembourg), fr_SN (Senegal)
Portuguese (3): pt_BR (Brazil), pt_MZ (Mozambique), pt_PT (Portugal)
Chinese (2): zh_CN (China), zh_TW (Taiwan)
African (2): af_ZA (Afrikaans - South Africa), zu_ZA (Zulu - South Africa)

All regional variants include localized:

City and state/province names
Postal code formats
Phone number formats
Domain suffixes and email providers
Appropriate locale-specific data

Data Categories

Person

First names (male, female, neutral)
Last names
Name prefixes/suffixes
Gender identities
Job titles

Address

Street names and numbers
Cities, states, countries
Postal codes
Directions
Full addresses

Company

Company names and suffixes
Industries
Business buzzwords
Descriptors
Catch phrases

Internet

Email addresses (custom and free providers)
Domain names
URLs
Usernames
Passwords

Phone

Phone numbers (locale-specific formats)

String Utilities

UUID v4 generation
Nanoid generation
Alphanumeric, alphabetic, numeric strings
Hexadecimal strings

Building and Testing

# Run tests
zig build test

# Run example
zig build example

# Run benchmarks
zig build benchmark

Performance

Zig Faker is designed for high performance with minimal memory allocations:

UUID Generation: Millions of operations per second
Email Generation: Millions of operations per second
Name Generation: Tens of millions of operations per second

Run zig build benchmark to see performance on your system.

Memory Management

Zig Faker follows Zig's explicit memory management philosophy:

Functions that return const strings (e.g., firstName(), city()) return pointers to static data - no deallocation needed
Functions that return dynamic strings (e.g., fullName(), email()) allocate memory - you must free the result

// No deallocation needed (const string)
const first = faker.person.firstName(.{});

// Must deallocate (dynamic string)
const full = try faker.person.fullName(.{});
defer allocator.free(full);

Examples

Generate User Profile

const profile = .{
    .name = try faker.person.fullName(.{ .prefix = true }),
    .email = try faker.internet.email(),
    .phone = try faker.phone.phoneNumber(),
    .address = try faker.address.fullAddress(),
    .company = try faker.company.name(),
    .job_title = faker.person.jobTitle(),
};

defer allocator.free(profile.name);
defer allocator.free(profile.email);
defer allocator.free(profile.phone);
defer allocator.free(profile.address);
defer allocator.free(profile.company);

Seed Database with Test Data

var faker = Faker.init(allocator, 12345, null); // Seeded for reproducibility

var users = std.ArrayList(User).init(allocator);
defer users.deinit();

for (0..100) |_| {
    const user = User{
        .name = try faker.person.fullName(.{}),
        .email = try faker.internet.email(),
        .phone = try faker.phone.phoneNumber(),
    };
    try users.append(user);
}

Generate Test Fixtures

test "user registration" {
    var faker = Faker.init(std.testing.allocator, null, null);

    const email = try faker.internet.email();
    defer std.testing.allocator.free(email);

    const password = try faker.internet.password(8, 16);
    defer std.testing.allocator.free(password);

    const result = try registerUser(email, password);
    try std.testing.expect(result.success);
}

Roadmap

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Acknowledgments

Inspired by ts-mocker - a blazing-fast TypeScript faker library.

Related Projects

ts-mocker - TypeScript/JavaScript version
@faker-js/faker - Popular JavaScript faker library

Food Module

// Food items
const dish = faker.food.dish();           // Pizza, Burger, Sushi, etc.
const ingredient = faker.food.ingredient(); // Tomato, Onion, Garlic, etc.
const fruit = faker.food.fruit();         // Apple, Banana, Orange, etc.
const vegetable = faker.food.vegetable(); // Carrot, Broccoli, etc.
const meat = faker.food.meat();           // Chicken, Beef, Pork, etc.
const spice = faker.food.spice();         // Pepper, Salt, Paprika, etc.

// Recipe name
const recipe = try faker.food.recipe();
defer allocator.free(recipe);

Animal Module

// Animal breeds and species
const dog = faker.animal.dog();           // Labrador, German Shepherd, etc.
const cat = faker.animal.cat();           // Persian, Maine Coon, etc.
const bird = faker.animal.bird();         // Sparrow, Robin, Eagle, etc.
const fish = faker.animal.fish();         // Goldfish, Koi, Betta, etc.
const animal_type = faker.animal.type_(); // Mammal, Bird, Fish, etc.

// Pet names
const pet_name = faker.animal.petName();  // Max, Bella, Charlie, etc.

Date Module

// Timestamps
const timestamp = faker.date.timestamp();    // Random Unix timestamp
const past_date = faker.date.past(30);      // Within last 30 days
const future_date = faker.date.future(30);  // Within next 30 days
const recent = faker.date.recent();         // Within last 7 days
const soon = faker.date.soon();             // Within next 7 days

// Date components
const weekday = faker.date.weekday();       // Monday, Tuesday, etc.
const month = faker.date.month();           // January, February, etc.

// Formatted dates
const date_str = try faker.date.dateString(); // 2024-03-15
defer allocator.free(date_str);

const time_str = try faker.date.timeString(); // 14:30:45
defer allocator.free(time_str);

const iso = try faker.date.iso8601();        // 2024-03-15T14:30:45Z
defer allocator.free(iso);

Number Module

// Basic numbers
const int_num = faker.number.int(1, 100);      // Random integer in range
const float_num = faker.number.float(0.0, 1.0); // Random float in range
const percent = faker.number.percentage(2);     // Random percentage

// Special numbers
const prime_num = faker.number.prime(100);      // Random prime <= 100
const even_num = faker.number.even(1, 100);     // Random even number
const odd_num = faker.number.odd(1, 100);       // Random odd number

// Number formats
const binary = try faker.number.binary(8);      // 10110101
defer allocator.free(binary);

const octal = try faker.number.octal(6);        // 742531
defer allocator.free(octal);

const hex = try faker.number.hexadecimal(8);    // a3f5c2d1
defer allocator.free(hex);

Color Module

// Color names
const color_name = faker.color.name();        // Red, Blue, Green, etc.
const css_color = faker.color.cssColor();     // aliceblue, antiquewhite, etc.

// Color formats
const hex_color = try faker.color.hex();      // #FF5733
defer allocator.free(hex_color);

const rgb = try faker.color.rgb();            // rgb(255, 87, 51)
defer allocator.free(rgb);

const rgba = try faker.color.rgba();          // rgba(255, 87, 51, 0.8)
defer allocator.free(rgba);

const hsl = try faker.color.hsl();            // hsl(120, 50%, 50%)
defer allocator.free(hsl);

const hsla = try faker.color.hsla();          // hsla(120, 50%, 50%, 0.8)
defer allocator.free(hsla);

// RGB array
const rgb_array = faker.color.rgbArray();     // [255, 87, 51]

Lorem Module

// Words
const word = faker.lorem.word();              // lorem, ipsum, dolor, etc.

const words = try faker.lorem.words(5);       // 5 random words
defer allocator.free(words);

// Sentences
const sentence = try faker.lorem.sentence();  // Random sentence with period
defer allocator.free(sentence);

const sentences = try faker.lorem.sentences(3); // 3 sentences
defer allocator.free(sentences);

// Paragraphs
const paragraph = try faker.lorem.paragraph(); // Random paragraph
defer allocator.free(paragraph);

const paragraphs = try faker.lorem.paragraphs(2); // 2 paragraphs
defer allocator.free(paragraphs);

// Other formats
const lines = try faker.lorem.lines(5);       // 5 lines of text
defer allocator.free(lines);

const slug = try faker.lorem.slug(3);         // lorem-ipsum-dolor
defer allocator.free(slug);

const text = try faker.lorem.text(100);       // ~100 characters of text
defer allocator.free(text);

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
benchmarks		benchmarks
examples		examples
src		src
.gitignore		.gitignore
HELPERS_GUIDE.md		HELPERS_GUIDE.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
README.md		README.md
REFACTORING_COMPLETE.md		REFACTORING_COMPLETE.md
build.zig		build.zig

Uh oh!

Uh oh!

zig-utils/zig-faker

Folders and files

Latest commit

History

Repository files navigation

Zig Faker

Features

Installation

Quick Start

API Reference

Person Module

Address Module

Company Module

Internet Module

Phone Module

String Module

Seeded Generation

Locale Support

Available Locales (55 Total)

Data Categories

Person

Address

Company

Internet

Phone

String Utilities

Building and Testing

Performance

Memory Management

Examples

Generate User Profile

Seed Database with Test Data

Generate Test Fixtures

Roadmap

Contributing

License

Acknowledgments

Related Projects

Food Module

Animal Module

Date Module

Number Module

Color Module

Lorem Module

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Languages