Render a more helpful error message in Effect.timeout (#3228)

.changeset/famous-windows-poke.md

@@ -0,0 +1,5 @@
+---
+"effect": patch
+---
+
+Render a more helpful error message when timing out an effect

packages/effect/src/internal/core.ts

@@ -5,6 +5,7 @@ import * as Chunk from "../Chunk.js"
 import * as Context from "../Context.js"
 import type * as Deferred from "../Deferred.js"
 import type * as Differ from "../Differ.js"
+import * as Duration from "../Duration.js"
 import type * as Effect from "../Effect.js"
 import * as Either from "../Either.js"
 import * as Equal from "../Equal.js"
@@ -2297,6 +2298,9 @@ export const TimeoutExceptionTypeId: Cause.TimeoutExceptionTypeId = Symbol.for(
 export const TimeoutException = makeException<Cause.TimeoutException>({
   [TimeoutExceptionTypeId]: TimeoutExceptionTypeId
 }, "TimeoutException")
+/** @internal */
+export const timeoutExceptionFromDuration = (duration: Duration.DurationInput): Cause.TimeoutException =>
+  new TimeoutException(`Operation timed out before the specified duration of '${Duration.format(duration)}' elapsed`)
 
 /** @internal */
 export const isTimeoutException = (u: unknown): u is Cause.TimeoutException => hasProperty(u, TimeoutExceptionTypeId)

packages/effect/src/internal/effect/circular.ts

@@ -419,7 +419,7 @@ export const timeout = dual<
   ) => Effect.Effect<A, E | Cause.TimeoutException, R>
 >(2, (self, duration) =>
   timeoutFail(self, {
-    onTimeout: () => new core.TimeoutException(),
+    onTimeout: () => core.timeoutExceptionFromDuration(duration),
     duration
   }))
 

packages/effect/test/Effect/timeout.test.ts

@@ -10,6 +10,21 @@ import * as TestClock from "effect/TestClock"
 import { assert, describe } from "vitest"
 
 describe("Effect", () => {
+  it.effect("timeout produces a useful error message", () =>
+    Effect.gen(function*() {
+      const duration = Duration.millis(1500)
+      const fiber = yield* Effect.never.pipe(
+        Effect.timeout(duration),
+        Effect.flip,
+        Effect.fork
+      )
+      yield* TestClock.adjust(Duration.millis(2000))
+      const result = yield* Fiber.join(fiber)
+      assert.include(
+        result.toString(),
+        "TimeoutException: Operation timed out before the specified duration of '1s 500ms' elapsed"
+      )
+    }))
   it.live("timeout a long computation", () =>
     Effect.gen(function*($) {
       const result = yield* $(