effect 4.0.0-beta.102 → 4.0.0-beta.104

package/dist/Layer.js

@@ -21,7 +21,7 @@ const memoMapReuse = (entry, scope) => {
  *
  * **Example** (Checking whether a value is a layer)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -33,11 +33,11 @@ const memoMapReuse = (entry, scope) => {
  * })
  * const notALayer = { someProperty: "value" }
  *
- * console.log(Layer.isLayer(dbLayer)) // true
- * console.log(Layer.isLayer(notALayer)) // false
+ * Layer.isLayer(dbLayer) // => true
+ * Layer.isLayer(notALayer) // => false
  * ```
  *
- * @category getters
+ * @category guards
  * @since 2.0.0
  */
 export const isLayer = u => hasProperty(u, TypeId);
@@ -67,7 +67,7 @@ const fromBuildUnsafe = build => {
  *
  * **Example** (Constructing a layer from a build function)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -81,6 +81,9 @@ const fromBuildUnsafe = build => {
  *     })
  *   )
  * )
+ *
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, databaseLayer)) // => "result"
  * ```
  *
  * @category constructors
@@ -101,7 +104,7 @@ export const fromBuild = build => fromBuildUnsafe((memoMap, scope) => {
  *
  * **Example** (Memoizing layer construction)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -115,6 +118,9 @@ export const fromBuild = build => fromBuildUnsafe((memoMap, scope) => {
  *     })
  *   )
  * )
+ *
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, databaseLayer)) // => "result"
  * ```
  *
  * @category constructors
@@ -162,11 +168,13 @@ class MemoMapImpl {
     return this.parent?.get(layer, scope);
   }
   getOrElseMemoize(layer, scope, build) {
-    const existing = this.get(layer, scope);
-    if (existing) {
-      return existing;
-    }
-    return memoMapBuild(this, layer, scope, build);
+    return internalEffect.suspend(() => {
+      const existing = this.get(layer, scope);
+      if (existing) {
+        return existing;
+      }
+      return memoMapBuild(this, layer, scope, build);
+    });
   }
 }
 /**
@@ -174,7 +182,7 @@ class MemoMapImpl {
  *
  * **Example** (Creating a memo map unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -193,9 +201,12 @@ class MemoMapImpl {
  *
  *   return Context.get(context, Database)
  * })
+ *
+ * const database = Effect.runSync(Effect.scoped(program))
+ * Effect.runSync(database.query("SELECT 1")) // => "result"
  * ```
  *
- * @category memo map
+ * @category constructors
  * @since 4.0.0
  */
 export const makeMemoMapUnsafe = () => new MemoMapImpl();
@@ -213,7 +224,7 @@ export const makeMemoMapUnsafe = () => new MemoMapImpl();
  * @see {@link forkMemoMap} for allocating the child memo map inside `Effect`
  * @see {@link makeMemoMapUnsafe} for creating a root memo map without a parent
  *
- * @category memo map
+ * @category constructors
  * @since 4.0.0
  */
 export const forkMemoMapUnsafe = parent => new MemoMapImpl(parent);
@@ -222,7 +233,7 @@ export const forkMemoMapUnsafe = parent => new MemoMapImpl(parent);
  *
  * **Example** (Creating a memo map in an effect)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -241,9 +252,12 @@ export const forkMemoMapUnsafe = parent => new MemoMapImpl(parent);
  *
  *   return Context.get(context, Database)
  * })
+ *
+ * const database = Effect.runSync(Effect.scoped(program))
+ * Effect.runSync(database.query("SELECT 1")) // => "result"
  * ```
  *
- * @category memo map
+ * @category constructors
  * @since 2.0.0
  */
 export const makeMemoMap = /*#__PURE__*/internalEffect.sync(makeMemoMapUnsafe);
@@ -261,7 +275,7 @@ export const makeMemoMap = /*#__PURE__*/internalEffect.sync(makeMemoMapUnsafe);
  * @see {@link forkMemoMapUnsafe} for the synchronous constructor variant
  * @see {@link buildWithMemoMap} for building layers with an explicit memo map
  *
- * @category memo map
+ * @category constructors
  * @since 4.0.0
  */
 export const forkMemoMap = parent => internalEffect.sync(() => forkMemoMapUnsafe(parent));
@@ -280,7 +294,7 @@ export const forkMemoMap = parent => internalEffect.sync(() => forkMemoMapUnsafe
  *
  * @see {@link MemoMap} the memoization map type wrapped by this service
  *
- * @category models
+ * @category services
  * @since 3.13.0
  */
 export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer/CurrentMemoMap") {
@@ -295,7 +309,7 @@ export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer
  *
  * **Example** (Building layers with an explicit memo map)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -306,6 +320,8 @@ export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer
  *   readonly log: (msg: string) => Effect.Effect<void>
  * }>()("Logger") {}
  *
+ * const logs: Array<string> = []
+ *
  * // Build layers with explicit memoization control
  * const program = Effect.gen(function*() {
  *   const memoMap = yield* Layer.makeMemoMap
@@ -319,7 +335,7 @@ export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer
  *
  *   // Build logger layer with same memoization (reuses memo if same layer)
  *   const loggerLayer = Layer.succeed(Logger, {
- *     log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
+ *     log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(msg)))
  *   })
  *   const loggerContext = yield* Layer.buildWithMemoMap(
  *     loggerLayer,
@@ -332,9 +348,13 @@ export class CurrentMemoMap extends /*#__PURE__*/Context.Service()("effect/Layer
  *     logger: Context.get(loggerContext, Logger)
  *   }
  * })
+ *
+ * const services = Effect.runSync(Effect.scoped(program))
+ * Effect.runSync(services.logger.log("ready"))
+ * logs // => ["ready"]
  * ```
  *
