Basic Effect programs

This is the 2nd entry in the Effect Series. The previous entry is a general introduction to Effect.

TL;DR
  • Effect.gen(function* () {}) creates Effects
  • Effect.fn('some-name')(function*() {}) creates functions that return Effects, and will create a span that is used for tracing and for a better stack trace
  • Effects can be composed by yield*ing an Effect inside an Effect
  • Data.TaggedError creates error classes that can be caught with Effect.catchTag
  • Effect.catchTag will remove caught tags from the resulting Effect’s type

Our first Effect program

Note

This is intended as a gradual introduction to Effect. Examples might be correct, but they are not intended to represent the “best” way to write a program. We do get there gradually, though.

Let’s write and execute some small programs, looking at the types.

import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from 'effect';


const 
const program: Effect.Effect<string, never, never>
program = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <never, string>(f: (resume: Effect.Adapter) => Generator<never, string, never>) => Effect.Effect<string, never, never> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.


When to Use


Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.


The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.


Example


import { Effect } from "effect"


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


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)


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


const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))


export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function*() {
  return 'Hello Effect!'
})
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <string, never>(effect: Effect.Effect<string, never, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<string>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(program).
Promise<string>.then<void, never>(onfulfilled?: ((value: string) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log).
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error)
const program: Effect.Effect<string, never, never>
// logs "Hello Effect!"

The type of program tells us it will return a string, it won’t fail, and it has no dependencies.

Effect.runPromise(program) returns a Promise with the result of the program.

Tip

Effect.gen lets you create an Effect with a block of code. For the case above we could have also used const program = Effect.succeed('Hello Effect!').

Now we’ll take a name. To do that, we will create a function that returns an Effect. () => Effect.gen would do that, but there is a more idiomatic way that will also get you a lot of the observability advantages for free: Effect.fn.

import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from 'effect';


const 
const sayHi: (name: string) => Effect.Effect<string, never, never>
sayHi = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: <never, string, [name: string]>(body: (name: string) => Generator<never, string, never>) => (name: string) => Effect.Effect<string, never, never> (+20 overloads)
fn(function* (
name: string
name: string) {
  return `Hello ${
name: string
name}!`;
})


import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <string, never>(effect: Effect.Effect<string, never, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<string>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(sayHi('Effect'))
const sayHi: (name: string) => Effect.Effect<string, never, never>
  .
Promise<string>.then<void, never>(onfulfilled?: ((value: string) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);
// logs "Hello Effect!"

The equivalent with Promises:

const 
const sayHi: (name: string) => Promise<string>
sayHi = async function(
name: string
name: string) {
  return `Hello ${
name: string
name}!`;
}


sayHi('Promise')
const sayHi: (name: string) => Promise<string>
  .
Promise<string>.then<void, never>(onfulfilled?: ((value: string) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);
// logs "Hello Promise!"

Definitely Promise is a bit simpler, but the simplest happy path is not where Effect shines.

Composing Effects

Your Effect programs can be made out of many Effects. You can describe obtaining the computation of an Effect with yield*. This is akin to await in the case of Promises.

import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from 'effect';


const 
const getPerson: Effect.Effect<{
    name: string;
}, never, never>
getPerson = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const succeed: <{
    name: string;
}>(value: {
    name: string;
}) => Effect.Effect<{
    name: string;
}, 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({ 
name: string
name: 'Effect' })


const 
const sayHi: (name: string) => Effect.Effect<string, never, never>
sayHi = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: <never, string, [name: string]>(body: (name: string) => Generator<never, string, never>) => (name: string) => Effect.Effect<string, never, never> (+20 overloads)
fn(function* (
name: string
name: string) {
  return `Hello ${
name: string
name}!`;
})


const 
const program: Effect.Effect<string, never, never>
program = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Effect.Effect<{
    name: string;
}, never, never>> | YieldWrap<Effect.Effect<string, never, never>>, string>(f: (resume: Effect.Adapter) => Generator<YieldWrap<Effect.Effect<{
    name: string;
}, never, never>> | YieldWrap<Effect.Effect<string, never, never>>, string, never>) => Effect.Effect<string, never, never> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.


When to Use


Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.


The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.


Example


import { Effect } from "effect"


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


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)


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


const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))


export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function*() {
  const 
const person: {
    name: string;
}
person = yield* 
const getPerson: Effect.Effect<{
    name: string;
}, never, never>
getPerson;
  const 
const message: string
message = yield* 
const sayHi: (name: string) => Effect.Effect<string, never, never>
sayHi(
const person: {
    name: string;
}
person.
name: string
name);
  return 
const message: string
message;
})


