Console.log

Back in the lessons on Context.Tag (16) and Effect.provideService (17) we saw how to define a custom service to help with dependency injection. The Effect library includes several “default” services. The Console service wraps writing to the console.

Console.log is an Effectful version of console.log. This means that it represents an instruction, which will only run when passed to one of the Effect.run*. This is different from a regular console.log, which will execute immediately.

import { 
import Console
Console, 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect";

const 
const printsWhenRun: Effect.Effect<void, never, never>
printsWhenRun = 
import Console
Console.
const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
log("This will print only when run");

var console: Console
console.
globalThis.Console.log(...data: any[]): void
MDN Reference
log("This will print immediately");
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runSync: <void, never>(effect: Effect.Effect<void, never, never>) => void
Executes an effect synchronously, running it immediately and returning the
result.
Details
This function evaluates the provided effect synchronously, returning its
result directly. It is ideal for effects that do not fail or include
asynchronous operations. If the effect does fail or involves async tasks, it
will throw an error. Execution stops at the point of failure or asynchronous
operation, making it unsuitable for effects that require asynchronous
handling.
Important: Attempting to run effects that involve asynchronous operations
or failures will result in exceptions being thrown, so use this function with
care for purely synchronous and error-free effects.
When to Use
Use this function when:

You are sure that the effect will not fail or involve asynchronous
operations.
You need a direct, synchronous result from the effect.
You are working within a context where asynchronous effects are not
allowed.

Avoid using this function for effects that can fail or require asynchronous
handling. For such cases, consider using
runPromise
or
runSyncExit
.
Example (Synchronous Logging)
import { Effect } from "effect"

const program = Effect.sync(() => {
  console.log("Hello, World!")
  return 1
})

const result = Effect.runSync(program)
// Output: Hello, World!

console.log(result)
// Output: 1
Example (Incorrect Usage with Failing or Async Effects)
import { Effect } from "effect"

try {
  // Attempt to run an effect that fails
  Effect.runSync(Effect.fail("my error"))
} catch (e) {
  console.error(e)
}
// Output:
// (FiberFailure) Error: my error

try {
  // Attempt to run an effect that involves async work
  Effect.runSync(Effect.promise(() => Promise.resolve(1)))
} catch (e) {
  console.error(e)
}
// Output:
// (FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
@see ― runSyncExit for a version that returns an Exit type instead of
throwing an error.
@since ― 2.0.0
runSync(
const printsWhenRun: Effect.Effect<void, never, never>
printsWhenRun);
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runSync: <void, never>(effect: Effect.Effect<void, never, never>) => void
Executes an effect synchronously, running it immediately and returning the
result.
Details
This function evaluates the provided effect synchronously, returning its
result directly. It is ideal for effects that do not fail or include
asynchronous operations. If the effect does fail or involves async tasks, it
will throw an error. Execution stops at the point of failure or asynchronous
operation, making it unsuitable for effects that require asynchronous
handling.
Important: Attempting to run effects that involve asynchronous operations
or failures will result in exceptions being thrown, so use this function with
care for purely synchronous and error-free effects.
When to Use
Use this function when:

You are sure that the effect will not fail or involve asynchronous
operations.
You need a direct, synchronous result from the effect.
You are working within a context where asynchronous effects are not
allowed.

Avoid using this function for effects that can fail or require asynchronous
handling. For such cases, consider using
runPromise
or
runSyncExit
.
Example (Synchronous Logging)
import { Effect } from "effect"

const program = Effect.sync(() => {
  console.log("Hello, World!")
  return 1
})

const result = Effect.runSync(program)
// Output: Hello, World!

console.log(result)
// Output: 1
Example (Incorrect Usage with Failing or Async Effects)
import { Effect } from "effect"

try {
  // Attempt to run an effect that fails
  Effect.runSync(Effect.fail("my error"))
} catch (e) {
  console.error(e)
}
// Output:
// (FiberFailure) Error: my error

try {
  // Attempt to run an effect that involves async work
  Effect.runSync(Effect.promise(() => Promise.resolve(1)))
} catch (e) {
  console.error(e)
}
// Output:
// (FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
@see ― runSyncExit for a version that returns an Exit type instead of
throwing an error.
@since ― 2.0.0
runSync(
const printsWhenRun: Effect.Effect<void, never, never>
printsWhenRun);

We can see the results:

This will print immediately
This will print only when run
This will print only when run

Console.log works nicely in a pipeline, especially when used with Effect.tap (38) and Effect.zipLeft (40) .

const 
const program: Effect.Effect<number, never, never>
program = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const succeed: <number>(value: number) => Effect.Effect<number, never, never>
Creates an Effect that always succeeds with a given value.
When to Use
Use this function when you need an effect that completes successfully with a
specific value without any errors or external dependencies.
Example (Creating a Successful Effect)
import { Effect } from "effect"

// Creating an effect that represents a successful scenario
//
//      ┌─── Effect<number, never, never>
//      ▼
const success = Effect.succeed(42)
@see ― fail to create an effect that represents a failure.
@since ― 2.0.0
succeed(0).
Pipeable.pipe<Effect.Effect<number, never, never>, Effect.Effect<number, never, never>, Effect.Effect<number, never, never>, Effect.Effect<number, never, never>, Effect.Effect<...>, Effect.Effect<...>, Effect.Effect<...>, Effect.Effect<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>, cd: (_: Effect.Effect<...>) => Effect.Effect<...>, de: (_: Effect.Effect<...>) => Effect.Effect<...>, ef: (_: Effect.Effect<...>) => Effect.Effect<...>, fg: (_: Effect.Effect<...>) => Effect.Effect<...>, gh: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe(
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const map: <number, number>(f: (a: number) => number) => <E, R>(self: Effect.Effect<number, E, R>) => Effect.Effect<number, E, R> (+1 overload)
Transforms the value inside an effect by applying a function to it.
Syntax
const mappedEffect = pipe(myEffect, Effect.map(transformation))
// or
const mappedEffect = Effect.map(myEffect, transformation)
// or
const mappedEffect = myEffect.pipe(Effect.map(transformation))
Details
map takes a function and applies it to the value contained within an
effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original
effect is not modified. Instead, a new effect is returned with the updated
value.
Example (Adding a Service Charge)
import { pipe, Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.map(addServiceCharge)
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 101
@see ― mapError for a version that operates on the error channel.
@see ― mapBoth for a version that operates on both channels.
@see ― flatMap or andThen for a version that can return a new effect.
@since ― 2.0.0
map((
x: number
x) => 
x: number
x + 1),
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const tap: <number, Effect.Effect<void, never, never>>(f: (a: number) => Effect.Effect<void, never, never>) => <E, R>(self: Effect.Effect<number, E, R>) => Effect.Effect<...> (+7 overloads)
Runs a side effect with the result of an effect without changing the original
value.
Details
This function works similarly to flatMap, but it ignores the result of the
function passed to it. The value from the previous effect remains available
for the next part of the chain. Note that if the side effect fails, the
entire chain will fail too.
When to Use
Use this function when you want to perform a side effect, like logging or
tracking, without modifying the main value. This is useful when you need to
observe or record an action but want the original value to be passed to the
next step.
Example (Logging a step in a pipeline)
import { Console, Effect, pipe } from "effect"

// Function to apply a discount safely to a transaction amount
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// Simulated asynchronous task to fetch a transaction amount from database
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  // Log the fetched transaction amount
  Effect.tap((amount) => Console.log(`Apply a discount to: ${amount}`)),
  // `amount` is still available!
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// Output:
// Apply a discount to: 100
// 95
@see ― flatMap for a version that allows you to change the value.
@since ― 2.0.0
tap(
import Console
Console.
const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
log),
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const map: <number, number>(f: (a: number) => number) => <E, R>(self: Effect.Effect<number, E, R>) => Effect.Effect<number, E, R> (+1 overload)
Transforms the value inside an effect by applying a function to it.
Syntax
const mappedEffect = pipe(myEffect, Effect.map(transformation))
// or
const mappedEffect = Effect.map(myEffect, transformation)
// or
const mappedEffect = myEffect.pipe(Effect.map(transformation))
Details
map takes a function and applies it to the value contained within an
effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original
effect is not modified. Instead, a new effect is returned with the updated
value.
Example (Adding a Service Charge)
import { pipe, Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.map(addServiceCharge)
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 101
@see ― mapError for a version that operates on the error channel.
@see ― mapBoth for a version that operates on both channels.
@see ― flatMap or andThen for a version that can return a new effect.
@since ― 2.0.0
map((
x: number
x) => 
x: number
x + 1),
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const tap: <number, Effect.Effect<void, never, never>>(f: (a: number) => Effect.Effect<void, never, never>) => <E, R>(self: Effect.Effect<number, E, R>) => Effect.Effect<...> (+7 overloads)
Runs a side effect with the result of an effect without changing the original
value.
Details
This function works similarly to flatMap, but it ignores the result of the
function passed to it. The value from the previous effect remains available
for the next part of the chain. Note that if the side effect fails, the
entire chain will fail too.
When to Use
Use this function when you want to perform a side effect, like logging or
tracking, without modifying the main value. This is useful when you need to
observe or record an action but want the original value to be passed to the
next step.
Example (Logging a step in a pipeline)
import { Console, Effect, pipe } from "effect"

// Function to apply a discount safely to a transaction amount
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// Simulated asynchronous task to fetch a transaction amount from database
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  // Log the fetched transaction amount
  Effect.tap((amount) => Console.log(`Apply a discount to: ${amount}`)),
  // `amount` is still available!
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// Output:
// Apply a discount to: 100
// 95
@see ― flatMap for a version that allows you to change the value.
@since ― 2.0.0
tap((
x: number
x) => 
import Console
Console.
const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
log(`Now x is ${
x: number
x}`)),
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const map: <number, number>(f: (a: number) => number) => <E, R>(self: Effect.Effect<number, E, R>) => Effect.Effect<number, E, R> (+1 overload)
Transforms the value inside an effect by applying a function to it.
Syntax
const mappedEffect = pipe(myEffect, Effect.map(transformation))
// or
const mappedEffect = Effect.map(myEffect, transformation)
// or
const mappedEffect = myEffect.pipe(Effect.map(transformation))
Details
map takes a function and applies it to the value contained within an
effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original
effect is not modified. Instead, a new effect is returned with the updated
value.
Example (Adding a Service Charge)
import { pipe, Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.map(addServiceCharge)
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 101
@see ― mapError for a version that operates on the error channel.
@see ― mapBoth for a version that operates on both channels.
@see ― flatMap or andThen for a version that can return a new effect.
@since ― 2.0.0
map((
x: number
x) => 
x: number
x + 1),
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const zipLeft: <void, never, never>(that: Effect.Effect<void, never, never>, options?: {
    readonly concurrent?: boolean | undefined;
    readonly batching?: boolean | "inherit" | undefined;
    readonly concurrentFinalizers?: boolean | undefined;
} | undefined) => <A, E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+1 overload)
Executes two effects sequentially, returning the result of the first effect
and ignoring the result of the second.
Details
This function allows you to run two effects in sequence, where the result of
the first effect is preserved, and the result of the second effect is
discarded. By default, the two effects are executed sequentially. If you need
them to run concurrently, you can pass the { concurrent: true } option.
The second effect will always be executed, even though its result is ignored.
This makes it useful for cases where you want to execute an effect for its
side effects while keeping the result of another effect.
When to Use
Use this function when you are only interested in the result of the first
effect but still need to run the second effect for its side effects, such as
logging or performing a cleanup action.
Example
import { Effect } from "effect"

const task1 = Effect.succeed(1).pipe(
  Effect.delay("200 millis"),
  Effect.tap(Effect.log("task1 done"))
)
const task2 = Effect.succeed("hello").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Effect.log("task2 done"))
)

const program = Effect.zipLeft(task1, task2)

Effect.runPromise(program).then(console.log)
// Output:
// timestamp=... level=INFO fiber=#0 message="task1 done"
// timestamp=... level=INFO fiber=#0 message="task2 done"
// 1
@see ― zipRight for a version that returns the result of the second
effect.
@since ― 2.0.0
zipLeft(
import Console
Console.
const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
log("This will be printed when x is 3")),
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const map: <number, number>(f: (a: number) => number) => <E, R>(self: Effect.Effect<number, E, R>) => Effect.Effect<number, E, R> (+1 overload)
Transforms the value inside an effect by applying a function to it.
Syntax
const mappedEffect = pipe(myEffect, Effect.map(transformation))
// or
const mappedEffect = Effect.map(myEffect, transformation)
// or
const mappedEffect = myEffect.pipe(Effect.map(transformation))
Details
map takes a function and applies it to the value contained within an
effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original
effect is not modified. Instead, a new effect is returned with the updated
value.
Example (Adding a Service Charge)
import { pipe, Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.map(addServiceCharge)
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 101
@see ― mapError for a version that operates on the error channel.
@see ― mapBoth for a version that operates on both channels.
@see ― flatMap or andThen for a version that can return a new effect.
@since ― 2.0.0
map((
x: number
x) => 
x: number
x + 1)
);

import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runSync: <number, never>(effect: Effect.Effect<number, never, never>) => number
Executes an effect synchronously, running it immediately and returning the
result.
Details
This function evaluates the provided effect synchronously, returning its
result directly. It is ideal for effects that do not fail or include
asynchronous operations. If the effect does fail or involves async tasks, it
will throw an error. Execution stops at the point of failure or asynchronous
operation, making it unsuitable for effects that require asynchronous
handling.
Important: Attempting to run effects that involve asynchronous operations
or failures will result in exceptions being thrown, so use this function with
care for purely synchronous and error-free effects.
When to Use
Use this function when:

You are sure that the effect will not fail or involve asynchronous
operations.
You need a direct, synchronous result from the effect.
You are working within a context where asynchronous effects are not
allowed.

Avoid using this function for effects that can fail or require asynchronous
handling. For such cases, consider using
runPromise
or
runSyncExit
.
Example (Synchronous Logging)
import { Effect } from "effect"

const program = Effect.sync(() => {
  console.log("Hello, World!")
  return 1
})

const result = Effect.runSync(program)
// Output: Hello, World!

console.log(result)
// Output: 1
Example (Incorrect Usage with Failing or Async Effects)
import { Effect } from "effect"

try {
  // Attempt to run an effect that fails
  Effect.runSync(Effect.fail("my error"))
} catch (e) {
  console.error(e)
}
// Output:
// (FiberFailure) Error: my error

try {
  // Attempt to run an effect that involves async work
  Effect.runSync(Effect.promise(() => Promise.resolve(1)))
} catch (e) {
  console.error(e)
}
// Output:
// (FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
@see ― runSyncExit for a version that returns an Exit type instead of
throwing an error.
@since ― 2.0.0
runSync(
const program: Effect.Effect<number, never, never>
program);

This will print

1
Now x is 2
This will be printed when x is 3

Console has other benefits beyond lazy execution and pipe-friendly ergonomics. Just like any other service, we can swap out the implementation. For example, we may want to provide a special TestConsole implementation to check logs during tests. We could also provide a custom Console that changes the format of log messages, perhaps by automatically adding a timestamp, or converting all messages to a JSON format for structured logging.

Effect v3.x implements these “default services” using a FiberRef. This may change in Effect v4.0. We won’t go into too much detail on this, since we haven’t yet covered Fibers or Refs. For now, it is enough to know that somewhere behind the scenes, a concrete default implementation of the Console is being provided.

We can implement an approximate version of Console.log using the tools we have learned so far.

import { Context, Effect, Layer } from "effect";

interface ConsoleShape {
  log: (...args: ReadonlyArray<unknown>) => Effect.Effect<void>;
}

const instance = {
  log: (...args) => Effect.sync(() => console.log(...args)),
} satisfies ConsoleShape;

export class Console extends Context.Tag("@fred.c/Console")<
  Console,
  ConsoleShape
>() {
  static Live = Layer.succeed(this, instance);

  static log = (...args: ReadonlyArray<unknown>) =>
    this.pipe(Effect.flatMap((svc) => svc.log(...args)));
}

This Console service is almost the same as the real one, except that we need to explicitly provide the implementation in order to run the program.

import { Effect } from "effect";

import { Console } from "./Console";

const program = Effect.succeed(0).pipe(
  Effect.map((x) => x + 1),
  Effect.tap(Console.log),
  Effect.map((x) => x + 1),
  Effect.tap((x) => Console.log(`Now x is ${x}`)),
  Effect.map((x) => x + 1),
  Effect.zipLeft(Console.log("This will be printed when x is 3")),
  Effect.map((x) => x + 1)
);

program.pipe(
  Effect.provide(Console.Live), // this is the only difference
  Effect.runSync
);

Effect.asVoid

Console.error