effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/PrimaryKey.ts

@@ -1,11 +1,48 @@
 /**
- * This module provides functionality for working with primary keys.
- * A `PrimaryKey` is a simple interface that represents a unique identifier
- * that can be converted to a string representation.
+ * The `PrimaryKey` module defines a small protocol for values that can expose
+ * a stable, string-based identifier. A value participates by implementing a
+ * method at {@link symbol}; consumers can check unknown values with
+ * {@link isPrimaryKey} and read the key with {@link value}.
  *
- * Primary keys are useful for creating unique identifiers for objects,
- * database records, cache keys, or any scenario where you need a
- * string-based unique identifier.
+ * **Mental model**
+ *
+ * - `PrimaryKey` is structural: no base class or registration step is required
+ * - The key is produced by a symbol-named method, which avoids collisions with
+ *   ordinary object fields
+ * - The returned string is expected to be stable for the lifetime of the value
+ *   when it is used for maps, caches, or persistence boundaries
+ *
+ * **Common tasks**
+ *
+ * - Implement the protocol on a class or object literal with
+ *   `[PrimaryKey.symbol]`
+ * - Accept unknown input safely by checking {@link isPrimaryKey}
+ * - Convert a known `PrimaryKey` to its string identifier with {@link value}
+ *
+ * **Gotchas**
+ *
+ * - {@link isPrimaryKey} only checks that the symbol property exists; it does
+ *   not call the method or verify the returned string
+ * - The module does not enforce global uniqueness. Choose key formats that are
+ *   unambiguous for the domain where they are compared
+ *
+ * **Example** (Implementing a stable key)
+ *
+ * ```ts
+ * import { PrimaryKey } from "effect"
+ *
+ * class UserId implements PrimaryKey.PrimaryKey {
+ *   constructor(readonly id: number) {}
+ *
+ *   [PrimaryKey.symbol](): string {
+ *     return `user:${this.id}`
+ *   }
+ * }
+ *
+ * const id = new UserId(42)
+ *
+ * PrimaryKey.value(id) // "user:42"
+ * ```
  *
  * @since 2.0.0
  */
@@ -13,7 +50,16 @@
 import { hasProperty } from "./Predicate.ts"
 
 /**
- * The unique identifier used to identify objects that implement the `PrimaryKey` interface.
+ * Defines the unique identifier used to identify objects that implement the `PrimaryKey` interface.
+ *
+ * **When to use**
+ *
+ * Use to implement the `PrimaryKey` protocol as a computed property key on
+ * classes or object literals that expose a stable string identifier.
+ *
+ * @see {@link PrimaryKey} for the protocol interface that declares the method keyed by this symbol
+ * @see {@link value} for reading the string key from a `PrimaryKey` value
+ * @see {@link isPrimaryKey} for checking whether an unknown value carries this method
  *
  * @category symbols
  * @since 2.0.0
@@ -23,6 +69,11 @@ export const symbol = "~effect/interfaces/PrimaryKey"
 /**
  * An interface for objects that can provide a string-based primary key.
  *
+ * **When to use**
+ *
+ * Use to define values that expose a stable string identifier for equality,
+ * hashing, caching, or persistence.
+ *
  * **Details**
  *
  * Objects implementing this interface must provide a method that returns
@@ -55,10 +106,20 @@ export interface PrimaryKey {
 /**
  * Checks whether a value implements the `PrimaryKey` protocol.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a `PrimaryKey`.
+ *
  * **Details**
  *
- * This is a structural guard for the `PrimaryKey.symbol` property. It does not
- * call the method or verify that it returns a string.
+ * This is a structural guard for the `PrimaryKey.symbol` property.
+ *
+ * **Gotchas**
+ *
+ * This guard does not call the method or verify that it returns a string.
+ *
+ * @see {@link PrimaryKey} for the protocol being checked
+ * @see {@link value} for extracting the string value after narrowing
  *
  * @category models
  * @since 4.0.0
@@ -68,6 +129,11 @@ export const isPrimaryKey = (u: unknown): u is PrimaryKey => hasProperty(u, symb
 /**
  * Extracts the string value from a `PrimaryKey`.
  *
+ * **When to use**
+ *
+ * Use to read the stable string identifier from a value that implements
+ * `PrimaryKey`.
+ *
  * **Example** (Reading primary key values)
  *
  * ```ts

package/src/PubSub.ts

@@ -1,33 +1,61 @@
 /**
- * This module provides utilities for working with publish-subscribe (PubSub) systems.
- *
- * A PubSub is an asynchronous message hub where publishers can publish messages and subscribers
- * can subscribe to receive those messages. PubSub supports various backpressure strategies,
- * message replay, and concurrent access from multiple producers and consumers.
- *
- * **Example** (Creating and using a PubSub)
+ * The `PubSub` module provides asynchronous publish-subscribe hubs for
+ * broadcasting values to many subscribers. Publishers add messages with
+ * {@link publish} or {@link publishAll}; each active {@link Subscription}
+ * receives its own copy of every accepted message.
+ *
+ * Unlike a queue, subscribers do not compete for messages. A published value is
+ * retained until all subscribers that were active for that value have taken it
+ * or unsubscribed.
+ *
+ * **Mental model**
+ *
+ * - A `PubSub<A>` is the shared publish side, and each `Subscription<A>` is an
+ *   independent read side
+ * - {@link subscribe} is scoped; leaving the scope automatically unsubscribes
+ *   the subscription and releases any retained messages for it
+ * - {@link bounded} applies back pressure when the buffer is full,
+ *   {@link dropping} drops new messages, and {@link sliding} drops old messages
+ * - {@link unbounded} removes the capacity limit but can retain an unbounded
+ *   number of messages for slow subscribers
+ * - The optional replay buffer lets late subscribers first consume recently
+ *   published messages
+ *
+ * **Common tasks**
+ *
+ * - Create hubs: {@link bounded}, {@link dropping}, {@link sliding},
+ *   {@link unbounded}
+ * - Publish values: {@link publish}, {@link publishAll}
+ * - Subscribe and consume: {@link subscribe}, {@link take}, {@link takeAll},
+ *   {@link takeUpTo}, {@link takeBetween}
+ * - Inspect lifecycle and capacity: {@link capacity}, {@link size},
+ *   {@link isFull}, {@link isEmpty}, {@link isShutdown}
+ * - Stop a hub: {@link shutdown}, {@link awaitShutdown}
+ *
+ * **Example** (Publishing to one scoped subscriber)
  *
  * ```ts
  * import { Effect, PubSub } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const pubsub = yield* PubSub.bounded<string>(10)
- *
- *   yield* Effect.scoped(Effect.gen(function*() {
+ * const program = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     const pubsub = yield* PubSub.bounded<string>(16)
  *     const subscription = yield* PubSub.subscribe(pubsub)
  *
- *     // Publisher
- *     yield* PubSub.publish(pubsub, "Hello")
- *     yield* PubSub.publish(pubsub, "World")
+ *     yield* PubSub.publish(pubsub, "ready")
  *
- *     // Subscriber
- *     const message1 = yield* PubSub.take(subscription)
- *     const message2 = yield* PubSub.take(subscription)
- *     console.log(message1, message2) // "Hello", "World"
- *   }))
- * })
+ *     return yield* PubSub.take(subscription)
+ *   })
+ * )
  * ```
  *
+ * **Gotchas**
+ *
+ * - `bounded` can suspend publishers when a subscriber is slow
+ * - `dropping` and `sliding` can lose messages by design
+ * - Replay buffers are for late subscribers; they do not make the hub a
+ *   permanent event log
+ *
  * @since 2.0.0
  */
 import * as Arr from "./Array.ts"
