effect 4.0.0-beta.65 → 4.0.0-beta.67

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,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Creating a TxChunk from a chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -118,9 +120,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Creating an empty TxChunk)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -149,9 +152,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Creating from an iterable)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -185,7 +189,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 +199,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 +215,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Modifying while returning a value)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -239,9 +245,10 @@ 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
+   * @since 4.0.0
+   * **Example** (Modifying while returning a value)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -270,9 +277,10 @@ 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
+   * @since 4.0.0
+   * **Example** (Modifying while returning a value)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -310,15 +318,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 +334,8 @@ export const modify: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const update: {
   /**
@@ -336,15 +344,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 +360,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 +370,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 +386,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 +401,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 +419,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 +430,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 +447,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 +457,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 +474,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 +484,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 +501,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 +516,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 +532,8 @@ export const set: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const append: {
   /**
@@ -529,7 +542,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 +558,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 +568,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 +584,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 +599,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 +615,8 @@ export const append: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const prepend: {
   /**
@@ -609,7 +625,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 +641,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 +651,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 +667,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 +679,8 @@ export const prepend: {
 /**
  * Gets the size of the `TxChunk`.
  *
- * @example
+ * **Example** (Getting the size)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -679,8 +698,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 +707,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 +725,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 +734,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 +752,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 +764,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 +780,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 +790,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 +806,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 +816,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 +832,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 +847,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 +863,8 @@ export const take: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const drop: {
   /**
@@ -848,7 +873,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 +889,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 +899,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 +915,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 +930,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 +946,8 @@ export const drop: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const slice: {
   /**
@@ -928,7 +956,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 +972,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 +982,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 +998,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 +1009,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 +1032,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 +1060,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 +1088,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 +1103,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 +1119,8 @@ export const map: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filter: {
   /**
@@ -1096,15 +1129,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 +1145,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 +1155,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 +1171,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 +1181,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 +1197,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 +1207,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 +1223,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 +1239,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 +1248,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 +1256,8 @@ export const filter: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const appendAll: {
   /**
@@ -1233,7 +1266,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 +1275,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 +1283,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 +1293,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 +1302,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 +1310,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 +1326,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 +1335,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 +1343,8 @@ export const appendAll: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const prependAll: {
   /**
@@ -1320,7 +1353,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 +1362,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 +1370,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 +1380,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 +1389,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 +1397,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 +1413,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Concatenating TxChunks)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -1409,9 +1443,10 @@ 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
+   * @since 4.0.0
+   * **Example** (Concatenating TxChunks)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *
@@ -1438,9 +1473,10 @@ 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
+   * @since 4.0.0
+   * **Example** (Concatenating TxChunks)
+   *
    * ```ts
    * import { Chunk, Effect, TxChunk } from "effect"
    *