TxPriorityQueue.ts

TxPriorityQueue.ts overview

Transactional priority queues whose state is stored in a TxRef. Elements are kept in the order defined by the Order supplied at construction time, and dequeue operations return the first element according to that ordering.

Use TxPriorityQueue when multiple fibers coordinate through a shared queue and queue operations need to compose with other transactional state changes. The retrying peek and take operations wait transactionally when the queue is empty, so they can be combined with other transactional reads and writes in one atomic workflow.

Since v4.0.0

---

Exports Grouped by Category

• constructors
  • empty
  • fromIterable
  • make
• converting
  • toArray
• filtering
  • removeIf
  • retainIf
• getters
  • isEmpty
  • isNonEmpty
  • peek
  • peekOption
  • size
• guards
  • isTxPriorityQueue
• models
  • TxPriorityQueue (interface)
• mutations
  • offer
  • offerAll
  • take
  • takeAll
  • takeOption
  • takeUpTo

---

constructors

empty

Creates an empty TxPriorityQueue with the given ordering.

Example (Creating an empty priority queue)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  const empty = yield* TxPriorityQueue.isEmpty(pq)
  console.log(empty) // true
})

Signature

declare const empty: <A>(order: Order<A>) => Effect.Effect<TxPriorityQueue<A>>

Source

Since v2.0.0

fromIterable

Creates a TxPriorityQueue from an iterable of elements.

Example (Creating a priority queue from an iterable)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [3, 1, 2])
  const first = yield* TxPriorityQueue.take(pq)
  console.log(first) // 1
})

Signature

declare const fromIterable: {
  <A>(order: Order<A>): (iterable: Iterable<A>) => Effect.Effect<TxPriorityQueue<A>>
  <A>(order: Order<A>, iterable: Iterable<A>): Effect.Effect<TxPriorityQueue<A>>
}

Source

Since v2.0.0

make

Creates a TxPriorityQueue from variadic elements.

Example (Creating a priority queue from variadic values)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.make(Order.Number)(3, 1, 2)
  const first = yield* TxPriorityQueue.take(pq)
  console.log(first) // 1
})

Signature

declare const make: <A>(order: Order<A>) => (...elements: Array<A>) => Effect.Effect<TxPriorityQueue<A>>

Source

Since v2.0.0

converting

toArray

Returns all elements in priority order without removing them.

Example (Reading values in priority order)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [3, 1, 2])
  const all = yield* TxPriorityQueue.toArray(pq)
  console.log(all) // [1, 2, 3]
})

Signature

declare const toArray: <A>(self: TxPriorityQueue<A>) => Effect.Effect<Array<A>>

Source

Since v2.0.0

filtering

removeIf

Removes elements matching the predicate.

Example (Removing matching values)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [1, 2, 3, 4, 5])
  yield* TxPriorityQueue.removeIf(pq, (n) => n % 2 === 0)
  const all = yield* TxPriorityQueue.takeAll(pq)
  console.log(all) // [1, 3, 5]
})

Signature

declare const removeIf: {
  <A>(predicate: Predicate<A>): (self: TxPriorityQueue<A>) => Effect.Effect<void>
  <A>(self: TxPriorityQueue<A>, predicate: Predicate<A>): Effect.Effect<void>
}

Source

Since v2.0.0

retainIf

Keeps only elements matching the predicate.

Example (Retaining matching values)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [1, 2, 3, 4, 5])
  yield* TxPriorityQueue.retainIf(pq, (n) => n % 2 === 0)
  const all = yield* TxPriorityQueue.takeAll(pq)
  console.log(all) // [2, 4]
})

Signature

declare const retainIf: {
  <A>(predicate: Predicate<A>): (self: TxPriorityQueue<A>) => Effect.Effect<void>
  <A>(self: TxPriorityQueue<A>, predicate: Predicate<A>): Effect.Effect<void>
}

Source

Since v2.0.0

getters

isEmpty

Returns true if the queue is empty.

Example (Checking whether a queue is empty)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  const empty = yield* TxPriorityQueue.isEmpty(pq)
  console.log(empty) // true
})

Signature

declare const isEmpty: <A>(self: TxPriorityQueue<A>) => Effect.Effect<boolean>

Source

Since v2.0.0

isNonEmpty

Returns true if the queue has at least one element.

Example (Checking whether a queue has elements)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [1])
  const nonEmpty = yield* TxPriorityQueue.isNonEmpty(pq)
  console.log(nonEmpty) // true
})

Signature

declare const isNonEmpty: <A>(self: TxPriorityQueue<A>) => Effect.Effect<boolean>

Source

Since v2.0.0

peek

Observes the smallest element without removing it.

When to use

Use to inspect the next prioritized value and retry transactionally while the queue is empty.

Example (Peeking at the next value)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [3, 1, 2])
  const top = yield* TxPriorityQueue.peek(pq)
  console.log(top) // 1
})

Signature

declare const peek: <A>(self: TxPriorityQueue<A>) => Effect.Effect<A>

Source

