effect 4.0.0-beta.2 → 4.0.0-beta.21

package/dist/Effect.js

@@ -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`.
  *
@@ -690,6 +755,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.
@@ -1998,15 +2108,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 +2142,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 +2153,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 +2226,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.
@@ -2344,6 +2467,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.
  *
@@ -2666,6 +2796,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
 // -----------------------------------------------------------------------------
@@ -3042,12 +3182,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 +3195,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 +3247,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 +3284,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
 // -----------------------------------------------------------------------------
@@ -4266,7 +4431,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 +4453,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 +4497,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 +4518,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
 // -----------------------------------------------------------------------------
@@ -4702,124 +4881,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).
  *
@@ -6579,6 +6640,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.
  *
@@ -6866,7 +6953,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 +6984,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 +7049,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
@@ -7146,16 +7158,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}`)