effect 3.10.18 → 3.11.0

package/dist/esm/Effect.js

@@ -1,4 +1,5 @@
 import { dual } from "./Function.js";
+import * as internalCause from "./internal/cause.js";
 import * as _console from "./internal/console.js";
 import { TagProto } from "./internal/context.js";
 import * as effect from "./internal/core-effect.js";
@@ -12,6 +13,7 @@ import * as _runtime from "./internal/runtime.js";
 import * as _schedule from "./internal/schedule.js";
 import * as Request from "./Request.js";
 import * as Scheduler from "./Scheduler.js";
+import { internalCall, isGeneratorFunction } from "./Utils.js";
 /**
  * @since 2.0.0
  * @category Symbols
@@ -36,6 +38,7 @@ export const isEffect = core.isEffect;
  * be recomputed upon next evaluation.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * let i = 1
@@ -63,6 +66,7 @@ export const isEffect = core.isEffect;
  * // result 1
  * // expensive task...
  * // result 2
+ * ```
  *
  * @since 2.0.0
  * @category Caching
@@ -74,6 +78,7 @@ export const cachedWithTTL = circular.cached;
  * invalidating the cached value before it naturally expires.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * let i = 1
@@ -104,6 +109,7 @@ export const cachedWithTTL = circular.cached;
  * // result 1
  * // expensive task...
  * // result 2
+ * ```
  *
  * @since 2.0.0
  * @category Caching
@@ -115,6 +121,7 @@ export const cachedInvalidateWithTTL = circular.cachedInvalidateWithTTL;
  * the logic.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * let i = 1
@@ -148,6 +155,7 @@ export const cachedInvalidateWithTTL = circular.cachedInvalidateWithTTL;
  * // expensive task...
  * // result 3
  * // result 3
+ * ```
  *
  * @since 2.0.0
  * @category Caching
@@ -159,6 +167,7 @@ export const cached = effect.memoize;
  * recompute them.
  *
  * @example
+ * ```ts
  * import { Effect, Random } from "effect"
  *
  * const program = Effect.gen(function* () {
@@ -181,6 +190,7 @@ export const cached = effect.memoize;
  * // memoized version:
  * // 5
  * // 5
+ * ```
  *
  * @since 2.0.0
  * @category Caching
@@ -191,6 +201,7 @@ export const cachedFunction = circular.cachedFunction;
  * called.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * const program = Effect.gen(function* () {
@@ -206,6 +217,7 @@ export const cachedFunction = circular.cachedFunction;
  * // task1
  * // task1
  * // task2
+ * ```
  *
  * @since 2.0.0
  * @category Caching
@@ -261,6 +273,7 @@ export const once = effect.once;
  * @see {@link forEach} for iterating over elements and applying an effect.
  *
  * @example
+ * ```ts
  * // Title: Combining Effects in Tuples
  * import { Effect, Console } from "effect"
  *
@@ -278,6 +291,7 @@ export const once = effect.once;
  * // 42
  * // Hello
  * // [ 42, 'Hello' ]
+ * ```
  *
  * @example
  * // Title: Combining Effects in Iterables
@@ -426,6 +440,7 @@ export const all = fiberRuntime.all;
  * your data and then apply operations to it.
  *
  * @example
+ * ```ts
  * import { Effect, pipe } from "effect"
  *
  * const task1 = Effect.succeed(1).pipe(
@@ -449,6 +464,7 @@ export const all = fiberRuntime.all;
  * // timestamp=... level=INFO fiber=#3 message="task2 done"
  * // timestamp=... level=INFO fiber=#2 message="task1 done"
  * // [ 1, 'hello' ]
+ * ```
  *
  * @since 2.0.0
  * @category Collecting
@@ -510,6 +526,7 @@ export const filter = fiberRuntime.filter;
  * @see {@link filter} for concurrent filtering without mapping.
  *
  * @example
+ * ```ts
  * import { Console, Effect, Option } from "effect"
  *
  * const task = (n: number) =>
@@ -530,6 +547,7 @@ export const filter = fiberRuntime.filter;
  * // task3 done
  * // task4 done
  * // [ 2, 4 ]
+ * ```
  *
  * @since 2.0.0
  * @category Filtering
@@ -566,6 +584,7 @@ export const findFirst = effect.findFirst;
  * @see {@link all} for combining multiple effects into one.
  *
  * @example
+ * ```ts
  * // Title: Applying Effects to Iterable Elements
  * import { Effect, Console } from "effect"
  *
@@ -581,6 +600,7 @@ export const findFirst = effect.findFirst;
  * // Currently at index 3
  * // Currently at index 4
  * // [ 2, 4, 6, 8, 10 ]
+ * ```
  *
  * @example
  * // Title: Using discard to Ignore Results
@@ -639,6 +659,7 @@ export const mergeAll = fiberRuntime.mergeAll;
  * @see {@link validateFirst} for a function that stops at the first success.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<[string[], number[]], never, never>
@@ -654,6 +675,7 @@ export const mergeAll = fiberRuntime.mergeAll;
  * Effect.runPromise(program).then(console.log, console.error)
  * // Output:
  * // [ [ '1 is not even', '3 is not even' ], [ 0, 2, 4 ] ]
+ * ```
  *
  * @since 2.0.0
  * @category Error Accumulation
@@ -734,6 +756,7 @@ export const takeWhile = effect.takeWhile;
  * @see {@link partition} when you need to separate successes and failures instead of losing successes with errors.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * //      ┌─── Effect<number[], string[], never>
@@ -760,6 +783,7 @@ export const takeWhile = effect.takeWhile;
  * //     failure: [ '4 is not less that 4', '5 is not less that 4' ]
  * //   }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Error Accumulation
@@ -781,6 +805,7 @@ export const validateAll = fiberRuntime.validateAll;
  * @see {@link firstSuccessOf} for a similar function that processes multiple effects and returns the first successful one or the last error.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * //      ┌─── Effect<number, string[], never>
@@ -797,6 +822,7 @@ export const validateAll = fiberRuntime.validateAll;
  * // Output:
  * // item 4
  * // 4
+ * ```
  *
  * @since 2.0.0
  * @category Error Accumulation
@@ -827,6 +853,7 @@ export const validateFirst = fiberRuntime.validateFirst;
  * behavior of the returned effect.
  *
  * @example
+ * ```ts
  * // Title: Wrapping a Callback API
  * import { Effect } from "effect"
  * import * as NodeFS from "node:fs"
@@ -847,6 +874,7 @@ export const validateFirst = fiberRuntime.validateFirst;
  * //      ┌─── Effect<Buffer, Error, never>
  * //      ▼
  * const program = readFile("example.txt")
+ * ```
  *
  * @example
  * // Title: Handling Interruption with Cleanup
@@ -937,12 +965,14 @@ export const asyncEffect = _runtime.asyncEffect;
  * the "this" of the effect.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const throwingFunction = () => { throw new Error() }
  * const blowUp = Effect.custom(throwingFunction, function() {
  *   return Effect.succeed(this.effect_instruction_i0())
  * })
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -965,6 +995,7 @@ export const withFiberRuntime = core.withFiberRuntime;
  * @see {@link succeed} to create an effect that represents a successful value.
  *
  * @example
+ * ```ts
  * // Title: Creating a Failed Effect
  * import { Effect } from "effect"
  *
@@ -973,6 +1004,7 @@ export const withFiberRuntime = core.withFiberRuntime;
  * const failure = Effect.fail(
  *   new Error("Operation failed due to network error")
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -1014,6 +1046,7 @@ export const failCauseSync = core.failCauseSync;
  * @see {@link dieMessage} for a variant that throws a `RuntimeException` with a message.
  *
  * @example
+ * ```ts
  * // Title: Terminating on Division by Zero with a Specified Error
  * import { Effect } from "effect"
  *
@@ -1030,6 +1063,7 @@ export const failCauseSync = core.failCauseSync;
  * // Output:
  * // (FiberFailure) Error: Cannot divide by zero
  * //   ...stack trace...
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -1058,6 +1092,7 @@ export const die = core.die;
  * lazily.
  *
  * @example
+ * ```ts
  * // Title: Terminating on Division by Zero with a Specified Message
  * import { Effect } from "effect"
  *
@@ -1074,6 +1109,7 @@ export const die = core.die;
  * // Output:
  * // (FiberFailure) RuntimeException: Cannot divide by zero
  * //   ...stack trace...
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -1107,6 +1143,7 @@ export const dieSync = core.dieSync;
  * effects and return the final result at the end.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const addServiceCharge = (amount: number) => amount + 1
@@ -1133,6 +1170,7 @@ export const dieSync = core.dieSync;
  *   const finalAmount = addServiceCharge(discountedAmount)
  *   return `Final amount to charge: ${finalAmount}`
  * })
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -1179,6 +1217,7 @@ export const none = effect.none;
  * @see {@link tryPromise} for a version that can handle failures.
  *
  * @example
+ * ```ts
  * // Title: Delayed Message
  * import { Effect } from "effect"
  *
@@ -1195,6 +1234,7 @@ export const none = effect.none;
  * //      ┌─── Effect<string, never, never>
  * //      ▼
  * const program = delay("Async operation completed successfully!")
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -1211,6 +1251,7 @@ export const promise = effect.promise;
  * @see {@link fail} to create an effect that represents a failure.
  *
  * @example
+ * ```ts
  * // Title: Creating a Successful Effect
  * import { Effect } from "effect"
  *
@@ -1219,6 +1260,7 @@ export const promise = effect.promise;
  * //      ┌─── Effect<number, never, never>
  * //      ▼
  * const success = Effect.succeed(42)
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -1253,6 +1295,7 @@ export const succeedSome = effect.succeedSome;
  * - **Unifying Return Types**: Can help TypeScript unify return types in situations where multiple branches of logic return different effects, simplifying type inference.
  *
  * @example
+ * ```ts
  * // Title: Lazy Evaluation with Side Effects
  * import { Effect } from "effect"
  *
@@ -1267,6 +1310,7 @@ export const succeedSome = effect.succeedSome;
  *
  * console.log(Effect.runSync(good)) // Output: 1
  * console.log(Effect.runSync(good)) // Output: 2
+ * ```
  *
  * @example
  * // Title: Recursive Fibonacci
@@ -1339,6 +1383,7 @@ export const suspend = core.suspend;
  * @see {@link try_ | try} for a version that can handle failures.
  *
  * @example
+ * ```ts
  * // Title: Logging a Message
  * import { Effect } from "effect"
  *
@@ -1350,6 +1395,7 @@ export const suspend = core.suspend;
  * //      ┌─── Effect<void, never, never>
  * //      ▼
  * const program = log("Hello, World!")
+ * ```
  *
  * @since 2.0.0
  * @category Creating Effects
@@ -1392,6 +1438,7 @@ _catch as catch };
  * @see {@link catchAllCause} for a version that can recover from both recoverable and unrecoverable errors.
  *
  * @example
+ * ```ts
  * // Title: Providing Recovery Logic for Recoverable Errors
  * import { Effect, Random } from "effect"
  *
@@ -1424,6 +1471,7 @@ _catch as catch };
  *     Effect.succeed(`Recovering from ${error._tag}`)
  *   )
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1447,6 +1495,7 @@ export const catchAll = core.catchAll;
  * dynamically loaded plugins, controlled recovery might be needed.
  *
  * @example
+ * ```ts
  * // Title: Recovering from All Errors
  * import { Cause, Effect } from "effect"
  *
@@ -1464,6 +1513,7 @@ export const catchAll = core.catchAll;
  *
  * Effect.runPromise(recovered).then(console.log)
  * // Output: "Recovered from a regular error"
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1493,6 +1543,7 @@ export const catchAllCause = core.catchAllCause;
  * dynamically loaded plugins, controlled recovery might be needed.
  *
  * @example
+ * ```ts
  * // Title: Handling All Defects
  * import { Effect, Cause, Console } from "effect"
  *
@@ -1517,6 +1568,7 @@ export const catchAllCause = core.catchAllCause;
  * //   _tag: "Success",
  * //   value: undefined
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1534,6 +1586,7 @@ export const catchAllDefect = effect.catchAllDefect;
  * error type unless a user-defined type guard is used to narrow the type.
  *
  * @example
+ * ```ts
  * // Title: Catching Specific Errors with a Predicate
  * import { Effect, Random } from "effect"
  *
@@ -1568,6 +1621,7 @@ export const catchAllDefect = effect.catchAllDefect;
  *     () => Effect.succeed("Recovering from HttpError")
  *   )
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1588,6 +1642,7 @@ export const catchIf = core.catchIf;
  * @see {@link catchIf} for a version that allows you to recover from errors based on a predicate.
  *
  * @example
+ * ```ts
  * // Title: Handling Specific Errors with Effect.catchSome
  * import { Effect, Random, Option } from "effect"
  *
@@ -1625,6 +1680,7 @@ export const catchIf = core.catchIf;
  *     }
  *   })
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1664,6 +1720,7 @@ export const catchSomeCause = effect.catchSomeCause;
  * - If the defect does not match, the function returns `Option.none`, allowing the defect to propagate.
  *
  * @example
+ * ```ts
  * // Title: Handling Specific Defects
  * import { Effect, Cause, Option, Console } from "effect"
  *
@@ -1694,6 +1751,7 @@ export const catchSomeCause = effect.catchSomeCause;
  * //     defect: { _tag: 'RuntimeException' }
  * //   }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1717,6 +1775,7 @@ export const catchSomeDefect = effect.catchSomeDefect;
  * types at once.
  *
  * @example
+ * ```ts
  * // Title: Handling Errors by Tag
  * import { Effect, Random } from "effect"
  *
@@ -1750,6 +1809,7 @@ export const catchSomeDefect = effect.catchSomeDefect;
  *     Effect.succeed("Recovering from HttpError")
  *   )
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1770,6 +1830,7 @@ export const catchTag = effect.catchTag;
  * field is used to identify and match errors.
  *
  * @example
+ * ```ts
  * // Title: Handling Multiple Tagged Error Types at Once
  * import { Effect, Random } from "effect"
  *
@@ -1805,6 +1866,7 @@ export const catchTag = effect.catchTag;
  *       Effect.succeed(`Recovering from ValidationError`)
  *   })
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1822,6 +1884,7 @@ export const catchTags = effect.catchTags;
  * interruptions, etc.).
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * //      ┌─── Effect<number, string, never>
@@ -1834,6 +1897,7 @@ export const catchTags = effect.catchTags;
  *   const cause = yield* Effect.cause(program)
  *   yield* Console.log(cause)
  * })
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1855,6 +1919,7 @@ export const eventually = effect.eventually;
  * side effects of the effect and do not need to handle or process its outcome.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, string, never>
@@ -1864,6 +1929,7 @@ export const eventually = effect.eventually;
  * //      ┌─── Effect<void, never, never>
  * //      ▼
  * const program = Effect.ignore(task)
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1889,6 +1955,7 @@ export const ignoreLogged = effect.ignoreLogged;
  * it easier to manage and respond to errors from multiple operations at once.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const fail1 = Effect.fail("Oh uh!")
@@ -1907,6 +1974,7 @@ export const ignoreLogged = effect.ignoreLogged;
  * //   _tag: 'Failure',
  * //   cause: { _id: 'Cause', _tag: 'Fail', failure: [ 'Oh uh!', 'Oh no!' ] }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1928,6 +1996,7 @@ export const parallelErrors = effect.parallelErrors;
  * @see {@link unsandbox} to restore the original error handling.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * //      ┌─── Effect<string, Error, never>
@@ -1962,6 +2031,7 @@ export const parallelErrors = effect.parallelErrors;
  * // Output:
  * // Caught a defect: Oh uh!
  * // fallback result on failure
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -1984,6 +2054,7 @@ export const sandbox = effect.sandbox;
  * @see {@link retryOrElse} for a version that allows you to run a fallback.
  *
  * @example
+ * ```ts
  * import { Effect, Schedule } from "effect"
  *
  * let count = 0
@@ -2012,6 +2083,7 @@ export const sandbox = effect.sandbox;
  * // failure
  * // success
  * // yay!
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -2029,6 +2101,7 @@ export const retry = _schedule.retry_combined;
  * @see {@link retry} for a version that does not run a fallback effect.
  *
  * @example
+ * ```ts
  * import { Effect, Schedule, Console } from "effect"
  *
  * let count = 0
@@ -2060,6 +2133,7 @@ export const retry = _schedule.retry_combined;
  * // failure
  * // orElse
  * // default value
+ * ```
  *
  * @since 2.0.0
  * @category Error handling
@@ -2091,6 +2165,7 @@ export {
  * throw errors.
  *
  * @example
+ * ```ts
  * // Title: Safe JSON Parsing
  * import { Effect } from "effect"
  *
@@ -2102,6 +2177,7 @@ export {
  * //      ▼
  * const program = parse("")
  *
+ * ```
  * @example
  * // Title: Custom Error Handling
  * import { Effect } from "effect"
@@ -2172,6 +2248,7 @@ export const tryMapPromise = effect.tryMapPromise;
  * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
  *
  * @example
+ * ```ts
  * // Title: Fetching a TODO Item
  * import { Effect } from "effect"
  *
@@ -2184,6 +2261,7 @@ export const tryMapPromise = effect.tryMapPromise;
  * //      ┌─── Effect<Response, UnknownException, never>
  * //      ▼
  * const program = getTodo(1)
+ * ```
  *
  * @example
  * // Title: Custom Error Handling
@@ -2266,6 +2344,7 @@ export const checkInterruptible = core.checkInterruptible;
  * @see {@link Effect.uninterruptible} for creating an uninterruptible effect.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const longRunningTask = Effect.gen(function* () {
@@ -2295,6 +2374,7 @@ export const checkInterruptible = core.checkInterruptible;
  * //   }
  * // }
  * // Heavy processing done.
+ * ```
  *
  * @since 2.0.0
  * @category Interruption
@@ -2340,6 +2420,7 @@ export const uninterruptibleMask = core.uninterruptibleMask;
  * or failing with specified error if the predicate fails
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const isPositive = (n: number): boolean => n > 0
@@ -2349,6 +2430,7 @@ export const uninterruptibleMask = core.uninterruptibleMask;
  *
  * // fails with `"0 is not positive"`
  * Effect.liftPredicate(0, isPositive, n => `${n} is not positive`)
+ * ```
  *
  * @category Condition Checking
  * @since 3.4.0
@@ -2361,6 +2443,7 @@ export const liftPredicate = effect.liftPredicate;
  * replace it with a new constant value.
  *
  * @example
+ * ```ts
  * // Title: Replacing a Value
  * import { pipe, Effect } from "effect"
  *
@@ -2369,6 +2452,7 @@ export const liftPredicate = effect.liftPredicate;
  *
  * Effect.runPromise(program).then(console.log)
  * // Output: "new value"
+ * ```
  *
  * @since 2.0.0
  * @category Mapping
@@ -2412,6 +2496,7 @@ export const asVoid = core.asVoid;
  * treat an error as a valid result.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, string, never>
@@ -2421,6 +2506,7 @@ export const asVoid = core.asVoid;
  * //      ┌─── Effect<string, number, never>
  * //      ▼
  * const flipped = Effect.flip(program)
+ * ```
  *
  * @since 2.0.0
  * @category Mapping
@@ -2461,6 +2547,7 @@ export const flipWith = effect.flipWith;
  * @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
  *
  * @example
+ * ```ts
  * // Title: Adding a Service Charge
  * import { pipe, Effect } from "effect"
  *
@@ -2475,6 +2562,7 @@ export const flipWith = effect.flipWith;
  *
  * Effect.runPromise(finalAmount).then(console.log)
  * // Output: 101
+ * ```
  * @since 2.0.0
  * @category Mapping
  */
