27 - Effect.fn: Traced, Named Effectful Functions

Previous · Next

Creates a named, traced wrapper around a generator-style Effect. Every invocation opens a span carrying the supplied name; traces, logs, and error reports include that name instead of <anonymous>.

An optional second argument transforms the entire effect, the natural home for retries, timeouts, and other call-wide instrumentation.

What you’ll work through

index.test.ts contains three beats: declaring a named Effect.fn, threading typed errors through its E channel, and using the second argument to attach call-wide instrumentation (retry, timeout, log annotations).

By the end you should wrap every service method in Effect.fn("Name.method") without thinking about it. The convention is canonical — step 23 documents the discipline.

The Shape

1
Effect.fn("name")(
2
  function* (args) { ... yield* something ... },
3
  // optional: wraps every call
4
  (effect, ...args) => effect.pipe(Effect.retry(...), Effect.timeout(...)),
5
)

The first call binds the name. The second call takes the generator and any number of pipeable instrumentation steps.

The result is a regular function returning an Effect.

A Named Function

1
import { Effect } from "effect"
2

3
//      ┌─── (n: number) => Effect<number, never, never>
4
//      ▼
5
const double = Effect.fn("double")(function* (n: number) {
6
  return yield* Effect.succeed(n * 2)
7
})
8

9
Effect.runSync(double(5)) // 10

Details

Without Effect.fn, the same logic written as const double = (n: number) => Effect.gen(...) produces an anonymous span. With it, every trace edge carries the string "double", visible in OpenTelemetry, error messages, and the structured log.

When to Use

For every top-level effectful function that crosses a boundary: service method implementations, request handlers, scheduled jobs, anything you might need to find in a trace.

A Named Function with Failure

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

3
class FetchError extends Data.TaggedError("FetchError")<{
4
  readonly url: string
5
}> {}
6

7
//      ┌─── (id: string) => Effect<User, FetchError, never>
8
//      ▼
9
const fetchUser = Effect.fn("fetchUser")(function* (id: string) {
10
  if (!id.startsWith("user_")) {
11
    return yield* Effect.fail(new FetchError({ url: `/api/users/${id}` }))
12
  }
13
  return yield* Effect.tryPromise({
14
    try: async () => ({ id, name: "Alice" }),
15
    catch: (cause) => new FetchError({ url: `/api/users/${id}` }),
16
  })
17
})

The failure carries the function name in its span. Log lines from fetchUser’s span are correlated automatically.

Centralised Instrumentation

The second argument to Effect.fn runs once per call and wraps the whole effect. This is where retry, timeout, and similar policies belong, applied at the definition site so every call gets them.

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

3
const resilientFetch = Effect.fn("resilientFetch")(
4
  function* (id: string) {
5
    return yield* Effect.tryPromise({
6
      try: () => fetchFromApi(id),
7
      catch: (cause) => new FetchError({ url: id, cause }),
8
    })
9
  },
10
  (effect) =>
11
    effect.pipe(
12
      Effect.retry(Schedule.recurs(3)),
13
      Effect.timeout("5 seconds"),
14
    ),
15
)

Every call to resilientFetch gets the same retry policy and the same timeout. Call sites remain clean.

`Effect.fn` vs `const`

1
// Anonymous, works, but the trace shows <anonymous>.
2
const processOrder = (orderId: string) =>
3
  Effect.gen(function* () {
4
    const db = yield* DbService
5
    return yield* db.find(orderId)
6
  })
7

8
// Named, same behaviour, observable.
9
const processOrder = Effect.fn("processOrder")(function* (orderId: string) {
10
  const db = yield* DbService
11
  return yield* db.find(orderId)
12
})

Runtime behaviour is identical. The difference is debuggability.

Common Pitfalls

1, Calling the factory directly. Effect.fn("name")(gen) returns a function, not an effect. Invoke it with the arguments to obtain the effect: myFn(args).pipe(...).

2, Pushing partial logic into the instrumentation argument. The second argument wraps the whole call. To apply retry only to one inner step, pipe that step directly, do not lift partial logic into the wrapper.

3, Reaching for Effect.fnUntraced. Skip the span only when measurements show the overhead matters in a hot loop. Default to Effect.fn.

4, Naming generically. Effect.fn("handler") is little better than anonymous. Use the function’s actual responsibility: "processOrder", "reserveInventory", "sendReceipt".

label is the supplied name, not ``. - [ ] Thread a typed error through the `E` channel — the `fn` wrapper preserves it. - [ ] Use the second argument to attach call-wide instrumentation (retry, timeout, log annotation) without touching the body.

The full test suite

The index.test.ts for this lesson, verbatim from steps/27-effect-fn/.

1
import { describe, it, expect } from "vite-plus/test"
2
import { Effect, Schedule, Data } from "effect"
3

4
// =============================================================================
5
// 25 - Effect.fn: Traced, Named Effectful Functions
6
// =============================================================================
7
//
8
// Effect.fn("name")(gen) wraps a generator with a named span.
9
// Effect.fn("name")(gen, (eff) => eff.pipe(...)) adds call-wide instrumentation.
10

