54 - Incremental Adoption: Bridge One Promise at a Time

Previous · Next

A production codebase will not be rewritten overnight, and trying produces a single unreviewable diff. Effect’s Effect.tryPromise is a precise bridge: it converts a Promise, including one that rejects, into an Effect whose failure mode is named in the type.

The rest of the codebase keeps using Promises. The two compose at the boundary you choose.

This step covers the constructors that bridge Promise code, the pattern for hiding them behind a service, and the order to migrate flows in.

What you’ll work through

index.test.ts contains three beats: lifting a single Promise call with Effect.tryPromise, hiding the bridge behind a service so callers don’t see it, and choosing the migration order — leaf calls first, composition root last.

By the end you should be able to introduce Effect into a Promise-based codebase without a single rewrite-the-world commit.

The Bridge

1
Promise side                              Effect side
2
------------                              -----------
3
legacy.fetchUser(id)        ─────────►    Effect<User, UserRepoError>
4
   may throw / reject                        failure named in E
5
                                             retry / fallback available
6
                                             composes with other Effects

Two constructors do the bridging, pick by whether the Promise can reject.

`Effect.tryPromise`

Creates an Effect from a function returning a Promise that may reject. The catch function maps the unknown rejection value into a typed error.

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

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

7
//      ┌─── Effect<unknown, FetchError, never>
8
//      ▼
9
const fetchJson = (url: string) =>
10
  Effect.tryPromise({
11
    try: () => fetch(url).then((response) => response.json() as unknown),
12
    catch: (cause) => new FetchError({ cause }),
13
  })

Details

The try callback receives an AbortSignal if the effect is interrupted, pass it to fetch to make the request cancellable. The catch callback runs only on rejection; its return value lands in the E channel.

When to Use

Every Promise that can reject. That includes fetch, every SDK call, every fs/promises call, every database driver method.

`Effect.promise`

Creates an Effect from a function returning a Promise that never rejects. A rejection at runtime is treated as a defect.

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, never, never>
4
//      ▼
5
const now = Effect.promise(() => Promise.resolve(Date.now()))

When to Use

In-memory operations: crypto.subtle.digest on a known input, a Promise.resolve, caches whose underlying store is guaranteed not to throw. The unconstrained version is the wrong default for I/O.

Hiding the Bridge Behind a Service

The bridge belongs at the seam between domain and infrastructure. Callers depend on a Context.Service; the implementation does the tryPromise once.

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

3
class UserRepoError extends Data.TaggedError("UserRepoError")<{
4
  readonly cause: unknown
5
}> {}
6

7
type User = { readonly id: string; readonly name: string }
8

9
interface LegacyUserRepo {
10
  readonly fetchUser: (id: string) => Promise<User>
11
}
12

13
class UserRepo extends Context.Service<UserRepo, {
14
    readonly fetchUser: (id: string) => Effect.Effect<User, UserRepoError>
15
  }>()("UserRepo") {}
16

17
const makeUserRepo = (legacy: LegacyUserRepo) => ({
18
  fetchUser: (id: string) =>
19
    Effect.tryPromise({
20
      try: () => legacy.fetchUser(id),
21
      catch: (cause) => new UserRepoError({ cause }),
22
    }),
23
})

The caller never sees the legacy module:

1
//      ┌─── Effect<string, UserRepoError, UserRepo>
2
//      ▼
3
const greet = (id: string) =>
4
  Effect.gen(function* () {
5
    const repo = yield* UserRepo
6
    const user = yield* repo.fetchUser(id)
7
    return `Hello, ${user.name}`
8
  })

The entrypoint is the one place where legacy and Effect coexist:

1
await Effect.runPromise(
2
  greet("user-1").pipe(Effect.provideService(UserRepo, makeUserRepo(legacyRepo))),
3
)

Migration Order

Migrate in order of pain, not file size. Where Effect pays off fastest:

