Filters

Developers can define custom validation logic beyond basic type checks, giving more control over how data is validated.

Declaring Filters

Filters are declared using the Schema.filter function. This function requires two arguments: the schema to be validated and a predicate function. The predicate function is user-defined and determines whether the data satisfies the condition. If the data fails the validation, an error message can be provided.

Example (Defining a Minimum String Length Filter)

1
import { Schema } from "effect"
2

3
// Define a string schema with a filter to ensure the string
4
// is at least 10 characters long
5
const LongString = Schema.String.pipe(
6
  Schema.filter(
7
    // Custom error message for strings shorter than 10 characters
8
    (s) => s.length >= 10 || "a string at least 10 characters long",
9
  ),
10
)
11

12
//     ┌─── string
13
//     ▼
14
type Type = typeof LongString.Type
15

16
console.log(Schema.decodeUnknownSync(LongString)("a"))
17
/*
18
throws:
19
ParseError: { string | filter }
20
└─ Predicate refinement failure
21
   └─ a string at least 10 characters long
22
*/

Note that the filter does not alter the schema’s Type:

//     ┌─── string
//     ▼
type Type = typeof LongString.Type

Filters add additional validation constraints without modifying the schema’s underlying type.

The Predicate Function

The predicate function in a filter follows this structure:

1
type Predicate = (a: A, options: ParseOptions, self: AST.Refinement) => FilterReturnType

where

1
interface FilterIssue {
2
  readonly path: ReadonlyArray<PropertyKey>
3
  readonly issue: string | ParseResult.ParseIssue
4
}
5

6
type FilterOutput = undefined | boolean | string | ParseResult.ParseIssue | FilterIssue
7

8
type FilterReturnType = FilterOutput | ReadonlyArray<FilterOutput>

The filter’s predicate can return several types of values, each affecting validation in a different way:

Return Type	Behavior
`true` or `undefined`	The data satisfies the filter’s condition and passes validation.
`false`	The data does not meet the condition, and no specific error message is provided.
`string`	The validation fails, and the provided string is used as the error message.
`ParseResult.ParseIssue`	The validation fails with a detailed error structure, specifying where and why it failed.
`FilterIssue`	Allows for more detailed error messages with specific paths, providing enhanced error reporting.
`ReadonlyArray<FilterOutput>`	An array of issues can be returned if multiple validation errors need to be reported.

Adding Annotations

Embedding metadata within the schema, such as identifiers, JSON schema specifications, and descriptions, enhances understanding and analysis of the schema’s constraints and purpose.

Example (Adding Metadata with Annotations)

1
import { Schema, JSONSchema } from "effect"
2

3
const LongString = Schema.String.pipe(
4
  Schema.filter((s) => (s.length >= 10 ? undefined : "a string at least 10 characters long"), {
5
    identifier: "LongString",
6
    jsonSchema: { minLength: 10 },
7
    description: "Lorem ipsum dolor sit amet, ...",
8
  }),
9
)
10

11
console.log(Schema.decodeUnknownSync(LongString)("a"))
12
/*
13
throws:
14
ParseError: LongString
15
└─ Predicate refinement failure
16
   └─ a string at least 10 characters long
17
*/
18

19
console.log(JSON.stringify(JSONSchema.make(LongString), null, 2))
20
/*
21
Output:
22
{
23
  "$schema": "http://json-schema.org/draft-07/schema#",
24
  "$defs": {
25
    "LongString": {
26
      "type": "string",
27
      "description": "Lorem ipsum dolor sit amet, ...",
28
      "minLength": 10
29
    }
30
  },
31
  "$ref": "#/$defs/LongString"
32
}
33
*/

Specifying Error Paths

When validating forms or structured data, it’s possible to associate specific error messages with particular fields or paths. This enhances error reporting and is especially useful when integrating with libraries like react-hook-form.

Example (Matching Passwords)

1
import { Either, Schema, ParseResult } from "effect"
2

3
const Password = Schema.Trim.pipe(Schema.minLength(2))
4

5
const MyForm = Schema.Struct({
6
  password: Password,
7
  confirm_password: Password,
8
}).pipe(
9
  // Add a filter to ensure that passwords match
10
  Schema.filter((input) => {
11
    if (input.password !== input.confirm_password) {
12
      // Return an error message associated
13
      // with the "confirm_password" field
14
      return {
15
        path: ["confirm_password"],
16
        message: "Passwords do not match",
17
      }
18
    }
19
  }),
20
)
21

