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.
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)
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.
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.
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)
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
Return Value:
- If the function returns a
string
, theTreeFormatter
uses it as the title unless amessage
annotation is present (which takes precedence). - If the function returns
undefined
, theTreeFormatter
determines the title based on the following priority:identifier
annotationtitle
annotationdescription
annotation- Default TypeScript-like schema representation
Example (Dynamic Titles Using parseIssueTitle
)
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)
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'
).
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)
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