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

package/src/SynchronizedRef.ts

@@ -134,7 +134,7 @@ export const getUnsafe = <A>(self: SynchronizedRef<A>): A => self.backing.ref.cu
 export const get = <A>(self: SynchronizedRef<A>): Effect.Effect<A> => Effect.sync(() => getUnsafe(self))
 
 /**
- * Atomically sets a new value and returns the previous value, serialized by the
+ * Sets a new value atomically and returns the previous value, serialized by the
  * ref's semaphore.
  *
  * **When to use**
@@ -151,7 +151,7 @@ export const get = <A>(self: SynchronizedRef<A>): Effect.Effect<A> => Effect.syn
  */
 export const getAndSet: {
   /**
-   * Atomically sets a new value and returns the previous value, serialized by the
+   * Sets a new value atomically and returns the previous value, serialized by the
    * ref's semaphore.
    *
    * **When to use**
@@ -168,7 +168,7 @@ export const getAndSet: {
    */
   <A>(value: A): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * Atomically sets a new value and returns the previous value, serialized by the
+   * Sets a new value atomically and returns the previous value, serialized by the
    * ref's semaphore.
    *
    * **When to use**
@@ -191,7 +191,7 @@ export const getAndSet: {
 )
 
 /**
- * Atomically updates the current value with a function and returns the previous
+ * Updates the current value atomically with a function and returns the previous
  * value, serialized by the ref's semaphore.
  *
  * **When to use**
@@ -207,7 +207,7 @@ export const getAndSet: {
  */
 export const getAndUpdate: {
   /**
-   * Atomically updates the current value with a function and returns the previous
+   * Updates the current value atomically with a function and returns the previous
    * value, serialized by the ref's semaphore.
    *
    * **When to use**
@@ -223,7 +223,7 @@ export const getAndUpdate: {
    */
   <A>(f: (a: A) => A): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * Atomically updates the current value with a function and returns the previous
+   * Updates the current value atomically with a function and returns the previous
    * value, serialized by the ref's semaphore.
    *
    * **When to use**
@@ -245,7 +245,7 @@ export const getAndUpdate: {
 )
 
 /**
- * Atomically runs an effectful update while holding the ref's semaphore, sets
+ * Runs an effectful update atomically while holding the ref's semaphore, sets
  * the new value if the effect succeeds, and returns the previous value.
  *
  * **When to use**
@@ -263,7 +263,7 @@ export const getAndUpdate: {
  */
 export const getAndUpdateEffect: {
   /**
-   * Atomically runs an effectful update while holding the ref's semaphore, sets
+   * Runs an effectful update atomically while holding the ref's semaphore, sets
    * the new value if the effect succeeds, and returns the previous value.
    *
    * **When to use**
@@ -281,7 +281,7 @@ export const getAndUpdateEffect: {
    */
   <A, R, E>(f: (a: A) => Effect.Effect<A, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Atomically runs an effectful update while holding the ref's semaphore, sets
+   * Runs an effectful update atomically while holding the ref's semaphore, sets
    * the new value if the effect succeeds, and returns the previous value.
    *
    * **When to use**
@@ -311,7 +311,7 @@ export const getAndUpdateEffect: {
 )
 
 /**
- * Atomically applies a partial update and returns the previous value. If the
+ * Applies a partial update atomically 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.
  *
@@ -327,7 +327,7 @@ export const getAndUpdateEffect: {
  */
 export const getAndUpdateSome: {
   /**
-   * Atomically applies a partial update and returns the previous value. If the
+   * Applies a partial update atomically 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.
    *
@@ -343,7 +343,7 @@ export const getAndUpdateSome: {
    */
   <A>(pf: (a: A) => Option.Option<A>): (self: SynchronizedRef<A>) => Effect.Effect<A>
   /**
-   * Atomically applies a partial update and returns the previous value. If the
+   * Applies a partial update atomically 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.
    *
@@ -365,7 +365,7 @@ export const getAndUpdateSome: {
 )
 
 /**
- * Atomically runs an effectful partial update while holding the ref's semaphore
+ * Runs an effectful partial update atomically while holding the ref's semaphore
  * and returns the previous value. `Option.some` updates the ref; `Option.none`
  * leaves it unchanged.
  *
@@ -382,7 +382,7 @@ export const getAndUpdateSome: {
  */
 export const getAndUpdateSomeEffect: {
   /**
-   * Atomically runs an effectful partial update while holding the ref's semaphore
+   * Runs an effectful partial update atomically while holding the ref's semaphore
    * and returns the previous value. `Option.some` updates the ref; `Option.none`
    * leaves it unchanged.
    *
@@ -399,7 +399,7 @@ export const getAndUpdateSomeEffect: {
    */
   <A, R, E>(pf: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SynchronizedRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Atomically runs an effectful partial update while holding the ref's semaphore
+   * Runs an effectful partial update atomically while holding the ref's semaphore
    * and returns the previous value. `Option.some` updates the ref; `Option.none`
    * leaves it unchanged.
    *
@@ -434,7 +434,7 @@ export const getAndUpdateSomeEffect: {
 )
 
 /**
- * Atomically computes a return value and a new ref value, stores the new value,
+ * Computes a return value and a new ref value atomically, stores the new value,
  * and returns the computed result.
  *
  * **When to use**
@@ -451,7 +451,7 @@ export const getAndUpdateSomeEffect: {
  */
 export const modify: {
   /**
-   * Atomically computes a return value and a new ref value, stores the new value,
+   * Computes a return value and a new ref value atomically, stores the new value,
    * and returns the computed result.
    *
    * **When to use**
@@ -468,7 +468,7 @@ export const modify: {
    */
   <A, B>(f: (a: A) => readonly [B, A]): (self: SynchronizedRef<A>) => Effect.Effect<B>
   /**
-   * Atomically computes a return value and a new ref value, stores the new value,
+   * Computes a return value and a new ref value atomically, stores the new value,
    * and returns the computed result.
    *
    * **When to use**
@@ -491,7 +491,7 @@ export const modify: {
 )
 
 /**
- * Atomically runs an effectful modification while holding the ref's semaphore,
+ * Runs an effectful modification atomically while holding the ref's semaphore,
  * stores the new value if the effect succeeds, and returns the computed result.
  *
  * **When to use**
@@ -507,7 +507,7 @@ export const modify: {
  */
 export const modifyEffect: {
   /**
-   * Atomically runs an effectful modification while holding the ref's semaphore,
+   * Runs an effectful modification atomically while holding the ref's semaphore,
    * stores the new value if the effect succeeds, and returns the computed result.
    *
    * **When to use**
@@ -523,7 +523,7 @@ export const modifyEffect: {
    */
   <A, B, E, R>(f: (a: A) => Effect.Effect<readonly [B, A], E, R>): (self: SynchronizedRef<A>) => Effect.Effect<B, E, R>
   /**
-   * Atomically runs an effectful modification while holding the ref's semaphore,
+   * Runs an effectful modification atomically while holding the ref's semaphore,
    * stores the new value if the effect succeeds, and returns the computed result.
    *
    * **When to use**
@@ -554,7 +554,7 @@ export const modifyEffect: {
 )
 
 /**
- * Atomically computes a return value and an optional new ref value.
+ * Computes a return value and an optional new ref value atomically.
  * `Option.some` updates the ref; `Option.none` leaves it unchanged.
  *
  * **When to use**
@@ -569,7 +569,7 @@ export const modifyEffect: {
  */
 export const modifySome: {
   /**
-   * Atomically computes a return value and an optional new ref value.
+   * Computes a return value and an optional new ref value atomically.
    * `Option.some` updates the ref; `Option.none` leaves it unchanged.
    *
    * **When to use**
@@ -584,7 +584,7 @@ export const modifySome: {
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]): (self: SynchronizedRef<A>) => Effect.Effect<B>
   /**
-   * Atomically computes a return value and an optional new ref value.
+   * Computes a return value and an optional new ref value atomically.
    * `Option.some` updates the ref; `Option.none` leaves it unchanged.
    *
    * **When to use**
@@ -607,7 +607,7 @@ export const modifySome: {
 )
 
 /**
- * Atomically runs an effectful modification while holding the ref's semaphore.
+ * Runs an effectful modification atomically 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.
  *
@@ -624,7 +624,7 @@ export const modifySome: {
  */
 export const modifySomeEffect: {
   /**
-   * Atomically runs an effectful modification while holding the ref's semaphore.
+   * Runs an effectful modification atomically 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.
    *
@@ -644,7 +644,7 @@ export const modifySomeEffect: {
     pf: (a: A) => Effect.Effect<readonly [B, Option.Option<A>], E, R>
   ): (self: SynchronizedRef<A>) => Effect.Effect<B, E, R>
   /**
-   * Atomically runs an effectful modification while holding the ref's semaphore.
+   * Runs an effectful modification atomically 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.
    *

package/src/Terminal.ts

@@ -129,7 +129,7 @@ export interface UserInput {
 const QuitErrorTypeId = "effect/platform/Terminal/QuitError"
 
 /**
- * A `QuitError` represents an error that occurs when a user attempts to
+ * Represents an error that occurs when a user attempts to
  * quit out of a `Terminal` prompt for input (usually by entering `ctrl`+`c`).
  *
  * **When to use**
@@ -174,9 +174,14 @@ export class QuitError extends Schema.ErrorClass<QuitError>("QuitError")({
 export const isQuitError = (u: unknown): u is QuitError => Predicate.hasProperty(u, QuitErrorTypeId)
 
 /**
- * Context service tag for accessing a `Terminal` implementation.
+ * Service tag for command-line input and output services.
  *
- * @category services
+ * **When to use**
+ *
+ * Use to access or provide platform terminal capabilities such as reading
+ * input, writing output, and inspecting terminal dimensions.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export const Terminal: Context.Service<Terminal, Terminal> = Context.Service("effect/platform/Terminal")

package/src/Tracer.ts

@@ -155,7 +155,12 @@ export type SpanStatus = {
 export type AnySpan = Span | ExternalSpan
 
 /**
- * The string key used to identify the `ParentSpan` context service.
+ * Defines the string key for the parent-span context service.
+ *
+ * **When to use**
+ *
+ * Use when integrating lower-level tracing code that needs the raw context key
+ * for parent span lookup.
  *
  * **Example** (Reading the parent span key)
  *
@@ -485,9 +490,17 @@ export const externalSpan = (
 })
 
 /**
- * Reference used to disable trace propagation. When set on the fiber or span
- * annotations, new spans are created as non-propagating no-op spans and
- * disabled spans are skipped when deriving a parent span.
+ * Context reference for disabling trace propagation.
+ *
+ * **When to use**
+ *
+ * Use to prevent spans in a scope from propagating tracing context.
+ *
+ * **Details**
+ *
+ * When enabled on fiber or span annotations, new spans are created as
+ * non-propagating no-op spans and disabled spans are skipped when deriving a
+ * parent span.
  *
  * **Example** (Disabling span propagation)
  *
@@ -511,7 +524,7 @@ export const DisablePropagation = Context.Reference<boolean>(
 )
 
 /**
- * Reference for controlling the current trace level for dynamic filtering.
+ * Context reference for controlling the current trace level for dynamic filtering.
  *
  * **When to use**
  *
@@ -534,7 +547,7 @@ export const CurrentTraceLevel: Context.Reference<LogLevel> = Context.Reference<
 )
 
 /**
- * Reference for setting the minimum trace level threshold. Spans and their
+ * Context reference for setting the minimum trace level threshold. Spans and their
  * descendants below this level will have their sampling decision forced to
  * false, preventing them from being exported.
  *
@@ -562,7 +575,12 @@ export const MinimumTraceLevel = Context.Reference<
 >("effect/Tracer/MinimumTraceLevel", { defaultValue: () => "All" })
 
 /**
- * The string key used to identify the active `Tracer` context reference.
+ * Defines the string key for the active tracer context reference.
+ *
+ * **When to use**
+ *
+ * Use when integrating lower-level tracing code that needs the raw context key
+ * for active tracer lookup.
  *
  * @category references
  * @since 4.0.0

package/src/Trie.ts

@@ -13,8 +13,6 @@
  * - Prefix lookup uses {@link keysWithPrefix}, {@link valuesWithPrefix},
  *   {@link entriesWithPrefix}, {@link toEntriesWithPrefix}, or
  *   {@link longestPrefixOf}.
- * - Updates such as {@link insert}, {@link remove}, {@link insertMany}, and
- *   {@link removeMany} return new tries; existing tries are not mutated.
  * - Iteration yields entries in key order, not insertion order.
  * - Lookup work is proportional to the key or prefix length rather than the
  *   total number of entries.
@@ -192,7 +190,7 @@ export const make: <Entries extends Array<readonly [string, any]>>(
 ) => Trie<Entries[number] extends readonly [any, infer V] ? V : never> = TR.make
 
 /**
- * Insert a new entry in the `Trie`.
+ * Inserts a new entry in the `Trie`.
  *
  * **Example** (Inserting entries)
  *
@@ -221,7 +219,7 @@ export const make: <Entries extends Array<readonly [string, any]>>(
  */
 export const insert: {
   /**
-   * Insert a new entry in the `Trie`.
+   * Inserts a new entry in the `Trie`.
    *
    * **Example** (Inserting entries)
    *
@@ -250,7 +248,7 @@ export const insert: {
    */
   <V>(key: string, value: V): (self: Trie<V>) => Trie<V>
   /**
-   * Insert a new entry in the `Trie`.
+   * Inserts a new entry in the `Trie`.
    *
    * **Example** (Inserting entries)
    *
@@ -819,7 +817,7 @@ export const longestPrefixOf: {
 export const size: <V>(self: Trie<V>) => number = TR.size
 
 /**
- * Safely lookup the value for the specified key in the `Trie`.
+ * Looks up the value for the specified key in the `Trie` safely.
  *
  * **Example** (Looking up values safely)
  *
@@ -849,7 +847,7 @@ export const size: <V>(self: Trie<V>) => number = TR.size
  */
 export const get: {
   /**
-   * Safely lookup the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` safely.
    *
    * **Example** (Looking up values safely)
    *
@@ -879,7 +877,7 @@ export const get: {
    */
   (key: string): <V>(self: Trie<V>) => Option<V>
   /**
-   * Safely lookup the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` safely.
    *
    * **Example** (Looking up values safely)
    *
@@ -911,7 +909,7 @@ export const get: {
 } = TR.get
 
 /**
- * Check if the given key exists in the `Trie`.
+ * Checks whether the given key exists in the `Trie`.
  *
  * **Example** (Checking key membership)
  *
@@ -941,7 +939,7 @@ export const get: {
  */
 export const has: {
   /**
-   * Check if the given key exists in the `Trie`.
+   * Checks whether the given key exists in the `Trie`.
    *
    * **Example** (Checking key membership)
    *
@@ -971,7 +969,7 @@ export const has: {
    */
   (key: string): <V>(self: Trie<V>) => boolean
   /**
-   * Check if the given key exists in the `Trie`.
+   * Checks whether the given key exists in the `Trie`.
    *
    * **Example** (Checking key membership)
    *
@@ -1024,7 +1022,7 @@ export const has: {
 export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
 
 /**
- * Unsafely looks up the value for the specified key in the `Trie`.
+ * Looks up the value for the specified key in the `Trie` unsafely.
  *
  * **Gotchas**
  *
@@ -1050,7 +1048,7 @@ export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
  */
 export const getUnsafe: {
   /**
-   * Unsafely looks up the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` unsafely.
    *
    * **Gotchas**
    *
@@ -1076,7 +1074,7 @@ export const getUnsafe: {
    */
   (key: string): <V>(self: Trie<V>) => V
   /**
-   * Unsafely looks up the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` unsafely.
    *
    * **Gotchas**
    *
@@ -1104,7 +1102,7 @@ export const getUnsafe: {
 } = TR.getUnsafe
 
 /**
- * Remove the entry for the specified key in the `Trie`.
+ * Removes the entry for the specified key in the `Trie`.
  *
  * **Example** (Removing entries)
  *
@@ -1132,7 +1130,7 @@ export const getUnsafe: {
  */
 export const remove: {
   /**
-   * Remove the entry for the specified key in the `Trie`.
+   * Removes the entry for the specified key in the `Trie`.
    *
    * **Example** (Removing entries)
    *
@@ -1160,7 +1158,7 @@ export const remove: {
    */
   (key: string): <V>(self: Trie<V>) => Trie<V>
   /**
-   * Remove the entry for the specified key in the `Trie`.
+   * Removes the entry for the specified key in the `Trie`.
    *
    * **Example** (Removing entries)
    *
@@ -1190,7 +1188,7 @@ export const remove: {
 } = TR.remove
 
 /**
- * Reduce a state over the entries of the `Trie`.
+ * Reduces a state over the entries of the `Trie`.
  *
  * **Example** (Reducing entries)
  *
@@ -1229,7 +1227,7 @@ export const remove: {
  */
 export const reduce: {
   /**
-   * Reduce a state over the entries of the `Trie`.
+   * Reduces a state over the entries of the `Trie`.
    *
    * **Example** (Reducing entries)
    *
@@ -1268,7 +1266,7 @@ export const reduce: {
    */
   <Z, V>(zero: Z, f: (accumulator: Z, value: V, key: string) => Z): (self: Trie<V>) => Z
   /**
-   * Reduce a state over the entries of the `Trie`.
+   * Reduces a state over the entries of the `Trie`.
    *
    * **Example** (Reducing entries)
    *
@@ -2019,7 +2017,7 @@ export const removeMany: {
 } = TR.removeMany
 
 /**
- * Insert multiple entries in the `Trie` at once.
+ * Inserts multiple entries in the `Trie` at once.
  *
  * **Example** (Inserting multiple entries)
  *
@@ -2051,7 +2049,7 @@ export const removeMany: {
  */
 export const insertMany: {
   /**
-   * Insert multiple entries in the `Trie` at once.
+   * Inserts multiple entries in the `Trie` at once.
    *
    * **Example** (Inserting multiple entries)
    *
@@ -2083,7 +2081,7 @@ export const insertMany: {
    */
   <V>(iter: Iterable<[string, V]>): (self: Trie<V>) => Trie<V>
   /**
-   * Insert multiple entries in the `Trie` at once.
+   * Inserts multiple entries in the `Trie` at once.
    *
    * **Example** (Inserting multiple entries)
    *