Error Formatters
When you’re working with Effect Schema and encounter errors during decoding, or encoding functions, you can format these errors in two different ways: using the TreeFormatter
or the ArrayFormatter
.
The TreeFormatter
is the default method for formatting errors. It organizes errors in a tree structure, providing a clear hierarchy of issues.
Here’s an example of how it works:
In this example, the tree error message is structured as follows:
{ readonly name: string; readonly age: number }
represents the schema, providing a visual representation of the expected structure. This can be customized by using annotations likeidentifier
,title
, ordescription
.["name"]
points to the problematic property, in this case, the"name"
property.is missing
details the specific error for the"name"
property.
The default error message represents the involved schemas in a TypeScript-like syntax:
You can customize this output by adding annotations such as identifier
, title
, or description
.
These annotations are applied in this order of priority and allow for a more concise and clear representation in error messages.
In this modified example, by adding a title
annotation, the schema representation in the error message changes to “Person”, providing a simpler and more understandable output. This helps in identifying the schema involved more quickly and improves the readability of the error messages.
Handling Multiple Errors
By default, decoding functions like decodeUnknownEither
return only the first encountered error. If you require a comprehensive list of all errors, you can modify the behavior by passing the { errors: "all" }
option:
This adjustment ensures that the formatter displays all errors related to the input, providing a more detailed diagnostic of what went wrong.
When a decoding or encoding operation fails, it’s useful to have additional details in the default error message returned by TreeFormatter
to understand exactly which value caused the operation to fail. To achieve this, you can set an annotation that depends on the value undergoing the operation and can return an excerpt of it, making it easier to identify the problematic value. A common scenario is when the entity being validated has an id
field. The ParseIssueTitle
annotation facilitates this kind of analysis during error handling.
The type of the annotation is:
If you set this annotation on a schema and the provided function returns a string
, then that string is used as the title by TreeFormatter
, unless a message
annotation (which has the highest priority) has also been set. If the function returns undefined
, then the default title used by TreeFormatter
is determined with the following priorities:
identifier
annotationtitle
annotationdescription
annotation- default TypeScript-like syntax
Example
In the examples above, we can see how the parseIssueTitle
annotation helps provide meaningful error messages when decoding fails.
The ArrayFormatter
offers an alternative method for formatting errors within effect/Schema
, organizing them into a more structured and easily navigable array format. This formatter is especially useful when you need a clear overview of all issues detected during the decoding or encoding processes.
The ArrayFormatter
formats errors as an array of objects, where each object represents a distinct issue and includes properties such as _tag
, path
, and message
. This structured format can help developers quickly identify and address multiple issues in data processing.
Here’s an example of how it works:
Each error is formatted as an object in an array, making it clear what the error is (is missing
), where it occurred (name
), and its type (Missing
).
Handling Multiple Errors
By default, decoding functions like decodeUnknownEither
return only the first encountered error. If you require a comprehensive list of all errors, you can modify the behavior by passing the { errors: "all" }
option:
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