effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Redacted.ts

@@ -155,7 +155,7 @@ export declare namespace Redacted {
    * console.log(rotate({ token: "secret" })) // { token: "secret:rotated" }
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 3.3.0
    */
   export type Value<T extends Redacted<any>> = [T] extends [Redacted<infer _A>] ? _A : never
@@ -258,7 +258,7 @@ const Proto = {
  *
  * **When to use**
  *
- * Use when the underlying sensitive value is required at a trusted boundary.
+ * Use when you need the underlying sensitive value at a trusted boundary.
  *
  * **Example** (Retrieving a redacted value)
  *
@@ -321,8 +321,8 @@ export const wipeUnsafe = <T>(self: Redacted<T>): boolean => redacted.redactedRe
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` for `Redacted` values based on their
- * underlying values.
+ * Use when you need to compare wrapped secrets through an approved equality
+ * rule without exposing the underlying values at each comparison site.
  *
  * **Example** (Comparing redacted values)
  *
@@ -340,7 +340,7 @@ export const wipeUnsafe = <T>(self: Redacted<T>): boolean => redacted.redactedRe
  * assert.equal(equivalence(API_KEY1, API_KEY3), true)
  * ```
  *
- * @category equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const makeEquivalence = <A>(isEquivalent: Equivalence.Equivalence<A>): Equivalence.Equivalence<Redacted<A>> =>

package/src/Reducer.ts

@@ -201,9 +201,8 @@ export function make<A>(
  *
  * **When to use**
  *
- * Use when you need the "right" value to act as the accumulator side.
- * - You want to reverse the natural direction of a non-commutative reducer
- *   (e.g. string concatenation becomes prepend).
+ * Use when you want the right-hand value to act as the accumulator, or need to
+ * reverse a non-commutative reducer such as string concatenation.
  *
  * **Details**
  *

package/src/Ref.ts

@@ -205,7 +205,7 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
  *
  * **When to use**
  *
- * Use to create shared mutable state inside an Effect program.
+ * Use to create a `Ref` for shared mutable state inside an Effect program.
  *
  * **Example** (Creating a ref)
  *
@@ -231,7 +231,7 @@ export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => ma
  *
  * **When to use**
  *
- * Use to read the current value without changing it.
+ * Use to read the current `Ref` value without changing it.
  *
  * **Example** (Getting the current value)
  *
@@ -257,7 +257,7 @@ export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
  *
  * **When to use**
  *
- * Use to replace the current value with a known value.
+ * Use to replace the current `Ref` value with a known value.
  *
  * **Example** (Setting a value)
  *
@@ -292,7 +292,7 @@ export const set = dual<
    *
    * **When to use**
    *
-   * Use to replace the current value with a known value.
+   * Use to replace the current `Ref` value with a known value.
    *
    * **Example** (Setting a value)
    *
@@ -327,7 +327,7 @@ export const set = dual<
    *
    * **When to use**
    *
-   * Use to replace the current value with a known value.
+   * Use to replace the current `Ref` value with a known value.
    *
    * **Example** (Setting a value)
    *
@@ -364,7 +364,7 @@ export const set = dual<
  *
  * **When to use**
  *
- * Use to replace the value while returning the previous value.
+ * Use to replace a plain `Ref` value while returning the previous value.
  *
  * **Example** (Replacing a value atomically)
  *
@@ -386,7 +386,7 @@ export const set = dual<
  * @see {@link set} for setting without returning the previous value
  * @see {@link getAndUpdate} for deriving the new value from the previous value
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const getAndSet = dual<
@@ -395,7 +395,7 @@ export const getAndSet = dual<
    *
    * **When to use**
    *
-   * Use to replace the value while returning the previous value.
+   * Use to replace a plain `Ref` value while returning the previous value.
    *
    * **Example** (Replacing a value atomically)
    *
@@ -417,7 +417,7 @@ export const getAndSet = dual<
    * @see {@link set} for setting without returning the previous value
    * @see {@link getAndUpdate} for deriving the new value from the previous value
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
@@ -426,7 +426,7 @@ export const getAndSet = dual<
    *
    * **When to use**
    *
-   * Use to replace the value while returning the previous value.
+   * Use to replace a plain `Ref` value while returning the previous value.
    *
    * **Example** (Replacing a value atomically)
    *
@@ -448,7 +448,7 @@ export const getAndSet = dual<
    * @see {@link set} for setting without returning the previous value
    * @see {@link getAndUpdate} for deriving the new value from the previous value
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<A>
@@ -464,7 +464,7 @@ export const getAndSet = dual<
  *
  * **When to use**
  *
- * Use to derive a new value while returning the previous value.
+ * Use to derive a new `Ref` value while returning the previous value.
  *
  * **Example** (Updating and returning the previous value)
  *
@@ -486,7 +486,7 @@ export const getAndSet = dual<
  * @see {@link update} for updating without returning the previous value
  * @see {@link updateAndGet} for returning the new value instead
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const getAndUpdate = dual<
@@ -495,7 +495,7 @@ export const getAndUpdate = dual<
    *
    * **When to use**
    *
-   * Use to derive a new value while returning the previous value.
+   * Use to derive a new `Ref` value while returning the previous value.
    *
    * **Example** (Updating and returning the previous value)
    *
@@ -517,7 +517,7 @@ export const getAndUpdate = dual<
    * @see {@link update} for updating without returning the previous value
    * @see {@link updateAndGet} for returning the new value instead
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
@@ -526,7 +526,7 @@ export const getAndUpdate = dual<
    *
    * **When to use**
    *
-   * Use to derive a new value while returning the previous value.
+   * Use to derive a new `Ref` value while returning the previous value.
    *
    * **Example** (Updating and returning the previous value)
    *
@@ -548,7 +548,7 @@ export const getAndUpdate = dual<
    * @see {@link update} for updating without returning the previous value
    * @see {@link updateAndGet} for returning the new value instead
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<A>
@@ -564,7 +564,7 @@ export const getAndUpdate = dual<
  *
  * **When to use**
  *
- * Use to return the previous value while applying a conditional update.
+ * Use to return the previous `Ref` value while applying a conditional update.
  *
  * **Details**
  *
@@ -605,7 +605,7 @@ export const getAndUpdate = dual<
  * @see {@link getAndUpdate} for always applying an update
  * @see {@link updateSome} for conditional updates without returning the previous value
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const getAndUpdateSome = dual<
@@ -614,7 +614,7 @@ export const getAndUpdateSome = dual<
    *
    * **When to use**
    *
-   * Use to return the previous value while applying a conditional update.
+   * Use to return the previous `Ref` value while applying a conditional update.
    *
    * **Details**
    *
@@ -655,7 +655,7 @@ export const getAndUpdateSome = dual<
    * @see {@link getAndUpdate} for always applying an update
    * @see {@link updateSome} for conditional updates without returning the previous value
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
@@ -664,7 +664,7 @@ export const getAndUpdateSome = dual<
    *
    * **When to use**
    *
-   * Use to return the previous value while applying a conditional update.
+   * Use to return the previous `Ref` value while applying a conditional update.
    *
    * **Details**
    *
@@ -705,7 +705,7 @@ export const getAndUpdateSome = dual<
    * @see {@link getAndUpdate} for always applying an update
    * @see {@link updateSome} for conditional updates without returning the previous value
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) => Effect.Effect<A>
@@ -724,7 +724,7 @@ export const getAndUpdateSome = dual<
  *
  * **When to use**
  *
- * Use when you want to set a value and immediately get it back in one
+ * Use when you want to set a `Ref` value and immediately get it back in one
  * atomic operation.
  *
  * **Example** (Setting and returning the new value)
@@ -753,7 +753,7 @@ export const getAndUpdateSome = dual<
  * })
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const setAndGet = dual<
@@ -762,7 +762,7 @@ export const setAndGet = dual<
    *
    * **When to use**
    *
