effect 4.0.0-beta.4 → 4.0.0-beta.41

package/dist/Effect.js

@@ -35,7 +35,7 @@ export class YieldableClass {
  * @since 2.0.0
  * @category Guards
  */
-export const isEffect = u => typeof u === "object" && u !== null && TypeId in u;
+export const isEffect = core.isEffect;
 /**
  * Combines multiple effects into one, returning results based on the input
  * structure.
@@ -181,7 +181,6 @@ export const isEffect = u => typeof u === "object" && u !== null && TypeId in u;
  * ```
  *
  * @see {@link forEach} for iterating over elements and applying an effect.
- * @see {@link allWith} for a data-last version of this function.
  *
  * @since 2.0.0
  * @category Collecting
@@ -215,6 +214,72 @@ export const all = internal.all;
  * @category Collecting
  */
 export const partition = internal.partition;
+/**
+ * Applies an effectful function to each element and accumulates all failures.
+ *
+ * This function always evaluates every element. If at least one effect fails,
+ * all failures are returned as a non-empty array and successes are discarded.
+ * If all effects succeed, it returns all collected successes.
+ *
+ * Use `discard: true` to ignore successful values while still validating all
+ * elements.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.validate([0, 1, 2, 3], (n) =>
+ *   n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
+ * )
+ *
+ * Effect.runPromiseExit(program).then(console.log)
+ * // {
+ * //   _id: 'Exit',
+ * //   _tag: 'Failure',
+ * //   cause: {
+ * //     _id: 'Cause',
+ * //     reasons: [
+ * //       { _id: 'Reason', _tag: 'Fail', error: '0 is even' },
+ * //       { _id: 'Reason', _tag: 'Fail', error: '2 is even' }
+ * //     ]
+ * //   }
+ * // }
+ * ```
+ *
+ * @since 4.0.0
+ * @category Error Accumulation
+ */
+export const validate = internal.validate;
+/**
+ * Returns the first element that satisfies an effectful predicate.
+ *
+ * The predicate receives the element and its index. Evaluation short-circuits
+ * as soon as an element matches.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.findFirst([1, 2, 3, 4], (n) => Effect.succeed(n > 2))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // { _id: 'Option', _tag: 'Some', value: 3 }
+ * ```
+ *
+ * @since 2.0.0
+ * @category Collecting
+ */
+export const findFirst = internal.findFirst;
+/**
+ * Returns the first value that passes an effectful `FilterEffect`.
+ *
+ * The filter receives the element and index. Evaluation short-circuits on the
+ * first `Result.succeed` and returns the transformed value in `Option.some`.
+ *
+ * @since 4.0.0
+ * @category Collecting
+ */
+export const findFirstFilter = internal.findFirstFilter;
 /**
  * Executes an effectful operation for each element in an `Iterable`.
  *
@@ -409,16 +474,18 @@ export const promise = internal.promise;
  *
  * @example Custom Error Handling
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class TodoFetchError extends Data.TaggedError("TodoFetchError")<{ readonly cause: unknown }> {}
  *
  * const getTodo = (id: number) =>
  *   Effect.tryPromise({
  *     try: () => fetch(`https://jsonplaceholder.typicode.com/todos/${id}`),
  *     // remap the error
- *     catch: (unknown) => new Error(`something went wrong ${unknown}`)
+ *     catch: (cause) => new TodoFetchError({ cause })
  *   })
  *
- * //      ┌─── Effect<Response, Error, never>
+ * //      ┌─── Effect<Response, TodoFetchError, never>
  * //      ▼
  * const program = getTodo(1)
  * ```
@@ -645,8 +712,13 @@ undefined_ as undefined };
  *
  * **When to Use**
  *
- * Use `Effect.async` when dealing with APIs that use callback-style instead of
+ * Use `Effect.callback` when dealing with APIs that use callback-style instead of
  * `async/await` or `Promise`.
+ * * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `Effect.async`
  *
  * @example
  * ```ts
@@ -690,6 +762,51 @@ export const callback = internal.callback;
  * @category Creating Effects
  */
 export const never = internal.never;
+/**
+ * An `Effect` containing an empty record `{}`, used as the starting point for
+ * do notation chains.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { pipe } from "effect/Function"
+ *
+ * const program = pipe(
+ *   Effect.Do,
+ *   Effect.bind("x", () => Effect.succeed(2)),
+ *   Effect.bind("y", ({ x }) => Effect.succeed(x + 1)),
+ *   Effect.let("sum", ({ x, y }) => x + y)
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+export const Do = internal.Do;
+/**
+ * Gives a name to the success value of an `Effect`, creating a single-key
+ * record used in do notation pipelines.
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+export const bindTo = internal.bindTo;
+const let_ = internal.let;
+export {
+/**
+ * Adds a computed plain value to the do notation record.
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+let_ as let };
+/**
+ * Adds an `Effect` value to the do notation record under a given name.
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+export const bind = internal.bind;
 /**
  * Provides a way to write effectful code using generator functions, simplifying
  * control flow and error handling.
@@ -707,16 +824,18 @@ export const never = internal.never;
  *
  * @example
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
  *
  * const addServiceCharge = (amount: number) => amount + 1
  *
  * const applyDiscount = (
  *   total: number,
  *   discountRate: number
- * ): Effect.Effect<number, Error> =>
+ * ): Effect.Effect<number, DiscountRateError> =>
  *   discountRate === 0
- *     ? Effect.fail(new Error("Discount rate cannot be zero"))
+ *     ? Effect.fail(new DiscountRateError())
  *     : Effect.succeed(total - (total * discountRate) / 100)
  *
  * const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
@@ -753,12 +872,14 @@ export const gen = internal.gen;
  * @example
  * ```ts
  * // Title: Creating a Failed Effect
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
  *
- * //      ┌─── Effect<never, Error, never>
+ * //      ┌─── Effect<never, OperationFailedError, never>
  * //      ▼
  * const failure = Effect.fail(
- *   new Error("Operation failed due to network error")
+ *   new OperationFailedError()
  * )
  * ```
  *
@@ -774,9 +895,11 @@ export const fail = internal.fail;
  *
  * @example
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class ProgramError extends Data.TaggedError("ProgramError")<{ readonly failedAt: Date }> {}
  *
- * const program = Effect.failSync(() => new Error("Something went wrong"))
+ * const program = Effect.failSync(() => new ProgramError({ failedAt: new Date() }))
  *
  * Effect.runPromiseExit(program).then(console.log)
  * // Output: { _id: 'Exit', _tag: 'Failure', cause: ... }
@@ -920,12 +1043,14 @@ export {
  *
  * @example Custom Error Handling
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class JsonParsingError extends Data.TaggedError("JsonParsingError")<{ readonly cause: unknown }> {}
  *
  * const parseJSON = (input: string) =>
  *   Effect.try({
  *     try: () => JSON.parse(input),
- *     catch: (error) => new Error(`JSON parsing failed: ${error}`)
+ *     catch: (cause) => new JsonParsingError({ cause })
  *   })
  *
  * Effect.runPromiseExit(parseJSON("invalid json")).then(console.log)
@@ -1050,17 +1175,17 @@ export const fromOption = internal.fromOption;
  * ```ts
  * import { Console, Effect } from "effect"
  *
- * const input: string | null = null
- *
- * const program = Effect.gen(function*() {
+ * const program = Effect.fn(function*(input: string | null) {
  *   const value = yield* Effect.fromNullishOr(input)
  *   yield* Console.log(value)
- * }).pipe(
+ * },
  *   Effect.catch(() => Console.log("missing"))
  * )
  *
- * Effect.runPromise(program)
+ * Effect.runPromise(program(null))
  * // Output: missing
+ * Effect.runPromise(program("hello"))
+ * // Output: hello
  * ```
  *
  * @since 4.0.0
@@ -1124,15 +1249,17 @@ export const fromYieldable = internal.fromYieldable;
  *
  * @example
  * ```ts
- * import { Effect, pipe } from "effect"
+ * import { Data, Effect, pipe } from "effect"
+ *
+ * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
  *
  * // Function to apply a discount safely to a transaction amount
  * const applyDiscount = (
  *   total: number,
  *   discountRate: number
- * ): Effect.Effect<number, Error> =>
+ * ): Effect.Effect<number, DiscountRateError> =>
  *   discountRate === 0
- *     ? Effect.fail(new Error("Discount rate cannot be zero"))
+ *     ? Effect.fail(new DiscountRateError())
  *     : Effect.succeed(total - (total * discountRate) / 100)
  *
  * // Simulated asynchronous task to fetch a transaction amount from database
@@ -1216,15 +1343,17 @@ export const flatten = internal.flatten;
  *
  * @example Applying a Discount Based on Fetched Amount
  * ```ts
- * import { Effect, pipe } from "effect"
+ * import { Data, Effect, pipe } from "effect"
+ *
+ * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
  *
  * // Function to apply a discount safely to a transaction amount
  * const applyDiscount = (
  *   total: number,
  *   discountRate: number
- * ): Effect.Effect<number, Error> =>
+ * ): Effect.Effect<number, DiscountRateError> =>
  *   discountRate === 0
- *     ? Effect.fail(new Error("Discount rate cannot be zero"))
+ *     ? Effect.fail(new DiscountRateError())
  *     : Effect.succeed(total - (total * discountRate) / 100)
  *
  * // Simulated asynchronous task to fetch a transaction amount from database
@@ -1281,16 +1410,18 @@ export const andThen = internal.andThen;
  * @example
  * ```ts
  * // Title: Logging a step in a pipeline
- * import { Effect, pipe } from "effect"
+ * import { Data, Effect, pipe } from "effect"
  * import { Console } from "effect"
  *
+ * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
+ *
  * // Function to apply a discount safely to a transaction amount
  * const applyDiscount = (
  *   total: number,
  *   discountRate: number
- * ): Effect.Effect<number, Error> =>
+ * ): Effect.Effect<number, DiscountRateError> =>
  *   discountRate === 0
- *     ? Effect.fail(new Error("Discount rate cannot be zero"))
+ *     ? Effect.fail(new DiscountRateError())
  *     : Effect.succeed(total - (total * discountRate) / 100)
  *
  * // Simulated asynchronous task to fetch a transaction amount from database
@@ -1697,12 +1828,12 @@ export {
  *
  * **Details**
  *
- * The `catchAll` function catches any errors that may occur during the
+ * The `catch` function catches any errors that may occur during the
  * execution of an effect and allows you to handle them by specifying a fallback
  * effect. This ensures that the program continues without failing by recovering
  * from errors using the provided fallback logic.
  *
- * **Note**: `catchAll` only handles recoverable errors. It will not recover
+ * **Note**: `catch` only handles recoverable errors. It will not recover
  * from unrecoverable defects.
  *
  * @see {@link catchCause} for a version that can recover from both recoverable and unrecoverable errors.
@@ -1767,7 +1898,8 @@ export const catchTag = internal.catchTag;
  * once. Instead of using {@link catchTag} multiple times, you can pass an
  * object where each key is an error type's `_tag`, and the value is the handler
  * for that specific error. This allows you to catch and recover from multiple
- * error types in a single call.
+ * error types in a single call. You can also provide a fallback handler for
+ * unhandled errors.
  *
  * The error type must have a readonly `_tag` field to use `catchTag`. This
  * field is used to identify and match errors.
@@ -1998,15 +2130,14 @@ export const catchCause = internal.catchCause;
  */
 export const catchDefect = internal.catchDefect;
 /**
- * Recovers from specific errors using a `Filter`, `Predicate`, or
- * `Refinement`.
+ * Recovers from specific errors using a `Predicate` or `Refinement`.
  *
  * **When to Use**
  *
- * `catchIf` lets you recover from errors that match a condition. Pass a
- * `Filter` for transformation, a `Refinement` for type narrowing, or a
- * `Predicate` for simple boolean matching. Non-matching errors re-fail with
- * the original cause. Defects and interrupts are not caught.
+ * `catchIf` lets you recover from errors that match a condition. Use a
+ * `Refinement` for type narrowing or a `Predicate` for simple boolean
+ * matching. Non-matching errors re-fail with the original cause. Defects and
+ * interrupts are not caught.
  *
  * **Previously Known As**
  *
@@ -2033,7 +2164,7 @@ export const catchDefect = internal.catchDefect;
  *
  * // With a Filter
  * const recovered2 = program.pipe(
- *   Effect.catchIf(
+ *   Effect.catchFilter(
  *     Filter.tagged("NotFound"),
  *     (error) => Effect.succeed(`missing:${error.id}`)
  *   )
@@ -2044,6 +2175,13 @@ export const catchDefect = internal.catchDefect;
  * @category Error Handling
  */
 export const catchIf = internal.catchIf;
+/**
+ * Recovers from specific errors using a `Filter`.
+ *
+ * @since 4.0.0
+ * @category Error Handling
+ */
+export const catchFilter = internal.catchFilter;
 /**
  * Catches `NoSuchElementError` failures and converts them to `Option.none`.
  *
@@ -2110,6 +2248,13 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
  * @category Error Handling
  */
 export const catchCauseIf = internal.catchCauseIf;
+/**
+ * Recovers from specific failures based on a `Filter`.
+ *
+ * @since 4.0.0
+ * @category Error Handling
+ */
+export const catchCauseFilter = internal.catchCauseFilter;
 /**
  * The `mapError` function is used to transform or modify the error
  * produced by an effect, without affecting its success value.
@@ -2125,17 +2270,19 @@ export const catchCauseIf = internal.catchCauseIf;
  *
  * @example
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
  *
  * //      ┌─── Effect<number, string, never>
  * //      ▼
  * const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))
  *
- * //      ┌─── Effect<number, Error, never>
+ * //      ┌─── Effect<number, TaskError, never>
  * //      ▼
  * const mapped = Effect.mapError(
  *   simulatedTask,
- *   (message) => new Error(message)
+ *   (message) => new TaskError({ message })
  * )
  * ```
  *
@@ -2155,16 +2302,18 @@ export const mapError = internal.mapError;
  *
  * @example
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
  *
  * //      ┌─── Effect<number, string, never>
  * //      ▼
  * const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))
  *
- * //      ┌─── Effect<boolean, Error, never>
+ * //      ┌─── Effect<boolean, TaskError, never>
  * //      ▼
  * const modified = Effect.mapBoth(simulatedTask, {
- *   onFailure: (message) => new Error(message),
+ *   onFailure: (message) => new TaskError({ message }),
  *   onSuccess: (n) => n > 0
  * })
  * ```
@@ -2194,11 +2343,13 @@ export const mapBoth = internal.mapBoth;
  * @example
  * ```ts
  * // Title: Propagating an Error as a Defect
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class DivideByZeroError extends Data.TaggedError("DivideByZeroError")<{}> {}
  *
  * const divide = (a: number, b: number) =>
  *   b === 0
- *     ? Effect.fail(new Error("Cannot divide by zero"))
+ *     ? Effect.fail(new DivideByZeroError())
  *     : Effect.succeed(a / b)
  *
  * //      ┌─── Effect<number, never, never>
@@ -2207,7 +2358,7 @@ export const mapBoth = internal.mapBoth;
  *
  * Effect.runPromise(program).catch(console.error)
  * // Output:
- * // (FiberFailure) Error: Cannot divide by zero
+ * // (FiberFailure) DivideByZeroError
  * //   ...stack trace...
  * ```
  *
@@ -2344,6 +2495,13 @@ export const tapCause = internal.tapCause;
  * @category Sequencing
  */
 export const tapCauseIf = internal.tapCauseIf;
+/**
+ * Conditionally executes a side effect based on the cause of a failed effect.
+ *
+ * @since 4.0.0
+ * @category Sequencing
+ */
+export const tapCauseFilter = internal.tapCauseFilter;
 /**
  * Inspect severe errors or defects (non-recoverable failures) in an effect.
  *
@@ -2412,7 +2570,7 @@ export const tapDefect = internal.tapDefect;
  *   attempts++
  *   yield* Console.log(`Attempt ${attempts}`)
  *   if (attempts < 3) {
- *     yield* Effect.fail("Not ready")
+ *     return yield* Effect.fail("Not ready")
  *   }
  *   return "Ready"
  * })
@@ -2454,13 +2612,15 @@ export const eventually = internal.eventually;
  *
  * @example
  * ```ts
- * import { Effect, Schedule } from "effect"
+ * import { Data, Effect, Schedule } from "effect"
+ *
+ * class AttemptError extends Data.TaggedError("AttemptError")<{ readonly attempt: number }> {}
  *
  * let attempt = 0
- * const task = Effect.callback<string, Error>((resume) => {
+ * const task = Effect.callback<string, AttemptError>((resume) => {
  *   attempt++
  *   if (attempt <= 2) {
- *     resume(Effect.fail(new Error(`Attempt ${attempt} failed`)))
+ *     resume(Effect.fail(new AttemptError({ attempt })))
  *   } else {
  *     resume(Effect.succeed("Success!"))
  *   }
@@ -2500,14 +2660,16 @@ export const retry = internalSchedule.retry;
  *
  * @example
  * ```ts
- * import { Console, Effect, Schedule } from "effect"
+ * import { Console, Data, Effect, Schedule } from "effect"
+ *
+ * class NetworkTimeoutError extends Data.TaggedError("NetworkTimeoutError")<{}> {}
  *
  * let attempt = 0
  * const networkRequest = Effect.gen(function*() {
  *   attempt++
  *   yield* Console.log(`Network attempt ${attempt}`)
  *   if (attempt < 3) {
- *     return yield* Effect.fail(new Error("Network timeout"))
+ *     return yield* Effect.fail(new NetworkTimeoutError())
  *   }
  *   return "Network data"
  * })
@@ -2579,7 +2741,8 @@ export const sandbox = internal.sandbox;
  * it succeeds or fails. This is useful when you only care about the side
  * effects of the effect and do not need to handle or process its outcome.
  *
- * Use the `log` option to emit the full {@link Cause} when the effect fails.
+ * Use the `log` option to emit the full {@link Cause} when the effect fails,
+ * and `message` to prepend a custom log message.
  *
  * @example
  * ```ts
@@ -2603,7 +2766,7 @@ export const sandbox = internal.sandbox;
  * const task = Effect.fail("Uh oh!")
  *
  * const program = task.pipe(Effect.ignore({ log: true }))
- * const programWarn = task.pipe(Effect.ignore({ log: "Warn" }))
+ * const programWarn = task.pipe(Effect.ignore({ log: "Warn", message: "Ignoring task failure" }))
  * ```
  *
  * **Previously Known As**
@@ -2619,7 +2782,8 @@ export const ignore = internal.ignore;
 /**
  * Ignores the effect's failure cause, including defects and interruptions.
  *
- * Use the `log` option to emit the full {@link Cause} when the effect fails.
+ * Use the `log` option to emit the full {@link Cause} when the effect fails,
+ * and `message` to prepend a custom log message.
  *
  * @example
  * ```ts
@@ -2628,7 +2792,7 @@ export const ignore = internal.ignore;
  * const task = Effect.fail("boom")
  *
  * const program = task.pipe(Effect.ignoreCause)
- * const programLog = task.pipe(Effect.ignoreCause({ log: true }))
+ * const programLog = task.pipe(Effect.ignoreCause({ log: true, message: "Ignoring failure cause" }))
  * ```
  *
  * @since 4.0.0
@@ -2651,7 +2815,10 @@ export const ignoreCause = internal.ignoreCause;
  *
  * const fetchUrl = Effect.gen(function*() {
  *   const endpoint = yield* Effect.service(Endpoint)
- *   return endpoint.url === "bad" ? yield* Effect.fail("Unavailable") : endpoint.url
+ *   if (endpoint.url === "bad") {
+ *     return yield* Effect.fail("Unavailable")
+ *   }
+ *   return endpoint.url
  * })
  *
  * const plan = ExecutionPlan.make(
@@ -2666,6 +2833,16 @@ export const ignoreCause = internal.ignoreCause;
  * @category Fallback
  */
 export const withExecutionPlan = internalExecutionPlan.withExecutionPlan;
+/**
+ * Runs an effect and reports any errors to the configured `ErrorReporter`s.
+ *
+ * If the `defectsOnly` option is set to `true`, only defects (unrecoverable
+ * errors) will be reported, while regular failures will be ignored.
+ *
+ * @since 4.0.0
+ * @category Error Handling
+ */
+export const withErrorReporting = internal.withErrorReporting;
 // -----------------------------------------------------------------------------
 // Fallback
 // -----------------------------------------------------------------------------
@@ -2830,7 +3007,7 @@ export const timeoutOption = internal.timeoutOption;
  * // Use cached data as fallback when timeout is reached
  * const program = Effect.timeoutOrElse(slowQuery, {
  *   duration: "2 seconds",
- *   onTimeout: () =>
+ *   orElse: () =>
  *     Effect.gen(function*() {
  *       yield* Console.log("Query timed out, using cached data")
  *       return "Cached result"
@@ -3042,12 +3219,12 @@ export const raceFirst = internal.raceFirst;
 // Filtering
 // -----------------------------------------------------------------------------
 /**
- * Filters elements of an iterable using a predicate, refinement, effectful
- * predicate, or `Filter.FilterEffect`.
+ * Filters elements of an iterable using a predicate, refinement, or effectful
+ * predicate.
  *
  * @example
  * ```ts
- * import { Effect, Filter, Result } from "effect"
+ * import { Effect } from "effect"
  *
  * // Sync predicate
  * const evens = Effect.filter([1, 2, 3, 4], (n) => n % 2 === 0)
@@ -3055,16 +3232,27 @@ export const raceFirst = internal.raceFirst;
  * // Effectful predicate
  * const checked = Effect.filter([1, 2, 3], (n) => Effect.succeed(n > 1))
  *
- * // FilterEffect
- * const mapped = Effect.filter([1, 2, 3, 4], (n) =>
- *   Effect.succeed(n % 2 === 0 ? Result.succeed(n * 2) : Result.fail(n))
- * )
+ * // Use Effect.filterMapEffect for effectful Filter.Filter callbacks
  * ```
  *
  * @since 2.0.0
  * @category Filtering
  */
 export const filter = internal.filter;
+/**
+ * Filters and maps elements of an iterable with a `Filter`.
+ *
+ * @since 4.0.0
+ * @category Filtering
+ */
+export const filterMap = internal.filterMap;
+/**
+ * Effectfully filters and maps elements of an iterable with a `FilterEffect`.
+ *
+ * @since 4.0.0
+ * @category Filtering
+ */
+export const filterMapEffect = internal.filterMapEffect;
 /**
  * Filters an effect, providing an alternative effect if the predicate fails.
  *
@@ -3096,6 +3284,13 @@ export const filter = internal.filter;
  * @category Filtering
  */
 export const filterOrElse = internal.filterOrElse;
+/**
+ * Filters an effect with a `Filter`, providing an alternative effect on failure.
+ *
+ * @since 4.0.0
+ * @category Filtering
+ */
+export const filterMapOrElse = internal.filterMapOrElse;
 /**
  * Filters an effect, failing with a custom error if the predicate fails.
  *
@@ -3126,6 +3321,13 @@ export const filterOrElse = internal.filterOrElse;
  * @category Filtering
  */
 export const filterOrFail = internal.filterOrFail;
+/**
+ * Filters an effect with a `Filter`, failing when the filter fails.
+ *
+ * @since 4.0.0
+ * @category Filtering
+ */
+export const filterMapOrFail = internal.filterMapOrFail;
 // -----------------------------------------------------------------------------
 // Conditional Operators
 // -----------------------------------------------------------------------------
@@ -3192,9 +3394,11 @@ export const when = internal.when;
  * @example
  * ```ts
  * // Title: Handling Both Success and Failure Cases
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
  *
- * const success: Effect.Effect<number, Error> = Effect.succeed(42)
+ * class ExampleError extends Data.TaggedError("ExampleError")<{ readonly message: string }> {}
+ *
+ * const success: Effect.Effect<number, ExampleError> = Effect.succeed(42)
  *
  * const program1 = Effect.match(success, {
  *   onFailure: (error) => `failure: ${error.message}`,
@@ -3205,8 +3409,8 @@ export const when = internal.when;
  * Effect.runPromise(program1).then(console.log)
  * // Output: "success: 42"
  *
- * const failure: Effect.Effect<number, Error> = Effect.fail(
- *   new Error("Uh oh!")
+ * const failure: Effect.Effect<number, ExampleError> = Effect.fail(
+ *   new ExampleError({ message: "Uh oh!" })
  * )
  *
  * const program2 = Effect.match(failure, {
@@ -3350,9 +3554,11 @@ export const matchCauseEffectEager = internal.matchCauseEffectEager;
  *
  * @example
  * ```ts
- * import { Cause, Console, Effect, Result } from "effect"
+ * import { Cause, Console, Data, Effect, Result } from "effect"
+ *
+ * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
  *
- * const task = Effect.fail(new Error("Task failed"))
+ * const task = Effect.fail(new TaskError({ message: "Task failed" }))
  *
  * const program = Effect.matchCauseEffect(task, {
  *   onFailure: (cause) =>
@@ -3408,11 +3614,13 @@ export const matchCauseEffect = internal.matchCauseEffect;
  * @example
  * ```ts
  * // Title: Handling Both Success and Failure Cases with Side Effects
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class ExampleError extends Data.TaggedError("ExampleError")<{ readonly message: string }> {}
  *
- * const success: Effect.Effect<number, Error> = Effect.succeed(42)
- * const failure: Effect.Effect<number, Error> = Effect.fail(
- *   new Error("Uh oh!")
+ * const success: Effect.Effect<number, ExampleError> = Effect.succeed(42)
+ * const failure: Effect.Effect<number, ExampleError> = Effect.fail(
+ *   new ExampleError({ message: "Uh oh!" })
  * )
  *
  * const program1 = Effect.matchEffect(success, {
@@ -3605,7 +3813,7 @@ export const servicesWith = internal.servicesWith;
  * const Database = ServiceMap.Service<Database>("Database")
  *
  * const DatabaseLive = Layer.succeed(Database)({
- *   query: (sql: string) => Effect.succeed(`Result for: ${sql}`)
+ *   query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result for: ${sql}`))
  * })
  *
  * const program = Effect.gen(function*() {
@@ -4245,9 +4453,11 @@ export const ensuring = internal.ensuring;
  *
  * @example
  * ```ts
- * import { Cause, Console, Effect } from "effect"
+ * import { Cause, Data, Console, Effect } from "effect"
+ *
+ * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
  *
- * const task = Effect.fail(new Error("Something went wrong"))
+ * const task = Effect.fail(new TaskError({ message: "Something went wrong" }))
  *
  * const program = Effect.onError(
  *   task,
@@ -4256,8 +4466,8 @@ export const ensuring = internal.ensuring;
  *
  * Effect.runPromise(program).catch(console.error)
  * // Output:
- * // Cleanup on error: Error: Something went wrong
- * // Error: Something went wrong
+ * // Cleanup on error: TaskError: Something went wrong
+ * // TaskError: Something went wrong
  * ```
  *
  * @since 2.0.0
@@ -4266,7 +4476,7 @@ export const ensuring = internal.ensuring;
 export const onError = internal.onError;
 /**
  * Runs the finalizer only when this effect fails and the `Cause` matches the
- * filter, passing the filtered failure and the original cause.
+ * provided predicate.
  *
  * @example
  * ```ts
@@ -4288,6 +4498,13 @@ export const onError = internal.onError;
  * @category Resource Management & Finalization
  */
 export const onErrorIf = internal.onErrorIf;
+/**
+ * Runs the finalizer only when this effect fails and the cause matches the provided `Filter`.
+ *
+ * @since 4.0.0
+ * @category Resource Management & Finalization
+ */
+export const onErrorFilter = internal.onErrorFilter;
 /**
  * The low level primitive that powers `onExit`.
  * function is used to run a finalizer when the effect exits, regardless of the
@@ -4325,20 +4542,20 @@ export const onExitPrimitive = internal.onExitPrimitive;
  */
 export const onExit = internal.onExit;
 /**
- * Runs the cleanup effect only when the `Exit` passes the provided filter.
- *
- * The cleanup is skipped when the filter returns `Filter.fail`.
+ * Runs the cleanup effect only when the `Exit` satisfies the provided
+ * predicate.
  *
  * @example
  * ```ts
- * import { Console, Effect, Exit, Filter } from "effect"
- *
- * const exitFilter = Filter.fromPredicate(Exit.isSuccess<number, never>)
+ * import { Console, Effect, Exit } from "effect"
  *
  * const program = Effect.onExitIf(
  *   Effect.succeed(42),
- *   exitFilter,
- *   (success) => Console.log(`Succeeded with: ${success.value}`)
+ *   Exit.isSuccess,
+ *   (exit) =>
+ *     Exit.isSuccess(exit)
+ *       ? Console.log(`Succeeded with: ${exit.value}`)
+ *       : Effect.void
  * )
  * ```
  *
@@ -4346,6 +4563,13 @@ export const onExit = internal.onExit;
  * @category Resource Management & Finalization
  */
 export const onExitIf = internal.onExitIf;
+/**
+ * Runs the cleanup effect only when the `Exit` matches the provided `Filter`.
+ *
+ * @since 4.0.0
+ * @category Resource Management & Finalization
+ */
+export const onExitFilter = internal.onExitFilter;
 // -----------------------------------------------------------------------------
 // Caching
 // -----------------------------------------------------------------------------
@@ -4561,8 +4785,8 @@ export const cachedInvalidateWithTTL = internal.cachedInvalidateWithTTL;
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   yield* Effect.interrupt
- *   yield* Effect.succeed("This won't execute")
+ *   return yield* Effect.interrupt
+ *   yield* Effect.succeed("This won't execute and is unreachable")
  * })
  *
  * Effect.runPromise(program).catch(console.error)
@@ -4702,124 +4926,6 @@ export const uninterruptibleMask = internal.uninterruptibleMask;
  * @category Interruption
  */
 export const interruptibleMask = internal.interruptibleMask;
-/**
- * Unsafely creates a new Semaphore.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const semaphore = Effect.makeSemaphoreUnsafe(3)
- *
- * const task = (id: number) =>
- *   semaphore.withPermits(1)(
- *     Effect.gen(function*() {
- *       yield* Effect.log(`Task ${id} started`)
- *       yield* Effect.sleep("1 second")
- *       yield* Effect.log(`Task ${id} completed`)
- *     })
- *   )
- *
- * // Only 3 tasks can run concurrently
- * const program = Effect.all([
- *   task(1),
- *   task(2),
- *   task(3),
- *   task(4),
- *   task(5)
- * ], { concurrency: "unbounded" })
- * ```
- *
- * @since 2.0.0
- * @category Semaphore
- */
-export const makeSemaphoreUnsafe = internal.makeSemaphoreUnsafe;
-/**
- * Creates a new Semaphore.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const semaphore = yield* Effect.makeSemaphore(2)
- *
- *   const task = (id: number) =>
- *     semaphore.withPermits(1)(
- *       Effect.gen(function*() {
- *         yield* Effect.log(`Task ${id} acquired permit`)
- *         yield* Effect.sleep("1 second")
- *         yield* Effect.log(`Task ${id} releasing permit`)
- *       })
- *     )
- *
- *   // Run 4 tasks, but only 2 can run concurrently
- *   yield* Effect.all([task(1), task(2), task(3), task(4)])
- * })
- * ```
- *
- * @since 2.0.0
- * @category Semaphore
- */
-export const makeSemaphore = internal.makeSemaphore;
-/**
- * Creates a new Latch.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const latch = Effect.makeLatchUnsafe(false)
- *
- * const waiter = Effect.gen(function*() {
- *   yield* Effect.log("Waiting for latch to open...")
- *   yield* latch.await
- *   yield* Effect.log("Latch opened! Continuing...")
- * })
- *
- * const opener = Effect.gen(function*() {
- *   yield* Effect.sleep("2 seconds")
- *   yield* Effect.log("Opening latch...")
- *   yield* latch.open
- * })
- *
- * const program = Effect.all([waiter, opener])
- * ```
- *
- * @category Latch
- * @since 3.8.0
- */
-export const makeLatchUnsafe = internal.makeLatchUnsafe;
-/**
- * Creates a new Latch.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const latch = yield* Effect.makeLatch(false)
- *
- *   const waiter = Effect.gen(function*() {
- *     yield* Effect.log("Waiting for latch to open...")
- *     yield* latch.await
- *     yield* Effect.log("Latch opened! Continuing...")
- *   })
- *
- *   const opener = Effect.gen(function*() {
- *     yield* Effect.sleep("2 seconds")
- *     yield* Effect.log("Opening latch...")
- *     yield* latch.open
- *   })
- *
- *   yield* Effect.all([waiter, opener])
- * })
- * ```
- *
- * @category Latch
- * @since 3.8.0
- */
-export const makeLatch = internal.makeLatch;
 /**
  * Repeats this effect forever (until the first error).
  *
@@ -4942,7 +5048,7 @@ export const repeat = internalSchedule.repeat;
  *   attempt++
  *   if (attempt <= 2) {
  *     yield* Console.log(`Attempt ${attempt} failed`)
- *     yield* Effect.fail(`Error ${attempt}`)
+ *     return yield* Effect.fail(`Error ${attempt}`)
  *   }
  *   yield* Console.log(`Attempt ${attempt} succeeded`)
  *   return "success"
@@ -5510,7 +5616,7 @@ export const withParentSpan = internal.withParentSpan;
  * )
  *
  * const program = Effect.gen(function*() {
- *   const name = yield* Effect.request(GetUser({ id: 1 }), Effect.succeed(resolver))
+ *   const name = yield* Effect.request(GetUser({ id: 1 }), resolver)
  *   yield* Console.log(name)
  * })
  * ```
@@ -6568,7 +6674,7 @@ export const withLogger = /*#__PURE__*/dual(2, (effect, logger) => internal.upda
  * @since 2.0.0
  * @category Logging
  */
-export const annotateLogs = /*#__PURE__*/dual(args => core.isEffect(args[0]), (effect, ...args) => internal.updateService(effect, CurrentLogAnnotations, annotations => {
+export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect, ...args) => internal.updateService(effect, CurrentLogAnnotations, annotations => {
   const newAnnotations = {
     ...annotations
   };
@@ -6579,6 +6685,32 @@ export const annotateLogs = /*#__PURE__*/dual(args => core.isEffect(args[0]), (e
   }
   return newAnnotations;
 }));
+/**
+ * Adds log annotations to the current scope.
+ *
+ * This differs from `annotateLogs`, which only annotates a specific effect.
+ * `annotateLogsScoped` updates annotations for the entire current `Scope` and
+ * restores the previous annotations when the scope closes.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     yield* Effect.log("before")
+ *     yield* Effect.annotateLogsScoped({ requestId: "req-123" })
+ *     yield* Effect.log("inside scope")
+ *   })
+ * )
+ *
+ * Effect.runPromise(program)
+ * ```
+ *
+ * @since 4.0.0
+ * @category Logging
+ */
+export const annotateLogsScoped = internal.annotateLogsScoped;
 /**
  * Adds a span to each log line in this effect.
  *
@@ -6744,18 +6876,20 @@ export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self
  *
  * @example
  * ```ts
- * import { Effect, Metric } from "effect"
+ * import { Data, Effect, Metric } from "effect"
+ *
+ * class ConnectionFailedError extends Data.TaggedError("ConnectionFailedError")<{}> {}
  *
  * // Track error types using frequency metric
  * const errorTypeFrequency = Metric.frequency("error_types")
  *
- * const program = Effect.fail(new Error("Connection failed")).pipe(
- *   Effect.trackErrors(errorTypeFrequency, (error: Error) => error.name)
+ * const program = Effect.fail(new ConnectionFailedError()).pipe(
+ *   Effect.trackErrors(errorTypeFrequency, (error: ConnectionFailedError) => error._tag)
  * )
  *
  * Effect.runPromiseExit(program).then(() =>
  *   Effect.runPromise(Metric.value(errorTypeFrequency)).then(console.log)
- *   // Output: { occurrences: Map(1) { "Error" => 1 } }
+ *   // Output: { occurrences: Map(1) { "ConnectionFailedError" => 1 } }
  * )
  * ```
  *
@@ -6866,7 +7000,7 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
   const startTime = clock.currentTimeNanosUnsafe();
   return onExit(self, () => {
     const endTime = clock.currentTimeNanosUnsafe();
-    const duration = Duration.subtract(Duration.fromDurationInputUnsafe(endTime), Duration.fromDurationInputUnsafe(startTime));
+    const duration = Duration.subtract(Duration.fromInputUnsafe(endTime), Duration.fromInputUnsafe(startTime));
     const input = f === undefined ? duration : internalCall(() => f(duration));
     return Metric.update(metric, input);
   });
@@ -6897,125 +7031,63 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  */
 export class Transaction extends /*#__PURE__*/ServiceMap.Service()("effect/Effect/Transaction") {}
 /**
- * Defines a transaction. Transactions are "all or nothing" with respect to changes made to
- * transactional values (i.e. TxRef) that occur within the transaction body.
+ * Accesses the current transaction state within an active transaction.
  *
- * In Effect transactions are optimistic with retry, that means transactions are retried when:
- *
- * - the body of the transaction explicitely calls to `Effect.retryTransaction` and any of the
- *   accessed transactional values changes.
- *
- * - any of the accessed transactional values change during the execution of the transaction
- *   due to a different transaction committing before the current.
- *
- * - parent transaction retry, if you have a transaction within another transaction and
- *   the parent retries the child will also retry together with the parent.
+ * This function requires `Transaction` in the context and does NOT create or strip
+ * transaction boundaries. Use it to interact with the transaction journal (e.g. in
+ * `TxRef` internals). To define a transaction boundary, use {@link transaction}.
  *
  * @example
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   const ref1 = yield* TxRef.make(0)
- *   const ref2 = yield* TxRef.make(0)
- *
- *   // All operations within atomic block succeed or fail together
- *   yield* Effect.atomic(Effect.gen(function*() {
- *     yield* TxRef.set(ref1, 10)
- *     yield* TxRef.set(ref2, 20)
- *     const sum = (yield* TxRef.get(ref1)) + (yield* TxRef.get(ref2))
- *     console.log(`Transaction sum: ${sum}`)
- *   }))
- *
- *   console.log(`Final ref1: ${yield* TxRef.get(ref1)}`) // 10
- *   console.log(`Final ref2: ${yield* TxRef.get(ref2)}`) // 20
- * })
- * ```
- *
- * @since 4.0.0
- * @category Transactions
- */
-export const atomic = effect => atomicWith(() => effect);
-/**
- * Executes a function within a transaction context, providing access to the transaction state.
- *
- * @example
- * ```ts
- * import { Effect, TxRef } from "effect"
- *
- * const program = Effect.atomicWith((txState) =>
- *   Effect.gen(function*() {
- *     const ref = yield* TxRef.make(0)
- *
- *     // Access transaction state for debugging
- *     console.log(`Journal size: ${txState.journal.size}`)
- *     console.log(`Retry flag: ${txState.retry}`)
+ *   const ref = yield* Effect.transaction(TxRef.make(0))
  *
+ *   yield* Effect.transaction(Effect.gen(function*() {
  *     yield* TxRef.set(ref, 42)
  *     return yield* TxRef.get(ref)
- *   })
- * )
- *
- * Effect.runPromise(program).then(console.log) // 42
+ *   }))
+ * })
  * ```
  *
  * @since 4.0.0
  * @category Transactions
  */
-export const atomicWith = f => withFiber(fiber => {
-  // Check if transaction already exists and reuse it (composing behavior)
-  if (fiber.services.mapUnsafe.has(Transaction.key)) {
-    return internalCall(() => f(ServiceMap.getUnsafe(fiber.services, Transaction)));
-  }
-  // No existing transaction, create isolated one using transactionWith
-  return transactionWith(f);
-});
+export const withTxState = f => flatMap(Transaction.asEffect(), state => internalCall(() => f(state)));
 /**
- * Creates an isolated transaction that never composes with parent transactions.
+ * Defines a transaction boundary. Transactions are "all or nothing" with respect to changes
+ * made to transactional values (i.e. TxRef) that occur within the transaction body.
  *
- * **Details**
+ * In Effect transactions are optimistic with retry, that means transactions are retried when:
  *
- * Unlike `Effect.atomic`, which composes with parent transactions when nested,
- * `Effect.transaction` always creates a new isolated transaction boundary.
- * This ensures complete isolation between different transaction scopes.
+ * - the body of the transaction explicitely calls to `Effect.retryTransaction` and any of the
+ *   accessed transactional values changes.
  *
- * **Key Differences from Effect.atomic:**
- * - Always creates a new transaction, even when called within another transaction
- * - Parent transaction failures don't affect isolated transactions
- * - Isolated transaction failures don't affect parent transactions
- * - Each transaction has its own journal and retry logic
+ * - any of the accessed transactional values change during the execution of the transaction
+ *   due to a different transaction committing before the current.
  *
- * **When to Use:**
- * - When you need guaranteed isolation between transaction scopes
- * - For implementing independent operations that shouldn't be affected by outer transactions
- * - When building transaction-based systems where isolation is critical
+ * Each call to `transaction` always creates a new isolated transaction boundary with its own
+ * journal and retry logic.
  *
  * @example
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   const ref1 = yield* TxRef.make(0)
- *   const ref2 = yield* TxRef.make(100)
- *
- *   // Nested atomic transaction - ref1 will be part of outer transaction
- *   yield* Effect.atomic(Effect.gen(function*() {
- *     yield* TxRef.set(ref1, 10)
- *
- *     // This atomic operation composes with the parent
- *     yield* Effect.atomic(Effect.gen(function*() {
- *       yield* TxRef.set(ref1, 20) // Part of same transaction
- *     }))
- *   }))
+ *   const ref1 = yield* Effect.transaction(TxRef.make(0))
+ *   const ref2 = yield* Effect.transaction(TxRef.make(0))
  *
- *   // Isolated transaction - ref2 will be in its own transaction
+ *   // All operations within transaction block succeed or fail together
  *   yield* Effect.transaction(Effect.gen(function*() {
- *     yield* TxRef.set(ref2, 200)
+ *     yield* TxRef.set(ref1, 10)
+ *     yield* TxRef.set(ref2, 20)
+ *     const sum = (yield* TxRef.get(ref1)) + (yield* TxRef.get(ref2))
+ *     console.log(`Transaction sum: ${sum}`)
  *   }))
  *
- *   const val1 = yield* TxRef.get(ref1) // 20
- *   const val2 = yield* TxRef.get(ref2) // 200
- *   return { ref1: val1, ref2: val2 }
+ *   console.log(`Final ref1: ${yield* Effect.transaction(TxRef.get(ref1))}`) // 10
+ *   console.log(`Final ref2: ${yield* Effect.transaction(TxRef.get(ref2))}`) // 20
  * })
  * ```
  *
@@ -7024,34 +7096,21 @@ export const atomicWith = f => withFiber(fiber => {
  */
 export const transaction = effect => transactionWith(() => effect);
 /**
- * Executes a function within an isolated transaction context, providing access to the transaction state.
+ * Like {@link transaction} but provides access to the transaction state.
  *
- * This function always creates a new transaction boundary, regardless of whether it's called
- * within another transaction. This ensures complete isolation between transaction scopes.
+ * Always creates a new isolated transaction boundary with its own journal and retry logic.
  *
  * @example
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
- * const program = Effect.transactionWith((txState) =>
+ * const program = Effect.transactionWith((_txState) =>
  *   Effect.gen(function*() {
  *     const ref = yield* TxRef.make(0)
- *
- *     // This transaction is isolated - it has its own journal
- *     // txState.journal is independent of any parent transaction
- *
  *     yield* TxRef.set(ref, 42)
  *     return yield* TxRef.get(ref)
  *   })
  * )
- *
- * // Even when nested in another atomic block, this transaction is isolated
- * const nestedProgram = Effect.atomic(
- *   Effect.gen(function*() {
- *     const result = yield* program // Runs in its own isolated transaction
- *     return result
- *   })
- * )
  * ```
  *
  * @since 4.0.0
@@ -7063,7 +7122,6 @@ export const transactionWith = f => withFiber(fiber => {
     journal: new Map(),
     retry: false
   };
-  const scheduler = fiber.currentScheduler;
   let result;
   return uninterruptibleMask(restore => flatMap(whileLoop({
     while: () => !result,
@@ -7076,7 +7134,7 @@ export const transactionWith = f => withFiber(fiber => {
         return clearTransaction(state);
       }
       if (Exit.isSuccess(exit)) {
-        commitTransaction(scheduler, state);
+        commitTransaction(fiber, state);
       } else {
         clearTransaction(state);
       }
@@ -7113,7 +7171,7 @@ const awaitPendingTransaction = state => suspend(() => {
     return sync(clearPending);
   });
 });
-function commitTransaction(scheduler, state) {
+function commitTransaction(fiber, state) {
   for (const [ref, {
     value
   }] of state.journal) {
@@ -7122,7 +7180,7 @@ function commitTransaction(scheduler, state) {
       ref.value = value;
     }
     for (const pending of ref.pending.values()) {
-      scheduler.scheduleTask(pending, 0);
+      fiber.currentDispatcher.scheduleTask(pending, 0);
     }
     ref.pending.clear();
   }
@@ -7146,16 +7204,16 @@ function clearTransaction(state) {
  *
  * const program = Effect.gen(function*() {
  *   // create a transactional reference
- *   const ref = yield* TxRef.make(0)
+ *   const ref = yield* Effect.transaction(TxRef.make(0))
  *
  *   // forks a fiber that increases the value of `ref` every 100 millis
  *   yield* Effect.forkChild(Effect.forever(
  *     // update to transactional value
- *     TxRef.update(ref, (n) => n + 1).pipe(Effect.delay("100 millis"))
+ *     Effect.transaction(TxRef.update(ref, (n) => n + 1)).pipe(Effect.delay("100 millis"))
  *   ))
  *
  *   // the following will retry 10 times until the `ref` value is 10
- *   yield* Effect.atomic(Effect.gen(function*() {
+ *   yield* Effect.transaction(Effect.gen(function*() {
  *     const value = yield* TxRef.get(ref)
  *     if (value < 10) {
  *       yield* Effect.log(`retry due to value: ${value}`)
@@ -7259,18 +7317,20 @@ export const satisfiesSuccessType = () => effect => effect;
  *
  * @example
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class ValidationError extends Data.TaggedError("ValidationError")<{}> {}
  *
- * // Define a constraint that the error type must be an Error
- * const satisfiesError = Effect.satisfiesErrorType<Error>()
+ * // Define a constraint that the error type must be a ValidationError
+ * const satisfiesError = Effect.satisfiesErrorType<ValidationError>()
  *
- * // This works - Effect<number, TypeError, never> extends Effect<number, Error, never>
- * const validEffect = satisfiesError(Effect.fail(new TypeError("Invalid type")))
+ * // This works - Effect<number, ValidationError, never> extends the constrained type
+ * const validEffect = satisfiesError(Effect.fail(new ValidationError()))
  *
  * // This would cause a TypeScript compilation error:
  * // const invalidEffect = satisfiesError(Effect.fail("string error"))
  * //                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- * // Type 'string' is not assignable to type 'Error'
+ * // Type 'string' is not assignable to type 'ValidationError'
  * ```
  *
  * @since 4.0.0