- * @category memo map
+ * @category destructors
  * @since 2.0.0
  */
 export const buildWithMemoMap = /*#__PURE__*/dual(3, (self, memoMap, scope) => internalEffect.provideService(internalEffect.map(self.build(memoMap, scope), Context.add(CurrentMemoMap, memoMap)), CurrentMemoMap, memoMap));
@@ -343,7 +363,7 @@ export const buildWithMemoMap = /*#__PURE__*/dual(3, (self, memoMap, scope) => i
  *
  * **Example** (Building a layer into a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -364,6 +384,8 @@ export const buildWithMemoMap = /*#__PURE__*/dual(3, (self, memoMap, scope) => i
  *
  *   return yield* database.query("SELECT * FROM users")
  * })
+ *
+ * Effect.runSync(Effect.scoped(program)) // => "result"
  * ```
  *
  * @category destructors
@@ -385,22 +407,24 @@ export const build = self => core.withFiber(fiber => buildWithMemoMap(self, Curr
  *
  * **Example** (Building a layer with an explicit scope)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, Scope } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
+ * const logs: Array<string> = []
+ *
  * // Build a layer with explicit scope control
  * const program = Effect.gen(function*() {
  *   const scope = yield* Effect.scope
  *
  *   const dbLayer = Layer.effect(Database, Effect.gen(function*() {
- *     console.log("Initializing database...")
+ *     logs.push("Initializing database...")
  *     yield* Scope.addFinalizer(
  *       scope,
- *       Effect.sync(() => console.log("Database closed"))
+ *       Effect.sync(() => logs.push("Database closed"))
  *     )
  *     return { query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result: ${sql}`)) }
  *   }))
@@ -412,6 +436,9 @@ export const build = self => core.withFiber(fiber => buildWithMemoMap(self, Curr
  *   return yield* database.query("SELECT * FROM users")
  *   // Database will be closed when scope is closed
  * })
+ *
+ * Effect.runSync(Effect.scoped(program)) // => "Result: SELECT * FROM users"
+ * logs // => ["Initializing database...", "Database closed"]
  * ```
  *
  * @category destructors
@@ -429,7 +456,7 @@ export const buildWithScope = /*#__PURE__*/dual(2, (self, scope) => core.withFib
  *
  * **Example** (Creating a layer from a service implementation)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -439,6 +466,8 @@ export const buildWithScope = /*#__PURE__*/dual(2, (self, scope) => core.withFib
  * const DatabaseLive = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Query result: ${sql}`))
  * })
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, DatabaseLive)) // => "Query result: SELECT 1"
  * ```
  *
  * @see {@link sync} for constructing layers from lazy values
@@ -468,7 +497,7 @@ export const succeed = function () {
  *
  * **Example** (Providing multiple services from a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -479,15 +508,19 @@ export const succeed = function () {
  *   readonly log: (msg: string) => Effect.Effect<void>
  * }>()("Logger") {}
  *
+ * const logs: Array<string> = []
  * const context = Context.make(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  * }).pipe(
  *   Context.add(Logger, {
- *     log: (msg: string) => Effect.sync(() => console.log(msg))
+ *     log: (msg: string) => Effect.sync(() => logs.push(msg))
  *   })
  * )
  *
  * const layer = Layer.succeedContext(context)
+ * const program = Logger.use((logger) => logger.log("ready"))
+ * Effect.runSync(Effect.provide(program, layer))
+ * logs // => ["ready"]
  * ```
  *
  * @see {@link succeed} for providing a single service from a value
