Error Formatters

When working with Effect Schema, errors encountered during decoding or encoding operations can be formatted using two built-in methods: TreeFormatter and ArrayFormatter. These formatters help structure and present errors in a readable and actionable manner.

TreeFormatter (default)

The TreeFormatter is the default method for formatting errors. It organizes errors in a tree structure, providing a clear hierarchy of issues.

Example (Decoding with Missing Properties)

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

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Number,
6
})
7

8
const decode = Schema.decodeUnknownEither(Person)
9

10
const result = decode({})
11
if (Either.isLeft(result)) {
12
  console.error("Decoding failed:")
13
  console.error(ParseResult.TreeFormatter.formatErrorSync(result.left))
14
}
15
/*
16
Decoding failed:
17
{ readonly name: string; readonly age: number }
18
└─ ["name"]
19
   └─ is missing
20
*/

In this example:

{ readonly name: string; readonly age: number } describes the schema’s expected structure.
["name"] identifies the specific field causing the error.
is missing explains the issue for the "name" field.

Customizing the Output

You can make the error output more concise and meaningful by annotating the schema with annotations like identifier, title, or description. These annotations replace the default TypeScript-like representation in the error messages.

Example (Using title Annotation for Clarity)

Adding a title annotation replaces the schema structure in the error message with the more human-readable “Person” making it easier to understand.

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

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Number,
6
}).annotations({ title: "Person" }) // Add a title annotation
7

8
const result = Schema.decodeUnknownEither(Person)({})
9
if (Either.isLeft(result)) {
10
  console.error(ParseResult.TreeFormatter.formatErrorSync(result.left))
11
}
12
/*
13
Person
14
└─ ["name"]
15
   └─ is missing
16
*/

Handling Multiple Errors

By default, decoding functions like Schema.decodeUnknownEither report only the first error. To list all errors, use the { errors: "all" } option.

Example (Listing All Errors)

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

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Number,
6
})
7

8
const decode = Schema.decodeUnknownEither(Person, { errors: "all" })
9

10
const result = decode({})
11
if (Either.isLeft(result)) {
12
  console.error("Decoding failed:")
13
  console.error(ParseResult.TreeFormatter.formatErrorSync(result.left))
14
}
15
/*
16
Decoding failed:
17
{ readonly name: string; readonly age: number }
18
├─ ["name"]
19
│  └─ is missing
20
└─ ["age"]
21
   └─ is missing
22
*/

ParseIssueTitle Annotation

The parseIssueTitle annotation allows you to add dynamic context to error messages by generating titles based on the value being validated. For instance, it can include an ID from the validated object, making it easier to identify specific issues in complex or nested data structures.

Annotation Type

1
export type ParseIssueTitleAnnotation = (issue: ParseIssue) => string | undefined

Return Value:

If the function returns a string, the TreeFormatter uses it as the title unless a message annotation is present (which takes precedence).
If the function returns undefined, the TreeFormatter determines the title based on the following priority:
1. identifier annotation
2. title annotation
3. description annotation
4. Default TypeScript-like schema representation

Example (Dynamic Titles Using parseIssueTitle)

1
import type { ParseResult } from "effect"
2
import { Schema } from "effect"
3

4
// Function to generate titles for OrderItem issues
5
const getOrderItemId = ({ actual }: ParseResult.ParseIssue) => {
6
  if (Schema.is(Schema.Struct({ id: Schema.String }))(actual)) {
7
    return `OrderItem with id: ${actual.id}`
8
  }
9
}
10

11
const OrderItem = Schema.Struct({
12
  id: Schema.String,
13
  name: Schema.String,
14
  price: Schema.Number,
15
}).annotations({
16
  identifier: "OrderItem",
17
  parseIssueTitle: getOrderItemId,
18
})
19

20
// Function to generate titles for Order issues
21
const getOrderId = ({ actual }: ParseResult.ParseIssue) => {
22
  if (Schema.is(Schema.Struct({ id: Schema.Number }))(actual)) {
23
    return `Order with id: ${actual.id}`
24
  }
25
}
26

27
const Order = Schema.Struct({
28
  id: Schema.Number,
29
  name: Schema.String,
30
  items: Schema.Array(OrderItem),
31
}).annotations({
32
  identifier: "Order",
33
  parseIssueTitle: getOrderId,
34
})
35

36
const decode = Schema.decodeUnknownSync(Order, { errors: "all" })
37

38
// Case 1: No id available, uses the `identifier` annotation
39
decode({})
40
/*
41
throws
42
ParseError: Order
43
├─ ["id"]
44
│  └─ is missing
45
├─ ["name"]
46
│  └─ is missing
47
└─ ["items"]
48
   └─ is missing
49
*/
50

51
// Case 2: ID present, uses the dynamic `parseIssueTitle` annotation
52
decode({ id: 1 })
53
/*
54
throws
55
ParseError: Order with id: 1
56
├─ ["name"]
57
│  └─ is missing
58
└─ ["items"]
59
   └─ is missing
60
*/
61

62
// Case 3: Nested issues with IDs for both Order and OrderItem
63
decode({ id: 1, items: [{ id: "22b", price: "100" }] })
64
/*
65
throws
66
ParseError: Order with id: 1
67
├─ ["name"]
68
│  └─ is missing
69
└─ ["items"]
70
   └─ ReadonlyArray<OrderItem>
71
      └─ [0]
72
         └─ OrderItem with id: 22b
73
            ├─ ["name"]
74
            │  └─ is missing
75
            └─ ["price"]
76
               └─ Expected a number, actual "100"
77
*/

ArrayFormatter

The ArrayFormatter provides a structured, array-based approach to formatting errors. It represents each error as an object, making it easier to analyze and address multiple issues during data decoding or encoding. Each error object includes properties like _tag, path, and message for clarity.

Example (Single Error in Array Format)

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

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Number,
6
})
7

8
const decode = Schema.decodeUnknownEither(Person)
9

10
const result = decode({})
11
if (Either.isLeft(result)) {
12
  console.error("Decoding failed:")
13
  console.error(ParseResult.ArrayFormatter.formatErrorSync(result.left))
14
}
15
/*
16
Decoding failed:
17
[ { _tag: 'Missing', path: [ 'name' ], message: 'is missing' } ]
18
*/

In this example:

_tag: Indicates the type of error (Missing).
path: Specifies the location of the error in the data (['name']).
message: Describes the issue ('is missing').

Handling Multiple Errors

By default, decoding functions like Schema.decodeUnknownEither report only the first error. To list all errors, use the { errors: "all" } option.

Example (Listing All Errors)

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

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Number,
6
})
7

8
const decode = Schema.decodeUnknownEither(Person, { errors: "all" })
9

10
const result = decode({})
11
if (Either.isLeft(result)) {
12
  console.error("Decoding failed:")
13
  console.error(ParseResult.ArrayFormatter.formatErrorSync(result.left))
14
}
15
/*
16
Decoding failed:
17
[
18
  { _tag: 'Missing', path: [ 'name' ], message: 'is missing' },
19
  { _tag: 'Missing', path: [ 'age' ], message: 'is missing' }
20
]
21
*/

React Hook Form

If you are working with React and need form validation, @hookform/resolvers offers an adapter for effect/Schema, which can be integrated with React Hook Form for enhanced form validation processes. This integration allows you to leverage the powerful features of effect/Schema within your React applications.

For more detailed instructions and examples on how to integrate effect/Schema with React Hook Form using @hookform/resolvers, you can visit the official npm package page: React Hook Form Resolvers