@fakeforge/core

FakeForge

Offline, deterministic fake-data generation for JavaScript and TypeScript.

FakeForge is a lightweight fake-data generation library for development, testing, prototyping, demos, fixtures, schema-driven data generation, and synthetic datasets.

It runs entirely locally and does not require a cloud service, API key, or network connection.

Features

• Deterministic, seeded data generation
• Country-aware fake data
• Person names
• Job titles
• Email addresses
• Usernames
• Phone numbers
• Addresses
• Companies
• Internet data
• UUID, ULID, and NanoID generation
• Dates and timestamps
• Numbers and booleans
• JSON export
• JSONL export
• CSV export
• SQL export
• Schema generation
• Nested object generation
• Relationship-aware generation
• Schema validation
• JSON Schema generation
• TypeScript schema generation
• C# schema generation
• SQL schema generation
• SQL insert generation
• Fully offline operation

---

Installation

Install FakeForge from npm:

npm install @fakeforge/core

FakeForge is distributed as an ES module and exposes its public API through the package root.

Basic Usage

import { FakeForge } from "@fakeforge/core";

const fake = FakeForge.create({
  seed: 12345,
});

const record = fake.record();

console.log(record.name.fullName());
console.log(record.internet.email());
console.log(record.phone.number());
console.log(record.address.city());
console.log(record.company.name());

Deterministic Generation

FakeForge uses a seeded pseudo-random generator.

Providing the same seed and making the same sequence of generator calls produces the same results.

const first = FakeForge.create({
  seed: 12345,
});

const second = FakeForge.create({
  seed: 12345,
});

const firstRecord = first.record();
const secondRecord = second.record();

console.log(firstRecord.name.fullName());
console.log(secondRecord.name.fullName());

For deterministic behavior, keep the following consistent:

• Seed
• Country/locale configuration
• Generator call order
• Generator arguments

FakeForge's deterministic behavior is designed for:

• Unit tests
• Integration tests
• Test fixtures
• CI/CD pipelines
• Development environments
• Prototyping
• Demonstrations
• Reproducible datasets
• Synthetic data generation

Locale / Country Generation

FakeForge supports locale-aware fake-data generation.

import { FakeForge } from "@fakeforge/core";

const fake = FakeForge.create({
  seed: 12345,
  country: "IN",
});

const record = fake.record();

console.log(record.resolvedCountry);
console.log(record.name.fullName());
console.log(record.phone.number());
console.log(record.address.city());
console.log(record.address.state());
console.log(record.address.postalCode());

resolvedCountry identifies the concrete country associated with the generated record.

Currently Implemented Locales

FakeForge 0.2.0 currently provides implemented locale datasets for:

Code	Country
US	United States
IN	India
GB	United Kingdom
CA	Canada
AU	Australia
DE	Germany
FR	France
JP	Japan
SG	Singapore
AE	United Arab Emirates

All locales listed above are available for locale-aware data generation.

Additional country metadata may exist internally, but metadata does not necessarily mean that a complete locale dataset is currently implemented.

Individual Generators

Person

record.name.firstName();
record.name.lastName();
record.name.fullName();
record.name.jobTitle();

Internet

record.internet.email();
record.internet.username();
record.internet.url();
record.internet.ipv4();
record.internet.macAddress();

Identifiers

record.string.uuid();
record.string.ulid();
record.string.nanoId();

Dates

record.date.date();
record.date.dateTime();
record.date.unixTimestamp();

Numbers

record.number.integer(1, 100);
record.number.float(0, 100);
record.boolean();

Phone

record.phone.number();

Address

record.address.street();
record.address.city();
record.address.state();
record.address.postalCode();
record.address.country();
record.address.fullAddress();

Company

record.company.name();

Exporters

FakeForge provides exporters for common data formats:

• JSON
• JSONL
• CSV
• SQL

import {
  exportJson,
  exportJsonl,
  exportCsv,
  exportSql,
} from "@fakeforge/core";

