@rank-lang/plugin-faker

First-party Faker provider package for Rank.

Full documentation →

Install

npm install @rank-lang/plugin-faker

Rank programs consume the provider through the faker namespace:

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

Determinism model

faker::Generate is deterministic for the tuple (seed, itemKey, spec).

• seed is required and initializes the provider RNG.
• itemKey is optional and derives a stable per-item sub-seed.
• locale selects the Faker locale and defaults to en_US.
• refDate sets the default reference instant used by relative date recipes.

Arrays and objects are traversed recursively. Primitive values (string, number, bool, null) are copied through unchanged.

Example

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

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

person = Person {}

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

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

Within one generated item, repeated projections from the same scope stay correlated. Reusing the same input reproduces the same output.

API reference

faker::Generate<T>

Materializes a recipe tree into a concrete Rank value of type T.

Input shape:

| Field | Type | Required | Notes | | --- | --- | --- | --- | | spec | faker::types::Spec<T> | yes | Recipe tree to materialize | | seed | number | yes | Base deterministic seed | | itemKey | number | no | Optional per-item stable discriminator | | locale | string | no | Faker locale name, defaults to en_US | | refDate | std::Time::Instant | no | Required when using relative faker::DateTime recipes |

Primitive recipe constructors

faker::UUID {}

Produces a UUID string.

faker::Int { min, max, multipleOf? }

Produces an integer in the inclusive range [min, max].

• min and max must be whole numbers.
• min <= max is required.
• multipleOf, when present, must be a whole number greater than 0.

faker::Boolean { probability? }

Produces a boolean.

• probability, when present, must be between 0 and 1 inclusive.

faker::DateTime { ... }

Produces a std::Time::Instant.

Supported shapes:

• bounded range: { from, to }
• relative recent: { recent: { days? } }
• relative soon: { soon: { days? } }
• relative past: { past: { years? } }
• relative future: { future: { years? } }

Rules:

• bounded ranges must provide both from and to
• from must be earlier than to
• bounded and relative shapes cannot be mixed
• exactly one relative shape must be provided when not using a bounded range
• relative shapes require refDate on Generate
• days and years default to 1 and must be whole numbers greater than 0

Correlated scopes

faker::Person and faker::Location do not directly materialize into output values. They create scope objects whose projected fields can be embedded in spec.

faker::Person { sex? }

Config:

| Field | Type | Required | Notes | | --- | --- | --- | --- | | sex | female or male | no | When omitted, Faker chooses a sex type |

Available projections:

• person.firstName: string
• person.lastName: string
• person.email: string
• person.age: number
• person.address: Object { street, city, country }

All projections from the same person scope share a single generated identity.

faker::Location {}

Available projections:

• location.street: string
• location.city: string
• location.region: string
• location.postalCode: string
• location.country: string

All projections from the same location scope share a single generated location.

faker::types

Provider-owned types live under faker::types.

Important exported types:

• Spec<T>: recursive recipe tree accepted by Generate<T>
• GenerateInput<T>: full Generate<T> input object
• marker/config types for UUID, Int, Boolean, DateTime, Person, and Location
• projection types for correlated person and location fields

At runtime, Spec<T> may contain:

• plain Rank scalar values
• nested arrays and objects
• primitive recipe markers
• person or location projections

Validation and errors

Invalid input is reported as InvalidInput provider errors. Common causes include:

• unknown or empty locale values
• malformed refDate values
• invalid integer or boolean config
• invalid DateTime shape combinations
• embedding Person {} or Location {} directly instead of one of their projections

Development

npm run build -w @rank-lang/plugin-faker
npm run test -w @rank-lang/plugin-faker
npm run typecheck -w @rank-lang/plugin-faker

Publishing

Build the package first, then publish from the workspace root:

npm run build -w @rank-lang/plugin-faker
npm publish -w @rank-lang/plugin-faker

This package currently relies on normal npm runtime dependencies rather than a fully bundled standalone provider artifact. In particular, it depends on @faker-js/faker and @rank-lang/provider-runtime at runtime.