import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <string, never>(effect: Effect.Effect<string, never, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<string>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(
const program: Effect.Effect<string, never, never>
program)
  .
Promise<string>.then<void, never>(onfulfilled?: ((value: string) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);

You can imagine getPerson reaching to the database for information, for example. Down the line, we’ll learn how to make some of these Effects run concurrently.

In many cases, a whole application is a single Effect composed of many other Effects. For example, an HTTP Server Effect will rely on other Effects to handle routes, and each route will rely on other Effects to reach to the database, and perform operations.

Reminder

In the code example above, program is just a description of the computation. To run it, you need to pass it through Effect.runPromise.

Errors

We already covered that Effect tracks errors. To recap: the second type argument of an Effect is the error channel. We can use this channel to declare what recoverable errors an Effect may result in—or never for no errors.

Tracking errors allows you to ensure each error is handled correctly. This is very important as errors, especially business errors, are a necessary part of a program, but they are often an after-thought. Even if a program initially declares and handles errors perfectly, this will certainly degrade with time. Tracking errors at the type level ensures errors are never forgotten.

Now, to be clear, there is always the possibility of an error. So many things can go wrong that you won’t control. In Effect, these are called unexpected or unrecoverable errors, or defects.

To summarize:

  • Failure: A recoverable error that is tracked at the type level. You can create one with Effect.fail.
  • Defect: An unexpected error that is not tracked at the type level. You can think of them as unrecoverable, even though Effect still provides tools to capture them if necessary. You may produce a defect with Effect.die.

Here we’ll focus on how to create and recover from failures.

A simple error

Let’s look at an example with an error.

import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from 'effect';


class 
class DivisionByZeroError
DivisionByZeroError extends 
var Error: ErrorConstructor
Error {}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: <YieldWrap<Effect.Effect<never, DivisionByZeroError, never>>, number, [n1: number, n2: number]>(body: (n1: number, n2: number) => Generator<YieldWrap<Effect.Effect<never, DivisionByZeroError, never>>, number, never>) => (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never> (+20 overloads)
fn(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <DivisionByZeroError>(error: DivisionByZeroError) => Effect.Effect<never, DivisionByZeroError, never>
Creates an Effect that represents a recoverable error.


When to Use


Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like


catchAll


or


catchTag


.


Example (Creating a Failed Effect)


import { Effect } from "effect"


//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@see ― succeed to create an effect that represents a successful value.
@since ― 2.0.0
fail(new 
constructor DivisionByZeroError(message?: string): DivisionByZeroError
DivisionByZeroError("Can't divide by 0, silly!"));
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <number, DivisionByZeroError>(effect: Effect.Effect<number, DivisionByZeroError, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<number>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(divide(5, 0))
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
  .
Promise<number>.then<void, never>(onfulfilled?: ((value: number) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);

Note the return type: Effect<number, DivisionByZeroError, never>. We know that this program may fail and exactly how at the type level.

If we run the program, this will be logged:

(FiberFailure) Error: Can't divide by 0, silly!
    at <anonymous> (index.ts:6:31)
    at <anonymous> (index.ts:4:23)
    at <anonymous> (index.ts:13:19)

Depending on your JavaScript runtime (node, bun, deno) and the version, you might get more or less useful details, including the error name. Still, the stack trace is definitely not ideal. This is because anything that needs to manage the execution of a program (a runtime), will mess with your stack trace. This is a little bit the case with Promise, but you might have also had to deal with long and unhelpful stack-traces in React, which also manages its own execution cycle.

Let’s compare with an equivalent Promise-based program:

class 
class DivisionByZeroError
DivisionByZeroError extends 
var Error: ErrorConstructor
Error {}


const 
const divide: (n1: number, n2: number) => Promise<number>
divide = async (
n1: number
n1: number, 
n2: number
n2: number) => {
  if (
n2: number
n2 === 0) {
    throw new 
constructor DivisionByZeroError(message?: string): DivisionByZeroError
DivisionByZeroError("Can't divide by 0, silly!");
  }
  return 
n1: number
n1 / 
n2: number
n2;
}


divide(5, 0)
const divide: (n1: number, n2: number) => Promise<number>
  .
Promise<number>.then<void, never>(onfulfilled?: ((value: number) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);

This will be logged:

DivisionByZeroError: Can't divide by 0, silly!
    at divide (index.ts:20:11)
    at <anonymous> (index.ts:25:1)
    at ModuleJob.run (node:internal/modules/esm/module_job:377:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:691:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

It does have a lot of stuff, but it does tell us about the specific error (DivisionByZeroError) and the divide function.

While I could argue that the unideal stack trace from Effect is a necessary evil, again, because we need to go through a runtime on top of the JavaScript runtime, I am happy to report that Effect gives us tools to not just solve this problem, but get additional observability benefits. Let’s transform Effect.fn(body) to Effect.fn(name)(body):

import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from 'effect';


class 
class DivisionByZeroError
DivisionByZeroError extends 
var Error: ErrorConstructor
Error {}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <DivisionByZeroError>(error: DivisionByZeroError) => Effect.Effect<never, DivisionByZeroError, never>
Creates an Effect that represents a recoverable error.


When to Use


Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like


catchAll


or


catchTag


.


Example (Creating a Failed Effect)


import { Effect } from "effect"


//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@see ― succeed to create an effect that represents a successful value.
@since ― 2.0.0
fail(new 
constructor DivisionByZeroError(message?: string): DivisionByZeroError
DivisionByZeroError("Can't divide by 0, silly!"));
  }
  return 
n1: number
n1 / 
n2: number
n2;
})
4 collapsed lines


import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <number, DivisionByZeroError>(effect: Effect.Effect<number, DivisionByZeroError, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<number>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(5, 0))
  .
Promise<number>.then<void, never>(onfulfilled?: ((value: number) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);

Just with that little change, the logged output in case of error fails:

(FiberFailure) Error: Can't divide by 0, silly!
    at <anonymous> (index.ts:6:31)
    at divide (index.ts:4:23)
    at divide (index.ts:13:19)

And, importantly, a divide span has been created. With the built-in observability tooling, this means you get detailed traces and logs for all your Effects. I’ll cover observability in detail later.

Tip

Effect automatically accumulates errors as you compose Effects. Your Effect will have the errors that it specifically fails with, as well as the errors of any Effect it calls—unless you handle them.

Catching errors

Now let’s take advantage that Effect tracks errors at the type level. We know there will be an error, so let’s catch it:

10 collapsed lines
import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from 'effect';


class 
class DivisionByZeroError
DivisionByZeroError extends 
var Error: ErrorConstructor
Error {}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <DivisionByZeroError>(error: DivisionByZeroError) => Effect.Effect<never, DivisionByZeroError, never>
Creates an Effect that represents a recoverable error.


When to Use


Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like


catchAll


or


catchTag


.


Example (Creating a Failed Effect)


import { Effect } from "effect"


//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@see ― succeed to create an effect that represents a successful value.
@since ― 2.0.0
fail(new 
constructor DivisionByZeroError(message?: string): DivisionByZeroError
DivisionByZeroError("Can't divide by 0, silly!"));
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


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 catchAll: <number, DivisionByZeroError, never, number, never, never>(self: Effect.Effect<number, DivisionByZeroError, never>, f: (e: DivisionByZeroError) => Effect.Effect<number, never, never>) => Effect.Effect<number, never, never> (+1 overload)
Handles all errors in an effect by providing a fallback effect.


Details


This function catches any errors that may occur during the execution of an
effect and allows you to handle them by specifying a fallback effect. This
ensures that the program continues without failing by recovering from errors
using the provided fallback logic.


Note: This function only handles recoverable errors. It will not recover
from unrecoverable defects.


Example (Providing Recovery Logic for Recoverable Errors)


import { Effect, Random } from "effect"


class HttpError {
  readonly _tag = "HttpError"
}


class ValidationError {
  readonly _tag = "ValidationError"
}


//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})


//      ┌─── Effect<string, never, never>
//      ▼
const recovered = program.pipe(
  Effect.catchAll((error) =>
    Effect.succeed(`Recovering from ${error._tag}`)
  )
)
@see ― catchAllCause for a version that can recover from both
recoverable and unrecoverable errors.
@since ― 2.0.0
catchAll(
  divide(5, 0),
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
  // the "catch" body, if Effect fails
  (
_error: DivisionByZeroError
_error) => 
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)
)


import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <number, never>(effect: Effect.Effect<number, never, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<number>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(program)
const program: Effect.Effect<number, never, never>
  .
Promise<number>.then<void, never>(onfulfilled?: ((value: number) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);
// Will log: 0

Note how the return type of divide has DivisionByZeroError as a possible error, but that has disappeared from the type of program:

Effect<number, DivisionByZeroError, never> -> Effect.catchAll -> Effect<number, never, never>

Catching specific errors

More typically, we’d want to catch specific errors and handle them distinctly. Effect provides a number of methods to do that.

  • Effect.catchTag: catch errors with a specific tag
  • Effect.catchTags: catch errors with a different recovery function for each given tag
  • Effect.catchIf: catch errors that fulfill the given predicate

Effect provides an easy way to “tag” errors: Data.TaggedError. Tagged errors declared that way are yieldable, which means you can yield* them directly, without wrapping them in Effect.fail.

A better way to write the division program using tagged errors would be:

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


class 
class DivisionByZeroError
DivisionByZeroError extends 
import Data
Data.
const TaggedError: <"DivisionByZeroError">(tag: "DivisionByZeroError") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "DivisionByZeroError";
} & Readonly<A>
@since ― 2.0.0
TaggedError('DivisionByZeroError') {
  override readonly 
DivisionByZeroError.message: "Can't divide by 0, silly!"
message = "Can't divide by 0, silly!";
}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* new 
constructor DivisionByZeroError<{}>(args: void): DivisionByZeroError
DivisionByZeroError();
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


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 catchTag: <number, DivisionByZeroError, never, ["DivisionByZeroError"], number, never, never>(self: Effect.Effect<number, DivisionByZeroError, never>, args_0: "DivisionByZeroError", f: (e: DivisionByZeroError) => Effect.Effect<number, never, never>) => Effect.Effect<number, never, never> (+1 overload)
Catches and handles specific errors by their _tag field, which is used as a
discriminator.


When to Use


catchTag is useful when your errors are tagged with a readonly _tag field
that identifies the error type. You can use this function to handle specific
error types by matching the _tag value. This allows for precise error
handling, ensuring that only specific errors are caught and handled.


The error type must have a readonly _tag field to use catchTag. This
field is used to identify and match errors.


Example (Handling Errors by Tag)


import { Effect, Random } from "effect"


class HttpError {
  readonly _tag = "HttpError"
}


class ValidationError {
  readonly _tag = "ValidationError"
}


//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})


//      ┌─── Effect<string, ValidationError, never>
//      ▼
const recovered = program.pipe(
  // Only handle HttpError errors
  Effect.catchTag("HttpError", (_HttpError) =>
    Effect.succeed("Recovering from HttpError")
  )
)
@see ― catchTags for a version that allows you to handle multiple error
types at once.
@since ― 2.0.0
catchTag(
  
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(5, 0),
  'DivisionByZeroError',
  () => 
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)
);


import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <number, never>(effect: Effect.Effect<number, never, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<number>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(program)
const program: Effect.Effect<number, never, never>
  .
Promise<number>.then<void, never>(onfulfilled?: ((value: number) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);
// Logs 0

Like in the previous example, program can only succeed with a number.

If our program had other errors, they would persist in the error channel (the type), because we are not handling them. For example, if divide took strings and attempted to parse them into numbers, which could result in a ParseError. divide could therefore error with DivisionByZeroError | ParseError. If we still catch DivisionByZero, we end up with a program that may only fail with ParseError, and we see that at the type level:

17 collapsed lines
import { 
import Data
Data, 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Schema
Schema } from "effect"


class 
class DivisionByZeroError
DivisionByZeroError extends 
import Data
Data.
const TaggedError: <"DivisionByZeroError">(tag: "DivisionByZeroError") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "DivisionByZeroError";
} & Readonly<A>
@since ― 2.0.0
TaggedError("DivisionByZeroError") {
  override readonly 
DivisionByZeroError.message: "Can't divide by 0, silly!"
message = "Can't divide by 0, silly!"
}


const 
const parseNum: (i: string, overrideOptions?: ParseOptions) => Effect.Effect<number, ParseError, never>
parseNum = 
import Schema
Schema.
const decode: <number, string, never>(schema: Schema.Schema<number, string, never>, options?: ParseOptions) => (i: string, overrideOptions?: ParseOptions) => Effect.Effect<number, ParseError, never>
@since ― 3.10.0
decode(
import Schema
Schema.
class NumberFromString
This schema transforms a string into a number by parsing the string using the parse function of the effect/Number module.


It returns an error if the value can't be converted (for example when non-numeric characters are provided).


The following special string values are supported: "NaN", "Infinity", "-Infinity".
@since ― 3.10.0
NumberFromString);


const 
const divide: (input1: string, input2: string) => Effect.Effect<number, DivisionByZeroError | ParseError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn("divide")(function*(
input1: string
input1: string, 
input2: string
input2: string) {
  const 
const n1: number
n1 = yield* 
const parseNum: (i: string, overrideOptions?: ParseOptions) => Effect.Effect<number, ParseError, never>
parseNum(
input1: string
input1)
  const 
const n2: number
n2 = yield* 
const parseNum: (i: string, overrideOptions?: ParseOptions) => Effect.Effect<number, ParseError, never>
parseNum(
input2: string
input2)
  if (
const n2: number
n2 === 0) {
    return yield* new 
constructor DivisionByZeroError<{}>(args: void): DivisionByZeroError
DivisionByZeroError()
  }


  return 
const n1: number
n1 / 
const n2: number
n2
})


const 
const program: Effect.Effect<number, ParseError, never>
program = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const catchTag: <number, DivisionByZeroError | ParseError, never, ["DivisionByZeroError"], number, never, never>(self: Effect.Effect<number, DivisionByZeroError | ParseError, never>, args_0: "DivisionByZeroError", f: (e: DivisionByZeroError) => Effect.Effect<number, never, never>) => Effect.Effect<number, ParseError, never> (+1 overload)
Catches and handles specific errors by their _tag field, which is used as a
discriminator.


When to Use


catchTag is useful when your errors are tagged with a readonly _tag field
that identifies the error type. You can use this function to handle specific
error types by matching the _tag value. This allows for precise error
handling, ensuring that only specific errors are caught and handled.


The error type must have a readonly _tag field to use catchTag. This
field is used to identify and match errors.


Example (Handling Errors by Tag)


import { Effect, Random } from "effect"


class HttpError {
  readonly _tag = "HttpError"
}


class ValidationError {
  readonly _tag = "ValidationError"
}


//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})


//      ┌─── Effect<string, ValidationError, never>
//      ▼
const recovered = program.pipe(
  // Only handle HttpError errors
  Effect.catchTag("HttpError", (_HttpError) =>
    Effect.succeed("Recovering from HttpError")
  )
)
@see ― catchTags for a version that allows you to handle multiple error
types at once.
@since ― 2.0.0
catchTag(
  divide("2", "foo"),
const divide: (input1: string, input2: string) => Effect.Effect<number, DivisionByZeroError | ParseError, never>
  "DivisionByZeroError",
  () => 
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)
)


import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <number, ParseError>(effect: Effect.Effect<number, ParseError, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<number>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(program)
const program: Effect.Effect<number, ParseError, never>
  .
Promise<number>.then<void, never>(onfulfilled?: ((value: number) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);

When run, this program will result in a ParseError error.

Tip

If you expand the above example, you’ll get a glimpse of Effect Schema, which takes care of parsing the string into a number, and failing with ParseError. I’ll cover Schema in a future post.

You own the error channel

Because errors are tracked at the type level, if you wanted, you could enforce that all errors should be handled at some level, by expecting a never in the error channel. Here we can see TypeScript complaining because DivisionByZeroError is not handled.

12 collapsed lines
import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Data
Data } from "effect"


class 
class DivisionByZeroError
DivisionByZeroError extends 
import Data
Data.
const TaggedError: <"DivisionByZeroError">(tag: "DivisionByZeroError") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "DivisionByZeroError";
} & Readonly<A>
@since ― 2.0.0
TaggedError('DivisionByZeroError') {
  override readonly 
DivisionByZeroError.message: "Can't divide by 0, silly!"
message = "Can't divide by 0, silly!";
}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* new 
constructor DivisionByZeroError<{}>(args: void): DivisionByZeroError
DivisionByZeroError();
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


const successEffect: 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
interface Effect<out A, out E = never, out R = never>
The Effect interface defines a value that describes a workflow or job,
which can succeed or fail.


Details


The Effect interface represents a computation that can model a workflow
involving various types of operations, such as synchronous, asynchronous,
concurrent, and parallel interactions. It operates within a context of type
R, and the result can either be a success with a value of type A or a
failure with an error of type E. The Effect is designed to handle complex
interactions with external resources, offering advanced features such as
fiber-based concurrency, scheduling, interruption handling, and scalability.
This makes it suitable for tasks that require fine-grained control over
concurrency and error management.


To execute an Effect value, you need a Runtime, which provides the
environment necessary to run and manage the computation.
@since ― 2.0.0
@since ― 2.0.0
Effect<number, never> = 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(2, 1);
Error ts(2375)  ― Type 'Effect<number, DivisionByZeroError, never>' is not assignable to type 'Effect<number, never, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
  Type 'DivisionByZeroError' is not assignable to type 'never'.

We can fix it by catching DivisionByZeroError, like we saw before:

12 collapsed lines
import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Data
Data } from "effect"


class 
class DivisionByZeroError
DivisionByZeroError extends 
import Data
Data.
const TaggedError: <"DivisionByZeroError">(tag: "DivisionByZeroError") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "DivisionByZeroError";
} & Readonly<A>
@since ― 2.0.0
TaggedError('DivisionByZeroError') {
  override readonly 
DivisionByZeroError.message: "Can't divide by 0, silly!"
message = "Can't divide by 0, silly!";
}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* new 
constructor DivisionByZeroError<{}>(args: void): DivisionByZeroError
DivisionByZeroError();
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


const 
const successEffect: Effect.Effect<number, never, never>
successEffect: 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
interface Effect<out A, out E = never, out R = never>
The Effect interface defines a value that describes a workflow or job,
which can succeed or fail.


Details


The Effect interface represents a computation that can model a workflow
involving various types of operations, such as synchronous, asynchronous,
concurrent, and parallel interactions. It operates within a context of type
R, and the result can either be a success with a value of type A or a
failure with an error of type E. The Effect is designed to handle complex
interactions with external resources, offering advanced features such as
fiber-based concurrency, scheduling, interruption handling, and scalability.
This makes it suitable for tasks that require fine-grained control over
concurrency and error management.


To execute an Effect value, you need a Runtime, which provides the
environment necessary to run and manage the computation.
@since ― 2.0.0
@since ― 2.0.0
Effect<number, never> = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const catchTag: <number, DivisionByZeroError, never, ["DivisionByZeroError"], number, never, never>(self: Effect.Effect<number, DivisionByZeroError, never>, args_0: "DivisionByZeroError", f: (e: DivisionByZeroError) => Effect.Effect<number, never, never>) => Effect.Effect<number, never, never> (+1 overload)
Catches and handles specific errors by their _tag field, which is used as a
discriminator.


When to Use


catchTag is useful when your errors are tagged with a readonly _tag field
that identifies the error type. You can use this function to handle specific
error types by matching the _tag value. This allows for precise error
handling, ensuring that only specific errors are caught and handled.


The error type must have a readonly _tag field to use catchTag. This
field is used to identify and match errors.


Example (Handling Errors by Tag)


import { Effect, Random } from "effect"


class HttpError {
  readonly _tag = "HttpError"
}


class ValidationError {
  readonly _tag = "ValidationError"
}


//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})


//      ┌─── Effect<string, ValidationError, never>
//      ▼
const recovered = program.pipe(
  // Only handle HttpError errors
  Effect.catchTag("HttpError", (_HttpError) =>
    Effect.succeed("Recovering from HttpError")
  )
)
@see ― catchTags for a version that allows you to handle multiple error
types at once.
@since ― 2.0.0
catchTag(
  
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(2, 1),
  'DivisionByZeroError',
  () => 
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)
);

In a similar fashion, you could require that all your errors are mapped to HTTP errors at the route handler level. In the following example, you can see how TypeScript complains because we have a DivisionByZeroError, which is not one of the expected HttpErrors.

20 collapsed lines
import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Data
Data } from "effect"


class 
class DivisionByZeroError
DivisionByZeroError extends 
import Data
Data.
const TaggedError: <"DivisionByZeroError">(tag: "DivisionByZeroError") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "DivisionByZeroError";
} & Readonly<A>
@since ― 2.0.0
TaggedError('DivisionByZeroError') {
  override readonly 
DivisionByZeroError.message: "Can't divide by 0, silly!"
message = "Can't divide by 0, silly!";
}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* new 
constructor DivisionByZeroError<{}>(args: void): DivisionByZeroError
DivisionByZeroError();
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