11
describe("25 - Effect.fn", () => {
12
  // @beat
13
  //   id: named-fn
14
  //   shape: one-todo
15
  //   title: Name and trace an effectful function
16
  //   teaches: Effect.fn("name")(gen) wraps a generator so every invocation opens a span carrying that name.
17
  //   hint: const double = Effect.fn("double")(function* (n: number) { return yield* Effect.succeed(n * 2) })
18
  describe("named functions", () => {
19
    it("creates a function that returns an Effect", async () => {
20
      //      ┌─── (n: number) => Effect<number, never, never>
21
      //      ▼
22
      const double = Effect.fn("double")(function* (n: number) {
23
        return yield* Effect.succeed(n * 2)
24
      })
25

26
      expect(await Effect.runPromise(double(5))).toBe(10)
27
    })
28

29
    it("attaches the name to every invocation's span", async () => {
30
      const greet = Effect.fn("greet")(function* (name: string) {
31
        return `Hello, ${name}!`
32
      })
33

34
      expect(await Effect.runPromise(greet("World"))).toBe("Hello, World!")
35
    })
36

37
    it("supports yielding async effects", async () => {
38
      const fetchName = Effect.fn("fetchName")(function* (id: string) {
39
        return yield* Effect.tryPromise({
40
          try: async () => ({ id, name: "Alice" }),
41
          catch: (cause) => new Error(`Fetch failed: ${cause}`),
42
        })
43
      })
44

45
      const result = await Effect.runPromise(fetchName("123"))
46
      expect(result.name).toBe("Alice")
47
    })
48

49
    it("is a drop-in for const fn = () => Effect.gen", async () => {
50
      const anonymous = (n: number, factor: number) =>
51
        Effect.gen(function* () {
52
          return yield* Effect.succeed(n * factor)
53
        })
54

55
      const named = Effect.fn("multiply")(function* (n: number, factor: number) {
56
        return yield* Effect.succeed(n * factor)
57
      })
58

59
      expect(await Effect.runPromise(anonymous(4, 5))).toBe(20)
60
      expect(await Effect.runPromise(named(4, 5))).toBe(20)
61
    })
62
  })
63
  // @end-beat
64

65
  // @beat
66
  //   id: fn-error-channel
67
  //   shape: one-todo
68
  //   title: Failures inherit the function name
69
  //   teaches: Inside Effect.fn the error channel works unchanged; the failure carries the function name in its span.
70
  //   hint: yield* Effect.fail(new FetchError({ url })) inside the generator
71
  describe("error handling inside Effect.fn", () => {
72
    class FetchError extends Data.TaggedError("FetchError")<{
73
      readonly url: string
74
    }> {}
75

76
    const fetchData = Effect.fn("fetchData")(function* (url: string) {
77
      if (url.includes("error")) {
78
        return yield* Effect.fail(new FetchError({ url }))
79
      }
80
      return yield* Effect.succeed({ data: "ok" })
81
    })
82

83
    it("failures carry the function name in their span", async () => {
84
      const exit = await Effect.runPromiseExit(fetchData("/api/error"))
85
      expect(exit._tag).toBe("Failure")
86
    })
87

88
    it("the success path is unaffected", async () => {
89
      const result = await Effect.runPromise(fetchData("/api/users"))
90
      expect(result.data).toBe("ok")
91
    })
92
  })
93
  // @end-beat
94

95
  // @beat
96
  //   id: call-wide-instrumentation
97
  //   shape: multi-todo
98
  //   title: Centralise retry and timeout at the definition site
99
  //   teaches: The second argument of Effect.fn wraps every call uniformly — retry and timeout policies live there, not at call sites.
100
  //   hint: Effect.fn("name")(function* (...) { ... }, (effect) => effect.pipe(Effect.retry(Schedule.recurs(3))))
101
  describe("call-wide instrumentation (second argument)", () => {
102
    it("retry policies live at the definition site", async () => {
103
      let attempts = 0
104

105
      const resilientFetch = Effect.fn("resilientFetch")(
106
        function* (id: string) {
107
          attempts++
108
          if (attempts < 3) {
109
            return yield* Effect.fail("transient")
110
          }
111
          return yield* Effect.succeed({ id, name: "Alice" })
112
        },
113
        (effect) => effect.pipe(Effect.retry(Schedule.recurs(3))),
114
      )
115

116
      const result = await Effect.runPromise(resilientFetch("123"))
117
      expect(result.name).toBe("Alice")
118
      expect(attempts).toBe(3)
119
    })
120

121
    it("every caller gets the same instrumentation", async () => {
122
      let callCount = 0
123

124
      const withOneRetry = Effect.fn("withOneRetry")(
125
        function* (x: number) {
126
          callCount++
127
          if (callCount === 1) {
128
            return yield* Effect.fail("first attempt fails")
129
          }
130
          return yield* Effect.succeed(x * 10)
131
        },
132
        (effect) => effect.pipe(Effect.retry(Schedule.recurs(1))),
133
      )
134

135
      const result = await Effect.runPromise(withOneRetry(7))
136
      expect(result).toBe(70)
137
      expect(callCount).toBe(2)
138
    })
139
  })
140
  // @end-beat
141
})

04·03Effect.fn

27 - Effect.fn: Traced, Named Effectful Functions

What you’ll work through

The Shape

A Named Function

A Named Function with Failure

Centralised Instrumentation

`Effect.fn` vs `const`

Common Pitfalls

See Also

The full test suite

04·03Effect.fn

27 - Effect.fn: Traced, Named Effectful Functions

What you’ll work through

The Shape

A Named Function

A Named Function with Failure

Centralised Instrumentation

Effect.fn vs const

Common Pitfalls

See Also

The full test suite

`Effect.fn` vs `const`