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

package/dist/PubSub.d.ts

@@ -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"
@@ -45,7 +47,8 @@ declare const TypeId = "~effect/PubSub";
  * messages of type `A` and subscribers can subscribe to take messages of type
  * `A`.
  *
- * @example
+ * **Example** (Publishing and subscribing to messages)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -54,13 +57,14 @@ declare const TypeId = "~effect/PubSub";
  *   // Create a bounded PubSub with capacity 10
  *   const pubsub = yield* PubSub.bounded<string>(10)
  *
- *   // Publish messages
- *   yield* PubSub.publish(pubsub, "Hello")
- *   yield* PubSub.publish(pubsub, "World")
- *
  *   // Subscribe and consume messages
  *   yield* Effect.scoped(Effect.gen(function*() {
  *     const subscription = yield* PubSub.subscribe(pubsub)
+ *
+ *     // Publish messages
+ *     yield* PubSub.publish(pubsub, "Hello")
+ *     yield* PubSub.publish(pubsub, "World")
+ *
  *     const message1 = yield* PubSub.take(subscription)
  *     const message2 = yield* PubSub.take(subscription)
  *     console.log(message1, message2) // "Hello", "World"
@@ -68,8 +72,8 @@ declare const TypeId = "~effect/PubSub";
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface PubSub<in out A> extends Pipeable {
     readonly [TypeId]: {
@@ -83,15 +87,18 @@ export interface PubSub<in out A> extends Pipeable {
     readonly strategy: PubSub.Strategy<A>;
 }
 /**
+ * Companion namespace containing the low-level building blocks used by
+ * `PubSub`, including atomic implementations, backing subscriptions, replay
+ * windows, and delivery strategies.
+ *
  * @since 2.0.0
- * @category models
  */
 export declare namespace PubSub {
     /**
      * Low-level atomic PubSub interface that handles the core message storage and retrieval.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface Atomic<in out A> {
         readonly capacity: number;
@@ -107,8 +114,8 @@ export declare namespace PubSub {
     /**
      * Low-level subscription interface that handles message polling for individual subscribers.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface BackingSubscription<out A> {
         isEmpty(): boolean;
@@ -118,17 +125,23 @@ export declare namespace PubSub {
         unsubscribe(): void;
     }
     /**
-     * Internal type representing the mapping from subscriptions to their pollers.
+     * Tracks the pollers currently waiting on each backing subscription.
+     *
+     * **Notes**
+     *
+     * This type is part of the low-level `PubSub.Strategy` contract. Most
+     * application code should use `subscribe`, `take`, and the other `PubSub`
+     * operations instead of manipulating subscriber maps directly.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     type Subscribers<A> = Map<BackingSubscription<A>, Set<MutableList.MutableList<Deferred.Deferred<A>>>>;
     /**
      * Interface for accessing replay buffer contents for late subscribers.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface ReplayWindow<A> {
         take(): A | undefined;
@@ -139,8 +152,8 @@ export declare namespace PubSub {
     /**
      * Strategy interface defining how PubSub handles backpressure and message distribution.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface Strategy<in out A> {
         /**
@@ -174,7 +187,8 @@ declare const SubscriptionTypeId = "~effect/PubSub/Subscription";
 /**
  * A subscription represents a consumer's connection to a PubSub, allowing them to take messages.
  *
- * @example
+ * **Example** (Taking messages from a subscription)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -188,18 +202,23 @@ declare const SubscriptionTypeId = "~effect/PubSub/Subscription";
  *       pubsub
  *     )
  *
+ *     yield* PubSub.publishAll(pubsub, ["msg1", "msg2", "msg3"])
+ *
  *     // Take individual messages
  *     const message = yield* PubSub.take(subscription)
+ *     console.log(message) // "msg1"
  *
  *     // Take multiple messages
- *     const messages = yield* PubSub.takeUpTo(subscription, 5)
+ *     const messages = yield* PubSub.takeUpTo(subscription, 1)
+ *     console.log(messages) // ["msg2"]
  *     const allMessages = yield* PubSub.takeAll(subscription)
+ *     console.log(allMessages) // ["msg3"]
  *   }))
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Subscription<out A> extends Pipeable {
     readonly [SubscriptionTypeId]: {
@@ -217,7 +236,8 @@ export interface Subscription<out A> extends Pipeable {
 /**
  * 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"
@@ -234,25 +254,28 @@ export interface Subscription<out A> extends Pipeable {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <A>(options: {
     readonly atomicPubSub: LazyArg<PubSub.Atomic<A>>;
     readonly strategy: LazyArg<PubSub.Strategy<A>>;
 }) => Effect.Effect<PubSub<A>>;
 /**
- * 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"
@@ -269,8 +292,8 @@ export declare const make: <A>(options: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const bounded: <A>(capacity: number | {
     readonly capacity: number;
@@ -282,7 +305,8 @@ export declare const bounded: <A>(capacity: number | {
  *
  * 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"
@@ -297,17 +321,24 @@ export declare const bounded: <A>(capacity: number | {
  *     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 declare const dropping: <A>(capacity: number | {
     readonly capacity: number;
@@ -319,7 +350,8 @@ export declare const dropping: <A>(capacity: number | {
  *
  * 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"
@@ -334,22 +366,23 @@ export declare const dropping: <A>(capacity: number | {
  *     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 declare const sliding: <A>(capacity: number | {
     readonly capacity: number;
@@ -358,7 +391,8 @@ export declare const sliding: <A>(capacity: number | {
 /**
  * Creates an unbounded `PubSub`.
  *
- * @example
+ * **Example** (Creating an unbounded PubSub)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as PubSub from "effect/PubSub"
@@ -372,21 +406,22 @@ export declare const sliding: <A>(capacity: number | {
  *     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 declare const unbounded: <A>(options?: {
     readonly replay?: number | undefined;
@@ -394,8 +429,8 @@ export declare const unbounded: <A>(options?: {
 /**
  * Creates a bounded atomic PubSub implementation with optional replay buffer.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeAtomicBounded: <A>(capacity: number | {
     readonly capacity: number;
@@ -404,8 +439,8 @@ export declare const makeAtomicBounded: <A>(capacity: number | {
 /**
  * Creates an unbounded atomic PubSub implementation with optional replay buffer.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeAtomicUnbounded: <A>(options?: {
     readonly replay?: number | undefined;
@@ -413,7 +448,8 @@ export declare const makeAtomicUnbounded: <A>(options?: {
 /**
  *  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"
@@ -429,16 +465,19 @@ export declare const makeAtomicUnbounded: <A>(options?: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const capacity: <A>(self: PubSub<A>) => number;
 /**
- * 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"
@@ -450,25 +489,36 @@ export declare const capacity: <A>(self: PubSub<A>) => number;
  *   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 declare const size: <A>(self: PubSub<A>) => Effect.Effect<number>;
 /**
- * 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"
  *
@@ -479,15 +529,17 @@ export declare const size: <A>(self: PubSub<A>) => Effect.Effect<number>;
  * console.log("Current size:", size)
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const sizeUnsafe: <A>(self: PubSub<A>) => number;
 /**
- * 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"
@@ -499,23 +551,30 @@ export declare const sizeUnsafe: <A>(self: PubSub<A>) => number;
  *   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 declare const isFull: <A>(self: PubSub<A>) => Effect.Effect<boolean>;
 /**
  * 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"
@@ -527,54 +586,61 @@ export declare const isFull: <A>(self: PubSub<A>) => Effect.Effect<boolean>;
  *   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)
  *
- *   const nowEmpty = yield* PubSub.isEmpty(pubsub)
- *   console.log("Now empty:", nowEmpty) // false
+ *     // Publish a message for the active subscription
+ *     yield* PubSub.publish(pubsub, "Hello")
+ *
+ *     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 declare const isEmpty: <A>(self: PubSub<A>) => Effect.Effect<boolean>;
 /**
- * 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 declare const shutdown: <A>(self: PubSub<A>) => Effect.Effect<void>;
 /**
  * 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"
@@ -594,14 +660,15 @@ export declare const shutdown: <A>(self: PubSub<A>) => Effect.Effect<void>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const isShutdown: <A>(self: PubSub<A>) => Effect.Effect<boolean>;
 /**
  * Returns `true` if `shutdown` has been called, otherwise returns `false`.
  *
- * @example
+ * **Example** (Checking shutdown synchronously)
+ *
  * ```ts
  * import { PubSub } from "effect"
  *
@@ -616,8 +683,8 @@ export declare const isShutdown: <A>(self: PubSub<A>) => Effect.Effect<boolean>;
  * }
  * ```
  *
- * @since 4.0.0
  * @category predicates
+ * @since 4.0.0
  */
 export declare const isShutdownUnsafe: <A>(self: PubSub<A>) => boolean;
 /**
@@ -625,7 +692,8 @@ export declare const isShutdownUnsafe: <A>(self: PubSub<A>) => boolean;
  * 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"
  *
@@ -651,15 +719,20 @@ export declare const isShutdownUnsafe: <A>(self: PubSub<A>) => boolean;
  * })
  * ```
  *
- * @since 2.0.0
  * @category lifecycle
+ * @since 2.0.0
  */
 export declare const awaitShutdown: <A>(self: PubSub<A>) => Effect.Effect<void>;
 /**
- * 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"
@@ -671,32 +744,30 @@ export declare const awaitShutdown: <A>(self: PubSub<A>) => Effect.Effect<void>;
  *   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 declare 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.
+     *
+     * 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"
@@ -708,32 +779,30 @@ export declare const publish: {
      *   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
      */
     <A>(value: A): (self: PubSub<A>) => Effect.Effect<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.
+     *
+     * 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"
@@ -745,25 +814,18 @@ export declare const publish: {
      *   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
      */
     <A>(self: PubSub<A>, value: A): Effect.Effect<boolean>;
 };
@@ -771,7 +833,8 @@ export declare const publish: {
  * 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"
  *
@@ -792,15 +855,16 @@ export declare const publish: {
  * console.log(`Published ${publishedCount} out of ${messages.length} messages`)
  * ```
  *
- * @since 4.0.0
  * @category publishing
+ * @since 4.0.0
  */
 export declare const publishUnsafe: {
     /**
      * 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"
      *
@@ -821,15 +885,16 @@ export declare const publishUnsafe: {
      * console.log(`Published ${publishedCount} out of ${messages.length} messages`)
      * ```
      *
-     * @since 4.0.0
      * @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`.
      *
-     * @example
+     * **Example** (Publishing without suspending)
+     *
      * ```ts
      * import { PubSub } from "effect"
      *
@@ -850,8 +915,8 @@ export declare const publishUnsafe: {
      * console.log(`Published ${publishedCount} out of ${messages.length} messages`)
      * ```
      *
-     * @since 4.0.0
      * @category publishing
+     * @since 4.0.0
      */
     <A>(self: PubSub<A>, value: A): boolean;
 };
@@ -859,9 +924,10 @@ export declare const publishUnsafe: {
  * 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*() {
@@ -872,34 +938,40 @@ export declare const publishUnsafe: {
  *   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 declare const publishAll: {
     /**
      * 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*() {
@@ -910,34 +982,40 @@ export declare const publishAll: {
      *   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
      */
     <A>(elements: Iterable<A>): (self: PubSub<A>) => Effect.Effect<boolean>;
     /**
      * 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*() {
@@ -948,25 +1026,30 @@ export declare const publishAll: {
      *   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
      */
     <A>(self: PubSub<A>, elements: Iterable<A>): Effect.Effect<boolean>;
 };
@@ -975,21 +1058,22 @@ export declare const publishAll: {
  * 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)
@@ -998,13 +1082,13 @@ export declare const publishAll: {
  *     // 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)
@@ -1014,15 +1098,16 @@ export declare const publishAll: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category subscription
+ * @since 2.0.0
  */
 export declare const subscribe: <A>(self: PubSub<A>) => Effect.Effect<Subscription<A>, never, Scope.Scope>;
 /**
  * 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"
  *
@@ -1047,27 +1132,28 @@ export declare const subscribe: <A>(self: PubSub<A>) => Effect.Effect<Subscripti
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export declare const take: <A>(self: Subscription<A>) => Effect.Effect<A>;
 /**
  * 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"]
@@ -1075,14 +1161,15 @@ export declare const take: <A>(self: Subscription<A>) => Effect.Effect<A>;
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export declare const takeAll: <A>(self: Subscription<A>) => Effect.Effect<Arr.NonEmptyArray<A>>;
 /**
  * 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"
@@ -1090,12 +1177,12 @@ export declare const takeAll: <A>(self: Subscription<A>) => Effect.Effect<Arr.No
  * 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"]
@@ -1111,14 +1198,15 @@ export declare const takeAll: <A>(self: Subscription<A>) => Effect.Effect<Arr.No
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export declare const takeUpTo: {
     /**
      * 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"
@@ -1126,12 +1214,12 @@ export declare const takeUpTo: {
      * 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"]
@@ -1147,14 +1235,15 @@ export declare const takeUpTo: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category subscription
+     * @since 4.0.0
      */
     (max: number): <A>(self: Subscription<A>) => Effect.Effect<Array<A>>;
     /**
      * 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"
@@ -1162,12 +1251,12 @@ export declare const takeUpTo: {
      * 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"]
@@ -1183,8 +1272,8 @@ export declare const takeUpTo: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category subscription
+     * @since 4.0.0
      */
     <A>(self: Subscription<A>, max: number): Effect.Effect<Array<A>>;
 };
@@ -1192,7 +1281,8 @@ export declare const takeUpTo: {
  * 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"
  *
@@ -1217,15 +1307,16 @@ export declare const takeUpTo: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category subscription
+ * @since 4.0.0
  */
 export declare const takeBetween: {
     /**
      * 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"
      *
@@ -1250,15 +1341,16 @@ export declare const takeBetween: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category subscription
+     * @since 4.0.0
      */
     (min: number, max: number): <A>(self: Subscription<A>) => Effect.Effect<Array<A>>;
     /**
      * 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"
      *
@@ -1283,15 +1375,20 @@ export declare const takeBetween: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category subscription
+     * @since 4.0.0
      */
     <A>(self: Subscription<A>, min: number, max: number): Effect.Effect<Array<A>>;
 };
 /**
- * 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"
@@ -1299,12 +1396,12 @@ export declare const takeBetween: {
  * 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
@@ -1318,14 +1415,15 @@ export declare const takeBetween: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const remaining: <A>(self: Subscription<A>) => Effect.Effect<number>;
 /**
  * Returns the number of messages currently available in the subscription.
  *
- * @example
+ * **Example** (Checking remaining messages synchronously)
+ *
  * ```ts
  * import { PubSub } from "effect"
  *
@@ -1345,8 +1443,8 @@ export declare const remaining: <A>(self: Subscription<A>) => Effect.Effect<numb
  * }
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export declare const remainingUnsafe: <A>(self: Subscription<A>) => Option.Option<number>;
 /**
@@ -1356,8 +1454,8 @@ export declare const remainingUnsafe: <A>(self: Subscription<A>) => Option.Optio
  * 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 declare class BackPressureStrategy<in out A> implements PubSub.Strategy<A> {
     publishers: MutableList.MutableList<readonly [A, Deferred.Deferred<boolean>, boolean]>;
@@ -1377,7 +1475,8 @@ export declare class BackPressureStrategy<in out A> implements PubSub.Strategy<A
  * 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"
@@ -1392,24 +1491,25 @@ export declare class BackPressureStrategy<in out A> implements PubSub.Strategy<A
  *     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 declare class DroppingStrategy<in out A> implements PubSub.Strategy<A> {
     get shutdown(): Effect.Effect<void>;
@@ -1425,7 +1525,8 @@ export declare class DroppingStrategy<in out A> implements PubSub.Strategy<A> {
  * 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"
@@ -1440,23 +1541,24 @@ export declare class DroppingStrategy<in out A> implements PubSub.Strategy<A> {
  *     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 declare class SlidingStrategy<in out A> implements PubSub.Strategy<A> {
     get shutdown(): Effect.Effect<void>;