Effect 3.11 (Release)

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

Effect.fn

The Effect.fn API allows you to create a function that is automatically traced, and also attaches the location where the function was called to any error traces, helping you track the source of failures.

Example (Creating a traced function)

1
import { Effect } from "effect"
2

3
const logExample = Effect.fn("example")(function* <N extends number>(n: N) {
4
  yield* Effect.annotateCurrentSpan("n", n)
5
  yield* Effect.logInfo(`got: ${n}`)
6
  yield* Effect.fail(new Error())
7
})

Let’s see it in action by exporting the traces to the console:

Example (Exporting traces to the console)

In the output below, you can see the location where the function was called.

1
import { Effect } from "effect"
2
import { NodeSdk } from "@effect/opentelemetry"
3
import {
4
  ConsoleSpanExporter,
5
  BatchSpanProcessor,
6
} from "@opentelemetry/sdk-trace-base"
7

8
const logExample = Effect.fn("example")(function* <N extends number>(n: N) {
9
  yield* Effect.annotateCurrentSpan("n", n)
10
  yield* Effect.logInfo(`got: ${n}`)
11
  yield* Effect.fail(new Error())
12
})
13

14
const program = logExample(100).pipe(Effect.catchAllCause(Effect.logError))
15

16
const NodeSdkLive = NodeSdk.layer(() => ({
17
  resource: { serviceName: "example" },
18
  // Export span data to the console
19
  spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter()),
20
}))
21

22
Effect.runFork(program.pipe(Effect.provide(NodeSdkLive)))
23
/*
24
Output:
25
{
26
  resource: {
27
    attributes: {
28
      'service.name': 'example',
29
      'telemetry.sdk.language': 'nodejs',
30
      'telemetry.sdk.name': '@effect/opentelemetry',
31
      'telemetry.sdk.version': '1.28.0'
32
    }
33
  },
34
  instrumentationScope: { name: 'example', version: undefined, schemaUrl: undefined },
35
  traceId: 'f9ffd211c2f6efc66e11d8aab3466e3f',
36
  parentId: undefined,
37
  traceState: undefined,
38
  name: 'example',
39
  id: '2949fa70d80fe0f4',
40
  kind: 0,
41
  timestamp: 1733217197993387.8,
42
  duration: 5023.958,
43
  attributes: {
44
    n: 100,
45
    'code.stacktrace': 'at <anonymous> (/path/to/file/index.ts:16:17)'
46
  },
47
  status: { code: 2, message: 'An error has occurred' },
48
  events: [
49
    {
50
      name: 'got: 100',
51
      attributes: { 'effect.fiberId': '#0', 'effect.logLevel': 'INFO' },
52
      time: [ 1733217197, 995354750 ],
53
      droppedAttributesCount: 0
54
    },
55
    {
56
      name: 'exception',
57
      attributes: {
58
        'exception.type': 'Error',
59
        'exception.message': 'An error has occurred',
60
        'exception.stacktrace': 'Error: An error has occurred\n' +
61
          '    at <anonymous> (/path/to/file/index.ts:13:22)\n' +
62
          '    at example (/path/to/file/index.ts:16:17)'
63
      },
64
      time: [ 1733217197, 998411750 ],
65
      droppedAttributesCount: 0
66
    }
67
  ],
68
  links: []
69
}
70
*/

Effect.fn with a pipeline

The Effect.fn API also acts as a pipe function, allowing you to create a pipeline after the function definition.

Example (Creating a traced function with a pipeline)

In this example, Effect.fn is used not only to define the traced function but also to create a pipeline by chaining Effect.delay after the function, adding a delay of “1 second” to the execution.

1
import { Effect } from "effect"
2

3
const logExample = Effect.fn("example")(
4
  function* <N extends number>(n: N) {
5
    yield* Effect.annotateCurrentSpan("n", n)
6
    yield* Effect.logInfo(`got: ${n}`)
7
    yield* Effect.fail(new Error())
8
  },
9
  // Add a delay to the effect
10
  Effect.delay("1 second"),
11
)

Context.Reference

You can now create a tag with a default value.

Example (Declaring a Tag with a default value)

In this example, you don’t have to explicitly provide the SpecialNumber implementation. The default value is automatically used when the service is accessed.

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

3
class SpecialNumber extends Context.Reference<SpecialNumber>()(
4
  "SpecialNumber",
5
  {
6
    defaultValue: () => 2048,
7
  },
8
) {}
9