Priority	Code shape	Why it pays off
1	External API calls (`fetch`, third-party SDKs)	Adds retry, timeout, typed failure
2	Payment / checkout flows	Failures are expensive; surface them
3	Duplicated retry / backoff loops	Replaced by `Effect.retry` + `Schedule`
4	Config loading at startup	`Config` removes process-level crashes
5	Multi-step initialisation	Sequencing with `Effect.gen` reads well
,	Boring CRUD that already works	Leave it. Migrating buys little.

Wrap a throwing legacy function with `Effect.try`

The first step of incremental adoption lives at the boundary between legacy and Effect code. Effect.try converts a throwing synchronous function into an Effect whose error channel holds a typed value — no exceptions cross the boundary into the rest of the program.

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

3
class LegacyValidationError extends Data.TaggedError("LegacyValidationError")<{
4
  readonly cause: unknown
5
}> {}
6

7
declare const legacyValidate: (input: string) => string  // throws on bad input
8

9
const validate = (input: string) =>
10
  Effect.try({
11
    try: () => legacyValidate(input),
12
    catch: (cause) => new LegacyValidationError({ cause }),
13
  })
14
//   ┌─── Effect<string, LegacyValidationError, never>

The thunk runs on every execution. The catch callback decides what typed shape the legacy exception takes before it enters E.

Downstream code never sees a raw exception — catchTag and retry work as if the legacy function had always been an Effect.

Your turn wrap a throwing legacy function with `Effect.try` and map any thrown value to a `LegacyValidationError`. Confirm valid input produces a `Success` exit and invalid input produces a `Failure` carrying the tagged error.

Wrap each Promise-returning function at the boundary

Every Promise-returning function at the legacy boundary gets its own Effect.tryPromise wrapper. The pattern is always the same: try runs the Promise, catch maps the rejection to a tagged error, and the resulting Effect slots into the surrounding pipeline.

There’s no shortcut — wrap each one, name each error.

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

3
class UserRepoError extends Data.TaggedError("UserRepoError")<{
4
  readonly cause: unknown
5
}> {}
6

7
declare const legacySaveUser: (user: User) => Promise<{ id: string }>
8

9
const saveUser = (user: User) =>
10
  Effect.tryPromise({
11
    try: () => legacySaveUser(user),
12
    catch: (cause) => new UserRepoError({ cause }),
13
  })
14
//   ┌─── Effect<{ id: string }, UserRepoError, never>

Repetition at the boundary is the price of typed failure everywhere above it. Each wrapper is mechanical; do not abstract until you’ve written three and seen the shared shape.

Your turn wrap a Promise-returning legacy `saveUser` function with `Effect.tryPromise`, returning a tagged `UserRepoError` on rejection. Assert the success path resolves and the rejection path lands as a `Failure` carrying the tagged error.

Bridge with `ManagedRuntime` when call sites are scattered

Effect.runPromise is fine when every entrypoint can share a single Layer.provide. In a legacy codebase, every controller, every job, every React effect is its own call site.

ManagedRuntime.make builds the layer once and exposes runtime.runPromise (and runSync, runFork) that close over it — so every scattered call site picks up the same wired services without rebuilding the layer.

1
import { Effect, ManagedRuntime, Layer } from "effect"
2

3
const AppLayer = Layer.mergeAll(UserRepoLive, PaymentLive, LoggerLive)
4

5
// Build the runtime once at process boundary.
6
export const runtime = ManagedRuntime.make(AppLayer)
7

8
// Anywhere in the legacy codebase:
9
function handleHttpRequest(req: Request) {
10
  return runtime.runPromise(saveUser(req.body))
11
}

The runtime owns the layer’s lifecycle — finalizers run when the runtime is disposed (await runtime.dispose()), which matters once Layers acquire connections or open files. For a process that never restarts, build once at startup and let it live for the lifetime of the program.

Your turn build a `ManagedRuntime` from a Layer that provides a `UserRepo` test double, then call `runtime.runPromise(saveUser(...))` from two different "call sites" and confirm both share the same service.

A Full Example

Wrapping a third-party Stripe-style charge function, hiding it behind a service, and composing it with a notification step.

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

3
class ChargeError extends Data.TaggedError("ChargeError")<{
4
  readonly cause: unknown
5
}> {}
6

