effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Metric.ts

@@ -104,6 +104,8 @@ import type { Contravariant, Covariant } from "./Types.ts"
  * A `Metric<Input, State>` represents a concurrent metric which accepts update
  * values of type `Input` and are aggregated to a value of type `State`.
  *
+ * **Details**
+ *
  * For example, a counter metric would have type `Metric<number, number>`,
  * representing the fact that the metric can be updated with numbers (the amount
  * to increment or decrement the counter by), and the state of the counter is a
@@ -191,6 +193,8 @@ export interface Metric<in Input, out State> extends Pipeable {
 /**
  * A Counter metric that tracks cumulative values that typically only increase.
  *
+ * **When to use**
+ *
  * Counters are useful for tracking monotonically increasing values like request counts,
  * bytes processed, errors encountered, or any value that accumulates over time.
  *
@@ -322,6 +326,8 @@ export interface CounterState<in Input extends number | bigint> {
 /**
  * A Frequency metric interface that counts occurrences of discrete string values.
  *
+ * **When to use**
+ *
  * Frequency metrics are ideal for tracking categorical data where you want to count
  * how many times specific string values occur, such as HTTP status codes, user actions,
  * error types, or any discrete string-based events.
@@ -492,6 +498,8 @@ export interface FrequencyState {
 /**
  * A Gauge metric that tracks instantaneous values that can go up or down.
  *
+ * **When to use**
+ *
  * Gauges are useful for tracking current state values like memory usage, CPU load,
  * active connections, queue sizes, or any value that represents a current level.
  *
@@ -622,6 +630,8 @@ export interface GaugeState<in Input extends number | bigint> {
 /**
  * A Histogram metric that records observations in configurable buckets to analyze value distributions.
  *
+ * **When to use**
+ *
  * Histograms are ideal for measuring request durations, response sizes, and other continuous values
  * where you need to understand the distribution of values rather than just aggregates.
  *
@@ -802,6 +812,8 @@ export interface HistogramState {
 /**
  * A Summary metric that calculates quantiles over a sliding time window of observations.
  *
+ * **When to use**
+ *
  * Summaries provide statistical insights into value distributions by tracking specific quantiles
  * (percentiles) such as median (50th), 95th percentile, 99th percentile, etc. They're ideal for
  * understanding performance characteristics like response time distributions.
@@ -1700,6 +1712,7 @@ export const CurrentMetricAttributesKey = "effect/Metric/CurrentMetricAttributes
  * context.
  *
  * **Details**
+ *
  * The default value is an empty attribute set. Metric reads and updates merge
  * these contextual attributes with the metric's own attributes to select the
  * metric series being accessed.
@@ -1746,6 +1759,7 @@ const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey"
  * `Context.Reference` for the metric registry in the current context.
  *
  * **Details**
+ *
  * The default registry is an empty `Map`. Metrics register their metadata and
  * hooks lazily in this map when they are read or updated.
  *
@@ -2126,6 +2140,8 @@ class MetricTransform<in Input, out State, in Input2> extends Metric$<Input2, St
 /**
  * Returns `true` if the specified value is a `Metric`, otherwise returns `false`.
  *
+ * **When to use**
+ *
  * This function is useful for runtime type checking and ensuring that a value
  * conforms to the Metric interface before performing metric operations.
  *
@@ -2155,7 +2171,7 @@ export const isMetric = (u: unknown): u is Metric<unknown, never> =>
  * time. Counters can be incremented and decremented and provide a running total
  * of changes.
  *
- * **Options**
+ * **Details**
  *
  * - `description` - A description of the `Counter`.
  * - `attributes`  - The attributes to associate with the `Counter`.
@@ -2215,7 +2231,7 @@ export const counter: {
    * time. Counters can be incremented and decremented and provide a running total
    * of changes.
    *
-   * **Options**
+   * **Details**
    *
    * - `description` - A description of the `Counter`.
    * - `attributes`  - The attributes to associate with the `Counter`.
@@ -2283,7 +2299,7 @@ export const counter: {
    * time. Counters can be incremented and decremented and provide a running total
    * of changes.
    *
-   * **Options**
+   * **Details**
    *
    * - `description` - A description of the `Counter`.
    * - `attributes`  - The attributes to associate with the `Counter`.
@@ -2352,10 +2368,12 @@ export const counter: {
  * Represents a `Gauge` metric that tracks and reports a single numerical value
  * at a specific moment.
  *
+ * **When to use**
+ *
  * Gauges are most suitable for metrics that represent instantaneous values,
  * such as memory usage or CPU load.
  *
- * **Options**
+ * **Details**
  *
  * - `description` - A description of the `Gauge`.
  * - `attributes`  - The attributes to associate with the `Gauge`.
@@ -2417,10 +2435,12 @@ export const gauge: {
    * Represents a `Gauge` metric that tracks and reports a single numerical value
    * at a specific moment.
    *
+   * **When to use**
+   *
    * Gauges are most suitable for metrics that represent instantaneous values,
    * such as memory usage or CPU load.
    *
-   * **Options**
+   * **Details**
    *
    * - `description` - A description of the `Gauge`.
    * - `attributes`  - The attributes to associate with the `Gauge`.
@@ -2489,10 +2509,12 @@ export const gauge: {
    * Represents a `Gauge` metric that tracks and reports a single numerical value
    * at a specific moment.
    *
+   * **When to use**
+   *
    * Gauges are most suitable for metrics that represent instantaneous values,
    * such as memory usage or CPU load.
    *
-   * **Options**
+   * **Details**
    *
    * - `description` - A description of the `Gauge`.
    * - `attributes`  - The attributes to associate with the `Gauge`.
@@ -2563,10 +2585,12 @@ export const gauge: {
  * Creates a `Frequency` metric which can be used to count the number of
  * occurrences of a string.
  *
+ * **When to use**
+ *
  * Frequency metrics are most suitable for counting the number of times a
  * specific event or incident occurs.
  *
- * **Options**
+ * **Details**
  *
  * - `description` - A description of the `Frequency`.
  * - `attributes`  - The attributes to associate with the `Frequency`.
@@ -2644,10 +2668,12 @@ export const frequency = (name: string, options?: {
 /**
  * Represents a `Histogram` metric that records observations into buckets.
  *
+ * **When to use**
+ *
  * Histogram metrics are most suitable for measuring the distribution of values
  * within a range.
  *
- * **Options**
+ * **Details**
  *
  * - `description` - A description of the `Histogram`.
  * - `attributes`  - The attributes to associate with the `Histogram`.
@@ -2722,10 +2748,12 @@ export const histogram = (name: string, options: {
  * Creates a `Summary` metric that records observations and calculates quantiles
  * which takes a value as input and uses the current time.
  *
+ * **When to use**
+ *
  * Summary metrics are most suitable for providing statistical information about
  * a set of values, including quantiles.
  *
- * **Options**
+ * **Details**
  *
  * - `description` - An description of the `Summary`.
  * - `attributes`  - The attributes to associate with the `Summary`.
@@ -2816,11 +2844,15 @@ export const summary = (name: string, options: {
  * Creates a `Summary` metric that records observations with explicit
  * timestamps and calculates quantiles.
  *
+ * **When to use**
+ *
  * Summary metrics are most suitable for statistical information about a set of
- * values. Inputs to this metric are `[value, timestamp]` pairs; the current
- * clock is used when reading quantiles against the configured `maxAge`.
+ * values.
  *
- * **Options**
+ * **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`.
@@ -2859,6 +2891,8 @@ export const summaryWithTimestamp = (name: string, options: {
  * Creates a timer metric, based on a `Histogram`, which keeps track of
  * durations in milliseconds.
  *
+ * **Details**
+ *
  * The unit of time will automatically be added to the metric as a tag (i.e.
  * `"time_unit: milliseconds"`).
  *
@@ -2915,6 +2949,7 @@ export const timer = (name: string, options?: {
  * Retrieves the current state of the specified `Metric`.
  *
  * **Details**
+ *
  * The returned state depends on the metric type:
  *
  * - Counter: `CounterState<number | bigint>` with `count` and `incremental`
@@ -2966,7 +3001,10 @@ export const value = <Input, State>(
 /**
  * Modifies the metric with the specified input.
  *
+ * **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
@@ -3008,7 +3046,10 @@ export const modify: {
   /**
    * Modifies the metric with the specified input.
    *
+   * **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
@@ -3050,7 +3091,10 @@ export const modify: {
   /**
    * Modifies the metric with the specified input.
    *
+   * **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
@@ -3093,7 +3137,10 @@ export const modify: {
   /**
    * Modifies the metric with the specified input.
    *
+   * **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
@@ -3135,7 +3182,10 @@ export const modify: {
   /**
    * Modifies the metric with the specified input.
    *
+   * **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
@@ -3183,7 +3233,10 @@ export const modify: {
 /**
  * Updates the metric with the specified input.
  *
+ * **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
@@ -3234,7 +3287,10 @@ export const update: {
   /**
    * Updates the metric with the specified input.
    *
+   * **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
@@ -3285,7 +3341,10 @@ export const update: {
   /**
    * Updates the metric with the specified input.
    *
+   * **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
@@ -3337,7 +3396,10 @@ export const update: {
   /**
    * Updates the metric with the specified input.
    *
+   * **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
@@ -3388,7 +3450,10 @@ export const update: {
   /**
    * Updates the metric with the specified input.
    *
+   * **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
@@ -3851,6 +3916,8 @@ export const withConstantInput: {
 /**
  * Returns a new metric that applies the specified attributes to all operations.
  *
+ * **Details**
+ *
  * Attributes are key-value pairs that provide additional context for metrics,
  * enabling filtering, grouping, and more detailed analysis. Each combination
  * of attribute values creates a separate metric series.
@@ -3908,6 +3975,8 @@ export const withAttributes: {
   /**
    * Returns a new metric that applies the specified attributes to all operations.
    *
+   * **Details**
+   *
    * Attributes are key-value pairs that provide additional context for metrics,
    * enabling filtering, grouping, and more detailed analysis. Each combination
    * of attribute values creates a separate metric series.
@@ -3965,6 +4034,8 @@ export const withAttributes: {
   /**
    * Returns a new metric that applies the specified attributes to all operations.
    *
+   * **Details**
+   *
    * Attributes are key-value pairs that provide additional context for metrics,
    * enabling filtering, grouping, and more detailed analysis. Each combination
    * of attribute values creates a separate metric series.
@@ -4023,6 +4094,8 @@ export const withAttributes: {
   /**
    * Returns a new metric that applies the specified attributes to all operations.
    *
+   * **Details**
+   *
    * Attributes are key-value pairs that provide additional context for metrics,
    * enabling filtering, grouping, and more detailed analysis. Each combination
    * of attribute values creates a separate metric series.
@@ -4080,6 +4153,8 @@ export const withAttributes: {
   /**
    * Returns a new metric that applies the specified attributes to all operations.
    *
+   * **Details**
+   *
    * Attributes are key-value pairs that provide additional context for metrics,
    * enabling filtering, grouping, and more detailed analysis. Each combination
    * of attribute values creates a separate metric series.
@@ -4150,6 +4225,8 @@ export const withAttributes: {
 /**
  * Captures a snapshot of all registered metrics in the current context.
  *
+ * **Details**
+ *
  * Returns an array of metric snapshots, each containing the metric's metadata
  * (name, description, type) and current state (values, counts, etc.).
  *
@@ -4205,6 +4282,8 @@ export const snapshot: Effect<ReadonlyArray<Metric.Snapshot>> = InternalEffect.m
  * Returns a human-readable string representation of all currently registered
  * metrics in a tabular format.
  *
+ * **Details**
+ *
  * This debugging utility captures a snapshot of all metrics and formats them
  * in an easy-to-read table showing names, descriptions, types, attributes,
  * and current state values.
@@ -4295,6 +4374,8 @@ export const dump: Effect<string> = InternalEffect.flatMap(InternalEffect.contex
  * Synchronously captures a snapshot of all registered metrics using the provided
  * service context.
  *
+ * **Details**
+ *
  * This is the "unsafe" version that bypasses Effect's safety guarantees and requires
  * manual handling of the services context. Use the safe `snapshot` function for normal
  * application code.
@@ -4426,6 +4507,8 @@ const attributesToString = (attributes: Metric.AttributeSet): string => {
  * A helper method to create histogram bucket boundaries from an iterable set
  * of values.
  *
+ * **Details**
+ *
  * Processes any iterable of numbers by removing duplicates, filtering out
  * non-positive values, and automatically appending positive infinity as the
  * final boundary.
@@ -4496,6 +4579,7 @@ export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArra
  * positive infinity.
  *
  * **Details**
+ *
  * Generates `count - 1` finite boundaries using `start + width + index` for
  * each zero-based index, then applies the same normalization as
  * `boundariesFromIterable`: non-positive values are removed, duplicates are
@@ -4549,6 +4633,8 @@ export const linearBoundaries = (options: {
  * A helper method to create histogram bucket boundaries with exponentially
  * increasing values.
  *
+ * **Details**
+ *
  * Creates boundaries that grow exponentially, useful for metrics that span
  * multiple orders of magnitude. Each boundary is calculated as start * factor^i.
  *
@@ -4710,6 +4796,7 @@ export interface FiberRuntimeMetricsService {
  * `Context.Reference` for the optional fiber runtime metrics service.
  *
  * **Details**
+ *
  * When provided, the runtime can notify the service about child-fiber start and
  * end events. When the reference is `undefined`, automatic fiber runtime metric
  * collection is disabled.
@@ -4826,6 +4913,8 @@ export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
  * A Layer that enables automatic collection of fiber runtime metrics across
  * an entire Effect application.
  *
+ * **When to use**
+ *
  * Unlike the function version which wraps individual Effects, this layer provides
  * runtime metrics collection to all Effects in the application context. This is
  * the recommended approach for production applications that need comprehensive
@@ -4966,6 +5055,8 @@ export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(und
 /**
  * Enables automatic collection of fiber runtime metrics for the provided Effect.
  *
+ * **Details**
+ *
  * When enabled, automatically tracks fiber lifecycle metrics including active fibers,
  * started fibers, successful completions, and failures. These metrics provide valuable
  * insights into the concurrency patterns and health of your Effect application.
@@ -5051,6 +5142,8 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
 /**
  * Disables automatic collection of fiber runtime metrics for the provided Effect.
  *
+ * **When to use**
+ *
  * 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.

package/src/MutableHashMap.ts

@@ -40,6 +40,8 @@ const TypeId = "~effect/collections/MutableHashMap"
  * A mutable hash map that stores key-value pairs and supports both referential
  * and Effect structural equality.
  *
+ * **Details**
+ *
  * Operations mutate the map in place. Keys that implement `Equal` / `Hash` can
  * be looked up structurally; other keys use normal JavaScript reference or
  * primitive equality.
@@ -202,6 +204,8 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
 /**
  * Looks up a key in the `MutableHashMap`.
  *
+ * **Details**
+ *
  * Returns `Some(value)` when an equal key is present and `None` when the key is
  * absent.
  *
@@ -227,6 +231,8 @@ export const get: {
   /**
    * Looks up a key in the `MutableHashMap`.
    *
+   * **Details**
+   *
    * Returns `Some(value)` when an equal key is present and `None` when the key is
    * absent.
    *
@@ -252,6 +258,8 @@ export const get: {
   /**
    * Looks up a key in the `MutableHashMap`.
    *
+   * **Details**
+   *
    * Returns `Some(value)` when an equal key is present and `None` when the key is
    * absent.
    *
@@ -278,6 +286,8 @@ export const get: {
   /**
    * Looks up a key in the `MutableHashMap`.
    *
+   * **Details**
+   *
    * Returns `Some(value)` when an equal key is present and `None` when the key is
    * absent.
    *
@@ -303,6 +313,8 @@ export const get: {
   /**
    * Looks up a key in the `MutableHashMap`.
    *
+   * **Details**
+   *
    * Returns `Some(value)` when an equal key is present and `None` when the key is
    * absent.
    *
@@ -1455,6 +1467,8 @@ export const isEmpty = <K, V>(self: MutableHashMap<K, V>): boolean => self.backi
 /**
  * Runs a callback for each key-value pair in the `MutableHashMap`.
  *
+ * **Details**
+ *
  * Iteration follows the backing map's order. The callback receives the value
  * first and the key second, matching `Map.prototype.forEach`.
  *
@@ -1465,6 +1479,8 @@ export const forEach: {
   /**
    * Runs a callback for each key-value pair in the `MutableHashMap`.
    *
+   * **Details**
+   *
    * Iteration follows the backing map's order. The callback receives the value
    * first and the key second, matching `Map.prototype.forEach`.
    *
@@ -1475,6 +1491,8 @@ export const forEach: {
   /**
    * Runs a callback for each key-value pair in the `MutableHashMap`.
    *
+   * **Details**
+   *
    * Iteration follows the backing map's order. The callback receives the value
    * first and the key second, matching `Map.prototype.forEach`.
    *

package/src/MutableHashSet.ts

@@ -84,6 +84,8 @@ const TypeId = "~effect/collections/MutableHashSet"
  * A mutable hash set for storing unique values with Effect structural equality
  * support.
  *
+ * **Details**
+ *
  * Operations mutate the set in place. Values that implement `Equal` / `Hash`
  * can be de-duplicated structurally; other values use normal JavaScript
  * reference or primitive equality.

package/src/MutableList.ts

@@ -129,6 +129,8 @@ export declare namespace MutableList {
    * Storage node used by the exposed `head` and `tail` fields of a
    * `MutableList`.
    *
+   * **Details**
+   *
    * Most code should treat buckets as an implementation detail and use
    * `MutableList` operations such as `append`, `prepend`, and `take` instead
    * of constructing or mutating buckets directly.
@@ -420,8 +422,10 @@ 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.
  *
- * ⚠️ **Warning**: When mutable=true, the input array may be modified internally.
- * Only use mutable=true when you control the array lifecycle.
+ * **Gotchas**
+ *
+ * When mutable=true, the input array may be modified internally. Only use
+ * mutable=true when you control the array lifecycle.
  *
  * **Example** (Prepending arrays with optional mutation)
  *
@@ -503,8 +507,10 @@ 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.
  *
- * ⚠️ **Warning**: When mutable=true, the input array may be modified internally.
- * Only use mutable=true when you control the array lifecycle.
+ * **Gotchas**
+ *
+ * When mutable=true, the input array may be modified internally. Only use
+ * mutable=true when you control the array lifecycle.
  *
  * **Example** (Appending arrays with optional mutation)
  *
@@ -668,6 +674,8 @@ export const takeN = <A>(self: MutableList<A>, n: number): Array<A> => {
  * Removes up to `n` elements from the beginning of the `MutableList` without
  * returning them.
  *
+ * **Details**
+ *
  * If `n` is less than or equal to zero, or the list is empty, the list is left
  * unchanged. If `n` is greater than or equal to the current length, the list is
  * cleared.
@@ -812,6 +820,8 @@ export const take = <A>(self: MutableList<A>): Empty | A => {
  * Copies up to `n` elements from the beginning of the `MutableList` into a new
  * array without modifying the list.
  *
+ * **When to use**
+ *
  * Use `takeN` when the copied elements should also be removed from the list.
  *
  * @category elements
@@ -836,6 +846,8 @@ export const toArrayN = <A>(self: MutableList<A>, n: number): Array<A> => {
  * Copies all current elements of the `MutableList` into a new array without
  * modifying the list.
  *
+ * **When to use**
+ *
  * Use `takeAll` when the list should be emptied after converting it to an
  * array.
  *
@@ -912,8 +924,14 @@ 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.
  *
- * The list is modified in place. Values are compared with `!==`, so this does
- * not use Effect structural equality.
+ * **Details**
+ *
+ * The list is modified in place.
+ *
+ * **Gotchas**
+ *
+ * Values are compared with `!==`, so this does not use Effect structural
+ * equality.
  *
  * **Example** (Removing matching values)
  *

package/src/MutableRef.ts

@@ -43,6 +43,8 @@ const TypeId = "~effect/MutableRef"
 /**
  * A synchronous mutable reference that stores a current value.
  *
+ * **Details**
+ *
  * Read or write the value directly through `.current`, or use the `MutableRef`
  * helpers for pipeable updates such as `get`, `set`, `update`, and
  * `compareAndSet`. All operations mutate the same reference in place.