@@ -500,6 +528,28 @@ export const unbounded = <A>(options?: {
 /**
  * Creates a bounded atomic PubSub implementation with optional replay buffer.
  *
+ * **When to use**
+ *
+ * Use to provide bounded message storage when building a custom `PubSub` with
+ * `make` and an explicit delivery strategy.
+ *
+ * **Details**
+ *
+ * Pass either a capacity number or an options object with `capacity` and
+ * optional `replay`. A positive `replay` value enables a replay buffer for late
+ * subscribers, and fractional replay sizes are rounded up.
+ *
+ * **Gotchas**
+ *
+ * The capacity must be greater than zero; invalid capacities throw
+ * synchronously before an atomic implementation is created.
+ *
+ * @see {@link make} for constructing a `PubSub` from an atomic implementation and delivery strategy
+ * @see {@link makeAtomicUnbounded} for an atomic implementation without a bounded capacity
+ * @see {@link bounded} for the higher-level backpressure constructor
+ * @see {@link dropping} for the higher-level dropping constructor
+ * @see {@link sliding} for the higher-level sliding constructor
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -524,6 +574,20 @@ export const makeAtomicBounded = <A>(
 /**
  * Creates an unbounded atomic PubSub implementation with optional replay buffer.
  *
+ * **When to use**
+ *
+ * Use to create the low-level storage layer for a custom `PubSub` whose active
+ * subscribers may retain an unbounded number of pending messages.
+ *
+ * **Gotchas**
+ *
+ * Messages published while subscribers are active can be retained without a
+ * capacity limit until those subscribers take them or unsubscribe.
+ *
+ * @see {@link makeAtomicBounded} for a bounded atomic implementation that enforces capacity
+ * @see {@link make} for wrapping an atomic implementation with a delivery strategy
+ * @see {@link unbounded} for the high-level effectful constructor for unbounded `PubSub` values
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -596,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**
  *
@@ -744,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)
  *
@@ -772,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)
  *
@@ -833,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)
  *
@@ -864,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)
    *
@@ -900,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)
    *
@@ -936,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
    */
@@ -960,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)
  *
@@ -985,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)
    *
@@ -1015,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)
    *
@@ -1045,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
    */
@@ -1680,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)
  *
@@ -1715,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
  */
@@ -1726,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)
  *
@@ -1749,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
  */
@@ -2631,11 +2772,26 @@ 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**
+ *
+ * Use to preserve every message for current subscribers when a bounded custom
+ * `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
  *
  * @category models
  * @since 4.0.0
@@ -2733,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)
  *
@@ -2811,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)
  *