22
console.log(
23
  JSON.stringify(
24
    Schema.decodeUnknownEither(MyForm)({
25
      password: "abc",
26
      confirm_password: "abd", // Confirm password does not match
27
    }).pipe(Either.mapLeft((error) => ParseResult.ArrayFormatter.formatErrorSync(error))),
28
    null,
29
    2,
30
  ),
31
)
32
/*
33
  "_id": "Either",
34
  "_tag": "Left",
35
  "left": [
36
    {
37
      "_tag": "Type",
38
      "path": [
39
        "confirm_password"
40
      ],
41
      "message": "Passwords do not match"
42
    }
43
  ]
44
}
45
*/

In this example, we define a MyForm schema with two password fields (password and confirm_password). We use Schema.filter to check that both passwords match. If they don’t, an error message is returned, specifically associated with the confirm_password field. This makes it easier to pinpoint the exact location of the validation failure.

The error is formatted in a structured way using ArrayFormatter, allowing for easier post-processing and integration with form libraries.

Multiple Error Reporting

The Schema.filter API supports reporting multiple validation issues at once, which is especially useful in scenarios like form validation where several checks might fail simultaneously.

Example (Reporting Multiple Validation Errors)

1
import { Either, Schema, ParseResult } from "effect"
2

3
const Password = Schema.Trim.pipe(Schema.minLength(2))
4
const OptionalString = Schema.optional(Schema.String)
5

6
const MyForm = Schema.Struct({
7
  password: Password,
8
  confirm_password: Password,
9
  name: OptionalString,
10
  surname: OptionalString,
11
}).pipe(
12
  Schema.filter((input) => {
13
    const issues: Array<Schema.FilterIssue> = []
14

15
    // Check if passwords match
16
    if (input.password !== input.confirm_password) {
17
      issues.push({
18
        path: ["confirm_password"],
19
        message: "Passwords do not match",
20
      })
21
    }
22

23
    // Ensure either name or surname is present
24
    if (!input.name && !input.surname) {
25
      issues.push({
26
        path: ["surname"],
27
        message: "Surname must be present if name is not present",
28
      })
29
    }
30
    return issues
31
  }),
32
)
33

34
console.log(
35
  JSON.stringify(
36
    Schema.decodeUnknownEither(MyForm)({
37
      password: "abc",
38
      confirm_password: "abd", // Confirm password does not match
39
    }).pipe(Either.mapLeft((error) => ParseResult.ArrayFormatter.formatErrorSync(error))),
40
    null,
41
    2,
42
  ),
43
)
44
/*
45
{
46
  "_id": "Either",
47
  "_tag": "Left",
48
  "left": [
49
    {
50
      "_tag": "Type",
51
      "path": [
52
        "confirm_password"
53
      ],
54
      "message": "Passwords do not match"
55
    },
56
    {
57
      "_tag": "Type",
58
      "path": [
59
        "surname"
60
      ],
61
      "message": "Surname must be present if name is not present"
62
    }
63
  ]
64
}
65
*/

In this example, we define a MyForm schema with fields for password validation and optional name/surname fields. The Schema.filter function checks if the passwords match and ensures that either a name or surname is provided. If either validation fails, the corresponding error message is associated with the relevant field and both errors are returned in a structured format.

Exposed Values

For schemas with filters, you can access the base schema (the schema before the filter was applied) using the from property:

1
import { Schema } from "effect"
2

3
const LongString = Schema.String.pipe(Schema.filter((s) => s.length >= 10))
4

5
// Access the base schema, which is the string schema
6
// before the filter was applied
7
//
8
//      ┌─── typeof Schema.String
9
//      ▼
10
const From = LongString.from

Built-in Filters

String Filters

Here is a list of useful string filters provided by the Schema module:

1
import { Schema } from "effect"
2

3
// Specifies maximum length of a string
4
Schema.String.pipe(Schema.maxLength(5))
5

6
// Specifies minimum length of a string
7
Schema.String.pipe(Schema.minLength(5))
8

9
// Equivalent to minLength(1)
10
Schema.String.pipe(Schema.nonEmptyString())
11
// or
12
Schema.NonEmptyString
13

14
// Specifies exact length of a string
15
Schema.String.pipe(Schema.length(5))
16

17
// Specifies a range for the length of a string
18
Schema.String.pipe(Schema.length({ min: 2, max: 4 }))
19

