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)

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

// Define a Person schema with constraints
const Person = Schema.Struct({
  name: Schema.NonEmptyString,
  age: Schema.NumberFromString.pipe(Schema.int(), Schema.between(0, 200))
})

// Create an Arbitrary based on the schema
const PersonArbitraryType = Arbitrary.make(Person)

// Generate random samples from the Arbitrary
console.log(FastCheck.sample(PersonArbitraryType, 2))
/*
Example Output:
[ { name: 'q r', age: 1 }, { name: '&|', age: 133 } ]
*/

Access FastCheck API

The entirety of fast-check’s API is accessible via the FastCheck export, allowing direct use of all its functionalities within your projects.

Transformations and Arbitrary Generation

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

Filters Ignored

Filters applied before the last transformation in the transformation chain are not considered during the generation of arbitrary data.

Example (Filters and Transformations)

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

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

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

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

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

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:

1. Apply Filters First: Define filters for the initial type (I).
2. Apply Transformations: Add transformations to convert the data.
3. 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:

import { Schema } from "effect"

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

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

Example (Preferred Structured Approach)

import { Schema } from "effect"

// Recommended: Separate transformations and filters
const improved = Schema.transform(
  Schema.String,
  Schema.String.pipe(Schema.trimmed(), Schema.lowercased()),
  {
    strict: true,
    decode: (s) => s.trim().toLowerCase(),
    encode: (s) => s
  }
)

Customizing Arbitrary Data Generation

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

Example (Custom Arbitrary Generator)

import { Schema } from "effect"

// Schema with a custom generator for natural numbers
const schema = Schema.Number.annotations({
  arbitrary: (/**typeParameters**/) => (fc) => fc.nat()
})

The annotation allows access to any type parameters via the first argument (typeParameters) and 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.

Customization May Disrupt Filters

Customizing a schema can disrupt previously applied filters. Filters set after the customization will remain effective, while those applied before will be disregarded.

Example (Handling Filters with Custom Generators)

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

// Custom generator that overrides the 'positive' filter
const problematic = Schema.Number.pipe(Schema.positive()).annotations({
  arbitrary: () => (fc) => fc.integer()
})

console.log(FastCheck.sample(Arbitrary.make(problematic), 2))
/*
Example Output:
[ -1600163302, -6 ]
*/

// Custom generator with 'positive' filter applied after the customization
const improved = Schema.Number.annotations({
  arbitrary: () => (fc) => fc.integer()
}).pipe(Schema.positive())

console.log(FastCheck.sample(Arbitrary.make(improved), 2))
/*
Example Output:
[ 7, 1518247613 ]
*/