Arbitrary
Derives, samples, and checks generated values from Effect Schema.
Constructors
Combines Arbitraries into one Arbitrary whose generated value mirrors the input shape.
When to use
Use when you need to generate several independent values together.
Details
Accepts a tuple or array, an iterable, or a record of Arbitraries. Tuple positions and record keys are preserved in the generated value. Members are generated in a randomized internal order so recursive members share the generation budget fairly, while shrinking changes one member at a time.
Gotchas
Iterable inputs are consumed when all is called. If any member discards a generated root, the complete generated
value is discarded.
Signature
declare function all<Input extends Iterable<Arbitrary<any>, any, any> | Record<string, Arbitrary<any>>>(input: Input): Arbitrary<[Input] extends [readonly Array<Arbitrary<any>>] ? { [K in string | number | symbol]: [Input[K]] extends [Arbitrary<A>] ? A : never } : [Input] extends [Iterable<Arbitrary<A>, any, any>] ? Array<A> : [Input] extends [Record<string, Arbitrary<any>>] ? { [K in string | number | symbol]: [Input[K]] extends [Arbitrary<A>] ? A : never } : never>Creates an Arbitrary that always generates value and has no shrink candidates.
When to use
Use when a branch of dependent generation should produce an already constructed value.
Gotchas
Every generation returns the same value. Objects are not cloned, so properties must not mutate them.
See
- flatMap for selecting dependent Arbitraries
Signature
declare function Constant<A>(value: A): Arbitrary<A>Derives an Arbitrary from the decoded Type of a Schema.
When to use
Use when you want Schema-aware generation without exposing a third-party property-testing engine.
Details
When options.shrink is provided, generated roots still come from Schema derivation, while the callback defines the
complete shrink tree. Invalid candidates are skipped and count against maxShrinks without reaching the property.
Gotchas
Derivation is immediate and throws when the current unstable implementation cannot compile the Schema or prove a finite route through a recursive component.
A custom shrinker replaces Schema-derived shrinking. It is evaluated lazily after a property failure and must be synchronous, deterministic, terminating, and free of mutation.
Signature
declare function schema<S extends Constraint>(schema: S, options?: SchemaOptions<S["Type"]>): Arbitrary<S["Type"]>Converting
formatCheckFailure
Formats an unsuccessful property-check result as a diagnostic message, returning undefined for a passed result.
When to use
Use when integrating checkEffect with a test runner or another reporting interface.
Signature
declare function formatCheckFailure<A, E>(result: CheckResult<A, E>): string | undefinedErrors
SampleError interface
Describes sampling exhaustion before the requested number of values was generated.
Details
The effective seed can be passed to sampleEffect to reproduce the exhausted run, including when sampling
originally selected a seed from the Effect Random service.
Signature
interface SampleError { readonly _tag: "SampleError"; readonly discards: number; readonly generated: number; readonly seed: string | number;}Filtering
Keeps generated values and shrink candidates that satisfy a predicate or refinement.
When to use
Use when a condition cannot be expressed constructively by the source Schema or after values have been transformed.
Gotchas
Rejected generated values count against maxDiscards. Prefer Schema checks when possible because the Schema compiler
may generate matching values directly.
See
- filterMap for transforming and filtering simultaneously
Signature
declare const filter: { <A, B>(refinement: Refinement<A, B>): (self: Arbitrary<A>) => Arbitrary<B>; <A>(predicate: Predicate<A>): <B>(self: Arbitrary<B>) => Arbitrary<B>; <A, B>(self: Arbitrary<A>, refinement: Refinement<A, B>): Arbitrary<B>; <A>(self: Arbitrary<A>, predicate: Predicate<A>): Arbitrary<A>;}Transforms accepted generated values and discards rejected values.
When to use
Use when transformation and validation need to happen in one step after constructing an Arbitrary.
Gotchas
Failed filters discard generated roots and count against maxDiscards. Failures are not exposed in sampling or
checking results.
See
Signature
declare const filterMap: { <A, B, X>(f: Filter<A, B, X>): (self: Arbitrary<A>) => Arbitrary<B>; <A, B, X>(self: Arbitrary<A>, f: Filter<A, B, X>): Arbitrary<B>;}Guards
isArbitrary
Checks whether a value is an Arbitrary.
When to use
Use when accepting both Arbitrary values and other input descriptions.
Signature
declare function isArbitrary(u: unknown): u is Arbitrary<unknown>Mapping
Transforms every generated value and its shrink candidates.
When to use
Use when you want to derive generated values from an existing Arbitrary without changing its generation or shrink
structure.
Signature
declare const map: { <A, B>(f: (value: A) => B): (self: Arbitrary<A>) => Arbitrary<B>; <A, B>(self: Arbitrary<A>, f: (value: A) => B): Arbitrary<B>;}Models
Represents a pure description of values that can be generated and shrunk.
When to use
Use as the result of schema, Constant, and composition, and as the input to sampleEffect or checkEffect.
Details
Arbitraries implement Pipeable, so data-last combinators can be composed with .pipe(...).
Signature
interface Arbitrary<out A> extends Pipeable { readonly "~A": Covariant<A>; readonly "~effect/arbitrary/Arbitrary": "~effect/arbitrary/Arbitrary";}CheckOptions interface
Configures property checking, shrinking, and replay.
Details
size is the maximum local complexity scale. Checking starts with smaller values and grows to that size according
to completed runs; discarded attempts do not advance the progression. A single-run check uses the configured size.
Each unconstrained string, collection, or object property observes the current size independently. Recursive
branches instead consume one shared recursion allowance. Explicit Schema bounds and required members still apply.
maxShrinks bounds the number of shrink candidates inspected after the initial failure. Candidates rejected by a
Schema check, filter, filterMap, or dependent generation consume the same budget even though the property is not
evaluated. Candidates that produce a different failure class also consume the budget. When the budget is exhausted,
checking returns the best shrunk input found so far. The shrinks field in a Falsified result counts only
candidates that were accepted as smaller failures.
Gotchas
When replay is present, its recorded seed, attempt, size, and shrink path control the run. The runs, size,
maxDiscards, maxShrinks, and seed options are ignored.
Signature
interface CheckOptions { readonly maxDiscards?: number; readonly maxShrinks?: number; readonly replay?: string; readonly runs?: number; readonly seed?: string | number; readonly size?: number;}CheckResult type
Represents every ordinary outcome of property checking.
Details
Defects and fiber interruption are not converted to this data type and continue through the returned Effect.
Signature
type CheckResult<A, E> = Passed | Falsified<A, E> | Exhausted | ReplayMismatchReports that bounded generation discarded too many candidates.
Details
The effective seed can be passed to checkEffect to reproduce the exhausted run, including when checking
originally selected a seed from the Effect Random service.
Signature
interface Exhausted { readonly _tag: "Exhausted"; readonly discards: number; readonly runs: number; readonly seed: string | number;}Reports a generated failure and its shrunk input.
Details
initialInput is the generated value that first falsified the property. shrunkInput is the best failing value found
by the bounded shrink search and may be equal to initialInput.
runs counts main property evaluations through the falsifying evaluation. It excludes evaluations performed while
shrinking. A replay reports one run.
Signature
interface Falsified<out A, out E> { readonly _tag: "Falsified"; readonly discards: number; readonly failure: PropertyFailure<E>; readonly initialInput: A; readonly replay: string; readonly runs: number; readonly shrinks: number; readonly shrunkInput: A;}Reports that every requested property run passed.
Signature
interface Passed { readonly _tag: "Passed"; readonly discards: number; readonly runs: number;}PropertyError interface
Preserves a typed failure produced by an effectful property.
Signature
interface PropertyError<out E> { readonly _tag: "PropertyError"; readonly error: E;}PropertyFailure type
Represents the reason a property was falsified.
Signature
type PropertyFailure<E> = ReturnedFalse | PropertyError<E>Opaque string token that replays a falsification and its complete shrink path.
When to use
Use with CheckOptions.replay to copy, store, and reproduce a Falsified result from the same
implementation.
Details
The token records whether the property returned false or failed its Effect, but does not record a typed error value
or input fingerprint.
Gotchas
Replay compatibility is not guaranteed across releases of this unstable module.
Signature
type Replay = stringReplayMismatch interface
Reports that replay coordinates no longer reproduce the recorded failure class.
Details
PropertyPassedmeans that the regenerated root passed.ShrinkPassedmeans that the root switched failure class, or that a recorded shrink either passed or switched failure class.
Signature
interface ReplayMismatch { readonly _tag: "ReplayMismatch"; readonly reason: "AttemptDiscarded" | "PropertyPassed" | "ShrinkPathUnavailable" | "ShrinkPassed";}ReturnedFalse interface
Identifies a property that returned false.
Signature
interface ReturnedFalse { readonly _tag: "ReturnedFalse";}SampleOptions interface
Configures direct sampling from an Arbitrary.
Details
size is a local complexity scale, not a global bound on the complete value. Each unconstrained string, collection,
or object property observes the same size independently, while recursive branches share one recursion allowance.
Explicit Schema minima and required members are still honored, while explicit maxima clamp generation.
Signature
interface SampleOptions { readonly count?: number; readonly maxDiscards?: number; readonly seed?: string | number; readonly size?: number;}SchemaOptions interface
Configures Schema-derived generation.
Details
shrink returns the immediate semantic simplifications of a failing value. Each returned candidate is validated
against the decoded side of the original Schema before it can reach the property.
Signature
interface SchemaOptions<A> { readonly shrink?: (value: A) => readonly Array<A>;}Running
checkEffect
Checks a pure or effectful property and shrinks the first falsification.
When to use
Use when you want deterministic, interruptible property checking with typed property failures and replay.
Details
Returning false and failing an Effect are shrinkable falsifications. Shrinking preserves which of these two
failure classes caused the initial falsification. Typed error values may change while shrinking and are not compared
for equality. Defects and interruption continue through the returned Effect instead of becoming CheckResult
values.
Gotchas
Properties must treat generated values as immutable. The runner does not clone values before evaluation, so mutation can change reported shrunk inputs or interfere with shrinking and replay.
A property must also produce the same outcome for the same input and initial environment. The runner may evaluate it repeatedly and does not restore mutable services between evaluations. Stateful properties should acquire and release an independent fixture inside each evaluation.
Signature
declare function checkEffect<A, E = never, R = never>(self: Arbitrary<A>, property: (value: A) => boolean | Effect<boolean, E, R>, options?: CheckOptions): Effect<CheckResult<A, E>, never, R>sampleEffect
Generates a bounded collection of values from an Arbitrary.
When to use
Use when you need generated examples without running a property.
Signature
declare function sampleEffect<A>(self: Arbitrary<A>, options?: SampleOptions): Effect<readonly Array<A>, SampleError>Sequencing
Sequentially selects an Arbitrary from a generated value.
When to use
Use when the domain or shape of a generated value depends on another generated value.
Details
Shrinking first tries smaller source values and regenerates their dependent Arbitraries. It then shrinks the selected dependent value. After a dependent shrink is selected, source shrinking is closed for that branch.
Gotchas
The callback must be synchronous, deterministic, and terminating. It can be evaluated again during shrinking and replay. Deriving a Schema inside the callback also repeats that derivation, so precompile finite dependent Arbitraries when possible.
See
Signature
declare const flatMap: { <A, B>(f: (value: A) => Arbitrary<B>): (self: Arbitrary<A>) => Arbitrary<B>; <A, B>(self: Arbitrary<A>, f: (value: A) => Arbitrary<B>): Arbitrary<B>;}