effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/SubscriptionRef.ts

@@ -207,7 +207,7 @@ export const make = <A>(value: A): Effect.Effect<SubscriptionRef<A>> =>
 export const changes = <A>(self: SubscriptionRef<A>): Stream.Stream<A> => Stream.fromPubSub(self.pubsub)
 
 /**
- * Unsafely retrieves the current value of the `SubscriptionRef`.
+ * Retrieves the current value of the `SubscriptionRef` unsafely.
  *
  * **Gotchas**
  *
@@ -255,7 +255,7 @@ export const getUnsafe = <A>(self: SubscriptionRef<A>): A => self.value
 export const get = <A>(self: SubscriptionRef<A>): Effect.Effect<A> => Effect.sync(() => self.value)
 
 /**
- * Atomically retrieves the current value and sets a new value, notifying
+ * Retrieves the current value and sets a new value atomically, notifying
  * subscribers of the change.
  *
  * **Example** (Getting and setting a value)
@@ -279,7 +279,7 @@ export const get = <A>(self: SubscriptionRef<A>): Effect.Effect<A> => Effect.syn
  */
 export const getAndSet: {
   /**
-   * Atomically retrieves the current value and sets a new value, notifying
+   * Retrieves the current value and sets a new value atomically, notifying
    * subscribers of the change.
    *
    * **Example** (Getting and setting a value)
@@ -303,7 +303,7 @@ export const getAndSet: {
    */
   <A>(value: A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Atomically retrieves the current value and sets a new value, notifying
+   * Retrieves the current value and sets a new value atomically, notifying
    * subscribers of the change.
    *
    * **Example** (Getting and setting a value)
@@ -339,7 +339,7 @@ const setUnsafe = <A>(self: SubscriptionRef<A>, value: A) => {
 }
 
 /**
- * Atomically retrieves the current value and updates it with the result of
+ * Retrieves the current value and updates it atomically with the result of
  * applying a function, notifying subscribers of the change.
  *
  * **Example** (Getting and updating a value)
@@ -363,7 +363,7 @@ const setUnsafe = <A>(self: SubscriptionRef<A>, value: A) => {
  */
 export const getAndUpdate: {
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying a function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating a value)
@@ -387,7 +387,7 @@ export const getAndUpdate: {
    */
   <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying a function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating a value)
@@ -419,7 +419,7 @@ export const getAndUpdate: {
   })))
 
 /**
- * Atomically retrieves the current value and updates it with the result of
+ * Retrieves the current value and updates it atomically with the result of
  * applying an effectful function, notifying subscribers of the change.
  *
  * **Example** (Getting and updating with an effect)
@@ -446,7 +446,7 @@ export const getAndUpdate: {
  */
 export const getAndUpdateEffect: {
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying an effectful function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating with an effect)
@@ -473,7 +473,7 @@ export const getAndUpdateEffect: {
    */
   <A, E, R>(update: (a: A) => Effect.Effect<A, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying an effectful function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating with an effect)
@@ -512,9 +512,18 @@ export const getAndUpdateEffect: {
   })))
 
 /**
- * Atomically retrieves the current value and applies an update function. If
- * the function returns `Option.some`, sets and publishes that value; if it
- * returns `Option.none`, leaves the reference unchanged and does not publish.
+ * Retrieves the current value and optionally updates the reference.
+ *
+ * **When to use**
+ *
+ * Use to read the old value while applying a synchronous update only when a
+ * new value is available.
+ *
+ * **Details**
+ *
+ * If the function returns `Option.some`, the new value is set and published. If
+ * it returns `Option.none`, the reference is left unchanged and no update is
+ * published.
  *
  * **Example** (Getting and conditionally updating a value)
  *
@@ -540,9 +549,18 @@ export const getAndUpdateEffect: {
  */
 export const getAndUpdateSome: {
   /**
-   * Atomically retrieves the current value and applies an update function. If
-   * the function returns `Option.some`, sets and publishes that value; if it
-   * returns `Option.none`, leaves the reference unchanged and does not publish.
+   * Retrieves the current value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying a synchronous update only when a
+   * new value is available.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set and published. If
+   * it returns `Option.none`, the reference is left unchanged and no update is
+   * published.
    *
    * **Example** (Getting and conditionally updating a value)
    *
@@ -568,9 +586,18 @@ export const getAndUpdateSome: {
    */
   <A>(update: (a: A) => Option.Option<A>): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Atomically retrieves the current value and applies an update function. If
-   * the function returns `Option.some`, sets and publishes that value; if it
-   * returns `Option.none`, leaves the reference unchanged and does not publish.
+   * Retrieves the current value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying a synchronous update only when a
+   * new value is available.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set and published. If
+   * it returns `Option.none`, the reference is left unchanged and no update is
+   * published.
    *
    * **Example** (Getting and conditionally updating a value)
    *
@@ -610,10 +637,18 @@ export const getAndUpdateSome: {
   })))
 
 /**
- * Atomically retrieves the current value and applies an effectful update
- * function. If it succeeds with `Option.some`, sets and publishes that value;
- * if it succeeds with `Option.none`, leaves the reference unchanged and does
- * not publish.
+ * Retrieves the current value and optionally updates the reference effectfully.
+ *
+ * **When to use**
+ *
+ * Use to read the old value while applying an effectful update only when a new
+ * value is available.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set and
+ * published. If it succeeds with `Option.none`, the reference is left unchanged
+ * and no update is published.
  *
  * **Example** (Getting and conditionally updating with an effect)
  *
@@ -639,10 +674,18 @@ export const getAndUpdateSome: {
  */
 export const getAndUpdateSomeEffect: {
   /**
-   * Atomically retrieves the current value and applies an effectful update
-   * function. If it succeeds with `Option.some`, sets and publishes that value;
-   * if it succeeds with `Option.none`, leaves the reference unchanged and does
-   * not publish.
+   * Retrieves the current value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying an effectful update only when a new
+   * value is available.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Getting and conditionally updating with an effect)
    *
@@ -668,10 +711,18 @@ export const getAndUpdateSomeEffect: {
    */
   <A, R, E>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Atomically retrieves the current value and applies an effectful update
-   * function. If it succeeds with `Option.some`, sets and publishes that value;
-   * if it succeeds with `Option.none`, leaves the reference unchanged and does
-   * not publish.
+   * Retrieves the current value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying an effectful update only when a new
+   * value is available.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Getting and conditionally updating with an effect)
    *