@@ -2499,6 +2587,7 @@ export const map = core.map;
  * input collection type.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * // Define an initial state and a transformation function
@@ -2517,6 +2606,7 @@ export const map = core.map;
  * // Output:
  * // 6
  * // [ 'A', 'BB', 'CCC' ]
+ * ```
  *
  * @since 2.0.0
  * @category Mapping
@@ -2535,6 +2625,7 @@ export const mapAccum = effect.mapAccum;
  * @see {@link mapError} for a version that operates on the error channel.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, string, never>
@@ -2547,6 +2638,7 @@ export const mapAccum = effect.mapAccum;
  *   onFailure: (message) => new Error(message),
  *   onSuccess: (n) => n > 0
  * })
+ * ```
  *
  * @since 2.0.0
  * @category Mapping
@@ -2566,6 +2658,7 @@ export const mapBoth = core.mapBoth;
  * @see {@link orElseFail} if you want to replace the error with a new one.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, string, never>
@@ -2578,6 +2671,7 @@ export const mapBoth = core.mapBoth;
  *   simulatedTask,
  *   (message) => new Error(message)
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Mapping
@@ -2605,6 +2699,7 @@ export const mapErrorCause = effect.mapErrorCause;
  * errors as part of the outcome.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, string, never>
@@ -2614,6 +2709,7 @@ export const mapErrorCause = effect.mapErrorCause;
  * //      ┌─── Effect<number | string, never, never>
  * //      ▼
  * const recovered = Effect.merge(program)
