effect 4.0.0-beta.6 → 4.0.0-beta.62

package/dist/Effect.js

@@ -1,3 +1,4 @@
+import * as Context from "./Context.js";
 import * as Duration from "./Duration.js";
 import * as Exit from "./Exit.js";
 import { constant, dual } from "./Function.js";
@@ -9,7 +10,6 @@ import * as internalRequest from "./internal/request.js";
 import * as internalSchedule from "./internal/schedule.js";
 import * as Metric from "./Metric.js";
 import { CurrentLogAnnotations, CurrentLogSpans } from "./References.js";
-import * as ServiceMap from "./ServiceMap.js";
 import { internalCall, SingleShotGen } from "./Utils.js";
 const TypeId = core.EffectTypeId;
 /**
@@ -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
@@ -2645,13 +2809,16 @@ export const ignoreCause = internal.ignoreCause;
  *
  * @example
  * ```ts
- * import { Effect, ExecutionPlan, Layer, ServiceMap } from "effect"
+ * import { Effect, ExecutionPlan, Layer, Context } from "effect"
  *
- * const Endpoint = ServiceMap.Service<{ url: string }>("Endpoint")
+ * const Endpoint = Context.Service<{ url: string }>("Endpoint")
  *
  * 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
 // -----------------------------------------------------------------------------
@@ -2711,6 +2888,50 @@ export const withExecutionPlan = internalExecutionPlan.withExecutionPlan;
  * @category Fallback
  */
 export const orElseSucceed = internal.orElseSucceed;
+/**
+ * Runs a sequence of effects and returns the result of the first successful
+ * one.
+ *
+ * **Details**
+ *
+ * This function executes the provided effects in sequence, stopping at the
+ * first success. If an effect succeeds, its result is returned immediately and
+ * no further effects in the sequence are executed.
+ *
+ * If all effects fail, the returned effect fails with the error from the last
+ * effect. If the collection is empty, the returned effect defects with an
+ * `Error` whose message is `"Received an empty collection of effects"`.
+ *
+ * **When to Use**
+ *
+ * Use `firstSuccessOf` when you have prioritized fallback strategies, such as
+ * attempting multiple APIs, reading configuration from several sources, or
+ * trying alternative resource locations in order.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const primary = Effect.fail("primary unavailable")
+ * const secondary = Effect.succeed("secondary result")
+ * const tertiary = Effect.sync(() => {
+ *   throw new Error("not evaluated")
+ * })
+ *
+ * const program = Effect.firstSuccessOf([
+ *   primary,
+ *   secondary,
+ *   tertiary
+ * ])
+ *
+ * console.log(Effect.runSync(program))
+ * // Output: "secondary result"
+ * ```
+ *
+ * @since 2.0.0
+ * @category Fallback
+ */
+export const firstSuccessOf = internal.firstSuccessOf;
 // -----------------------------------------------------------------------------
 // Delays & timeouts
 // -----------------------------------------------------------------------------
@@ -2830,7 +3051,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 +3263,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 +3276,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 +3328,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 +3365,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 +3438,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 +3453,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 +3598,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 +3658,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"
  *
