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

package/dist/TxChunk.d.ts

@@ -24,7 +24,8 @@ declare 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"
  *
@@ -54,8 +55,8 @@ declare 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;
@@ -67,9 +68,8 @@ export interface TxChunk<in out A> extends Inspectable, Pipeable {
  * **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"
  *
@@ -83,6 +83,9 @@ export interface TxChunk<in out A> extends Inspectable, Pipeable {
  *   console.log(Chunk.toReadonlyArray(result)) // [1, 2, 3]
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <A>(initial: Chunk.Chunk<A>) => Effect.Effect<TxChunk<A>>;
 /**
@@ -91,9 +94,8 @@ export declare const make: <A>(initial: Chunk.Chunk<A>) => Effect.Effect<TxChunk
  * **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"
  *
@@ -112,6 +114,9 @@ export declare const make: <A>(initial: Chunk.Chunk<A>) => Effect.Effect<TxChunk
  *   console.log(isStillEmpty) // false
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export declare const empty: <A = never>() => Effect.Effect<TxChunk<A>>;
 /**
@@ -120,9 +125,8 @@ export declare 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"
  *
@@ -146,6 +150,9 @@ export declare 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 declare const fromIterable: <A>(iterable: Iterable<A>) => Effect.Effect<TxChunk<A>>;
 /**
@@ -154,7 +161,8 @@ export declare const fromIterable: <A>(iterable: Iterable<A>) => Effect.Effect<T
  * **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"
  *
@@ -163,8 +171,8 @@ export declare const fromIterable: <A>(iterable: Iterable<A>) => Effect.Effect<T
  * const txChunk = TxChunk.makeUnsafe(ref)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeUnsafe: <A>(ref: TxRef.TxRef<Chunk.Chunk<A>>) => TxChunk<A>;
 /**
@@ -173,9 +181,8 @@ export declare const makeUnsafe: <A>(ref: TxRef.TxRef<Chunk.Chunk<A>>) => TxChun
  * **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"
  *
@@ -194,6 +201,9 @@ export declare const makeUnsafe: <A>(ref: TxRef.TxRef<Chunk.Chunk<A>>) => TxChun
  *   console.log(Chunk.toReadonlyArray(newChunk)) // [1, 2, 3, 4]
  * })
  * ```
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export declare const modify: {
     /**
@@ -202,9 +212,8 @@ export declare 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"
      *
@@ -223,6 +232,9 @@ export declare 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>]): (self: TxChunk<A>) => Effect.Effect<R>;
     /**
@@ -231,9 +243,8 @@ export declare 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"
      *
@@ -252,6 +263,9 @@ export declare const modify: {
      *   console.log(Chunk.toReadonlyArray(newChunk)) // [1, 2, 3, 4]
      * })
      * ```
+     *
+     * @category combinators
+     * @since 4.0.0
      */
     <A, R>(self: TxChunk<A>, f: (current: Chunk.Chunk<A>) => [returnValue: R, newValue: Chunk.Chunk<A>]): Effect.Effect<R>;
 };
@@ -261,15 +275,15 @@ export declare 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)
@@ -277,8 +291,8 @@ export declare const modify: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const update: {
     /**
@@ -287,15 +301,15 @@ export declare 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)
@@ -303,8 +317,8 @@ export declare 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>;
     /**
@@ -313,15 +327,15 @@ export declare 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)
@@ -329,15 +343,16 @@ export declare 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>;
 };
 /**
  * Reads the current chunk from the `TxChunk`.
  *
- * @example
+ * **Example** (Reading the current chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -354,8 +369,8 @@ export declare const update: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const get: <A>(self: TxChunk<A>) => Effect.Effect<Chunk.Chunk<A>>;
 /**
@@ -364,7 +379,8 @@ export declare const get: <A>(self: TxChunk<A>) => Effect.Effect<Chunk.Chunk<A>>
  * **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"
  *
@@ -380,8 +396,8 @@ export declare const get: <A>(self: TxChunk<A>) => Effect.Effect<Chunk.Chunk<A>>
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const set: {
     /**
@@ -390,7 +406,8 @@ export declare 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"
      *
@@ -406,8 +423,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(chunk: Chunk.Chunk<A>): (self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -416,7 +433,8 @@ export declare 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"
      *
@@ -432,8 +450,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, chunk: Chunk.Chunk<A>): Effect.Effect<void>;
 };
@@ -443,7 +461,8 @@ export declare 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"
  *
@@ -458,8 +477,8 @@ export declare const set: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const append: {
     /**
@@ -468,7 +487,8 @@ export declare 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"
      *
@@ -483,8 +503,8 @@ export declare const append: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(element: A): (self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -493,7 +513,8 @@ export declare 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"
      *
@@ -508,8 +529,8 @@ export declare const append: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, element: A): Effect.Effect<void>;
 };
@@ -519,7 +540,8 @@ export declare 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"
  *
@@ -534,8 +556,8 @@ export declare const append: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const prepend: {
     /**
@@ -544,7 +566,8 @@ export declare 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"
      *
@@ -559,8 +582,8 @@ export declare const prepend: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(element: A): (self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -569,7 +592,8 @@ export declare 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"
      *
@@ -584,15 +608,16 @@ export declare const prepend: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, element: A): Effect.Effect<void>;
 };
 /**
  * Gets the size of the `TxChunk`.
  *
- * @example
+ * **Example** (Getting the size)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -610,14 +635,15 @@ export declare const prepend: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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"
  *
@@ -634,14 +660,15 @@ export declare const size: <A>(self: TxChunk<A>) => Effect.Effect<number>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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"
  *
@@ -658,8 +685,8 @@ export declare const isEmpty: <A>(self: TxChunk<A>) => Effect.Effect<boolean>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const isNonEmpty: <A>(self: TxChunk<A>) => Effect.Effect<boolean>;
 /**
@@ -668,7 +695,8 @@ export declare 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"
  *
@@ -683,8 +711,8 @@ export declare const isNonEmpty: <A>(self: TxChunk<A>) => Effect.Effect<boolean>
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const take: {
     /**
@@ -693,7 +721,8 @@ export declare 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"
      *
@@ -708,8 +737,8 @@ export declare const take: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (n: number): <A>(self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -718,7 +747,8 @@ export declare 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"
      *
@@ -733,8 +763,8 @@ export declare const take: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, n: number): Effect.Effect<void>;
 };
@@ -744,7 +774,8 @@ export declare 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"
  *
@@ -759,8 +790,8 @@ export declare const take: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const drop: {
     /**
@@ -769,7 +800,8 @@ export declare 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"
      *
@@ -784,8 +816,8 @@ export declare const drop: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (n: number): <A>(self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -794,7 +826,8 @@ export declare 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"
      *
@@ -809,8 +842,8 @@ export declare const drop: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, n: number): Effect.Effect<void>;
 };
@@ -820,7 +853,8 @@ export declare 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"
  *
@@ -835,8 +869,8 @@ export declare const drop: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const slice: {
     /**
@@ -845,7 +879,8 @@ export declare 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"
      *
@@ -860,8 +895,8 @@ export declare const slice: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (start: number, end: number): <A>(self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -870,7 +905,8 @@ export declare 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"
      *
@@ -885,27 +921,28 @@ export declare const slice: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, start: number, end: number): 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)
@@ -913,26 +950,27 @@ export declare const slice: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare 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)
@@ -940,26 +978,27 @@ export declare 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)
@@ -967,8 +1006,8 @@ export declare const map: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, f: (a: A) => A): Effect.Effect<void>;
 };
@@ -978,15 +1017,15 @@ export declare 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)
@@ -994,8 +1033,8 @@ export declare const map: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const filter: {
     /**
@@ -1004,15 +1043,15 @@ export declare 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)
@@ -1020,8 +1059,8 @@ export declare 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>;
     /**
@@ -1030,15 +1069,15 @@ export declare 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)
@@ -1046,8 +1085,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(predicate: (a: A) => boolean): (self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -1056,15 +1095,15 @@ export declare 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)
@@ -1072,8 +1111,8 @@ export declare 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>;
     /**
@@ -1082,15 +1121,15 @@ export declare 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)
@@ -1098,8 +1137,8 @@ export declare const filter: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, predicate: (a: A) => boolean): Effect.Effect<void>;
 };
@@ -1109,7 +1148,8 @@ export declare 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"
  *
@@ -1117,8 +1157,7 @@ export declare 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)
@@ -1126,8 +1165,8 @@ export declare const filter: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const appendAll: {
     /**
@@ -1136,7 +1175,8 @@ export declare 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"
      *
@@ -1144,8 +1184,7 @@ export declare 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)
@@ -1153,8 +1192,8 @@ export declare const appendAll: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(other: Chunk.Chunk<A>): (self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -1163,7 +1202,8 @@ export declare 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"
      *
@@ -1171,8 +1211,7 @@ export declare 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)
@@ -1180,8 +1219,8 @@ export declare const appendAll: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, other: Chunk.Chunk<A>): Effect.Effect<void>;
 };
@@ -1191,7 +1230,8 @@ export declare 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"
  *
@@ -1199,8 +1239,7 @@ export declare 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)
@@ -1208,8 +1247,8 @@ export declare const appendAll: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const prependAll: {
     /**
@@ -1218,7 +1257,8 @@ export declare 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"
      *
@@ -1226,8 +1266,7 @@ export declare 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)
@@ -1235,8 +1274,8 @@ export declare const prependAll: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(other: Chunk.Chunk<A>): (self: TxChunk<A>) => Effect.Effect<void>;
     /**
@@ -1245,7 +1284,8 @@ export declare 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"
      *
@@ -1253,8 +1293,7 @@ export declare 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)
@@ -1262,8 +1301,8 @@ export declare const prependAll: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: TxChunk<A>, other: Chunk.Chunk<A>): Effect.Effect<void>;
 };
@@ -1273,9 +1312,8 @@ export declare 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"
  *
@@ -1294,6 +1332,9 @@ export declare const prependAll: {
  *   console.log(Chunk.toReadonlyArray(original)) // [4, 5, 6]
  * })
  * ```
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export declare const concat: {
     /**
@@ -1302,9 +1343,8 @@ export declare 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"
      *
@@ -1323,6 +1363,9 @@ export declare 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>;
     /**
@@ -1331,9 +1374,8 @@ export declare 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"
      *
@@ -1352,6 +1394,9 @@ export declare 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>;
 };