@@ -506,14 +539,12 @@ export const succeedContext = context => fromBuildUnsafe(constant(internalEffect
  *
  * **Example** (Disabling optional lifecycle work)
  *
- * ```ts
- * import { Console, Layer } from "effect"
- *
- * declare const flag: boolean
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Layer, Option } from "effect"
  *
- * const StartupLogLive = flag
- *   ? Layer.effectDiscard(Console.log("application starting"))
- *   : Layer.empty
+ * const Service = Context.Service<string>("Service")
+ * const context = Effect.runSync(Effect.scoped(Layer.build(Layer.empty)))
+ * Context.getOption(context, Service) // => Option.none()
  * ```
  *
  * @see {@link effectDiscard} for running an effect while providing no services
@@ -537,7 +568,7 @@ export const empty = /*#__PURE__*/succeedContext(/*#__PURE__*/Context.empty());
  *
  * **Example** (Lazily providing a service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -547,6 +578,8 @@ export const empty = /*#__PURE__*/succeedContext(/*#__PURE__*/Context.empty());
  * const layer = Layer.sync(Database, () => ({
  *   query: (sql: string) => Effect.succeed(`Query: ${sql}`)
  * }))
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, layer)) // => "Query: SELECT 1"
  * ```
  *
  * @see {@link succeed} for constructing layers from static values
@@ -575,7 +608,7 @@ export const sync = function () {
  *
  * **Example** (Lazily providing a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -587,6 +620,8 @@ export const sync = function () {
  *     query: (sql: string) => Effect.succeed(`Query: ${sql}`)
  *   })
  * )
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, layer)) // => "Query: SELECT 1"
  * ```
  *
  * @see {@link sync} for lazily providing a single service
@@ -612,7 +647,7 @@ export const syncContext = evaluate => fromBuildMemo(constant(internalEffect.syn
  *
  * **Example** (Creating a layer from an effect)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -624,6 +659,8 @@ export const syncContext = evaluate => fromBuildMemo(constant(internalEffect.syn
  *     query: (sql: string) => Effect.succeed(`Query: ${sql}`)
  *   }))
  * )
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, layer)) // => "Query: SELECT 1"
  * ```
  *
  * @see {@link effectContext} for effectfully providing multiple services
@@ -655,7 +692,7 @@ const effectImpl = (service, effect) => effectContext(internalEffect.map(effect,
  *
  * **Example** (Creating a layer from an effectful context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<
@@ -668,6 +705,8 @@ const effectImpl = (service, effect) => effectContext(internalEffect.map(effect,
  *     query: (sql: string) => Effect.succeed(`Query: ${sql}`)
  *   }))
  * )
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, layer)) // => "Query: SELECT 1"
  * ```
  *
  * @see {@link effect} for effectfully providing a single service
@@ -687,14 +726,17 @@ export const effectContext = effect => fromBuildMemo((_, scope) => Scope.provide
  *
  * **Example** (Running an effect during layer construction)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Layer } from "effect"
  *
+ * const logs: Array<string> = []
  * const initLayer = Layer.effectDiscard(
  *   Effect.sync(() => {
- *     console.log("Initializing application...")
+ *     logs.push("Initializing application...")
  *   })
  * )
+ * Effect.runSync(Effect.scoped(Layer.build(initLayer)))
+ * logs // => ["Initializing application..."]
  * ```
  *
  * @see {@link empty} for a no-op layer that performs no construction work
@@ -713,8 +755,8 @@ export const effectDiscard = effect => effectContext(internalEffect.as(effect, C
  *
  * **Example** (Choosing a layer lazily)
  *
- * ```ts
- * import { Context, Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Layer } from "effect"
  *
  * class Config extends Context.Service<Config, string>()("Config") {}
  *
