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

package/src/TxSubscriptionRef.ts

@@ -1,6 +1,39 @@
 /**
- * TxSubscriptionRef is a TxRef that allows subscribing to all committed changes. Subscribers
- * receive the current value followed by every subsequent update via a transactional queue.
+ * The `TxSubscriptionRef` module provides a transactional reference that can
+ * also be observed as a stream of committed values. It combines the read and
+ * update behavior of a `TxRef.TxRef` with a subscription channel, so each
+ * subscriber first receives the current value and then receives every value
+ * published by later updates.
+ *
+ * **Mental model**
+ *
+ * - The current value is stored transactionally and can be read with
+ *   {@link get}
+ * - Mutations such as {@link set}, {@link update}, and {@link modify} commit a
+ *   new value and publish that value to active subscribers
+ * - {@link changes} creates a scoped transactional queue for one subscriber
+ * - {@link changesStream} exposes the same change feed as a `Stream.Stream`
+ * - Subscriptions are per subscriber; each subscriber gets its own queue of
+ *   committed values
+ *
+ * **Common tasks**
+ *
+ * - Create observable transactional state with {@link make}
+ * - Read or replace the current value with {@link get} and {@link set}
+ * - Derive new values atomically with {@link update} or {@link modify}
+ * - Consume changes from transactional code with {@link changes}
+ * - Consume changes from stream pipelines with {@link changesStream}
+ *
+ * **Gotchas**
+ *
+ * - A subscription starts with the value current at subscription time, not just
+ *   future updates
+ * - The queue returned by {@link changes} is scoped; leaving the scope removes
+ *   the subscriber
+ * - Updates are published even when the new value is equal to the previous
+ *   value
+ * - Subscriber queues are unbounded, so long-lived slow subscribers can retain
+ *   pending values until they catch up or their scope closes
  *
  * @since 4.0.0
  */
@@ -24,6 +57,11 @@ const TypeId = "~effect/transactions/TxSubscriptionRef"
  * committed changes. Subscribers receive the current value followed by every subsequent
  * update via a transactional dequeue.
  *
+ * **When to use**
+ *
+ * Use to store transactional state whose committed changes must be observable by
+ * subscribers.
+ *
  * **Example** (Subscribing to transactional changes)
  *
  * ```ts
@@ -46,6 +84,10 @@ const TypeId = "~effect/transactions/TxSubscriptionRef"
  * })
  * ```
  *
+ * @see {@link make} for creating a transactional subscription reference
+ * @see {@link changes} for subscribing through a transactional queue
+ * @see {@link changesStream} for subscribing through a `Stream`
+ *
  * @category models
  * @since 4.0.0
  */
@@ -79,6 +121,11 @@ const TxSubscriptionRefProto: Omit<TxSubscriptionRef<any>, typeof TypeId | "ref"
 /**
  * Creates a new TxSubscriptionRef with the specified initial value.
  *
+ * **When to use**
+ *
+ * Use to create transactional state that also publishes every committed update
+ * to subscribers.
+ *
  * **Example** (Creating a transactional subscription reference)
  *
  * ```ts
@@ -91,6 +138,8 @@ const TxSubscriptionRefProto: Omit<TxSubscriptionRef<any>, typeof TypeId | "ref"
  * })
  * ```
  *
+ * @see {@link changes} for subscribing to the created reference
+ *
  * @category constructors
  * @since 3.10.0
  */
@@ -112,6 +161,11 @@ export const make = <A>(value: A): Effect.Effect<TxSubscriptionRef<A>> =>
 /**
  * Reads the current value of the TxSubscriptionRef.
  *
+ * **When to use**
+ *
+ * Use to read the current transactional value without subscribing to future
+ * changes.
+ *
  * **Example** (Reading the current value)
  *
  * ```ts
@@ -124,6 +178,8 @@ export const make = <A>(value: A): Effect.Effect<TxSubscriptionRef<A>> =>
  * })
  * ```
  *
+ * @see {@link changes} for reading the current value and subsequent updates
+ *
  * @category getters
  * @since 3.10.0
  */
