effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/Scope.ts

@@ -25,23 +25,21 @@ const CloseableTypeId = effect.ScopeCloseableTypeId
  *
  * **Example** (Managing scoped resources)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Scope } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const scope = yield* Scope.make("sequential")
  *
- *   // Scope has a strategy and state
- *   console.log(scope.strategy) // "sequential"
- *   console.log(scope.state._tag) // "Open"
- *
- *   // Close the scope
+ *   const initial = [scope.strategy, scope.state._tag]
  *   yield* Scope.close(scope, Exit.void)
- *   console.log(scope.state._tag) // "Closed"
+ *   return [initial, scope.state._tag]
  * })
+ *
+ * Effect.runSync(program) // => [["sequential", "Empty"], "Closed"]
  * ```
  *
- * @category models
+ * @category services
  * @since 2.0.0
  */
 export interface Scope {
@@ -55,18 +53,18 @@ export interface Scope {
  *
  * **Example** (Closing a scope)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
+ * const cleanups: Array<string> = []
  * const program = Effect.gen(function*() {
  *   const scope = yield* Scope.make()
- *
- *   // Add a finalizer
- *   yield* Scope.addFinalizer(scope, Console.log("Cleanup!"))
- *
- *   // Scope can be closed
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => cleanups.push("Cleanup!")))
  *   yield* Scope.close(scope, Exit.void)
  * })
+ *
+ * Effect.runSync(program)
+ * cleanups // => ["Cleanup!"]
  * ```
  *
  * @category models
@@ -83,25 +81,17 @@ export interface Closeable extends Scope {
  *
  * **Example** (Checking scope states)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Scope } from "effect"
  *
- * // Example of checking scope states
  * const program = Effect.gen(function*() {
  *   const scope = yield* Scope.make()
- *
- *   // When open, the scope accepts finalizers
- *   if (scope.state._tag === "Open") {
- *     console.log("Scope is open")
- *   }
- *
+ *   const before = scope.state._tag
  *   yield* Scope.close(scope, Exit.void)
- *
- *   // When closed, the scope no longer accepts finalizers
- *   if (scope.state._tag === "Closed") {
- *     console.log("Scope is closed")
- *   }
+ *   return [before, scope.state._tag]
  * })
+ *
+ * Effect.runSync(program) // => ["Empty", "Closed"]
  * ```
  *
  * @since 4.0.0
@@ -118,16 +108,12 @@ export declare namespace State {
    *
    * **Example** (Inspecting an empty scope state)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Scope } from "effect"
    *
    * const scope = Scope.makeUnsafe()
    *
-   * // When scope is open, you can check its state
-   * if (scope.state._tag === "Open") {
-   *   console.log("Scope is open and accepting finalizers")
-   *   console.log(scope.state.finalizers.size) // Number of registered finalizers
-   * }
+   * scope.state._tag // => "Empty"
    * ```
    *
    * @category models
@@ -142,16 +128,17 @@ export declare namespace State {
    *
    * **Example** (Inspecting an open scope state)
    *
-   * ```ts
-   * import { Scope } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, Scope } from "effect"
    *
    * const scope = Scope.makeUnsafe()
    *
-   * // When scope is open, you can check its state
-   * if (scope.state._tag === "Open") {
-   *   console.log("Scope is open and accepting finalizers")
-   *   console.log(scope.state.finalizers.size) // Number of registered finalizers
-   * }
+   * Effect.runSync(Scope.addFinalizer(scope, Effect.void))
+   * const state = scope.state
+   * if (state._tag !== "Open") throw new Error("unexpected state")
+   *
+   * state._tag // => "Open"
+   * state.finalizers.size // => 1
    * ```
    *
    * @category models
@@ -167,21 +154,20 @@ export declare namespace State {
    *
    * **Example** (Inspecting a closed scope state)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Scope } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const scope = yield* Scope.make()
    *
-   *   // Close the scope
    *   yield* Scope.close(scope, Exit.succeed("Done"))
-   *
-   *   // Check if scope is closed
    *   if (scope.state._tag === "Closed") {
-   *     console.log("Scope is closed")
-   *     console.log(scope.state.exit) // The exit value used to close the scope
+   *     return scope.state.exit
    *   }
+   *   return Exit.die("unexpected state")
    * })
