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

4
// =============================================================================
5
// 39b - Deferred: One-Shot Communication Between Fibers
6
// =============================================================================
7
//
8
// Deferred.make          create an empty one-shot cell     — Effect<Deferred<A, E>>
9
// Deferred.await         block until a value is available  — Effect<A, E>
10
// Deferred.succeed       resolve with a success value      — Effect<boolean>
11
// Deferred.fail          resolve with a failure            — Effect<boolean>
12
// Deferred.isDone        check without blocking            — Effect<boolean>
13
//
14
// A Deferred can be completed exactly once. Any fiber that awaits before
15
// completion suspends; any fiber that awaits after completion gets the value
16
// immediately. Think of it as a typed, Effect-native Promise.
17

18
describe("39b - Deferred", () => {
19
  // @beat
20
  //   id: make-and-succeed
21
  //   shape: one-todo
22
  //   title: Create a Deferred and resolve it
23
  //   teaches: Deferred.make creates an empty cell; Deferred.succeed fills it; Deferred.await unblocks and returns the value.
24
  //   hint: yield* Deferred.make<number>(), then yield* Deferred.succeed(deferred, 42), then yield* Deferred.await(deferred)
25
  describe("Deferred.make and Deferred.succeed", () => {
26
    it("resolves and unblocks await", async () => {
27
      //      ┌─── Effect<number>
28
      //      ▼
29
      const program = /* @stub */ Effect.gen(function* () {
30
        const deferred = yield* Deferred.make<number>()
31
        yield* Deferred.succeed(deferred, 42)
32
        return yield* Deferred.await(deferred)
33
      }) /* @end */
34

35
      expect(await Effect.runPromise(program)).toBe(42)
36
    })
37

38
    it("allows multiple fibers to await the same value", async () => {
39
      const program = Effect.gen(function* () {
40
        const deferred = yield* Deferred.make<string>()
41

42
        // Two waiters, one resolver.
43
        const waiter1 = yield* Effect.forkChild(Deferred.await(deferred))
44
        const waiter2 = yield* Effect.forkChild(Deferred.await(deferred))
45

46
        yield* Deferred.succeed(deferred, "hello")
47

48
        return [yield* Fiber.join(waiter1), yield* Fiber.join(waiter2)]
49
      })
50

51
      expect(await Effect.runPromise(program)).toEqual(["hello", "hello"])
52
    })
53
  })
54
  // @end-beat
55

56
  // @beat
57
  //   id: fail-a-deferred
58
  //   shape: one-todo
59
  //   title: Propagate failure through a Deferred
60
  //   teaches: Deferred.fail resolves the cell with a typed failure; any fiber awaiting it receives that failure in its E channel.
61
  //   hint: Deferred.make<number, string>(), then Deferred.fail(deferred, "bad input"), then Deferred.await propagates the failure
62
  describe("Deferred.fail", () => {
63
    it("routes a failure to every fiber awaiting", async () => {
64
      //      ┌─── Exit<number, string>
65
      //      ▼
66
      const exit = await Effect.runPromiseExit(
67
        /* @stub */ Effect.gen(function* () {
68
          const deferred = yield* Deferred.make<number, string>()
69
          yield* Deferred.fail(deferred, "bad input")
70
          return yield* Deferred.await(deferred)
71
        }) /* @end */,
72
      )
73

74
      expect(Exit.isFailure(exit)).toBe(true)
75
      if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
76
        expect(exit.cause.reasons[0].error).toBe("bad input")
77
      }
78
    })
79
  })
80
  // @end-beat
81

82
  // @beat
83
  //   id: cross-fiber
84
  //   shape: one-todo
85
  //   title: Hand off a value between two fibers
86
  //   teaches: A Deferred is the idiomatic channel for one-shot fiber-to-fiber communication — simpler than a Queue when only one value will ever be sent.
87
  //   hint: the consumer awaits the Deferred, then doubles whatever value the producer publishes — the producer publishes 21
88
  describe("cross-fiber hand-off", () => {
89
    it("suspends the consumer until the producer resolves", async () => {
90
      const program = Effect.gen(function* () {
91
        const gate = yield* Deferred.make<number>()
92

93
        const consumer = yield* Effect.forkChild(
94
          Deferred.await(gate).pipe(Effect.map((n) => n * 2)),
95
        )
96

97
        // Give the consumer a moment to suspend, then produce.
98
        yield* Effect.yieldNow
99
        yield* Deferred.succeed(gate, 21)
100

101
        return yield* Fiber.join(consumer)
102
      })
103

104
      // Predict the value the joined consumer fiber returns.
105
      expect(await Effect.runPromise(program)).toBe(/* @stub */ 42 /* @end */)
106
    })
107
  })
108
  // @end-beat
109

110
  // @beat
111
  //   id: is-done
112
  //   shape: multi-todo
113
  //   title: Check completion without blocking
114
  //   teaches: Deferred.isDone returns a boolean Effect that never suspends — use it to poll state without risking a deadlock.
115
  //   hint: predict the boolean before vs after Deferred.succeed lands
116
  describe("Deferred.isDone", () => {
117
    it("reports false before completion and true after", async () => {
118
      const program = Effect.gen(function* () {
119
        const deferred = yield* Deferred.make<number>()
120
        const before = yield* Deferred.isDone(deferred)
121
        yield* Deferred.succeed(deferred, 1)
122
        const after = yield* Deferred.isDone(deferred)
123
        return { before, after }
124
      })
125

126
      const result = await Effect.runPromise(program)
127
      // Predict isDone before vs after Deferred.succeed
128
      expect(result.before).toBe(/* @stub */ false /* @end */)
129
      expect(result.after).toBe(/* @stub */ true /* @end */)
130
    })
131
  })
132
  // @end-beat
133
})