Schema to Arbitrary

An Arbitrary<A> describes how to generate values of type A and how to shrink a failing value.

Its main use is property-based testing. Instead of checking a rule against a few examples chosen by hand, the runner checks it against many generated inputs. If one input breaks the rule, shrinking searches for a smaller counterexample, which usually makes the bug easier to understand and reproduce.

When an Arbitrary comes from a Schema, its generated inputs conform to the Schema’s decoded Type. Sampling lets you inspect those inputs. Property checks let you verify rules such as encode/decode round trips across many values.

Arbitrary.schema derives a native Arbitrary from a Schema’s decoded Type. Use it to inspect generated values or run property checks with shrinking and replay.

Import the module from effect/unstable/arbitrary:

import { Arbitrary } from "effect/unstable/arbitrary"

Generating values

Call Arbitrary.schema to derive an Arbitrary, then pass it to Arbitrary.sampleEffect:

Example (Generating Values from a Schema)

1
import { Effect, Schema } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
const Person = Schema.Struct({
5
  name: Schema.NonEmptyString,
6
  age: Schema.Int.check(Schema.isBetween({ minimum: 18, maximum: 80 })),
7
})
8

9
const arbitrary = Arbitrary.schema(Person)
10

11
const samples = await Effect.runPromise(
12
  Arbitrary.sampleEffect(arbitrary, {
13
    count: 10,
14
    seed: 1,
15
  }),
16
)
17

18
samples.every(({ name, age }) => name.length > 0 && age >= 18 && age <= 80) // => true

sampleEffect accepts these options:

size is not a global length limit. Each collection or property observes it independently. Explicit Schema bounds still apply.

Constraints and filters

Built-in Schema checks include generation constraints where possible. The Arbitrary compiler uses them to construct matching values instead of repeatedly generating and rejecting unrelated values.

Example (Generating Values with Built-In Constraints)

1
import { Effect, Schema } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
const Username = Schema.String.check(
5
  Schema.isMinLength(3),
6
  Schema.isMaxLength(20),
7
  Schema.isPattern(/^[a-z0-9_]+$/),
8
)
9

10
const samples = await Effect.runPromise(
11
  Arbitrary.sampleEffect(Arbitrary.schema(Username), {
12
    count: 20,
13
    seed: 1,
14
  }),
15
)
16

17
samples.every(
18
  (value) =>
19
    value.length >= 3 && value.length <= 20 && /^[a-z0-9_]+$/.test(value),
20
) // => true

The compiler understands built-in bounds for numbers, lengths, collection sizes, object property counts, regular expressions, and uniqueness. It still runs every Schema filter against generated roots and shrink candidates.

Custom filter constraints

A custom filter can expose constructive information through the arbitraryConstraint annotation. The filter remains the final check.

Example (Describing a Custom Numeric Constraint)

1
import { Effect, Order, Schema } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
const isPort = Schema.makeFilter(
5
  (value: number) => Number.isInteger(value) && value >= 0 && value <= 65_535,
6
  {
7
    expected: "a TCP port",
8
    arbitraryConstraint: {
9
      order: Order.Number,
10
      minimum: 0,
11
      maximum: 65_535,
12
      number: "integer",
13
    },
14
  },
15
)
16

17
const Port = Schema.Number.check(isPort)
18

19
const ports = await Effect.runPromise(
20
  Arbitrary.sampleEffect(Arbitrary.schema(Port), {
21
    count: 20,
22
    seed: 1,
23
  }),
24
)
25

26
ports.every((port) => Number.isInteger(port) && port >= 0 && port <= 65_535) // => true

Opaque filters and discarded values

A custom filter without arbitraryConstraint is still enforced, but it cannot guide construction. Rejected candidates consume the discard budget. Prefer built-in checks or constructive constraints when valid values are rare.

sampleEffect fails with SampleError after too many discards. Property checks return an Exhausted result instead. Both include the effective seed so the run can be reproduced.

Transformations and decoded values

Arbitrary.schema generates a Schema’s decoded Type, not its Encoded value. For a codec, derivation follows the type-side Schema and its constraints.

Example (Generating the Decoded Side of a Codec)

1
import { Effect, Schema } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
const samples = await Effect.runPromise(
5
  Arbitrary.sampleEffect(Arbitrary.schema(Schema.FiniteFromString), {
6
    count: 20,
7
    seed: 1,
8
  }),
9
)
10

11
samples.every((value) => typeof value === "number" && Number.isFinite(value)) // => true

To generate encoded values, derive from Schema.toEncoded(schema) instead.

Checking properties

Arbitrary.checkEffect evaluates a pure or effectful property. It stops at the first falsification, shrinks the generated value, and returns a CheckResult.

Example (Shrinking and Replaying a Failure)

1
import { Effect, Schema } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
const numbers = Arbitrary.schema(
5
  Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 100 })),
6
)
7

8
const result = await Effect.runPromise(
9
  Arbitrary.checkEffect(numbers, (value) => value < 5, {
10
    runs: 100,
11
    seed: 42,
12
  }),
13
)
14

