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

4
// =============================================================================
5
// 31 - HTTP Client Patterns: Decode at the Boundary
6
// =============================================================================
7
//
8
// The README uses @effect/platform's HttpClient. Here we model the same
9
// four-gate flow against a minimal HttpClient tag so the test runs with
10
// effect alone: transport → status → schema → domain value.
11

12
class HttpFailure extends Data.TaggedError("HttpFailure")<{
13
  readonly reason: string
14
}> {}
15

16
class UserNotFound extends Data.TaggedError("UserNotFound")<{
17
  readonly id: string
18
}> {}
19

20
class InvalidUserResponse extends Data.TaggedError("InvalidUserResponse")<{
21
  readonly cause: unknown
22
}> {}
23

24
const User = Schema.Struct({
25
  id: Schema.String,
26
  name: Schema.String,
27
})
28

29
type User = typeof User.Type
30

31
type Response = {
32
  readonly status: number
33
  readonly body: unknown
34
}
35

36
class HttpClient extends Context.Service<HttpClient, {
37
    readonly get: (url: string) => Effect.Effect<Response, HttpFailure>
38
  }>()("HttpClient") {}
39

40
//      ┌─── Effect<User, HttpFailure | UserNotFound | InvalidUserResponse, HttpClient>
41
//      ▼
42
const getUser = (id: string) =>
43
  Effect.gen(function* () {
44
    const http = yield* HttpClient
45
    const response = yield* http.get(`/users/${id}`)
46

47
    if (response.status === 404) {
48
      return yield* Effect.fail(new UserNotFound({ id }))
49
    }
50
    if (response.status >= 400) {
51
      return yield* Effect.fail(
52
        new HttpFailure({ reason: `unexpected status ${response.status}` }),
53
      )
54
    }
55

56
    return yield* Effect.try({
57
      try: () => Schema.decodeUnknownSync(User)(response.body),
58
      catch: (cause) => new InvalidUserResponse({ cause }),
59
    })
60
  })
61

62
describe("31 - HTTP Client Patterns", () => {
63
  // @beat
64
  //   id: decode-body
65
  //   shape: one-todo
66
  //   title: Decode the body at the boundary
67
  //   teaches: HttpClient yields a Response; schema decoding turns its unknown body into a typed domain value.
68
  //   hint: the schema is identity-shaped — a matching 200 body returns the same fields
69
  it("decodes a 200 body into a domain value", async () => {
70
    const user = await Effect.runPromise(
71
      getUser("1").pipe(
72
        Effect.provideService(HttpClient, {
73
          get: () => Effect.succeed({ status: 200, body: { id: "1", name: "Ada" } }),
74
        }),
75
      ),
76
    )
77

78
    // Predict the decoded domain value the pipeline returns.
79
    expect(user).toEqual(/* @stub */ { id: "1", name: "Ada" } /* @end */)
80
  })
81
  // @end-beat
82

83
  // @beat
84
  //   id: status-branching
85
  //   shape: one-todo
86
  //   title: Branch on status before decoding
87
  //   teaches: A 404 becomes a UserNotFound tag before any schema runs, keeping decoding errors distinct from missing resources.
88
  //   hint: which tagged error in this file represents a missing resource? that's the tag a 404 should surface
89
  it("translates a 404 into a tagged domain error", async () => {
90
    const exit = await Effect.runPromiseExit(
91
      getUser("missing").pipe(
92
        Effect.provideService(HttpClient, {
93
          get: () => Effect.succeed({ status: 404, body: { message: "missing" } }),
94
        }),
95
      ),
96
    )
97

98
    expect(exit._tag).toBe("Failure")
99
    if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
100
      // Predict the domain tag a 404 surfaces in E.
101
      expect(exit.cause.reasons[0].error._tag).toBe(/* @stub */ "UserNotFound" /* @end */)
102
    }
103
  })
104
  // @end-beat
105

106
  // @beat
107
  //   id: schema-validation
108
  //   shape: one-todo
109
  //   title: Reject wire shapes that violate the schema
110
  //   teaches: Schema.decodeUnknownSync surfaces a ParseError that lands in E as InvalidUserResponse instead of crashing downstream.
111
  //   hint: schema decode failures get caught and rethrown as which tagged error declared above?
112
  it("fails fast when the wire format does not match the schema", async () => {
113
    const exit = await Effect.runPromiseExit(
114
      getUser("1").pipe(
115
        Effect.provideService(HttpClient, {
116
          get: () => Effect.succeed({ status: 200, body: { id: 1, wrong: true } }),
117
        }),
118
      ),
119
    )
120

121
    expect(exit._tag).toBe("Failure")
122
    if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
123
      // Predict the tag the schema-decode catch handler emits.
124
      expect(exit.cause.reasons[0].error._tag).toBe(/* @stub */ "InvalidUserResponse" /* @end */)
125
    }
126
  })
127
  // @end-beat
128

129
  // @beat
130
  //   id: add-retry
131
  //   shape: one-todo
132
  //   title: Add a retry schedule to a flaky HTTP request
133
  //   teaches: Effect.retry wraps any Effect and re-runs it on failure according to a Schedule; the E channel is unchanged — retries are transparent to callers.
134
  //   hint: program.pipe(Effect.retry(Schedule.recurs(2))) — retries up to 2 times on any failure
135

136
  it("retries a flaky request up to N times before failing", async () => {
137
    let attempts = 0
138

139
    const flakyClient = {
140
      get: (_url: string): Effect.Effect<Response, HttpFailure> => {
141
        attempts++
142
        if (attempts < 3) {
143
          return Effect.fail(new HttpFailure({ reason: "transient" }))
144
        }
145
        return Effect.succeed({ status: 200, body: { id: "1", name: "Ada" } })
146
      },
147
    }
148

149
    const program = /* @stub */ getUser("1").pipe(
150
      Effect.provideService(HttpClient, flakyClient),
151
      Effect.retry(Schedule.recurs(2)),
152
    ) /* @end */
153

154
    const user = await Effect.runPromise(program)
155
    expect(user.name).toBe("Ada")
156
    expect(attempts).toBe(3)
157
  })
158
  // @end-beat
159
})