Console.ts

Console.ts overview

Wraps console operations in Effect.

The Console service exposes common console methods such as logging, warnings, errors, groups, counters, tables, and timers. Because console access goes through a service, programs can use custom console implementations in tests or other environments. This module also includes scoped helpers that close console groups or timers automatically.

Since v2.0.0

---

Exports Grouped by Category

• accessors
  • assert
  • clear
  • count
  • countReset
  • debug
  • dir
  • dirxml
  • error
  • group
  • info
  • log
  • table
  • time
  • timeLog
  • trace
  • warn
  • withGroup
  • withTime
• constructors
  • consoleWith
• models
  • Console (interface)
• references
  • Console

---

accessors

assert

Writes the supplied assertion message to the console as an error when condition is false; when condition is true, no console output is produced.

Example (Logging failed assertions)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.assert(2 + 2 === 4, "Math is working correctly")
  yield* Console.assert(2 + 2 === 5, "This will be logged as an error")
})

Signature

declare const assert: (condition: boolean, ...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

clear

Runs the current console service’s clear operation.

When to use

Use to request that the active console implementation clear its visible output.

Gotchas

The clearing behavior depends on the active console implementation and host environment.

Example (Clearing console output)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.log("This will be cleared")
  yield* Console.clear
  yield* Console.log("This appears after clearing")
})

Signature

declare const clear: Effect.Effect<void, never, never>

Source

Since v2.0.0

count

Logs and increments the counter associated with label, using the console’s default counter when no label is provided.

Example (Counting repeated calls)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.count("my-counter")
  yield* Console.count("my-counter") // Will show: my-counter: 2
  yield* Console.count() // Default counter
})

Signature

declare const count: (label?: string) => Effect.Effect<void>

Source

Since v2.0.0

countReset

Resets the counter associated with the specified label back to zero.

Example (Resetting a counter)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.count("my-counter")
  yield* Console.count("my-counter") // Will show: my-counter: 2
  yield* Console.countReset("my-counter")
  yield* Console.count("my-counter") // Will show: my-counter: 1
})

Signature

declare const countReset: (label?: string) => Effect.Effect<void>

Source

Since v2.0.0

debug

Writes a debug message through the current Console service.

Details

The arguments are passed to the service’s debug method when the returned Effect is executed. Any filtering behavior depends on the active console implementation.

Example (Writing debug messages)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.debug("Debug info:", { userId: 123, action: "login" })
  yield* Console.debug("Processing step", 1, "of", 5)
})

Signature

declare const debug: (...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

dir

Displays an interactive list of the properties of the specified object, optionally using console-specific inspection options for debugging complex data structures.

Example (Inspecting an object)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  const obj = { name: "John", age: 30, nested: { city: "New York" } }
  yield* Console.dir(obj)
  yield* Console.dir(obj, { depth: 2, colors: true })
})

Signature

declare const dir: (item: any, options?: any) => Effect.Effect<void>

Source

Since v2.0.0

dirxml

Displays an interactive tree of descendant XML or HTML elements, which is particularly useful for inspecting DOM elements in browser environments.

Example (Inspecting XML-like data)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.dirxml('<user id="1">Ada</user>')
})

Effect.runSync(program)
// <user id="1">Ada</user>

Signature

declare const dirxml: (...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

error

Writes an error-level message to the console, typically displayed with error styling by the active console implementation.

Example (Writing error messages)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.error("Something went wrong!")
  yield* Console.error("Error details:", {
    code: 500,
    message: "Internal Server Error"
  })
})

Signature

declare const error: (...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

group

Creates a scoped console group, optionally collapsed and labeled, and closes it automatically when the Effect scope is finalized.

Example (Grouping scoped output)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.scoped(
    Effect.gen(function* () {
      yield* Console.group({ label: "User Processing" })
      yield* Console.log("Loading user data...")
      yield* Console.log("Validating user...")
      yield* Console.log("User processed successfully")
    })
  )
})

Signature

declare const group: (
  options?: { label?: string | undefined; collapsed?: boolean | undefined } | undefined
) => Effect.Effect<void, never, Scope>

Source

Since v2.0.0

info

Writes an informational message to the console, typically displayed with info styling by the active console implementation.

Example (Writing informational messages)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.info("Application started successfully")
  yield* Console.info("Server configuration:", {
    port: 3000,
    env: "development"
  })
})

Signature

declare const info: (...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

log

Logs a general-purpose message to the console.

Example (Writing log messages)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.log("Hello, world!")
  yield* Console.log("User data:", { name: "John", age: 30 })
  yield* Console.log("Processing", 42, "items")
})

Signature

declare const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

table

Displays tabular data as a formatted table in the console, optionally limited to selected properties.

Example (Displaying tabular data)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  const users = [
    { name: "John", age: 30, city: "New York" },
    { name: "Jane", age: 25, city: "London" },
    { name: "Bob", age: 35, city: "Paris" }
  ]
  yield* Console.table(users)
  yield* Console.table(users, ["name", "age"]) // Only show specific columns
})

Signature

declare const table: (tabularData: any, properties?: ReadonlyArray<string>) => Effect.Effect<void>