@@ -137,6 +193,11 @@ export const get = <A>(self: TxSubscriptionRef<A>): Effect.Effect<A> => TxRef.ge
  * Modifies the value of the TxSubscriptionRef using a function that returns both a
  * result and the new value. The new value is published to all subscribers atomically.
  *
+ * **When to use**
+ *
+ * Use to compute a separate return value and next state in one transactional
+ * update.
+ *
  * **Example** (Modifying and returning a value)
  *
  * ```ts
@@ -150,6 +211,9 @@ export const get = <A>(self: TxSubscriptionRef<A>): Effect.Effect<A> => TxRef.ge
  * })
  * ```
  *
+ * @see {@link update} for deriving the next value without a separate return value
+ * @see {@link set} for replacing the value directly
+ *
  * @category mutations
  * @since 3.10.0
  */
@@ -162,6 +226,11 @@ export const modify: {
    * Modifies the value of the TxSubscriptionRef using a function that returns both a
    * result and the new value. The new value is published to all subscribers atomically.
    *
+   * **When to use**
+   *
+   * Use to compute a separate return value and next state in one transactional
+   * update.
+   *
    * **Example** (Modifying and returning a value)
    *
    * ```ts
@@ -175,6 +244,9 @@ export const modify: {
    * })
    * ```
    *
+   * @see {@link update} for deriving the next value without a separate return value
+   * @see {@link set} for replacing the value directly
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -187,6 +259,11 @@ export const modify: {
    * Modifies the value of the TxSubscriptionRef using a function that returns both a
    * result and the new value. The new value is published to all subscribers atomically.
    *
+   * **When to use**
+   *
+   * Use to compute a separate return value and next state in one transactional
+   * update.
+   *
    * **Example** (Modifying and returning a value)
    *
    * ```ts
@@ -200,6 +277,9 @@ export const modify: {
    * })
    * ```
    *
+   * @see {@link update} for deriving the next value without a separate return value
+   * @see {@link set} for replacing the value directly
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -225,6 +305,10 @@ export const modify: {
 /**
  * Sets the value of the TxSubscriptionRef and publishes the new value to all subscribers.
  *
+ * **When to use**
+ *
+ * Use to replace the current value with a known value and publish it.
+ *
  * **Example** (Setting a new value)
  *
  * ```ts
@@ -237,6 +321,9 @@ export const modify: {
  * })
  * ```
  *
+ * @see {@link update} for deriving the new value from the current value
+ * @see {@link getAndSet} for setting while returning the previous value
+ *
  * @category mutations
  * @since 3.10.0
  */
@@ -244,6 +331,10 @@ export const set: {
   /**
    * Sets the value of the TxSubscriptionRef and publishes the new value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to replace the current value with a known value and publish it.
+   *
    * **Example** (Setting a new value)
    *
    * ```ts
@@ -256,6 +347,9 @@ export const set: {
    * })
    * ```
    *
+   * @see {@link update} for deriving the new value from the current value
+   * @see {@link getAndSet} for setting while returning the previous value
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -263,6 +357,10 @@ export const set: {
   /**
    * Sets the value of the TxSubscriptionRef and publishes the new value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to replace the current value with a known value and publish it.
+   *
    * **Example** (Setting a new value)
    *
    * ```ts
@@ -275,6 +373,9 @@ export const set: {
    * })
    * ```
    *
+   * @see {@link update} for deriving the new value from the current value
+   * @see {@link getAndSet} for setting while returning the previous value
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -288,6 +389,10 @@ export const set: {
  * Updates the value of the TxSubscriptionRef using a function and publishes the new
  * value to all subscribers.
  *
+ * **When to use**
+ *
+ * Use to derive the next value from the current value and publish it.
+ *
  * **Example** (Updating a value)
  *
  * ```ts
@@ -300,6 +405,9 @@ export const set: {
  * })
  * ```
  *
+ * @see {@link set} for replacing the value directly
+ * @see {@link updateAndGet} for returning the new value after the update
+ *
  * @category mutations
  * @since 3.10.0
  */
@@ -308,6 +416,10 @@ export const update: {
    * Updates the value of the TxSubscriptionRef using a function and publishes the new
    * value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to derive the next value from the current value and publish it.
+   *
    * **Example** (Updating a value)
    *
    * ```ts
@@ -320,6 +432,9 @@ export const update: {
    * })
    * ```
    *
+   * @see {@link set} for replacing the value directly
+   * @see {@link updateAndGet} for returning the new value after the update
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -328,6 +443,10 @@ export const update: {
    * Updates the value of the TxSubscriptionRef using a function and publishes the new
    * value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to derive the next value from the current value and publish it.
+   *
    * **Example** (Updating a value)
    *
    * ```ts
@@ -340,6 +459,9 @@ export const update: {
    * })
    * ```
    *
+   * @see {@link set} for replacing the value directly
+   * @see {@link updateAndGet} for returning the new value after the update
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -354,6 +476,10 @@ export const update: {
  * Gets the current value and sets a new value atomically. Publishes the new value
  * to all subscribers.
  *
+ * **When to use**
+ *
+ * Use to replace the value while returning the previous value.
+ *
  * **Example** (Getting and setting atomically)
  *
  * ```ts
@@ -367,6 +493,9 @@ export const update: {
  * })
  * ```
  *
+ * @see {@link set} for setting without returning the previous value
+ * @see {@link getAndUpdate} for deriving the new value from the previous value
+ *
  * @category mutations
  * @since 3.10.0
  */
@@ -375,6 +504,10 @@ export const getAndSet: {
    * Gets the current value and sets a new value atomically. Publishes the new value
    * to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to replace the value while returning the previous value.
+   *
    * **Example** (Getting and setting atomically)
    *
    * ```ts
@@ -388,6 +521,9 @@ export const getAndSet: {
    * })
    * ```
    *
+   * @see {@link set} for setting without returning the previous value
+   * @see {@link getAndUpdate} for deriving the new value from the previous value
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -396,6 +532,10 @@ export const getAndSet: {
    * Gets the current value and sets a new value atomically. Publishes the new value
    * to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to replace the value while returning the previous value.
+   *
    * **Example** (Getting and setting atomically)
    *
    * ```ts
@@ -409,6 +549,9 @@ export const getAndSet: {
    * })
    * ```
    *
+   * @see {@link set} for setting without returning the previous value
+   * @see {@link getAndUpdate} for deriving the new value from the previous value
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -422,6 +565,10 @@ export const getAndSet: {
  * Gets the current value and updates it using a function atomically. Publishes
  * the new value to all subscribers.
  *
+ * **When to use**
+ *
+ * Use to derive and publish a new value while returning the previous value.
+ *
  * **Example** (Getting and updating atomically)
  *
  * ```ts
@@ -435,6 +582,9 @@ export const getAndSet: {
  * })
  * ```
  *
+ * @see {@link update} for updating without returning the previous value
+ * @see {@link updateAndGet} for returning the new value instead
+ *
  * @category mutations
  * @since 3.10.0
  */
@@ -443,6 +593,10 @@ export const getAndUpdate: {
    * Gets the current value and updates it using a function atomically. Publishes
    * the new value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to derive and publish a new value while returning the previous value.
+   *
    * **Example** (Getting and updating atomically)
    *
    * ```ts
@@ -456,6 +610,9 @@ export const getAndUpdate: {
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the previous value
+   * @see {@link updateAndGet} for returning the new value instead
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -464,6 +621,10 @@ export const getAndUpdate: {
    * Gets the current value and updates it using a function atomically. Publishes
    * the new value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to derive and publish a new value while returning the previous value.
+   *
    * **Example** (Getting and updating atomically)
    *
    * ```ts
@@ -477,6 +638,9 @@ export const getAndUpdate: {
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the previous value
+   * @see {@link updateAndGet} for returning the new value instead
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -491,6 +655,10 @@ export const getAndUpdate: {
  * Updates the value using a function and returns the new value. Publishes the
  * new value to all subscribers.
  *
+ * **When to use**
+ *
+ * Use to derive and publish a new value while returning that new value.
+ *
  * **Example** (Updating and reading atomically)
  *
  * ```ts
@@ -503,6 +671,9 @@ export const getAndUpdate: {
  * })
  * ```
  *
+ * @see {@link update} for updating without returning the new value
+ * @see {@link getAndUpdate} for returning the previous value instead
+ *
  * @category mutations
  * @since 3.10.0
  */
@@ -511,6 +682,10 @@ export const updateAndGet: {
    * Updates the value using a function and returns the new value. Publishes the
    * new value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to derive and publish a new value while returning that new value.
+   *
    * **Example** (Updating and reading atomically)
    *
    * ```ts
@@ -523,6 +698,9 @@ export const updateAndGet: {
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the new value
+   * @see {@link getAndUpdate} for returning the previous value instead
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -531,6 +709,10 @@ export const updateAndGet: {
    * Updates the value using a function and returns the new value. Publishes the
    * new value to all subscribers.
    *
+   * **When to use**
+   *
+   * Use to derive and publish a new value while returning that new value.
+   *
    * **Example** (Updating and reading atomically)
    *
    * ```ts
@@ -543,6 +725,9 @@ export const updateAndGet: {
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the new value
+   * @see {@link getAndUpdate} for returning the previous value instead
+   *
    * @category mutations
    * @since 3.10.0
    */
@@ -564,6 +749,10 @@ export const updateAndGet: {
  * Subscribes to all changes of the TxSubscriptionRef. Returns a scoped TxDequeue
  * that first yields the current value, then every subsequent update.
  *
+ * **When to use**
+ *
+ * Use to subscribe to committed changes through a scoped transactional queue.
+ *
  * **Example** (Subscribing to changes)
  *
  * ```ts
@@ -586,6 +775,8 @@ export const updateAndGet: {
  * })
  * ```
  *
+ * @see {@link changesStream} for subscribing through a `Stream`
+ *
  * @category subscriptions
  * @since 3.10.0
  */
@@ -608,6 +799,10 @@ export const changes = <A>(
  * Returns a Stream of all changes to the TxSubscriptionRef, starting with the
  * current value followed by every subsequent update.
  *
+ * **When to use**
+ *
+ * Use to consume committed changes as a `Stream`.
+ *
  * **Example** (Streaming changes)
  *
  * ```ts
@@ -625,6 +820,8 @@ export const changes = <A>(
  * })
  * ```
  *
+ * @see {@link changes} for subscribing through a transactional queue
+ *
  * @category subscriptions
  * @since 3.10.0
  */
@@ -643,6 +840,10 @@ export const changesStream = <A>(self: TxSubscriptionRef<A>): Stream.Stream<A, n
 /**
  * Checks if the given value is a TxSubscriptionRef.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a `TxSubscriptionRef`.
+ *
  * **Example** (Checking transactional subscription references)
  *
  * ```ts
@@ -655,6 +856,8 @@ export const changesStream = <A>(self: TxSubscriptionRef<A>): Stream.Stream<A, n
  * }
  * ```
  *
+ * @see {@link make} for creating a `TxSubscriptionRef`
+ *
  * @category guards
  * @since 4.0.0
  */

package/src/Types.ts

@@ -298,7 +298,7 @@ export type Simplify<A> = {
  *
  * **When to use**
  *
- * Use in conditional types or type-level tests to assert type equality.
+ * Use to assert type equality in conditional types or type-level tests.
  *
  * **Details**
  *
@@ -457,7 +457,7 @@ export type MergeRight<Target, Source> = Simplify<
  *
  * **When to use**
  *
- * Prefer {@link MergeLeft} or {@link MergeRight} for clarity about which
+ * Use when prefer {@link MergeLeft} or {@link MergeRight} for clarity about which
  * side wins.
  *
  * **Example** (Merging records)
@@ -484,6 +484,10 @@ export type MergeRecord<Source, Target> = MergeLeft<Source, Target>
  * Describes the concurrency level for Effect operations that run multiple
  * effects.
  *
+ * **When to use**
+ *
+ * Use to type options that control how many effects may run at the same time.
+ *
  * **Details**
  *
  * - `number` — run at most N effects concurrently.
@@ -587,8 +591,8 @@ export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepM
  *
  * **When to use**
  *
- * Use on a function parameter when you want inference to come from other
- * parameters, not this one.
+ * Use when a function parameter must match an inferred type without becoming
+ * an inference source.
  *
  * **Details**
  *
@@ -647,12 +651,20 @@ export type Invariant<A> = (_: A) => A
 /**
  * Namespace for {@link Invariant}-related utilities.
  *
+ * **When to use**
+ *
+ * Use when referring to type-level helpers nested under `Invariant`.
+ *
  * @since 3.9.0
  */
 export declare namespace Invariant {
   /**
    * Extracts the type parameter `A` from an `Invariant<A>`.
    *
+   * **When to use**
+   *
+   * Use to recover the carried type from an invariant phantom marker.
+   *
    * **Example** (Extracting the inner type)
    *
    * ```ts
@@ -707,12 +719,20 @@ export type Covariant<A> = (_: never) => A
 /**
  * Namespace for {@link Covariant}-related utilities.
  *
+ * **When to use**
+ *
+ * Use when referring to type-level helpers nested under `Covariant`.
+ *
  * @since 3.9.0
  */
 export declare namespace Covariant {
   /**
    * Extracts the type parameter `A` from a `Covariant<A>`.
    *
+   * **When to use**
+   *
+   * Use to recover the carried type from a covariant phantom marker.
+   *
    * **Example** (Extracting the inner type)
    *
    * ```ts
@@ -767,12 +787,20 @@ export type Contravariant<A> = (_: A) => void
 /**
  * Namespace for {@link Contravariant}-related utilities.
  *
+ * **When to use**
+ *
+ * Use when referring to type-level helpers nested under `Contravariant`.
+ *
  * @since 3.9.0
  */
 export declare namespace Contravariant {
   /**
    * Extracts the type parameter `A` from a `Contravariant<A>`.
    *
+   * **When to use**
+   *
+   * Use to recover the carried type from a contravariant phantom marker.
+   *
    * **Example** (Extracting the inner type)
    *
    * ```ts
@@ -794,6 +822,10 @@ export declare namespace Contravariant {
  * Conditional type that returns `void` if `S` is an empty object type,
  * otherwise returns `S`.
  *
+ * **When to use**
+ *
+ * Use to erase an empty object type from an API result or parameter position.
+ *
  * @category types
  * @since 3.19.20
  */
@@ -829,8 +861,7 @@ export type NotFunction<T> = T extends Function ? never : T
  *
  * **When to use**
  *
- * Use in generic functions to catch accidental extra properties at compile
- * time.
+ * Use to catch accidental extra properties in generic functions at compile time.
  *
  * **Details**
  *
@@ -856,6 +887,11 @@ export type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyo
 /**
  * Branded marker interface representing an unassigned type parameter.
  *
+ * **When to use**
+ *
+ * Use when Effect's type-level machinery needs to represent a type parameter
+ * that has not been assigned yet.
+ *
  * **Details**
  *
  * Used internally by the Effect type system to indicate that a type parameter
@@ -873,6 +909,11 @@ export interface unassigned {
 /**
  * Branded marker interface representing an unhandled error type.
  *
+ * **When to use**
+ *
+ * Use when Effect's type-level machinery needs to represent an error type that
+ * has not been handled yet.
+ *
  * **Details**
  *
  * Used internally by the Effect type system to indicate that an error type
@@ -890,6 +931,10 @@ export interface unhandled {
 /**
  * Checks whether a type `T` is a union type.
  *
+ * **When to use**
+ *
+ * Use to branch type-level logic depending on whether a type is a union.
+ *
  * **Details**
  *
  * - Compares `[T]` against `[UnionToIntersection<T>]`. If they differ, `T`
@@ -950,6 +995,11 @@ export type ReasonOf<E> = E extends { readonly reason: infer R } ? R : never
 /**
  * Extracts the `_tag` values from the `reason` type of an error.
  *
+ * **When to use**
+ *
+ * Use to get the discriminant values available inside a nested `reason`
+ * error union.
+ *
  * **Details**
  *
  * This is shorthand for `Tags<ReasonOf<E>>`. It returns `never` if `E` has no
@@ -1129,6 +1179,10 @@ export type ExcludeReason<E, K extends string> = E extends { readonly reason: in
 /**
  * Extracts the required keys from a type.
  *
+ * **When to use**
+ *
+ * Use to derive the keys whose properties must be present on an object type.
+ *
  * @category types
  * @since 4.0.0
  */