effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/PubSub.ts

@@ -660,8 +660,8 @@ export const capacity = <A>(self: PubSub<A>): number => self.pubsub.capacity
  */
 export const size = <A>(self: PubSub<A>): Effect.Effect<number> => Effect.sync(() => sizeUnsafe(self))
 /**
- * Synchronously returns the current number of messages retained by the `PubSub`
- * for active subscribers.
+ * Returns the current number of messages retained by the `PubSub` for active
+ * subscribers synchronously.
  *
  * **Details**
  *
@@ -808,7 +808,8 @@ export const shutdown = <A>(self: PubSub<A>): Effect.Effect<void> =>
   }))
 
 /**
- * Returns `true` if `shutdown` has been called, otherwise returns `false`.
+ * Checks effectfully whether `shutdown` has been called, returning `true`
+ * after shutdown and `false` otherwise.
  *
  * **Example** (Checking whether a PubSub is shutdown)
  *
@@ -836,7 +837,8 @@ export const shutdown = <A>(self: PubSub<A>): Effect.Effect<void> =>
 export const isShutdown = <A>(self: PubSub<A>): Effect.Effect<boolean> => Effect.sync(() => isShutdownUnsafe(self))
 
 /**
- * Returns `true` if `shutdown` has been called, otherwise returns `false`.
+ * Checks synchronously whether `shutdown` has been called, returning `true`
+ * after shutdown and `false` otherwise.
  *
  * **Example** (Checking shutdown synchronously)
  *
@@ -897,14 +899,19 @@ export const isShutdownUnsafe = <A>(self: PubSub<A>): boolean => self.shutdownFl
 export const awaitShutdown = <A>(self: PubSub<A>): Effect.Effect<void> => self.shutdownHook.await
 
 /**
- * Attempts to publish a message synchronously without applying the PubSub
- * strategy's effectful surplus handling.
+ * Publishes a message to the `PubSub` as an `Effect`, returning whether the
+ * message was accepted.
+ *
+ * **When to use**
+ *
+ * Use when publishing from effectful code and the configured PubSub strategy
+ * should handle surplus messages.
  *
  * **Details**
  *
- * Returns `false` if the `PubSub` is shut down or the message cannot be
- * accepted immediately, for example when a bounded PubSub is full. Prefer
- * `publish` when backpressure or sliding behavior should be honored.
+ * The effect succeeds with `false` if the `PubSub` is shut down. If the message
+ * cannot be accepted immediately, the configured strategy decides how surplus
+ * messages are handled.
  *
  * **Example** (Publishing a message)
  *
@@ -928,19 +935,26 @@ export const awaitShutdown = <A>(self: PubSub<A>): Effect.Effect<void> => self.s
  * })
  * ```
  *
+ * @see {@link publishUnsafe} for a synchronous non-blocking attempt that does not run effectful surplus handling
+ *
  * @category publishing
  * @since 2.0.0
  */
 export const publish: {
   /**
-   * Attempts to publish a message synchronously without applying the PubSub
-   * strategy's effectful surplus handling.
+   * Publishes a message to the `PubSub` as an `Effect`, returning whether the
+   * message was accepted.
+   *
+   * **When to use**
+   *
+   * Use when publishing from effectful code and the configured PubSub strategy
+   * should handle surplus messages.
    *
    * **Details**
    *
-   * Returns `false` if the `PubSub` is shut down or the message cannot be
-   * accepted immediately, for example when a bounded PubSub is full. Prefer
-   * `publish` when backpressure or sliding behavior should be honored.
+   * The effect succeeds with `false` if the `PubSub` is shut down. If the message
+   * cannot be accepted immediately, the configured strategy decides how surplus
+   * messages are handled.
    *
    * **Example** (Publishing a message)
    *
@@ -964,19 +978,26 @@ export const publish: {
    * })
    * ```
    *
+   * @see {@link publishUnsafe} for a synchronous non-blocking attempt that does not run effectful surplus handling
+   *
    * @category publishing
    * @since 2.0.0
    */
   <A>(value: A): (self: PubSub<A>) => Effect.Effect<boolean>
   /**
-   * Attempts to publish a message synchronously without applying the PubSub
-   * strategy's effectful surplus handling.
+   * Publishes a message to the `PubSub` as an `Effect`, returning whether the
+   * message was accepted.
+   *
+   * **When to use**
+   *
+   * Use when publishing from effectful code and the configured PubSub strategy
+   * should handle surplus messages.
    *
    * **Details**
    *
-   * Returns `false` if the `PubSub` is shut down or the message cannot be
-   * accepted immediately, for example when a bounded PubSub is full. Prefer
-   * `publish` when backpressure or sliding behavior should be honored.
+   * The effect succeeds with `false` if the `PubSub` is shut down. If the message
+   * cannot be accepted immediately, the configured strategy decides how surplus
+   * messages are handled.
    *
    * **Example** (Publishing a message)
    *
@@ -1000,6 +1021,8 @@ export const publish: {
    * })
    * ```
    *
+   * @see {@link publishUnsafe} for a synchronous non-blocking attempt that does not run effectful surplus handling
+   *
    * @category publishing
    * @since 2.0.0
    */
@@ -1024,8 +1047,19 @@ export const publish: {
   }))
 
 /**
- * Publishes a message to the `PubSub`, returning whether the message was published
- * to the `PubSub`.
+ * Attempts to publish a message synchronously without applying the PubSub
+ * strategy's effectful surplus handling.
+ *
+ * **When to use**
+ *
+ * Use when you need a non-blocking synchronous publish attempt and can handle
+ * `false` when the message cannot be accepted immediately.
+ *
+ * **Details**
+ *
+ * Returns `false` if the `PubSub` is shut down or the message cannot be
+ * accepted immediately, for example when a bounded PubSub is full. Prefer
+ * `publish` when backpressure or sliding behavior should be honored.
  *
  * **Example** (Publishing without suspending)
  *
@@ -1049,13 +1083,26 @@ export const publish: {
  * console.log(`Published ${publishedCount} out of ${messages.length} messages`)
  * ```
  *
+ * @see {@link publish} for effectful publishing that honors the configured surplus strategy
+ *
  * @category publishing
  * @since 4.0.0
  */
 export const publishUnsafe: {
   /**
-   * Publishes a message to the `PubSub`, returning whether the message was published
-   * to the `PubSub`.
+   * Attempts to publish a message synchronously without applying the PubSub
+   * strategy's effectful surplus handling.
+   *
+   * **When to use**
+   *
+   * Use when you need a non-blocking synchronous publish attempt and can handle
+   * `false` when the message cannot be accepted immediately.
+   *
+   * **Details**
+   *
+   * Returns `false` if the `PubSub` is shut down or the message cannot be
+   * accepted immediately, for example when a bounded PubSub is full. Prefer
+   * `publish` when backpressure or sliding behavior should be honored.
    *
    * **Example** (Publishing without suspending)
    *
@@ -1079,13 +1126,26 @@ export const publishUnsafe: {
    * console.log(`Published ${publishedCount} out of ${messages.length} messages`)
    * ```
    *
+   * @see {@link publish} for effectful publishing that honors the configured surplus strategy
+   *
    * @category publishing
    * @since 4.0.0
    */
   <A>(value: A): (self: PubSub<A>) => boolean
   /**
-   * Publishes a message to the `PubSub`, returning whether the message was published
-   * to the `PubSub`.
+   * Attempts to publish a message synchronously without applying the PubSub
+   * strategy's effectful surplus handling.
+   *
+   * **When to use**
+   *
+   * Use when you need a non-blocking synchronous publish attempt and can handle
+   * `false` when the message cannot be accepted immediately.
+   *
+   * **Details**
+   *
+   * Returns `false` if the `PubSub` is shut down or the message cannot be
+   * accepted immediately, for example when a bounded PubSub is full. Prefer
+   * `publish` when backpressure or sliding behavior should be honored.
    *
    * **Example** (Publishing without suspending)
    *
@@ -1109,6 +1169,8 @@ export const publishUnsafe: {
    * console.log(`Published ${publishedCount} out of ${messages.length} messages`)
    * ```
    *
+   * @see {@link publish} for effectful publishing that honors the configured surplus strategy
+   *
    * @category publishing
    * @since 4.0.0
    */
@@ -1744,13 +1806,18 @@ const takeRemainderLoop = <A>(
 }
 
 /**
- * Synchronously checks how many messages can be taken from a subscription.
+ * Returns the number of messages currently available in the subscription as an
+ * `Effect`.
+ *
+ * **When to use**
+ *
+ * Use when checking a subscription from effectful code and shutdown should
+ * interrupt the effect.
  *
  * **Details**
  *
- * Returns `Option.some(count)` while the subscription is active, including
- * replay-buffered messages, and `Option.none()` after the subscription has
- * been shut down. Prefer `remaining` in effectful code.
+ * The count includes replay-buffered messages. If the subscription has been
+ * shut down, the effect interrupts.
  *
  * **Example** (Checking remaining messages)
  *
@@ -1779,6 +1846,8 @@ const takeRemainderLoop = <A>(
  * })
  * ```
  *
+ * @see {@link remainingUnsafe} for a synchronous check that reports shutdown as `Option.none()`
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -1790,7 +1859,13 @@ export const remaining = <A>(self: Subscription<A>): Effect.Effect<number> =>
   )
 
 /**
- * Returns the number of messages currently available in the subscription.
+ * Synchronously returns the number of messages currently available in the
+ * subscription, or `Option.none()` when it is shut down.
+ *
+ * **When to use**
+ *
+ * Use when polling from synchronous code and you can handle the `Option.none()`
+ * shutdown case directly.
  *
  * **Example** (Checking remaining messages synchronously)
  *
@@ -1813,6 +1888,8 @@ export const remaining = <A>(self: Subscription<A>): Effect.Effect<number> =>
  * }
  * ```
  *
+ * @see {@link remaining} for the effectful variant that interrupts on shutdown
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -2695,11 +2772,7 @@ const ensureCapacity = (capacity: number): void => {
 // -----------------------------------------------------------------------------
 
 /**
- * A strategy that applies back pressure to publishers when the `PubSub` is at
- * capacity. This guarantees that all subscribers will receive all messages
- * published to the `PubSub` while they are subscribed. However, it creates the
- * risk that a slow subscriber will slow down the rate at which messages
- * are published and received by other subscribers.
+ * Represents the back-pressure strategy for bounded `PubSub` values.
  *
  * **When to use**
  *
@@ -2707,6 +2780,15 @@ const ensureCapacity = (capacity: number): void => {
  * `PubSub` should make publishers wait for capacity instead of dropping or
  * evicting messages.
  *
+ * **Details**
+ *
+ * Publishers wait when the `PubSub` is at capacity, so all current subscribers
+ * can receive every published message.
+ *
+ * **Gotchas**
+ *
+ * A slow subscriber can slow down publishers and other subscribers.
+ *
  * @see {@link bounded} for creating bounded PubSubs with back pressure by default
  * @see {@link DroppingStrategy} for dropping new messages when capacity is full
  * @see {@link SlidingStrategy} for evicting old messages when capacity is full
@@ -2807,12 +2889,21 @@ export class BackPressureStrategy<in out A> implements PubSub.Strategy<A> {
 }
 
 /**
- * A strategy that drops new messages when the `PubSub` is at capacity. This
- * guarantees that a slow subscriber will not slow down the rate at which
- * messages are published. However, it creates the risk that a slow
- * subscriber will slow down the rate at which messages are received by
- * other subscribers and that subscribers may not receive all messages
- * published to the `PubSub` while they are subscribed.
+ * Represents the dropping strategy for bounded `PubSub` values.
+ *
+ * **When to use**
+ *
+ * Use to keep publishers fast by dropping new messages when the `PubSub` is at
+ * capacity.
+ *
+ * **Details**
+ *
+ * A publish that arrives while the `PubSub` is full is dropped instead of
+ * waiting for capacity.
+ *
+ * **Gotchas**
+ *
+ * Subscribers may miss messages published while they are subscribed.
  *
  * **Example** (Using a dropping strategy)
  *
@@ -2885,11 +2976,21 @@ export class DroppingStrategy<in out A> implements PubSub.Strategy<A> {
 }
 
 /**
- * A strategy that adds new messages and drops old messages when the `PubSub` is
- * at capacity. This guarantees that a slow subscriber will not slow down
- * the rate at which messages are published and received by other
- * subscribers. However, it creates the risk that a slow subscriber will
- * not receive some messages published to the `PubSub` while it is subscribed.
+ * Represents the sliding strategy for bounded `PubSub` values.
+ *
+ * **When to use**
+ *
+ * Use to keep the most recent messages when the `PubSub` is at capacity.
+ *
+ * **Details**
+ *
+ * New messages are accepted by evicting older messages from the bounded
+ * `PubSub`.
+ *
+ * **Gotchas**
+ *
+ * Slow subscribers may miss older messages that are evicted before they are
+ * consumed.
  *
  * **Example** (Using a sliding strategy)
  *

package/src/Pull.ts

@@ -236,7 +236,7 @@ export const catchDone: {
   internalEffect.catchCauseFilter(effect, filterDoneLeftover as any, (l: any) => f(l)) as any)
 
 /**
- * Checks if a Cause contains any done errors.
+ * Checks whether a Cause contains any done errors.
  *
  * **When to use**
  *

package/src/Queue.ts

@@ -657,7 +657,7 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
 export const unbounded = <A, E = never>(): Effect<Queue<A, E>> => make()
 
 /**
- * Add a message to the queue. Returns `false` if the queue is done.
+ * Adds a message to the queue. Returns `false` if the queue is done.
  *
  * **Details**
  *
@@ -714,7 +714,7 @@ export const offer = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>): Eff
   })
 
 /**
- * Add a message to the queue synchronously. Returns `false` if the queue is done.
+ * Adds a message to the queue synchronously. Returns `false` if the queue is done.
  *
  * **Gotchas**
  *
@@ -765,7 +765,7 @@ export const offerUnsafe = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>
 }
 
 /**
- * Add multiple messages to the queue. Returns the remaining messages that
+ * Adds multiple messages to the queue. Returns the remaining messages that
  * were not added.
  *
  * **Details**
@@ -806,7 +806,7 @@ export const offerAll = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effe
   })
 
 /**
- * Add multiple messages to the queue synchronously. Returns the remaining messages that
+ * Adds multiple messages to the queue synchronously. Returns the remaining messages that
  * were not added.
  *
  * **Gotchas**
@@ -870,7 +870,7 @@ export const offerAllUnsafe = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>)
 }
 
 /**
- * Fail the queue with an error. If the queue is already done, `false` is
+ * Fails the queue with an error. If the queue is already done, `false` is
  * returned.
  *
  * **Example** (Failing queues with an error)
@@ -897,7 +897,7 @@ export const offerAllUnsafe = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>)
 export const fail = <A, E>(self: Enqueue<A, E>, error: E) => failCause(self, core.causeFail(error))
 
 /**
- * Fail the queue with a cause. If the queue is already done, `false` is
+ * Fails the queue with a cause. If the queue is already done, `false` is
  * returned.
  *
  * **Example** (Failing queues with a cause)
@@ -923,7 +923,7 @@ export const fail = <A, E>(self: Enqueue<A, E>, error: E) => failCause(self, cor
  */
 export const failCause: {
   /**
-   * Fail the queue with a cause. If the queue is already done, `false` is
+   * Fails the queue with a cause. If the queue is already done, `false` is
    * returned.
    *
    * **Example** (Failing queues with a cause)
@@ -949,7 +949,7 @@ export const failCause: {
    */
   <E>(cause: Cause<E>): <A>(self: Enqueue<A, E>) => Effect<boolean>
   /**
-   * Fail the queue with a cause. If the queue is already done, `false` is
+   * Fails the queue with a cause. If the queue is already done, `false` is
    * returned.
    *
    * **Example** (Failing queues with a cause)
@@ -981,7 +981,7 @@ export const failCause: {
 )
 
 /**
- * Fail the queue with a cause synchronously. If the queue is already done, `false` is
+ * Fails the queue with a cause synchronously. If the queue is already done, `false` is
  * returned.
  *
  * **Gotchas**
@@ -1027,8 +1027,16 @@ export const failCauseUnsafe = <A, E>(self: Enqueue<A, E>, cause: Cause<E>): boo
 }
 
 /**
- * Signal that the queue is complete. If the queue is already done, `false` is
- * returned.
+ * Signals queue completion.
+ *
+ * **When to use**
+ *
+ * Use to stop accepting new offers while allowing already queued messages to be
+ * consumed.
+ *
+ * **Details**
+ *
+ * Returns `false` if the queue is already done.
  *
  * **Example** (Ending queues)
  *
@@ -1062,8 +1070,16 @@ export const failCauseUnsafe = <A, E>(self: Enqueue<A, E>, cause: Cause<E>): boo
 export const end = <A, E>(self: Enqueue<A, E | Done>): Effect<boolean> => failCause(self, core.causeFail(core.Done()))
 
 /**
- * Signal that the queue is complete synchronously. If the queue is already done, `false` is
- * returned.
+ * Signals queue completion synchronously.
+ *
+ * **When to use**
+ *
+ * Use when implementing low-level queue integrations that must complete a queue
+ * without wrapping the operation in `Effect`.
+ *
+ * **Details**
+ *
+ * Returns `false` if the queue is already done.
  *
  * **Gotchas**
  *
@@ -1205,7 +1221,7 @@ export const shutdown = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
   })
 
 /**
- * Drains and returns all currently buffered messages without waiting for more.
+ * Takes and returns all currently buffered messages without waiting for more.
  *
  * **Details**
  *
@@ -1237,7 +1253,7 @@ export const shutdown = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 4.0.0
  */
 export const clear = <A, E>(self: Dequeue<A, E>): Effect<Array<A>, Pull.ExcludeDone<E>> =>
@@ -1286,7 +1302,7 @@ export const takeAll = <A, E>(self: Dequeue<A, E>): Effect<Arr.NonEmptyArray<A>,
   takeBetween(self, 1, Number.POSITIVE_INFINITY) as any
 
 /**
- * Take all messages from the queue, until the queue has errored or is done.
+ * Takes all messages from the queue, until the queue has errored or is done.
  *
  * **Example** (Collecting values until completion)
  *
@@ -1420,7 +1436,7 @@ export const takeBetween = <A, E>(
   )
 
 /**
- * Take a single message from the queue, or wait for a message to be
+ * Takes a single message from the queue, or wait for a message to be
  * available.
  *
  * **Details**
@@ -1511,7 +1527,7 @@ export const poll = <A, E>(self: Dequeue<A, E>): Effect<Option.Option<A>> =>
   })
 
 /**
- * Views the next item without removing it.
+ * Peeks at the next item without removing it.
  *
  * **Details**
  *
@@ -1532,7 +1548,7 @@ export const poll = <A, E>(self: Dequeue<A, E>): Effect<Option.Option<A>> =>
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 4.0.0
  */
 export const peek = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
@@ -1692,7 +1708,7 @@ export {
 export const size = <A, E>(self: Dequeue<A, E>): Effect<number> => internalEffect.sync(() => sizeUnsafe(self))
 
 /**
- * Check if the queue is full.
+ * Checks whether the queue is full.
  *
  * **Example** (Checking if queues are full)
  *
@@ -1760,7 +1776,7 @@ export const isFull = <A, E>(self: Dequeue<A, E>): Effect<boolean> => internalEf
 export const sizeUnsafe = <A, E>(self: Dequeue<A, E>): number => self.state._tag === "Done" ? 0 : self.messages.length
 
 /**
- * Check if the queue is full synchronously.
+ * Checks whether the queue is full synchronously.
  *
  * **Example** (Checking fullness synchronously)
  *
@@ -1785,7 +1801,7 @@ export const sizeUnsafe = <A, E>(self: Dequeue<A, E>): number => self.state._tag
 export const isFullUnsafe = <A, E>(self: Dequeue<A, E>): boolean => sizeUnsafe(self) === self.capacity
 
 /**
- * Run an `Effect` into a `Queue`, where success ends the queue and failure
+ * Runs an `Effect` into a `Queue`, where success ends the queue and failure
  * fails the queue.
  *
  * **Example** (Running effects into queues)
@@ -1820,7 +1836,7 @@ export const isFullUnsafe = <A, E>(self: Dequeue<A, E>): boolean => sizeUnsafe(s
  */
 export const into: {
   /**
-   * Run an `Effect` into a `Queue`, where success ends the queue and failure
+   * Runs an `Effect` into a `Queue`, where success ends the queue and failure
    * fails the queue.
    *
    * **Example** (Running effects into queues)
@@ -1857,7 +1873,7 @@ export const into: {
     effect: Effect<AX, EX, RX>
   ) => Effect<boolean, never, RX>
   /**
-   * Run an `Effect` into a `Queue`, where success ends the queue and failure
+   * Runs an `Effect` into a `Queue`, where success ends the queue and failure
    * fails the queue.
    *
    * **Example** (Running effects into queues)

package/src/RcMap.ts

@@ -195,7 +195,7 @@ const makeUnsafe = <K, A, E>(options: {
 })
 
 /**
- * An `RcMap` can contain multiple reference counted resources that can be indexed
+ * Creates an `RcMap` that can contain multiple reference counted resources that can be indexed
  * by a key. The resources are lazily acquired on the first call to `get` and
  * released when the last reference is released.
  *
@@ -242,7 +242,7 @@ const makeUnsafe = <K, A, E>(options: {
  */
 export const make: {
   /**
-   * An `RcMap` can contain multiple reference counted resources that can be indexed
+   * Creates an `RcMap` that can contain multiple reference counted resources that can be indexed
    * by a key. The resources are lazily acquired on the first call to `get` and
    * released when the last reference is released.
    *
@@ -295,7 +295,7 @@ export const make: {
     }
   ): Effect.Effect<RcMap<K, A, E>, never, Scope.Scope | R>
   /**
-   * An `RcMap` can contain multiple reference counted resources that can be indexed
+   * Creates an `RcMap` that can contain multiple reference counted resources that can be indexed
    * by a key. The resources are lazily acquired on the first call to `get` and
    * released when the last reference is released.
    *