-   * Use when you want to set a value and immediately get it back in one
+   * Use when you want to set a `Ref` value and immediately get it back in one
    * atomic operation.
    *
    * **Example** (Setting and returning the new value)
@@ -791,7 +791,7 @@ export const setAndGet = dual<
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
@@ -800,7 +800,7 @@ export const setAndGet = dual<
    *
    * **When to use**
    *
-   * Use when you want to set a value and immediately get it back in one
+   * Use when you want to set a `Ref` value and immediately get it back in one
    * atomic operation.
    *
    * **Example** (Setting and returning the new value)
@@ -829,7 +829,7 @@ export const setAndGet = dual<
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<A>
@@ -840,8 +840,8 @@ export const setAndGet = dual<
  *
  * **When to use**
  *
- * Use to compute both a separate return value and the next stored value in one
- * atomic update.
+ * Use to compute both a separate return value and the next stored `Ref` value
+ * in one atomic update.
  *
  * **Details**
  *
@@ -894,8 +894,8 @@ export const modify = dual<
    *
    * **When to use**
    *
-   * Use to compute both a separate return value and the next stored value in one
-   * atomic update.
+   * Use to compute both a separate return value and the next stored `Ref` value
+   * in one atomic update.
    *
    * **Details**
    *
@@ -948,8 +948,8 @@ export const modify = dual<
    *
    * **When to use**
    *