7
interface LegacyPaymentSdk {
8
  readonly charge: (amount: number) => Promise<{ readonly id: string }>
9
}
10

11
class Payment extends Context.Service<Payment, { readonly charge: (amount: number) => Effect.Effect<string, ChargeError> }>()("Payment") {}
12

13
const PaymentLive = (sdk: LegacyPaymentSdk) =>
14
  Layer.succeed(
15
    Payment,
16
    Payment.of({
17
      charge: (amount) =>
18
        Effect.tryPromise({
19
          try: () => sdk.charge(amount).then((result) => result.id),
20
          catch: (cause) => new ChargeError({ cause }),
21
        }),
22
    }),
23
  )
24

25
//      ┌─── Effect<string, ChargeError, Payment>
26
//      ▼
27
const program = Effect.gen(function* () {
28
  const payment = yield* Payment
29
  const id = yield* payment.charge(2000)
30
  yield* Effect.logInfo("charged", { id })
31
  return id
32
})

The legacy SDK never leaves PaymentLive. Callers see a clean Effect-shaped service.

Common Pitfalls

1, Migrating everything at once. A single PR that touches every async function is unreviewable and reverts as a unit. Wrap one flow per change.

2, Using Effect.promise for code that can throw. Rejections become defects, which means typed recovery operators (catchTag, retry, mapError) cannot see them. Use Effect.tryPromise whenever rejection is possible.

3, Wrapping at the wrong layer. Wrapping inside business logic spreads the bridge across the codebase. Wrap once at the service boundary; everything upstream becomes pure Effect.

4, Ignoring the R channel. When the type becomes Effect<A, E, UserRepo | Payment | …>, the compiler is showing the project’s dependency graph. Provide each tag at the entrypoint; do not paper over with as any.

stubbed. - [ ] Lift a single Promise call with `Effect.tryPromise` — the typed failure mode in `E` is the payoff. - [ ] Hide the bridge behind a service so callers don't see the lift. - [ ] Read the migration-order beat — leaves first, composition root last.

The full test suite

The index.test.ts for this lesson, verbatim from steps/54-incremental-adoption/.

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

4
// =============================================================================
5
// 30 - Incremental Adoption: Bridge One Promise at a Time
6
// =============================================================================
7
//
8
// Wrap legacy Promise APIs with Effect.tryPromise, hide them behind a
9
// Context.Service, provide the implementation at the entrypoint.
10

11
class UserRepoError extends Data.TaggedError("UserRepoError")<{
12
  readonly cause: unknown
13
}> {}
14

15
type LegacyUser = {
16
  readonly id: string
17
  readonly name: string
18
}
19

20
interface LegacyUserRepo {
21
  readonly fetchUser: (id: string) => Promise<LegacyUser>
22
}
23

24
class UserRepo extends Context.Service<UserRepo, {
25
    readonly fetchUser: (id: string) => Effect.Effect<LegacyUser, UserRepoError>
26
  }>()("UserRepo") {}
27

28
const makeUserRepo = (legacy: LegacyUserRepo) => ({
29
  fetchUser: (id: string) =>
30
    Effect.tryPromise({
31
      try: () => legacy.fetchUser(id),
32
      catch: (cause) => new UserRepoError({ cause }),
33
    }),
34
})
35

36
//      ┌─── Effect<string, UserRepoError, UserRepo>
37
//      ▼
38
const greet = (id: string) =>
39
  Effect.gen(function* () {
40
    const repo = yield* UserRepo
41
    const user = yield* repo.fetchUser(id)
42
    return `Hello, ${user.name}`
43
  })
44

