effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/TxHashSet.ts

@@ -56,21 +56,11 @@ const TxHashSetProto = {
 }
 
 /**
- * A TxHashSet is a transactional hash set data structure that provides atomic operations
- * on unique values within Effect transactions. It uses an immutable HashSet internally
- * with TxRef for transactional semantics, ensuring all operations are performed atomically.
+ * A TxHashSet is a transactional hash set data structure that provides atomic operations on unique values within Effect transactions. It uses an immutable HashSet internally with TxRef for transactional semantics, ensuring all operations are performed atomically.
  *
- * ## Mutation vs Return Behavior
+ * **Details**
  *
- * **Mutation operations** (add, remove, clear) modify the original TxHashSet and return `Effect<void>` or `Effect<boolean>`:
- * - These operations mutate the TxHashSet in place
- * - They do not create new TxHashSet instances
- * - Examples: `add`, `remove`, `clear`
- *
- * **Transform operations** (union, intersection, difference, map, filter) create new TxHashSet instances:
- * - These operations return `Effect<TxHashSet<T>>` with a new instance
- * - The original TxHashSet remains unchanged
- * - Examples: `union`, `intersection`, `difference`, `map`, `filter`
+ * Mutation operations such as `add`, `remove`, and `clear` update the original TxHashSet and return `Effect<void>` or `Effect<boolean>`. Transform operations such as `union`, `intersection`, `difference`, `map`, and `filter` create new TxHashSet instances and leave the original TxHashSet unchanged.
  *
  * **Example** (Using transactional hash sets)
  *
@@ -320,8 +310,9 @@ export const isTxHashSet = (u: unknown): u is TxHashSet<unknown> => hasProperty(
 /**
  * Adds a value to the TxHashSet. If the value already exists, the operation has no effect.
  *
- * **Mutation behavior**: This function mutates the original TxHashSet by adding
- * the specified value. It does not return a new TxHashSet reference.
+ * **Details**
+ *
+ * This function mutates the original TxHashSet by adding the specified value. It does not return a new TxHashSet reference.
  *
  * **Example** (Adding values)
  *
@@ -348,8 +339,9 @@ export const add: {
   /**
    * Adds a value to the TxHashSet. If the value already exists, the operation has no effect.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by adding
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by adding the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Adding values)
    *
@@ -376,8 +368,9 @@ export const add: {
   /**
    * Adds a value to the TxHashSet. If the value already exists, the operation has no effect.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by adding
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by adding the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Adding values)
    *
@@ -405,8 +398,9 @@ export const add: {
   /**
    * Adds a value to the TxHashSet. If the value already exists, the operation has no effect.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by adding
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by adding the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Adding values)
    *
@@ -433,8 +427,9 @@ export const add: {
   /**
    * Adds a value to the TxHashSet. If the value already exists, the operation has no effect.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by adding
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by adding the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Adding values)
    *
@@ -463,8 +458,9 @@ export const add: {
 /**
  * Removes a value from the TxHashSet.
  *
- * **Mutation behavior**: This function mutates the original TxHashSet by removing
- * the specified value. It does not return a new TxHashSet reference.
+ * **Details**
+ *
+ * This function mutates the original TxHashSet by removing the specified value. It does not return a new TxHashSet reference.
  *
  * **Example** (Removing values)
  *
@@ -492,8 +488,9 @@ export const remove: {
   /**
    * Removes a value from the TxHashSet.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by removing
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by removing the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Removing values)
    *
@@ -521,8 +518,9 @@ export const remove: {
   /**
    * Removes a value from the TxHashSet.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by removing
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by removing the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Removing values)
    *
@@ -551,8 +549,9 @@ export const remove: {
   /**
    * Removes a value from the TxHashSet.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by removing
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by removing the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Removing values)
    *
@@ -580,8 +579,9 @@ export const remove: {
   /**
    * Removes a value from the TxHashSet.
    *
-   * **Mutation behavior**: This function mutates the original TxHashSet by removing
-   * the specified value. It does not return a new TxHashSet reference.
+   * **Details**
+   *
+   * This function mutates the original TxHashSet by removing the specified value. It does not return a new TxHashSet reference.
    *
    * **Example** (Removing values)
    *
@@ -861,8 +861,9 @@ export const isEmpty = <V>(self: TxHashSet<V>): Effect.Effect<boolean> =>
 /**
  * Removes all values from the TxHashSet.
  *
- * **Mutation behavior**: This function mutates the original TxHashSet by clearing
- * all values. It does not return a new TxHashSet reference.
+ * **Details**
+ *
+ * This function mutates the original TxHashSet by clearing all values. It does not return a new TxHashSet reference.
  *
  * **Example** (Clearing all values)
  *

package/src/TxPriorityQueue.ts

@@ -24,6 +24,8 @@ const TypeId = "~effect/transactions/TxPriorityQueue"
 /**
  * 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.

package/src/TxPubSub.ts

@@ -366,12 +366,9 @@ export const isShutdown = <A>(self: TxPubSub<A>): Effect.Effect<boolean> => TxRe
 /**
  * Publishes a message to all current subscribers.
  *
- * Returns `true` if the message was delivered to all subscribers, or `false` if
- * the hub is shut down or the message was dropped for any subscriber (dropping strategy).
+ * **Details**
  *
- * For bounded strategy, retries the transaction if any subscriber queue is full.
- * For sliding strategy, drops oldest messages in full subscriber queues.
- * For dropping strategy, drops the message for full subscriber queues and returns `false`.
+ * Returns `true` if the message was delivered to all subscribers, or `false` if the hub is shut down or the message was dropped for any subscriber. For the bounded strategy, the transaction retries if any subscriber queue is full. For the sliding strategy, full subscriber queues drop their oldest messages. For the dropping strategy, full subscriber queues drop the new message and the operation returns `false`.
  *
  * **Example** (Publishing a message to subscribers)
  *
@@ -407,12 +404,9 @@ export const publish: {
   /**
    * Publishes a message to all current subscribers.
    *
-   * Returns `true` if the message was delivered to all subscribers, or `false` if
-   * the hub is shut down or the message was dropped for any subscriber (dropping strategy).
+   * **Details**
    *
-   * For bounded strategy, retries the transaction if any subscriber queue is full.
-   * For sliding strategy, drops oldest messages in full subscriber queues.
-   * For dropping strategy, drops the message for full subscriber queues and returns `false`.
+   * Returns `true` if the message was delivered to all subscribers, or `false` if the hub is shut down or the message was dropped for any subscriber. For the bounded strategy, the transaction retries if any subscriber queue is full. For the sliding strategy, full subscriber queues drop their oldest messages. For the dropping strategy, full subscriber queues drop the new message and the operation returns `false`.
    *
    * **Example** (Publishing a message to subscribers)
    *
@@ -448,12 +442,9 @@ export const publish: {
   /**
    * Publishes a message to all current subscribers.
    *
-   * Returns `true` if the message was delivered to all subscribers, or `false` if
-   * the hub is shut down or the message was dropped for any subscriber (dropping strategy).
+   * **Details**
    *
-   * For bounded strategy, retries the transaction if any subscriber queue is full.
-   * For sliding strategy, drops oldest messages in full subscriber queues.
-   * For dropping strategy, drops the message for full subscriber queues and returns `false`.
+   * Returns `true` if the message was delivered to all subscribers, or `false` if the hub is shut down or the message was dropped for any subscriber. For the bounded strategy, the transaction retries if any subscriber queue is full. For the sliding strategy, full subscriber queues drop their oldest messages. For the dropping strategy, full subscriber queues drop the new message and the operation returns `false`.
    *
    * **Example** (Publishing a message to subscribers)
    *
@@ -503,6 +494,8 @@ export const publish: {
 /**
  * Publishes all messages from an iterable to all current subscribers.
  *
+ * **Details**
+ *
  * Returns `true` if all messages were delivered to all subscribers.
  *
  * **Example** (Publishing multiple messages to subscribers)
@@ -533,6 +526,8 @@ export const publishAll: {
   /**
    * Publishes all messages from an iterable to all current subscribers.
    *
+   * **Details**
+   *
    * Returns `true` if all messages were delivered to all subscribers.
    *
    * **Example** (Publishing multiple messages to subscribers)
@@ -563,6 +558,8 @@ export const publishAll: {
   /**
    * Publishes all messages from an iterable to all current subscribers.
    *
+   * **Details**
+   *
    * Returns `true` if all messages were delivered to all subscribers.
    *
    * **Example** (Publishing multiple messages to subscribers)
@@ -606,13 +603,11 @@ export const publishAll: {
 )
 
 /**
- * Subscribes to the TxPubSub, returning a scoped `TxQueue` for messages
- * published after subscription.
+ * Subscribes to the TxPubSub, returning a scoped `TxQueue` for messages published after subscription.
  *
- * The returned queue uses the hub's capacity strategy: bounded subscriptions
- * backpressure publishers when full, dropping subscriptions may miss new
- * messages when full, and sliding subscriptions may evict older queued
- * messages. The subscription is automatically removed when the scope is closed.
+ * **Details**
+ *
+ * The returned queue uses the hub's capacity strategy: bounded subscriptions backpressure publishers when full, dropping subscriptions may miss new messages when full, and sliding subscriptions may evict older queued messages. The subscription is automatically removed when the scope is closed.
  *
  * **Example** (Subscribing multiple queues)
  *
@@ -649,9 +644,9 @@ export const subscribe = <A>(self: TxPubSub<A>): Effect.Effect<TxQueue.TxQueue<A
 /**
  * Creates a subscriber queue and registers it with the pub/sub.
  *
- * This is the transactional acquire step of `subscribe`, exposed so that
- * callers can compose it with other Tx operations in a single transaction
- * (e.g. `TxSubscriptionRef.changes`).
+ * **Details**
+ *
+ * This is the transactional acquire step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction, such as `TxSubscriptionRef.changes`.
  *
  * @category mutations
  * @since 4.0.0
@@ -668,8 +663,9 @@ export const acquireSubscriber = <A>(
 /**
  * Removes a subscriber queue from the pub/sub and shuts it down.
  *
- * This is the transactional release step of `subscribe`, exposed so that
- * callers can compose it with other Tx operations in a single transaction.
+ * **Details**
+ *
+ * This is the transactional release step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction.
  *
  * @category mutations
  * @since 4.0.0
@@ -678,8 +674,9 @@ export const releaseSubscriber: {
   /**
    * Removes a subscriber queue from the pub/sub and shuts it down.
    *
-   * This is the transactional release step of `subscribe`, exposed so that
-   * callers can compose it with other Tx operations in a single transaction.
+   * **Details**
+   *
+   * This is the transactional release step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction.
    *
    * @category mutations
    * @since 4.0.0
@@ -688,8 +685,9 @@ export const releaseSubscriber: {
   /**
    * Removes a subscriber queue from the pub/sub and shuts it down.
    *
-   * This is the transactional release step of `subscribe`, exposed so that
-   * callers can compose it with other Tx operations in a single transaction.
+   * **Details**
+   *
+   * This is the transactional release step of `subscribe`, exposed so that callers can compose it with other Tx operations in a single transaction.
    *
    * @category mutations
    * @since 4.0.0
@@ -724,12 +722,15 @@ const makeSubscriberQueue = <A>(
 }
 
 /**
- * Shuts down the TxPubSub and all subscriber queues registered at the time of
- * shutdown.
+ * Shuts down the TxPubSub and all subscriber queues registered at the time of shutdown.
+ *
+ * **Details**
+ *
+ * After shutdown, `publish` and `publishAll` return `false`, and `awaitShutdown` completes. The operation is idempotent.
+ *
+ * **Gotchas**
  *
- * After shutdown, `publish` and `publishAll` return `false`, and
- * `awaitShutdown` completes. The operation is idempotent; subscribers acquired
- * after shutdown are not automatically shut down by this call.
+ * Subscribers acquired after shutdown are not automatically shut down by this call.
  *
  * **Example** (Shutting down a pub/sub)
  *