class 
class Http400
Http400 extends 
import Data
Data.
const TaggedError: <"Http400">(tag: "Http400") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http400";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http400') {}
class 
class Http401
Http401 extends 
import Data
Data.
const TaggedError: <"Http401">(tag: "Http401") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http401";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http401') {}
class 
class Http402
Http402 extends 
import Data
Data.
const TaggedError: <"Http402">(tag: "Http402") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http402";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http402') {}
class 
class Http403
Http403 extends 
import Data
Data.
const TaggedError: <"Http403">(tag: "Http403") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http403";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http403') {}
class 
class Http404
Http404 extends 
import Data
Data.
const TaggedError: <"Http404">(tag: "Http404") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http404";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http404') {}


type 
type HttpError = Http400 | Http401 | Http402 | Http403 | Http404
HttpError = 
class Http400
Http400 | 
class Http401
Http401 | 
class Http402
Http402 | 
class Http403
Http403 | 
class Http404
Http404;


const routeHandler: 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
interface Effect<out A, out E = never, out R = never>
The Effect interface defines a value that describes a workflow or job,
which can succeed or fail.


Details


The Effect interface represents a computation that can model a workflow
involving various types of operations, such as synchronous, asynchronous,
concurrent, and parallel interactions. It operates within a context of type
R, and the result can either be a success with a value of type A or a
failure with an error of type E. The Effect is designed to handle complex
interactions with external resources, offering advanced features such as
fiber-based concurrency, scheduling, interruption handling, and scalability.
This makes it suitable for tasks that require fine-grained control over
concurrency and error management.


