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

package/src/Metric.ts

@@ -1765,8 +1765,8 @@ const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey"
  *
  * **When to use**
  *
- * Use to provide a custom metric registry when a program or test needs metrics
- * isolated from the default registry.
+ * Use when you need a custom metric registry for an isolated program or test
+ * instead of the default registry.
  *
  * **Details**
  *
@@ -2193,11 +2193,10 @@ export const isMetric = (u: unknown): u is Metric<unknown, never> =>
  *
  * **Details**
  *
- * - `description` - A description of the `Counter`.
- * - `attributes`  - The attributes to associate with the `Counter`.
- * - `bigint`      - Indicates if the `Counter` should use the `bigint` type.
- * - `incremental` - Set to `true` to create a `Counter` that can only ever be
- *                   incremented.
+ * The optional `description` describes the counter, and `attributes` attach
+ * dimensions to it. Set `bigint` to create a counter that accepts `bigint`
+ * inputs. Set `incremental` to `true` to create a counter that can only ever be
+ * incremented.
  *
  * **Example** (Creating counter metrics)
  *
@@ -2253,11 +2252,10 @@ export const counter: {
    *
    * **Details**
    *
-   * - `description` - A description of the `Counter`.
-   * - `attributes`  - The attributes to associate with the `Counter`.
-   * - `bigint`      - Indicates if the `Counter` should use the `bigint` type.
-   * - `incremental` - Set to `true` to create a `Counter` that can only ever be
-   *                   incremented.
+   * The optional `description` describes the counter, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a counter that accepts `bigint`
+   * inputs. Set `incremental` to `true` to create a counter that can only ever be
+   * incremented.
    *
    * **Example** (Creating counter metrics)
    *
@@ -2321,11 +2319,10 @@ export const counter: {
    *
    * **Details**
    *
-   * - `description` - A description of the `Counter`.
-   * - `attributes`  - The attributes to associate with the `Counter`.
-   * - `bigint`      - Indicates if the `Counter` should use the `bigint` type.
-   * - `incremental` - Set to `true` to create a `Counter` that can only ever be
-   *                   incremented.
+   * The optional `description` describes the counter, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a counter that accepts `bigint`
+   * inputs. Set `incremental` to `true` to create a counter that can only ever be
+   * incremented.
    *
    * **Example** (Creating counter metrics)
    *
@@ -2390,14 +2387,14 @@ export const counter: {
  *
  * **When to use**
  *
- * Use when gauges are most suitable for metrics that represent instantaneous values,
- * such as memory usage or CPU load.
+ * Use when you need a metric for instantaneous values, such as memory usage or
+ * CPU load.
  *
  * **Details**
  *
- * - `description` - A description of the `Gauge`.
- * - `attributes`  - The attributes to associate with the `Gauge`.
- * - `bigint`      - Indicates if the `Gauge` should use the `bigint` type.
+ * The optional `description` describes the gauge, and `attributes` attach
+ * dimensions to it. Set `bigint` to create a gauge that accepts `bigint`
+ * inputs.
  *
  * **Example** (Creating gauge metrics)
  *
@@ -2457,14 +2454,14 @@ export const gauge: {
    *
    * **When to use**
    *
-   * Use when gauges are most suitable for metrics that represent instantaneous values,
-   * such as memory usage or CPU load.
+   * Use when you need a metric for instantaneous values, such as memory usage or
+   * CPU load.
    *
    * **Details**
    *
-   * - `description` - A description of the `Gauge`.
-   * - `attributes`  - The attributes to associate with the `Gauge`.
-   * - `bigint`      - Indicates if the `Gauge` should use the `bigint` type.
+   * The optional `description` describes the gauge, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a gauge that accepts `bigint`
+   * inputs.
    *
    * **Example** (Creating gauge metrics)
    *
@@ -2531,14 +2528,14 @@ export const gauge: {
    *
    * **When to use**
    *
-   * Use when gauges are most suitable for metrics that represent instantaneous values,
-   * such as memory usage or CPU load.
+   * Use when you need a metric for instantaneous values, such as memory usage or
+   * CPU load.
    *
    * **Details**
    *
-   * - `description` - A description of the `Gauge`.
-   * - `attributes`  - The attributes to associate with the `Gauge`.
-   * - `bigint`      - Indicates if the `Gauge` should use the `bigint` type.
+   * The optional `description` describes the gauge, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a gauge that accepts `bigint`
+   * inputs.
    *
    * **Example** (Creating gauge metrics)
    *
@@ -2607,15 +2604,14 @@ export const gauge: {
  *
  * **When to use**
  *
- * Use when frequency metrics are most suitable for counting the number of times a
- * specific event or incident occurs.
+ * Use when you need a metric for counting how often a specific event or
+ * incident occurs.
  *
  * **Details**
  *
- * - `description` - A description of the `Frequency`.
- * - `attributes`  - The attributes to associate with the `Frequency`.
- * - `preregisteredWords` - Occurrences which are pre-registered with the
- *                          `Frequency` metric occurrences.
+ * The optional `description` describes the frequency, and `attributes` attach
+ * dimensions to it. Use `preregisteredWords` to initialize occurrence counts
+ * for known string values before updates arrive.
  *
  * **Example** (Creating frequency metrics)
  *
@@ -2690,14 +2686,14 @@ export const frequency = (name: string, options?: {
  *
  * **When to use**
  *
- * Use when histogram metrics are most suitable for measuring the distribution of values
- * within a range.
+ * Use when you need a metric for measuring the distribution of values within a
+ * range.
  *
  * **Details**
  *
- * - `description` - A description of the `Histogram`.
- * - `attributes`  - The attributes to associate with the `Histogram`.
- * - `boundaries`  - The bucket boundaries of the `Histogram`
+ * The optional `description` describes the histogram, and `attributes` attach
+ * dimensions to it. The required `boundaries` option defines the histogram
+ * bucket boundaries.
  *
  * **Example** (Creating histogram metrics)
  *
@@ -2770,16 +2766,15 @@ export const histogram = (name: string, options: {
  *
  * **When to use**
  *
- * Use when summary metrics are most suitable for providing statistical information about
- * a set of values, including quantiles.
+ * Use when you need a metric that records statistical information about a set
+ * of values, including quantiles.
  *
  * **Details**
  *
- * - `description` - An description of the `Summary`.
- * - `attributes`  - The attributes to associate with the `Summary`.
- * - `maxAge`      - The maximum age of observations to retain.
- * - `maxSize`     - The maximum number of observations to keep.
- * - `quantiles`   - An array of quantiles to calculate (e.g., [0.5, 0.9]).
+ * The optional `description` describes the summary, and `attributes` attach
+ * dimensions to it. `maxAge` controls how long observations are retained,
+ * `maxSize` controls how many observations are kept, and `quantiles` lists the
+ * quantiles to calculate, such as `[0.5, 0.9]`.
  *
  * **Example** (Creating summary metrics)
  *
@@ -2866,19 +2861,18 @@ export const summary = (name: string, options: {
  *
  * **When to use**
  *
- * Use when summary metrics are most suitable for statistical information about a set of
- * values.
+ * Use when you need a metric that records statistical information about a set
+ * of values together with timestamps.
  *
  * **Details**
  *
  * Inputs to this metric are `[value, timestamp]` pairs; the current clock is
  * used when reading quantiles against the configured `maxAge`.
  *
- * - `description` - An description of the `Summary`.
- * - `attributes`  - The attributes to associate with the `Summary`.
- * - `maxAge`      - The maximum age of observations to retain.
- * - `maxSize`     - The maximum number of observations to keep.
- * - `quantiles`   - An array of quantiles to calculate (e.g., [0.5, 0.9]).
+ * The optional `description` describes the summary, and `attributes` attach
+ * dimensions to it. `maxAge` controls how long observations are retained,
+ * `maxSize` controls how many observations are kept, and `quantiles` lists the
+ * quantiles to calculate, such as `[0.5, 0.9]`.
  *
  * **Example** (Creating summaries with explicit timestamps)
  *
@@ -2970,13 +2964,12 @@ export const timer = (name: string, options?: {
  *
  * **Details**
  *
- * The returned state depends on the metric type:
- *
- * - Counter: `CounterState<number | bigint>` with `count` and `incremental`
- * - Gauge: `GaugeState<number | bigint>` with `value`
- * - Frequency: `FrequencyState` with `occurrences`
- * - Histogram: `HistogramState` with buckets, count, min, max, and sum
- * - Summary: `SummaryState` with quantiles, count, min, max, and sum
+ * The returned state depends on the metric type. Counters return
+ * `CounterState<number | bigint>` with `count` and `incremental`, gauges return
+ * `GaugeState<number | bigint>` with `value`, frequencies return
+ * `FrequencyState` with `occurrences`, histograms return `HistogramState` with
+ * buckets, count, min, max, and sum, and summaries return `SummaryState` with
+ * quantiles, count, min, max, and sum.
  *
  * **Example** (Reading metric state)
  *
@@ -3023,13 +3016,11 @@ export const value = <Input, State>(
  *
  * **Details**
  *
- * The behavior of `modify` depends on the metric type:
- *
- * - **Counter**: Adds the input value to the current count
- * - **Gauge**: Adds the input value to the current gauge value
- * - **Frequency**: Same as `update` - increments the occurrence count for the input string
- * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
- * - **Summary**: Same as `update` - records the input observation
+ * The behavior of `modify` depends on the metric type. Counters add the input
+ * value to the current count, gauges add the input value to the current gauge
+ * value, frequencies increment the occurrence count for the input string,
+ * histograms record the input value in the appropriate bucket, and summaries
+ * record the input observation.
  *
  * **Example** (Modifying metric values)
  *
@@ -3068,13 +3059,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3113,13 +3102,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3159,13 +3146,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3204,13 +3189,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3255,13 +3238,11 @@ export const modify: {
  *
  * **Details**
  *
- * The behavior of `update` depends on the metric type:
- *
- * - **Counter**: Adds the input value to the current count (same as `modify`)
- * - **Gauge**: Sets the gauge to the specified value (replaces current value)
- * - **Frequency**: Increments the occurrence count for the input string by 1
- * - **Histogram**: Records the input value in the appropriate bucket
- * - **Summary**: Records the input value as a new observation
+ * The behavior of `update` depends on the metric type. Counters add the input
+ * value to the current count, gauges replace the current value with the input
+ * value, frequencies increment the occurrence count for the input string,
+ * histograms record the input value in the appropriate bucket, and summaries
+ * record the input value as a new observation.
  *
  * **Example** (Updating metric values)
  *
@@ -3309,13 +3290,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -3363,13 +3342,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -3418,13 +3395,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -3472,13 +3447,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -5171,9 +5144,8 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  *
  * **When to use**
  *
- * Use when this is useful when you want to selectively disable runtime metrics for specific
- * parts of your application while keeping them enabled elsewhere, or when you need
- * to avoid the overhead of metrics collection in performance-critical sections.
+ * Use when you need to disable runtime metrics for a specific effect while
+ * keeping them enabled elsewhere.
  *
  * **Example** (Disabling runtime metrics for an effect)
  *

package/src/MutableHashMap.ts

@@ -269,7 +269,7 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
  *
  * **When to use**
  *
- * Use to safely read the value for a key as an `Option`.
+ * Use to safely read a `MutableHashMap` value for a key as an `Option`.
  *
  * **Details**
  *
@@ -303,7 +303,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -337,7 +337,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -372,7 +372,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -406,7 +406,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to safely read the value for a key as an `Option`.
+   * Use to safely read a `MutableHashMap` value for a key as an `Option`.
    *
    * **Details**
    *
@@ -546,7 +546,8 @@ const getFromBucket = <K, V>(
  *
  * **When to use**
  *
- * Use to test whether a key is present without reading its value.
+ * Use to test whether a key is present in a `MutableHashMap` without reading
+ * its value.
  *
  * **Example** (Checking for a key)
  *
@@ -574,7 +575,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -602,7 +604,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -631,7 +634,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -659,7 +663,8 @@ export const has: {
    *
    * **When to use**
    *
-   * Use to test whether a key is present without reading its value.
+   * Use to test whether a key is present in a `MutableHashMap` without reading
+   * its value.
    *
    * **Example** (Checking for a key)
    *
@@ -690,7 +695,8 @@ export const has: {
  *
  * **When to use**
  *
- * Use to insert a new entry or replace an existing entry in place.
+ * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+ * place.
  *
  * **Example** (Setting key-value pairs)
  *
@@ -730,7 +736,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -770,7 +777,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -811,7 +819,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -851,7 +860,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to insert a new entry or replace an existing entry in place.
+   * Use to insert a new `MutableHashMap` entry or replace an existing entry in
+   * place.
    *
    * **Example** (Setting key-value pairs)
    *
@@ -931,7 +941,8 @@ const getRefKey = <K>(
  *
  * **When to use**
  *
- * Use to transform an existing value in place without inserting missing keys.
+ * Use to transform an existing `MutableHashMap` value in place without
+ * inserting missing keys.
  *
  * **Example** (Modifying existing values)
  *
@@ -970,7 +981,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *
@@ -1009,7 +1021,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *
@@ -1049,7 +1062,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *
@@ -1088,7 +1102,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to transform an existing value in place without inserting missing keys.
+   * Use to transform an existing `MutableHashMap` value in place without
+   * inserting missing keys.
    *
    * **Example** (Modifying existing values)
    *

package/src/MutableList.ts

@@ -427,6 +427,11 @@ export const prependAll = <A>(self: MutableList<A>, messages: Iterable<A>): void
  * Prepends all elements from a ReadonlyArray to the beginning of the MutableList.
  * This is an optimized version that can reuse the array when mutable=true.
  *
+ * **When to use**
+ *
+ * Use when prepending a trusted array directly is worth the optimized path and
+ * you control whether the input may be reused.
+ *
  * **Gotchas**
  *
  * When mutable=true, the input array may be modified internally. Only use
@@ -512,6 +517,11 @@ export const appendAll = <A>(self: MutableList<A>, messages: Iterable<A>): numbe
  * This is an optimized version that can reuse the array when mutable=true.
  * Returns the number of elements added.
  *
+ * **When to use**
+ *
+ * Use when appending a trusted array directly is worth the optimized path and
+ * you control whether the input may be reused.
+ *
  * **Gotchas**
  *
  * When mutable=true, the input array may be modified internally. Only use
@@ -942,6 +952,11 @@ export const filter = <A>(self: MutableList<A>, f: (value: A, i: number) => bool
  * Removes all occurrences of a value from the `MutableList` using JavaScript
  * strict equality semantics.
  *
+ * **When to use**
+ *
+ * Use when in-place removal should use JavaScript identity/strict equality
+ * rather than Effect structural equality.
+ *
  * **Details**
  *
  * The list is modified in place.