Schema Generation

FakeForge supports structured schema generation and schema-driven data generation.

Capabilities include:

• Flat schema generation
• Nested object generation
• Relationship-aware generation
• Schema validation
• JSON Schema generation
• TypeScript schema generation
• C# schema generation
• SQL schema generation
• CSV data generation
• SQL INSERT generation

The schema system is designed for applications that need to generate structured datasets from predefined schemas.

Relationships

FakeForge supports schema relationship definitions and relationship-aware generated data.

Relationship APIs are exposed as typed interfaces so applications can construct deterministic related datasets.

Schema Validation

Schemas can be validated before being used for generation.

This allows applications to detect invalid or unsupported schema definitions before generating data.

Error Handling

FakeForge exposes typed error helpers:

import {
  FakeForgeError,
  isFakeForgeError,
} from "@fakeforge/core";

Example:

try {
  // FakeForge operation
} catch (error) {
  if (isFakeForgeError(error)) {
    console.error(error.message);
  } else {
    throw error;
  }
}

TypeScript Support

FakeForge ships with TypeScript declaration files for type-safe development.

import {
  FakeForge,
  type FakeForgeOptions,
  type Locale,
} from "@fakeforge/core";

The package is intended for both JavaScript and TypeScript projects.

Offline Operation

FakeForge performs fake-data generation locally.

Generated values do not require a remote API.

No cloud service or API key is required.

This makes FakeForge suitable for:

• Unit tests
• Integration tests
• CI/CD pipelines
• Local development
• Test fixtures
• Database seeding
• API testing
• Prototyping
• Demonstrations
• Synthetic datasets
• Schema prototyping
• Reproducible test data

Synthetic Data

FakeForge generates synthetic data for development and testing purposes.

Generated values should not be assumed to represent real people, organizations, addresses, or other factual records.

Do not use generated data as a substitute for verified real-world information.

Deterministic Random Generation

FakeForge uses a seeded pseudo-random generator.

The same seed produces the same random sequence when the same sequence of operations is performed.

Example:

const first = FakeForge.create({
  seed: 12345,
});

const second = FakeForge.create({
  seed: 12345,
});

const a = first.record();
const b = second.record();

console.log(a.string.uuid());
console.log(b.string.uuid());

Deterministic generation is particularly useful for:

• Snapshot tests
• Unit tests
• Integration tests
• Test fixtures
• Database seed data
• Reproducible bug reports
• CI environments
• Development
• Demonstrations

API Overview

A typical FakeForge workflow is:

FakeForge.create()
        │
        ▼
    fake.record()
        │
        ├── name
        ├── internet
        ├── phone
        ├── address
        ├── company
        ├── number
        ├── string
        └── date

Example:

const fake = FakeForge.create({
  country: "IN",
  seed: 12345,
});

const record = fake.record();

const user = {
  name: record.name.fullName(),
  email: record.internet.email(),
  phone: record.phone.number(),
  city: record.address.city(),
  state: record.address.state(),
  company: record.company.name(),
};

TypeScript API Imports

The primary API is available from the package root:

import {
  FakeForge,
  FakeForgeError,
  isFakeForgeError,
  exportJson,
  exportJsonl,
  exportCsv,
  exportSql,
} from "@fakeforge/core";

Types can also be imported from the package:

import type {
  FakeForgeOptions,
  Locale,
} from "@fakeforge/core";

Package Information

Property	Value
Package	@fakeforge/core
Version	0.2.0
Language	JavaScript / TypeScript
Module	ES Module
Data generation	Local
Network required	No
API key required	No

License

FakeForge is distributed under the FakeForge Proprietary Free-Use License.

Commercial applications using FakeForge are permitted under the license.

Standalone redistribution, repackaging, modification, or distribution of FakeForge itself is restricted by the license.

See LICENSE for the complete license terms.

Repository

https://github.com/NavaidhInnovations/FakeForge