Effect 3.8 (Release)

Sep 16, 2024

Effect 3.8 has been released! This release includes a number of new features and improvements. Here’s a summary of what’s new:

Logger.withLeveledConsole

With this api you can create a logger that uses the console.{log,info,warn,error,trace} functions, depending on the log level of each message.

This is useful in environments such as browsers, where the different log levels are styled differently.

For example:

1
import { Effect, Logger } from "effect"
2

3
const loggerLayer = Logger.replace(
4
  Logger.defaultLogger,
5
  Logger.withLeveledConsole(Logger.stringLogger)
6
)
7

8
Effect.gen(function* () {
9
  yield* Effect.logError("an error")
10
  yield* Effect.logInfo("an info")
11
}).pipe(Effect.provide(loggerLayer))

More types implement Effect

Many of the data types in Effect can now be used directly as Effect’s. These include:

Ref<A> - Effect<A>, equivalent to Ref.get
SynchronizedRef<A> - Effect<A>, equivalent to SynchronizedRef.get
SubscriptionRef<A> - Effect<A>, equivalent to SubscriptionRef.get
Deferred<A, E> - Effect<A, E>, equivalent to Deferred.await
Dequeue<A> - Effect<A>, equivalent to Queue.take
Fiber<A, E> - Effect<A, E>, equivalent to Fiber.join
FiberRef<A> - Effect<A>, equivalent to FiberRef.get

Semaphore.withPermitsIfAvailable

Semaphore.withPermitsIfAvailable will attempt to run an effect immediately if permits are available. It will return an Option<A> from the result of the effect, depending on whether the permits were available.

1
import { Effect } from "effect"
2

3
Effect.gen(function*() {
4
  const semaphore = yield* Effect.makeSemaphore(1)
5

6
  // returns Option.some("foo")
7
  yield* semaphore.withPermitsIfAvailable(1)(Effect.succeed("foo"))
8
  // returns Option.none()
9
  yield* semaphore.withPermitsIfAvailable(2)(Effect.succeed("bar"))
10
})

Effect.makeLatch

You can create an Effect.Latch with Effect.makeLatch, which can be used to synchronize multiple effects.

The latch can be opened, closed and waited on.

1
import { Effect } from "effect"
2

3
Effect.gen(function* () {
4
  // Create a latch, starting in the closed state
5
  const latch = yield* Effect.makeLatch(false)
6

7
  // Fork a fiber that logs "open sesame" when the latch is opened
8
  const fiber = yield* Effect.log("open sesame").pipe(
9
    latch.whenOpen,
10
    Effect.fork
11
  )
12

13
  // Open the latch
14
  yield* latch.open
15

16
  // Wait for the latch to be opened
17
  yield* fiber.await
18

19
  // Release all waiters, without opening the latch
20
  yield* latch.release
21
})

Stream.share

Stream.share is a reference counted equivalent of the Stream.broadcastDynamic api.

It is useful when you want to share a Stream, and ensure any resources are finalized when no more consumers are subscribed.

1
import { Effect, Stream } from "effect"
2

3
Effect.gen(function*() {
4
  const sharedStream = yield* Effect.acquireRelease(
5
    Effect.log("Stream acquired").pipe(
6
      Effect.as(Stream.never)
7
    ),
8
    () => Effect.log("Stream released")
9
  ).pipe(
10
    Stream.unwrapScoped,
11
    Stream.share({ capacity: 16 })
12
  )
13

14
  // Nothing is logged yet
15

16
  yield* Stream.runDrain(sharedStream)
17
  // The upstream will now start emitting values.
18
  // If the downstream is interrupted, the upstream will also be finalized.
19
})

HttpClient refactor

The @effect/platform/HttpClient module has been refactored to reduce and simplify the api surface.

HttpClient.fetch removed

The HttpClient.fetch client implementation has been removed. Instead, you can access a HttpClient using the corresponding Context.Tag.

1
import { FetchHttpClient, HttpClient } from "@effect/platform"
2
import { Effect } from "effect"
3

4
Effect.gen(function* () {
5
  const client = yield* HttpClient.HttpClient
6

7
  // make a get request
8
  yield* client.get("https://jsonplaceholder.typicode.com/todos/1")
9
}).pipe(
10
  Effect.scoped,
11
  // the fetch client has been moved to the `FetchHttpClient` module
12
  Effect.provide(FetchHttpClient.layer)
13
)

