effect 4.0.0-beta.101 → 4.0.0-beta.103

package/src/FiberHandle.ts

@@ -35,18 +35,20 @@ const TypeId = "~effect/FiberHandle"
  *
  * **Example** (Managing a single fiber)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   // Create a FiberHandle that can hold fibers producing strings
  *   const handle = yield* FiberHandle.make<string, never>()
  *
  *   // The handle can store and manage a single fiber
  *   const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello"))
- *   const result = yield* Fiber.await(fiber)
- *   console.log(result) // "hello"
+ *   return yield* Fiber.join(fiber)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => "hello"
  * ```
  *
  * @category models
@@ -69,18 +71,20 @@ export interface FiberHandle<out A = unknown, out E = unknown> extends Pipeable,
  *
  * **Example** (Checking fiber handles)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *
- *   console.log(FiberHandle.isFiberHandle(handle)) // true
- *   console.log(FiberHandle.isFiberHandle("not a handle")) // false
+ *   return [FiberHandle.isFiberHandle(handle), FiberHandle.isFiberHandle("not a handle")]
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => [true, false]
  * ```
  *
- * @category refinements
+ * @category guards
  * @since 2.0.0
  */
 export const isFiberHandle = (u: unknown): u is FiberHandle => Predicate.hasProperty(u, TypeId)
@@ -115,10 +119,10 @@ const makeUnsafe = <A = unknown, E = unknown>(): FiberHandle<A, E> => {
  *
  * **Example** (Creating a scoped fiber handle)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *
  *   // run some effects
@@ -126,10 +130,14 @@ const makeUnsafe = <A = unknown, E = unknown>(): FiberHandle<A, E> => {
  *   // this will interrupt the previous fiber
  *   yield* FiberHandle.run(handle, Effect.never)
  *
- *   yield* Effect.sleep(1000)
+ *   yield* Effect.yieldNow
+ *   return handle.state._tag === "Open" && handle.state.fiber !== undefined
  * }).pipe(
  *   Effect.scoped // The fiber will be interrupted when the scope is closed
  * )
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => true
  * ```
  *
  * @category constructors
@@ -162,20 +170,24 @@ export const make = <A = unknown, E = unknown>(): Effect.Effect<FiberHandle<A, E
  *
  * **Example** (Running effects with a fiber handle)
  *
- * ```ts
- * import { Effect, Fiber, FiberHandle } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect, Exit, Fiber, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const run = yield* FiberHandle.makeRuntime<never>()
  *
  *   // Run effects and get fibers back
- *   const fiberA = run(Effect.succeed("first"))
+ *   const fiberA = run(Effect.never)
  *   const fiberB = run(Effect.succeed("second"))
  *
  *   // The second fiber will interrupt the first
  *   const resultA = yield* Fiber.await(fiberA)
  *   const resultB = yield* Fiber.await(fiberB)
+ *   return [resultA, resultB]
  * }).pipe(Effect.scoped)
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [Exit.failCause(Cause.interrupt(-1)), Exit.succeed("second")]
  * ```
  *
  * @category constructors
@@ -218,17 +230,19 @@ export const makeRuntime = <R, E = unknown, A = unknown>(): Effect.Effect<
  *
  * **Example** (Running effects as promises)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const run = yield* FiberHandle.makeRuntimePromise()
  *
  *   // Run effects and get promises back
  *   const promise = run(Effect.succeed("hello"))
- *   const result = yield* Effect.promise(() => promise)
- *   console.log(result) // "hello"
+ *   return yield* Effect.promise(() => promise)
  * }).pipe(Effect.scoped)
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => "hello"
  * ```
  *
  * @category constructors
