Schema to Arbitrary

The Arbitrary.make function allows for the creation of random values that align with a specific Schema<A, I, R>. This function returns an Arbitrary<A> from the fast-check library, which is particularly useful for generating random test data that adheres to the defined schema constraints.

Example (Generating Arbitrary Data for a Schema)

1
import { Arbitrary, FastCheck, Schema } from "effect"
2

3
// Define a Person schema with constraints
4
const Person = Schema.Struct({
5
  name: Schema.NonEmptyString,
6
  age: Schema.Int.pipe(Schema.between(1, 80)),
7
})
8

9
// Create an Arbitrary based on the schema
10
const arb = Arbitrary.make(Person)
11

12
// Generate random samples from the Arbitrary
13
console.log(FastCheck.sample(arb, 2))
14
/*
15
Example Output:
16
[ { name: 'q r', age: 3 }, { name: '&|', age: 6 } ]
17
*/

To make the output more realistic, see the Customizing Arbitrary Data Generation section.

Filters

When generating random values, Arbitrary tries to follow the schema’s constraints. It uses the most appropriate fast-check primitives and applies constraints if the primitive supports them.

For instance, if you define an age property as:

Schema.Int.pipe(Schema.between(1, 80))

the arbitrary generation will use:

FastCheck.integer({ min: 1, max: 80 })

to produce values within that range.

Patterns

To generate efficient arbitraries for strings that must match a certain pattern, use the Schema.pattern filter instead of writing a custom filter:

Example (Using Schema.pattern for Pattern Constraints)

1
import { Schema } from "effect"
2

3
// ❌ Without using Schema.pattern (less efficient)
4
const Bad = Schema.String.pipe(Schema.filter((s) => /^[a-z]+$/.test(s)))
5

6
// ✅ Using Schema.pattern (more efficient)
7
const Good = Schema.String.pipe(Schema.pattern(/^[a-z]+$/))

By using Schema.pattern, arbitrary generation will rely on FastCheck.stringMatching(regexp), which is more efficient and directly aligned with the defined pattern.

When multiple patterns are used, they are combined into a union. For example:

1
(?:${pattern1})|(?:${pattern2})

This approach ensures all patterns have an equal chance of generating values when using FastCheck.stringMatching.

Transformations and Arbitrary Generation

When generating arbitrary data, it is important to understand how transformations and filters are handled within a schema:

Example (Filters and Transformations)

1
import { Arbitrary, FastCheck, Schema } from "effect"
2

3
// Schema with filters before the transformation
4
const schema1 = Schema.compose(Schema.NonEmptyString, Schema.Trim).pipe(Schema.maxLength(500))
5

6
// May produce empty strings due to ignored NonEmpty filter
7
console.log(FastCheck.sample(Arbitrary.make(schema1), 2))
8
/*
9
Example Output:
10
[ '', '"Ry' ]
11
*/
12

13
// Schema with filters applied after transformations
14
const schema2 = Schema.Trim.pipe(Schema.nonEmptyString(), Schema.maxLength(500))
15

16
// Adheres to all filters, avoiding empty strings
17
console.log(FastCheck.sample(Arbitrary.make(schema2), 2))
18
/*
19
Example Output:
20
[ ']H+MPXgZKz', 'SNS|waP~\\' ]
21
*/

Explanation:

schema1: Takes into account Schema.maxLength(500) since it is applied after the Schema.Trim transformation, but ignores the Schema.NonEmptyString as it precedes the transformations.
schema2: Adheres fully to all filters because they are correctly sequenced after transformations, preventing the generation of undesired data.

Best Practices

To ensure consistent and valid arbitrary data generation, follow these guidelines:

Apply Filters First: Define filters for the initial type (I).
Apply Transformations: Add transformations to convert the data.
Apply Final Filters: Use filters for the transformed type (A).

This setup ensures that each stage of data processing is precise and well-defined.

Example (Avoid Mixed Filters and Transformations)

Avoid haphazard combinations of transformations and filters:

1
import { Schema } from "effect"
2

3
// Less optimal approach: Mixing transformations and filters
4
const problematic = Schema.compose(Schema.Lowercase, Schema.Trim)

Prefer a structured approach by separating transformation steps from filter applications:

Example (Preferred Structured Approach)

1
import { Schema } from "effect"
2

3
// Recommended: Separate transformations and filters
4
const improved = Schema.transform(
5
  Schema.String,
6
  Schema.String.pipe(Schema.trimmed(), Schema.lowercased()),
7
  {
8
    strict: true,
9
    decode: (s) => s.trim().toLowerCase(),
10
    encode: (s) => s,
11
  },
12
)

Customizing Arbitrary Data Generation

You can customize how arbitrary data is generated using the arbitrary annotation in schema definitions.

Example (Custom Arbitrary Generator)

1
import { Arbitrary, FastCheck, Schema } from "effect"
2

3
const Name = Schema.NonEmptyString.annotations({
4
  arbitrary: () => (fc) => fc.constantFrom("Alice Johnson", "Dante Howell", "Marta Reyes"),
5
})
6

7
const Age = Schema.Int.pipe(Schema.between(1, 80))
8

9
const Person = Schema.Struct({
10
  name: Name,
11
  age: Age,
12
})
13

14
const arb = Arbitrary.make(Person)
15

16
console.log(FastCheck.sample(arb, 2))
17
/*
18
Example Output:
19
[ { name: 'Dante Howell', age: 6 }, { name: 'Marta Reyes', age: 53 } ]
20
*/

The annotation allows access the complete export of the fast-check library (fc). This setup enables you to return an Arbitrary that precisely generates the type of data desired.

Integration with Fake Data Generators

When using mocking libraries like @faker-js/faker, you can combine them with fast-check to generate realistic data for testing purposes.

Example (Integrating with Faker)

1
import { Arbitrary, FastCheck, Schema } from "effect"
2
import { faker } from "@faker-js/faker"
3

4
const Name = Schema.NonEmptyString.annotations({
5
  arbitrary: () => (fc) =>
6
    fc.constant(null).map(() => {
7
      // Each time the arbitrary is sampled, faker generates a new name
8
      return faker.person.fullName()
9
    }),
10
})
11

12
const Age = Schema.Int.pipe(Schema.between(1, 80))
13

14
const Person = Schema.Struct({
15
  name: Name,
16
  age: Age,
17
})
18

19
const arb = Arbitrary.make(Person)
20

21
console.log(FastCheck.sample(arb, 2))
22
/*
23
Example Output:
24
[
25
  { name: 'Henry Dietrich', age: 68 },
26
  { name: 'Lucas Haag', age: 52 }
27
]
28
*/