15
if (result._tag !== "Falsified") {
16
  throw new Error("Expected a falsification")
17
}
18

19
result.shrunkInput // => 5
20
Arbitrary.formatCheckFailure(result)?.includes("Shrunk input: 5") // => true
21

22
const replayed = await Effect.runPromise(
23
  Arbitrary.checkEffect(numbers, (value) => value < 5, {
24
    replay: result.replay,
25
  }),
26
)
27

28
replayed._tag // => "Falsified"

A property may return boolean or Effect<boolean, E, R>. Returning false and failing the Effect are both shrinkable falsifications. Defects and interruption remain failures of the returned Effect.

CheckResult has four cases:

Use Arbitrary.formatCheckFailure when integrating with a test runner. It returns undefined for Passed and a diagnostic message for every other case.

When replay is present, the token controls the seed, attempt, size, and shrink path. Other checking options are ignored.

Composing arbitraries

The native module can construct generators that are not described by one Schema node.

Example (Mapping and Combining Arbitraries)

1
import { Effect, Schema } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
const reverse = (value: string) => Array.from(value).reverse().join("")
5

6
const palindrome = Arbitrary.schema(Schema.String).pipe(
7
  Arbitrary.map((half) => `${half}${reverse(half)}`),
8
)
9

10
const profile = Arbitrary.all({
11
  name: Arbitrary.schema(Schema.Literals(["Alice", "Dante", "Marta"])),
12
  bio: palindrome,
13
})
14

15
const samples = await Effect.runPromise(
16
  Arbitrary.sampleEffect(profile, { count: 20, seed: 1 }),
17
)
18

19
samples.every(({ bio }) => bio === reverse(bio)) // => true

The module provides these combinators:

• Constant always generates the supplied value and has no shrink candidates.
• map transforms generated values and their shrink candidates.
• filter keeps values that satisfy a predicate or refinement.
• filterMap transforms accepted values and discards rejected ones.
• flatMap selects a dependent Arbitrary from a generated value.
• all combines a tuple, iterable, or record of Arbitraries.

Rejected values from filter and filterMap consume the discard budget. Use a Schema constraint when it can describe the valid domain directly.

Custom shrinking

Pass a shrink function to Arbitrary.schema when a type has a simpler domain specific reduction strategy.

Example (Replacing Schema-Derived Shrinking)

1
import { Effect, Schema } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
const Count = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 100 }))
5

6
const count = Arbitrary.schema(Count, {
7
  shrink: (value) => (value === 0 ? [] : [Math.floor(value / 2)]),
8
})
9

10
const result = await Effect.runPromise(
11
  Arbitrary.checkEffect(count, (value) => value === 0, {
12
    runs: 100,
13
    seed: 42,
14
  }),
15
)
16

17
if (result._tag !== "Falsified") {
18
  throw new Error("Expected a falsification")
19
}
20

21
result.shrunkInput // => 1

The custom function replaces Schema-derived shrinking but does not change root generation. The runner validates every shrink candidate against Count before passing it to the property. A shrink function must be synchronous, deterministic, terminating, and free of mutation.

Custom declarations

The compiler cannot derive an Arbitrary for an opaque declaration unless it has a generatable representation. Add toCodecArbitrary to describe that representation and how to decode it into the declared type.

Example (Generating an Opaque Class)

1
import { Effect, Schema, SchemaGetter } from "effect"
2
import { Arbitrary } from "effect/unstable/arbitrary"
3

4
class UserId {
5
  constructor(readonly value: string) {}
6
}
7

8
const UserIdSchema = Schema.declare(
9
  (input: unknown): input is UserId => input instanceof UserId,
10
  {
11
    expected: "UserId",
12
    toCodecArbitrary: () =>
13
      Schema.link<UserId>()(
14
        Schema.String.check(Schema.isPattern(/^user_[a-z]+$/)),
15
        {
16
          decode: SchemaGetter.transform((value) => new UserId(value)),
17
          encode: SchemaGetter.transform((id) => id.value),
18
        },
19
      ),
20
  },
21
)
22

23
const ids = await Effect.runPromise(
24
  Arbitrary.sampleEffect(Arbitrary.schema(UserIdSchema), {
25
    count: 5,
26
    seed: 1,
27
  }),
28
)
29

30
ids.every((id) => id instanceof UserId && /^user_[a-z]+$/.test(id.value)) // => true

The annotation callback also receives decoded type-parameter schemas and any normalized generation constraint. This API is experimental while native Arbitrary remains unstable.

Derivation failures

Arbitrary.schema compiles the Schema immediately. It throws when it encounters an impossible constraint, Schema.Never, an unsupported declaration, or a recursive Schema without a finite generation path.

Generation can still discard candidates at runtime. This happens with opaque filters, partial declaration transformations, filter, and filterMap. Control this work with maxDiscards.

Properties and Arbitrary callbacks must treat generated values as immutable. Shrinking and replay may evaluate them more than once.