effect 4.0.0-beta.70 → 4.0.0-beta.71

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
  */
@@ -15,6 +52,15 @@ import { hasProperty } from "./Predicate.ts"
 /**
  * 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 through the
+ * `PrimaryKey` protocol.
+ *
  * **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
  */
@@ -2637,6 +2701,16 @@ const ensureCapacity = (capacity: number): void => {
  * risk that a slow subscriber will slow down the rate at which messages
  * are published and received by other subscribers.
  *
+ * **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.
+ *
+ * @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
  */

package/src/Pull.ts

@@ -39,6 +39,12 @@ import * as Result from "./Result.ts"
  * An effectful pull step that either produces a value, fails with `E`, or
  * signals completion with `Cause.Done<Done>`.
  *
+ * **When to use**
+ *
+ * Use to model one low-level pull step when a consumer repeatedly evaluates an
+ * effect that may emit a value, fail normally, or signal normal completion
+ * through `Cause.Done`.
+ *
  * **Details**
  *
  * `Pull` represents completion in the error channel so low-level stream
@@ -55,6 +61,15 @@ export interface Pull<out A, out E = never, out Done = void, out R = never>
 /**
  * Extracts the success type from a Pull type.
  *
+ * **When to use**
+ *
+ * Use to derive the value produced by an existing `Pull` when declaring
+ * reusable type aliases, low-level stream helpers, or function signatures.
+ *
+ * @see {@link Error} for extracting the ordinary failure type
+ * @see {@link Leftover} for extracting the completion leftover type
+ * @see {@link Services} for extracting the required services type instead
+ *
  * @category type extractors
  * @since 4.0.0
  */
@@ -63,6 +78,16 @@ export type Success<P> = P extends Effect<infer _A, infer _E, infer _R> ? _A : n
 /**
  * Extracts the error type from a Pull type, excluding Done errors.
  *
+ * **When to use**
+ *
+ * Use to derive only the ordinary failure type from a `Pull` when declaring
+ * wrappers or APIs that handle completion separately.
+ *
+ * @see {@link Success} for extracting the pulled value type instead
+ * @see {@link Leftover} for extracting the completion leftover type
+ * @see {@link Services} for extracting the required services type instead
+ * @see {@link ExcludeDone} for excluding `Cause.Done` from an error union
+ *
  * @category type extractors
  * @since 4.0.0
  */
@@ -72,6 +97,16 @@ export type Error<P> = P extends Effect<infer _A, infer _E, infer _R> ? _E exten
 /**
  * Extracts the leftover type from a Pull type.
  *
+ * **When to use**
+ *
+ * Use to derive the completion leftover type from an existing `Pull` when
+ * declaring reusable type aliases or helper signatures that preserve a pull's
+ * done value.
+ *
+ * @see {@link Success} for extracting the pulled value type instead
+ * @see {@link Error} for extracting the ordinary failure type, excluding `Cause.Done`
+ * @see {@link Services} for extracting the required services type instead
+ *
  * @category type extractors
  * @since 4.0.0
  */
@@ -81,13 +116,30 @@ export type Leftover<P> = P extends Effect<infer _A, infer _E, infer _R> ? _E ex
 /**
  * Extracts the service requirements (context) type from a Pull type.
  *
+ * **When to use**
+ *
+ * Use to derive the context requirements of a generic or inferred `Pull`
+ * without restating its `R` type parameter.
+ *
+ * @see {@link Success} for extracting the pulled value type instead
+ * @see {@link Error} for extracting the ordinary failure type
+ * @see {@link Leftover} for extracting the completion leftover type
+ *
  * @category type extractors
  * @since 4.0.0
  */
 export type Services<P> = P extends Effect<infer _A, infer _E, infer _R> ? _R : never
 
 /**
- * Excludes done errors from an error type union.
+ * Excludes `Cause.Done` completion signals from an error type union.
+ *
+ * **When to use**
+ *
+ * Use to describe the ordinary error type that remains after `Cause.Done`
+ * completion signals have been handled or filtered out of an error union.
+ *
+ * @see {@link Error} for extracting ordinary failures from a `Pull`
+ * @see {@link Leftover} for extracting the completion leftover type
  *
  * @category type extractors
  * @since 4.0.0
@@ -102,11 +154,20 @@ export type ExcludeDone<E> = Exclude<E, Cause.Done<any>>
  * Handles `Cause.Done` failures in an effect while leaving ordinary failures
  * in the error channel.
  *
+ * **When to use**
+ *
+ * Use to recover from a `Cause.Done` completion signal in an effect, such as
+ * turning a pull leftover value into a successful recovery effect while
+ * preserving ordinary failures.
+ *
  * **Details**
  *
  * The handler receives the done leftover value and may recover with a new
  * effect. Non-done errors are preserved.
  *
+ * @see {@link matchEffect} for handling success, ordinary failure, and done outcomes explicitly
+ * @see {@link filterDoneLeftover} for extracting a done leftover from an existing `Cause`
+ *
  * @category Done
  * @since 4.0.0
  */
@@ -119,11 +180,20 @@ export const catchDone: {
    * Handles `Cause.Done` failures in an effect while leaving ordinary failures
    * in the error channel.
    *
+   * **When to use**
+   *
+   * Use to recover from a `Cause.Done` completion signal in an effect, such as
+   * turning a pull leftover value into a successful recovery effect while
+   * preserving ordinary failures.
+   *
    * **Details**
    *
    * The handler receives the done leftover value and may recover with a new
    * effect. Non-done errors are preserved.
    *
+   * @see {@link matchEffect} for handling success, ordinary failure, and done outcomes explicitly
+   * @see {@link filterDoneLeftover} for extracting a done leftover from an existing `Cause`
+   *
    * @category Done
    * @since 4.0.0
    */
@@ -138,11 +208,20 @@ export const catchDone: {
    * Handles `Cause.Done` failures in an effect while leaving ordinary failures
    * in the error channel.
    *
+   * **When to use**
+   *
+   * Use to recover from a `Cause.Done` completion signal in an effect, such as
+   * turning a pull leftover value into a successful recovery effect while
+   * preserving ordinary failures.
+   *
    * **Details**
    *
    * The handler receives the done leftover value and may recover with a new
    * effect. Non-done errors are preserved.
    *
+   * @see {@link matchEffect} for handling success, ordinary failure, and done outcomes explicitly
+   * @see {@link filterDoneLeftover} for extracting a done leftover from an existing `Cause`
+   *
    * @category Done
    * @since 4.0.0
    */
@@ -159,13 +238,31 @@ export const catchDone: {
 /**
  * Checks if a Cause contains any done errors.
  *
+ * **When to use**
+ *
+ * Use to test a whole pull failure cause for normal completion when you only
+ * need a boolean branch and do not need the done payload.
+ *
+ * @see {@link isDoneFailure} for checking a single `Cause.Reason`
+ * @see {@link filterDone} for extracting the `Cause.Done` value from a `Cause`
+ * @see {@link filterNoDone} for selecting causes with no done failures
+ *
  * @category Done
  * @since 4.0.0
  */
 export const isDoneCause = <E>(cause: Cause.Cause<E>): boolean => cause.reasons.some(isDoneFailure)
 
 /**
- * Checks if a Cause failure is a done error.
+ * Checks whether a `Cause.Reason` is a `Fail` reason whose error is a
+ * `Cause.Done` signal.
+ *
+ * **When to use**
+ *
+ * Use as a predicate when traversing `cause.reasons` and you need to identify
+ * done completion reasons before handling ordinary failures.
+ *
+ * @see {@link isDoneCause} for checking an entire `Cause` for any done reason
+ * @see {@link filterDone} for extracting the `Cause.Done` value from a `Cause`
  *
  * @category Done
  * @since 4.0.0
@@ -177,6 +274,11 @@ export const isDoneFailure = <E>(
 /**
  * Finds a `Cause.Done` failure in a `Cause`.
  *
+ * **When to use**
+ *
+ * Use to separate `Cause.Done` completion from ordinary causes while preserving
+ * the typed done value.
+ *
  * **Details**
  *
  * Returns a successful `Result` with the `Cause.Done` value when one is
@@ -196,11 +298,20 @@ export const filterDone: <E>(
 /**
  * Finds a `Cause.Done` failure in a cause whose done value is not used.
  *
+ * **When to use**
+ *
+ * Use to detect `Cause.Done` completion in a `Cause` when the completion value
+ * is not part of the downstream logic.
+ *
  * **Details**
  *
  * Returns a successful `Result` with the done marker when present, otherwise
  * returns a failed `Result` with the non-done cause.
  *
+ * @see {@link filterDone} for preserving the typed `Cause.Done` value when the done payload matters
+ * @see {@link filterDoneLeftover} for extracting only the done leftover value
+ * @see {@link filterNoDone} for the inverse filter that succeeds only when no done failure is present
+ *
  * @category Done
  * @since 4.0.0
  */
@@ -214,11 +325,19 @@ export const filterDoneVoid: <E extends Cause.Done>(
 /**
  * Keeps a `Cause` only when it contains no `Cause.Done` failures.
  *
+ * **When to use**
+ *
+ * Use to select ordinary failure causes for handling while leaving `Cause.Done`
+ * completion causes outside that handler.
+ *
  * **Details**
  *
  * Returns a successful `Result` with the cause when every failure is non-done;
  * otherwise returns a failed `Result` with the original cause.
  *
+ * @see {@link filterDone} for the inverse typed done filter
+ * @see {@link filterDoneVoid} for done detection when the payload is not needed
+ *
  * @category Done
  * @since 4.0.0
  */
@@ -234,6 +353,11 @@ export const filterNoDone: <E>(
 /**
  * Filters a Cause to extract the leftover value from done errors.
  *
+ * **When to use**
+ *
+ * Use to extract only the leftover value carried by a `Cause.Done` completion
+ * signal.
+ *
  * @category Done
  * @since 4.0.0
  */
@@ -248,11 +372,20 @@ export const filterDoneLeftover: <E>(
  * Converts a `Cause` into an `Exit`, treating `Cause.Done` as successful
  * completion.
  *
+ * **When to use**
+ *
+ * Use to produce an `Exit` for finalizing a low-level pull workflow when a
+ * `Cause.Done` signal should be treated as success and any remaining cause
+ * should fail.
+ *
  * **Details**
  *
  * If the cause contains a done value, that leftover becomes the successful
  * value. Otherwise the non-done cause becomes the failure cause.
  *
+ * @see {@link filterDone} for extracting the done signal without converting the cause to an `Exit`
+ * @see {@link matchEffect} for handling `Pull` success, failure, and done outcomes directly
+ *
  * @category Done
  * @since 4.0.0
  */
@@ -264,6 +397,10 @@ export const doneExitFromCause = <E>(cause: Cause.Cause<E>): Exit.Exit<Cause.Don
 /**
  * Pattern matches on a Pull, handling success, failure, and done cases.
  *
+ * **When to use**
+ *
+ * Use to handle all three `Pull` outcomes with effectful handlers.
+ *
  * **Example** (Matching Pull outcomes)
  *
  * ```ts
@@ -285,6 +422,10 @@ export const matchEffect: {
   /**
    * Pattern matches on a Pull, handling success, failure, and done cases.
    *
+   * **When to use**
+   *
+   * Use to handle all three `Pull` outcomes with effectful handlers.
+   *
    * **Example** (Matching Pull outcomes)
    *
    * ```ts
@@ -312,6 +453,10 @@ export const matchEffect: {
   /**
    * Pattern matches on a Pull, handling success, failure, and done cases.
    *
+   * **When to use**
+   *
+   * Use to handle all three `Pull` outcomes with effectful handlers.
+   *
    * **Example** (Matching Pull outcomes)
    *
    * ```ts