To execute an Effect value, you need a Runtime, which provides the
environment necessary to run and manage the computation.
@since ― 2.0.0
@since ― 2.0.0
Effect<number, 
type HttpError = Http400 | Http401 | Http402 | Http403 | Http404
HttpError> = 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(2, 1)
Error ts(2375)  ― Type 'Effect<number, DivisionByZeroError, never>' is not assignable to type 'Effect<number, HttpError, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
  Type 'DivisionByZeroError' is not assignable to type 'HttpError' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
    Type 'DivisionByZeroError' is not assignable to type 'Http404' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
      Types of property '_tag' are incompatible.
        Type '"DivisionByZeroError"' is not assignable to type '"Http404"'.

This way, route handlers are forced to think about errors, and make HTTP 500 errors go away, except for when things really are deeply broken.

You can fix the error by catching DivisionByZeroError like in earlier examples, either by making it a success or by mapping it to one of the accepted errors:

20 collapsed lines
import { 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Data
Data } from "effect"


class 
class DivisionByZeroError
DivisionByZeroError extends 
import Data
Data.
const TaggedError: <"DivisionByZeroError">(tag: "DivisionByZeroError") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "DivisionByZeroError";
} & Readonly<A>
@since ― 2.0.0
TaggedError('DivisionByZeroError') {
  override readonly 
DivisionByZeroError.message: "Can't divide by 0, silly!"
message = "Can't divide by 0, silly!";
}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  if (
n2: number
n2 === 0) {
    return yield* new 
constructor DivisionByZeroError<{}>(args: void): DivisionByZeroError
DivisionByZeroError();
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


class 
class Http400
Http400 extends 
import Data
Data.
const TaggedError: <"Http400">(tag: "Http400") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http400";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http400') {}
class 
class Http401
Http401 extends 
import Data
Data.
const TaggedError: <"Http401">(tag: "Http401") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http401";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http401') {}
class 
class Http402
Http402 extends 
import Data
Data.
const TaggedError: <"Http402">(tag: "Http402") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http402";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http402') {}
class 
class Http403
Http403 extends 
import Data
Data.
const TaggedError: <"Http403">(tag: "Http403") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http403";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http403') {}
class 
class Http404
Http404 extends 
import Data
Data.
const TaggedError: <"Http404">(tag: "Http404") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "Http404";
} & Readonly<A>
@since ― 2.0.0
TaggedError('Http404') {}