HttpClient interface now uses methods

Instead of being a function that returns the response, the HttpClient interface now uses methods to make requests.

Some shorthand methods have been added to the HttpClient interface to make less complex requests easier to implement.

1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest
5
} from "@effect/platform"
6
import { Effect } from "effect"
7

8
Effect.gen(function* () {
9
  const client = yield* HttpClient.HttpClient
10

11
  // make a get request
12
  yield* client.get("https://jsonplaceholder.typicode.com/todos/1")
13
  // make a post request
14
  yield* client.post("https://jsonplaceholder.typicode.com/todos")
15

16
  // execute a request instance
17
  yield* client.execute(
18
    HttpClientRequest.get("https://jsonplaceholder.typicode.com/todos/1")
19
  )
20
})

Scoped HttpClientResponse helpers removed

The HttpClientResponse helpers that also supplied the Scope have been removed.

Instead, you can use the HttpClientResponse methods directly, and explicitly add a Effect.scoped to the pipeline.

1
import { FetchHttpClient, HttpClient } from "@effect/platform"
2
import { Effect } from "effect"
3

4
Effect.gen(function* () {
5
  const client = yield* HttpClient.HttpClient
6

7
  yield* client.get("https://jsonplaceholder.typicode.com/todos/1").pipe(
8
    Effect.flatMap((response) => response.json),
9
    Effect.scoped // supply the `Scope`
10
  )
11
})

Some apis have been renamed

Including the HttpClientRequest body apis, which is to make them more discoverable.

Mailbox module

A new experimental effect/Mailbox module has been added. Mailbox is an asynchronous queue that can have a done / failure signal.

It is useful when you want to communicate between effects, and have a way to determine that the communication is complete.

1
import { Chunk, Effect, Mailbox } from "effect"
2
import * as assert from "node:assert"
3

4
Effect.gen(function* () {
5
  const mailbox = yield* Mailbox.make<number, string>()
6

7
  // add messages to the mailbox
8
  yield* mailbox.offer(1)
9
  yield* mailbox.offer(2)
10
  yield* mailbox.offerAll([3, 4, 5])
11

12
  // take messages from the mailbox
13
  const [messages, done] = yield* mailbox.takeAll
14
  assert.deepStrictEqual(Chunk.toReadonlyArray(messages), [1, 2, 3, 4, 5])
15
  assert.strictEqual(done, false)
16

17
  // signal that the mailbox is done
18
  yield* mailbox.end
19
  const [messages2, done2] = yield* mailbox.takeAll
20
  assert.deepStrictEqual(messages2, Chunk.empty())
21
  assert.strictEqual(done2, true)
22

23
  // signal that the mailbox is failed
24
  yield* mailbox.fail("boom")
25

26
  // turn the mailbox into a stream
27
  const stream = Mailbox.toStream(mailbox)
28
})

FiberRef performance improvements

Some common FiberRef instances are now cached, which improves performance of the Effect runtime.

RcMap.keys & MutableMap.keys

You can now access the available keys of a RcMap or MutableMap using the keys api.

For example:

1
const map = MutableHashMap.make([["a", "a"], ["b", "b"], ["c", "c"]])
2
const keys = MutableHashMap.keys(map) // ["a", "b", "c"]

And for RcMap:

1
Effect.gen(function* () {
2
  const map = yield* RcMap.make({
3
    lookup: (key) => Effect.succeed(key)
4
  })
5

6
  yield* RcMap.get(map, "a")
7
  yield* RcMap.get(map, "b")
8
  yield* RcMap.get(map, "c")
9

10
  const keys = yield* RcMap.keys(map) // ["a", "b", "c"]
11
})

Duration conversion apis

Some new apis for converting between a Duration and it’s corresponding parts have been added:

Duration.toMinutes
Duration.toHours
Duration.toDays
Duration.toWeeks
Duration.parts

Other changes

There were several other smaller changes made. Take a look through the CHANGELOG to see them all: CHANGELOG.

Don’t forget to join our Discord Community to follow the last updates and discuss every tiny detail!