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.

7 exports Added in v2.0.0 Source

Converting

toJson

Added in v4.0.0 Source

Converts a value to its structured inspection representation.

When to use

Use when you need the structured representation of an inspectable value without risking unhandled errors.

Details

This function applies redaction before extracting data from objects that implement toJSON, recursively processes arrays, and handles errors gracefully. Plain objects are returned unchanged, so the result is not guaranteed to be accepted by JSON.stringify; it may still contain values such as BigInt, functions, or circular references.

See

toStringUnknown for converting unknown values to strings

Signature

declare function toJson(input: unknown): unknown

toStringUnknown

Added in v2.0.0 Source

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

Class

Added in v2.0.0 Source

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;
}

Example

(Extending the inspectable base class)

import { Inspectable } from "effect"

class User extends Inspectable.Class {
  constructor(
    public readonly id: number,
    public readonly name: string,
    public readonly email: string
  ) {
    super()
  }

  toJSON() {
    return {
      _tag: "User",
      id: this.id,
      name: this.name,
      email: this.email
    }
  }
}

const user = new User(1, "Alice", "alice@example.com")
user.toString() // => "{\"_tag\":\"User\",\"id\":1,\"name\":\"Alice\",\"email\":\"alice@example.com\"}"
user[Inspectable.NodeInspectSymbol]() // => { _tag: "User", id: 1, name: "Alice", email: "alice@example.com" }

Inspectable interface

Added in v2.0.0 Source

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;
}

Example

(Implementing inspectable objects)

import { Formatter, Inspectable } from "effect"

class Result implements Inspectable.Inspectable {
  constructor(
    private readonly tag: "Success" | "Failure",
    private readonly value: unknown
  ) {}

  toString(): string {
    return Formatter.format(this.toJSON())
  }

  toJSON() {
    return { _tag: this.tag, value: this.value }
  }

  [Inspectable.NodeInspectSymbol]() {
    return this.toJSON()
  }
}

const success = new Result("Success", 42)
success.toString() // => "{\"_tag\":\"Success\",\"value\":42}"

Prototypes

BaseProto

Added in v2.0.0 Source

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

Example

(Using the base inspectable prototype)

import { Inspectable } from "effect"

// Use as prototype
const myObject = Object.create(Inspectable.BaseProto)
myObject.name = "example"
myObject.value = 42

myObject.toString() // => "\"[toJSON threw]\""

// Or extend in a constructor
function MyClass(this: any, name: string) {
  this.name = name
}
MyClass.prototype = Object.create(Inspectable.BaseProto)
MyClass.prototype.constructor = MyClass

Symbols

NodeInspectSymbol

Added in v2.0.0 Source

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

Example

(Defining custom Node inspection)

import { Inspectable } from "effect"

class CustomObject {
  constructor(private value: string) {}

  [Inspectable.NodeInspectSymbol]() {
    return `CustomObject(${this.value})`
  }
}

const obj = new CustomObject("hello")
obj[Inspectable.NodeInspectSymbol]() // => "CustomObject(hello)"

NodeInspectSymbol type

Added in v2.0.0 Source

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

Example

(Typing custom Node inspection)

import { Inspectable } from "effect"

class CustomObject {
  constructor(private value: string) {}

  [Inspectable.NodeInspectSymbol]() {
    return `CustomObject(${this.value})`
  }
}

const obj = new CustomObject("test")
obj[Inspectable.NodeInspectSymbol]() // => "CustomObject(test)"