effect 4.0.0-beta.66 → 4.0.0-beta.67

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,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Creating a TxChunk from a chunk)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -91,9 +93,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Creating an empty TxChunk)
+ *
  * ```ts
  * import { Effect, TxChunk } from "effect"
  *
@@ -120,9 +123,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Creating from an iterable)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -154,7 +158,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 +168,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 +178,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Modifying while returning a value)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -202,9 +208,10 @@ 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
+     * @since 4.0.0
+     * **Example** (Modifying while returning a value)
+     *
      * ```ts
      * import { Chunk, Effect, TxChunk } from "effect"
      *
@@ -231,9 +238,10 @@ 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
+     * @since 4.0.0
+     * **Example** (Modifying while returning a value)
+     *
      * ```ts
      * import { Chunk, Effect, TxChunk } from "effect"
      *
@@ -261,15 +269,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 +285,8 @@ export declare const modify: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const update: {
     /**
@@ -287,15 +295,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 +311,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 +321,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 +337,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 +363,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 +373,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 +390,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 +400,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 +417,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 +427,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 +444,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 +455,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 +471,8 @@ export declare const set: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const append: {
     /**
@@ -468,7 +481,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 +497,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 +507,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 +523,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 +534,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 +550,8 @@ export declare const append: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const prepend: {
     /**
@@ -544,7 +560,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 +576,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 +586,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 +602,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 +629,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 +654,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 +679,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 +689,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 +705,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 +715,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 +731,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 +741,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 +757,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 +768,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 +784,8 @@ export declare const take: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const drop: {
     /**
@@ -769,7 +794,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 +810,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 +820,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 +836,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 +847,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 +863,8 @@ export declare const drop: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const slice: {
     /**
@@ -845,7 +873,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 +889,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 +899,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 +915,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 +944,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 +972,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 +1000,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 +1011,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 +1027,8 @@ export declare const map: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const filter: {
     /**
@@ -1004,15 +1037,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 +1053,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 +1063,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 +1079,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 +1089,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 +1105,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 +1115,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 +1131,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 +1142,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 +1151,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 +1159,8 @@ export declare const filter: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const appendAll: {
     /**
@@ -1136,7 +1169,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 +1178,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 +1186,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 +1196,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 +1205,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 +1213,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 +1224,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 +1233,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 +1241,8 @@ export declare const appendAll: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const prependAll: {
     /**
@@ -1218,7 +1251,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 +1260,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 +1268,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 +1278,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 +1287,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 +1295,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 +1306,10 @@ 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
+ * @since 4.0.0
+ * **Example** (Concatenating TxChunks)
+ *
  * ```ts
  * import { Chunk, Effect, TxChunk } from "effect"
  *
@@ -1302,9 +1336,10 @@ 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
+     * @since 4.0.0
+     * **Example** (Concatenating TxChunks)
+     *
      * ```ts
      * import { Chunk, Effect, TxChunk } from "effect"
      *
@@ -1331,9 +1366,10 @@ 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
+     * @since 4.0.0
+     * **Example** (Concatenating TxChunks)
+     *
      * ```ts
      * import { Chunk, Effect, TxChunk } from "effect"
      *