+   *
+   * Effect.runSync(program) // => Exit.succeed("Done")
    * ```
    *
    * @category models
@@ -203,19 +189,17 @@ export declare namespace State {
  *
  * **Example** (Accessing the scope service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Scope } from "effect"
  *
+ * const cleanups: Array<string> = []
  * const program = Effect.gen(function*() {
- *   // Access the scope from the context
  *   const scope = yield* Scope.Scope
- *
- *   // Use the scope for resource management
- *   yield* Scope.addFinalizer(scope, Effect.log("Cleanup"))
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => cleanups.push("Cleanup")))
  * })
  *
- * // Provide a scope to the program
- * const scoped = Effect.scoped(program)
+ * Effect.runSync(Effect.scoped(program))
+ * cleanups // => ["Cleanup"]
  * ```
  *
  * @category services
@@ -228,21 +212,19 @@ export const Scope: Context.Service<Scope, Scope> = effect.scopeTag
  *
  * **Example** (Creating a scope)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
+ * const cleanups: Array<string> = []
  * const program = Effect.gen(function*() {
- *   // Create a scope with sequential cleanup
  *   const scope = yield* Scope.make("sequential")
- *
- *   // Add finalizers
- *   yield* Scope.addFinalizer(scope, Console.log("Cleanup 1"))
- *   yield* Scope.addFinalizer(scope, Console.log("Cleanup 2"))
- *
- *   // Close the scope (finalizers run in reverse order)
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => cleanups.push("Cleanup 1")))
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => cleanups.push("Cleanup 2")))
  *   yield* Scope.close(scope, Exit.void)
- *   // Output: "Cleanup 2", then "Cleanup 1"
  * })
+ *
+ * Effect.runSync(program)
+ * cleanups // => ["Cleanup 2", "Cleanup 1"]
  * ```
  *
  * @category constructors
@@ -262,17 +244,18 @@ export const make: (finalizerStrategy?: "sequential" | "parallel") => Effect<Clo
  *
  * **Example** (Creating a scope synchronously)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
- * // Create a scope immediately
  * const scope = Scope.makeUnsafe("sequential")
- *
- * // Use it in an Effect program
+ * const cleanups: Array<string> = []
  * const program = Effect.gen(function*() {
- *   yield* Scope.addFinalizer(scope, Console.log("Cleanup"))
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => cleanups.push("Cleanup")))
  *   yield* Scope.close(scope, Exit.void)
  * })
+ *
+ * Effect.runSync(program)
+ * cleanups // => ["Cleanup"]
  * ```
  *
  * @category constructors
@@ -294,21 +277,24 @@ export const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel") => Clos
  *
  * **Example** (Providing a scope)
  *
- * ```ts
- * import { Console, Effect, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
- * // An effect that requires a Scope
+ * const events: Array<string> = []
  * const program = Effect.gen(function*() {
  *   const scope = yield* Scope.Scope
- *   yield* Scope.addFinalizer(scope, Console.log("Cleanup"))
- *   yield* Console.log("Working...")
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("cleanup")))
+ *   events.push("working")
  * })
  *
- * // Provide a scope to the program
  * const withScope = Effect.gen(function*() {
  *   const scope = yield* Scope.make()
  *   yield* Scope.provide(scope)(program)
+ *   yield* Scope.close(scope, Exit.void)
  * })
+ *
+ * Effect.runSync(withScope)
+ * events // => ["working", "cleanup"]
  * ```
  *
  * @category combinators
