Inspectable
Controls how values appear in logs and debugging output.
Effect data types use Inspectable to provide stable string, JSON, and Node.js inspection output. This keeps custom values readable in logs, REPLs, test failures, and diagnostics. This module defines the Node inspect symbol, the Inspectable interface, safe conversion helpers, and shared prototype or class implementations for custom values.
Converting
Signature
declare function toJson(input: unknown): unknown;toStringUnknown
Converts an unknown value to a string for diagnostics.
When to use
Use to produce a diagnostic string from a value whose runtime type is unknown.
Details
Strings are returned unchanged. Objects are formatted as JSON using the provided whitespace setting when possible, and values that cannot be formatted are converted with String.
Signature
declare function toStringUnknown(u: unknown, whitespace: string | number | undefined): string;Models
Provides an abstract base class that implements the Inspectable interface.
When to use
Use as a base class for inspectable objects that define their own JSON representation.
Details
This class provides a convenient way to create inspectable objects by extending it. Subclasses only need to implement the toJSON() method, and they automatically get proper toString() and Node.js inspection support.
Signature
declare class Class {
constructor();
[NodeInspectSymbol](): unknown;
abstract toJSON(): unknown;
toString(): string;
}Inspectable interface
Interface for objects that can be inspected and provide custom string representations.
When to use
Use to define values with custom string, JSON, and Node.js inspection output.
Details
Objects implementing this interface can control how they appear in debugging contexts, JSON serialization, and Node.js inspection. This is particularly useful for creating custom data types that display meaningful information during development.
Signature
interface Inspectable {
[NodeInspectSymbol](): unknown;
toJSON(): unknown;
toString(): string;
}Prototypes
A base prototype object that implements the Inspectable interface.
When to use
Use as a prototype for plain objects that should share standard inspectable behavior.
Details
This object provides default implementations for the Inspectable methods. It can be used as a prototype for objects that want to be inspectable, or as a mixin to add inspection capabilities to existing objects.
Signature
declare const BaseProto: Inspectable;Symbols
NodeInspectSymbol
Defines the symbol used by Node.js for custom object inspection.
When to use
Use to implement Node.js custom inspection for a value.
Details
This symbol is recognized by Node.js's util.inspect() function and the REPL for custom object representation. When an object has a method with this symbol, it will be called to determine how the object should be displayed.
Signature
declare const NodeInspectSymbol: typeof NodeInspectSymbol;NodeInspectSymbol type
The type of the Node.js inspection symbol used for custom object inspection. This symbol type is used to implement custom inspection behavior in Node.js environments.
When to use
Use to type methods keyed by the Node.js custom inspection symbol.
Signature
type NodeInspectSymbol = typeof NodeInspectSymbol;
Converts a value to a JSON-serializable representation safely.
When to use
Use when you need a safe, JSON-serializable representation of a value without risking unhandled errors.
Details
This function attempts to extract JSON data from objects that implement the
toJSONmethod, recursively processes arrays, and handles errors gracefully. For objects that don't have atoJSONmethod, it applies redaction to protect sensitive information.See
toStringUnknownfor converting unknown values to strings