Schema to Formatter

Schema.toFormatter derives a human-readable formatter for values of a schema’s Type. It recursively formats structs, arrays, unions, and declarations; it does not validate the value.

This value formatter is distinct from the Error Formatters used for decoding and encoding failures.

Example (Formatter for a Struct Schema)

1
import { Schema } from "effect"
2

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

8
const PersonFormatter = Schema.toFormatter(Person)
9

10
PersonFormatter({ name: "Alice", age: 30 }) // => `{ "name": "Alice", "age": 30 }`

Customizing Formatter Generation

Use Schema.overrideToFormatter to replace the formatter derived for an existing schema.

Example (Custom Formatter for Numbers)

1
import { Schema } from "effect"
2

3
const schema = Schema.Finite.pipe(
4
  Schema.overrideToFormatter(() => (value) => `my format: ${value}`),
5
)
6

7
const customFormatter = Schema.toFormatter(schema)
8

9
customFormatter(1) // => "my format: 1"

Declarations can instead provide a toFormatter annotation when they are defined. Parameterized declarations receive the formatter derived for each type parameter.

Intercepting AST Nodes

Pass an onBefore hook to intercept selected AST nodes before the default formatter is derived. Return undefined to retain the default behavior.

Example (Customizing All String Nodes)

1
import { Schema } from "effect"
2

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

8
const formatter = Schema.toFormatter(Person, {
9
  onBefore: (ast) =>
10
    ast._tag === "String" ? (value: string) => `<${value}>` : undefined,
11
})
12

13
formatter({ name: "Alice", city: "Rome" }) // => `{ "name": <Alice>, "city": <Rome> }`