+ * ```
  *
  * @since 2.0.0
  * @category Mapping
@@ -2762,6 +2858,15 @@ export const scope = fiberRuntime.scope;
  * @category scoping, resources & finalization
  */
 export const scopeWith = fiberRuntime.scopeWith;
+/**
+ * Creates a `Scope`, passes it to the specified effectful function, and then
+ * closes the scope as soon as the effect is complete (whether through success,
+ * failure, or interruption).
+ *
+ * @since 3.11.0
+ * @category scoping, resources & finalization
+ */
+export const scopedWith = fiberRuntime.scopedWith;
 /**
  * Scopes all resources used in this workflow to the lifetime of the workflow,
  * ensuring that their finalizers are run as soon as this workflow completes
@@ -3085,6 +3190,7 @@ export const timedWith = effect.timedWith;
  * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const task = Effect.gen(function* () {
@@ -3110,6 +3216,7 @@ export const timedWith = effect.timedWith;
  * //     failure: { _tag: 'TimeoutException' }
  * //   }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category delays & timeouts
@@ -3135,6 +3242,7 @@ export const timeout = circular.timeout;
  * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const task = Effect.gen(function* () {
@@ -3158,6 +3266,7 @@ export const timeout = circular.timeout;
  * //   { _id: 'Option', _tag: 'Some', value: 'Result' },
  * //   { _id: 'Option', _tag: 'None' }
  * // ]
+ * ```
  *
  * @since 3.1.0
  * @category delays & timeouts