20
// Matches a string against a regular expression pattern
21
Schema.String.pipe(Schema.pattern(/^[a-z]+$/))
22

23
// Ensures a string starts with a specific substring
24
Schema.String.pipe(Schema.startsWith("prefix"))
25

26
// Ensures a string ends with a specific substring
27
Schema.String.pipe(Schema.endsWith("suffix"))
28

29
// Checks if a string includes a specific substring
30
Schema.String.pipe(Schema.includes("substring"))
31

32
// Validates that a string has no leading or trailing whitespaces
33
Schema.String.pipe(Schema.trimmed())
34

35
// Validates that a string is entirely in lowercase
36
Schema.String.pipe(Schema.lowercased())
37

38
// Validates that a string is entirely in uppercase
39
Schema.String.pipe(Schema.uppercased())
40

41
// Validates that a string is capitalized
42
Schema.String.pipe(Schema.capitalized())
43

44
// Validates that a string is uncapitalized
45
Schema.String.pipe(Schema.uncapitalized())

Number Filters

Here is a list of useful number filters provided by the Schema module:

1
import { Schema } from "effect"
2

3
// Specifies a number greater than 5
4
Schema.Number.pipe(Schema.greaterThan(5))
5

6
// Specifies a number greater than or equal to 5
7
Schema.Number.pipe(Schema.greaterThanOrEqualTo(5))
8

9
// Specifies a number less than 5
10
Schema.Number.pipe(Schema.lessThan(5))
11

12
// Specifies a number less than or equal to 5
13
Schema.Number.pipe(Schema.lessThanOrEqualTo(5))
14

15
// Specifies a number between -2 and 2, inclusive
16
Schema.Number.pipe(Schema.between(-2, 2))
17

18
// Specifies that the value must be an integer
19
Schema.Number.pipe(Schema.int())
20
// or
21
Schema.Int
22

23
// Ensures the value is not NaN
24
Schema.Number.pipe(Schema.nonNaN())
25
// or
26
Schema.NonNaN
27

28
// Ensures that the provided value is a finite number
29
// (excluding NaN, +Infinity, and -Infinity)
30
Schema.Number.pipe(Schema.finite())
31
// or
32
Schema.Finite
33

34
// Specifies a positive number (> 0)
35
Schema.Number.pipe(Schema.positive())
36
// or
37
Schema.Positive
38

39
// Specifies a non-negative number (>= 0)
40
Schema.Number.pipe(Schema.nonNegative())
41
// or
42
Schema.NonNegative
43

44
// A non-negative integer
45
Schema.NonNegativeInt
46

47
// Specifies a negative number (< 0)
48
Schema.Number.pipe(Schema.negative())
49
// or
50
Schema.Negative
51

52
// Specifies a non-positive number (<= 0)
53
Schema.Number.pipe(Schema.nonPositive())
54
// or
55
Schema.NonPositive
56

57
// Specifies a number that is evenly divisible by 5
58
Schema.Number.pipe(Schema.multipleOf(5))
59

60
// A 8-bit unsigned integer (0 to 255)
61
Schema.Uint8

ReadonlyArray Filters

Here is a list of useful array filters provided by the Schema module:

1
import { Schema } from "effect"
2

3
// Specifies the maximum number of items in the array
4
Schema.Array(Schema.Number).pipe(Schema.maxItems(2))
5

6
// Specifies the minimum number of items in the array
7
Schema.Array(Schema.Number).pipe(Schema.minItems(2))
8

9
// Specifies the exact number of items in the array
10
Schema.Array(Schema.Number).pipe(Schema.itemsCount(2))

Date Filters

1
import { Schema } from "effect"
2

3
// Specifies a valid date (rejects values like `new Date("Invalid Date")`)
4
Schema.DateFromSelf.pipe(Schema.validDate())
5
// or
6
Schema.ValidDateFromSelf
7

8
// Specifies a date greater than the current date
9
Schema.Date.pipe(Schema.greaterThanDate(new Date()))
10

11
// Specifies a date greater than or equal to the current date
12
Schema.Date.pipe(Schema.greaterThanOrEqualToDate(new Date()))
13

14
// Specifies a date less than the current date
15
Schema.Date.pipe(Schema.lessThanDate(new Date()))
16

17
// Specifies a date less than or equal to the current date
18
Schema.Date.pipe(Schema.lessThanOrEqualToDate(new Date()))
19

20
// Specifies a date between two dates
21
Schema.Date.pipe(Schema.betweenDate(new Date(0), new Date()))

