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

package/dist/PubSub.js

@@ -5,20 +5,22 @@
  * can subscribe to receive those messages. PubSub supports various backpressure strategies,
  * message replay, and concurrent access from multiple producers and consumers.
  *
- * @example
+ * **Example** (Creating and using a PubSub)
+ *
  * ```ts
  * import { Effect, PubSub } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const pubsub = yield* PubSub.bounded<string>(10)
  *
- *   // Publisher
- *   yield* PubSub.publish(pubsub, "Hello")
- *   yield* PubSub.publish(pubsub, "World")
- *
- *   // Subscriber
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Publisher
+ *     yield* PubSub.publish(pubsub, "Hello")
+ *     yield* PubSub.publish(pubsub, "World")
+ *
+ *     // Subscriber
  *     const message1 = yield* PubSub.take(subscription)
  *     const message2 = yield* PubSub.take(subscription)
  *     console.log(message1, message2) // "Hello", "World"
@@ -46,7 +48,8 @@ const SubscriptionTypeId = "~effect/PubSub/Subscription";
 /**
  * Creates a PubSub with a custom atomic implementation and strategy.
  *
- * @example
+ * **Example** (Creating a PubSub with a custom strategy)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -63,22 +66,25 @@ const SubscriptionTypeId = "~effect/PubSub/Subscription";
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = options => Effect.sync(() => makePubSubUnsafe(options.atomicPubSub(), new Map(), Scope.makeUnsafe(), Latch.makeUnsafe(false), MutableRef.make(false), options.strategy()));
 /**
- * Creates a bounded PubSub with backpressure strategy.
+ * Creates a bounded `PubSub` that applies backpressure when it reaches
+ * capacity.
  *
- * The PubSub will retain messages until they have been taken by all subscribers.
- * When the PubSub reaches capacity, publishers will be suspended until space becomes available.
- * This ensures message delivery guarantees but may slow down fast publishers.
+ * Published messages are retained until all current subscribers have taken
+ * them. When the capacity is full, publishers suspend until space is available.
+ * Pass an options object to configure both `capacity` and an optional replay
+ * buffer for late subscribers.
  *
  * @param capacity - The maximum number of messages the PubSub can hold, or an options object
  *                   with capacity and optional replay buffer size
  * @returns An Effect that creates a bounded PubSub
  *
- * @example
+ * **Example** (Creating a bounded PubSub)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -95,8 +101,8 @@ export const make = options => Effect.sync(() => makePubSubUnsafe(options.atomic
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const bounded = capacity => make({
   atomicPubSub: () => makeAtomicBounded(capacity),
@@ -108,7 +114,8 @@ export const bounded = capacity => make({
  *
  * For best performance use capacities that are powers of two.
  *
- * @example
+ * **Example** (Dropping messages when full)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -123,17 +130,24 @@ export const bounded = capacity => make({
  *     replay: 5
  *   })
  *
- *   // Fill the PubSub and see dropping behavior
- *   yield* PubSub.publish(pubsub, "msg1") // succeeds
- *   yield* PubSub.publish(pubsub, "msg2") // succeeds
- *   yield* PubSub.publish(pubsub, "msg3") // succeeds
- *   const dropped = yield* PubSub.publish(pubsub, "msg4") // returns false (dropped)
- *   console.log("Message dropped:", !dropped)
+ *   yield* Effect.scoped(Effect.gen(function*() {
+ *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Fill the PubSub and see dropping behavior
+ *     yield* PubSub.publish(pubsub, "msg1") // succeeds
+ *     yield* PubSub.publish(pubsub, "msg2") // succeeds
+ *     yield* PubSub.publish(pubsub, "msg3") // succeeds
+ *     const dropped = yield* PubSub.publish(pubsub, "msg4") // returns false (dropped)
+ *     console.log("Message dropped:", !dropped) // true
+ *
+ *     const messages = yield* PubSub.takeAll(subscription)
+ *     console.log(messages) // ["msg1", "msg2", "msg3"]
+ *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const dropping = capacity => make({
   atomicPubSub: () => makeAtomicBounded(capacity),
@@ -145,7 +159,8 @@ export const dropping = capacity => make({
  *
  * For best performance use capacities that are powers of two.
  *
- * @example
+ * **Example** (Sliding old messages when full)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -160,22 +175,23 @@ export const dropping = capacity => make({
  *     replay: 2
  *   })
  *
- *   // Fill and overflow the PubSub
- *   yield* PubSub.publish(pubsub, "msg1")
- *   yield* PubSub.publish(pubsub, "msg2")
- *   yield* PubSub.publish(pubsub, "msg3")
- *   yield* PubSub.publish(pubsub, "msg4") // "msg1" is evicted
- *
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Fill and overflow the PubSub
+ *     yield* PubSub.publish(pubsub, "msg1")
+ *     yield* PubSub.publish(pubsub, "msg2")
+ *     yield* PubSub.publish(pubsub, "msg3")
+ *     yield* PubSub.publish(pubsub, "msg4") // "msg1" is evicted
+ *
  *     const messages = yield* PubSub.takeAll(subscription)
  *     console.log(messages) // ["msg2", "msg3", "msg4"]
  *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const sliding = capacity => make({
   atomicPubSub: () => makeAtomicBounded(capacity),
@@ -184,7 +200,8 @@ export const sliding = capacity => make({
 /**
  * Creates an unbounded `PubSub`.
  *
- * @example
+ * **Example** (Creating an unbounded PubSub)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -198,21 +215,22 @@ export const sliding = capacity => make({
  *     replay: 10
  *   })
  *
- *   // Can publish unlimited messages
- *   for (let i = 0; i < 1000; i++) {
- *     yield* PubSub.publish(pubsub, `message-${i}`)
- *   }
- *
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Can publish unlimited messages
+ *     for (let i = 0; i < 3; i++) {
+ *       yield* PubSub.publish(pubsub, `message-${i}`)
+ *     }
+ *
  *     const message = yield* PubSub.take(subscription)
- *     console.log("First message:", message)
+ *     console.log("First message:", message) // "message-0"
  *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const unbounded = options => make({
   atomicPubSub: () => makeAtomicUnbounded(options),
@@ -221,8 +239,8 @@ export const unbounded = options => make({
 /**
  * Creates a bounded atomic PubSub implementation with optional replay buffer.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeAtomicBounded = capacity => {
   const options = typeof capacity === "number" ? {
@@ -241,14 +259,15 @@ export const makeAtomicBounded = capacity => {
 /**
  * Creates an unbounded atomic PubSub implementation with optional replay buffer.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeAtomicUnbounded = options => new UnboundedPubSub(options?.replay ? new ReplayBuffer(options.replay) : undefined);
 /**
  *  Returns the number of elements the queue can hold.
  *
- * @example
+ * **Example** (Getting PubSub capacity)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -264,16 +283,19 @@ export const makeAtomicUnbounded = options => new UnboundedPubSub(options?.repla
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const capacity = self => self.pubsub.capacity;
 /**
- * Retrieves the size of the queue, which is equal to the number of elements
- * in the queue. This may be negative if fibers are suspended waiting for
- * elements to be added to the queue.
+ * Returns the current number of messages retained by the `PubSub` for active
+ * subscribers.
+ *
+ * If the `PubSub` has been shut down, the returned effect succeeds with `0`.
+ * The size is not a count of waiting subscribers or suspended publishers.
+ *
+ * **Example** (Getting PubSub size)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -285,25 +307,36 @@ export const capacity = self => self.pubsub.capacity;
  *   const initialSize = yield* PubSub.size(pubsub)
  *   console.log("Initial size:", initialSize) // 0
  *
- *   // Publish some messages
- *   yield* PubSub.publish(pubsub, "msg1")
- *   yield* PubSub.publish(pubsub, "msg2")
+ *   yield* Effect.scoped(Effect.gen(function*() {
+ *     const subscription = yield* PubSub.subscribe(pubsub)
  *
- *   const afterPublish = yield* PubSub.size(pubsub)
- *   console.log("After publishing:", afterPublish) // 2
+ *     // Publish some messages for the active subscription
+ *     yield* PubSub.publish(pubsub, "msg1")
+ *     yield* PubSub.publish(pubsub, "msg2")
+ *
+ *     const afterPublish = yield* PubSub.size(pubsub)
+ *     console.log("After publishing:", afterPublish) // 2
+ *
+ *     yield* PubSub.takeAll(subscription)
+ *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const size = self => Effect.sync(() => sizeUnsafe(self));
 /**
- * Retrieves the size of the queue, which is equal to the number of elements
- * in the queue. This may be negative if fibers are suspended waiting for
- * elements to be added to the queue.
+ * Synchronously returns the current number of messages retained by the `PubSub`
+ * for active subscribers.
+ *
+ * **Notes**
+ *
+ * Returns `0` after shutdown. Because this is an unsafe synchronous snapshot,
+ * prefer `size` in effectful code.
+ *
+ * **Example** (Reading size synchronously)
  *
- * @example
  * ```ts
  * import { PubSub } from "effect"
  *
