effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/SynchronizedRef.ts

@@ -69,7 +69,8 @@ const Proto = {
  *
  * **When to use**
  *
- * Use when synchronous construction is required outside an Effect workflow.
+ * Use when you need synchronous `SynchronizedRef` construction outside an
+ * Effect workflow.
  *
  * @category constructors
  * @since 4.0.0
@@ -86,8 +87,8 @@ export const makeUnsafe = <A>(value: A): SynchronizedRef<A> => {
  *
  * **When to use**
  *
- * Use to create a synchronized reference inside an Effect program when later
- * updates may run effects and must be serialized.
+ * Use to create a `SynchronizedRef` inside an Effect program when later updates
+ * may run effects and must be serialized.
  *
  * **Details**
  *
@@ -196,7 +197,8 @@ export const getAndSet: {
  *
  * **When to use**
  *
- * Use to run a pure state update when the previous stored value is also needed.
+ * Use to run a pure `SynchronizedRef` state update when the previous stored
+ * value is also needed.
  *
  * @see {@link update} for updating without returning a value
  * @see {@link updateAndGet} for updating and returning the new value
@@ -212,7 +214,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to run a pure state update when the previous stored value is also needed.
+   * Use to run a pure `SynchronizedRef` state update when the previous stored
+   * value is also needed.
    *
    * @see {@link update} for updating without returning a value
    * @see {@link updateAndGet} for updating and returning the new value
@@ -228,7 +231,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to run a pure state update when the previous stored value is also needed.
+   * Use to run a pure `SynchronizedRef` state update when the previous stored
+   * value is also needed.
    *
    * @see {@link update} for updating without returning a value
    * @see {@link updateAndGet} for updating and returning the new value
@@ -250,7 +254,8 @@ export const getAndUpdate: {
  *
  * **When to use**
  *
- * Use when an effectful state transition must return the previous stored value.
+ * Use when you need an effectful `SynchronizedRef` state transition to return
+ * the previous stored value.
  *
  * @see {@link getAndUpdate} for pure updates that return the previous value
  * @see {@link updateEffect} for effectful updates without returning a value
@@ -268,7 +273,8 @@ export const getAndUpdateEffect: {
    *
    * **When to use**
    *
-   * Use when an effectful state transition must return the previous stored value.
+   * Use when you need an effectful `SynchronizedRef` state transition to return
+   * the previous stored value.
    *
    * @see {@link getAndUpdate} for pure updates that return the previous value
    * @see {@link updateEffect} for effectful updates without returning a value
@@ -286,7 +292,8 @@ export const getAndUpdateEffect: {
    *
    * **When to use**
    *
-   * Use when an effectful state transition must return the previous stored value.
+   * Use when you need an effectful `SynchronizedRef` state transition to return
+   * the previous stored value.
    *
    * @see {@link getAndUpdate} for pure updates that return the previous value
    * @see {@link updateEffect} for effectful updates without returning a value
@@ -317,7 +324,8 @@ export const getAndUpdateEffect: {
  *
  * **When to use**
  *
- * Use to return the previous value while applying a pure conditional update.
+ * Use to return the previous `SynchronizedRef` value while applying a pure
+ * conditional update.
  *
  * @see {@link getAndUpdate} for always applying a pure update
  * @see {@link updateSome} for applying a pure conditional update without returning the previous value
@@ -333,7 +341,8 @@ export const getAndUpdateSome: {
    *
    * **When to use**
    *
-   * Use to return the previous value while applying a pure conditional update.
+   * Use to return the previous `SynchronizedRef` value while applying a pure
+   * conditional update.
    *
    * @see {@link getAndUpdate} for always applying a pure update
    * @see {@link updateSome} for applying a pure conditional update without returning the previous value
@@ -349,7 +358,8 @@ export const getAndUpdateSome: {
    *
    * **When to use**
    *
-   * Use to return the previous value while applying a pure conditional update.
+   * Use to return the previous `SynchronizedRef` value while applying a pure
+   * conditional update.
    *
    * @see {@link getAndUpdate} for always applying a pure update
    * @see {@link updateSome} for applying a pure conditional update without returning the previous value
@@ -371,8 +381,8 @@ export const getAndUpdateSome: {
  *
  * **When to use**
  *
- * Use to return the previous value while running an effectful conditional
- * update.
+ * Use to return the previous `SynchronizedRef` value while running an effectful
+ * conditional update.
  *
  * @see {@link getAndUpdateSome} for the pure conditional variant
  * @see {@link updateSomeEffect} for effectful conditional updates without returning the previous value
@@ -388,8 +398,8 @@ export const getAndUpdateSomeEffect: {
    *
    * **When to use**
    *
-   * Use to return the previous value while running an effectful conditional
-   * update.
+   * Use to return the previous `SynchronizedRef` value while running an effectful
+   * conditional update.
    *
    * @see {@link getAndUpdateSome} for the pure conditional variant
    * @see {@link updateSomeEffect} for effectful conditional updates without returning the previous value
@@ -405,8 +415,8 @@ export const getAndUpdateSomeEffect: {
    *
    * **When to use**
    *
-   * Use to return the previous value while running an effectful conditional
-   * update.
+   * Use to return the previous `SynchronizedRef` value while running an effectful
+   * conditional update.
    *
    * @see {@link getAndUpdateSome} for the pure conditional variant
    * @see {@link updateSomeEffect} for effectful conditional updates without returning the previous value
@@ -439,8 +449,8 @@ export const getAndUpdateSomeEffect: {
  *
  * **When to use**
  *
- * Use to derive a separate result and the next stored value from the same
- * current value in one serialized pure update.
+ * Use to derive a separate result and the next stored `SynchronizedRef` value
+ * from the same current value in one serialized pure update.
  *
  * @see {@link modifyEffect} for effectfully deriving both the result and next stored value
  * @see {@link modifySome} for deriving a result and optionally updating the stored value
@@ -456,8 +466,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to derive a separate result and the next stored value from the same
-   * current value in one serialized pure update.
+   * Use to derive a separate result and the next stored `SynchronizedRef` value
+   * from the same current value in one serialized pure update.
    *
    * @see {@link modifyEffect} for effectfully deriving both the result and next stored value
    * @see {@link modifySome} for deriving a result and optionally updating the stored value
@@ -473,8 +483,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to derive a separate result and the next stored value from the same
-   * current value in one serialized pure update.
+   * Use to derive a separate result and the next stored `SynchronizedRef` value
+   * from the same current value in one serialized pure update.
    *
    * @see {@link modifyEffect} for effectfully deriving both the result and next stored value
    * @see {@link modifySome} for deriving a result and optionally updating the stored value
@@ -497,7 +507,7 @@ export const modify: {
  * **When to use**
  *
  * Use to effectfully compute both a separate return value and the next stored
- * value in one serialized update.
+ * `SynchronizedRef` value in one serialized update.
  *
  * @see {@link modify} for the pure variant
  * @see {@link updateEffect} for effectfully storing a new value without a separate result
@@ -513,7 +523,7 @@ export const modifyEffect: {
    * **When to use**
    *
    * Use to effectfully compute both a separate return value and the next stored
-   * value in one serialized update.
+   * `SynchronizedRef` value in one serialized update.
    *
    * @see {@link modify} for the pure variant
    * @see {@link updateEffect} for effectfully storing a new value without a separate result
@@ -529,7 +539,7 @@ export const modifyEffect: {
    * **When to use**
    *
    * Use to effectfully compute both a separate return value and the next stored
-   * value in one serialized update.
+   * `SynchronizedRef` value in one serialized update.
    *
    * @see {@link modify} for the pure variant
    * @see {@link updateEffect} for effectfully storing a new value without a separate result
@@ -559,7 +569,8 @@ export const modifyEffect: {
  *
  * **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 `SynchronizedRef`
+ * under its semaphore.
  *
  * @see {@link modify} for always storing a new value
  * @see {@link updateSome} for optional updates without a separate return value
@@ -574,7 +585,8 @@ 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 `SynchronizedRef`
+   * under its semaphore.
    *
    * @see {@link modify} for always storing a new value
    * @see {@link updateSome} for optional updates without a separate return value
@@ -589,7 +601,8 @@ 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 `SynchronizedRef`
+   * under its semaphore.
    *
    * @see {@link modify} for always storing a new value
    * @see {@link updateSome} for optional updates without a separate return value
@@ -614,7 +627,7 @@ export const modifySome: {
  * **When to use**
  *
  * Use to effectfully compute a return value while optionally updating the
- * stored value.
+ * stored `SynchronizedRef` value.
  *
  * @see {@link modifySome} for the pure variant
  * @see {@link updateSomeEffect} for effectful optional updates without a separate return value
@@ -631,7 +644,7 @@ export const modifySomeEffect: {
    * **When to use**
    *
    * Use to effectfully compute a return value while optionally updating the
-   * stored value.
+   * stored `SynchronizedRef` value.
    *
    * @see {@link modifySome} for the pure variant
    * @see {@link updateSomeEffect} for effectful optional updates without a separate return value
@@ -651,7 +664,7 @@ export const modifySomeEffect: {
    * **When to use**
    *
    * Use to effectfully compute a return value while optionally updating the
-   * stored value.
+   * stored `SynchronizedRef` value.
    *
    * @see {@link modifySome} for the pure variant
    * @see {@link updateSomeEffect} for effectful optional updates without a separate return value
@@ -740,8 +753,8 @@ export const set: {
  *
  * **When to use**
  *
- * Use to replace the current value with a known value and return that new
- * value.
+ * Use to replace the current `SynchronizedRef` value with a known value and
+ * return that new value.
  *
  * @see {@link set} for setting without returning a value
  * @see {@link getAndSet} for setting while returning the previous value
@@ -755,8 +768,8 @@ export const setAndGet: {
    *
    * **When to use**
    *
-   * Use to replace the current value with a known value and return that new
-   * value.
+   * Use to replace the current `SynchronizedRef` value with a known value and
+   * return that new value.
    *
    * @see {@link set} for setting without returning a value
    * @see {@link getAndSet} for setting while returning the previous value
@@ -770,8 +783,8 @@ export const setAndGet: {
    *
    * **When to use**
    *
-   * Use to replace the current value with a known value and return that new
-   * value.
+   * Use to replace the current `SynchronizedRef` value with a known value and
+   * return that new value.
    *
    * @see {@link set} for setting without returning a value
    * @see {@link getAndSet} for setting while returning the previous value
@@ -917,7 +930,8 @@ export const updateEffect: {
  *
  * **When to use**
  *
- * Use to apply a pure state transition and return the new stored value.
+ * Use to apply a pure `SynchronizedRef` state transition and return the new
+ * stored value.
  *
  * @see {@link update} for updating without returning the new value
  * @see {@link getAndUpdate} for updating while returning the previous value
@@ -932,7 +946,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to apply a pure state transition and return the new stored value.
+   * Use to apply a pure `SynchronizedRef` state transition and return the new
+   * stored value.
    *
    * @see {@link update} for updating without returning the new value
    * @see {@link getAndUpdate} for updating while returning the previous value
@@ -947,7 +962,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to apply a pure state transition and return the new stored value.
+   * Use to apply a pure `SynchronizedRef` state transition and return the new
+   * stored value.
    *
    * @see {@link update} for updating without returning the new value
    * @see {@link getAndUpdate} for updating while returning the previous value
@@ -968,7 +984,8 @@ export const updateAndGet: {
  *
  * **When to use**
  *
- * Use to run an effectful state transition and return the new stored value.
+ * Use to run an effectful `SynchronizedRef` state transition and return the new
+ * stored value.
  *
  * @see {@link updateEffect} for effectful updates without returning the new value
  * @see {@link updateAndGet} for the pure variant
@@ -983,7 +1000,8 @@ export const updateAndGetEffect: {
    *
    * **When to use**
    *
-   * Use to run an effectful state transition and return the new stored value.
+   * Use to run an effectful `SynchronizedRef` state transition and return the new
+   * stored value.
    *
    * @see {@link updateEffect} for effectful updates without returning the new value
    * @see {@link updateAndGet} for the pure variant
@@ -998,7 +1016,8 @@ export const updateAndGetEffect: {
    *
    * **When to use**
    *
-   * Use to run an effectful state transition and return the new stored value.
+   * Use to run an effectful `SynchronizedRef` state transition and return the new
+   * stored value.
    *
    * @see {@link updateEffect} for effectful updates without returning the new value
    * @see {@link updateAndGet} for the pure variant
@@ -1025,7 +1044,8 @@ export const updateAndGetEffect: {
  *
  * **When to use**
  *
- * Use to apply a pure conditional update without returning a value.
+ * Use to apply a pure conditional `SynchronizedRef` update without returning a
+ * value.
  *
  * @see {@link update} for always applying a pure update
  * @see {@link updateSomeAndGet} for returning the resulting current value
@@ -1040,7 +1060,8 @@ export const updateSome: {
    *
    * **When to use**
    *
-   * Use to apply a pure conditional update without returning a value.
+   * Use to apply a pure conditional `SynchronizedRef` update without returning a
+   * value.
    *
    * @see {@link update} for always applying a pure update
    * @see {@link updateSomeAndGet} for returning the resulting current value
@@ -1055,7 +1076,8 @@ export const updateSome: {
    *
    * **When to use**
    *
-   * Use to apply a pure conditional update without returning a value.
+   * Use to apply a pure conditional `SynchronizedRef` update without returning a
+   * value.
    *
    * @see {@link update} for always applying a pure update
    * @see {@link updateSomeAndGet} for returning the resulting current value
@@ -1076,7 +1098,8 @@ export const updateSome: {
  *
  * **When to use**
  *
- * Use to run an effectful conditional update without returning a value.
+ * Use to run an effectful conditional `SynchronizedRef` update without
+ * returning a value.
  *
  * @see {@link updateSome} for the pure conditional variant
  * @see {@link updateEffect} for effectful updates that always store a new value
@@ -1091,7 +1114,8 @@ export const updateSomeEffect: {
    *
    * **When to use**
    *
-   * Use to run an effectful conditional update without returning a value.
+   * Use to run an effectful conditional `SynchronizedRef` update without
+   * returning a value.
    *
    * @see {@link updateSome} for the pure conditional variant
    * @see {@link updateEffect} for effectful updates that always store a new value
@@ -1106,7 +1130,8 @@ export const updateSomeEffect: {
    *
    * **When to use**
    *
-   * Use to run an effectful conditional update without returning a value.
+   * Use to run an effectful conditional `SynchronizedRef` update without
+   * returning a value.
    *
    * @see {@link updateSome} for the pure conditional variant
    * @see {@link updateEffect} for effectful updates that always store a new value
@@ -1139,8 +1164,8 @@ export const updateSomeEffect: {
  *
  * **When to use**
  *
- * Use to apply a pure conditional update and return the resulting current
- * value.
+ * Use to apply a pure conditional `SynchronizedRef` update and return the
+ * resulting current value.
  *
  * @see {@link updateSome} for conditional updates without returning a value
  * @see {@link updateAndGet} for always applying a pure update and returning the new value
@@ -1156,8 +1181,8 @@ export const updateSomeAndGet: {
    *
    * **When to use**
    *
-   * Use to apply a pure conditional update and return the resulting current
-   * value.
+   * Use to apply a pure conditional `SynchronizedRef` update and return the
+   * resulting current value.
    *
    * @see {@link updateSome} for conditional updates without returning a value
    * @see {@link updateAndGet} for always applying a pure update and returning the new value
@@ -1173,8 +1198,8 @@ export const updateSomeAndGet: {
    *
    * **When to use**
    *
-   * Use to apply a pure conditional update and return the resulting current
-   * value.
+   * Use to apply a pure conditional `SynchronizedRef` update and return the
+   * resulting current value.
    *
    * @see {@link updateSome} for conditional updates without returning a value
    * @see {@link updateAndGet} for always applying a pure update and returning the new value
@@ -1196,8 +1221,8 @@ export const updateSomeAndGet: {
  *
  * **When to use**
  *
- * Use to run an effectful conditional update and return the resulting current
- * value.
+ * Use to run an effectful conditional `SynchronizedRef` update and return the
+ * resulting current value.
  *
  * @see {@link updateSomeEffect} for effectful conditional updates without returning a value
  * @see {@link updateAndGetEffect} for effectful updates that always store and return a new value
@@ -1213,8 +1238,8 @@ export const updateSomeAndGetEffect: {
    *
    * **When to use**
    *
-   * Use to run an effectful conditional update and return the resulting current
-   * value.
+   * Use to run an effectful conditional `SynchronizedRef` update and return the
+   * resulting current value.
    *
    * @see {@link updateSomeEffect} for effectful conditional updates without returning a value
    * @see {@link updateAndGetEffect} for effectful updates that always store and return a new value
@@ -1230,8 +1255,8 @@ export const updateSomeAndGetEffect: {
    *
    * **When to use**
    *
-   * Use to run an effectful conditional update and return the resulting current
-   * value.
+   * Use to run an effectful conditional `SynchronizedRef` update and return the
+   * resulting current value.
    *
    * @see {@link updateSomeEffect} for effectful conditional updates without returning a value
    * @see {@link updateAndGetEffect} for effectful updates that always store and return a new value

package/src/Tracer.ts

@@ -159,8 +159,8 @@ export type AnySpan = Span | ExternalSpan
  *
  * **When to use**
  *
- * Use when integrating lower-level tracing code that needs the raw context key
- * for parent span lookup.
+ * Use when you need the raw context key for parent span lookup in lower-level
+ * tracing code.
  *
  * **Example** (Reading the parent span key)
  *
@@ -579,8 +579,8 @@ export const MinimumTraceLevel = Context.Reference<
  *
  * **When to use**
  *
- * Use when integrating lower-level tracing code that needs the raw context key
- * for active tracer lookup.
+ * Use when you need the raw context key for active tracer lookup in lower-level
+ * tracing code.
  *
  * @category references
  * @since 4.0.0

package/src/Trie.ts

@@ -1024,6 +1024,11 @@ export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
 /**
  * Looks up the value for the specified key in the `Trie` unsafely.
  *
+ * **When to use**
+ *
+ * Use when the trie key is known to exist and a missing key should be treated
+ * as a programming error.
+ *
  * **Gotchas**
  *
  * `getUnsafe` throws if the key is not found. Use `get` instead to safely get
@@ -1050,6 +1055,11 @@ export const getUnsafe: {
   /**
    * Looks up the value for the specified key in the `Trie` unsafely.
    *
+   * **When to use**
+   *
+   * Use when the trie key is known to exist and a missing key should be treated
+   * as a programming error.
+   *
    * **Gotchas**
    *
    * `getUnsafe` throws if the key is not found. Use `get` instead to safely get
@@ -1076,6 +1086,11 @@ export const getUnsafe: {
   /**
    * Looks up the value for the specified key in the `Trie` unsafely.
    *
+   * **When to use**
+   *
+   * Use when the trie key is known to exist and a missing key should be treated
+   * as a programming error.
+   *
    * **Gotchas**
    *
    * `getUnsafe` throws if the key is not found. Use `get` instead to safely get

package/src/Tuple.ts

@@ -80,8 +80,8 @@ import type { Apply, Lambda } from "./Struct.ts"
  *
  * **When to use**
  *
- * Use when you use this instead of `[a, b, c] as const` when you want a properly typed tuple
- * without a manual cast.
+ * Use when you need a properly typed tuple without writing `[a, b, c] as const`
+ * or another manual cast.
  *
  * **Details**
  *
@@ -111,7 +111,7 @@ type Indices<T extends ReadonlyArray<unknown>> = Exclude<Partial<T>["length"], T
  *
  * **When to use**
  *
- * Use when you use this in a pipeline when you need to extract a single element.
+ * Use when a single tuple element should be extracted in a pipeline.
  *
  * **Details**
  *
@@ -137,7 +137,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use when you use this in a pipeline when you need to extract a single element.
+   * Use when a single tuple element should be extracted in a pipeline.
    *
    * **Details**
    *
@@ -163,7 +163,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use when you use this in a pipeline when you need to extract a single element.
+   * Use when a single tuple element should be extracted in a pipeline.
    *
    * **Details**
    *
@@ -383,7 +383,8 @@ export const omit: {
  *
  * **When to use**
  *
- * Use to add one element to the end of a tuple while preserving tuple types.
+ * Use when you need the appended value to remain part of the tuple's type-level
+ * shape and preserve literal element positions.
  *
  * **Details**
  *
@@ -408,7 +409,8 @@ export const appendElement: {
    *
    * **When to use**
    *
-   * Use to add one element to the end of a tuple while preserving tuple types.
+   * Use when you need the appended value to remain part of the tuple's type-level
+   * shape and preserve literal element positions.
    *
    * **Details**
    *
@@ -433,7 +435,8 @@ export const appendElement: {
    *
    * **When to use**
    *
-   * Use to add one element to the end of a tuple while preserving tuple types.
+   * Use when you need the appended value to remain part of the tuple's type-level
+   * shape and preserve literal element positions.
    *
    * **Details**
    *
@@ -774,7 +777,7 @@ export const renameIndices: {
  *
  * **When to use**
  *
- * Use when you want to apply the same transformation to every element.
+ * Use when you want to apply the same transformation to every tuple element.
  *
  * **Details**
  *
@@ -812,7 +815,7 @@ export const map: {
    *
    * **When to use**
    *
-   * Use when you want to apply the same transformation to every element.
+   * Use when you want to apply the same transformation to every tuple element.
    *
    * **Details**
    *
@@ -852,7 +855,7 @@ export const map: {
    *
    * **When to use**
    *
-   * Use when you want to apply the same transformation to every element.
+   * Use when you want to apply the same transformation to every tuple element.
    *
    * **Details**
    *
@@ -1125,7 +1128,7 @@ export const mapOmit: {
  *
  * **When to use**
  *
- * Use when you need to compare tuples element-by-element.
+ * Use when you need an `Equivalence` to compare tuples element-by-element.
  *
  * **Details**
  *
@@ -1158,7 +1161,8 @@ export const makeEquivalence = Equivalence.Tuple
  *
  * **When to use**
  *
- * Use to sort or compare tuples lexicographically by element position.
+ * Use when you need to sort fixed-position arrays lexicographically, with each
+ * position using its own ordering rule.
  *
  * **Details**
  *
@@ -1188,7 +1192,8 @@ export {
    *
    * **When to use**
    *
-   * Use to guard against unexpected array lengths at runtime.
+   * Use to guard that an array has exactly the tuple length expected at
+   * runtime.
    *
    * **Details**
    *
@@ -1222,8 +1227,8 @@ export {
    *
    * **When to use**
    *
-   * Use to guard that an array has at least the expected number of
-   * elements.
+   * Use to guard that an array has at least the tuple length expected at
+   * runtime.
    *
    * **Details**
    *
@@ -1260,8 +1265,8 @@ export {
  *
  * **When to use**
  *
- * Use when you need to merge two tuples of the same shape, such as summing
- * counters or concatenating strings.
+ * Use when you need to merge two same-shape tuples by combining each position
+ * independently, such as summing counters or concatenating strings.
  *
  * **Example** (Combining tuple elements)
  *
@@ -1301,7 +1306,8 @@ export function makeCombiner<A extends ReadonlyArray<unknown>>(
  *
  * **When to use**
  *
- * Use to fold a collection of tuples into a single summary tuple.
+ * Use when you need to fold same-shape tuples by accumulating each position
+ * independently into one summary tuple.
  *
  * **Example** (Reducing a collection of tuples)
  *