@@ -269,10 +283,10 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  *
  * **Example** (Setting a fiber unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *   const fiber = Effect.runFork(Effect.succeed("hello"))
  *
@@ -280,9 +294,11 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  *   FiberHandle.setUnsafe(handle, fiber)
  *
  *   // The fiber is now managed by the handle
- *   const result = yield* Fiber.await(fiber)
- *   console.log(result) // "hello"
+ *   return yield* Fiber.join(fiber)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => "hello"
  * ```
  *
  * @category combinators
@@ -300,10 +316,10 @@ export const setUnsafe: {
    *
    * **Example** (Setting a fiber unsafely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
-   * Effect.gen(function*() {
+   * const program = Effect.gen(function*() {
    *   const handle = yield* FiberHandle.make()
    *   const fiber = Effect.runFork(Effect.succeed("hello"))
    *
@@ -311,9 +327,11 @@ export const setUnsafe: {
    *   FiberHandle.setUnsafe(handle, fiber)
    *
    *   // The fiber is now managed by the handle
-   *   const result = yield* Fiber.await(fiber)
-   *   console.log(result) // "hello"
+   *   return yield* Fiber.join(fiber)
    * })
+   *
+   * const actual = await Effect.runPromise(Effect.scoped(program))
+   * actual // => "hello"
    * ```
    *
    * @category combinators
@@ -337,10 +355,10 @@ export const setUnsafe: {
    *
    * **Example** (Setting a fiber unsafely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
-   * Effect.gen(function*() {
+   * const program = Effect.gen(function*() {
    *   const handle = yield* FiberHandle.make()
    *   const fiber = Effect.runFork(Effect.succeed("hello"))
    *
@@ -348,9 +366,11 @@ export const setUnsafe: {
    *   FiberHandle.setUnsafe(handle, fiber)
    *
    *   // The fiber is now managed by the handle
-   *   const result = yield* Fiber.await(fiber)
-   *   console.log(result) // "hello"
+   *   return yield* Fiber.join(fiber)
    * })
+   *
+   * const actual = await Effect.runPromise(Effect.scoped(program))
+   * actual // => "hello"
    * ```
    *
    * @category combinators
@@ -415,10 +435,10 @@ export const setUnsafe: {
  *
  * **Example** (Setting a fiber safely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *   const fiber = Effect.runFork(Effect.succeed("hello"))
  *
@@ -426,9 +446,11 @@ export const setUnsafe: {
  *   yield* FiberHandle.set(handle, fiber)
  *
  *   // The fiber is now managed by the handle
- *   const result = yield* Fiber.await(fiber)
- *   console.log(result) // "hello"
+ *   return yield* Fiber.join(fiber)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => "hello"
  * ```
  *
  * @category combinators
@@ -446,10 +468,10 @@ export const set: {
    *
    * **Example** (Setting a fiber safely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
-   * Effect.gen(function*() {
+   * const program = Effect.gen(function*() {
    *   const handle = yield* FiberHandle.make()
    *   const fiber = Effect.runFork(Effect.succeed("hello"))
    *
@@ -457,9 +479,11 @@ export const set: {
    *   yield* FiberHandle.set(handle, fiber)
    *
    *   // The fiber is now managed by the handle
-   *   const result = yield* Fiber.await(fiber)
-   *   console.log(result) // "hello"
+   *   return yield* Fiber.join(fiber)
    * })
+   *
+   * const actual = await Effect.runPromise(Effect.scoped(program))
+   * actual // => "hello"
    * ```
    *
    * @category combinators
@@ -483,10 +507,10 @@ export const set: {
    *
    * **Example** (Setting a fiber safely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
-   * Effect.gen(function*() {
+   * const program = Effect.gen(function*() {
    *   const handle = yield* FiberHandle.make()
    *   const fiber = Effect.runFork(Effect.succeed("hello"))
    *
@@ -494,9 +518,11 @@ export const set: {
    *   yield* FiberHandle.set(handle, fiber)
    *
    *   // The fiber is now managed by the handle
-   *   const result = yield* Fiber.await(fiber)
-   *   console.log(result) // "hello"
+   *   return yield* Fiber.join(fiber)
    * })
+   *
+   * const actual = await Effect.runPromise(Effect.scoped(program))
+   * actual // => "hello"
    * ```
    *
    * @category combinators
@@ -535,21 +561,23 @@ export const set: {
  *
  * **Example** (Reading the current fiber unsafely)
  *
- * ```ts
- * import { Effect, FiberHandle } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FiberHandle, Option } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *
  *   // No fiber initially
  *   const emptyFiber = FiberHandle.getUnsafe(handle)
- *   console.log(emptyFiber._tag === "None") // true
  *
  *   // Add a fiber
- *   yield* FiberHandle.run(handle, Effect.succeed("hello"))
+ *   yield* FiberHandle.run(handle, Effect.never)
  *   const fiber = FiberHandle.getUnsafe(handle)
- *   console.log(fiber._tag === "Some") // true
+ *   return [emptyFiber, Option.map(fiber, () => true)]
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => [Option.none(), Option.some(true)]
  * ```
  *
  * @category combinators
@@ -564,22 +592,22 @@ export function getUnsafe<A, E>(self: FiberHandle<A, E>): Option.Option<Fiber.Fi
  *
  * **Example** (Reading the current fiber)
  *
- * ```ts
- * import { Effect, Fiber, FiberHandle } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FiberHandle, Option } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *
  *   // Add a fiber
- *   yield* FiberHandle.run(handle, Effect.succeed("hello"))
+ *   yield* FiberHandle.run(handle, Effect.never)
  *
  *   // Get the current fiber if present
  *   const fiber = yield* FiberHandle.get(handle)
- *   if (fiber._tag === "Some") {
- *     const result = yield* Fiber.await(fiber.value)
- *     console.log(result) // "hello"
- *   }
+ *   return Option.map(fiber, () => true)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => Option.some(true)
  * ```
  *
  * @category combinators
@@ -595,10 +623,10 @@ export function get<A, E>(self: FiberHandle<A, E>): Effect.Effect<Option.Option<
  *
  * **Example** (Clearing a fiber handle)
  *
- * ```ts
- * import { Effect, FiberHandle } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FiberHandle, Option } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *
  *   // Add a fiber
@@ -608,9 +636,11 @@ export function get<A, E>(self: FiberHandle<A, E>): Effect.Effect<Option.Option<
  *   yield* FiberHandle.clear(handle)
  *
  *   // The handle is now empty
- *   const fiber = FiberHandle.getUnsafe(handle)
- *   console.log(fiber) // Option.none()
+ *   return FiberHandle.getUnsafe(handle)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => Option.none()
  * ```
  *
  * @category combinators
@@ -621,10 +651,11 @@ export const clear = <A, E>(self: FiberHandle<A, E>): Effect.Effect<void> =>
     if (self.state._tag === "Closed" || self.state.fiber === undefined) {
       return Effect.void
     }
+    const fiber = self.state.fiber
     return Effect.andThen(
-      restore(Fiber.interruptAs(self.state.fiber, internalFiberId)),
+      restore(Fiber.interruptAs(fiber, internalFiberId)),
       Effect.sync(() => {
-        if (self.state._tag === "Open") {
+        if (self.state._tag === "Open" && self.state.fiber === fiber) {
           self.state.fiber = undefined
         }
       })
@@ -652,22 +683,24 @@ const constInterruptedFiber = (function() {
  *
  * **Example** (Running an effect in a fiber handle)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *
  *   // Run an effect and get the fiber
  *   const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello"))
- *   const result = yield* Fiber.await(fiber)
- *   console.log(result) // "hello"
+ *   const result = yield* Fiber.join(fiber)
  *
  *   // Running another effect will interrupt the previous one
  *   const fiber2 = yield* FiberHandle.run(handle, Effect.succeed("world"))
- *   const result2 = yield* Fiber.await(fiber2)
- *   console.log(result2) // "world"
+ *   const result2 = yield* Fiber.join(fiber2)
+ *   return [result, result2]
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => ["hello", "world"]
  * ```
  *
  * @category combinators
@@ -685,22 +718,24 @@ export const run: {
    *
    * **Example** (Running an effect in a fiber handle)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
-   * Effect.gen(function*() {
+   * const program = Effect.gen(function*() {
    *   const handle = yield* FiberHandle.make()
    *
    *   // Run an effect and get the fiber
    *   const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello"))
-   *   const result = yield* Fiber.await(fiber)
-   *   console.log(result) // "hello"
+   *   const result = yield* Fiber.join(fiber)
    *
    *   // Running another effect will interrupt the previous one
    *   const fiber2 = yield* FiberHandle.run(handle, Effect.succeed("world"))
-   *   const result2 = yield* Fiber.await(fiber2)
-   *   console.log(result2) // "world"
+   *   const result2 = yield* Fiber.join(fiber2)
+   *   return [result, result2]
    * })
+   *
+   * const actual = await Effect.runPromise(Effect.scoped(program))
+   * actual // => ["hello", "world"]
    * ```
    *
    * @category combinators
@@ -727,22 +762,24 @@ export const run: {
    *
    * **Example** (Running an effect in a fiber handle)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
-   * Effect.gen(function*() {
+   * const program = Effect.gen(function*() {
    *   const handle = yield* FiberHandle.make()
    *
    *   // Run an effect and get the fiber
    *   const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello"))
-   *   const result = yield* Fiber.await(fiber)
-   *   console.log(result) // "hello"
+   *   const result = yield* Fiber.join(fiber)
    *
    *   // Running another effect will interrupt the previous one
    *   const fiber2 = yield* FiberHandle.run(handle, Effect.succeed("world"))
-   *   const result2 = yield* Fiber.await(fiber2)
-   *   console.log(result2) // "world"
+   *   const result2 = yield* Fiber.join(fiber2)
+   *   return [result, result2]
    * })
+   *
+   * const actual = await Effect.runPromise(Effect.scoped(program))
+   * actual // => ["hello", "world"]
    * ```
    *
    * @category combinators
@@ -795,28 +832,32 @@ const runImpl = <A, E, R, XE extends E, XA extends A>(
  *
  * **Example** (Capturing a runtime for fiber handles)
  *
- * ```ts
- * import { Context, Effect, FiberHandle } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Fiber, FiberHandle } from "effect"
  *
- * interface Users {
- *   readonly _: unique symbol
- * }
- * const Users = Context.Service<Users, {
- *   getAll: Effect.Effect<Array<unknown>>
- * }>("Users")
+ * class Users extends Context.Service<Users, {
+ *   readonly getAll: Effect.Effect<Array<unknown>>
+ * }>()("Users") {}
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *   const run = yield* FiberHandle.runtime(handle)<Users>()
  *
  *   // run an effect and set the fiber in the handle
- *   run(Effect.andThen(Users, (_) => _.getAll))
+ *   const fiberA = run(Effect.andThen(Users, (_) => _.getAll))
  *
  *   // this will interrupt the previous fiber
- *   run(Effect.andThen(Users, (_) => _.getAll))
+ *   const fiberB = run(Effect.andThen(Users, (_) => _.getAll))
+ *   yield* Fiber.await(fiberA)
+ *   return (yield* Fiber.join(fiberB)).length
  * }).pipe(
  *   Effect.scoped // The fiber will be interrupted when the scope is closed
  * )
+ *
+ * const actual = await Effect.runPromise(Effect.provideService(program, Users, {
+ *   getAll: Effect.succeed([])
+ * }))
+ * actual // => 0
  * ```
  *
  * @category combinators
@@ -878,18 +919,20 @@ export const runtime: <A, E>(
  *
  * **Example** (Capturing a runtime for promises)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *   const runPromise = yield* FiberHandle.runtimePromise(handle)<never>()
  *
  *   // Run an effect and get a promise
  *   const promise = runPromise(Effect.succeed("hello"))
- *   const result = yield* Effect.promise(() => promise)
- *   console.log(result) // "hello"
+ *   return yield* Effect.promise(() => promise)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => "hello"
  * ```
  *
  * @category combinators
@@ -948,16 +991,19 @@ export const runtimePromise = <A, E>(self: FiberHandle<A, E>): <R = never>() =>
  *
  * **Example** (Propagating fiber failures)
  *
- * ```ts
- * import { Effect, FiberHandle } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, FiberHandle } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *   yield* FiberHandle.set(handle, Effect.runFork(Effect.fail("error")))
  *
  *   // parent fiber will fail with "error"
  *   yield* FiberHandle.join(handle)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.exit(Effect.scoped(program)))
+ * actual // => Exit.fail("error")
  * ```
  *
  * @category combinators
@@ -971,20 +1017,22 @@ export const join = <A, E>(self: FiberHandle<A, E>): Effect.Effect<void, E> =>
  *
  * **Example** (Waiting for a fiber to complete)
  *
- * ```ts
- * import { Effect, FiberHandle } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FiberHandle, Option } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const handle = yield* FiberHandle.make()
  *
- *   // Start a long-running effect
- *   yield* FiberHandle.run(handle, Effect.sleep(1000))
+ *   yield* FiberHandle.run(handle, Effect.yieldNow)
  *
  *   // Wait for the fiber to complete
  *   yield* FiberHandle.awaitEmpty(handle)
  *
- *   console.log("Fiber completed")
+ *   return yield* FiberHandle.get(handle)
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.scoped(program))
+ * actual // => Option.none()
  * ```
  *
  * @category combinators