type 
type HttpError = Http400 | Http401 | Http402 | Http403 | Http404
HttpError = 
class Http400
Http400 | 
class Http401
Http401 | 
class Http402
Http402 | 
class Http403
Http403 | 
class Http404
Http404;


// An always successful effect is acceptable
const 
const option1: Effect.Effect<number, HttpError, never>
option1: 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
interface Effect<out A, out E = never, out R = never>
The Effect interface defines a value that describes a workflow or job,
which can succeed or fail.


Details


The Effect interface represents a computation that can model a workflow
involving various types of operations, such as synchronous, asynchronous,
concurrent, and parallel interactions. It operates within a context of type
R, and the result can either be a success with a value of type A or a
failure with an error of type E. The Effect is designed to handle complex
interactions with external resources, offering advanced features such as
fiber-based concurrency, scheduling, interruption handling, and scalability.
This makes it suitable for tasks that require fine-grained control over
concurrency and error management.


To execute an Effect value, you need a Runtime, which provides the
environment necessary to run and manage the computation.
@since ― 2.0.0
@since ― 2.0.0
Effect<number, 
type HttpError = Http400 | Http401 | Http402 | Http403 | Http404
HttpError> = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const catchTag: <number, DivisionByZeroError, never, ["DivisionByZeroError"], number, never, never>(self: Effect.Effect<number, DivisionByZeroError, never>, args_0: "DivisionByZeroError", f: (e: DivisionByZeroError) => Effect.Effect<number, never, never>) => Effect.Effect<number, never, never> (+1 overload)
Catches and handles specific errors by their _tag field, which is used as a
discriminator.


