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

package/src/SynchronizedRef.ts

@@ -1,4 +1,26 @@
 /**
+ * The `SynchronizedRef` module provides mutable references whose updates are
+ * serialized, including updates that run effects before deciding the next
+ * value. A `SynchronizedRef<A>` behaves like a `Ref<A>` for reading and basic
+ * updates, but uses an internal semaphore so concurrent modifications observe a
+ * consistent current value and apply one at a time.
+ *
+ * **When to use**
+ *
+ * - Coordinating shared state that may be updated by many fibers
+ * - Running effectful state transitions that must not overlap
+ * - Computing both a return value and a new stored value atomically
+ * - Applying partial updates with `Option`, where `None` leaves the value
+ *   unchanged
+ *
+ * **Gotchas**
+ *
+ * - Effectful update functions run while the semaphore is held, so long-running
+ *   effects delay other updates to the same ref
+ * - Failed effectful updates do not replace the stored value
+ * - `getUnsafe` and `makeUnsafe` bypass the `Effect` API and should be reserved
+ *   for low-level or carefully controlled code
+ *
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -11,8 +33,11 @@ import * as Semaphore from "./Semaphore.ts"
 const TypeId = "~effect/SynchronizedRef"
 
 /**
- * @since 2.0.0
+ * A mutable reference whose update and modify operations are serialized with an
+ * internal semaphore, including effectful transformations.
+ *
  * @category models
+ * @since 2.0.0
  */
 export interface SynchronizedRef<in out A> extends Ref.Ref<A> {
   readonly [TypeId]: typeof TypeId
@@ -32,8 +57,12 @@ const Proto = {
 }
 
 /**
- * @since 4.0.0
+ * Creates a `SynchronizedRef` synchronously from an initial value.
+ *
+ * This bypasses `Effect` construction; prefer `make` in effectful code.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeUnsafe = <A>(value: A): SynchronizedRef<A> => {
   const self = Object.create(Proto)
@@ -43,36 +72,52 @@ export const makeUnsafe = <A>(value: A): SynchronizedRef<A> => {
 }
 
 /**
- * @since 2.0.0
+ * Creates a `SynchronizedRef` from an initial value, wrapped in an `Effect`.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A>(value: A): Effect.Effect<SynchronizedRef<A>> => Effect.sync(() => makeUnsafe(value))
 
 /**
- * @since 2.0.0
+ * Reads the current value synchronously, bypassing the `Effect` API and the
+ * ref's semaphore.
+ *
  * @category getters
+ * @since 2.0.0
  */
 export const getUnsafe = <A>(self: SynchronizedRef<A>): A => self.backing.ref.current
 
 /**
- * @since 2.0.0
+ * Returns an `Effect` that reads the current value of the `SynchronizedRef`.
+ *
  * @category getters
+ * @since 2.0.0
  */
 export const get = <A>(self: SynchronizedRef<A>): Effect.Effect<A> => Effect.sync(() => getUnsafe(self))
 
 /**
- * @since 2.0.0
+ * Atomically sets a new value and returns the previous value, serialized by the
+ * ref's semaphore.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const getAndSet: {
   /**
-   * @since 2.0.0
+   * Atomically sets a new value and returns the previous value, serialized by the
+   * ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * @since 2.0.0
+   * Atomically sets a new value and returns the previous value, serialized by the
+   * ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, value: A): Effect.Effect<A>
 } = dual(
@@ -82,18 +127,27 @@ export const getAndSet: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically updates the current value with a function and returns the previous
+ * value, serialized by the ref's semaphore.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdate: {
   /**
-   * @since 2.0.0
+   * Atomically updates the current value with a function and returns the previous
+   * value, serialized by the ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * @since 2.0.0
+   * Atomically updates the current value with a function and returns the previous
+   * value, serialized by the ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, f: (a: A) => A): Effect.Effect<A>
 } = dual(
@@ -103,18 +157,27 @@ export const getAndUpdate: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically runs an effectful update while holding the ref's semaphore, sets
+ * the new value if the effect succeeds, and returns the previous value.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdateEffect: {
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful update while holding the ref's semaphore, sets
+   * the new value if the effect succeeds, and returns the previous value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(f: (a: A) => Effect.Effect<A, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<A, E, R>
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful update while holding the ref's semaphore, sets
+   * the new value if the effect succeeds, and returns the previous value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(self: SynchronizedRef<A>, f: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = dual(
@@ -130,18 +193,30 @@ export const getAndUpdateEffect: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically applies a partial update and returns the previous value. If the
+ * function returns `Option.some`, the ref is updated; if it returns
+ * `Option.none`, the ref is left unchanged.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdateSome: {
   /**
-   * @since 2.0.0
+   * Atomically applies a partial update and returns the previous value. If the
+   * function returns `Option.some`, the ref is updated; if it returns
+   * `Option.none`, the ref is left unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * @since 2.0.0
+   * Atomically applies a partial update and returns the previous value. If the
+   * function returns `Option.some`, the ref is updated; if it returns
+   * `Option.none`, the ref is left unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, pf: (a: A) => Option.Option<A>): Effect.Effect<A>
 } = dual(
@@ -151,18 +226,30 @@ export const getAndUpdateSome: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically runs an effectful partial update while holding the ref's semaphore
+ * and returns the previous value. `Option.some` updates the ref; `Option.none`
+ * leaves it unchanged.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdateSomeEffect: {
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful partial update while holding the ref's semaphore
+   * and returns the previous value. `Option.some` updates the ref; `Option.none`
+   * leaves it unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(pf: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<A, E, R>
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful partial update while holding the ref's semaphore
+   * and returns the previous value. `Option.some` updates the ref; `Option.none`
+   * leaves it unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(
     self: SynchronizedRef<A>,
@@ -184,18 +271,27 @@ export const getAndUpdateSomeEffect: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically computes a return value and a new ref value, stores the new value,
+ * and returns the computed result.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const modify: {
   /**
-   * @since 2.0.0
+   * Atomically computes a return value and a new ref value, stores the new value,
+   * and returns the computed result.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, B>(f: (a: A) => readonly [B, A]): (self: SynchronizedRef<A>) => Effect.Effect<B>
   /**
-   * @since 2.0.0
+   * Atomically computes a return value and a new ref value, stores the new value,
+   * and returns the computed result.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, B>(self: SynchronizedRef<A>, f: (a: A) => readonly [B, A]): Effect.Effect<B>
 } = dual(
@@ -205,18 +301,27 @@ export const modify: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically runs an effectful modification while holding the ref's semaphore,
+ * stores the new value if the effect succeeds, and returns the computed result.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const modifyEffect: {
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful modification while holding the ref's semaphore,
+   * stores the new value if the effect succeeds, and returns the computed result.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, B, E, R>(f: (a: A) => Effect.Effect<readonly [B, A], E, R>): (self: SynchronizedRef<A>) => Effect.Effect<B, E, R>
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful modification while holding the ref's semaphore,
+   * stores the new value if the effect succeeds, and returns the computed result.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, B, E, R>(
     self: SynchronizedRef<A>,
@@ -235,18 +340,27 @@ export const modifyEffect: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically computes a return value and an optional new ref value.
+ * `Option.some` updates the ref; `Option.none` leaves it unchanged.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const modifySome: {
   /**
-   * @since 2.0.0
+   * Atomically computes a return value and an optional new ref value.
+   * `Option.some` updates the ref; `Option.none` leaves it unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]): (self: SynchronizedRef<A>) => Effect.Effect<B>
   /**
-   * @since 2.0.0
+   * Atomically computes a return value and an optional new ref value.
+   * `Option.some` updates the ref; `Option.none` leaves it unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, B>(self: SynchronizedRef<A>, pf: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>
 } = dual(
@@ -258,21 +372,33 @@ export const modifySome: {
 )
 
 /**
- * @since 2.0.0
+ * Atomically runs an effectful modification while holding the ref's semaphore.
+ * The effect computes a return value and an optional new ref value;
+ * `Option.some` updates the ref and `Option.none` leaves it unchanged.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const modifySomeEffect: {
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful modification while holding the ref's semaphore.
+   * The effect computes a return value and an optional new ref value;
+   * `Option.some` updates the ref and `Option.none` leaves it unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, B, R, E>(
     fallback: B,
     pf: (a: A) => Effect.Effect<readonly [B, Option.Option<A>], E, R>
   ): (self: SynchronizedRef<A>) => Effect.Effect<B, E, R>
   /**
-   * @since 2.0.0
+   * Atomically runs an effectful modification while holding the ref's semaphore.
+   * The effect computes a return value and an optional new ref value;
+   * `Option.some` updates the ref and `Option.none` leaves it unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, B, R, E>(
     self: SynchronizedRef<A>,
@@ -297,18 +423,24 @@ export const modifySomeEffect: {
 )
 
 /**
- * @since 2.0.0
+ * Sets the value of the `SynchronizedRef`, serialized by the ref's semaphore.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const set: {
   /**
-   * @since 2.0.0
+   * Sets the value of the `SynchronizedRef`, serialized by the ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A): (self: SynchronizedRef<A>) => Effect.Effect<void>
   /**
-   * @since 2.0.0
+   * Sets the value of the `SynchronizedRef`, serialized by the ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, value: A): Effect.Effect<void>
 } = dual(
@@ -318,18 +450,24 @@ export const set: {
 )
 
 /**
- * @since 2.0.0
+ * Sets the value of the `SynchronizedRef` and returns the new value.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const setAndGet: {
   /**
-   * @since 2.0.0
+   * Sets the value of the `SynchronizedRef` and returns the new value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * @since 2.0.0
+   * Sets the value of the `SynchronizedRef` and returns the new value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, value: A): Effect.Effect<A>
 } = dual(
@@ -339,18 +477,27 @@ export const setAndGet: {
 )
 
 /**
- * @since 2.0.0
+ * Updates the value of the `SynchronizedRef` with a function, serialized by the
+ * ref's semaphore.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const update: {
   /**
-   * @since 2.0.0
+   * Updates the value of the `SynchronizedRef` with a function, serialized by the
+   * ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A): (self: SynchronizedRef<A>) => Effect.Effect<void>
   /**
-   * @since 2.0.0
+   * Updates the value of the `SynchronizedRef` with a function, serialized by the
+   * ref's semaphore.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, f: (a: A) => A): Effect.Effect<void>
 } = dual(
@@ -360,18 +507,27 @@ export const update: {
 )
 
 /**
- * @since 2.0.0
+ * Runs an effectful update while holding the ref's semaphore and stores the new
+ * value if the effect succeeds.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const updateEffect: {
   /**
-   * @since 2.0.0
+   * Runs an effectful update while holding the ref's semaphore and stores the new
+   * value if the effect succeeds.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(f: (a: A) => Effect.Effect<A, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<void, E, R>
   /**
-   * @since 2.0.0
+   * Runs an effectful update while holding the ref's semaphore and stores the new
+   * value if the effect succeeds.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(self: SynchronizedRef<A>, f: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<void, E, R>
 } = dual(
@@ -386,18 +542,27 @@ export const updateEffect: {
 )
 
 /**
- * @since 2.0.0
+ * Updates the value of the `SynchronizedRef` with a function and returns the
+ * new value.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const updateAndGet: {
   /**
-   * @since 2.0.0
+   * Updates the value of the `SynchronizedRef` with a function and returns the
+   * new value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * @since 2.0.0
+   * Updates the value of the `SynchronizedRef` with a function and returns the
+   * new value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, f: (a: A) => A): Effect.Effect<A>
 } = dual(
@@ -407,18 +572,27 @@ export const updateAndGet: {
 )
 
 /**
- * @since 2.0.0
+ * Runs an effectful update while holding the ref's semaphore, stores the new
+ * value if the effect succeeds, and returns that new value.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const updateAndGetEffect: {
   /**
-   * @since 2.0.0
+   * Runs an effectful update while holding the ref's semaphore, stores the new
+   * value if the effect succeeds, and returns that new value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(f: (a: A) => Effect.Effect<A, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<A, E, R>
   /**
-   * @since 2.0.0
+   * Runs an effectful update while holding the ref's semaphore, stores the new
+   * value if the effect succeeds, and returns that new value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(self: SynchronizedRef<A>, f: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = dual(
@@ -434,18 +608,27 @@ export const updateAndGetEffect: {
 )
 
 /**
- * @since 2.0.0
+ * Applies a partial update to the current value. `Option.some` stores the new
+ * value; `Option.none` leaves the ref unchanged.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const updateSome: {
   /**
-   * @since 2.0.0
+   * Applies a partial update to the current value. `Option.some` stores the new
+   * value; `Option.none` leaves the ref unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => Option.Option<A>): (self: SynchronizedRef<A>) => Effect.Effect<void>
   /**
-   * @since 2.0.0
+   * Applies a partial update to the current value. `Option.some` stores the new
+   * value; `Option.none` leaves the ref unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, f: (a: A) => Option.Option<A>): Effect.Effect<void>
 } = dual(
@@ -455,18 +638,27 @@ export const updateSome: {
 )
 
 /**
- * @since 2.0.0
+ * Runs an effectful partial update while holding the ref's semaphore.
+ * `Option.some` stores the new value; `Option.none` leaves the ref unchanged.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const updateSomeEffect: {
   /**
-   * @since 2.0.0
+   * Runs an effectful partial update while holding the ref's semaphore.
+   * `Option.some` stores the new value; `Option.none` leaves the ref unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(pf: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<void, E, R>
   /**
-   * @since 2.0.0
+   * Runs an effectful partial update while holding the ref's semaphore.
+   * `Option.some` stores the new value; `Option.none` leaves the ref unchanged.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(
     self: SynchronizedRef<A>,
@@ -487,18 +679,30 @@ export const updateSomeEffect: {
 )
 
 /**
- * @since 2.0.0
+ * Applies a partial update and returns the resulting current value.
+ * `Option.some` stores and returns the new value; `Option.none` returns the
+ * unchanged value.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const updateSomeAndGet: {
   /**
-   * @since 2.0.0
+   * Applies a partial update and returns the resulting current value.
+   * `Option.some` stores and returns the new value; `Option.none` returns the
+   * unchanged value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * @since 2.0.0
+   * Applies a partial update and returns the resulting current value.
+   * `Option.some` stores and returns the new value; `Option.none` returns the
+   * unchanged value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: SynchronizedRef<A>, pf: (a: A) => Option.Option<A>): Effect.Effect<A>
 } = dual(
@@ -508,18 +712,30 @@ export const updateSomeAndGet: {
 )
 
 /**
- * @since 2.0.0
+ * Runs an effectful partial update while holding the ref's semaphore and
+ * returns the resulting current value. `Option.some` stores and returns the new
+ * value; `Option.none` returns the unchanged value.
+ *
  * @category utils
+ * @since 2.0.0
  */
 export const updateSomeAndGetEffect: {
   /**
-   * @since 2.0.0
+   * Runs an effectful partial update while holding the ref's semaphore and
+   * returns the resulting current value. `Option.some` stores and returns the new
+   * value; `Option.none` returns the unchanged value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(pf: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<A, E, R>
   /**
-   * @since 2.0.0
+   * Runs an effectful partial update while holding the ref's semaphore and
+   * returns the resulting current value. `Option.some` stores and returns the new
+   * value; `Option.none` returns the unchanged value.
+   *
    * @category utils
+   * @since 2.0.0
    */
   <A, R, E>(
     self: SynchronizedRef<A>,