Skip to content

Formatter

Formats JavaScript values into readable strings.

format is intended for logs, diagnostics, and error messages. It handles primitives, objects, arrays, dates, regular expressions, maps, sets, class instances, errors, circular references, and redactable values. formatJson wraps JSON formatting with redaction and circular-reference handling, and the module also includes helpers for property keys, paths, and dates.

3 exports Added in v2.0.0 Source

Formatting

format

Added in v2.0.0 Source

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

Signature

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

Models

Formatter interface

Added in v4.0.0 Source

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

Signature

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

Serialization

formatJson

Added in v4.0.0 Source

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. 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

Signature

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