When to Use


catchTag is useful when your errors are tagged with a readonly _tag field
that identifies the error type. You can use this function to handle specific
error types by matching the _tag value. This allows for precise error
handling, ensuring that only specific errors are caught and handled.


The error type must have a readonly _tag field to use catchTag. This
field is used to identify and match errors.


Example (Handling Errors by Tag)


import { Effect, Random } from "effect"


class HttpError {
  readonly _tag = "HttpError"
}


class ValidationError {
  readonly _tag = "ValidationError"
}


//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})


//      ┌─── Effect<string, ValidationError, never>
//      ▼
const recovered = program.pipe(
  // Only handle HttpError errors
  Effect.catchTag("HttpError", (_HttpError) =>
    Effect.succeed("Recovering from HttpError")
  )
)
@see ― catchTags for a version that allows you to handle multiple error
types at once.
@since ― 2.0.0
catchTag(
  
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(2, 1),
  'DivisionByZeroError',
  () => 
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)
);


// And so is one that only fails with an HttpError
const 
const option2: Effect.Effect<number, HttpError, never>
option2: 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
interface Effect<out A, out E = never, out R = never>
The Effect interface defines a value that describes a workflow or job,
which can succeed or fail.


Details


The Effect interface represents a computation that can model a workflow
involving various types of operations, such as synchronous, asynchronous,
concurrent, and parallel interactions. It operates within a context of type
R, and the result can either be a success with a value of type A or a
failure with an error of type E. The Effect is designed to handle complex
interactions with external resources, offering advanced features such as
fiber-based concurrency, scheduling, interruption handling, and scalability.
This makes it suitable for tasks that require fine-grained control over
concurrency and error management.


