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

package/src/TxPriorityQueue.ts

@@ -28,7 +28,8 @@ const TypeId = "~effect/transactions/TxPriorityQueue"
  * construction time. `take` returns the smallest element, `peek` observes it
  * without removing.
  *
- * @example
+ * **Example** (Dequeuing values by priority)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -42,8 +43,8 @@ const TypeId = "~effect/transactions/TxPriorityQueue"
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxPriorityQueue<in out A> extends Inspectable, Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -95,7 +96,8 @@ const insertSorted = <A>(chunk: Chunk<A>, value: A, ord: Order<A>): Chunk<A> =>
 /**
  * Creates an empty `TxPriorityQueue` with the given ordering.
  *
- * @example
+ * **Example** (Creating an empty priority queue)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -106,8 +108,8 @@ const insertSorted = <A>(chunk: Chunk<A>, value: A, ord: Order<A>): Chunk<A> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const empty = <A>(order: Order<A>): Effect.Effect<TxPriorityQueue<A>> =>
   Effect.map(TxRef.make<Chunk<A>>(C.empty()), (ref) => makeTxPriorityQueue(ref, order))
@@ -115,7 +117,8 @@ export const empty = <A>(order: Order<A>): Effect.Effect<TxPriorityQueue<A>> =>
 /**
  * Creates a `TxPriorityQueue` from an iterable of elements.
  *
- * @example
+ * **Example** (Creating a priority queue from an iterable)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -126,14 +129,15 @@ export const empty = <A>(order: Order<A>): Effect.Effect<TxPriorityQueue<A>> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromIterable: {
   /**
    * Creates a `TxPriorityQueue` from an iterable of elements.
    *
-   * @example
+   * **Example** (Creating a priority queue from an iterable)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -144,14 +148,15 @@ export const fromIterable: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   <A>(order: Order<A>): (iterable: Iterable<A>) => Effect.Effect<TxPriorityQueue<A>>
   /**
    * Creates a `TxPriorityQueue` from an iterable of elements.
    *
-   * @example
+   * **Example** (Creating a priority queue from an iterable)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -162,8 +167,8 @@ export const fromIterable: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   <A>(order: Order<A>, iterable: Iterable<A>): Effect.Effect<TxPriorityQueue<A>>
 } = dual(
@@ -174,7 +179,8 @@ export const fromIterable: {
       TxRef.make</**
        * Creates a `TxPriorityQueue` from an iterable of elements.
        *
-       * @example
+       * **Example** (Creating a priority queue from an iterable)
+       *
        * ```ts
        * import { Effect, Order, TxPriorityQueue } from "effect"
        *
@@ -185,8 +191,8 @@ export const fromIterable: {
        * })
        * ```
        *
-       * @since 4.0.0
        * @category constructors
+       * @since 4.0.0
        */
       Chunk<A>>(C.fromIterable(arr)),
       (ref) => makeTxPriorityQueue(ref, order)
