Faker Provider

Use the Faker provider when you want deterministic test fixtures, seeded datasets, and correlated fake identities without leaving Rank. For runnable examples, start with Test Fixtures and Faker Dataset.

How providers work

Providers are out-of-process extensions that expose typed functions to Rank programs under a namespace. The compiler spawns the provider process, type-checks calls against the manifest's declared schemas, and exchanges values over a JSON-line stdio protocol.

From a Rank program's point of view, a provider looks like any other import:

use faker::{ Generate, UUID }

The faker namespace is backed by the @rank-lang/plugin-faker package. Register it in rank.toml using the npm registry:

[providers]
faker = { registry = "npm", package = "@rank-lang/plugin-faker", version = "0.1.0" }

On the first run, Rank fetches and caches the package automatically and writes a rank.lock file. Subsequent runs reuse the cache. No separate npm install step is needed.

The provider is pure — it declares no capabilities — so no --allow-provider-capability flag is needed at the call site.

Providers can be distributed through npm the same way as @rank-lang/plugin-faker; see the Provider authoring guide for the publish workflow.

---

Faker

@rank-lang/plugin-faker is a first-party provider package that ships alongside Rank. It is not built into the compiler — it is a separate npm package that must be registered in your project's rank.toml like any other provider. Once registered, it exposes its exports through use faker.

The provider is deterministic by construction. Every generated value is derived from explicit inputs instead of ambient randomness.

Exports

Export	Description
faker::Generate<T>	Generate one T from a typed recipe
faker::UUID {}	Generate a UUID string
faker::Int { min, max, multipleOf? }	Generate an integer in a bounded range
faker::Boolean { probability? }	Generate a boolean with optional weighting
faker::DateTime { ... }	Generate a Time::Instant value
faker::Person { sex? }	Declare a correlated person scope
faker::Location {}	Declare a correlated location scope
faker::types::Spec<T>	Recipe type for composing markers and nested structures

faker::Generate<T>

The central export. Accepts a spec recipe, a seed, and optional controls.

Determinism Controls

faker::Generate<T> accepts these core inputs:

• seed: required base seed
• itemKey: optional deterministic variation input for repeated generation
• locale: optional Faker locale such as en_US
• refDate: required only when relative faker::DateTime recipes are used

Reusing the same (spec, seed, itemKey, locale, refDate) tuple replays identically.

Correlated Scopes

faker::Person and faker::Location are declarative recipe scopes, not sampled runtime objects.

Within one generated item, repeated projections from the same scope stay coherent:

use faker::{ Generate, Person, UUID }
use faker::types::{ Spec }

User = Object {
  id: string,
  first: string,
  firstAgain: string,
}

person = Person {
  sex: `female`,
}

spec: Spec<User> = {
  id: UUID {},
  first: person.firstName,
  firstAgain: person.firstName,
}

pub main = || Generate<User> {
  spec,
  seed: 123,
  itemKey: 0,
  locale: `en_US`,
}

In this example, first and firstAgain always match within one generated item.

Repeated Generation

Rank intentionally keeps repeated generation in ordinary collection composition around singular faker::Generate<T> calls:

use faker::{ Generate, UUID }
use faker::types::{ Spec }
use std::collections::{ map }
use std::list::{ range }

User = Object {
  id: string,
}

spec: Spec<User> = {
  id: UUID {},
}

seed = 123

pub main = || range(0, 3)
  |> map(|_, ctx| Generate<User> {
       spec,
       seed,
       itemKey: ctx.index,
       locale: `en_US`,
     })

Validation Behavior

• malformed Faker marker parameters fail during evaluation with provider diagnostics
• unsupported markers nested inside larger specs are rejected during recursive materialization
• generated scalar values participate in ordinary Rank validation flows such as @unique(group: ...)

Deferred Items

The current v1 boundary deliberately excludes a few features:

• probabilistic structural omission helpers inside faker::Spec<T>
• collection-scoped uniqueness helpers such as faker::Unique
• a broader faker::DateTime surface beyond the current bounded and relative forms
• exact structural projection from T into the recipe type surface beyond the current recursive T | SpecValue compromise

For the implementation plan and remaining deferred work, see the expansion plan in plan/expansions/FAKER_PLUGIN.md.