@@ -3182,6 +3291,7 @@ export const timeoutOption = circular.timeoutOption;
  * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const task = Effect.gen(function* () {
@@ -3214,6 +3324,7 @@ export const timeoutOption = circular.timeoutOption;
  * //     failure: MyTimeoutError { _tag: 'MyTimeoutError' }
  * //   }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category delays & timeouts
@@ -3237,6 +3348,7 @@ export const timeoutFail = circular.timeoutFail;
  * @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
  *
  * @example
+ * ```ts
  * import { Effect, Cause } from "effect"
  *
  * const task = Effect.gen(function* () {
@@ -3261,6 +3373,7 @@ export const timeoutFail = circular.timeoutFail;
  * //   _tag: 'Failure',
  * //   cause: { _id: 'Cause', _tag: 'Die', defect: 'Timed out!' }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category delays & timeouts
@@ -3288,6 +3401,7 @@ export const timeoutFailCause = circular.timeoutFailCause;
  * @see {@link timeoutFailCause} for a version that raises a custom defect.
  *
  * @example
+ * ```ts
  * import { Effect, Either } from "effect"
  *
  * const task = Effect.gen(function* () {
@@ -3315,6 +3429,7 @@ export const timeoutFailCause = circular.timeoutFailCause;
  * //   _tag: "Left",
  * //   left: "Timed out!"
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category delays & timeouts
@@ -3381,6 +3496,7 @@ export const mapInputContext = core.mapInputContext;
  * @see {@link provideService} for providing a service to an effect.
  *
  * @example
+ * ```ts
  * import { Context, Effect, Layer } from "effect"
  *
  * class Database extends Context.Tag("Database")<
@@ -3412,6 +3528,7 @@ export const mapInputContext = core.mapInputContext;
  * // Output:
  * // timestamp=... level=INFO fiber=#0 message="Executing query: SELECT * FROM users"
  * // []
+ * ```
  *
  * @since 2.0.0
  * @category Context
@@ -3430,6 +3547,7 @@ export const provide = layer.effect_provide;
  * @see {@link provide} for providing multiple layers to an effect.
  *
  * @example
+ * ```ts
  * import { Effect, Context } from "effect"
  *
  * // Declaring a tag for a service that generates random numbers
@@ -3457,6 +3575,7 @@ export const provide = layer.effect_provide;
  * Effect.runPromise(runnable)
  * // Example Output:
  * // random number: 0.8241872233134417
+ * ```
  *
  * @since 2.0.0
  * @category Context
@@ -3527,6 +3646,7 @@ export const updateService = effect.updateService;
  * @see {@link let_ let}
  *
  * @example
+ * ```ts
  * import { Effect, pipe } from "effect"
  *
  * const result = pipe(
@@ -3536,6 +3656,7 @@ export const updateService = effect.updateService;
  *   Effect.let("sum", ({ x, y }) => x + y)
  * )
  * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ * ```
  *
  * @category Do notation
  * @since 2.0.0
@@ -3556,6 +3677,7 @@ export const Do = effect.Do;
  * @see {@link let_ let}
  *
  * @example
+ * ```ts
  * import { Effect, pipe } from "effect"
  *
  * const result = pipe(
@@ -3565,6 +3687,7 @@ export const Do = effect.Do;
  *   Effect.let("sum", ({ x, y }) => x + y)
  * )
  * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ * ```
  *
  * @category Do notation
  * @since 2.0.0
@@ -3576,6 +3699,7 @@ export const bind = effect.bind;
  * results in a Do notation pipeline.
  *
  * @example
+ * ```ts
  * import { Effect, Either, pipe } from "effect"
  *
  * const result = pipe(
@@ -3587,6 +3711,7 @@ export const bind = effect.bind;
  *   }), { concurrency: 2, mode: "either" })
  * )
  * assert.deepStrictEqual(Effect.runSync(result), { x: 2, a: Either.right(2), b: Either.left("oops") })
+ * ```
  *
  * @category Do notation
  * @since 3.7.0
@@ -3607,6 +3732,7 @@ export const bindAll = circular.bindAll;
  * @see {@link let_ let}
  *
  * @example
+ * ```ts
  * import { Effect, pipe } from "effect"
  *
  * const result = pipe(
@@ -3616,6 +3742,7 @@ export const bindAll = circular.bindAll;
  *   Effect.let("sum", ({ x, y }) => x + y)
  * )
  * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ * ```
  *
  * @category Do notation
  * @since 2.0.0
@@ -3638,6 +3765,7 @@ export {
  * @see {@link bindTo}
  *
  * @example
+ * ```ts
  * import { Effect, pipe } from "effect"
  *
  * const result = pipe(
@@ -3648,6 +3776,7 @@ export {
  * )
  * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
  *
+ * ```
  * @category Do notation
  * @since 2.0.0
  */
@@ -3670,6 +3799,7 @@ let_ as let };
  * @see {@link exit} for a version that uses `Exit` instead.
  *
  * @example
+ * ```ts
  * // Title: Using Effect.option to Handle Errors
  * import { Effect } from "effect"
  *
@@ -3702,6 +3832,7 @@ let_ as let };
  * //   _tag: 'Failure',
  * //   cause: { _id: 'Cause', _tag: 'Die', defect: 'Boom!' }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Outcome Encapsulation
@@ -3726,6 +3857,7 @@ export const option = effect.option;
  * @see {@link exit} for a version that uses `Exit` instead.
  *
  * @example
+ * ```ts
  * import { Effect, Either, Random } from "effect"
  *
  * class HttpError {
@@ -3761,6 +3893,7 @@ export const option = effect.option;
  *     onRight: (value) => value // Do nothing in case of success
  *   })
  * })
+ * ```
  *
  * @since 2.0.0
  * @category Outcome Encapsulation
@@ -3783,6 +3916,7 @@ export const either = core.either;
  * @see {@link either} for a version that uses `Either` instead.
  *
  * @example
+ * ```ts
  * import { Effect, Cause, Console, Exit } from "effect"
  *
  * // Simulating a runtime error
@@ -3814,6 +3948,7 @@ export const either = core.either;
  * //   _tag: "Success",
  * //   value: undefined
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Outcome Encapsulation
@@ -3830,6 +3965,7 @@ export const exit = core.exit;
  * failure. Additionally, if the effect is interrupted, the `Deferred` will also be interrupted.
  *
  * @example
+ * ```ts
  * import { Deferred, Effect } from "effect"
  *
  * // Define an effect that succeeds
@@ -3853,6 +3989,7 @@ export const exit = core.exit;
  * // Output:
  * // 42
  * // true
+ * ```
  *
  * @since 2.0.0
  * @category Synchronization Utilities
@@ -3868,6 +4005,7 @@ export {
  * is executed. If it is `false`, the `onFalse` effect is executed instead.
  *
  * @example
+ * ```ts
  * // Title: Simulating a Coin Flip
  * import { Effect, Random, Console } from "effect"
  *
@@ -3878,6 +4016,7 @@ export {
  *
  * Effect.runFork(flipTheCoin)
  *
+ * ```
  * @since 2.0.0
  * @category Conditional Operators
  */
@@ -3917,6 +4056,7 @@ export const filterOrElse = effect.filterOrElse;
  * Let's explore this concept through an example:
  *
  * @example
+ * ```ts
  * import { Effect, pipe } from "effect"
  *
  * // Define a user interface
@@ -3937,6 +4077,7 @@ export const filterOrElse = effect.filterOrElse;
  *   // 'user' now has the type `User` (not `User | null`)
  *   Effect.andThen((user) => user.name)
  * )
+ * ```
  *
  * @since 2.0.0
  * @category Filtering
@@ -3980,6 +4121,7 @@ export const unlessEffect = effect.unlessEffect;
  * @see {@link unless} for a version that executes the effect when the condition is `false`.
  *
  * @example
+ * ```ts
  * // Title: Conditional Effect Execution
  * import { Effect, Option } from "effect"
  *
@@ -4005,6 +4147,7 @@ export const unlessEffect = effect.unlessEffect;
  * //   _id: "Option",
  * //   _tag: "None"
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Conditional Operators
@@ -4028,6 +4171,7 @@ export const when = effect.when;
  * @see {@link unlessEffect} for a version that executes the effect when the condition is `false`.
  *
  * @example
+ * ```ts
  * // Title: Using an Effect as a Condition
  * import { Effect, Random } from "effect"
  *
@@ -4038,6 +4182,7 @@ export const when = effect.when;
  * console.log(Effect.runSync(randomIntOption))
  * // Example Output:
  * // { _id: 'Option', _tag: 'Some', value: 8609104974198840 }
+ * ```
  *
  * @since 2.0.0
  * @category Conditional Operators
@@ -4088,6 +4233,7 @@ export const whenRef = effect.whenRef;
  * changing the original one.
  *
  * @example
+ * ```ts
  * import { pipe, Effect } from "effect"
  *
  * // Function to apply a discount safely to a transaction amount
@@ -4110,6 +4256,7 @@ export const whenRef = effect.whenRef;
  *
  * Effect.runPromise(finalAmount).then(console.log)
  * // Output: 95
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4149,6 +4296,7 @@ export const flatMap = core.flatMap;
  * treating them as effects.
  *
  * @example
+ * ```ts
  * // Title: Applying a Discount Based on Fetched Amount
  * import { pipe, Effect } from "effect"
  *
@@ -4183,6 +4331,7 @@ export const flatMap = core.flatMap;
  *
  * Effect.runPromise(result2).then(console.log)
  * // Output: 190
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4263,6 +4412,7 @@ export const summarized = effect.summarized;
  * will fail too.
  *
  * @example
+ * ```ts
  * // Title: Logging a step in a pipeline
  * import { Console, Effect, pipe } from "effect"
  *
@@ -4290,6 +4440,7 @@ export const summarized = effect.summarized;
  * // Output:
  * // Apply a discount to: 100
  * // 95
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4307,6 +4458,7 @@ export const tap = core.tap;
  * altering the result.
  *
  * @example
+ * ```ts
  * import { Effect, Random, Console } from "effect"
  *
  * // Simulate a task that might fail
@@ -4326,6 +4478,7 @@ export const tap = core.tap;
  * Effect.runFork(tapping)
  * // Example Output:
  * // failure: random number is negative
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4342,6 +4495,7 @@ export const tapBoth = effect.tapBoth;
  * severe errors.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * // Simulate a task that fails with a recoverable error
@@ -4369,6 +4523,7 @@ export const tapBoth = effect.tapBoth;
  * // Output:
  * // defect: RuntimeException: Something went wrong
  * //   ... stack trace ...
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4384,6 +4539,7 @@ export const tapDefect = effect.tapDefect;
  * while the operation you provide can inspect or act on it.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * // Simulate a task that fails with an error
@@ -4397,6 +4553,7 @@ export const tapDefect = effect.tapDefect;
  * Effect.runFork(tapping)
  * // Output:
  * // expected error: NetworkError
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4412,6 +4569,7 @@ export const tapError = effect.tapError;
  * without modifying the error or the overall result of the effect.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * class NetworkError {
@@ -4436,6 +4594,7 @@ export const tapError = effect.tapError;
  * Effect.runFork(tapping)
  * // Output:
  * // expected error: 504
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4451,6 +4610,7 @@ export const tapErrorTag = effect.tapErrorTag;
  * altering the error or the overall result of the effect.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * // Create a task that fails with a NetworkError
@@ -4477,6 +4637,7 @@ export const tapErrorTag = effect.tapErrorTag;
  * // Output:
  * // error cause: RuntimeException: Something went wrong
  * //   ... stack trace ...
+ * ```
  *
  * @since 2.0.0
  * @category sequencing
@@ -4508,6 +4669,7 @@ export const forever = effect.forever;
  * ```
  *
  * @example
+ * ```ts
  * // Title: Effectful Iteration
  * import { Effect } from "effect"
  *
@@ -4524,6 +4686,7 @@ export const forever = effect.forever;
  *
  * Effect.runPromise(result).then(console.log)
  * // Output: 6
+ * ```
  *
  * @since 2.0.0
  * @category Looping
@@ -4556,6 +4719,7 @@ export const iterate = effect.iterate;
  * discarded, and the final result will be `void`.
  *
  * @example
+ * ```ts
  * // Title: Looping with Collected Results
  * import { Effect } from "effect"
  *
@@ -4575,6 +4739,7 @@ export const iterate = effect.iterate;
  *
  * Effect.runPromise(result).then(console.log)
  * // Output: [1, 2, 3, 4, 5]
+ * ```
  *
  * @example
  * // Title: Loop with Discarded Results
@@ -4616,6 +4781,7 @@ export const loop = effect.loop;
  * an additional time.
  *
  * @example
+ * ```ts
  * // Success Example
  * import { Effect, Schedule, Console } from "effect"
  *
@@ -4624,6 +4790,7 @@ export const loop = effect.loop;
  * const program = Effect.repeat(action, policy)
  *
  * Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
+ * ```
  *
  * @example
  * // Failure Example
@@ -4659,12 +4826,14 @@ export const repeat = _schedule.repeat_combined;
  * initially and then repeats it one additional time if it succeeds.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * const action = Console.log("success")
  * const program = Effect.repeatN(action, 2)
  *
  * Effect.runPromise(program)
+ * ```
  *
  * @since 2.0.0
  * @category repetition / recursion
@@ -4679,6 +4848,7 @@ export const repeatN = effect.repeatN;
  * initially and then repeats it an additional time if it succeeds.
  *
  * @example
+ * ```ts
  * import { Effect, Schedule } from "effect"
  *
  * let count = 0
@@ -4708,6 +4878,7 @@ export const repeatN = effect.repeatN;
  * )
  *
  * Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
+ * ```
  *
  * @since 2.0.0
  * @category repetition / recursion
@@ -4830,6 +5001,7 @@ export const isSuccess = effect.isSuccess;
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const success: Effect.Effect<number, Error> = Effect.succeed(42)
@@ -4855,6 +5027,7 @@ export const isSuccess = effect.isSuccess;
  * // Run and log the result of the failed effect
  * Effect.runPromise(program2).then(console.log)
  * // Output: "failure: Uh oh!"
+ * ```
  *
  * @since 2.0.0
  * @category getters & folding
@@ -4890,6 +5063,7 @@ export const matchCause = core.matchCause;
  * @see {@link matchEffect} if you don't need to handle the cause of the failure.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * const task: Effect.Effect<number, Error> = Effect.die("Uh oh!")
@@ -4917,6 +5091,7 @@ export const matchCause = core.matchCause;
  *
  * Effect.runSync(program)
  * // Output: "Die: Uh oh!"
+ * ```
  *
  * @since 2.0.0
  * @category getters & folding
@@ -4945,6 +5120,7 @@ export const matchEffect = core.matchEffect;
  * To adjust the log level, use the `Logger.withMinimumLogLevel` function.
  *
  * @example
+ * ```ts
  * import { Cause, Effect } from "effect"
  *
  * const program = Effect.log(
@@ -4958,6 +5134,7 @@ export const matchEffect = core.matchEffect;
  * // Output:
  * // timestamp=... level=INFO fiber=#0 message=message1 message=message2 cause="Error: Oh no!
  * // Error: Oh uh!"
+ * ```
  *
  * @since 2.0.0
  * @category Logging
@@ -4985,12 +5162,14 @@ export const logTrace = effect.logTrace;
  * `Logger.withMinimumLogLevel` and set the log level to `LogLevel.Debug`.
  *
  * @example
+ * ```ts
  * import { Effect, Logger, LogLevel } from "effect"
  *
  * const program = Effect.logDebug("message1").pipe(Logger.withMinimumLogLevel(LogLevel.Debug))
  *
  * // Effect.runFork(program)
  * // timestamp=... level=DEBUG fiber=#0 message=message1
+ * ```
  *
  * @since 2.0.0
  * @category Logging
@@ -5030,6 +5209,7 @@ export const logFatal = effect.logFatal;
  * time-sensitive processes.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -5039,6 +5219,7 @@ export const logFatal = effect.logFatal;
  *
  * // Effect.runFork(program)
  * // timestamp=... level=INFO fiber=#0 message="The job is finished!" myspan=1011ms
+ * ```
  *
  * @since 2.0.0
  * @category Logging
@@ -5050,6 +5231,7 @@ export const withLogSpan = effect.withLogSpan;
  * to log messages, making them more informative and easier to trace.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -5060,6 +5242,7 @@ export const withLogSpan = effect.withLogSpan;
  * // Effect.runFork(program)
  * // timestamp=... level=INFO fiber=#0 message=message1 key=value
  * // timestamp=... level=INFO fiber=#0 message=message2 key=value
+ * ```
  *
  * @since 2.0.0
  * @category Logging
@@ -5072,6 +5255,7 @@ export const annotateLogs = effect.annotateLogs;
  * defined `Scope`, making it easier to manage context-specific logging.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -5086,6 +5270,7 @@ export const annotateLogs = effect.annotateLogs;
  * // timestamp=... level=INFO fiber=#0 message=message1 key=value
  * // timestamp=... level=INFO fiber=#0 message=message2 key=value
  * // timestamp=... level=INFO fiber=#0 message="no annotations again"
+ * ```
  *
  * @since 3.1.0
  * @category Logging
@@ -5121,6 +5306,7 @@ export const withUnhandledErrorLogLevel = core.withUnhandledErrorLogLevel;
  * @see {@link orDieWith} if you need to customize the error.
  *
  * @example
+ * ```ts
  * // Title: Propagating an Error as a Defect
  * import { Effect } from "effect"
  *
@@ -5137,6 +5323,7 @@ export const withUnhandledErrorLogLevel = core.withUnhandledErrorLogLevel;
  * // Output:
  * // (FiberFailure) Error: Cannot divide by zero
  * //   ...stack trace...
+ * ```
  *
  * @since 2.0.0
  * @category Converting Failures to Defects
@@ -5160,6 +5347,7 @@ export const orDie = core.orDie;
  * @see {@link orDie} if you don't need to customize the error.
  *
  * @example
+ * ```ts
  * // Title: Customizing Defect
  * import { Effect } from "effect"
  *
@@ -5179,6 +5367,7 @@ export const orDie = core.orDie;
  * // Output:
  * // (FiberFailure) Error: defect: Cannot divide by zero
  * //   ...stack trace...
+ * ```
  *
  * @since 2.0.0
  * @category Converting Failures to Defects
@@ -5195,6 +5384,7 @@ export const orDieWith = core.orDieWith;
  * @see {@link catchAll} if you need to access the error in the fallback effect.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const success = Effect.succeed("success")
@@ -5210,6 +5400,7 @@ export const orDieWith = core.orDieWith;
  * const program2 = Effect.orElse(failure, () => fallback)
  * console.log(Effect.runSync(program2))
  * // Output: "fallback"
+ * ```
  *
  * @since 2.0.0
  * @category Fallback
@@ -5228,6 +5419,7 @@ export const orElse = core.orElse;
  * @see {@link mapError} if you need to access the error to transform it.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const validate = (age: number): Effect.Effect<number, string> => {
@@ -5249,6 +5441,7 @@ export const orElse = core.orElse;
  * //   _tag: 'Failure',
  * //   cause: { _id: 'Cause', _tag: 'Fail', failure: 'invalid age' }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Fallback
@@ -5272,6 +5465,7 @@ export const orElseFail = effect.orElseFail;
  * already succeeds, it will remain unchanged.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const validate = (age: number): Effect.Effect<number, string> => {
@@ -5289,6 +5483,7 @@ export const orElseFail = effect.orElseFail;
  * console.log(Effect.runSyncExit(program))
  * // Output:
  * // { _id: 'Exit', _tag: 'Success', value: 18 }
+ * ```
  *
  * @since 2.0.0
  * @category Fallback
@@ -5312,6 +5507,7 @@ export const orElseSucceed = effect.orElseSucceed;
  * error.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * interface Config {
@@ -5358,6 +5554,7 @@ export const orElseSucceed = effect.orElseSucceed;
  * // Unavailable config for node2
  * // Config for node3 found
  * // { host: 'node3.example.com', port: 8080, apiKey: '12345-abcde' }
+ * ```
  *
  * @since 2.0.0
  * @category Fallback
@@ -5489,6 +5686,7 @@ export const unsafeMakeLatch = circular.unsafeMakeLatch;
  * @category latch
  * @since 3.8.0
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * Effect.gen(function*() {
@@ -5505,6 +5703,7 @@ export const unsafeMakeLatch = circular.unsafeMakeLatch;
  *   yield* latch.open
  *   yield* fiber.await
  * })
+ * ```
  */
 export const makeLatch = circular.makeLatch;
 /**
@@ -5521,6 +5720,7 @@ export const makeLatch = circular.makeLatch;
  * `runFork` is a good default choice.
  *
  * @example
+ * ```ts
  * // Title: Running an Effect in the Background
  * import { Effect, Console, Schedule, Fiber } from "effect"
  *
@@ -5538,6 +5738,7 @@ export const makeLatch = circular.makeLatch;
  * setTimeout(() => {
  *   Effect.runFork(Fiber.interrupt(fiber))
  * }, 500)
+ * ```
  *
  * @since 2.0.0
  * @category Running Effects
@@ -5563,11 +5764,13 @@ export const runCallback = _runtime.unsafeRunEffect;
  * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
  *
  * @example
+ * ```ts
  * // Title: Running a Successful Effect as a Promise
  * import { Effect } from "effect"
  *
  * Effect.runPromise(Effect.succeed(1)).then(console.log)
  * // Output: 1
+ * ```
  *
  * @example
  * //Example: Handling a Failing Effect as a Rejected Promise
@@ -5598,6 +5801,7 @@ export const runPromise = _runtime.unsafeRunPromiseEffect;
  *   a `Cause` type.
  *
  * @example
+ * ```ts
  * // Title: Handling Results as Exit
  * import { Effect } from "effect"
  *
@@ -5622,6 +5826,7 @@ export const runPromise = _runtime.unsafeRunPromiseEffect;
  * //     failure: "my error"
  * //   }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Running Effects
@@ -5643,6 +5848,7 @@ export const runPromiseExit = _runtime.unsafeRunPromiseExitEffect;
  * throwing an error.
  *
  * @example
+ * ```ts
  * // Title: Synchronous Logging
  * import { Effect } from "effect"
  *
@@ -5656,6 +5862,7 @@ export const runPromiseExit = _runtime.unsafeRunPromiseExitEffect;
  *
  * console.log(result)
  * // Output: 1
+ * ```
  *
  * @example
  * // Title: Incorrect Usage with Failing or Async Effects
@@ -5704,6 +5911,7 @@ export const runSync = _runtime.unsafeRunSyncEffect;
  * resolved synchronously.
  *
  * @example
+ * ```ts
  * // Title: Handling Results as Exit
  * import { Effect } from "effect"
  *
@@ -5726,6 +5934,7 @@ export const runSync = _runtime.unsafeRunSyncEffect;
  * //     failure: "my error"
  * //   }
  * // }
+ * ```
  *
  * @example
  * // Title: Asynchronous Operation Resulting in Die
@@ -5766,6 +5975,7 @@ export const runSyncExit = _runtime.unsafeRunSyncExitEffect;
  * @see {@link zip} for a version that stops at the first error.
  *
  * @example
+ * ```ts
  * import { Effect, Console } from "effect"
  *
  * const task1 = Console.log("task1").pipe(Effect.as(1))
@@ -5793,6 +6003,7 @@ export const runSyncExit = _runtime.unsafeRunSyncExitEffect;
  * //     right: { _id: 'Cause', _tag: 'Fail', failure: 'Oh no!' }
  * //   }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Error Accumulation
@@ -5821,6 +6032,7 @@ export const validateWith = fiberRuntime.validateWith;
  * @see {@link validate} for a version that accumulates errors.
  *
  * @example
+ * ```ts
  * // Title: Combining Two Effects Sequentially
  * import { Effect } from "effect"
  *
@@ -5844,6 +6056,7 @@ export const validateWith = fiberRuntime.validateWith;
  * // timestamp=... level=INFO fiber=#0 message="task1 done"
  * // timestamp=... level=INFO fiber=#0 message="task2 done"
  * // [ 1, 'hello' ]
+ * ```
  *
  * @example
  * // Title: Combining Two Effects Concurrently
@@ -5889,6 +6102,7 @@ export const zip = fiberRuntime.zipOptions;
  * @see {@link zipRight} for a version that returns the result of the second effect.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const task1 = Effect.succeed(1).pipe(
@@ -5907,6 +6121,7 @@ export const zip = fiberRuntime.zipOptions;
  * // timestamp=... level=INFO fiber=#0 message="task1 done"
  * // timestamp=... level=INFO fiber=#0 message="task2 done"
  * // 1
+ * ```
  *
  * @since 2.0.0
  * @category Zipping
@@ -5930,6 +6145,7 @@ export const zipLeft = fiberRuntime.zipLeftOptions;
  * @see {@link zipLeft} for a version that returns the result of the first effect.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const task1 = Effect.succeed(1).pipe(
@@ -5948,6 +6164,7 @@ export const zipLeft = fiberRuntime.zipLeftOptions;
  * // timestamp=... level=INFO fiber=#0 message="task1 done"
  * // timestamp=... level=INFO fiber=#0 message="task2 done"
  * // hello
+ * ```
  *
  * @since 2.0.0
  * @category Zipping
@@ -5969,6 +6186,7 @@ export const zipRight = fiberRuntime.zipRightOptions;
  * use the `{ concurrent: true }` option.
  *
  * @example
+ * ```ts
  * // Title: Combining Effects with a Custom Function
  * import { Effect } from "effect"
  *
@@ -5993,6 +6211,7 @@ export const zipRight = fiberRuntime.zipRightOptions;
  * // timestamp=... level=INFO fiber=#3 message="task1 done"
  * // timestamp=... level=INFO fiber=#2 message="task2 done"
  * // 6
+ * ```
  *
  * @since 2.0.0
  * @category Zipping
@@ -6069,6 +6288,7 @@ export const withTracerScoped = fiberRuntime.withTracerScoped;
  * @since 2.0.0
  * @category Tracing
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * Effect.succeed(42).pipe(
@@ -6076,6 +6296,7 @@ export const withTracerScoped = fiberRuntime.withTracerScoped;
  *   // the span will not be registered with the tracer
  *   Effect.withTracerEnabled(false)
  * )
+ * ```
  */
 export const withTracerEnabled = core.withTracerEnabled;
 /**
@@ -6166,6 +6387,7 @@ export const withSpan = effect.withSpan;
  * @since 3.2.0
  * @category Tracing
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * const getTodo = Effect.functionWithSpan({
@@ -6175,6 +6397,7 @@ export const withSpan = effect.withSpan;
  *     attributes: { id }
  *   })
  * })
+ * ```
  */
 export const functionWithSpan = effect.functionWithSpan;
 /**
@@ -6205,6 +6428,7 @@ export const withParentSpan = effect.withParentSpan;
  * value.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, NoSuchElementException, never>
@@ -6230,6 +6454,7 @@ export const withParentSpan = effect.withParentSpan;
  * //     failure: { _tag: 'NoSuchElementException' }
  * //   }
  * // }
+ * ```
  *
  * @since 2.0.0
  * @category Optional Wrapping
@@ -6247,6 +6472,7 @@ export const fromNullable = effect.fromNullable;
  * unchanged.
  *
  * @example
+ * ```ts
  * import { Effect } from "effect"
  *
  * //      ┌─── Effect<number, NoSuchElementException, never>
@@ -6270,6 +6496,7 @@ export const fromNullable = effect.fromNullable;
  *
  * Effect.runPromise(option2).then(console.log)
  * // Output: { _tag: 'None' }
+ * ```
  *
  * @since 2.0.0
  * @category Optional Wrapping
@@ -6303,6 +6530,7 @@ const makeTagProxy = TagClass => {
 };
 /**
  * @example
+ * ```ts
  * import { Effect, Layer } from "effect"
  *
  * class MapTag extends Effect.Tag("MapTag")<MapTag, Map<string, string>>() {
@@ -6311,6 +6539,7 @@ const makeTagProxy = TagClass => {
  *    Effect.sync(() => new Map())
  *  )
  * }
+ * ```
  *
  * @since 2.0.0
  * @category Context
@@ -6337,6 +6566,7 @@ export const Tag = id => () => {
 };
 /**
  * @example
+ * ```ts
  * import { Effect } from 'effect';
  *
  * class Prefix extends Effect.Service<Prefix>()("Prefix", {
@@ -6356,6 +6586,7 @@ export const Tag = id => () => {
  *  }),
  *  dependencies: [Prefix.Default]
  * }) {}
+ * ```
  *
  * @since 3.9.0
  * @category Context
@@ -6445,4 +6676,70 @@ export const Service = function () {
     return proxy === true ? makeTagProxy(TagClass) : TagClass;
   };
 };
+/**
+ * Creates a function that returns an Effect which is automatically traced with a span pointing to the call site.
+ *
+ * The function can be created both using a generator function that can yield effects or using a normal function.
+ *
+ * @since 3.11.0
+ * @category function
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const logExample = Effect.fn("logExample")(
+ *   function*<N extends number>(n: N) {
+ *     yield* Effect.annotateCurrentSpan("n", n)
+ *     yield* Effect.logInfo(`got: ${n}`)
+ *     yield* Effect.fail(new Error())
+ *   },
+ *   Effect.delay("1 second")
+ * )
+ *
+ * Effect.runFork(
+ *   // this location is printed on the stack trace of the following `Effect.logError`
+ *   logExample(100).pipe(
+ *     Effect.catchAllCause(Effect.logError)
+ *   )
+ * )
+ */
+export const fn = (name, options) => (body, ...pipeables) => {
+  return function (...args) {
+    const limit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 2;
+    const error = new Error();
+    Error.stackTraceLimit = limit;
+    let cache = false;
+    const captureStackTrace = () => {
+      if (cache !== false) {
+        return cache;
+      }
+      if (error.stack) {
+        const stack = error.stack.trim().split("\n");
+        cache = stack.slice(2).join("\n").trim();
+        return cache;
+      }
+    };
+    let effect;
+    let fnError = undefined;
+    try {
+      effect = isGeneratorFunction(body) ? gen(() => internalCall(() => body.apply(this, args))) : body.apply(this, args);
+    } catch (error) {
+      fnError = error;
+      effect = die(error);
+    }
+    try {
+      for (const x of pipeables) {
+        effect = x(effect);
+      }
+    } catch (error) {
+      effect = fnError ? failCause(internalCause.sequential(internalCause.die(fnError), internalCause.die(error))) : die(error);
+    }
+    const opts = options && "captureStackTrace" in options ? options : {
+      captureStackTrace,
+      ...options
+    };
+    return withSpan(effect, name, opts);
+  };
+};
 //# sourceMappingURL=Effect.js.map