DataForger.Abstractions 0.1.0

DataForger

A lightweight, extensible, enterprise-ready synthetic test data generation library for .NET.

DataForger creates deterministic, country-specific, clearly synthetic data — no real personal information is ever used, no network or file access happens at runtime, and the same seed always produces the same dataset. It targets .NET Standard 2.0 and is thread-safe and DI-friendly.

using DataForger;

var customer = Forge.ForCountry(Country.PT).WithSeed(1234).Create<Customer>();

var customers = Forge.ForCountry(Country.BR).WithSeed(42).Create<Customer>(1000);

Why DataForger?

• Deterministic — the same seed + country + entity type always yields the same data. Dates are anchored to a fixed epoch (2025-01-01 UTC), so results never depend on the wall clock and are stable across .NET runtime versions.
• Country-aware — built-in providers for Portugal, Spain, United Kingdom, France, Germany, United States and Brazil: names, phone formats, postal codes and country-validated tax identifiers (NIF/NIPC, DNI/CIF, CPF/CNPJ, SSN-like, EIN, SIREN, ...).
• No real PII — names are curated common names, e-mails use RFC 2606 reserved domains (example.com, example.net, example.org), and US SSN-like numbers use the never-issued 9xx area.
• Extensible — implement IDataGenerator<T> or ICountryDataProvider and plug into the fluent API; optional provider capabilities (e.g. IPersonTaxIdentifierProvider) can grow without breaking changes.
• Enterprise-ready — strong-named, XML-documented, StyleCop-clean, SourceLink-enabled, zero compiler warnings, and a CI pipeline in this repository.

Getting started

1. Reference the packages from your project (or add project references to src/):

   • DataForger — the fluent entry point.
   • DataForger.Abstractions — entities, interfaces, enums (reference this in extension libraries).
   • DataForger.CountryProviders — the built-in country data providers.
   • DataForger.Generators — the built-in entity generators.
   • DataForger.Extensions — optional extension methods (e.g. WithSeed(string)).

2. Build a Forge for a country and generate:

// Single entity
var person = Forge.ForCountry(Country.PT).Create<Person>();

// Deterministic batch
var contracts = Forge.ForCountry(Country.UK).WithSeed(2024).Create<Contract>(500);

// Text seed via the extensions package
var products = Forge.ForCountry(Country.DE).WithSeed("demo-fixture").Create<Product>(100);

3. Use the entities in your tests, demos or development databases.

Note on the entry point name. The original specification used DataForger.ForCountry(...), but C# forbids a type and a namespace from sharing a name, so the facade is the static class Forge in the DataForger namespace: Forge.ForCountry(Country.PT). Everything else in the public API matches the specification.

Built-in entities

See docs/api.md for the full public API surface.

Quick API reference

Forge.ForCountry(Country country)                                          // entry point
Forge.ForCountry(Country country, ICountryDataProviderRegistry registry)   // custom providers
forge.WithSeed(int seed)                                                   // deterministic
forge.WithSeed(string seed)                                                // extension: FNV-1a hash
forge.Register<TGenerator>()                                               // custom generator
forge.Create<T>()                                                          // single entity
forge.Create<T>(int count)                                                 // IReadOnlyCollection<T>

Thread safety

Forge instances are safe to share across threads: the generator registry is a ConcurrentDictionary, the seed is read/written atomically, and every generation call receives a fresh, private context with its own random source. Configure the instance (seed, registrations) before generating from multiple threads.

Documentation

• Architecture overview
• Public API reference
• Extending DataForger — custom generators, providers and capabilities
• Security considerations — threat model, misuse, validation, determinism
• Contributing

Building and testing

dotnet build DataForger.slnx
dotnet test DataForger.slnx
dotnet pack DataForger.slnx -c Release

Packages land in artifacts/packages/.

Icons

Package icons: <a href="https://www.flaticon.com/free-icons/forging" title="forging icons">Forging icons created by Nikita Golubev - Flaticon</a>

License

MIT — see LICENSE.