Inspectable.ts

Inspectable.ts overview

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.

Since v2.0.0

Exports Grouped by Category

classes
- Class (class)
converting
- toJson
- toStringUnknown
models
- Inspectable (interface)
prototypes
- BaseProto
symbols
- NodeInspectSymbol
- NodeInspectSymbol (type alias)

classes

Class (class)

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.

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")
console.log(user.toString()) // Pretty printed JSON with _tag, id, name, email
console.log(user) // In Node.js, shows the same formatted output

Signature

declare class Class

Source

Since v2.0.0

toJSON (method)

Returns a JSON representation of this object.

When to use

Use to provide the JSON representation consumed by inherited inspection methods.

Details

Subclasses must implement this method to define how the object should be serialized for debugging and inspection purposes.

Signature

declare const toJSON: () => unknown

Source

Since v2.0.0

[NodeInspectSymbol] (method)

Node.js custom inspection method.

When to use

Use to expose the class JSON representation to Node.js inspection.

Signature

declare const [NodeInspectSymbol]: () => unknown

Source

Since v2.0.0

toString (method)

Returns a formatted string representation of this object.

When to use

Use to format the class JSON representation as a string.

Signature

declare const toString: () => string

Source

Since v2.0.0

converting

toJson

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 toJSON method, recursively processes arrays, and handles errors gracefully. For objects that don’t have a toJSON method, it applies redaction to protect sensitive information.

See

toStringUnknown for converting unknown values to strings

Signature

declare const toJson: (input: unknown) => unknown

Source

Since v4.0.0

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 const toStringUnknown: (u: unknown, whitespace?: number | string | undefined) => string

Source

Since v2.0.0

models

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.

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)
console.log(success.toString()) // Pretty formatted JSON

Signature

export interface Inspectable {
  toString(): string
  toJSON(): unknown
  [NodeInspectSymbol](): unknown
}

Source

Since v2.0.0

prototypes

BaseProto

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.

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

console.log(myObject.toString()) // Pretty printed representation

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

Signature

declare const BaseProto: Inspectable

Source

Since v2.0.0

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.

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")
console.log(obj) // Displays: CustomObject(hello)

Signature

declare const NodeInspectSymbol: unique symbol

Source

Since v2.0.0

NodeInspectSymbol (type alias)

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.

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")
console.log(obj) // CustomObject(test)

Signature

type NodeInspectSymbol = typeof NodeInspectSymbol

Source

Since v2.0.0