Source

Since v2.0.0

time

Starts a scoped timer for label and automatically ends it when the Effect scope is finalized.

Example (Timing scoped work)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.scoped(
    Effect.gen(function* () {
      yield* Console.time("operation-timer")
      yield* Effect.sleep("1 second")
      yield* Console.log("Operation completed")
      // Timer ends automatically when scope closes
    })
  )
})

Signature

declare const time: (label?: string | undefined) => Effect.Effect<void, never, Scope>

Source

Since v2.0.0

timeLog

Logs the elapsed time for an existing timer without stopping it, allowing progress reports for long-running operations.

Example (Logging timer progress)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Effect.scoped(
    Effect.gen(function* () {
      yield* Console.time("long-operation")
      yield* Effect.sleep("500 millis")
      yield* Console.timeLog("long-operation", "Halfway done")
      yield* Effect.sleep("500 millis")
      // Timer ends when scope closes
    })
  )
})

Signature

declare const timeLog: (label?: string, ...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

trace

Writes the current stack trace to the console to show how the current point in the code was reached.

Example (Writing stack traces)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.trace("Debug trace point")
  yield* Console.trace("Function call:", { functionName: "processData" })
})

Signature

declare const trace: (...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

warn

Writes a warning-level message to the console, typically displayed with warning styling by the active console implementation.

Example (Writing warning messages)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.warn("This feature is deprecated")
  yield* Console.warn("Performance warning:", {
    slowQuery: "SELECT * FROM large_table"
  })
})

Signature

declare const warn: (...args: ReadonlyArray<any>) => Effect.Effect<void>

Source

Since v2.0.0

withGroup

Runs an Effect inside an optionally labeled or collapsed console group, starting the group before execution and ending it after the Effect completes.

Example (Wrapping an effect in a group)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.withGroup(
    Effect.gen(function* () {
      yield* Console.log("Step 1: Initialize")
      yield* Console.log("Step 2: Process")
      yield* Console.log("Step 3: Complete")
    }),
    { label: "Processing Steps", collapsed: false }
  )
})

Signature

declare const withGroup: ((options?: {
  readonly label?: string | undefined
  readonly collapsed?: boolean | undefined
}) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>) &
  (<A, E, R>(
    self: Effect.Effect<A, E, R>,
    options?: { readonly label?: string | undefined; readonly collapsed?: boolean | undefined }
  ) => Effect.Effect<A, E, R>)

Source

Since v2.0.0

withTime

Runs an Effect with a console timer, starting the timer before execution and ending it after the Effect completes.

Example (Timing an effect)

import { Console, Effect } from "effect"

const program = Effect.gen(function* () {
  yield* Console.withTime(
    Effect.gen(function* () {
      yield* Effect.sleep("1 second")
      yield* Console.log("Operation completed")
    }),
    "my-operation"
  )
})

Signature

declare const withTime: ((label?: string) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>) &
  (<A, E, R>(self: Effect.Effect<A, E, R>, label?: string) => Effect.Effect<A, E, R>)

Source

Since v2.0.0

constructors

consoleWith

Creates an Effect that provides access to the current console service and lets you perform operations with it within an Effect context.

Example (Accessing the current console service)

import { Console, Effect } from "effect"

const program = Console.consoleWith((console) =>
  Effect.sync(() => {
    console.log("Hello, world!")
    console.error("This is an error message")
  })
)

Signature

declare const consoleWith: <A, E, R>(f: (console: Console) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>

Source

Since v2.0.0

models

Console (interface)

Represents a console interface for logging, debugging, timing, and grouping output.

Signature

export interface Console {
  assert(condition: boolean, ...args: ReadonlyArray<any>): void
  clear(): void
  count(label?: string): void
  countReset(label?: string): void
  debug(...args: ReadonlyArray<any>): void
  dir(item: any, options?: any): void
  dirxml(...args: ReadonlyArray<any>): void
  error(...args: ReadonlyArray<any>): void
  group(...args: ReadonlyArray<any>): void
  groupCollapsed(...args: ReadonlyArray<any>): void
  groupEnd(): void
  info(...args: ReadonlyArray<any>): void
  log(...args: ReadonlyArray<any>): void
  table(tabularData: any, properties?: ReadonlyArray<string>): void
  time(label?: string): void
  timeEnd(label?: string): void
  timeLog(label?: string, ...args: ReadonlyArray<any>): void
  trace(...args: ReadonlyArray<any>): void
  warn(...args: ReadonlyArray<any>): void
}

Source

Since v2.0.0

references

Console

Context reference for the current console service in the Effect system, allowing access to the active console implementation from within the Effect context.

When to use

Use when you need an effect to run against a provided console implementation, such as tests or alternate runtimes, rather than the default console.

Details

When no override is provided, the reference resolves to globalThis.console.

Example (Accessing the current console)

import { Console, Effect } from "effect"

const program = Console.consoleWith((console) =>
  Effect.sync(() => {
    console.log("Hello from current console!")
  })
)

See

• consoleWith for using the current console service inside an effect

Signature

declare const Console: Context.Reference<Console>

Source

Since v2.0.0