@@ -197,7 +203,8 @@ export const fromIterable: {
 /**
  * Creates a `TxPriorityQueue` from variadic elements.
  *
- * @example
+ * **Example** (Creating a priority queue from variadic values)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -208,8 +215,8 @@ export const fromIterable: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <A>(order: Order<A>) => (...elements: Array<A>): Effect.Effect<TxPriorityQueue<A>> =>
   fromIterable(order, elements)
@@ -217,7 +224,8 @@ export const make = <A>(order: Order<A>) => (...elements: Array<A>): Effect.Effe
 /**
  * Returns the number of elements in the queue.
  *
- * @example
+ * **Example** (Getting the queue size)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -228,15 +236,16 @@ export const make = <A>(order: Order<A>) => (...elements: Array<A>): Effect.Effe
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const size = <A>(self: TxPriorityQueue<A>): Effect.Effect<number> => Effect.map(TxRef.get(self.ref), C.size)
 
 /**
  * Returns `true` if the queue is empty.
  *
- * @example
+ * **Example** (Checking whether a queue is empty)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -247,15 +256,16 @@ export const size = <A>(self: TxPriorityQueue<A>): Effect.Effect<number> => Effe
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const isEmpty = <A>(self: TxPriorityQueue<A>): Effect.Effect<boolean> => Effect.map(size(self), (n) => n === 0)
 
 /**
  * Returns `true` if the queue has at least one element.
  *
- * @example
+ * **Example** (Checking whether a queue has elements)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -266,8 +276,8 @@ export const isEmpty = <A>(self: TxPriorityQueue<A>): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const isNonEmpty = <A>(self: TxPriorityQueue<A>): Effect.Effect<boolean> => Effect.map(size(self), (n) => n > 0)
 
@@ -275,7 +285,8 @@ export const isNonEmpty = <A>(self: TxPriorityQueue<A>): Effect.Effect<boolean>
  * Observes the smallest element without removing it. Retries if the queue is
  * empty.
  *
- * @example
+ * **Example** (Peeking at the next value)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -286,8 +297,8 @@ export const isNonEmpty = <A>(self: TxPriorityQueue<A>): Effect.Effect<boolean>
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const peek = <A>(self: TxPriorityQueue<A>): Effect.Effect<A> =>
   Effect.gen(function*() {
@@ -303,7 +314,8 @@ export const peek = <A>(self: TxPriorityQueue<A>): Effect.Effect<A> =>
  * Observes the smallest element without removing it. Returns `None` if the
  * queue is empty.
  *
- * @example
+ * **Example** (Peeking without retrying)
+ *
  * ```ts
  * import { Effect, Option, Order, TxPriorityQueue } from "effect"
  *
@@ -314,8 +326,8 @@ export const peek = <A>(self: TxPriorityQueue<A>): Effect.Effect<A> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const peekOption = <A>(self: TxPriorityQueue<A>): Effect.Effect<Option<A>> =>
   Effect.map(TxRef.get(self.ref), C.head)
@@ -323,7 +335,8 @@ export const peekOption = <A>(self: TxPriorityQueue<A>): Effect.Effect<Option<A>
 /**
  * Inserts an element into the queue in sorted position.
  *
- * @example
+ * **Example** (Offering a value)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -336,14 +349,15 @@ export const peekOption = <A>(self: TxPriorityQueue<A>): Effect.Effect<Option<A>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const offer: {
   /**
    * Inserts an element into the queue in sorted position.
    *
-   * @example
+   * **Example** (Offering a value)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -356,14 +370,15 @@ export const offer: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A>(value: A): (self: TxPriorityQueue<A>) => Effect.Effect<void>
   /**
    * Inserts an element into the queue in sorted position.
    *
-   * @example
+   * **Example** (Offering a value)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -376,8 +391,8 @@ export const offer: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A>(self: TxPriorityQueue<A>, value: A): Effect.Effect<void>
 } = dual(
@@ -389,7 +404,8 @@ export const offer: {
 /**
  * Inserts all elements from an iterable into the queue.
  *
- * @example
+ * **Example** (Offering multiple values)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -401,14 +417,15 @@ export const offer: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const offerAll: {
   /**
    * Inserts all elements from an iterable into the queue.
    *
-   * @example
+   * **Example** (Offering multiple values)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -420,14 +437,15 @@ export const offerAll: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A>(values: Iterable<A>): (self: TxPriorityQueue<A>) => Effect.Effect<void>
   /**
    * Inserts all elements from an iterable into the queue.
    *
-   * @example
+   * **Example** (Offering multiple values)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -439,8 +457,8 @@ export const offerAll: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A>(self: TxPriorityQueue<A>, values: Iterable<A>): Effect.Effect<void>
 } = dual(
@@ -455,7 +473,8 @@ export const offerAll: {
 /**
  * Takes the smallest element from the queue. Retries if the queue is empty.
  *
- * @example
+ * **Example** (Taking the next value)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -466,8 +485,8 @@ export const offerAll: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const take = <A>(self: TxPriorityQueue<A>): Effect.Effect<A> =>
   Effect.gen(function*() {
@@ -483,7 +502,8 @@ export const take = <A>(self: TxPriorityQueue<A>): Effect.Effect<A> =>
 /**
  * Takes all elements from the queue, returning them in priority order.
  *
- * @example
+ * **Example** (Taking all values in priority order)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -494,8 +514,8 @@ export const take = <A>(self: TxPriorityQueue<A>): Effect.Effect<A> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const takeAll = <A>(self: TxPriorityQueue<A>): Effect.Effect<Array<A>> =>
   Effect.map(
@@ -506,7 +526,8 @@ export const takeAll = <A>(self: TxPriorityQueue<A>): Effect.Effect<Array<A>> =>
 /**
  * Tries to take the smallest element. Returns `None` if the queue is empty.
  *
- * @example
+ * **Example** (Taking without retrying)
+ *
  * ```ts
  * import { Effect, Option, Order, TxPriorityQueue } from "effect"
  *
@@ -517,8 +538,8 @@ export const takeAll = <A>(self: TxPriorityQueue<A>): Effect.Effect<Array<A>> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const takeOption = <A>(self: TxPriorityQueue<A>): Effect.Effect<Option<A>> =>
   TxRef.modify(self.ref, (chunk) => {
@@ -532,7 +553,8 @@ export const takeOption = <A>(self: TxPriorityQueue<A>): Effect.Effect<Option<A>
 /**
  * Takes up to `n` elements from the queue in priority order.
  *
- * @example
+ * **Example** (Taking up to a limit)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -543,14 +565,15 @@ export const takeOption = <A>(self: TxPriorityQueue<A>): Effect.Effect<Option<A>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const takeUpTo: {
   /**
    * Takes up to `n` elements from the queue in priority order.
    *
-   * @example
+   * **Example** (Taking up to a limit)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -561,14 +584,15 @@ export const takeUpTo: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   (n: number): <A>(self: TxPriorityQueue<A>) => Effect.Effect<Array<A>>
   /**
    * Takes up to `n` elements from the queue in priority order.
    *
-   * @example
+   * **Example** (Taking up to a limit)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -579,8 +603,8 @@ export const takeUpTo: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A>(self: TxPriorityQueue<A>, n: number): Effect.Effect<Array<A>>
 } = dual(
@@ -599,7 +623,8 @@ export const takeUpTo: {
 /**
  * Removes elements matching the predicate.
  *
- * @example
+ * **Example** (Removing matching values)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -611,14 +636,15 @@ export const takeUpTo: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category filtering
+ * @since 4.0.0
  */
 export const removeIf: {
   /**
    * Removes elements matching the predicate.
    *
-   * @example
+   * **Example** (Removing matching values)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -630,14 +656,15 @@ export const removeIf: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A>(predicate: Predicate<A>): (self: TxPriorityQueue<A>) => Effect.Effect<void>
   /**
    * Removes elements matching the predicate.
    *
-   * @example
+   * **Example** (Removing matching values)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -649,8 +676,8 @@ export const removeIf: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A>(self: TxPriorityQueue<A>, predicate: Predicate<A>): Effect.Effect<void>
 } = dual(
@@ -662,7 +689,8 @@ export const removeIf: {
 /**
  * Retains only elements matching the predicate.
  *
- * @example
+ * **Example** (Retaining matching values)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -674,14 +702,15 @@ export const removeIf: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category filtering
+ * @since 4.0.0
  */
 export const retainIf: {
   /**
    * Retains only elements matching the predicate.
    *
-   * @example
+   * **Example** (Retaining matching values)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -693,14 +722,15 @@ export const retainIf: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A>(predicate: Predicate<A>): (self: TxPriorityQueue<A>) => Effect.Effect<void>
   /**
    * Retains only elements matching the predicate.
    *
-   * @example
+   * **Example** (Retaining matching values)
+   *
    * ```ts
    * import { Effect, Order, TxPriorityQueue } from "effect"
    *
@@ -712,8 +742,8 @@ export const retainIf: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A>(self: TxPriorityQueue<A>, predicate: Predicate<A>): Effect.Effect<void>
 } = dual(
@@ -725,7 +755,8 @@ export const retainIf: {
 /**
  * Returns all elements in priority order without removing them.
  *
- * @example
+ * **Example** (Reading values in priority order)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -736,8 +767,8 @@ export const retainIf: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category conversions
+ * @since 4.0.0
  */
 export const toArray = <A>(self: TxPriorityQueue<A>): Effect.Effect<Array<A>> =>
   Effect.map(TxRef.get(self.ref), C.toArray)
@@ -745,7 +776,8 @@ export const toArray = <A>(self: TxPriorityQueue<A>): Effect.Effect<Array<A>> =>
 /**
  * Determines if the provided value is a `TxPriorityQueue`.
  *
- * @example
+ * **Example** (Checking for a TxPriorityQueue)
+ *
  * ```ts
  * import { Effect, Order, TxPriorityQueue } from "effect"
  *
@@ -756,7 +788,7 @@ export const toArray = <A>(self: TxPriorityQueue<A>): Effect.Effect<Array<A>> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxPriorityQueue = (u: unknown): u is TxPriorityQueue<unknown> => hasProperty(u, TypeId)