@@ -329,21 +315,24 @@ export const provide: {
    *
    * **Example** (Providing a scope)
    *
-   * ```ts
-   * import { Console, Effect, Scope } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, Exit, Scope } from "effect"
    *
-   * // An effect that requires a Scope
+   * const events: Array<string> = []
    * const program = Effect.gen(function*() {
    *   const scope = yield* Scope.Scope
-   *   yield* Scope.addFinalizer(scope, Console.log("Cleanup"))
-   *   yield* Console.log("Working...")
+   *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("cleanup")))
+   *   events.push("working")
    * })
    *
-   * // Provide a scope to the program
    * const withScope = Effect.gen(function*() {
    *   const scope = yield* Scope.make()
    *   yield* Scope.provide(scope)(program)
+   *   yield* Scope.close(scope, Exit.void)
    * })
+   *
+   * Effect.runSync(withScope)
+   * events // => ["working", "cleanup"]
    * ```
    *
    * @category combinators
@@ -364,21 +353,24 @@ export const provide: {
    *
    * **Example** (Providing a scope)
    *
-   * ```ts
-   * import { Console, Effect, Scope } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, Exit, Scope } from "effect"
    *
-   * // An effect that requires a Scope
+   * const events: Array<string> = []
    * const program = Effect.gen(function*() {
    *   const scope = yield* Scope.Scope
-   *   yield* Scope.addFinalizer(scope, Console.log("Cleanup"))
-   *   yield* Console.log("Working...")
+   *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("cleanup")))
+   *   events.push("working")
    * })
    *
-   * // Provide a scope to the program
    * const withScope = Effect.gen(function*() {
    *   const scope = yield* Scope.make()
    *   yield* Scope.provide(scope)(program)
+   *   yield* Scope.close(scope, Exit.void)
    * })
+   *
+   * Effect.runSync(withScope)
+   * events // => ["working", "cleanup"]
    * ```
    *
    * @category combinators
@@ -403,29 +395,18 @@ export const provide: {
  *
  * **Example** (Adding an exit-aware finalizer)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
+ * const exits: Array<Exit.Exit<unknown, unknown>> = []
  * const withResource = Effect.gen(function*() {
  *   const scope = yield* Scope.make()
- *
- *   // Add a finalizer for cleanup
- *   yield* Scope.addFinalizerExit(
- *     scope,
- *     (exit) =>
- *       Console.log(
- *         `Cleaning up resource. Exit: ${
- *           Exit.isSuccess(exit) ? "Success" : "Failure"
- *         }`
- *       )
- *   )
- *
- *   // Use the resource
- *   yield* Console.log("Using resource")
- *
- *   // Close the scope
+ *   yield* Scope.addFinalizerExit(scope, (exit) => Effect.sync(() => exits.push(exit)))
  *   yield* Scope.close(scope, Exit.void)
  * })
+ *
+ * Effect.runSync(withResource)
+ * exits // => [Exit.void]
  * ```
  *
  * @category combinators
@@ -445,23 +426,21 @@ export const addFinalizerExit: (scope: Scope, finalizer: (exit: Exit<any, any>)
  *
  * **Example** (Adding finalizers)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
+ * const events: Array<string> = []
  * const program = Effect.gen(function*() {
  *   const scope = yield* Scope.make()
- *
- *   // Add simple finalizers
- *   yield* Scope.addFinalizer(scope, Console.log("Cleanup task 1"))
- *   yield* Scope.addFinalizer(scope, Console.log("Cleanup task 2"))
- *   yield* Scope.addFinalizer(scope, Effect.log("Cleanup task 3"))
- *
- *   // Do some work
- *   yield* Console.log("Doing work...")
- *
- *   // Close the scope
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("cleanup 1")))
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("cleanup 2")))
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("cleanup 3")))
+ *   events.push("work")
  *   yield* Scope.close(scope, Exit.void)
  * })
+ *
+ * Effect.runSync(program)
+ * events // => ["work", "cleanup 3", "cleanup 2", "cleanup 1"]
  * ```
  *
  * @category combinators
@@ -480,25 +459,21 @@ export const addFinalizer: (scope: Scope, finalizer: Effect<unknown>) => Effect<
  *
  * **Example** (Creating a child scope)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
+ * const cleanups: Array<string> = []
  * const nestedScopes = Effect.gen(function*() {
  *   const parentScope = yield* Scope.make("sequential")
- *
- *   // Add finalizer to parent
- *   yield* Scope.addFinalizer(parentScope, Console.log("Parent cleanup"))
- *
- *   // Create child scope
+ *   yield* Scope.addFinalizer(parentScope, Effect.sync(() => cleanups.push("parent")))
  *   const childScope = yield* Scope.fork(parentScope, "parallel")
- *
- *   // Add finalizer to child
- *   yield* Scope.addFinalizer(childScope, Console.log("Child cleanup"))
- *
- *   // Close child first, then parent
+ *   yield* Scope.addFinalizer(childScope, Effect.sync(() => cleanups.push("child")))
  *   yield* Scope.close(childScope, Exit.void)
  *   yield* Scope.close(parentScope, Exit.void)
  * })
+ *
+ * Effect.runSync(nestedScopes)
+ * cleanups // => ["child", "parent"]
  * ```
  *
  * @category combinators
@@ -525,21 +500,21 @@ export const fork: (
  *
  * **Example** (Creating a child scope synchronously)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
+ * const cleanups: Array<string> = []
  * const program = Effect.gen(function*() {
  *   const parentScope = Scope.makeUnsafe("sequential")
  *   const childScope = Scope.forkUnsafe(parentScope, "parallel")
- *
- *   // Add finalizers to both scopes
- *   yield* Scope.addFinalizer(parentScope, Console.log("Parent cleanup"))
- *   yield* Scope.addFinalizer(childScope, Console.log("Child cleanup"))
- *
- *   // Close child first, then parent
+ *   yield* Scope.addFinalizer(parentScope, Effect.sync(() => cleanups.push("parent")))
+ *   yield* Scope.addFinalizer(childScope, Effect.sync(() => cleanups.push("child")))
  *   yield* Scope.close(childScope, Exit.void)
  *   yield* Scope.close(parentScope, Exit.void)
  * })
+ *
+ * Effect.runSync(program)
+ * cleanups // => ["child", "parent"]
  * ```
  *
  * @category combinators
@@ -562,24 +537,21 @@ export const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential" | "para
  *
  * **Example** (Running scope finalizers)
  *
- * ```ts
- * import { Console, Effect, Exit, Scope } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Scope } from "effect"
  *
+ * const events: Array<string> = []
  * const resourceManagement = Effect.gen(function*() {
  *   const scope = yield* Scope.make("sequential")
- *
- *   // Add multiple finalizers
- *   yield* Scope.addFinalizer(scope, Console.log("Close database connection"))
- *   yield* Scope.addFinalizer(scope, Console.log("Close file handle"))
- *   yield* Scope.addFinalizer(scope, Console.log("Release memory"))
- *
- *   // Do some work...
- *   yield* Console.log("Performing operations...")
- *
- *   // Close scope - finalizers run in reverse order of registration
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("database")))
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("file")))
+ *   yield* Scope.addFinalizer(scope, Effect.sync(() => events.push("memory")))
+ *   events.push("work")
  *   yield* Scope.close(scope, Exit.succeed("Success!"))
- *   // Output: "Release memory", "Close file handle", "Close database connection"
  * })
+ *
+ * Effect.runSync(resourceManagement)
+ * events // => ["work", "memory", "file", "database"]
  * ```
  *
  * @category combinators

package/src/ScopedRef.ts

@@ -165,7 +165,7 @@ export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never
  * changed to the new value, with old resources released, or until the attempt
  * to acquire a new value fails.
  *
- * @category setters
+ * @category mutations
  * @since 2.0.0
  */
 export const set: {
@@ -184,7 +184,7 @@ export const set: {
    * changed to the new value, with old resources released, or until the attempt
    * to acquire a new value fails.
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A, R, E>(acquire: Effect.Effect<A, E, R>): (self: ScopedRef<A>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>>
@@ -203,7 +203,7 @@ export const set: {
    * changed to the new value, with old resources released, or until the attempt
    * to acquire a new value fails.
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A, R, E>(self: ScopedRef<A>, acquire: Effect.Effect<A, E, R>): Effect.Effect<void, E, Exclude<R, Scope.Scope>>
@@ -214,12 +214,12 @@ export const set: {
       self: ScopedRef<A>,
       acquire: Effect.Effect<A, E, R>
     ) {
-      yield* Scope.close(self.backing.backing.ref.current[0], Exit.void)
       const scope = Scope.makeUnsafe()
       const value = yield* acquire.pipe(
         Scope.provide(scope),
         Effect.tapCause((cause) => Scope.close(scope, Exit.failCause(cause)))
       )
+      yield* Scope.close(self.backing.backing.ref.current[0], Exit.void)
       self.backing.backing.ref.current = [scope, value]
     },
     Effect.uninterruptible,