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

4
// =============================================================================
5
// 03 - Effect Basics: Creating and Running Effects
6
// =============================================================================
7
//
8
// An Effect<A, E, R> is an immutable, lazy description of a computation.
9
// Creating one does nothing. A runner — Effect.runSync, Effect.runPromise,
10
// or their *Exit variants — turns the description into execution.
11

12
// @beat
13
//   id: succeed-and-fail
14
//   shape: multi-todo
15
//   title: Express success and failure
16
//   teaches: Effect.succeed and Effect.fail lift known values into the success or error channel.
17
//   hint: use Effect.succeed for the value and Effect.fail for the error
18
it("Effect.succeed places a value in the A channel", () => {
19
  //      ┌─── Effect<number, never, never>
20
  //      ▼
21
  const program = /* @stub */ Effect.succeed(42) /* @end */
22
  expect(Effect.runSync(program)).toBe(42)
23
})
24

25
it("Effect.fail places an error in the E channel", () => {
26
  class NotFound {
27
    readonly _tag = "NotFound"
28
  }
29

30
  //      ┌─── Effect<never, NotFound, never>
31
  //      ▼
32
  const program = /* @stub */ Effect.fail(new NotFound()) /* @end */
33
  const exit = Effect.runSyncExit(program)
34
  expect(Exit.isFailure(exit)).toBe(true)
35
})
36
// @end-beat
37

38
// @beat
39
//   id: wrap-sync
40
//   shape: one-todo
41
//   title: Defer a synchronous side effect
42
//   teaches: Effect.sync wraps a thunk; the thunk runs on every execution.
43
//   hint: wrap the body in Effect.sync(() => { ... })
44
it("Effect.sync defers and re-runs the thunk", () => {
45
  let counter = 0
46

47
  //      ┌─── Effect<number, never, never>
48
  //      ▼
49
  const increment = /* @stub */ Effect.sync(() => {
50
    counter += 1
51
    return counter
52
  }) /* @end */
53

54
  // Building the effect did nothing yet.
55
  expect(counter).toBe(0)
56

57
  // Running it executes the thunk — every time.
58
  expect(Effect.runSync(increment)).toBe(1)
59
  expect(Effect.runSync(increment)).toBe(2)
60
  expect(counter).toBe(2)
61
})
62
// @end-beat
63

64
// @beat
65
//   id: wrap-throwing
66
//   shape: one-todo
67
//   title: Wrap code that may throw
68
//   teaches: Effect.try maps a thrown exception into a typed E value via the catch callback.
69
//   hint: Effect.try takes { try, catch }; the catch maps unknown to a typed error
70
it("Effect.try converts an exception into a typed error", () => {
71
  class ParseError {
72
    readonly _tag = "ParseError"
73
    constructor(readonly cause: unknown) {}
74
  }
75

76
  //      ┌─── Effect<unknown, ParseError, never>
77
  //      ▼
78
  const program = /* @stub */ Effect.try({
79
    try: () => JSON.parse("{ invalid }") as unknown,
80
    catch: (cause) => new ParseError(cause),
81
  }) /* @end */
82

83
  const exit = Effect.runSyncExit(program)
84
  expect(Exit.isFailure(exit)).toBe(true)
85
})
86
// @end-beat
87

88
// @beat
89
//   id: runners
90
//   shape: worked-then-your-turn
91
//   title: Pick a runner
92
//   teaches: runSync and runPromise throw on failure; the *Exit variants return a typed Exit instead.
93
//   hint: use Effect.runPromiseExit for the async path
94
it("runSync returns A directly (worked example)", () => {
95
  expect(Effect.runSync(Effect.succeed(1))).toBe(1)
96
})
97

98
it("runSyncExit never throws — it returns an Exit (worked example)", () => {
99
  const success = Effect.runSyncExit(Effect.succeed(1))
100
  expect(Exit.isSuccess(success)).toBe(true)
101

102
  const failure = Effect.runSyncExit(Effect.fail("boom"))
103
  expect(Exit.isFailure(failure)).toBe(true)
104
})
105

106
it("runPromiseExit: your turn — return an Exit from an async run", async () => {
107
  //      ┌─── Promise<Exit<number, never>>
108
  //      ▼
109
  const exit = await /* @stub */ Effect.runPromiseExit(Effect.succeed(99)) /* @end */
110
  expect(Exit.isSuccess(exit)).toBe(true)
111
})
112
// @end-beat
113

114
// @beat
115
//   id: sync-vs-async-runner
116
//   shape: read-run
117
//   title: runSync throws on async effects
118
//   teaches: Effect.runSync can only execute synchronous effects; calling it on any effect that contains an asynchronous step (Promise, sleep, async callback) throws at runtime.
119
//   hint: run the test and read the thrown message — it tells you to use runPromise instead
120
it("throws at runtime when the effect is asynchronous", () => {
121
  const asyncEffect = Effect.promise(() => Promise.resolve(42))
122

123
  expect(() => Effect.runSync(asyncEffect)).toThrow()
124
})
125

126
it("runPromise handles the same async effect without throwing", async () => {
127
  const asyncEffect = Effect.promise(() => Promise.resolve(42))
128

129
  await expect(Effect.runPromise(asyncEffect)).resolves.toBe(42)
130
})
131
// @end-beat
132

133
// @beat
134
//   id: compose
135
//   shape: multi-todo
136
//   title: Compose — parse, then validate
137
//   teaches: Effect.flatMap chains an effect onto the success channel; the E channel widens to the union of all possible failures.
138
//   hint: Effect.try produces ParseError; the flatMap branch produces ValidationError
139
it("composes Effect.try with a validation step", () => {
140
  type User = { readonly name: string }
141

142
  class ParseError {
143
    readonly _tag = "ParseError"
144
    constructor(readonly cause: unknown) {}
145
  }
146
  class ValidationError {
147
    readonly _tag = "ValidationError"
148
  }
149

150
  const isUser = (value: unknown): value is User =>
151
    typeof value === "object" &&
152
    value !== null &&
153
    "name" in value &&
154
    typeof (value as { name: unknown }).name === "string"
155

156
  //      ┌─── Effect<User, ParseError | ValidationError, never>
157
  //      ▼
158
  const parseUser = (input: string) =>
159
    /* @stub */ Effect.try({
160
      try: () => JSON.parse(input) as unknown,
161
      catch: (cause) => new ParseError(cause),
162
    }) /* @end */.pipe(
163
      Effect.flatMap((value) =>
164
        /* @stub */ isUser(value)
165
          ? Effect.succeed(value)
166
          : Effect.fail(new ValidationError()) /* @end */
167
      )
168
    )
169

170
  expect(Effect.runSync(parseUser('{"name":"Alice"}'))).toEqual({ name: "Alice" })
171
  expect(Exit.isFailure(Effect.runSyncExit(parseUser("not json")))).toBe(true)
172
  expect(Exit.isFailure(Effect.runSyncExit(parseUser('{"name":42}')))).toBe(true)
173
})
174
// @end-beat