-   * Use to compute both a separate return value and the next stored value in one
-   * atomic update.
+   * Use to compute both a separate return value and the next stored `Ref` value
+   * in one atomic update.
    *
    * **Details**
    *
@@ -1009,7 +1009,7 @@ export const modify = dual<
  *
  * **When to use**
  *
- * Use to compute a return value while optionally updating the stored value.
+ * Use to compute a return value while optionally updating a plain `Ref`.
  *
  * **Details**
  *
@@ -1068,7 +1068,7 @@ export const modifySome: {
    *
    * **When to use**
    *
-   * Use to compute a return value while optionally updating the stored value.
+   * Use to compute a return value while optionally updating a plain `Ref`.
    *
    * **Details**
    *
@@ -1127,7 +1127,7 @@ export const modifySome: {
    *
    * **When to use**
    *
-   * Use to compute a return value while optionally updating the stored value.
+   * Use to compute a return value while optionally updating a plain `Ref`.
    *
    * **Details**
    *
@@ -1187,7 +1187,7 @@ export const modifySome: {
    *
    * **When to use**
    *
-   * Use to compute a return value while optionally updating the stored value.
+   * Use to compute a return value while optionally updating a plain `Ref`.
    *
    * **Details**
    *
@@ -1246,7 +1246,7 @@ export const modifySome: {
    *
    * **When to use**
    *
-   * Use to compute a return value while optionally updating the stored value.
+   * Use to compute a return value while optionally updating a plain `Ref`.
    *
    * **Details**
    *
@@ -1311,7 +1311,7 @@ export const modifySome: {
  *
  * **When to use**
  *
- * Use to apply a state transition without returning a value.
+ * Use to apply a `Ref` state transition without returning a value.
  *
  * **Example** (Updating a value)
  *
@@ -1349,7 +1349,7 @@ export const update = dual<
    *
    * **When to use**
    *
-   * Use to apply a state transition without returning a value.
+   * Use to apply a `Ref` state transition without returning a value.
    *
    * **Example** (Updating a value)
    *
@@ -1387,7 +1387,7 @@ export const update = dual<
    *
    * **When to use**
    *
-   * Use to apply a state transition without returning a value.
+   * Use to apply a `Ref` state transition without returning a value.
    *
    * **Example** (Updating a value)
    *
@@ -1430,7 +1430,7 @@ export const update = dual<
  *
  * **When to use**
  *
- * Use to apply a state transition and return the new stored value.
+ * Use to apply a `Ref` state transition and return the new stored value.
  *
  * **Example** (Updating and returning the new value)
  *
@@ -1453,7 +1453,7 @@ export const update = dual<
  * @see {@link update} for updating without returning the new value
  * @see {@link getAndUpdate} for returning the previous value instead
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const updateAndGet = dual<
@@ -1462,7 +1462,7 @@ export const updateAndGet = dual<
    *
    * **When to use**
    *
-   * Use to apply a state transition and return the new stored value.
+   * Use to apply a `Ref` state transition and return the new stored value.
    *
    * **Example** (Updating and returning the new value)
    *
@@ -1485,7 +1485,7 @@ export const updateAndGet = dual<
    * @see {@link update} for updating without returning the new value
    * @see {@link getAndUpdate} for returning the previous value instead
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
@@ -1494,7 +1494,7 @@ export const updateAndGet = dual<
    *
    * **When to use**
    *
-   * Use to apply a state transition and return the new stored value.
+   * Use to apply a `Ref` state transition and return the new stored value.
    *
    * **Example** (Updating and returning the new value)
    *
@@ -1517,7 +1517,7 @@ export const updateAndGet = dual<
    * @see {@link update} for updating without returning the new value
    * @see {@link getAndUpdate} for returning the previous value instead
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<A>
@@ -1528,7 +1528,7 @@ export const updateAndGet = dual<
  *
  * **When to use**
  *
- * Use to apply a conditional update without returning a value.
+ * Use to apply a conditional `Ref` update without returning a value.
  *
  * **Details**
  *
@@ -1576,7 +1576,7 @@ export const updateSome = dual<
    *
    * **When to use**
    *
-   * Use to apply a conditional update without returning a value.
+   * Use to apply a conditional `Ref` update without returning a value.
    *
    * **Details**
    *
@@ -1624,7 +1624,7 @@ export const updateSome = dual<
    *
    * **When to use**
    *
-   * Use to apply a conditional update without returning a value.
+   * Use to apply a conditional `Ref` update without returning a value.
    *
    * **Details**
    *
@@ -1680,7 +1680,8 @@ export const updateSome = dual<
  *
  * **When to use**
  *
- * Use to apply a conditional update and return the resulting current value.
+ * Use to apply a conditional `Ref` update and return the resulting current
+ * value.
  *
  * **Details**
  *
@@ -1715,7 +1716,7 @@ export const updateSome = dual<
  * @see {@link updateSome} for conditional updates without returning a value
  * @see {@link updateAndGet} for always updating and returning the new value
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const updateSomeAndGet = dual<
@@ -1724,7 +1725,8 @@ export const updateSomeAndGet = dual<
    *
    * **When to use**
    *
-   * Use to apply a conditional update and return the resulting current value.
+   * Use to apply a conditional `Ref` update and return the resulting current
+   * value.
    *
    * **Details**
    *
@@ -1759,7 +1761,7 @@ export const updateSomeAndGet = dual<
    * @see {@link updateSome} for conditional updates without returning a value
    * @see {@link updateAndGet} for always updating and returning the new value
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
@@ -1768,7 +1770,8 @@ export const updateSomeAndGet = dual<
    *
    * **When to use**
    *
-   * Use to apply a conditional update and return the resulting current value.
+   * Use to apply a conditional `Ref` update and return the resulting current
+   * value.
    *
    * **Details**
    *
@@ -1803,7 +1806,7 @@ export const updateSomeAndGet = dual<
    * @see {@link updateSome} for conditional updates without returning a value
    * @see {@link updateAndGet} for always updating and returning the new value
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) => Effect.Effect<A>

package/src/References.ts

@@ -108,8 +108,8 @@ export {
    *
    * **When to use**
    *
-   * Use to tune scheduler fairness for CPU-bound fibers by changing the
-   * operation budget that triggers a scheduler yield.
+   * Use to configure the runtime reference for the fiber operation budget that
+   * triggers a scheduler yield.
    *
    * **Details**
    *
@@ -780,8 +780,8 @@ export const CurrentLoggers: Context.Reference<ReadonlySet<Logger<unknown, any>>
  *
  * **When to use**
  *
- * Use to keep stdout reserved for protocol messages or data output while still
- * allowing Effect runtime logs to be emitted.
+ * Use to configure the runtime reference that controls whether built-in console
+ * loggers write to stderr.
  *
  * **Details**
  *

package/src/RegExp.ts

@@ -102,7 +102,7 @@ export const isRegExp: (input: unknown) => input is RegExp = predicate.isRegExp
  * assert.deepStrictEqual(RegExp.escape("a*b"), "a\\*b")
  * ```
  *
- * @category utils
+ * @category RegExp
  * @since 2.0.0
  */
 export const escape = (string: string): string => string.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")