@@ -725,6 +767,7 @@ export const effectDiscard = effect => effectContext(internalEffect.as(effect, C
  *     ? Layer.succeed(Config, "https://api.example.com")
  *     : Layer.succeed(Config, "http://localhost:3000")
  * )
+ * Effect.runSync(Effect.provide(Config, layer)) // => "https://api.example.com"
  * ```
  *
  * @category constructors
@@ -746,7 +789,7 @@ export const suspend = evaluate => fromBuildMemo((memoMap, scope) => internalEff
  *
  * **Example** (Unwrapping an effectful layer)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -758,6 +801,8 @@ export const suspend = evaluate => fromBuildMemo((memoMap, scope) => internalEff
  * )
  *
  * const unwrappedLayer = Layer.unwrap(layerEffect)
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, unwrappedLayer)) // => "result"
  * ```
  *
  * @category converting
@@ -791,7 +836,7 @@ const mergeAllEffect = (layers, memoMap, scope) => {
  *
  * **Example** (Merging independent layers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -805,11 +850,15 @@ const mergeAllEffect = (layers, memoMap, scope) => {
  * const dbLayer = Layer.succeed(Database, {
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  * })
+ * const logs: Array<string> = []
  * const loggerLayer = Layer.succeed(Logger, {
- *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
+ *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(msg)))
  * })
  *
  * const mergedLayer = Layer.mergeAll(dbLayer, loggerLayer)
+ * const program = Logger.use((logger) => logger.log("ready"))
+ * Effect.runSync(Effect.provide(program, mergedLayer))
+ * logs // => ["ready"]
  * ```
  *
  * @see {@link merge} for merging one layer with another layer or array
@@ -835,7 +884,7 @@ export const mergeAll = (...layers) => fromBuild((memoMap, scope) => mergeAllEff
  *
  * **Example** (Merging two layers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -850,10 +899,12 @@ export const mergeAll = (...layers) => fromBuild((memoMap, scope) => mergeAllEff
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed("result"))
  * })
  * const loggerLayer = Layer.succeed(Logger, {
- *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
+ *   log: Effect.fn("Logger.log")((_msg: string) => Effect.void)
  * })
  *
  * const mergedLayer = Layer.merge(dbLayer, loggerLayer)
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, mergedLayer)) // => "result"
  * ```
  *
  * @see {@link mergeAll} for merging several layers at once
@@ -878,7 +929,7 @@ const provideWith = (self, that, f) => fromBuild((memoMap, scope) => internalEff
  *
  * **Example** (Providing layer dependencies)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -901,8 +952,9 @@ const provideWith = (self, that, f) => fromBuild((memoMap, scope) => internalEff
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
  * })
  *
+ * const logs: Array<string> = []
  * const loggerLayer = Layer.succeed(Logger, {
- *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
+ *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(`[LOG] ${msg}`)))
  * })
  *
  * // UserService depends on Database and Logger
@@ -933,6 +985,8 @@ const provideWith = (self, that, f) => fromBuild((memoMap, scope) => internalEff
  * }).pipe(
  *   Effect.provide(userServiceWithDependencies)
  * )
+ * Effect.runSync(program) // => { id: "123", name: "DB: SELECT * FROM users WHERE id = 123" }
+ * logs // => ["[LOG] Looking up user 123"]
  * ```
  *
  * @see {@link provideMerge} for retaining the dependency services
@@ -956,7 +1010,7 @@ export const provide = /*#__PURE__*/dual(2, (self, that) => provideWith(self, th
  *
  * **Example** (Providing dependencies while retaining services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -979,8 +1033,9 @@ export const provide = /*#__PURE__*/dual(2, (self, that) => provideWith(self, th
  *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
  * })
  *
+ * const logs: Array<string> = []
  * const loggerLayer = Layer.succeed(Logger, {
- *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(`[LOG] ${msg}`)))
+ *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(`[LOG] ${msg}`)))
  * })
  *
  * // UserService depends on Database and Logger
@@ -1017,6 +1072,8 @@ export const provide = /*#__PURE__*/dual(2, (self, that) => provideWith(self, th
  * }).pipe(
  *   Effect.provide(allServicesLayer)
  * )
+ * Effect.runSync(program) // => { id: "123", name: "DB: SELECT * FROM users WHERE id = 123" }
+ * logs // => ["[LOG] Looking up user 123", "[LOG] Found user: DB: SELECT * FROM users WHERE id = 123"]
  * ```
  *
  * @see {@link provide} for keeping dependency services private