BigInt Filters

Here is a list of useful BigInt filters provided by the Schema module:

1
import { Schema } from "effect"
2

3
// Specifies a BigInt greater than 5
4
Schema.BigInt.pipe(Schema.greaterThanBigInt(5n))
5

6
// Specifies a BigInt greater than or equal to 5
7
Schema.BigInt.pipe(Schema.greaterThanOrEqualToBigInt(5n))
8

9
// Specifies a BigInt less than 5
10
Schema.BigInt.pipe(Schema.lessThanBigInt(5n))
11

12
// Specifies a BigInt less than or equal to 5
13
Schema.BigInt.pipe(Schema.lessThanOrEqualToBigInt(5n))
14

15
// Specifies a BigInt between -2n and 2n, inclusive
16
Schema.BigInt.pipe(Schema.betweenBigInt(-2n, 2n))
17

18
// Specifies a positive BigInt (> 0n)
19
Schema.BigInt.pipe(Schema.positiveBigInt())
20
// or
21
Schema.PositiveBigIntFromSelf
22

23
// Specifies a non-negative BigInt (>= 0n)
24
Schema.BigInt.pipe(Schema.nonNegativeBigInt())
25
// or
26
Schema.NonNegativeBigIntFromSelf
27

28
// Specifies a negative BigInt (< 0n)
29
Schema.BigInt.pipe(Schema.negativeBigInt())
30
// or
31
Schema.NegativeBigIntFromSelf
32

33
// Specifies a non-positive BigInt (<= 0n)
34
Schema.BigInt.pipe(Schema.nonPositiveBigInt())
35
// or
36
Schema.NonPositiveBigIntFromSelf

BigDecimal Filters

Here is a list of useful BigDecimal filters provided by the Schema module:

1
import { Schema, BigDecimal } from "effect"
2

3
// Specifies a BigDecimal greater than 5
4
Schema.BigDecimal.pipe(Schema.greaterThanBigDecimal(BigDecimal.unsafeFromNumber(5)))
5

6
// Specifies a BigDecimal greater than or equal to 5
7
Schema.BigDecimal.pipe(Schema.greaterThanOrEqualToBigDecimal(BigDecimal.unsafeFromNumber(5)))
8
// Specifies a BigDecimal less than 5
9
Schema.BigDecimal.pipe(Schema.lessThanBigDecimal(BigDecimal.unsafeFromNumber(5)))
10

11
// Specifies a BigDecimal less than or equal to 5
12
Schema.BigDecimal.pipe(Schema.lessThanOrEqualToBigDecimal(BigDecimal.unsafeFromNumber(5)))
13

14
// Specifies a BigDecimal between -2 and 2, inclusive
15
Schema.BigDecimal.pipe(
16
  Schema.betweenBigDecimal(BigDecimal.unsafeFromNumber(-2), BigDecimal.unsafeFromNumber(2)),
17
)
18

19
// Specifies a positive BigDecimal (> 0)
20
Schema.BigDecimal.pipe(Schema.positiveBigDecimal())
21

22
// Specifies a non-negative BigDecimal (>= 0)
23
Schema.BigDecimal.pipe(Schema.nonNegativeBigDecimal())
24

25
// Specifies a negative BigDecimal (< 0)
26
Schema.BigDecimal.pipe(Schema.negativeBigDecimal())
27

28
// Specifies a non-positive BigDecimal (<= 0)
29
Schema.BigDecimal.pipe(Schema.nonPositiveBigDecimal())

Duration Filters

Here is a list of useful Duration filters provided by the Schema module:

1
import { Schema } from "effect"
2

3
// Specifies a duration greater than 5 seconds
4
Schema.Duration.pipe(Schema.greaterThanDuration("5 seconds"))
5

6
// Specifies a duration greater than or equal to 5 seconds
7
Schema.Duration.pipe(Schema.greaterThanOrEqualToDuration("5 seconds"))
8

9
// Specifies a duration less than 5 seconds
10
Schema.Duration.pipe(Schema.lessThanDuration("5 seconds"))
11

12
// Specifies a duration less than or equal to 5 seconds
13
Schema.Duration.pipe(Schema.lessThanOrEqualToDuration("5 seconds"))
14

15
// Specifies a duration between 5 seconds and 10 seconds, inclusive
16
Schema.Duration.pipe(Schema.betweenDuration("5 seconds", "10 seconds"))