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

package/src/Terminal.ts

@@ -181,7 +181,7 @@ export const isQuitError = (u: unknown): u is QuitError => Predicate.hasProperty
  * Use to access or provide platform terminal capabilities such as reading
  * input, writing output, and inspecting terminal dimensions.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export const Terminal: Context.Service<Terminal, Terminal> = Context.Service("effect/platform/Terminal")

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)
  *
@@ -171,7 +171,7 @@ export type AnySpan = Span | ExternalSpan
  * console.log(Tracer.ParentSpanKey) // "effect/Tracer/ParentSpan"
  * ```
  *
- * @category tags
+ * @category constants
  * @since 4.0.0
  */
 export const ParentSpanKey = "effect/Tracer/ParentSpan"
@@ -192,7 +192,7 @@ export const ParentSpanKey = "effect/Tracer/ParentSpan"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 2.0.0
  */
 export class ParentSpan extends Context.Service<ParentSpan, AnySpan>()(ParentSpanKey) {}
@@ -255,7 +255,7 @@ export interface ExternalSpan {
  * )
  * ```
  *
- * @category models
+ * @category options
  * @since 3.1.0
  */
 export interface SpanOptions extends SpanOptionsNoTrace, TraceOptions {}
@@ -265,7 +265,7 @@ export interface SpanOptions extends SpanOptionsNoTrace, TraceOptions {}
  * attributes, links, parent or root selection, annotations, span kind,
  * sampling, and the trace level used for filtering.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface SpanOptionsNoTrace {
@@ -283,7 +283,7 @@ export interface SpanOptionsNoTrace {
  * Options that control stack trace capture for tracing wrappers.
  * `captureStackTrace` can disable capture or provide a lazy stack string.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface TraceOptions {
@@ -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**
    *
@@ -224,7 +224,7 @@ type PickTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, K>
  *
  * @see {@link omit} – the inverse (exclude indices instead)
  * @see {@link get} – extract a single element
- * @category utils
+ * @category filtering
  * @since 4.0.0
  */
 export const pick: {
@@ -250,7 +250,7 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude indices instead)
    * @see {@link get} – extract a single element
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(indices: I): (self: T) => PickTuple<T, I[number]>
@@ -276,7 +276,7 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude indices instead)
    * @see {@link get} – extract a single element
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(self: T, indices: I): PickTuple<T, I[number]>
@@ -313,7 +313,7 @@ type OmitTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, Exclude<Ind
  * ```
  *
  * @see {@link pick} – the inverse (keep only specified indices)
- * @category utils
+ * @category filtering
  * @since 4.0.0
  */
 export const omit: {
@@ -338,7 +338,7 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified indices)
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(indices: I): (self: T) => OmitTuple<T, I[number]>
@@ -363,7 +363,7 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified indices)
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(self: T, indices: I): OmitTuple<T, I[number]>
@@ -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**
  *
@@ -399,7 +400,7 @@ export const omit: {
  * ```
  *
  * @see {@link appendElements} – append multiple elements (another tuple)
- * @category Concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const appendElement: {
@@ -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**
    *
@@ -424,7 +426,7 @@ export const appendElement: {
    * ```
    *
    * @see {@link appendElements} – append multiple elements (another tuple)
-   * @category Concatenating
+   * @category combining
    * @since 2.0.0
    */
   <const E>(element: E): <const T extends ReadonlyArray<unknown>>(self: T) => [...T, E]
@@ -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**
    *
@@ -449,7 +452,7 @@ export const appendElement: {
    * ```
    *
    * @see {@link appendElements} – append multiple elements (another tuple)
-   * @category Concatenating
+   * @category combining
    * @since 2.0.0
    */
   <const T extends ReadonlyArray<unknown>, const E>(self: T, element: E): [...T, E]
@@ -477,7 +480,7 @@ export const appendElement: {
  * ```
  *
  * @see {@link appendElement} – append a single element
- * @category Concatenating
+ * @category combining
  * @since 4.0.0
  */
 export const appendElements: {
@@ -503,7 +506,7 @@ export const appendElements: {
    * ```
    *
    * @see {@link appendElement} – append a single element
-   * @category Concatenating
+   * @category combining
    * @since 4.0.0
    */
   <const T2 extends ReadonlyArray<unknown>>(that: T2): <const T1 extends ReadonlyArray<unknown>>(self: T1) => [...T1, ...T2]
@@ -529,7 +532,7 @@ export const appendElements: {
    * ```
    *
    * @see {@link appendElement} – append a single element
-   * @category Concatenating
+   * @category combining
    * @since 4.0.0
    */
   <const T1 extends ReadonlyArray<unknown>, const T2 extends ReadonlyArray<unknown>>(self: T1, that: T2): [...T1, ...T2]
@@ -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**
  *
@@ -1146,7 +1149,7 @@ export const mapOmit: {
  * ```
  *
  * @see {@link makeOrder} – create an `Order` for tuples
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const makeEquivalence = Equivalence.Tuple
@@ -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**
  *
@@ -1176,7 +1180,7 @@ export const makeEquivalence = Equivalence.Tuple
  * ```
  *
  * @see {@link makeEquivalence} – create an `Equivalence` for tuples
- * @category Ordering
+ * @category ordering
  * @since 4.0.0
  */
 export const makeOrder = order.Tuple
@@ -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)
  *

package/src/TxHashMap.ts

@@ -164,7 +164,7 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Key<T extends TxHashMap<any, any>> = T extends TxHashMap<infer K, any> ? K : never
@@ -197,7 +197,7 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Value<T extends TxHashMap<any, any>> = T extends TxHashMap<any, infer V> ? V : never
@@ -233,7 +233,7 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Entry<T extends TxHashMap<any, any>> = T extends TxHashMap<infer K, infer V> ? readonly [K, V] : never

package/src/TxHashSet.ts

@@ -146,7 +146,7 @@ export declare namespace TxHashSet {
    * console.log(processFruit("apple")) // Processing apple
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Value<T> = T extends TxHashSet<infer V> ? V : never

package/src/TxReentrantLock.ts

@@ -594,7 +594,8 @@ export const withWriteLock: {
  *
  * **When to use**
  *
- * Use as the short alias for {@link withWriteLock}.
+ * Use when you need to run an effect with exclusive write access through a
+ * `TxReentrantLock` and prefer the concise lock helper.
  *
  * **Example** (Running an effect with exclusive access)
  *
@@ -620,7 +621,8 @@ export const withLock: {
    *
    * **When to use**
    *
-   * Use as the short alias for {@link withWriteLock}.
+   * Use when you need to run an effect with exclusive write access through a
+   * `TxReentrantLock` and prefer the concise lock helper.
    *
    * **Example** (Running an effect with exclusive access)
    *
@@ -646,7 +648,8 @@ export const withLock: {
    *
    * **When to use**
    *
-   * Use as the short alias for {@link withWriteLock}.
+   * Use when you need to run an effect with exclusive write access through a
+   * `TxReentrantLock` and prefer the concise lock helper.
    *
    * **Example** (Running an effect with exclusive access)
    *

package/src/TxRef.ts

@@ -120,7 +120,7 @@ export interface TxRef<in out A> extends Pipeable {
  *
  * **When to use**
  *
- * Use to create a transactional reference inside an `Effect` workflow.
+ * Use to create a `TxRef` inside an `Effect` workflow.
  *
  * **Example** (Creating transactional references)
  *
@@ -153,8 +153,8 @@ export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
  *
  * **When to use**
  *
- * Use to construct a transactional reference synchronously when it must be
- * created outside an `Effect` workflow.
+ * Use to construct a `TxRef` synchronously when it must be created outside an
+ * `Effect` workflow.
  *
  * **Example** (Creating transactional references unsafely)
  *
@@ -188,8 +188,8 @@ export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
  *
  * **When to use**
  *
- * Use to update a transactional reference and return a computed result from the
- * same transaction step.
+ * Use to update a `TxRef` and return a computed result from the same
+ * transaction step.
  *
  * **Example** (Modifying transactional references)
  *
@@ -216,8 +216,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to update a transactional reference and return a computed result from the
-   * same transaction step.
+   * Use to update a `TxRef` and return a computed result from the same
+   * transaction step.
    *
    * **Example** (Modifying transactional references)
    *
@@ -244,8 +244,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to update a transactional reference and return a computed result from the
-   * same transaction step.
+   * Use to update a `TxRef` and return a computed result from the same
+   * transaction step.
    *
    * **Example** (Modifying transactional references)
    *
@@ -291,7 +291,7 @@ export const modify: {
  *
  * **When to use**
  *
- * Use to transform a transactional reference when no result value is needed.
+ * Use to transform a `TxRef` when no result value is needed.
  *
  * **Example** (Updating transactional references)
  *
@@ -319,7 +319,7 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform a transactional reference when no result value is needed.
+   * Use to transform a `TxRef` when no result value is needed.
    *
    * **Example** (Updating transactional references)
    *
@@ -347,7 +347,7 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform a transactional reference when no result value is needed.
+   * Use to transform a `TxRef` when no result value is needed.
    *
    * **Example** (Updating transactional references)
    *
@@ -380,7 +380,7 @@ export const update: {
  *
  * **When to use**
  *
- * Use to read the current value of a transactional reference.
+ * Use to read the current value of a `TxRef`.
  *
  * **Example** (Reading transactional references)
  *
@@ -409,7 +409,7 @@ export const get = <A>(self: TxRef<A>): Effect.Effect<A> => modify(self, (curren
  *
  * **When to use**
  *
- * Use to replace the value of a transactional reference.
+ * Use to replace the value of a `TxRef`.
  *
  * **Example** (Setting transactional references)
  *
@@ -437,7 +437,7 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the value of a transactional reference.
+   * Use to replace the value of a `TxRef`.
    *
    * **Example** (Setting transactional references)
    *
@@ -465,7 +465,7 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the value of a transactional reference.
+   * Use to replace the value of a `TxRef`.
    *
    * **Example** (Setting transactional references)
    *