@@ -1030,7 +1087,7 @@ export const provideMerge = /*#__PURE__*/dual(2, (self, that) => provideWith(sel
  *
  * **Example** (Creating services from layer output)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Config extends Context.Service<Config, {
@@ -1046,6 +1103,8 @@ export const provideMerge = /*#__PURE__*/dual(2, (self, that) => provideWith(sel
  *   readonly log: (msg: string) => Effect.Effect<void>
  * }>()("Logger") {}
  *
+ * const logs: Array<string> = []
+ *
  * // Base config layer
  * const configLayer = Layer.succeed(Config, {
  *   dbUrl: "postgres://localhost:5432/mydb",
@@ -1069,8 +1128,8 @@ export const provideMerge = /*#__PURE__*/dual(2, (self, that) => provideWith(sel
  *     const loggerLayer = Layer.succeed(Logger, {
  *       log: Effect.fn("Logger.log")((msg: string) =>
  *         config.logLevel === "debug"
- *           ? Effect.sync(() => console.log(`[DEBUG] ${msg}`))
- *           : Effect.sync(() => console.log(msg))
+ *           ? Effect.sync(() => logs.push(`[DEBUG] ${msg}`))
+ *           : Effect.sync(() => logs.push(msg))
  *       )
  *     })
  *
@@ -1091,6 +1150,8 @@ export const provideMerge = /*#__PURE__*/dual(2, (self, that) => provideWith(sel
  * }).pipe(
  *   Effect.provide(dynamicServiceLayer)
  * )
+ * Effect.runSync(program) // => "Querying postgres://localhost:5432/mydb: SELECT * FROM users"
+ * logs // => ["[DEBUG] Starting database query"]
  * ```
  *
  * @category sequencing
@@ -1172,8 +1233,8 @@ export const tapCause = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, sc
  *
  * **Example** (Converting layer failures to defects)
  *
- * ```ts
- * import { Context, Data, Effect, Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Data, Effect, Exit, Layer } from "effect"
  *
  * class DatabaseError extends Data.TaggedError("DatabaseError")<{
  *   message: string
@@ -1184,10 +1245,11 @@ export const tapCause = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, sc
  * }>()("Database") {}
  *
  * // Layer that can fail during construction
- * const flakyDatabaseLayer = Layer.effect(Database, Effect.gen(function*() {
- *   console.log("connecting")
- *   return yield* new DatabaseError({ message: "Connection failed" })
- * }))
+ * const error = new DatabaseError({ message: "Connection failed" })
+ * const flakyDatabaseLayer = Layer.effect(
+ *   Database,
+ *   Effect.fail(error)
+ * )
  *
  * // Convert failures to fiber death - removes error from type
  * const reliableDatabaseLayer = flakyDatabaseLayer.pipe(Layer.orDie)
@@ -1200,8 +1262,7 @@ export const tapCause = /*#__PURE__*/dual(2, (self, f) => fromBuild((memoMap, sc
  *   Effect.provide(reliableDatabaseLayer)
  * )
  *
- * // Running the program prints "connecting", then the DatabaseError is
- * // converted into a fiber defect instead of remaining a typed error.
+ * Effect.runSync(Effect.exit(program)) // => Exit.die(error)
  * ```
  *
  * @category error handling
@@ -1234,7 +1295,7 @@ catch_ as catch };
  *
  * **Example** (Recovering from tagged layer errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Data, Effect, Layer } from "effect"
  *
  * class ConfigError extends Data.TaggedError("ConfigError") {}
@@ -1250,6 +1311,8 @@ catch_ as catch };
  * const recovered = configLayer.pipe(
  *   Layer.catchTag("ConfigError", () => fallbackLayer)
  * )
+ * const program = Config.useSync((config) => config.apiUrl)
+ * Effect.runSync(Effect.provide(program, recovered)) // => "http://localhost"
  * ```
  *
  * @see {@link catchCause} for recovering with access to the full cause
@@ -1275,7 +1338,7 @@ export const catchTag = /*#__PURE__*/dual(3, (self, k, f) => fromBuildUnsafe((me
  *
  * **Example** (Recovering from layer failures by cause)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Data, Effect, Layer } from "effect"
  *
  * class DatabaseError extends Data.TaggedError("DatabaseError")<{
@@ -1300,14 +1363,12 @@ export const catchTag = /*#__PURE__*/dual(3, (self, k, f) => fromBuildUnsafe((me
  *
  * const program = Effect.gen(function*() {
  *   const database = yield* Database
- *   const result = yield* database.query("SELECT * FROM users")
- *   console.log(result)
+ *   return yield* database.query("SELECT * FROM users")
  * }).pipe(
  *   Effect.provide(databaseWithFallback)
  * )
  *
- * Effect.runPromise(program)
- * // Memory: SELECT * FROM users
+ * await Effect.runPromise(program) // => "Memory: SELECT * FROM users"
  * ```
  *
  * @see {@link catchTag} for recovering from specific tagged errors
@@ -1350,7 +1411,7 @@ export const updateService = /*#__PURE__*/dual(3, (layer, service, f) => provide
  *
  * **Example** (Creating non-shared layer instances)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, Ref } from "effect"
  *
  * class Counter extends Context.Service<Counter, {
@@ -1375,10 +1436,10 @@ export const updateService = /*#__PURE__*/dual(3, (layer, service, f) => provide
  *   return { counterId: counter.id }
  * }))
  *
- * const showIds = Effect.gen(function*() {
+ * const compareIds = Effect.gen(function*() {
  *   const left = yield* Left
  *   const right = yield* Right
- *   console.log(`same Counter: ${left.counterId === right.counterId}`)
+ *   return left.counterId === right.counterId
  * })
  *
  * const program = Effect.gen(function*() {
@@ -1386,7 +1447,6 @@ export const updateService = /*#__PURE__*/dual(3, (layer, service, f) => provide
  *
  *   const counterLayer = Layer.effect(Counter, Effect.gen(function*() {
  *     const id = yield* Ref.updateAndGet(nextId, (n) => n + 1)
- *     console.log("constructed Counter")
  *     return { id }
  *   }))
  *
@@ -1395,7 +1455,7 @@ export const updateService = /*#__PURE__*/dual(3, (layer, service, f) => provide
  *     Layer.provide(rightLayer, counterLayer)
  *   )
  *
- *   yield* Effect.provide(showIds, shared)
+ *   const sharedResult = yield* Effect.provide(compareIds, shared)
  *
  *   const freshCounterLayer = Layer.fresh(counterLayer)
  *   const fresh = Layer.merge(
@@ -1403,15 +1463,12 @@ export const updateService = /*#__PURE__*/dual(3, (layer, service, f) => provide
  *     Layer.provide(rightLayer, freshCounterLayer)
  *   )
  *
- *   yield* Effect.provide(showIds, fresh)
+ *   const freshResult = yield* Effect.provide(compareIds, fresh)
+ *
+ *   return { shared: sharedResult, fresh: freshResult }
  * })
  *
- * Effect.runPromise(program)
- * // constructed Counter
- * // same Counter: true
- * // constructed Counter
- * // constructed Counter
- * // same Counter: false
+ * await Effect.runPromise(program) // => { shared: true, fresh: false }
  * ```
  *
  * @category layers
@@ -1433,50 +1490,30 @@ export const fresh = self => fromBuildUnsafe((_, scope) => self.build(makeMemoMa
  *
  * **Example** (Launching an application layer)
  *
- * ```ts
- * import { Console, Context, Effect, Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Deferred, Effect, Fiber, Layer, Ref } from "effect"
  *
  * class HttpServer extends Context.Service<HttpServer, {
- *   readonly start: () => Effect.Effect<string>
- *   readonly stop: () => Effect.Effect<string>
+ *   readonly port: number
  * }>()("HttpServer") {}
  *
- * class Logger extends Context.Service<Logger, {
- *   readonly log: (msg: string) => Effect.Effect<void>
- * }>()("Logger") {}
- *
- * // Server layer that starts an HTTP server
- * const serverLayer = Layer.effect(HttpServer, Effect.gen(function*() {
- *   yield* Console.log("Starting HTTP server...")
+ * const program = Effect.gen(function*() {
+ *   const events = yield* Ref.make<Array<string>>([])
+ *   const started = yield* Deferred.make<void>()
  *
- *   return {
- *     start: Effect.fn("HttpServer.start")(function*() {
- *         yield* Console.log("Server listening on port 3000")
- *         return "Server started"
- *       }),
- *     stop: Effect.fn("HttpServer.stop")(function*() {
- *         yield* Console.log("Server stopped gracefully")
- *         return "Server stopped"
- *       })
- *   }
- * }))
+ *   const serverLayer = Layer.effect(HttpServer, Effect.gen(function*() {
+ *     yield* Ref.update(events, (events) => [...events, "Starting HTTP server..."])
+ *     yield* Deferred.succeed(started, undefined)
+ *     return { port: 3000 }
+ *   }))
  *
- * const loggerLayer = Layer.succeed(Logger, {
- *   log: Effect.fn("Logger.log")((msg: string) => Console.log(`[LOG] ${msg}`))
+ *   const fiber = yield* Effect.forkChild(Layer.launch(serverLayer))
+ *   yield* Deferred.await(started)
+ *   yield* Fiber.interrupt(fiber)
+ *   return yield* Ref.get(events)
  * })
  *
- * // Application layer combining all services
- * const appLayer = Layer.mergeAll(serverLayer, loggerLayer)
- *
- * // Launch the application - runs until interrupted
- * const application = appLayer.pipe(
- *   Layer.launch,
- *   Effect.tapError((error) => Console.log(`Application failed: ${error}`)),
- *   Effect.tap(() => Console.log("Application completed"))
- * )
- *
- * // This will run forever until externally interrupted
- * // Effect.runFork(application)
+ * await Effect.runPromise(program) // => ["Starting HTTP server..."]
  * ```
  *
  * @category converting
@@ -1498,7 +1535,7 @@ export const launch = self => internalEffect.scoped(internalEffect.andThen(build
  *
  * **Example** (Mocking services for tests)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class UserService extends Context.Service<UserService, {
@@ -1526,13 +1563,15 @@ export const launch = self => internalEffect.scoped(internalEffect.andThen(build
  *
  *   // This works - we provided an implementation
  *   const user = yield* userService.getUser("123")
- *   console.log(user.name) // "Test User"
  *
  *   // This would throw - we didn't implement deleteUser
  *   // yield* userService.deleteUser("123") // UnimplementedError
+ *
+ *   return user.name
  * }).pipe(
  *   Effect.provide(testUserLayer)
  * )
+ * Effect.runSync(testProgram) // => "Test User"
  * ```
  *
  * @category testing
@@ -1596,22 +1635,17 @@ const ChannelTypeId = "~effect/Channel";
  *
  * **Example** (Constraining layer success types)
  *
- * ```ts
- * import { Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Layer } from "effect"
  *
- * declare const FortyTwoLayer: Layer.Layer<42, never, never>
- * declare const StringLayer: Layer.Layer<string, never, never>
+ * const NumberService = Context.Service<number>("Number")
+ * const numberLayer = Layer.succeed(NumberService, 42)
  *
  * // Define a constraint that the success type must be a number
  * const satisfiesNumber = Layer.satisfiesSuccessType<number>()
  *
  * // This works - Layer<42, never, never> extends Layer<number, never, never>
- * const validLayer = satisfiesNumber(FortyTwoLayer)
- *
- * // This would cause a TypeScript compilation error:
- * // const invalidLayer = satisfiesNumber(StringLayer)
- * //                                     ^^^^^^^^^^^
- * // Type 'string' is not assignable to type 'number'
+ * const validLayer = satisfiesNumber(numberLayer)
  * ```
  *
  * @category utility types
@@ -1628,23 +1662,16 @@ export const satisfiesSuccessType = () => layer => layer;
  *
  * **Example** (Constraining layer error types)
  *
- * ```ts
- * import { Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
  *
- * declare const ErrorLayer: Layer.Layer<never, Error, never>
- * declare const TypeErrorLayer: Layer.Layer<never, TypeError, never>
- * declare const StringLayer: Layer.Layer<never, string, never>
+ * const typeErrorLayer = Layer.effectDiscard(Effect.fail(new TypeError("boom")))
  *
  * // Define a constraint that the error type must be an Error
  * const satisfiesError = Layer.satisfiesErrorType<Error>()
  *
  * // This works - Layer<never, TypeError, never> extends Layer<never, Error, never>
- * const validLayer = satisfiesError(TypeErrorLayer)
- *
- * // This would cause a TypeScript compilation error:
- * // const invalidLayer = satisfiesError(StringLayer)
- * //                                     ^^^^^^^^^^^
- * // Type 'string' is not assignable to type 'Error'
+ * const validLayer = satisfiesError(typeErrorLayer)
  * ```
  *
  * @category utility types
@@ -1661,22 +1688,17 @@ export const satisfiesErrorType = () => layer => layer;
  *
  * **Example** (Constraining layer service requirements)
  *
- * ```ts
- * import { Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Layer } from "effect"
  *
- * declare const FortyTwoLayer: Layer.Layer<never, never, 42>
- * declare const StringLayer: Layer.Layer<never, never, string>
+ * const NumberService = Context.Service<number>("Number")
+ * const numberLayer = Layer.effectDiscard(Effect.asVoid(NumberService))
  *
  * // Define a constraint that the service requirements must be numbers
  * const satisfiesNumber = Layer.satisfiesServicesType<number>()
  *
  * // This works - Layer<never, never, 42> extends Layer<never, never, number>
- * const validLayer = satisfiesNumber(FortyTwoLayer)
- *
- * // This would cause a TypeScript compilation error:
- * // const invalidLayer = satisfiesNumber(StringLayer)
- * //                                     ^^^^^^^^^^^
- * // Type 'string' is not assignable to type 'number'
+ * const validLayer = satisfiesNumber(numberLayer)
  * ```
  *
  * @category utility types
@@ -1697,38 +1719,37 @@ export const satisfiesServicesType = () => layer => layer;
  *
  * **Example** (Tracing layer construction with a span)
  *
- * ```ts
- * import { Console, Context, Effect, Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Layer } from "effect"
  * import type { Tracer } from "effect"
  *
  * class Database extends Context.Service<Database, {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
+ * const logs: Array<string> = []
+ *
  * // Create a traced layer - all operations performed during construction of
  * // the `Database` service are part of the "database-init" span
  * const databaseLayer = Layer.effect(Database, Effect.gen(function*() {
  *   // These operations are traced under "database-init" span
- *   yield* Effect.log("Connecting to database")
- *   yield* Effect.sleep("100 millis")
- *   yield* Effect.log("Database connected")
+ *   logs.push("Connecting to database")
+ *   logs.push("Database connected")
  *
  *   const parentSpan = yield* Effect.currentParentSpan
- *   yield* Console.log((parentSpan as Tracer.Span).name) // "database-init"
+ *   logs.push((parentSpan as Tracer.Span).name)
  *
  *   return {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result: ${sql}`))
  *   }
- * })).pipe(Layer.provide(Layer.span("database-init")))
- *
- * // Can also use the `onEnd` callback to execute logic when the span ends
- * const tracedLayer = Layer.span("service-initialization", {
- *   attributes: { version: "1.0.0" },
+ * })).pipe(Layer.provide(Layer.span("database-init", {
  *   onEnd: (span, exit) =>
- *     Effect.sync(() => {
- *       console.log(`Span ${span.name} ended with:`, exit._tag)
- *     })
- * })
+ *     Effect.sync(() => logs.push(`Span ${span.name} ended with: ${exit._tag}`))
+ * })))
+ *
+ * const program = Database.use((database) => database.query("SELECT 1"))
+ * Effect.runSync(Effect.provide(program, databaseLayer)) // => "Result: SELECT 1"
+ * logs // => ["Connecting to database", "Database connected", "database-init", "Span database-init ended with: Success"]
  * ```
  *
  * @category tracing
@@ -1749,10 +1770,11 @@ export const span = (name, options) => {
  *
  * **Example** (Referencing an existing parent span)
  *
- * ```ts
- * import { Console, Context, Effect, Layer, Tracer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Layer, Tracer } from "effect"
  *
  * class Database extends Context.Service<Database, {
+ *   readonly spanId: string
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }>()("Database") {}
  *
@@ -1760,12 +1782,10 @@ export const span = (name, options) => {
  * const databaseLayer = Layer.effect(
  *   Database,
  *   Effect.gen(function*() {
- *     yield* Effect.log("Initializing database")
- *
  *     const parentSpan = yield* Effect.currentParentSpan
- *     yield* Console.log(parentSpan.spanId) // "42"
  *
  *     return {
+ *       spanId: parentSpan.spanId,
  *       query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result: ${sql}`))
  *     }
  *   })
@@ -1773,6 +1793,9 @@ export const span = (name, options) => {
  *   spanId: "42",
  *   traceId: "000"
  * }))))
+ * const program = Database.use((database) =>
+ *   Effect.map(database.query("SELECT 1"), (result) => ({ spanId: database.spanId, result })))
+ * Effect.runSync(Effect.provide(program, databaseLayer)) // => { spanId: "42", result: "Result: SELECT 1" }
  * ```
  *
  * @category tracing
@@ -1791,7 +1814,7 @@ export const parentSpan = span => succeedContext(Tracer.ParentSpan.context(span)
  *
  * **Example** (Wrapping a layer with a span)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -1802,10 +1825,10 @@ export const parentSpan = span => succeedContext(Tracer.ParentSpan.context(span)
  *   readonly log: (msg: string) => Effect.Effect<void>
  * }>()("Logger") {}
  *
+ * const logs: Array<string> = []
+ *
  * // Create layers with tracing
  * const databaseLayer = Layer.effect(Database, Effect.gen(function*() {
- *   yield* Effect.log("Connecting to database")
- *   yield* Effect.sleep("100 millis")
  *   return {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result: ${sql}`))
  *   }
@@ -1814,16 +1837,14 @@ export const parentSpan = span => succeedContext(Tracer.ParentSpan.context(span)
  * }))
  *
  * const loggerLayer = Layer.succeed(Logger, {
- *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => console.log(msg)))
+ *   log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(msg)))
  * }).pipe(Layer.withSpan("logger-initialization"))
  *
  * // Combine traced layers
  * const appLayer = Layer.mergeAll(databaseLayer, loggerLayer).pipe(
  *   Layer.withSpan("app-initialization", {
  *     onEnd: (span, exit) =>
- *       Effect.sync(() => {
- *         console.log(`Application initialization completed: ${exit._tag}`)
- *       })
+ *       Effect.sync(() => logs.push(`Application initialization completed: ${exit._tag}`))
  *   })
  * )
  *
@@ -1834,6 +1855,8 @@ export const parentSpan = span => succeedContext(Tracer.ParentSpan.context(span)
  *   yield* logger.log("Application ready")
  *   return yield* database.query("SELECT * FROM users")
  * }).pipe(Effect.provide(appLayer))
+ * Effect.runSync(program) // => "Result: SELECT * FROM users"
+ * logs // => ["Application ready", "Application initialization completed: Success"]
  * ```
  *
  * @category tracing
@@ -1865,7 +1888,7 @@ export const withSpan = function () {
  *
  * **Example** (Attaching layers to an existing parent span)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Effect, Layer, Tracer } from "effect"
  *
  * class Database extends Context.Service<Database, {
@@ -1878,14 +1901,12 @@ export const withSpan = function () {
  *
  * // Create layers
  * const DatabaseLayer = Layer.effect(Database, Effect.gen(function*() {
- *   yield* Effect.log("Connecting to database")
  *   return {
  *     query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
  *   }
  * }))
  *
  * const CacheLayer = Layer.effect(Cache, Effect.gen(function*() {
- *   yield* Effect.log("Connecting to cache")
  *   return {
  *     get: Effect.fn("Cache.get")((key: string) => Effect.succeed(`Cache: ${key}`))
  *   }
@@ -1911,6 +1932,7 @@ export const withSpan = function () {
  *     return { dbResult, cacheResult }
  *   })
  * )
+ * Effect.runSync(Effect.scoped(program)) // => { dbResult: "DB: SELECT * FROM users", cacheResult: "Cache: user:123" }
  * ```
  *
  * @category tracing