Since v2.0.0

peekOption

Observes the smallest element without removing it, returning None when the queue is empty.

When to use

Use to inspect the next prioritized value without retrying on an empty queue.

Example (Peeking without retrying)

import { Effect, Option, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  const result = yield* TxPriorityQueue.peekOption(pq)
  console.log(Option.isNone(result)) // true
})

Signature

declare const peekOption: <A>(self: TxPriorityQueue<A>) => Effect.Effect<Option<A>>

Source

Since v2.0.0

size

Returns the number of elements in the queue.

Example (Getting the queue size)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [1, 2, 3])
  const s = yield* TxPriorityQueue.size(pq)
  console.log(s) // 3
})

Signature

declare const size: <A>(self: TxPriorityQueue<A>) => Effect.Effect<number>

Source

Since v2.0.0

guards

isTxPriorityQueue

Determines if the provided value is a TxPriorityQueue.

Example (Checking for a TxPriorityQueue)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  console.log(TxPriorityQueue.isTxPriorityQueue(pq)) // true
  console.log(TxPriorityQueue.isTxPriorityQueue("nope")) // false
})

Signature

declare const isTxPriorityQueue: (u: unknown) => u is TxPriorityQueue<unknown>

Source

Since v4.0.0

models

TxPriorityQueue (interface)

A transactional priority queue backed by a sorted Chunk.

Details

Elements are stored in ascending order according to the Order provided at construction time. take returns the smallest element, peek observes it without removing.

Example (Dequeuing values by priority)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  yield* TxPriorityQueue.offer(pq, 3)
  yield* TxPriorityQueue.offer(pq, 1)
  yield* TxPriorityQueue.offer(pq, 2)
  const first = yield* TxPriorityQueue.take(pq)
  console.log(first) // 1
})

Signature

export interface TxPriorityQueue<in out A> extends Inspectable, Pipeable {
  readonly [TypeId]: typeof TypeId
  readonly ref: TxRef.TxRef<Chunk<A>>
  readonly ord: Order<A>
}

Source

Since v4.0.0

mutations

offer

Inserts an element into the queue in sorted position.

Example (Offering a value)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  yield* TxPriorityQueue.offer(pq, 2)
  yield* TxPriorityQueue.offer(pq, 1)
  const first = yield* TxPriorityQueue.take(pq)
  console.log(first) // 1
})

Signature

declare const offer: {
  <A>(value: A): (self: TxPriorityQueue<A>) => Effect.Effect<void>
  <A>(self: TxPriorityQueue<A>, value: A): Effect.Effect<void>
}

Source

Since v2.0.0

offerAll

Inserts all elements from an iterable into the queue.

Example (Offering multiple values)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  yield* TxPriorityQueue.offerAll(pq, [3, 1, 2])
  const first = yield* TxPriorityQueue.take(pq)
  console.log(first) // 1
})

Signature

declare const offerAll: {
  <A>(values: Iterable<A>): (self: TxPriorityQueue<A>) => Effect.Effect<void>
  <A>(self: TxPriorityQueue<A>, values: Iterable<A>): Effect.Effect<void>
}

Source

Since v2.0.0

take

Takes the smallest element from the queue. Retries if the queue is empty.

Example (Taking the next value)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [3, 1, 2])
  const first = yield* TxPriorityQueue.take(pq)
  console.log(first) // 1
})

Signature

declare const take: <A>(self: TxPriorityQueue<A>) => Effect.Effect<A>

Source

Since v2.0.0

takeAll

Takes all elements from the queue, returning them in priority order.

Example (Taking all values in priority order)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [3, 1, 2])
  const all = yield* TxPriorityQueue.takeAll(pq)
  console.log(all) // [1, 2, 3]
})

Signature

declare const takeAll: <A>(self: TxPriorityQueue<A>) => Effect.Effect<Array<A>>

Source

Since v2.0.0

takeOption

Tries to take the smallest element. Returns None if the queue is empty.

Example (Taking without retrying)

import { Effect, Option, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.empty<number>(Order.Number)
  const result = yield* TxPriorityQueue.takeOption(pq)
  console.log(Option.isNone(result)) // true
})

Signature

declare const takeOption: <A>(self: TxPriorityQueue<A>) => Effect.Effect<Option<A>>

Source

Since v2.0.0

takeUpTo

Takes up to n elements from the queue in priority order.

Example (Taking up to a limit)

import { Effect, Order, TxPriorityQueue } from "effect"

const program = Effect.gen(function* () {
  const pq = yield* TxPriorityQueue.fromIterable(Order.Number, [5, 3, 1, 4, 2])
  const top2 = yield* TxPriorityQueue.takeUpTo(pq, 2)
  console.log(top2) // [1, 2]
})

Signature

declare const takeUpTo: {
  (n: number): <A>(self: TxPriorityQueue<A>) => Effect.Effect<Array<A>>
  <A>(self: TxPriorityQueue<A>, n: number): Effect.Effect<Array<A>>
}

Source

Since v2.0.0