- * const success: Effect.Effect<number, Error> = Effect.succeed(42)
- * const failure: Effect.Effect<number, Error> = Effect.fail(
- *   new Error("Uh oh!")
+ * class ExampleError extends Data.TaggedError("ExampleError")<{ readonly message: string }> {}
+ *
+ * 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, {
@@ -3506,7 +3758,7 @@ export const isSuccess = internal.isSuccess;
 // Environment
 // -----------------------------------------------------------------------------
 /**
- * Returns the complete service map from the current context.
+ * Returns the complete context.
  *
  * This function allows you to access all services that are currently available
  * in the effect's environment. This can be useful for debugging, introspection,
@@ -3514,56 +3766,56 @@ export const isSuccess = internal.isSuccess;
  *
  * @example
  * ```ts
- * import { Console, Effect, Option, ServiceMap } from "effect"
+ * import { Console, Effect, Option, Context } from "effect"
  *
- * const Logger = ServiceMap.Service<{
+ * const Logger = Context.Service<{
  *   log: (msg: string) => void
  * }>("Logger")
- * const Database = ServiceMap.Service<{
+ * const Database = Context.Service<{
  *   query: (sql: string) => string
  * }>("Database")
  *
  * const program = Effect.gen(function*() {
- *   const allServices = yield* Effect.services()
+ *   const allServices = yield* Effect.context()
  *
  *   // Check if specific services are available
- *   const loggerOption = ServiceMap.getOption(allServices, Logger)
- *   const databaseOption = ServiceMap.getOption(allServices, Database)
+ *   const loggerOption = Context.getOption(allServices, Logger)
+ *   const databaseOption = Context.getOption(allServices, Database)
  *
  *   yield* Console.log(`Logger available: ${Option.isSome(loggerOption)}`)
  *   yield* Console.log(`Database available: ${Option.isSome(databaseOption)}`)
  * })
  *
- * const serviceMap = ServiceMap.make(Logger, { log: console.log })
- *   .pipe(ServiceMap.add(Database, { query: () => "result" }))
+ * const context = Context.make(Logger, { log: console.log })
+ *   .pipe(Context.add(Database, { query: () => "result" }))
  *
- * const provided = Effect.provideServices(program, serviceMap)
+ * const provided = Effect.provideContext(program, context)
  * ```
  *
  * @since 2.0.0
  * @category Environment
  */
-export const services = internal.services;
+export const context = internal.context;
 /**
- * Transforms the current service map using the provided function.
+ * Transforms the current context using the provided function.
  *
- * This function allows you to access the complete service map and perform
+ * This function allows you to access the complete context and perform
  * computations based on all available services. This is useful when you need
  * to conditionally execute logic based on what services are available.
  *
  * @example
  * ```ts
- * import { Console, Effect, Option, ServiceMap } from "effect"
+ * import { Console, Effect, Option, Context } from "effect"
  *
- * const Logger = ServiceMap.Service<{
+ * const Logger = Context.Service<{
  *   log: (msg: string) => void
  * }>("Logger")
- * const Cache = ServiceMap.Service<{
+ * const Cache = Context.Service<{
  *   get: (key: string) => string | null
  * }>("Cache")
  *
- * const program = Effect.servicesWith((services) => {
- *   const cacheOption = ServiceMap.getOption(services, Cache)
+ * const program = Effect.contextWith((services) => {
+ *   const cacheOption = Context.getOption(services, Cache)
  *   const hasCache = Option.isSome(cacheOption)
  *
  *   if (hasCache) {
@@ -3588,7 +3840,7 @@ export const services = internal.services;
  * @since 2.0.0
  * @category Environment
  */
-export const servicesWith = internal.servicesWith;
+export const contextWith = internal.contextWith;
 /**
  * Provides dependencies to an effect using layers or a context. Use `options.local`
  * to build the layer every time; by default, layers are shared between provide
@@ -3596,16 +3848,16 @@ export const servicesWith = internal.servicesWith;
  *
  * @example
  * ```ts
- * import { Effect, Layer, ServiceMap } from "effect"
+ * import { Effect, Layer, Context } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }
  *
- * const Database = ServiceMap.Service<Database>("Database")
+ * const Database = Context.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*() {
@@ -3624,29 +3876,29 @@ export const servicesWith = internal.servicesWith;
  */
 export const provide = internalLayer.provide;
 /**
- * Provides a service map to an effect, fulfilling its service requirements.
+ * Provides a context to an effect, fulfilling its service requirements.
  *
  * **Details**
  *
- * This function provides multiple services at once by supplying a service map
+ * This function provides multiple services at once by supplying a context
  * that contains all the required services. It removes the provided services
  * from the effect's requirements, making them available to the effect.
  *
  * @example
  * ```ts
- * import { Effect, ServiceMap } from "effect"
+ * import { Effect, Context } from "effect"
  *
  * // Define service keys
- * const Logger = ServiceMap.Service<{
+ * const Logger = Context.Service<{
  *   log: (msg: string) => void
  * }>("Logger")
- * const Database = ServiceMap.Service<{
+ * const Database = Context.Service<{
  *   query: (sql: string) => string
  * }>("Database")
  *
- * // Create service map with multiple services
- * const serviceMap = ServiceMap.make(Logger, { log: console.log })
- *   .pipe(ServiceMap.add(Database, { query: () => "result" }))
+ * // Create a context with multiple services
+ * const context = Context.make(Logger, { log: console.log })
+ *   .pipe(Context.add(Database, { query: () => "result" }))
  *
  * // An effect that requires both services
  * const program = Effect.gen(function*() {
@@ -3656,25 +3908,25 @@ export const provide = internalLayer.provide;
  *   return db.query("SELECT * FROM users")
  * })
  *
- * const provided = Effect.provideServices(program, serviceMap)
+ * const provided = Effect.provideContext(program, context)
  * ```
  *
  * @since 2.0.0
  * @category Environment
  */
-export const provideServices = internal.provideServices;
+export const provideContext = internal.provideContext;
 /**
  * Accesses a service from the context.
  *
  * @example
  * ```ts
- * import { Effect, ServiceMap } from "effect"
+ * import { Effect, Context } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }
  *
- * const Database = ServiceMap.Service<Database>("Database")
+ * const Database = Context.Service<Database>("Database")
  *
  * const program = Effect.gen(function*() {
  *   const db = yield* Effect.service(Database)
@@ -3683,7 +3935,7 @@ export const provideServices = internal.provideServices;
  * ```
  *
  * @since 4.0.0
- * @category ServiceMap
+ * @category Context
  */
 export const service = internal.service;
 /**
@@ -3698,10 +3950,10 @@ export const service = internal.service;
  *
  * @example
  * ```ts
- * import { Effect, Option, ServiceMap } from "effect"
+ * import { Effect, Option, Context } from "effect"
  *
  * // Define a service key
- * const Logger = ServiceMap.Service<{
+ * const Logger = Context.Service<{
  *   log: (msg: string) => void
  * }>("Logger")
  *
@@ -3718,7 +3970,7 @@ export const service = internal.service;
  * ```
  *
  * @since 2.0.0
- * @category ServiceMap
+ * @category Context
  */
 export const serviceOption = internal.serviceOption;
 /**
@@ -3731,13 +3983,13 @@ export const serviceOption = internal.serviceOption;
  *
  * @example
  * ```ts
- * import { Effect, ServiceMap } from "effect"
+ * import { Effect, Context } from "effect"
  *
  * // Define services
- * const Logger = ServiceMap.Service<{
+ * const Logger = Context.Service<{
  *   log: (msg: string) => void
  * }>("Logger")
- * const Config = ServiceMap.Service<{
+ * const Config = Context.Service<{
  *   name: string
  * }>("Config")
  *
@@ -3747,8 +3999,8 @@ export const serviceOption = internal.serviceOption;
  *
  * // Transform services by providing Config while keeping Logger requirement
  * const configured = program.pipe(
- *   Effect.updateServices((services: ServiceMap.ServiceMap<typeof Logger>) =>
- *     ServiceMap.add(services, Config, { name: "World" })
+ *   Effect.updateContext((context: Context.Context<typeof Logger>) =>
+ *     Context.add(context, Config, { name: "World" })
  *   )
  * )
  *
@@ -3759,18 +4011,18 @@ export const serviceOption = internal.serviceOption;
  * ```
  *
  * @since 4.0.0
- * @category ServiceMap
+ * @category Context
  */
-export const updateServices = internal.updateServices;
+export const updateContext = internal.updateContext;
 /**
  * Updates the service with the required service entry.
  *
  * @example
  * ```ts
- * import { Console, Effect, ServiceMap } from "effect"
+ * import { Console, Effect, Context } from "effect"
  *
  * // Define a counter service
- * const Counter = ServiceMap.Service<{ count: number }>("Counter")
+ * const Counter = Context.Service<{ count: number }>("Counter")
  *
  * const program = Effect.gen(function*() {
  *   const updatedCounter = yield* Effect.service(Counter)
@@ -3788,7 +4040,7 @@ export const updateServices = internal.updateServices;
  * ```
  *
  * @since 2.0.0
- * @category ServiceMap
+ * @category Context
  */
 export const updateService = internal.updateService;
 /**
@@ -3805,10 +4057,10 @@ export const updateService = internal.updateService;
  *
  * @example
  * ```ts
- * import { Console, Effect, ServiceMap } from "effect"
+ * import { Console, Effect, Context } from "effect"
  *
  * // Define a service for configuration
- * const Config = ServiceMap.Service<{
+ * const Config = Context.Service<{
  *   apiUrl: string
  *   timeout: number
  * }>("Config")
@@ -3834,7 +4086,7 @@ export const updateService = internal.updateService;
  * ```
  *
  * @since 2.0.0
- * @category ServiceMap
+ * @category Context
  */
 export const provideService = internal.provideService;
 /**
@@ -3849,13 +4101,13 @@ export const provideService = internal.provideService;
  *
  * @example
  * ```ts
- * import { Console, Effect, ServiceMap } from "effect"
+ * import { Console, Effect, Context } from "effect"
  *
  * // Define a database connection service
  * interface DatabaseConnection {
  *   readonly query: (sql: string) => Effect.Effect<string>
  * }
- * const Database = ServiceMap.Service<DatabaseConnection>("Database")
+ * const Database = Context.Service<DatabaseConnection>("Database")
  *
  * // Effect that creates a database connection
  * const createConnection = Effect.gen(function*() {
@@ -3887,7 +4139,7 @@ export const provideService = internal.provideService;
  * ```
  *
  * @since 2.0.0
- * @category ServiceMap
+ * @category Context
  */
 export const provideServiceEffect = internal.provideServiceEffect;
 // -----------------------------------------------------------------------------
@@ -4245,9 +4497,11 @@ export const ensuring = internal.ensuring;
  *
  * @example
  * ```ts
- * import { Cause, Console, Effect } from "effect"
+ * import { Cause, Data, Console, Effect } from "effect"
  *
- * const task = Effect.fail(new Error("Something went wrong"))
+ * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
+ *
+ * const task = Effect.fail(new TaskError({ message: "Something went wrong" }))
  *
  * const program = Effect.onError(
  *   task,
@@ -4256,8 +4510,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 +4520,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 +4542,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 +4586,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 +4607,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 +4829,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,6 +4970,13 @@ export const uninterruptibleMask = internal.uninterruptibleMask;
  * @category Interruption
  */
 export const interruptibleMask = internal.interruptibleMask;
+/**
+ * Creates an AbortSignal that is managed by the provided scope.
+ *
+ * @since 4.0.0
+ * @category Interruption
+ */
+export const abortSignal = internal.abortSignal;
 /**
  * Repeats this effect forever (until the first error).
  *
@@ -4824,7 +5099,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"
@@ -5392,7 +5667,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)
  * })
  * ```
@@ -5400,7 +5675,7 @@ export const withParentSpan = internal.withParentSpan;
 export const request = internalRequest.request;
 /**
  * Low-level entry point that registers a request with a resolver and delivers the exit value via `onExit`.
- * Use this when you already have a `ServiceMap` and need to enqueue a request outside an `Effect`.
+ * Use this when you already have a `Context` and need to enqueue a request outside an `Effect`.
  *
  * It returns a canceler that removes the pending request entry.
  *
@@ -5645,15 +5920,15 @@ export const runFork = internal.runFork;
  *
  * @example
  * ```ts
- * import { Effect, ServiceMap } from "effect"
+ * import { Effect, Context } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => void
  * }
  *
- * const Logger = ServiceMap.Service<Logger>("Logger")
+ * const Logger = Context.Service<Logger>("Logger")
  *
- * const services = ServiceMap.make(Logger, {
+ * const services = Context.make(Logger, {
  *   log: (message) => console.log(message)
  * })
  *
@@ -5677,15 +5952,15 @@ export const runForkWith = internal.runForkWith;
  *
  * @example
  * ```ts
- * import { Console, Effect, Exit, ServiceMap } from "effect"
+ * import { Console, Effect, Exit, Context } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => Effect.Effect<void>
  * }
  *
- * const Logger = ServiceMap.Service<Logger>("Logger")
+ * const Logger = Context.Service<Logger>("Logger")
  *
- * const services = ServiceMap.make(Logger, {
+ * const services = Context.make(Logger, {
  *   log: (message) => Console.log(message)
  * })
  *
@@ -5789,15 +6064,15 @@ export const runPromise = internal.runPromise;
  *
  * @example
  * ```ts
- * import { Effect, ServiceMap } from "effect"
+ * import { Effect, Context } from "effect"
  *
  * interface Config {
  *   apiUrl: string
  * }
  *
- * const Config = ServiceMap.Service<Config>("Config")
+ * const Config = Context.Service<Config>("Config")
  *
- * const services = ServiceMap.make(Config, {
+ * const context = Context.make(Config, {
  *   apiUrl: "https://api.example.com"
  * })
  *
@@ -5806,7 +6081,7 @@ export const runPromise = internal.runPromise;
  *   return `Connecting to ${config.apiUrl}`
  * })
  *
- * Effect.runPromiseWith(services)(program).then(console.log)
+ * Effect.runPromiseWith(context)(program).then(console.log)
  * ```
  *
  * @since 4.0.0
@@ -5866,15 +6141,15 @@ export const runPromiseExit = internal.runPromiseExit;
  *
  * @example
  * ```ts
- * import { Effect, Exit, ServiceMap } from "effect"
+ * import { Effect, Exit, Context } from "effect"
  *
  * interface Database {
  *   query: (sql: string) => string
  * }
  *
- * const Database = ServiceMap.Service<Database>("Database")
+ * const Database = Context.Service<Database>("Database")
  *
- * const services = ServiceMap.make(Database, {
+ * const services = Context.make(Database, {
  *   query: (sql) => `Result for: ${sql}`
  * })
  *
@@ -5957,15 +6232,15 @@ export const runSync = internal.runSync;
  *
  * @example
  * ```ts
- * import { Effect, ServiceMap } from "effect"
+ * import { Effect, Context } from "effect"
  *
  * interface MathService {
  *   add: (a: number, b: number) => number
  * }
  *
- * const MathService = ServiceMap.Service<MathService>("MathService")
+ * const MathService = Context.Service<MathService>("MathService")
  *
- * const services = ServiceMap.make(MathService, {
+ * const context = Context.make(MathService, {
  *   add: (a, b) => a + b
  * })
  *
@@ -5974,7 +6249,7 @@ export const runSync = internal.runSync;
  *   return math.add(2, 3)
  * })
  *
- * const result = Effect.runSyncWith(services)(program)
+ * const result = Effect.runSyncWith(context)(program)
  * console.log(result) // 5
  * ```
  *
@@ -6057,10 +6332,10 @@ export const runSyncExit = internal.runSyncExit;
  *
  * @example
  * ```ts
- * import { Effect, Exit, ServiceMap } from "effect"
+ * import { Effect, Exit, Context } from "effect"
  *
  * // Define a logger service
- * const Logger = ServiceMap.Service<{
+ * const Logger = Context.Service<{
  *   log: (msg: string) => void
  * }>("Logger")
  *
@@ -6070,12 +6345,12 @@ export const runSyncExit = internal.runSyncExit;
  *   return 42
  * })
  *
- * // Prepare services
- * const services = ServiceMap.make(Logger, {
+ * // Prepare context
+ * const context = Context.make(Logger, {
  *   log: (msg) => console.log(`[LOG] ${msg}`)
  * })
  *
- * const exit = Effect.runSyncExitWith(services)(program)
+ * const exit = Effect.runSyncExitWith(context)(program)
  *
  * if (Exit.isSuccess(exit)) {
  *   console.log(`Success: ${exit.value}`)
@@ -6450,7 +6725,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
   };
@@ -6461,6 +6736,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.
  *
@@ -6626,18 +6927,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 } }
  * )
  * ```
  *
@@ -6748,7 +7051,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);
   });
@@ -6777,21 +7080,24 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * @since 4.0.0
  * @category Transactions
  */
-export class Transaction extends /*#__PURE__*/ServiceMap.Service()("effect/Effect/Transaction") {}
+export class Transaction extends /*#__PURE__*/Context.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.
+ * 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.
+ *
+ * If called inside an active transaction, `tx` composes with the current transaction and reuses
+ * its journal and retry state instead of creating a nested boundary.
  *
  * 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
+ * - the body of the transaction explicitely calls to `Effect.txRetry` 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.
+ * The outermost `tx` call creates the transaction boundary and commits or rolls back the full
+ * composed transaction.
  *
  * @example
  * ```ts
@@ -6801,10 +7107,10 @@ export class Transaction extends /*#__PURE__*/ServiceMap.Service()("effect/Effec
  *   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*() {
+ *   // Nested tx calls compose into the same transaction
+ *   yield* Effect.tx(Effect.gen(function*() {
  *     yield* TxRef.set(ref1, 10)
- *     yield* TxRef.set(ref2, 20)
+ *     yield* Effect.tx(TxRef.set(ref2, 20))
  *     const sum = (yield* TxRef.get(ref1)) + (yield* TxRef.get(ref2))
  *     console.log(`Transaction sum: ${sum}`)
  *   }))
@@ -6817,139 +7123,19 @@ export class Transaction extends /*#__PURE__*/ServiceMap.Service()("effect/Effec
  * @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}`)
- *
- *     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)));
+export const tx = effect => withFiber(fiber => {
+  if (fiber.context.mapUnsafe.has(Transaction.key)) {
+    return effect;
   }
-  // No existing transaction, create isolated one using transactionWith
-  return transactionWith(f);
-});
-/**
- * Creates an isolated transaction that never composes with parent transactions.
- *
- * **Details**
- *
- * 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.
- *
- * **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
- *
- * **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
- *
- * @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
- *     }))
- *   }))
- *
- *   // Isolated transaction - ref2 will be in its own transaction
- *   yield* Effect.transaction(Effect.gen(function*() {
- *     yield* TxRef.set(ref2, 200)
- *   }))
- *
- *   const val1 = yield* TxRef.get(ref1) // 20
- *   const val2 = yield* TxRef.get(ref2) // 200
- *   return { ref1: val1, ref2: val2 }
- * })
- * ```
- *
- * @since 4.0.0
- * @category Transactions
- */
-export const transaction = effect => transactionWith(() => effect);
-/**
- * Executes a function within an isolated transaction context, providing 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.
- *
- * @example
- * ```ts
- * import { Effect, TxRef } from "effect"
- *
- * 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
- * @category Transactions
- */
-export const transactionWith = f => withFiber(fiber => {
-  // Always create a new transaction state, never compose with parent
+  // Create transaction state only at the outermost boundary
   const state = {
     journal: new Map(),
     retry: false
   };
-  const scheduler = fiber.currentScheduler;
   let result;
   return uninterruptibleMask(restore => flatMap(whileLoop({
     while: () => !result,
-    body: constant(restore(suspend(() => f(state))).pipe(provideService(Transaction, state), tapCause(() => {
+    body: constant(restore(effect).pipe(provideService(Transaction, state), tapCause(() => {
       if (!state.retry) return void_;
       return restore(awaitPendingTransaction(state));
     }), exit)),
@@ -6958,7 +7144,7 @@ export const transactionWith = f => withFiber(fiber => {
         return clearTransaction(state);
       }
       if (Exit.isSuccess(exit)) {
-        commitTransaction(scheduler, state);
+        commitTransaction(fiber, state);
       } else {
         clearTransaction(state);
       }
@@ -6995,7 +7181,7 @@ const awaitPendingTransaction = state => suspend(() => {
     return sync(clearPending);
   });
 });
-function commitTransaction(scheduler, state) {
+function commitTransaction(fiber, state) {
   for (const [ref, {
     value
   }] of state.journal) {
@@ -7004,7 +7190,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();
   }
@@ -7033,15 +7219,15 @@ function clearTransaction(state) {
  *   // 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.tx(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.tx(Effect.gen(function*() {
  *     const value = yield* TxRef.get(ref)
  *     if (value < 10) {
  *       yield* Effect.log(`retry due to value: ${value}`)
- *       return yield* Effect.retryTransaction
+ *       return yield* Effect.txRetry
  *     }
  *     yield* Effect.log(`transaction done with value: ${value}`)
  *   }))
@@ -7050,7 +7236,7 @@ function clearTransaction(state) {
  * Effect.runPromise(program).catch(console.error)
  * ```
  */
-export const retryTransaction = /*#__PURE__*/flatMap(/*#__PURE__*/Transaction.asEffect(), state => {
+export const txRetry = /*#__PURE__*/flatMap(/*#__PURE__*/Transaction.asEffect(), state => {
   state.retry = true;
   return interrupt;
 });
@@ -7141,18 +7327,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