To execute an Effect value, you need a Runtime, which provides the
environment necessary to run and manage the computation.
@since ― 2.0.0
@since ― 2.0.0
Effect<number, 
type HttpError = Http400 | Http401 | Http402 | Http403 | Http404
HttpError> = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const catchTag: <number, DivisionByZeroError, never, ["DivisionByZeroError"], never, Http400, never>(self: Effect.Effect<number, DivisionByZeroError, never>, args_0: "DivisionByZeroError", f: (e: DivisionByZeroError) => Effect.Effect<never, Http400, never>) => Effect.Effect<number, Http400, never> (+1 overload)
Catches and handles specific errors by their _tag field, which is used as a
discriminator.


When to Use


catchTag is useful when your errors are tagged with a readonly _tag field
that identifies the error type. You can use this function to handle specific
error types by matching the _tag value. This allows for precise error
handling, ensuring that only specific errors are caught and handled.


The error type must have a readonly _tag field to use catchTag. This
field is used to identify and match errors.


Example (Handling Errors by Tag)


import { Effect, Random } from "effect"


class HttpError {
  readonly _tag = "HttpError"
}


class ValidationError {
  readonly _tag = "ValidationError"
}


//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})


//      ┌─── Effect<string, ValidationError, never>
//      ▼
const recovered = program.pipe(
  // Only handle HttpError errors
  Effect.catchTag("HttpError", (_HttpError) =>
    Effect.succeed("Recovering from HttpError")
  )
)
@see ― catchTags for a version that allows you to handle multiple error
types at once.
@since ― 2.0.0
catchTag(
  
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(2, 1),
  'DivisionByZeroError',
  () => 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fail: <Http400>(error: Http400) => Effect.Effect<never, Http400, never>
Creates an Effect that represents a recoverable error.


When to Use


Use this function to explicitly signal an error in an Effect. The error
will keep propagating unless it is handled. You can handle the error with
functions like


catchAll


or


catchTag


.


Example (Creating a Failed Effect)


import { Effect } from "effect"


//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)
@see ― succeed to create an effect that represents a successful value.
@since ― 2.0.0
fail(new 
constructor Http400<{}>(args: void): Http400
Http400())
);

Consider how much of your non-Effect code depends on engineers correctly handling everything that is not the happy path. Effect forces you to consider errors, which are always part of your domain.

Bonus: Retrying and Timing Out

The following is just to get some hype going on what you can do if you have modeled your program as an Effect. Note we are adding a log line inside divide.

import { 
import Data
Data, 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Schedule
Schedule } from 'effect';


3 collapsed lines
class 
class DivisionByZeroError
DivisionByZeroError extends 
import Data
Data.
const TaggedError: <"DivisionByZeroError">(tag: "DivisionByZeroError") => new <A>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
    readonly _tag: "DivisionByZeroError";
} & Readonly<A>
@since ― 2.0.0
TaggedError('DivisionByZeroError') {
  override readonly 
DivisionByZeroError.message: "Can't divide by 0, silly!"
message = "Can't divide by 0, silly!";
}


const 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide = 
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn('divide')(function* (
n1: number
n1: number, 
n2: number
n2: number) {
  
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log('Trying to divide', 
n1: number
n1, 
n2: number
n2);
  if (
n2: number
n2 === 0) {
    return yield* new 
constructor DivisionByZeroError<{}>(args: void): DivisionByZeroError
DivisionByZeroError();
  }
  return 
n1: number
n1 / 
n2: number
n2;
})


const 
const schedule: Schedule.Schedule<[Duration, number], unknown, never>
schedule = 
import Schedule
Schedule.
const intersect: <Duration, unknown, never, number, unknown, never>(self: Schedule.Schedule<Duration, unknown, never>, that: Schedule.Schedule<number, unknown, never>) => Schedule.Schedule<[Duration, number], unknown, never> (+1 overload)
Combines two schedules, continuing only if both schedules want to continue,
using the longer delay.


Details


This function takes two schedules and creates a new schedule that only
continues execution if both schedules allow it. The interval between
recurrences is determined by the longer delay between the two schedules.


The output of the resulting schedule is a tuple containing the outputs of
both schedules. The input type is the intersection of both schedules' input
types.


