effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/MutableRef.d.ts

@@ -4,6 +4,10 @@ declare const TypeId = "~effect/MutableRef";
 /**
  * A synchronous mutable reference that stores a current value.
  *
+ * **When to use**
+ *
+ * Use to keep local mutable state in a stable, pipeable reference.
+ *
  * **Details**
  *
  * Read or write the value directly through `.current`, or use the `MutableRef`
@@ -52,6 +56,10 @@ export interface MutableRef<out T> extends Pipeable, Inspectable {
 /**
  * Creates a new MutableRef with the specified initial value.
  *
+ * **When to use**
+ *
+ * Use to create a synchronous mutable reference initialized with a value.
+ *
  * **Example** (Creating mutable refs)
  *
  * ```ts
@@ -76,10 +84,15 @@ export interface MutableRef<out T> extends Pipeable, Inspectable {
  */
 export declare const make: <T>(value: T) => MutableRef<T>;
 /**
- * Atomically sets the value to newValue if the current value equals oldValue.
+ * Sets the value to newValue atomically if the current value equals oldValue.
  * Returns true if the value was updated, false otherwise.
  * Uses Effect's Equal interface for value comparison.
  *
+ * **When to use**
+ *
+ * Use to replace a value only when the current value still matches an expected
+ * value.
+ *
  * **Example** (Comparing and setting values)
  *
  * ```ts
@@ -114,10 +127,15 @@ export declare const make: <T>(value: T) => MutableRef<T>;
  */
 export declare const compareAndSet: {
     /**
-     * Atomically sets the value to newValue if the current value equals oldValue.
+     * Sets the value to newValue atomically if the current value equals oldValue.
      * Returns true if the value was updated, false otherwise.
      * Uses Effect's Equal interface for value comparison.
      *
+     * **When to use**
+     *
+     * Use to replace a value only when the current value still matches an expected
+     * value.
+     *
      * **Example** (Comparing and setting values)
      *
      * ```ts
@@ -152,10 +170,15 @@ export declare const compareAndSet: {
      */
     <T>(oldValue: T, newValue: T): (self: MutableRef<T>) => boolean;
     /**
-     * Atomically sets the value to newValue if the current value equals oldValue.
+     * Sets the value to newValue atomically if the current value equals oldValue.
      * Returns true if the value was updated, false otherwise.
      * Uses Effect's Equal interface for value comparison.
      *
+     * **When to use**
+     *
+     * Use to replace a value only when the current value still matches an expected
+     * value.
+     *
      * **Example** (Comparing and setting values)
      *
      * ```ts
@@ -193,6 +216,11 @@ export declare const compareAndSet: {
 /**
  * Decrements a numeric MutableRef by 1 and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric reference in place when you want the same
+ * reference back.
+ *
  * **Example** (Decrementing numeric refs)
  *
  * ```ts
@@ -224,6 +252,10 @@ export declare const decrement: (self: MutableRef<number>) => MutableRef<number>
 /**
  * Decrements a numeric MutableRef by 1 and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric reference and immediately read the updated value.
+ *
  * **Example** (Decrementing and reading refs)
  *
  * ```ts
@@ -255,6 +287,10 @@ export declare const decrementAndGet: (self: MutableRef<number>) => number;
 /**
  * Gets the current value of the MutableRef.
  *
+ * **When to use**
+ *
+ * Use to read the current value without mutating the reference.
+ *
  * **Example** (Reading current values)
  *
  * ```ts
@@ -284,6 +320,10 @@ export declare const get: <T>(self: MutableRef<T>) => T;
 /**
  * Decrements a numeric MutableRef by 1 and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to read the current numeric value before decrementing it.
+ *
  * **Example** (Reading before decrementing)
  *
  * ```ts
@@ -316,6 +356,10 @@ export declare const getAndDecrement: (self: MutableRef<number>) => number;
 /**
  * Increments a numeric MutableRef by 1 and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to read the current numeric value before incrementing it.
+ *
  * **Example** (Reading before incrementing)
  *
  * ```ts
@@ -356,6 +400,10 @@ export declare const getAndIncrement: (self: MutableRef<number>) => number;
 /**
  * Sets the MutableRef to a new value and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value while keeping the previous value.
+ *
  * **Example** (Reading before setting)
  *
  * ```ts
@@ -392,6 +440,10 @@ export declare const getAndSet: {
     /**
      * Sets the MutableRef to a new value and returns the previous value.
      *
+     * **When to use**
+     *
+     * Use to replace the current value while keeping the previous value.
+     *
      * **Example** (Reading before setting)
      *
      * ```ts
@@ -428,6 +480,10 @@ export declare const getAndSet: {
     /**
      * Sets the MutableRef to a new value and returns the previous value.
      *
+     * **When to use**
+     *
+     * Use to replace the current value while keeping the previous value.
+     *
      * **Example** (Reading before setting)
      *
      * ```ts
@@ -466,6 +522,10 @@ export declare const getAndSet: {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to transform the current value while keeping the previous value.
+ *
  * **Example** (Reading before updating)
  *
  * ```ts
@@ -509,6 +569,10 @@ export declare const getAndUpdate: {
      * Updates the MutableRef with the result of applying a function to its current value,
      * and returns the previous value.
      *
+     * **When to use**
+     *
+     * Use to transform the current value while keeping the previous value.
+     *
      * **Example** (Reading before updating)
      *
      * ```ts
@@ -552,6 +616,10 @@ export declare const getAndUpdate: {
      * Updates the MutableRef with the result of applying a function to its current value,
      * and returns the previous value.
      *
+     * **When to use**
+     *
+     * Use to transform the current value while keeping the previous value.
+     *
      * **Example** (Reading before updating)
      *
      * ```ts
@@ -595,6 +663,11 @@ export declare const getAndUpdate: {
 /**
  * Increments a numeric MutableRef by 1 and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to increment a numeric reference in place when you want the same
+ * reference back.
+ *
  * **Example** (Incrementing numeric refs)
  *
  * ```ts
@@ -629,6 +702,10 @@ export declare const increment: (self: MutableRef<number>) => MutableRef<number>
 /**
  * Increments a numeric MutableRef by 1 and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to increment a numeric reference and immediately read the updated value.
+ *
  * **Example** (Incrementing and reading refs)
  *
  * ```ts
@@ -664,6 +741,11 @@ export declare const incrementAndGet: (self: MutableRef<number>) => number;
 /**
  * Sets the MutableRef to a new value and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to replace the current value in place when you want the same reference
+ * back.
+ *
  * **Example** (Setting values)
  *
  * ```ts
@@ -704,6 +786,11 @@ export declare const set: {
     /**
      * Sets the MutableRef to a new value and returns the reference.
      *
+     * **When to use**
+     *
+     * Use to replace the current value in place when you want the same reference
+     * back.
+     *
      * **Example** (Setting values)
      *
      * ```ts
@@ -744,6 +831,11 @@ export declare const set: {
     /**
      * Sets the MutableRef to a new value and returns the reference.
      *
+     * **When to use**
+     *
+     * Use to replace the current value in place when you want the same reference
+     * back.
+     *
      * **Example** (Setting values)
      *
      * ```ts
@@ -785,6 +877,10 @@ export declare const set: {
 /**
  * Sets the MutableRef to a new value and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value and immediately read the replacement.
+ *
  * **Example** (Setting and reading values)
  *
  * ```ts
@@ -821,6 +917,10 @@ export declare const setAndGet: {
     /**
      * Sets the MutableRef to a new value and returns the new value.
      *
+     * **When to use**
+     *
+     * Use to replace the current value and immediately read the replacement.
+     *
      * **Example** (Setting and reading values)
      *
      * ```ts
@@ -857,6 +957,10 @@ export declare const setAndGet: {
     /**
      * Sets the MutableRef to a new value and returns the new value.
      *
+     * **When to use**
+     *
+     * Use to replace the current value and immediately read the replacement.
+     *
      * **Example** (Setting and reading values)
      *
      * ```ts
@@ -895,6 +999,11 @@ export declare const setAndGet: {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to transform the current value in place when you want the same reference
+ * back.
+ *
  * **Example** (Updating values)
  *
  * ```ts
@@ -940,6 +1049,11 @@ export declare const update: {
      * Updates the MutableRef with the result of applying a function to its current value,
      * and returns the reference.
      *
+     * **When to use**
+     *
+     * Use to transform the current value in place when you want the same reference
+     * back.
+     *
      * **Example** (Updating values)
      *
      * ```ts
@@ -985,6 +1099,11 @@ export declare const update: {
      * Updates the MutableRef with the result of applying a function to its current value,
      * and returns the reference.
      *
+     * **When to use**
+     *
+     * Use to transform the current value in place when you want the same reference
+     * back.
+     *
      * **Example** (Updating values)
      *
      * ```ts
@@ -1031,6 +1150,10 @@ export declare const update: {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to transform the current value and immediately read the updated value.
+ *
  * **Example** (Updating and reading values)
  *
  * ```ts
@@ -1078,6 +1201,10 @@ export declare const updateAndGet: {
      * Updates the MutableRef with the result of applying a function to its current value,
      * and returns the new value.
      *
+     * **When to use**
+     *
+     * Use to transform the current value and immediately read the updated value.
+     *
      * **Example** (Updating and reading values)
      *
      * ```ts
@@ -1125,6 +1252,10 @@ export declare const updateAndGet: {
      * Updates the MutableRef with the result of applying a function to its current value,
      * and returns the new value.
      *
+     * **When to use**
+     *
+     * Use to transform the current value and immediately read the updated value.
+     *
      * **Example** (Updating and reading values)
      *
      * ```ts
@@ -1170,7 +1301,13 @@ export declare const updateAndGet: {
     <T>(self: MutableRef<T>, f: (value: T) => T): T;
 };
 /**
- * Toggles a boolean MutableRef (true becomes false, false becomes true) and returns the reference.
+ * Switches a boolean `MutableRef` between `true` and `false`, then returns the
+ * reference.
+ *
+ * **When to use**
+ *
+ * Use to flip a boolean reference in place when you want the same reference
+ * back.
  *
  * **Example** (Toggling boolean refs)
  *

package/dist/MutableRef.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MutableRef.d.ts","sourceRoot":"","sources":["../src/MutableRef.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MutableRef.d.ts","sourceRoot":"","sources":["../src/MutableRef.ts"],"names":[],"mappings":"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"}

package/dist/MutableRef.js

@@ -50,6 +50,10 @@ const MutableRefProto = {
 /**
  * Creates a new MutableRef with the specified initial value.
  *
+ * **When to use**
+ *
+ * Use to create a synchronous mutable reference initialized with a value.
+ *
  * **Example** (Creating mutable refs)
  *
  * ```ts
@@ -78,10 +82,15 @@ export const make = value => {
   return ref;
 };
 /**
- * Atomically sets the value to newValue if the current value equals oldValue.
+ * Sets the value to newValue atomically if the current value equals oldValue.
  * Returns true if the value was updated, false otherwise.
  * Uses Effect's Equal interface for value comparison.
  *
+ * **When to use**
+ *
+ * Use to replace a value only when the current value still matches an expected
+ * value.
+ *
  * **Example** (Comparing and setting values)
  *
  * ```ts
@@ -124,6 +133,11 @@ export const compareAndSet = /*#__PURE__*/Dual.dual(3, (self, oldValue, newValue
 /**
  * Decrements a numeric MutableRef by 1 and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric reference in place when you want the same
+ * reference back.
+ *
  * **Example** (Decrementing numeric refs)
  *
  * ```ts
@@ -155,6 +169,10 @@ export const decrement = self => update(self, n => n - 1);
 /**
  * Decrements a numeric MutableRef by 1 and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to decrement a numeric reference and immediately read the updated value.
+ *
  * **Example** (Decrementing and reading refs)
  *
  * ```ts
@@ -186,6 +204,10 @@ export const decrementAndGet = self => updateAndGet(self, n => n - 1);
 /**
  * Gets the current value of the MutableRef.
  *
+ * **When to use**
+ *
+ * Use to read the current value without mutating the reference.
+ *
  * **Example** (Reading current values)
  *
  * ```ts
@@ -215,6 +237,10 @@ export const get = self => self.current;
 /**
  * Decrements a numeric MutableRef by 1 and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to read the current numeric value before decrementing it.
+ *
  * **Example** (Reading before decrementing)
  *
  * ```ts
@@ -247,6 +273,10 @@ export const getAndDecrement = self => getAndUpdate(self, n => n - 1);
 /**
  * Increments a numeric MutableRef by 1 and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to read the current numeric value before incrementing it.
+ *
  * **Example** (Reading before incrementing)
  *
  * ```ts
@@ -287,6 +317,10 @@ export const getAndIncrement = self => getAndUpdate(self, n => n + 1);
 /**
  * Sets the MutableRef to a new value and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value while keeping the previous value.
+ *
  * **Example** (Reading before setting)
  *
  * ```ts
@@ -328,6 +362,10 @@ export const getAndSet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to transform the current value while keeping the previous value.
+ *
  * **Example** (Reading before updating)
  *
  * ```ts
@@ -370,6 +408,11 @@ export const getAndUpdate = /*#__PURE__*/Dual.dual(2, (self, f) => getAndSet(sel
 /**
  * Increments a numeric MutableRef by 1 and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to increment a numeric reference in place when you want the same
+ * reference back.
+ *
  * **Example** (Incrementing numeric refs)
  *
  * ```ts
@@ -404,6 +447,10 @@ export const increment = self => update(self, n => n + 1);
 /**
  * Increments a numeric MutableRef by 1 and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to increment a numeric reference and immediately read the updated value.
+ *
  * **Example** (Incrementing and reading refs)
  *
  * ```ts
@@ -439,6 +486,11 @@ export const incrementAndGet = self => updateAndGet(self, n => n + 1);
 /**
  * Sets the MutableRef to a new value and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to replace the current value in place when you want the same reference
+ * back.
+ *
  * **Example** (Setting values)
  *
  * ```ts
@@ -482,6 +534,10 @@ export const set = /*#__PURE__*/Dual.dual(2, (self, value) => {
 /**
  * Sets the MutableRef to a new value and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value and immediately read the replacement.
+ *
  * **Example** (Setting and reading values)
  *
  * ```ts
@@ -522,6 +578,11 @@ export const setAndGet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the reference.
  *
+ * **When to use**
+ *
+ * Use to transform the current value in place when you want the same reference
+ * back.
+ *
  * **Example** (Updating values)
  *
  * ```ts
@@ -567,6 +628,10 @@ export const update = /*#__PURE__*/Dual.dual(2, (self, f) => set(self, f(get(sel
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to transform the current value and immediately read the updated value.
+ *
  * **Example** (Updating and reading values)
  *
  * ```ts
@@ -611,7 +676,13 @@ export const update = /*#__PURE__*/Dual.dual(2, (self, f) => set(self, f(get(sel
  */
 export const updateAndGet = /*#__PURE__*/Dual.dual(2, (self, f) => setAndGet(self, f(get(self))));
 /**
- * Toggles a boolean MutableRef (true becomes false, false becomes true) and returns the reference.
+ * Switches a boolean `MutableRef` between `true` and `false`, then returns the
+ * reference.
+ *
+ * **When to use**
+ *
+ * Use to flip a boolean reference in place when you want the same reference
+ * back.
  *
  * **Example** (Toggling boolean refs)
  *

package/dist/MutableRef.js.map

@@ -1 +1 @@
-{"version":3,"file":"MutableRef.js","names":["Equal","Dual","toJson","PipeInspectableProto","TypeId","MutableRefProto","toJSON","_id","current","make","value","ref","Object","create","compareAndSet","dual","self","oldValue","newValue","equals","decrement","update","n","decrementAndGet","updateAndGet","get","getAndDecrement","getAndUpdate","getAndIncrement","getAndSet","ret","f","increment","incrementAndGet","set","setAndGet","toggle","_"],"sources":["../src/MutableRef.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"MutableRef.js","names":["Equal","Dual","toJson","PipeInspectableProto","TypeId","MutableRefProto","toJSON","_id","current","make","value","ref","Object","create","compareAndSet","dual","self","oldValue","newValue","equals","decrement","update","n","decrementAndGet","updateAndGet","get","getAndDecrement","getAndUpdate","getAndIncrement","getAndSet","ret","f","increment","incrementAndGet","set","setAndGet","toggle","_"],"sources":["../src/MutableRef.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/Newtype.d.ts

@@ -75,9 +75,9 @@ declare const TypeId = "~effect/Newtype";
  *
  * **When to use**
  *
- * Define your newtype as an `interface` extending
- * `Newtype<"MyKey", CarrierType>` when you need two structurally identical
- * carrier types to remain distinct in TypeScript.
+ * Use to define a newtype as an `interface` extending
+ * `Newtype<"MyKey", CarrierType>` when structurally identical carrier types
+ * should remain distinct in TypeScript.
  *
  * **Details**
  *
@@ -112,6 +112,11 @@ export interface Newtype<in out Key extends string, out Carrier> {
  * Namespace containing type-level helpers for `Newtype` values, including
  * constraints and utilities for extracting a newtype's key and carrier type.
  *
+ * **When to use**
+ *
+ * Use to access generic constraints and type-level utilities for `Newtype`
+ * values.
+ *
  * @since 4.0.0
  */
 export declare namespace Newtype {
@@ -119,6 +124,10 @@ export declare namespace Newtype {
      * A type that matches any `Newtype`, useful as a generic constraint:
      * `<N extends Newtype.Any>`.
      *
+     * **When to use**
+     *
+     * Use as a generic constraint when a type parameter can be any `Newtype`.
+     *
      * @see {@link Newtype} — the base tagged interface
      *
      * @category utility types
@@ -130,7 +139,7 @@ export declare namespace Newtype {
      *
      * **When to use**
      *
-     * Use this in generic code that needs to inspect or constrain the key.
+     * Use to inspect or constrain a newtype's key in generic code.
      *
      * @category utility types
      * @since 4.0.0
@@ -141,7 +150,7 @@ export declare namespace Newtype {
      *
      * **When to use**
      *
-     * Use this when you need to refer to the wrapped type in generic utilities.
+     * Use when you need to refer to the wrapped type in generic utilities.
      *
      * @category utility types
      * @since 4.0.0
@@ -153,7 +162,7 @@ export declare namespace Newtype {
  *
  * **When to use**
  *
- * Use this when you only need to read the inner value and do not need to wrap
+ * Use when you only need to read the inner value and do not need to wrap
  * new values. For both wrapping and unwrapping, prefer {@link makeIso}.
  *
  * **Details**
@@ -185,7 +194,7 @@ export declare const value: <N extends Newtype.Any>(newtype: N) => Newtype.Carri
  *
  * **When to use**
  *
- * Use this as the primary way to construct and deconstruct newtype values.
+ * Use as the primary way to construct and deconstruct newtype values.
  *
  * **Details**
  *
@@ -217,7 +226,7 @@ export declare function makeIso<N extends Newtype.Any>(): Optic.Iso<N, Newtype.C
  *
  * **When to use**
  *
- * Use this when you need to compare two newtype values for equality.
+ * Use when you need to compare two newtype values for equality.
  *
  * **Details**
  *
@@ -249,7 +258,7 @@ export declare const makeEquivalence: <N extends Newtype.Any>(equivalence: Equiv
  *
  * **When to use**
  *
- * Use this when you need to sort or compare newtype values.
+ * Use when you need to sort or compare newtype values.
  *
  * **Details**
  *
@@ -279,7 +288,7 @@ export declare const makeOrder: <N extends Newtype.Any>(order: Order.Order<Newty
  *
  * **When to use**
  *
- * Use this when you need to combine newtype values.
+ * Use when you need to combine newtype values.
  *
  * **Details**
  *
@@ -311,7 +320,7 @@ export declare const makeCombiner: <N extends Newtype.Any>(combiner: Combiner.Co
  *
  * **When to use**
  *
- * Use this when you need to fold or reduce over a collection of newtype
+ * Use when you need to fold or reduce over a collection of newtype
  * values.
  *
  * **Details**