Effect.succeed

It took me a while to wrap my head around what exactly Effect is. Is it a data type? A library? A whole ecosystem? The answer: yes, all of those things. The word “Effect” is used to represent multiple terms, including (but probably not limited to)

  • Effect-the-data-type
  • Effect-the-module
  • Effect-the-library
  • Effect-the-ecosystem
  • Effect-the-community

Let’s start as small as we can. You can grab Effect-the-library from npm. Its source is on GitHub. Alternatively, you can get started by using the Effect Playground.

Here’s our first piece of Effect code.

// main.ts
import { Effect } from 'effect'
const myFirstEffect = Effect.succeed(3)
console.log(myFirstEffect)

Although this is valid JavaScript, we will be working in TypeScript. Type safety is one of the major benefits of Effect. If you’re not sold on TypeScript, Effect may not be for you.

The first line shows us that inside the 'effect' library is a namespace called Effect. This namespace has a whole heap of functions, many of which we’ll visit in future lessons. We’ll usually refer to this as The Effect Module. You can also import * as Effect from 'effect/Effect' if you want to be super explicit, but for simplicity we will continue to import from the top-level 'effect' library..

For now, we use the Effect.succeed function. Looking at myFirstEffect, we can see its type is Effect.Effect<number, never, never>. This gives us a first hint at what an Effect is: an Effect is a data type that can hold 3 generic parameters.

The first parameter is essential, but the other two are optional, and default to never.

// These types (A, B, C) are all the same.
// We could refer to this as "an Effect of number".
type A = Effect.Effect<number, never, never>
type B = Effect.Effect<number, never>
type C = Effect.Effect<number>

Let’s run the code, to see what this Effect looks like.

$ npx tsx main.ts
{ _id: 'Exit', _tag: 'Success', value: 3 }

We see our value 3 printed out, along with mysterious _id and _tag. In very broad terms, this tells us that an Effect can represent a successful exit with value 3. The mention of “Success” suggests there may also be “Failure”, and we’ll see that in future lessons. We’ll also see Effects that are not Exits.

Effect uses the convention that anything prefixed with _ should be treated as “private” - an implementation detail that you should not touch unless you really know what you are doing. Indeed, if you try to access myFirstEffect._id you will see TypeScript get angry:

Property '_id' does not exist on type 'Effect<number, never, never>'.

The only property we can access on our Effect is .pipe. If you’ve done much functional programming, you may be familiar with the pipe function. This is such an essential tool that many functional programming languages bake this into the language with special syntax. There’s even a proposal to introduce a pipe operator to JavaScript.

Piping will return a new value, rather than mutating the input. Our Effect, once created, is essentially immutable.

Let’s change the code a little.

// main.ts
import { Effect } from 'effect'
const mySecondEffect = Effect.succeed('Hello, Effect!')
console.log(mySecondEffect)

You’ll notice that mySecondEffect has a type of Effect.Effect<string, never, never> (aka Effect.Effect<string>). Without running the code, can you guess what running this code will do?

$ npx tsx main.ts
{ _id: 'Exit', _tag: 'Success', value: 'Hello, Effect!' }

Sure enough, we see an object printed out, with the matching value.

Let’s recap what we’ve seen so far.

  • Effect-the-library is an npm package. You can install it with npm install effect. You can import many things from the 'effect' library.
  • Effect-the-module is a symbol you can import from Effect-the-library, using import { Effect } from 'effect'.
  • Effect-the-data-type is a data type with up to 3 generic parameters. The first parameter represents the “value” that this Effect holds. An Effect is a plain JavaScript object behind the scenes, but we will rarely inspect its contents directly.
  • You can construct an Effect that holds a specific value using Effect.succeed
  • Effects are immutable