45
describe("30 - Incremental Adoption", () => {
46
  // @beat
47
  //   id: try-promise
48
  //   shape: one-todo
49
  //   title: Wrap a Promise with tryPromise
50
  //   teaches: Effect.tryPromise converts a rejectable Promise into an Effect whose failure is a typed value in E.
51
  //   hint: predict what `greet("user-1")` returns when the repo's fetchUser resolves to { name: "Ada" }
52
  it("wraps a Promise API without touching the call sites", async () => {
53
    const legacyRepo: LegacyUserRepo = {
54
      fetchUser: async (id) => ({ id, name: "Ada" }),
55
    }
56

57
    const result = await Effect.runPromise(
58
      greet("user-1").pipe(Effect.provideService(UserRepo, makeUserRepo(legacyRepo))),
59
    )
60

61
    expect(result).toBe(/* @stub */ "Hello, Ada" /* @end */)
62
  })
63
  // @end-beat
64

65
  // @beat
66
  //   id: hide-behind-service
67
  //   shape: multi-todo
68
  //   title: Hide the bridge behind a Context.Service
69
  //   teaches: A rejected Promise becomes a tagged UserRepoError in the E channel, ready for catchTag and retry.
70
  //   hint: the exit tag distinguishes success from failure; the inner error carries the tagged-error name defined on this file
71
  it("converts a thrown exception into a typed Effect failure", async () => {
72
    const legacyRepo: LegacyUserRepo = {
73
      fetchUser: async () => {
74
        throw new Error("database offline")
75
      },
76
    }
77

78
    const exit = await Effect.runPromiseExit(
79
      greet("user-1").pipe(Effect.provideService(UserRepo, makeUserRepo(legacyRepo))),
80
    )
81

82
    // Predict the exit shape and the tagged-error name surfaced through E.
83
    expect(exit._tag).toBe(/* @stub */ "Failure" /* @end */)
84
    if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
85
      expect(exit.cause.reasons[0].error._tag).toBe(/* @stub */ "UserRepoError" /* @end */)
86
    }
87
  })
88
  // @end-beat
89

90
  // @beat
91
  //   id: wrap-save-user
92
  //   shape: worked-then-your-turn
93
  //   title: Wrap a second Promise API the same way
94
  //   teaches: Every Promise-returning function at the boundary gets its own tryPromise wrapper; the pattern is always the same — try, catch, tagged error.
95
  //   hint: Effect.tryPromise({ try: () => legacy.saveUser(user), catch: (cause) => new UserWriteError({ cause }) })
96
  describe("wrapping a write API", () => {
97
    class UserWriteError extends Data.TaggedError("UserWriteError")<{
98
      readonly cause: unknown
99
    }> {}
100

101
    class UserWrite extends Context.Service<UserWrite, { readonly saveUser: (user: LegacyUser) => Effect.Effect<void, UserWriteError> }>()("UserWrite") {}
102

103
    it("worked example: fetchUser wraps a read Promise", async () => {
104
      const legacyRepo: LegacyUserRepo = {
105
        fetchUser: async (id) => ({ id, name: "Ada" }),
106
      }
107
      const result = await Effect.runPromise(
108
        greet("user-1").pipe(Effect.provideService(UserRepo, makeUserRepo(legacyRepo))),
109
      )
110
      expect(result).toBe("Hello, Ada")
111
    })
112

113
    it("your turn: wrap saveUser with tryPromise the same way", async () => {
114
      interface LegacyUserWrite {
115
        readonly saveUser: (user: LegacyUser) => Promise<void>
116
      }
117

118
      const makeLegacyUserWrite = (legacy: LegacyUserWrite) => ({
119
        saveUser: (user: LegacyUser): Effect.Effect<void, UserWriteError> =>
120
          /* @stub */ Effect.tryPromise({
121
            try: () => legacy.saveUser(user),
122
            catch: (cause) => new UserWriteError({ cause }),
123
          }) /* @end */,
124
      })
125

126
      const saved: LegacyUser[] = []
127
      const legacyWrite: LegacyUserWrite = {
128
        saveUser: async (user) => {
129
          saved.push(user)
130
        },
131
      }
132

133
      await Effect.runPromise(
134
        Effect.gen(function* () {
135
          const write = yield* UserWrite
136
          yield* write.saveUser({ id: "u1", name: "Ada" })
137
        }).pipe(Effect.provideService(UserWrite, makeLegacyUserWrite(legacyWrite))),
138
      )
139

140
      expect(saved).toEqual([{ id: "u1", name: "Ada" }])
141
    })
142
  })
143
  // @end-beat
144

145
  // @beat
146
  //   id: managed-runtime
147
  //   shape: multi-todo
148
  //   title: Share a Layer across call sites with ManagedRuntime
149
  //   teaches: ManagedRuntime.make builds the layer once and exposes runtime.runPromise — use it to integrate Effect into an existing codebase where every call site cannot share a single Effect entry point.
150
  //   hint: each greet call reuses the cached UserRepo, so the constructor body runs a fixed number of times across the two runPromise calls
151
  it("ManagedRuntime builds the layer once and shares it across call sites", async () => {
152
    let constructions = 0
153

154
    const CountedRepo = Layer.sync(UserRepo, () => {
155
      constructions += 1
156
      return makeUserRepo({ fetchUser: async (id) => ({ id, name: "Ada" }) })
157
    })
158

159
    //      ┌─── ManagedRuntime<UserRepo, never>
160
    //      ▼
161
    const runtime = ManagedRuntime.make(CountedRepo)
162

163
    // Two independent runPromise calls — the layer is only built once.
164
    const a = await runtime.runPromise(greet("u1"))
165
    const b = await runtime.runPromise(greet("u2"))
166

167
    // Predict the greeting both calls return, and the construction count after sharing the runtime.
168
    expect(a).toBe(/* @stub */ "Hello, Ada" /* @end */)
169
    expect(b).toBe(/* @stub */ "Hello, Ada" /* @end */)
170
    expect(constructions).toBe(/* @stub */ 1 /* @end */)
171

172
    await runtime.dispose()
173
  })
174
  // @end-beat
175

176
  // @beat
177
  //   id: wrap-legacy
178
  //   shape: one-todo
179
  //   title: Wrap a throwing legacy function in Effect.try
180
  //   teaches: Effect.try converts a throwing function into an Effect whose error channel holds a typed value — the first step of incremental adoption is at the boundary between legacy and Effect code.
181
  //   hint: Effect.try({ try: () => legacyFn(input), catch: (cause) => new YourError({ cause }) })
182

183
  it("wraps a throwing legacy function and surfaces the exception as a typed error", () => {
184
    class ParseError extends Data.TaggedError("ParseError")<{
185
      readonly cause: unknown
186
    }> {}
187

188
    // Legacy function — throws on bad input, outside our control
189
    const legacyParse = (input: string): { id: number } => {
190
      const n = parseInt(input)
191
      if (isNaN(n)) throw new TypeError(`Cannot parse: ${input}`)
192
      return { id: n }
193
    }
194

195
    // Your turn: wrap legacyParse in Effect.try so bad input surfaces as ParseError in E.
196
    const safeParse = (input: string) =>
197
      /* @stub */ Effect.try({
198
        try: () => legacyParse(input),
199
        catch: (cause) => new ParseError({ cause }),
200
      }) /* @end */
201

202
    expect(Effect.runSync(safeParse("42"))).toEqual({ id: 42 })
203

204
    const failExit = Effect.runSyncExit(safeParse("not-a-number"))
205
    expect(failExit._tag).toBe("Failure")
206
  })
207
  // @end-beat
208
})

10·04Incremental Adoption

54 - Incremental Adoption: Bridge One Promise at a Time

What you’ll work through

The Bridge

`Effect.tryPromise`

`Effect.promise`

Hiding the Bridge Behind a Service

Migration Order

Wrap a throwing legacy function with `Effect.try`

Wrap each Promise-returning function at the boundary

Bridge with `ManagedRuntime` when call sites are scattered

A Full Example

Common Pitfalls

See Also

The full test suite

10·04Incremental Adoption

54 - Incremental Adoption: Bridge One Promise at a Time

What you’ll work through

The Bridge

Effect.tryPromise

Effect.promise

Hiding the Bridge Behind a Service

Migration Order

Wrap a throwing legacy function with Effect.try

Wrap each Promise-returning function at the boundary

Bridge with ManagedRuntime when call sites are scattered

A Full Example

Common Pitfalls

See Also

The full test suite

`Effect.tryPromise`

`Effect.promise`

Wrap a throwing legacy function with `Effect.try`

Bridge with `ManagedRuntime` when call sites are scattered