effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/TxChunk.ts

@@ -30,7 +30,8 @@ const TypeId = "~effect/transactions/TxChunk"
  * A transaction will retry whenever a conflict is detected or whenever the transaction explicitly
  * calls `Effect.txRetry` and any of the accessed TxChunk values change.
  *
- * @example
+ * **Example** (Using a transactional chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -60,8 +61,8 @@ const TypeId = "~effect/transactions/TxChunk"
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxChunk<in out A> extends Inspectable, Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -92,9 +93,8 @@ const TxChunkProto = {
  * **Return behavior**: This function returns a new TxChunk reference containing
  * the provided initial chunk. No existing TxChunk instances are modified.
  *
- * @since 4.0.0
- * @category Constructors
- * @example
+ * **Example** (Creating a TxChunk from a chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -108,6 +108,9 @@ const TxChunkProto = {
  *   console.log(Chunk.toReadonlyArray(result)) // [1, 2, 3]
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = <A>(initial: Chunk.Chunk<A>): Effect.Effect<TxChunk<A>> =>
   Effect.map(TxRef.make(initial), (ref) => makeUnsafe(ref))
@@ -118,9 +121,8 @@ export const make = <A>(initial: Chunk.Chunk<A>): Effect.Effect<TxChunk<A>> =>
  * **Return behavior**: This function returns a new TxChunk reference that is
  * initially empty. No existing TxChunk instances are modified.
  *
- * @since 4.0.0
- * @category Constructors
- * @example
+ * **Example** (Creating an empty TxChunk)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -139,6 +141,9 @@ export const make = <A>(initial: Chunk.Chunk<A>): Effect.Effect<TxChunk<A>> =>
  *   console.log(isStillEmpty) // false
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const empty = <A = never>(): Effect.Effect<TxChunk<A>> =>
   Effect.map(TxRef.make(Chunk.empty<A>()), (ref) => makeUnsafe(ref))
@@ -149,9 +154,8 @@ export const empty = <A = never>(): Effect.Effect<TxChunk<A>> =>
  * **Return behavior**: This function returns a new TxChunk reference containing
  * elements from the provided iterable. No existing TxChunk instances are modified.
  *
- * @since 4.0.0
- * @category Constructors
- * @example
+ * **Example** (Creating from an iterable)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -175,6 +179,9 @@ export const empty = <A = never>(): Effect.Effect<TxChunk<A>> =>
  *   console.log(Chunk.toReadonlyArray(updated)) // [0, 1, 2, 3, 4, 5, 6]
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const fromIterable = <A>(iterable: Iterable<A>): Effect.Effect<TxChunk<A>> =>
   Effect.map(TxRef.make(Chunk.fromIterable(iterable)), (ref) => makeUnsafe(ref))
@@ -185,7 +192,8 @@ export const fromIterable = <A>(iterable: Iterable<A>): Effect.Effect<TxChunk<A>
  * **Return behavior**: This function returns a new TxChunk reference wrapping
  * the provided TxRef. No existing TxChunk instances are modified.
  *
- * @example
+ * **Example** (Wrapping an existing TxRef)
+ *
  * ```ts
  * import { Chunk, TxChunk, TxRef } from "effect"
  *
@@ -194,8 +202,8 @@ export const fromIterable = <A>(iterable: Iterable<A>): Effect.Effect<TxChunk<A>
  * const txChunk = TxChunk.makeUnsafe(ref)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeUnsafe = <A>(ref: TxRef.TxRef<Chunk.Chunk<A>>): TxChunk<A> => {
   const txChunk = Object.create(TxChunkProto)
@@ -210,9 +218,8 @@ export const makeUnsafe = <A>(ref: TxRef.TxRef<Chunk.Chunk<A>>): TxChunk<A> => {
  * **Mutation behavior**: This function mutates the original TxChunk by updating
  * its internal state. It does not return a new TxChunk reference.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Modifying while returning a value)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -231,6 +238,9 @@ export const makeUnsafe = <A>(ref: TxRef.TxRef<Chunk.Chunk<A>>): TxChunk<A> => {
  *   console.log(Chunk.toReadonlyArray(newChunk)) // [1, 2, 3, 4]
  * })
  * ```
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export const modify: {
   /**
@@ -239,9 +249,8 @@ export const modify: {
    * **Mutation behavior**: This function mutates the original TxChunk by updating
    * its internal state. It does not return a new TxChunk reference.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Modifying while returning a value)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -260,6 +269,9 @@ export const modify: {
    *   console.log(Chunk.toReadonlyArray(newChunk)) // [1, 2, 3, 4]
    * })
    * ```
+   *
+   * @category combinators
+   * @since 4.0.0
    */
   <A, R>(
     f: (current: Chunk.Chunk<NoInfer<A>>) => [returnValue: R, newValue: Chunk.Chunk<A>]
@@ -270,9 +282,8 @@ export const modify: {
    * **Mutation behavior**: This function mutates the original TxChunk by updating
    * its internal state. It does not return a new TxChunk reference.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Modifying while returning a value)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -291,6 +302,9 @@ export const modify: {
    *   console.log(Chunk.toReadonlyArray(newChunk)) // [1, 2, 3, 4]
    * })
    * ```
+   *
+   * @category combinators
+   * @since 4.0.0
    */
   <A, R>(
     self: TxChunk<A>,
@@ -310,15 +324,15 @@ export const modify: {
  * **Mutation behavior**: This function mutates the original TxChunk by updating
  * its internal state. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Updating the stored chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3])
  *
- *   // Update the chunk by reversing it
- *   // Update the chunk by reversing it - automatically transactional
+ *   // Update the chunk by reversing it atomically
  *   yield* TxChunk.update(txChunk, (chunk) => Chunk.reverse(chunk))
  *
  *   const result = yield* TxChunk.get(txChunk)
@@ -326,8 +340,8 @@ export const modify: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const update: {
   /**
@@ -336,15 +350,15 @@ export const update: {
    * **Mutation behavior**: This function mutates the original TxChunk by updating
    * its internal state. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Updating the stored chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3])
    *
-   *   // Update the chunk by reversing it
-   *   // Update the chunk by reversing it - automatically transactional
+   *   // Update the chunk by reversing it atomically
    *   yield* TxChunk.update(txChunk, (chunk) => Chunk.reverse(chunk))
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -352,8 +366,8 @@ export const update: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(f: (current: Chunk.Chunk<NoInfer<A>>) => Chunk.Chunk<A>): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -362,15 +376,15 @@ export const update: {
    * **Mutation behavior**: This function mutates the original TxChunk by updating
    * its internal state. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Updating the stored chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3])
    *
-   *   // Update the chunk by reversing it
-   *   // Update the chunk by reversing it - automatically transactional
+   *   // Update the chunk by reversing it atomically
    *   yield* TxChunk.update(txChunk, (chunk) => Chunk.reverse(chunk))
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -378,8 +392,8 @@ export const update: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, f: (current: Chunk.Chunk<A>) => Chunk.Chunk<A>): Effect.Effect<void>
 } = dual(
@@ -393,7 +407,8 @@ export const update: {
 /**
  * Reads the current chunk from the `TxChunk`.
  *
- * @example
+ * **Example** (Reading the current chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -410,8 +425,8 @@ export const update: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const get = <A>(self: TxChunk<A>): Effect.Effect<Chunk.Chunk<A>> => TxRef.get(self.ref)
 
@@ -421,7 +436,8 @@ export const get = <A>(self: TxChunk<A>): Effect.Effect<Chunk.Chunk<A>> => TxRef
  * **Mutation behavior**: This function mutates the original TxChunk by replacing
  * its internal state with the provided chunk. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Replacing the stored chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -437,8 +453,8 @@ export const get = <A>(self: TxChunk<A>): Effect.Effect<Chunk.Chunk<A>> => TxRef
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const set: {
   /**
@@ -447,7 +463,8 @@ export const set: {
    * **Mutation behavior**: This function mutates the original TxChunk by replacing
    * its internal state with the provided chunk. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Replacing the stored chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -463,8 +480,8 @@ export const set: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(chunk: Chunk.Chunk<A>): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -473,7 +490,8 @@ export const set: {
    * **Mutation behavior**: This function mutates the original TxChunk by replacing
    * its internal state with the provided chunk. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Replacing the stored chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -489,8 +507,8 @@ export const set: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, chunk: Chunk.Chunk<A>): Effect.Effect<void>
 } = dual(
@@ -504,7 +522,8 @@ export const set: {
  * **Mutation behavior**: This function mutates the original TxChunk by adding
  * the element to the end. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Appending an element)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -519,8 +538,8 @@ export const set: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const append: {
   /**
@@ -529,7 +548,8 @@ export const append: {
    * **Mutation behavior**: This function mutates the original TxChunk by adding
    * the element to the end. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Appending an element)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -544,8 +564,8 @@ export const append: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(element: A): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -554,7 +574,8 @@ export const append: {
    * **Mutation behavior**: This function mutates the original TxChunk by adding
    * the element to the end. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Appending an element)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -569,8 +590,8 @@ export const append: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, element: A): Effect.Effect<void>
 } = dual(
@@ -584,7 +605,8 @@ export const append: {
  * **Mutation behavior**: This function mutates the original TxChunk by adding
  * the element to the beginning. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -599,8 +621,8 @@ export const append: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const prepend: {
   /**
@@ -609,7 +631,8 @@ export const prepend: {
    * **Mutation behavior**: This function mutates the original TxChunk by adding
    * the element to the beginning. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Prepending an element)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -624,8 +647,8 @@ export const prepend: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(element: A): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -634,7 +657,8 @@ export const prepend: {
    * **Mutation behavior**: This function mutates the original TxChunk by adding
    * the element to the beginning. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Prepending an element)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -649,8 +673,8 @@ export const prepend: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, element: A): Effect.Effect<void>
 } = dual(
@@ -661,7 +685,8 @@ export const prepend: {
 /**
  * Gets the size of the `TxChunk`.
  *
- * @example
+ * **Example** (Getting the size)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -679,8 +704,8 @@ export const prepend: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const size = <A>(self: TxChunk<A>): Effect.Effect<number> =>
   modify(self, (current) => [Chunk.size(current), current])
@@ -688,7 +713,8 @@ export const size = <A>(self: TxChunk<A>): Effect.Effect<number> =>
 /**
  * Checks if the `TxChunk` is empty.
  *
- * @example
+ * **Example** (Checking for an empty chunk)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -705,8 +731,8 @@ export const size = <A>(self: TxChunk<A>): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isEmpty = <A>(self: TxChunk<A>): Effect.Effect<boolean> =>
   modify(self, (current) => [Chunk.isEmpty(current), current])
@@ -714,7 +740,8 @@ export const isEmpty = <A>(self: TxChunk<A>): Effect.Effect<boolean> =>
 /**
  * Checks if the `TxChunk` is non-empty.
  *
- * @example
+ * **Example** (Checking for a non-empty chunk)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -731,8 +758,8 @@ export const isEmpty = <A>(self: TxChunk<A>): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const isNonEmpty = <A>(self: TxChunk<A>): Effect.Effect<boolean> =>
   modify(self, (current) => [Chunk.isNonEmpty(current), current])
@@ -743,7 +770,8 @@ export const isNonEmpty = <A>(self: TxChunk<A>): Effect.Effect<boolean> =>
  * **Mutation behavior**: This function mutates the original TxChunk by keeping
  * only the first n elements. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Taking leading elements)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -758,8 +786,8 @@ export const isNonEmpty = <A>(self: TxChunk<A>): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const take: {
   /**
@@ -768,7 +796,8 @@ export const take: {
    * **Mutation behavior**: This function mutates the original TxChunk by keeping
    * only the first n elements. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Taking leading elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -783,8 +812,8 @@ export const take: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (n: number): <A>(self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -793,7 +822,8 @@ export const take: {
    * **Mutation behavior**: This function mutates the original TxChunk by keeping
    * only the first n elements. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Taking leading elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -808,8 +838,8 @@ export const take: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, n: number): Effect.Effect<void>
 } = dual(
@@ -823,7 +853,8 @@ export const take: {
  * **Mutation behavior**: This function mutates the original TxChunk by removing
  * the first n elements. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Dropping leading elements)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -838,8 +869,8 @@ export const take: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const drop: {
   /**
@@ -848,7 +879,8 @@ export const drop: {
    * **Mutation behavior**: This function mutates the original TxChunk by removing
    * the first n elements. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Dropping leading elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -863,8 +895,8 @@ export const drop: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (n: number): <A>(self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -873,7 +905,8 @@ export const drop: {
    * **Mutation behavior**: This function mutates the original TxChunk by removing
    * the first n elements. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Dropping leading elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -888,8 +921,8 @@ export const drop: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, n: number): Effect.Effect<void>
 } = dual(
@@ -903,7 +936,8 @@ export const drop: {
  * **Mutation behavior**: This function mutates the original TxChunk by keeping
  * only the elements in the specified range. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Taking a slice)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -918,8 +952,8 @@ export const drop: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const slice: {
   /**
@@ -928,7 +962,8 @@ export const slice: {
    * **Mutation behavior**: This function mutates the original TxChunk by keeping
    * only the elements in the specified range. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Taking a slice)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -943,8 +978,8 @@ export const slice: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (start: number, end: number): <A>(self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -953,7 +988,8 @@ export const slice: {
    * **Mutation behavior**: This function mutates the original TxChunk by keeping
    * only the elements in the specified range. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Taking a slice)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -968,8 +1004,8 @@ export const slice: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, start: number, end: number): Effect.Effect<void>
 } = dual(
@@ -979,21 +1015,22 @@ export const slice: {
 )
 
 /**
- * Maps each element of the `TxChunk` using the provided function.
- * Note: This only works when the mapped type B is assignable to A.
+ * Maps each element of the `TxChunk` using a function that returns the same
+ * element type.
  *
- * **Mutation behavior**: This function mutates the original TxChunk by transforming
- * each element in place. It does not return a new TxChunk reference.
+ * **Mutation behavior**: This function mutates the original `TxChunk` by
+ * transforming each element in place. It does not return a new `TxChunk`
+ * reference.
+ *
+ * **Example** (Mapping elements)
  *
- * @example
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4])
  *
- *   // Transform each element (must maintain same type)
- *   // Transform each element (must maintain same type) - automatically transactional
+ *   // Transform each element atomically (must maintain same type)
  *   yield* TxChunk.map(txChunk, (n) => n * 2)
  *
  *   const result = yield* TxChunk.get(txChunk)
@@ -1001,26 +1038,27 @@ export const slice: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const map: {
   /**
-   * Maps each element of the `TxChunk` using the provided function.
-   * Note: This only works when the mapped type B is assignable to A.
+   * Maps each element of the `TxChunk` using a function that returns the same
+   * element type.
    *
-   * **Mutation behavior**: This function mutates the original TxChunk by transforming
-   * each element in place. It does not return a new TxChunk reference.
+   * **Mutation behavior**: This function mutates the original `TxChunk` by
+   * transforming each element in place. It does not return a new `TxChunk`
+   * reference.
+   *
+   * **Example** (Mapping elements)
    *
-   * @example
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4])
    *
-   *   // Transform each element (must maintain same type)
-   *   // Transform each element (must maintain same type) - automatically transactional
+   *   // Transform each element atomically (must maintain same type)
    *   yield* TxChunk.map(txChunk, (n) => n * 2)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1028,26 +1066,27 @@ export const map: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(f: (a: NoInfer<A>) => A): (self: TxChunk<A>) => Effect.Effect<void>
   /**
-   * Maps each element of the `TxChunk` using the provided function.
-   * Note: This only works when the mapped type B is assignable to A.
+   * Maps each element of the `TxChunk` using a function that returns the same
+   * element type.
+   *
+   * **Mutation behavior**: This function mutates the original `TxChunk` by
+   * transforming each element in place. It does not return a new `TxChunk`
+   * reference.
    *
-   * **Mutation behavior**: This function mutates the original TxChunk by transforming
-   * each element in place. It does not return a new TxChunk reference.
+   * **Example** (Mapping elements)
    *
-   * @example
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4])
    *
-   *   // Transform each element (must maintain same type)
-   *   // Transform each element (must maintain same type) - automatically transactional
+   *   // Transform each element atomically (must maintain same type)
    *   yield* TxChunk.map(txChunk, (n) => n * 2)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1055,8 +1094,8 @@ export const map: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, f: (a: A) => A): Effect.Effect<void>
 } = dual(
@@ -1070,15 +1109,15 @@ export const map: {
  * **Mutation behavior**: This function mutates the original TxChunk by removing
  * elements that don't match the predicate. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Filtering elements)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5, 6])
  *
- *   // Keep only even numbers
- *   // Keep only even numbers - automatically transactional
+ *   // Keep only even numbers atomically
  *   yield* TxChunk.filter(txChunk, (n) => n % 2 === 0)
  *
  *   const result = yield* TxChunk.get(txChunk)
@@ -1086,8 +1125,8 @@ export const map: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filter: {
   /**
@@ -1096,15 +1135,15 @@ export const filter: {
    * **Mutation behavior**: This function mutates the original TxChunk by removing
    * elements that don't match the predicate. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5, 6])
    *
-   *   // Keep only even numbers
-   *   // Keep only even numbers - automatically transactional
+   *   // Keep only even numbers atomically
    *   yield* TxChunk.filter(txChunk, (n) => n % 2 === 0)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1112,8 +1151,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B extends A>(refinement: (a: A) => a is B): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -1122,15 +1161,15 @@ export const filter: {
    * **Mutation behavior**: This function mutates the original TxChunk by removing
    * elements that don't match the predicate. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5, 6])
    *
-   *   // Keep only even numbers
-   *   // Keep only even numbers - automatically transactional
+   *   // Keep only even numbers atomically
    *   yield* TxChunk.filter(txChunk, (n) => n % 2 === 0)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1138,8 +1177,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(predicate: (a: A) => boolean): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -1148,15 +1187,15 @@ export const filter: {
    * **Mutation behavior**: This function mutates the original TxChunk by removing
    * elements that don't match the predicate. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5, 6])
    *
-   *   // Keep only even numbers
-   *   // Keep only even numbers - automatically transactional
+   *   // Keep only even numbers atomically
    *   yield* TxChunk.filter(txChunk, (n) => n % 2 === 0)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1164,8 +1203,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B extends A>(self: TxChunk<A>, refinement: (a: A) => a is B): Effect.Effect<void>
   /**
@@ -1174,15 +1213,15 @@ export const filter: {
    * **Mutation behavior**: This function mutates the original TxChunk by removing
    * elements that don't match the predicate. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Filtering elements)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3, 4, 5, 6])
    *
-   *   // Keep only even numbers
-   *   // Keep only even numbers - automatically transactional
+   *   // Keep only even numbers atomically
    *   yield* TxChunk.filter(txChunk, (n) => n % 2 === 0)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1190,8 +1229,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, predicate: (a: A) => boolean): Effect.Effect<void>
 } = dual(
@@ -1206,7 +1245,8 @@ export const filter: {
  * **Mutation behavior**: This function mutates the original TxChunk by appending
  * all elements from the other chunk. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Appending another chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -1214,8 +1254,7 @@ export const filter: {
  *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3])
  *   const otherChunk = Chunk.fromIterable([4, 5, 6])
  *
- *   // Append all elements from another chunk
- *   // Append all elements from another chunk - automatically transactional
+ *   // Append all elements from another chunk atomically
  *   yield* TxChunk.appendAll(txChunk, otherChunk)
  *
  *   const result = yield* TxChunk.get(txChunk)
@@ -1223,8 +1262,8 @@ export const filter: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const appendAll: {
   /**
@@ -1233,7 +1272,8 @@ export const appendAll: {
    * **Mutation behavior**: This function mutates the original TxChunk by appending
    * all elements from the other chunk. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Appending another chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -1241,8 +1281,7 @@ export const appendAll: {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3])
    *   const otherChunk = Chunk.fromIterable([4, 5, 6])
    *
-   *   // Append all elements from another chunk
-   *   // Append all elements from another chunk - automatically transactional
+   *   // Append all elements from another chunk atomically
    *   yield* TxChunk.appendAll(txChunk, otherChunk)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1250,8 +1289,8 @@ export const appendAll: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(other: Chunk.Chunk<A>): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -1260,7 +1299,8 @@ export const appendAll: {
    * **Mutation behavior**: This function mutates the original TxChunk by appending
    * all elements from the other chunk. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Appending another chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -1268,8 +1308,7 @@ export const appendAll: {
    *   const txChunk = yield* TxChunk.fromIterable([1, 2, 3])
    *   const otherChunk = Chunk.fromIterable([4, 5, 6])
    *
-   *   // Append all elements from another chunk
-   *   // Append all elements from another chunk - automatically transactional
+   *   // Append all elements from another chunk atomically
    *   yield* TxChunk.appendAll(txChunk, otherChunk)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1277,8 +1316,8 @@ export const appendAll: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, other: Chunk.Chunk<A>): Effect.Effect<void>
 } = dual(
@@ -1293,7 +1332,8 @@ export const appendAll: {
  * **Mutation behavior**: This function mutates the original TxChunk by prepending
  * all elements from the other chunk. It does not return a new TxChunk reference.
  *
- * @example
+ * **Example** (Prepending another chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -1301,8 +1341,7 @@ export const appendAll: {
  *   const txChunk = yield* TxChunk.fromIterable([4, 5, 6])
  *   const otherChunk = Chunk.fromIterable([1, 2, 3])
  *
- *   // Prepend all elements from another chunk
- *   // Prepend all elements from another chunk - automatically transactional
+ *   // Prepend all elements from another chunk atomically
  *   yield* TxChunk.prependAll(txChunk, otherChunk)
  *
  *   const result = yield* TxChunk.get(txChunk)
@@ -1310,8 +1349,8 @@ export const appendAll: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const prependAll: {
   /**
@@ -1320,7 +1359,8 @@ export const prependAll: {
    * **Mutation behavior**: This function mutates the original TxChunk by prepending
    * all elements from the other chunk. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Prepending another chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -1328,8 +1368,7 @@ export const prependAll: {
    *   const txChunk = yield* TxChunk.fromIterable([4, 5, 6])
    *   const otherChunk = Chunk.fromIterable([1, 2, 3])
    *
-   *   // Prepend all elements from another chunk
-   *   // Prepend all elements from another chunk - automatically transactional
+   *   // Prepend all elements from another chunk atomically
    *   yield* TxChunk.prependAll(txChunk, otherChunk)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1337,8 +1376,8 @@ export const prependAll: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(other: Chunk.Chunk<A>): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -1347,7 +1386,8 @@ export const prependAll: {
    * **Mutation behavior**: This function mutates the original TxChunk by prepending
    * all elements from the other chunk. It does not return a new TxChunk reference.
    *
-   * @example
+   * **Example** (Prepending another chunk)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -1355,8 +1395,7 @@ export const prependAll: {
    *   const txChunk = yield* TxChunk.fromIterable([4, 5, 6])
    *   const otherChunk = Chunk.fromIterable([1, 2, 3])
    *
-   *   // Prepend all elements from another chunk
-   *   // Prepend all elements from another chunk - automatically transactional
+   *   // Prepend all elements from another chunk atomically
    *   yield* TxChunk.prependAll(txChunk, otherChunk)
    *
    *   const result = yield* TxChunk.get(txChunk)
@@ -1364,8 +1403,8 @@ export const prependAll: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, other: Chunk.Chunk<A>): Effect.Effect<void>
 } = dual(
@@ -1380,9 +1419,8 @@ export const prependAll: {
  * **Mutation behavior**: This function mutates the original TxChunk by appending
  * all elements from the other TxChunk. It does not return a new TxChunk reference.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Concatenating TxChunks)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -1401,6 +1439,9 @@ export const prependAll: {
  *   console.log(Chunk.toReadonlyArray(original)) // [4, 5, 6]
  * })
  * ```
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export const concat: {
   /**
@@ -1409,9 +1450,8 @@ export const concat: {
    * **Mutation behavior**: This function mutates the original TxChunk by appending
    * all elements from the other TxChunk. It does not return a new TxChunk reference.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Concatenating TxChunks)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -1430,6 +1470,9 @@ export const concat: {
    *   console.log(Chunk.toReadonlyArray(original)) // [4, 5, 6]
    * })
    * ```
+   *
+   * @category combinators
+   * @since 4.0.0
    */
   <A>(other: TxChunk<A>): (self: TxChunk<A>) => Effect.Effect<void>
   /**
@@ -1438,9 +1481,8 @@ export const concat: {
    * **Mutation behavior**: This function mutates the original TxChunk by appending
    * all elements from the other TxChunk. It does not return a new TxChunk reference.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Concatenating TxChunks)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -1459,6 +1501,9 @@ export const concat: {
    *   console.log(Chunk.toReadonlyArray(original)) // [4, 5, 6]
    * })
    * ```
+   *
+   * @category combinators
+   * @since 4.0.0
    */
   <A>(self: TxChunk<A>, other: TxChunk<A>): Effect.Effect<void>
 } = dual(