10
//      ┌─── Effect<void, never, never>
11
//      ▼
12
const program = Effect.gen(function* () {
13
  const specialNumber = yield* SpecialNumber
14
  console.log(`The special number is ${specialNumber}`)
15
})
16

17
// No need to provide the SpecialNumber implementation
18
Effect.runPromise(program)
19
// Output: The special number is 2048

Example (Overriding the default value)

In this example, the default value is overridden by providing a different implementation for the SpecialNumber service.

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

3
class SpecialNumber extends Context.Reference<SpecialNumber>()(
4
  "SpecialNumber",
5
  {
6
    defaultValue: () => 2048,
7
  },
8
) {}
9

10
const program = Effect.gen(function* () {
11
  const specialNumber = yield* SpecialNumber
12
  console.log(`The special number is ${specialNumber}`)
13
})
14

15
Effect.runPromise(program.pipe(Effect.provideService(SpecialNumber, -1)))
16
// Output: The special number is -1

Effect.scopedWith

Effect.scopedWith allows you to create and use a Scope without adding it to the Effect’s requirements.

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

3
//      ┌─── Effect<void, never, never>
4
//      ▼
5
const program = Effect.scopedWith((scope) =>
6
  Scope.addFinalizer(scope, Effect.log("finalized")),
7
)

Time zone support in Cron

Cron expressions using the Cron module now support time zones. You can specify a time zone when creating a cron instance when using Cron.make or Cron.parse.

BigDecimal updates

BigDecimal.toExponential added - format a BigDecimal as a string in exponential notation.
BigDecimal.fromNumber has been deprecated in favour of BigDecimal.unsafeFromNumber.

Micro runtime changes

Micro execution is now using a fiber-runtime based model. This results in the following benefits:

Improved performance
Improved interruption model
Consistency with the Effect data type

Env & EnvRef

Env & EnvRef have been removed in favor of Context.Reference.

MicroExit

The MicroExit data type is no longer based on Either:

Before:

type MicroExit<A, E> = Either<A, MicroCause<E>>

After:

type MicroExit<A, E> = MicroExit.Success<A, E> | MicroExit.Failure<A, E>

Joining Fibers

fiber.join has been replaced with Micro.fiberJoin.

1
import { Micro } from "effect"
2

3
const fib = (n: number): Micro.Micro<number> =>
4
  n < 2
5
    ? Micro.succeed(n)
6
    : Micro.zipWith(fib(n - 1), fib(n - 2), (a, b) => a + b)
7

8
const fib10Fiber = Micro.fork(fib(10))
9

10
const program = Micro.gen(function* () {
11
  const fiber = yield* fib10Fiber
12
  // Join the fiber and get the result
13
  const n = yield* fiber.join
14
  const n = yield* Micro.fiberJoin(fiber)
15
  console.log(n)
16
})
17

18
Micro.runPromise(program)
19
// Output: 55

Awaiting Fibers

fiber.await has been replaced with Micro.fiberAwait.

1
import { Micro } from "effect"
2

3
const fib = (n: number): Micro.Micro<number> =>
4
  n < 2
5
    ? Micro.succeed(n)
6
    : Micro.zipWith(fib(n - 1), fib(n - 2), (a, b) => a + b)
7

8
const fib10Fiber = Micro.fork(fib(10))
9

10
const program = Micro.gen(function* () {
11
  const fiber = yield* fib10Fiber
12
  // Await its completion and get the MicroExit result
13
  const exit = yield* fiber.await
14
  const exit = yield* Micro.fiberAwait(fiber)
15
  console.log(exit)
16
})
17

18
Micro.runPromise(program)
19
/*
20
Output:
21
{
22
  "_id": "MicroExit",
23
  "_tag": "Success",
24
  "value": 55
25
}
26
*/

Interrupting Fibers

fiber.interrupt has been replaced with Micro.fiberInterrupt.

1
import { Micro } from "effect"
2

3
const program = Micro.gen(function* () {
4
  const fiber = yield* Micro.fork(
5
    Micro.forever(Micro.sync(() => console.log("Hi!")).pipe(Micro.delay(10))),
6
  )
7
  yield* Micro.sleep(30)
8
  // Interrupt the fiber
9
  yield* fiber.interrupt
10
  yield* Micro.fiberInterrupt(fiber)
11
})
12

13
Micro.runPromise(program)
14
/*
15
Output:
16
Hi!
17
Hi!
18
*/

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!