Formatter

Converts any JavaScript value into a human-readable string.

When to use

Use when you need to format arbitrary JavaScript values for debugging, logging, or error messages.

Details

• Output is not valid JSON; use formatJson when you need parseable JSON.
• Handles BigInt, Symbol, Set, Map, Date, RegExp, and class instances that JSON.stringify cannot represent.
• Circular references are shown as "[Circular]" instead of throwing.
• Primitives: stringified naturally (null, undefined, 123, true). Strings are JSON-quoted.
• Objects with a custom toString (not Object.prototype.toString): toString() is called unless ignoreToString is true.
• Errors with a cause: formatted as "<message> (cause: <cause>)".
• Iterables (Set, Map, etc.): formatted as ClassName([...elements]).
• Class instances: wrapped as ClassName({...}).
• Redactable values are automatically redacted.
• Arrays/objects with 0–1 entries are inline; larger ones are pretty-printed when space is set.
• space — indentation unit (number of spaces, or a string like "\t"). Defaults to 0 (compact).
• ignoreToString — skip calling toString(). Defaults to false.

See

• formatJson
• Formatter

declare function format(input: unknown, options?: {
  readonly ignoreToString?: boolean;
  readonly space?: string | number;
}): string

import { Formatter } from "effect"

Formatter.format({ a: 1, b: [2, 3] }) // => "{\"a\":1,\"b\":[2,3]}"

import { Formatter } from "effect"

const output = Formatter.format({ a: 1, b: [2, 3] }, { space: 2 })
output // => "{\n  \"a\": 1,\n  \"b\": [\n    2,\n    3\n  ]\n}"

import { Formatter } from "effect"

const obj: any = { name: "loop" }
obj.self = obj
Formatter.format(obj) // => "{\"name\":\"loop\",\"self\":[Circular]}"

A callable interface representing a function that converts a Value into a Format, which defaults to string.

When to use

Use when you want to type a formatting or rendering function generically, or when you are building a pipeline that accepts pluggable formatters.

Details

This is a pure callable type and carries no runtime implementation. It is contravariant in Value and covariant in Format.

See

• format
• formatJson

interface Formatter<in Value, out Format = string> {
  (value: Value): Format;
}

import type { Formatter } from "effect"

const upper: Formatter.Formatter<string> = (s) => s.toUpperCase()

upper("hello") // => "HELLO"

Stringifies a value to JSON safely, silently dropping circular references.

When to use

Use when you need valid JSON output, unlike format, and the input may contain circular references that should be silently omitted rather than throwing a TypeError.

Details

Uses JSON.stringify internally with a replacer that tracks the current object ancestry. Circular references are replaced with undefined, which omits them from object output. Redactable values are automatically redacted before serialization. BigInt values are stringified with an n suffix. Values not supported by JSON otherwise follow standard JSON.stringify behavior. The space parameter controls indentation and defaults to 0.

Gotchas

When the root input is undefined, a symbol, or a function, formatJson returns "null" instead of the undefined returned by JSON.stringify. Nested values retain standard JSON.stringify behavior.

See

• format
• Formatter

declare function formatJson(input: unknown, options?: {
  readonly space?: string | number;
}): string

import { Formatter } from "effect"

Formatter.formatJson({ name: "Alice", age: 30 }) // => "{\"name\":\"Alice\",\"age\":30}"

import { Formatter } from "effect"

const obj: any = { name: "test" }
obj.self = obj
Formatter.formatJson(obj) // => "{\"name\":\"test\"}"

import { Formatter } from "effect"

const output = Formatter.formatJson({ name: "Alice", age: 30 }, { space: 2 })
output // => "{\n  \"name\": \"Alice\",\n  \"age\": 30\n}"