This is useful when coordinating multiple scheduling conditions where
execution should proceed only when both schedules permit it.
@see ― intersectWith If you need to use a custom merge function.
@since ― 2.0.0
intersect(
  
import Schedule
Schedule.
const exponential: (base: DurationInput, factor?: number) => Schedule.Schedule<Duration>
Creates a schedule that recurs indefinitely with exponentially increasing
delays.


Details


This schedule starts with an initial delay of base and increases the delay
exponentially on each repetition using the formula base * factor^n, where
n is the number of times the schedule has executed so far. If no factor
is provided, it defaults to 2, causing the delay to double after each
execution.
@since ― 2.0.0
exponential("10 millis"),
  
import Schedule
Schedule.
const recurs: (n: number) => Schedule.Schedule<number>
A schedule that recurs a fixed number of times before terminating.


Details


This schedule will continue executing until it has been stepped n times,
after which it will stop. The output of the schedule is the current count of
recurrences.
@since ― 2.0.0
recurs(5)
)


const 
const program: Effect.Effect<number, DivisionByZeroError, never>
program = 
const divide: (n1: number, n2: number) => Effect.Effect<number, DivisionByZeroError, never>
divide(5, 2).
Pipeable.pipe<Effect.Effect<number, DivisionByZeroError, never>, Effect.Effect<number, DivisionByZeroError, never>>(this: Effect.Effect<number, DivisionByZeroError, never>, ab: (_: Effect.Effect<number, DivisionByZeroError, never>) => Effect.Effect<number, DivisionByZeroError, never>): Effect.Effect<number, DivisionByZeroError, never> (+21 overloads)
pipe(
  
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const retry: <[Duration, number], DivisionByZeroError, never>(policy: Schedule.Schedule<[Duration, number], DivisionByZeroError, never>) => <A, R>(self: Effect.Effect<A, DivisionByZeroError, R>) => Effect.Effect<A, DivisionByZeroError, R> (+3 overloads)
Retries a failing effect based on a defined retry policy.


Details


The Effect.retry function takes an effect and a


Schedule


policy,
and will automatically retry the effect if it fails, following the rules of
the policy.


If the effect ultimately succeeds, the result will be returned.


If the maximum retries are exhausted and the effect still fails, the failure
is propagated.


When to Use


This can be useful when dealing with intermittent failures, such as network
issues or temporary resource unavailability. By defining a retry policy, you
can control the number of retries, the delay between them, and when to stop
retrying.


Example (Retrying with a Fixed Delay)


import { Effect, Schedule } from "effect"


let count = 0


// Simulates an effect with possible failures
const task = Effect.async<string, Error>((resume) => {
  if (count <= 2) {
    count++
    console.log("failure")
    resume(Effect.fail(new Error()))
  } else {
    console.log("success")
    resume(Effect.succeed("yay!"))
  }
})


// Define a repetition policy using a fixed delay between retries
const policy = Schedule.fixed("100 millis")


const repeated = Effect.retry(task, policy)


Effect.runPromise(repeated).then(console.log)
// Output:
// failure
// failure
// failure
// success
// yay!


Example (Retrying a Task up to 5 times)


import { Effect } from "effect"


let count = 0


// Simulates an effect with possible failures
const task = Effect.async<string, Error>((resume) => {
  if (count <= 2) {
    count++
    console.log("failure")
    resume(Effect.fail(new Error()))
  } else {
    console.log("success")
    resume(Effect.succeed("yay!"))
  }
})


// Retry the task up to 5 times
Effect.runPromise(Effect.retry(task, { times: 5 })).then(console.log)
// Output:
// failure
// failure
// failure
// success


Example (Retrying Until a Specific Condition is Met)


import { Effect } from "effect"


let count = 0


// Define an effect that simulates varying error on each invocation
const action = Effect.failSync(() => {
  console.log(`Action called ${++count} time(s)`)
  return `Error ${count}`
})


// Retry the action until a specific condition is met
const program = Effect.retry(action, {
  until: (err) => err === "Error 3"
})


Effect.runPromiseExit(program).then(console.log)
// Output:
// Action called 1 time(s)
// Action called 2 time(s)
// Action called 3 time(s)
// {
//   _id: 'Exit',
//   _tag: 'Failure',
//   cause: { _id: 'Cause', _tag: 'Fail', failure: 'Error 3' }
// }
@see ― retryOrElse for a version that allows you to run a fallback.
@see ― repeat if your retry condition is based on successful outcomes rather than errors.
@since ― 2.0.0
retry(
const schedule: Schedule.Schedule<[Duration, number], unknown, never>
schedule)
)


3 collapsed lines
import Effect
@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <number, DivisionByZeroError>(effect: Effect.Effect<number, DivisionByZeroError, never>, options?: {
    readonly signal?: AbortSignal | undefined;
} | undefined) => Promise<number>
Executes an effect and returns the result as a Promise.


Details


This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.


The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.


When to Use


Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.


Example (Running a Successful Effect as a Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1


Example (Handling a Failing Effect as a Rejected Promise)


import { Effect } from "effect"


Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise(
const program: Effect.Effect<number, DivisionByZeroError, never>
program)
  .
Promise<number>.then<void, never>(onfulfilled?: ((value: number) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log)
  .
Promise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>
Attaches a callback for only the rejection of the Promise.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of the callback.
catch(
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console').
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.error(message?: any, ...optionalParams: any[]): void
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3) (the arguments are all passed to util.format()).


const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr


If formatting elements (e.g. %d) are not found in the first string then util.inspect() is called on each argument and the resulting string
values are concatenated. See util.format() for more information.
@since ― v0.1.100
error);

Schedule made it so simple to define the retry behavior! You can get as fancy as you want with the repetition policy and even define schedules a la cron.