@@ -713,7 +764,7 @@ export const getAndUpdateSomeEffect: {
   })))
 
 /**
- * Atomically modifies the `SubscriptionRef` with a function that computes a
+ * Modifies the `SubscriptionRef` atomically with a function that computes a
  * return value and a new value, notifying subscribers of the change.
  *
  * **Example** (Modifying a value)
@@ -740,7 +791,7 @@ export const getAndUpdateSomeEffect: {
  */
 export const modify: {
   /**
-   * Atomically modifies the `SubscriptionRef` with a function that computes a
+   * Modifies the `SubscriptionRef` atomically with a function that computes a
    * return value and a new value, notifying subscribers of the change.
    *
    * **Example** (Modifying a value)
@@ -767,7 +818,7 @@ export const modify: {
    */
   <A, B>(modify: (a: A) => readonly [B, A]): (self: SubscriptionRef<A>) => Effect.Effect<B>
   /**
-   * Atomically modifies the `SubscriptionRef` with a function that computes a
+   * Modifies the `SubscriptionRef` atomically with a function that computes a
    * return value and a new value, notifying subscribers of the change.
    *
    * **Example** (Modifying a value)
@@ -804,7 +855,7 @@ export const modify: {
   })))
 
 /**
- * Atomically modifies the `SubscriptionRef` with an effectful function that
+ * Modifies the `SubscriptionRef` atomically with an effectful function that
  * computes a return value and a new value, notifying subscribers of the
  * change.
  *
@@ -832,7 +883,7 @@ export const modify: {
  */
 export const modifyEffect: {
   /**
-   * Atomically modifies the `SubscriptionRef` with an effectful function that
+   * Modifies the `SubscriptionRef` atomically with an effectful function that
    * computes a return value and a new value, notifying subscribers of the
    * change.
    *
@@ -860,7 +911,7 @@ export const modifyEffect: {
    */
   <B, A, E, R>(modify: (a: A) => Effect.Effect<readonly [B, A], E, R>): (self: SubscriptionRef<A>) => Effect.Effect<B, E, R>
   /**
-   * Atomically modifies the `SubscriptionRef` with an effectful function that
+   * Modifies the `SubscriptionRef` atomically with an effectful function that
    * computes a return value and a new value, notifying subscribers of the
    * change.
    *
@@ -902,9 +953,18 @@ export const modifyEffect: {
   )))
 
 /**
- * Atomically computes a return value and an optional new value. If the function
- * returns `Option.some` for the new value, sets and publishes it; if it returns
- * `Option.none`, leaves the reference unchanged and does not publish.
+ * Computes a return value and optionally updates the reference.
+ *
+ * **When to use**
+ *
+ * Use to return a separate result while synchronously deciding whether to
+ * publish a new value.
+ *
+ * **Details**
+ *
+ * If the function returns `Option.some` for the new value, the value is set and
+ * published. If it returns `Option.none`, the reference is left unchanged and
+ * no update is published.
  *
  * **Example** (Conditionally modifying a value)
  *
@@ -931,9 +991,18 @@ export const modifyEffect: {
  */
 export const modifySome: {
   /**
-   * Atomically computes a return value and an optional new value. If the function
-   * returns `Option.some` for the new value, sets and publishes it; if it returns
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while synchronously deciding whether to
+   * publish a new value.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some` for the new value, the value is set and
+   * published. If it returns `Option.none`, the reference is left unchanged and
+   * no update is published.
    *
    * **Example** (Conditionally modifying a value)
    *
@@ -960,9 +1029,18 @@ export const modifySome: {
    */
   <B, A>(modify: (a: A) => readonly [B, Option.Option<A>]): (self: SubscriptionRef<A>) => Effect.Effect<B>
   /**
-   * Atomically computes a return value and an optional new value. If the function
-   * returns `Option.some` for the new value, sets and publishes it; if it returns
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while synchronously deciding whether to
+   * publish a new value.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some` for the new value, the value is set and
+   * published. If it returns `Option.none`, the reference is left unchanged and
+   * no update is published.
    *
    * **Example** (Conditionally modifying a value)
    *
@@ -1000,10 +1078,18 @@ export const modifySome: {
   })))
 
 /**
- * Atomically computes a return value and an optional new value with an
- * effectful function. If the effect succeeds with `Option.some`, sets and
- * publishes the new value; if it succeeds with `Option.none`, leaves the
- * reference unchanged and does not publish.
+ * Computes a return value and optionally updates the reference effectfully.
+ *
+ * **When to use**
+ *
+ * Use to return a separate result while effectfully deciding whether to publish
+ * a new value.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set and
+ * published. If it succeeds with `Option.none`, the reference is left unchanged
+ * and no update is published.
  *
  * **Example** (Conditionally modifying with an effect)
  *
@@ -1034,10 +1120,18 @@ export const modifySome: {
  */
 export const modifySomeEffect: {
   /**
-   * Atomically computes a return value and an optional new value with an
-   * effectful function. If the effect succeeds with `Option.some`, sets and
-   * publishes the new value; if it succeeds with `Option.none`, leaves the
-   * reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while effectfully deciding whether to publish
+   * a new value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally modifying with an effect)
    *
@@ -1068,10 +1162,18 @@ export const modifySomeEffect: {
    */
   <A, B, R, E>(modify: (a: A) => Effect.Effect<readonly [B, Option.Option<A>], E, R>): (self: SubscriptionRef<A>) => Effect.Effect<B, E, R>
   /**
-   * Atomically computes a return value and an optional new value with an
-   * effectful function. If the effect succeeds with `Option.some`, sets and
-   * publishes the new value; if it succeeds with `Option.none`, leaves the
-   * reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while effectfully deciding whether to publish
+   * a new value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally modifying with an effect)
    *
@@ -1659,9 +1761,18 @@ export const updateSome: {
   })))
 
 /**
- * Applies an effectful update function to the current value. If it succeeds
- * with `Option.some`, sets and publishes that value; if it succeeds with
- * `Option.none`, leaves the reference unchanged and does not publish.
+ * Applies an effectful update only when it produces a new value.
+ *
+ * **When to use**
+ *
+ * Use to conditionally update a `SubscriptionRef` with an effectful function
+ * while discarding the resulting value.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set and
+ * published. If it succeeds with `Option.none`, the reference is left unchanged
+ * and no update is published.
  *
  * **Example** (Conditionally updating with an effect)
  *
@@ -1686,9 +1797,18 @@ export const updateSome: {
  */
 export const updateSomeEffect: {
   /**
-   * Applies an effectful update function to the current value. If it succeeds
-   * with `Option.some`, sets and publishes that value; if it succeeds with
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Applies an effectful update only when it produces a new value.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` with an effectful function
+   * while discarding the resulting value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally updating with an effect)
    *
@@ -1713,9 +1833,18 @@ export const updateSomeEffect: {
    */
   <A, E, R>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<void, E, R>
   /**
-   * Applies an effectful update function to the current value. If it succeeds
-   * with `Option.some`, sets and publishes that value; if it succeeds with
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Applies an effectful update only when it produces a new value.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` with an effectful function
+   * while discarding the resulting value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally updating with an effect)
    *
@@ -1754,10 +1883,18 @@ export const updateSomeEffect: {
   )))
 
 /**
- * Applies an update function and returns the resulting current value. If the
- * function returns `Option.some`, sets, publishes, and returns that value; if
- * it returns `Option.none`, returns the unchanged current value without
- * publishing.
+ * Applies an optional update and returns the current value afterward.
+ *
+ * **When to use**
+ *
+ * Use to conditionally update a `SubscriptionRef` and read the value that is
+ * current after the update decision.
+ *
+ * **Details**
+ *
+ * If the function returns `Option.some`, the new value is set, published, and
+ * returned. If it returns `Option.none`, the unchanged current value is
+ * returned without publishing.
  *
  * **Example** (Conditionally updating and reading the new value)
  *
@@ -1780,10 +1917,18 @@ export const updateSomeEffect: {
  */
 export const updateSomeAndGet: {
   /**
-   * Applies an update function and returns the resulting current value. If the
-   * function returns `Option.some`, sets, publishes, and returns that value; if
-   * it returns `Option.none`, returns the unchanged current value without
-   * publishing.
+   * Applies an optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` and read the value that is
+   * current after the update decision.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set, published, and
+   * returned. If it returns `Option.none`, the unchanged current value is
+   * returned without publishing.
    *
    * **Example** (Conditionally updating and reading the new value)
    *
@@ -1806,10 +1951,18 @@ export const updateSomeAndGet: {
    */
   <A>(update: (a: A) => Option.Option<A>): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Applies an update function and returns the resulting current value. If the
-   * function returns `Option.some`, sets, publishes, and returns that value; if
-   * it returns `Option.none`, returns the unchanged current value without
-   * publishing.
+   * Applies an optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` and read the value that is
+   * current after the update decision.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set, published, and
+   * returned. If it returns `Option.none`, the unchanged current value is
+   * returned without publishing.
    *
    * **Example** (Conditionally updating and reading the new value)
    *
@@ -1844,10 +1997,18 @@ export const updateSomeAndGet: {
   })))
 
 /**
- * Applies an effectful update function and returns the resulting current
- * value. If the effect succeeds with `Option.some`, sets, publishes, and
- * returns that value; if it succeeds with `Option.none`, returns the unchanged
- * current value without publishing.
+ * Applies an effectful optional update and returns the current value afterward.
+ *
+ * **When to use**
+ *
+ * Use to conditionally update a `SubscriptionRef` effectfully and read the
+ * value that is current after the update decision.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set, published,
+ * and returned. If it succeeds with `Option.none`, the unchanged current value
+ * is returned without publishing.
  *
  * **Example** (Conditionally updating with an effect and reading the new value)
  *
@@ -1870,10 +2031,18 @@ export const updateSomeAndGet: {
  */
 export const updateSomeAndGetEffect: {
   /**
-   * Applies an effectful update function and returns the resulting current
-   * value. If the effect succeeds with `Option.some`, sets, publishes, and
-   * returns that value; if it succeeds with `Option.none`, returns the unchanged
-   * current value without publishing.
+   * Applies an effectful optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` effectfully and read the
+   * value that is current after the update decision.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set, published,
+   * and returned. If it succeeds with `Option.none`, the unchanged current value
+   * is returned without publishing.
    *
    * **Example** (Conditionally updating with an effect and reading the new value)
    *
@@ -1896,10 +2065,18 @@ export const updateSomeAndGetEffect: {
    */
   <A, E, R>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Applies an effectful update function and returns the resulting current
-   * value. If the effect succeeds with `Option.some`, sets, publishes, and
-   * returns that value; if it succeeds with `Option.none`, returns the unchanged
-   * current value without publishing.
+   * Applies an effectful optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` effectfully and read the
+   * value that is current after the update decision.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set, published,
+   * and returned. If it succeeds with `Option.none`, the unchanged current value
+   * is returned without publishing.
    *
    * **Example** (Conditionally updating with an effect and reading the new value)
    *

package/src/Symbol.ts

@@ -27,7 +27,7 @@
 import * as predicate from "./Predicate.ts"
 
 /**
- * Tests if a value is a `symbol`.
+ * Checks whether a value is a `symbol`.
  *
  * **When to use**
  *