@@ -314,8 +347,8 @@ export const size = self => Effect.sync(() => sizeUnsafe(self));
  * console.log("Current size:", size)
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const sizeUnsafe = self => {
   if (MutableRef.get(self.shutdownFlag)) {
@@ -324,10 +357,12 @@ export const sizeUnsafe = self => {
   return self.pubsub.size();
 };
 /**
- * Returns `true` if the `PubSub` contains at least one element, `false`
- * otherwise.
+ * Returns `true` when the `PubSub` has reached its configured capacity.
+ *
+ * For unbounded PubSubs this is normally `false`.
+ *
+ * **Example** (Checking whether a PubSub is full)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -339,23 +374,30 @@ export const sizeUnsafe = self => {
  *   const initiallyFull = yield* PubSub.isFull(pubsub)
  *   console.log("Initially full:", initiallyFull) // false
  *
- *   // Fill the PubSub
- *   yield* PubSub.publish(pubsub, "msg1")
- *   yield* PubSub.publish(pubsub, "msg2")
+ *   yield* Effect.scoped(Effect.gen(function*() {
+ *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Fill the PubSub for the active subscription
+ *     yield* PubSub.publish(pubsub, "msg1")
+ *     yield* PubSub.publish(pubsub, "msg2")
+ *
+ *     const nowFull = yield* PubSub.isFull(pubsub)
+ *     console.log("Now full:", nowFull) // true
  *
- *   const nowFull = yield* PubSub.isFull(pubsub)
- *   console.log("Now full:", nowFull) // true
+ *     yield* PubSub.takeAll(subscription)
+ *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isFull = self => Effect.map(size(self), size => size === self.pubsub.capacity);
 /**
  * Returns `true` if the `Pubsub` contains zero elements, `false` otherwise.
  *
- * @example
+ * **Example** (Checking whether a PubSub is empty)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -367,48 +409,54 @@ export const isFull = self => Effect.map(size(self), size => size === self.pubsu
  *   const initiallyEmpty = yield* PubSub.isEmpty(pubsub)
  *   console.log("Initially empty:", initiallyEmpty) // true
  *
- *   // Publish a message
- *   yield* PubSub.publish(pubsub, "Hello")
+ *   yield* Effect.scoped(Effect.gen(function*() {
+ *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Publish a message for the active subscription
+ *     yield* PubSub.publish(pubsub, "Hello")
+ *
+ *     const nowEmpty = yield* PubSub.isEmpty(pubsub)
+ *     console.log("Now empty:", nowEmpty) // false
  *
- *   const nowEmpty = yield* PubSub.isEmpty(pubsub)
- *   console.log("Now empty:", nowEmpty) // false
+ *     yield* PubSub.take(subscription)
+ *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isEmpty = self => Effect.map(size(self), size => size === 0);
 /**
- * Interrupts any fibers that are suspended on `offer` or `take`. Future calls
- * to `offer*` and `take*` will be interrupted immediately.
+ * Shuts down the `PubSub`, interrupting suspended publishers and subscribers
+ * and finalizing active subscriptions.
+ *
+ * After shutdown, `publish` and `publishAll` succeed with `false`,
+ * `publishUnsafe` returns `false`, and subscription operations such as `take`
+ * interrupt.
+ *
+ * **Example** (Shutting down a PubSub)
  *
- * @example
  * ```ts
- * import { Effect, Fiber, PubSub } from "effect"
+ * import { Effect, PubSub } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const pubsub = yield* PubSub.bounded<string>(1)
  *
- *   // Start a fiber that will be suspended waiting to publish
- *   const publisherFiber = yield* Effect.forkChild(
- *     Effect.gen(function*() {
- *       yield* PubSub.publish(pubsub, "msg1") // fills the buffer
- *       yield* PubSub.publish(pubsub, "msg2") // will suspend here
- *     })
- *   )
- *
  *   // Shutdown the PubSub
  *   yield* PubSub.shutdown(pubsub)
  *
- *   // The suspended publisher will be interrupted
- *   const result = yield* Fiber.await(publisherFiber)
- *   console.log("Publisher interrupted:", result._tag === "Failure")
+ *   const isShutdown = yield* PubSub.isShutdown(pubsub)
+ *   console.log("Is shutdown:", isShutdown) // true
+ *
+ *   // Publishing after shutdown returns false
+ *   const published = yield* PubSub.publish(pubsub, "msg1")
+ *   console.log("Published after shutdown:", published) // false
  * })
  * ```
  *
- * @since 2.0.0
  * @category lifecycle
+ * @since 2.0.0
  */
 export const shutdown = self => Effect.uninterruptible(Effect.withFiber(fiber => {
   MutableRef.set(self.shutdownFlag, true);
@@ -417,7 +465,8 @@ export const shutdown = self => Effect.uninterruptible(Effect.withFiber(fiber =>
 /**
  * Returns `true` if `shutdown` has been called, otherwise returns `false`.
  *
- * @example
+ * **Example** (Checking whether a PubSub is shutdown)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -437,14 +486,15 @@ export const shutdown = self => Effect.uninterruptible(Effect.withFiber(fiber =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const isShutdown = self => Effect.sync(() => isShutdownUnsafe(self));
 /**
  * Returns `true` if `shutdown` has been called, otherwise returns `false`.
  *
- * @example
+ * **Example** (Checking shutdown synchronously)
+ *
  * ```ts
  * import { PubSub } from "effect"
  *
@@ -459,8 +509,8 @@ export const isShutdown = self => Effect.sync(() => isShutdownUnsafe(self));
  * }
  * ```
  *
- * @since 4.0.0
  * @category predicates
+ * @since 4.0.0
  */
 export const isShutdownUnsafe = self => self.shutdownFlag.current;
 /**
@@ -468,7 +518,8 @@ export const isShutdownUnsafe = self => self.shutdownFlag.current;
  * not resume until the queue has been shutdown. If the queue is already
  * shutdown, the `Effect` will resume right away.
  *
- * @example
+ * **Example** (Waiting for shutdown)
+ *
  * ```ts
  * import { Effect, Fiber, PubSub } from "effect"
  *
@@ -494,15 +545,20 @@ export const isShutdownUnsafe = self => self.shutdownFlag.current;
  * })
  * ```
  *
- * @since 2.0.0
  * @category lifecycle
+ * @since 2.0.0
  */
 export const awaitShutdown = self => self.shutdownHook.await;
 /**
- * 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.
+ *
+ * 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 a message)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -514,25 +570,18 @@ export const awaitShutdown = self => self.shutdownHook.await;
  *   const published = yield* PubSub.publish(pubsub, "Hello World")
  *   console.log("Message published:", published) // true
  *
- *   // With a full bounded PubSub using backpressure strategy
- *   const smallPubsub = yield* PubSub.bounded<string>(1)
- *   yield* PubSub.publish(smallPubsub, "msg1") // succeeds
- *
- *   // This will suspend until space becomes available
- *   const publishEffect = PubSub.publish(smallPubsub, "msg2")
- *
- *   // Create a subscriber to free up space
  *   yield* Effect.scoped(Effect.gen(function*() {
- *     const subscription = yield* PubSub.subscribe(smallPubsub)
- *     yield* PubSub.take(subscription) // frees space
- *     const result = yield* publishEffect
- *     console.log("Second message published:", result) // true
+ *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     yield* PubSub.publish(pubsub, "Hello")
+ *     const message = yield* PubSub.take(subscription)
+ *     console.log("Received:", message) // "Hello"
  *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category publishing
+ * @since 2.0.0
  */
 export const publish = /*#__PURE__*/dual(2, (self, value) => Effect.suspend(() => {
   if (self.shutdownFlag.current) {
@@ -548,7 +597,8 @@ export const publish = /*#__PURE__*/dual(2, (self, value) => Effect.suspend(() =
  * Publishes a message to the `PubSub`, returning whether the message was published
  * to the `PubSub`.
  *
- * @example
+ * **Example** (Publishing without suspending)
+ *
  * ```ts
  * import { PubSub } from "effect"
  *
@@ -569,8 +619,8 @@ export const publish = /*#__PURE__*/dual(2, (self, value) => Effect.suspend(() =
  * console.log(`Published ${publishedCount} out of ${messages.length} messages`)
  * ```
  *
- * @since 4.0.0
  * @category publishing
+ * @since 4.0.0
  */
 export const publishUnsafe = /*#__PURE__*/dual(2, (self, value) => {
   if (self.shutdownFlag.current) return false;
@@ -584,9 +634,10 @@ export const publishUnsafe = /*#__PURE__*/dual(2, (self, value) => {
  * Publishes all of the specified messages to the `PubSub`, returning whether they
  * were published to the `PubSub`.
  *
- * @example
+ * **Example** (Publishing multiple messages)
+ *
  * ```ts
- * import { Effect } from "effect"
+ * import { Effect, Fiber } from "effect"
  * import * as PubSub from "effect/PubSub"
  *
  * const program = Effect.gen(function*() {
@@ -597,25 +648,30 @@ export const publishUnsafe = /*#__PURE__*/dual(2, (self, value) => {
  *   const allPublished = yield* PubSub.publishAll(pubsub, messages)
  *   console.log("All messages published:", allPublished) // true
  *
- *   // With a smaller capacity
+ *   // With a smaller capacity and an active subscription
  *   const smallPubsub = yield* PubSub.bounded<string>(2)
  *   const manyMessages = ["msg1", "msg2", "msg3", "msg4"]
  *
- *   // Will suspend until space becomes available for all messages
- *   const publishAllEffect = PubSub.publishAll(smallPubsub, manyMessages)
- *
- *   // Subscribe to consume messages and free space
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(smallPubsub)
- *     yield* PubSub.takeAll(subscription) // consume all messages
- *     const result = yield* publishAllEffect
- *     console.log("All messages eventually published:", result)
+ *
+ *     // Will suspend until space becomes available for all messages
+ *     const fiber = yield* Effect.forkChild(PubSub.publishAll(smallPubsub, manyMessages))
+ *
+ *     const firstBatch = yield* PubSub.takeBetween(subscription, 2, 2)
+ *     console.log("First batch:", firstBatch) // ["msg1", "msg2"]
+ *
+ *     const result = yield* Fiber.join(fiber)
+ *     console.log("All messages eventually published:", result) // true
+ *
+ *     const secondBatch = yield* PubSub.takeAll(subscription)
+ *     console.log("Second batch:", secondBatch) // ["msg3", "msg4"]
  *   }))
  * })
  * ```
  *
- * @since 2.0.0
  * @category publishing
+ * @since 2.0.0
  */
 export const publishAll = /*#__PURE__*/dual(2, (self, elements) => Effect.suspend(() => {
   if (self.shutdownFlag.current) {
@@ -633,21 +689,22 @@ export const publishAll = /*#__PURE__*/dual(2, (self, elements) => Effect.suspen
  * be evaluated multiple times within the scope to take a message from the `PubSub`
  * each time.
  *
- * @example
+ * **Example** (Subscribing to messages)
+ *
  * ```ts
  * import { Effect, PubSub } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const pubsub = yield* PubSub.bounded<string>(10)
  *
- *   // Publish some messages
- *   yield* PubSub.publish(pubsub, "Hello")
- *   yield* PubSub.publish(pubsub, "World")
- *
  *   // Subscribe within a scope for automatic cleanup
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
  *
+ *     // Publish some messages
+ *     yield* PubSub.publish(pubsub, "Hello")
+ *     yield* PubSub.publish(pubsub, "World")
+ *
  *     // Take messages one by one
  *     const msg1 = yield* PubSub.take(subscription)
  *     const msg2 = yield* PubSub.take(subscription)
@@ -656,13 +713,13 @@ export const publishAll = /*#__PURE__*/dual(2, (self, elements) => Effect.suspen
  *     // Subscription is automatically cleaned up when scope exits
  *   }))
  *
- *   // Multiple subscribers can receive the same messages
- *   yield* PubSub.publish(pubsub, "Broadcast")
- *
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const sub1 = yield* PubSub.subscribe(pubsub)
  *     const sub2 = yield* PubSub.subscribe(pubsub)
  *
+ *     // Multiple subscribers can receive the same messages
+ *     yield* PubSub.publish(pubsub, "Broadcast")
+ *
  *     const [msg1, msg2] = yield* Effect.all([
  *       PubSub.take(sub1),
  *       PubSub.take(sub2)
@@ -672,8 +729,8 @@ export const publishAll = /*#__PURE__*/dual(2, (self, elements) => Effect.suspen
  * })
  * ```
  *
- * @since 2.0.0
  * @category subscription
+ * @since 2.0.0
  */
 export const subscribe = self => Effect.uninterruptible(Effect.contextWith(services => {
   const localScope = Context.get(services, Scope.Scope);
@@ -696,7 +753,8 @@ const unsubscribe = self => Effect.uninterruptible(Effect.withFiber(state => {
  * Takes a single message from the subscription. If no messages are available,
  * this will suspend until a message becomes available.
  *
- * @example
+ * **Example** (Taking a message)
+ *
  * ```ts
  * import { Effect, Fiber, PubSub } from "effect"
  *
@@ -721,8 +779,8 @@ const unsubscribe = self => Effect.uninterruptible(Effect.withFiber(state => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export const take = self => Effect.suspend(() => {
   if (self.shutdownFlag.current) {
@@ -744,19 +802,20 @@ export const take = self => Effect.suspend(() => {
  * Takes all available messages from the subscription, suspending if no items
  * are available.
  *
- * @example
+ * **Example** (Taking all available messages)
+ *
  * ```ts
  * import { Effect, PubSub } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const pubsub = yield* PubSub.bounded<string>(10)
  *
- *   // Publish multiple messages
- *   yield* PubSub.publishAll(pubsub, ["msg1", "msg2", "msg3"])
- *
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
  *
+ *     // Publish multiple messages
+ *     yield* PubSub.publishAll(pubsub, ["msg1", "msg2", "msg3"])
+ *
  *     // Take all available messages at once
  *     const allMessages = yield* PubSub.takeAll(subscription)
  *     console.log("All messages:", allMessages) // ["msg1", "msg2", "msg3"]
@@ -764,8 +823,8 @@ export const take = self => Effect.suspend(() => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export const takeAll = self => Effect.suspend(function loop(value) {
   if (self.shutdownFlag.current) {
@@ -801,7 +860,8 @@ const pollForItem = self => {
 /**
  * Takes up to the specified number of messages from the subscription without suspending.
  *
- * @example
+ * **Example** (Taking up to a maximum number of messages)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -809,12 +869,12 @@ const pollForItem = self => {
  * const program = Effect.gen(function*() {
  *   const pubsub = yield* PubSub.bounded<string>(10)
  *
- *   // Publish multiple messages
- *   yield* PubSub.publishAll(pubsub, ["msg1", "msg2", "msg3", "msg4", "msg5"])
- *
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
  *
+ *     // Publish multiple messages
+ *     yield* PubSub.publishAll(pubsub, ["msg1", "msg2", "msg3", "msg4", "msg5"])
+ *
  *     // Take up to 3 messages
  *     const upTo3 = yield* PubSub.takeUpTo(subscription, 3)
  *     console.log("Up to 3:", upTo3) // ["msg1", "msg2", "msg3"]
@@ -830,8 +890,8 @@ const pollForItem = self => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export const takeUpTo = /*#__PURE__*/dual(2, (self, max) => Effect.suspend(() => {
   if (self.shutdownFlag.current) return Effect.interrupt;
@@ -850,7 +910,8 @@ export const takeUpTo = /*#__PURE__*/dual(2, (self, max) => Effect.suspend(() =>
  * Takes between the specified minimum and maximum number of messages from the subscription.
  * Will suspend if the minimum number is not immediately available.
  *
- * @example
+ * **Example** (Taking between a minimum and maximum)
+ *
  * ```ts
  * import { Effect, Fiber, PubSub } from "effect"
  *
@@ -875,8 +936,8 @@ export const takeUpTo = /*#__PURE__*/dual(2, (self, max) => Effect.suspend(() =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export const takeBetween = /*#__PURE__*/dual(3, (self, min, max) => Effect.suspend(() => takeRemainderLoop(self, min, max, [])));
 const takeRemainderLoop = (self, min, max, acc) => {
@@ -902,9 +963,14 @@ const takeRemainderLoop = (self, min, max, acc) => {
   });
 };
 /**
- * Returns the number of messages currently available in the subscription.
+ * Synchronously checks how many messages can be taken from a subscription.
+ *
+ * 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.
+ *
+ * **Example** (Checking remaining messages)
  *
- * @example
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -912,12 +978,12 @@ const takeRemainderLoop = (self, min, max, acc) => {
  * const program = Effect.gen(function*() {
  *   const pubsub = yield* PubSub.bounded<string>(10)
  *
- *   // Publish some messages
- *   yield* PubSub.publishAll(pubsub, ["msg1", "msg2", "msg3"])
- *
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
  *
+ *     // Publish some messages
+ *     yield* PubSub.publishAll(pubsub, ["msg1", "msg2", "msg3"])
+ *
  *     // Check how many messages are available
  *     const count = yield* PubSub.remaining(subscription)
  *     console.log("Messages available:", count) // 3
@@ -931,14 +997,15 @@ const takeRemainderLoop = (self, min, max, acc) => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const remaining = self => Effect.suspend(() => self.shutdownFlag.current ? Effect.interrupt : Effect.succeed(self.subscription.size() + self.replayWindow.remaining));
 /**
  * Returns the number of messages currently available in the subscription.
  *
- * @example
+ * **Example** (Checking remaining messages synchronously)
+ *
  * ```ts
  * import { PubSub } from "effect"
  *
@@ -958,8 +1025,8 @@ export const remaining = self => Effect.suspend(() => self.shutdownFlag.current
  * }
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const remainingUnsafe = self => {
   if (self.shutdownFlag.current) {
@@ -1677,8 +1744,8 @@ const ensureCapacity = capacity => {
  * risk that a slow subscriber will slow down the rate at which messages
  * are published and received by other subscribers.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class BackPressureStrategy {
   publishers = /*#__PURE__*/MutableList.make();
@@ -1752,7 +1819,8 @@ export class BackPressureStrategy {
  * other subscribers and that subscribers may not receive all messages
  * published to the `PubSub` while they are subscribed.
  *
- * @example
+ * **Example** (Using a dropping strategy)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -1767,24 +1835,25 @@ export class BackPressureStrategy {
  *     strategy: () => new PubSub.DroppingStrategy()
  *   })
  *
- *   // Fill the PubSub
- *   const pub1 = yield* PubSub.publish(pubsub, "msg1") // true
- *   const pub2 = yield* PubSub.publish(pubsub, "msg2") // true
- *   const pub3 = yield* PubSub.publish(pubsub, "msg3") // false (dropped)
- *
- *   console.log("Publication results:", [pub1, pub2, pub3]) // [true, true, false]
- *
- *   // Subscribers will only see the first two messages
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Fill the PubSub
+ *     const pub1 = yield* PubSub.publish(pubsub, "msg1") // true
+ *     const pub2 = yield* PubSub.publish(pubsub, "msg2") // true
+ *     const pub3 = yield* PubSub.publish(pubsub, "msg3") // false (dropped)
+ *
+ *     console.log("Publication results:", [pub1, pub2, pub3]) // [true, true, false]
+ *
+ *     // Subscribers will only see the first two messages
  *     const messages = yield* PubSub.takeAll(subscription)
  *     console.log("Received messages:", messages) // ["msg1", "msg2"]
  *   }))
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class DroppingStrategy {
   get shutdown() {
@@ -1810,7 +1879,8 @@ export class DroppingStrategy {
  * subscribers. However, it creates the risk that a slow subscriber will
  * not receive some messages published to the `PubSub` while it is subscribed.
  *
- * @example
+ * **Example** (Using a sliding strategy)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -1825,23 +1895,24 @@ export class DroppingStrategy {
  *     strategy: () => new PubSub.SlidingStrategy()
  *   })
  *
- *   // Publish messages that exceed capacity
- *   yield* PubSub.publish(pubsub, "msg1") // stored
- *   yield* PubSub.publish(pubsub, "msg2") // stored
- *   yield* PubSub.publish(pubsub, "msg3") // "msg1" evicted, "msg3" stored
- *   yield* PubSub.publish(pubsub, "msg4") // "msg2" evicted, "msg4" stored
- *
- *   // Subscribers will see the most recent messages
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Publish messages that exceed capacity
+ *     yield* PubSub.publish(pubsub, "msg1") // stored
+ *     yield* PubSub.publish(pubsub, "msg2") // stored
+ *     yield* PubSub.publish(pubsub, "msg3") // "msg1" evicted, "msg3" stored
+ *     yield* PubSub.publish(pubsub, "msg4") // "msg2" evicted, "msg4" stored
+ *
+ *     // Subscribers will see the most recent messages
  *     const messages = yield* PubSub.takeAll(subscription)
  *     console.log("Recent messages:", messages) // ["msg3", "msg4"]
  *   }))
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class SlidingStrategy {
   get shutdown() {