import { inspect } from 'node:util' export interface FormatErrorTreeOptions { /** Deepest nesting level rendered; deeper errors are counted as omitted. Default 5. */ maxDepth?: number /** Total nested errors rendered across the tree. Default 20. */ maxNested?: number } type Child = { label: string; value: unknown } /** Formats an error and its nested `errors[]` and `cause` chain without util.format's shallow output. */ export function formatErrorTree(error: unknown, options: FormatErrorTreeOptions = {}): string { const maxDepth = options.maxDepth ?? 5 const maxNested = options.maxNested ?? 20 const seen = new Set() // Nodes visited only while counting omitted subtrees; kept apart from `seen` so a hidden // occurrence never turns a later visible occurrence into `[circular]`. const omittedSeen = new Set() let nestedCount = 0 let omittedCount = 0 const render = (value: unknown, depth: number, label?: string): string[] => { if (isObject(value)) { if (seen.has(value)) return indentLines('[circular]', depth, label) seen.add(value) } const lines = indentLines(formatValue(value), depth, label) for (const child of getChildren(value)) { if (depth >= maxDepth || nestedCount >= maxNested) { omittedCount += countOmitted(child.value, seen, omittedSeen) } else { nestedCount += 1 lines.push(...render(child.value, depth + 1, child.label)) } } return lines } const lines = render(error, 0) if (omittedCount > 0) lines.push(`… ${omittedCount} more nested errors omitted`) return lines.join('\n') } function formatValue(value: unknown): string { if (!(value instanceof Error)) return inspect(withoutChildren(value), { depth: 2 }) if (typeof value.stack === 'string' && value.stack.length > 0) return value.stack return `${value.name || 'Error'}: ${value.message}` } // Child errors are traversed separately under the limits, so inspect must not print them too. function withoutChildren(value: unknown): unknown { if (!isObject(value) || Array.isArray(value) || getChildren(value).length === 0) return value const copy = { ...(value as Record) } if (Array.isArray(copy.errors)) delete copy.errors if (copy.cause !== undefined) delete copy.cause return copy } function getChildren(value: unknown): Child[] { if (!isObject(value)) return [] const children: Child[] = [] const properties = value as Record const errors = properties.errors if (Array.isArray(errors)) { errors.forEach((nested, index) => children.push({ label: `errors[${index}]:`, value: nested })) } if (properties.cause !== undefined) children.push({ label: 'cause:', value: properties.cause }) return children } function countOmitted(value: unknown, seen: Set, omittedSeen: Set): number { const pending = [value] let count = 0 while (pending.length > 0) { const current = pending.pop() if (isObject(current)) { if (seen.has(current) || omittedSeen.has(current)) { count += 1 continue } omittedSeen.add(current) } count += 1 const children = getChildren(current) for (let index = children.length - 1; index >= 0; index -= 1) { pending.push(children[index]!.value) } } return count } function indentLines(value: string, depth: number, label?: string): string[] { const indentation = ' '.repeat(depth) return value .split(/\r?\n/) .map((line, index) => `${indentation}${index === 0 && label ? `${label} ` : ''}${line}`) } function isObject(value: unknown): value is object { return (typeof value === 'object' && value !== null) || typeof value === 'function' }