effect 3.8.4 → 3.9.0

package/src/Metric.ts

@@ -152,7 +152,23 @@ export const make: MetricApply = internal.make
  * @category mapping
  */
 export const mapInput: {
+  /**
+   * Returns a new metric that is powered by this one, but which accepts updates
+   * of the specified new type, which must be transformable to the input type of
+   * this metric.
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <In, In2>(f: (input: In2) => In): <Type, Out>(self: Metric<Type, In, Out>) => Metric<Type, In2, Out>
+  /**
+   * Returns a new metric that is powered by this one, but which accepts updates
+   * of the specified new type, which must be transformable to the input type of
+   * this metric.
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <Type, In, Out, In2>(self: Metric<Type, In, Out>, f: (input: In2) => In): Metric<Type, In2, Out>
 } = internal.mapInput
 
@@ -182,6 +198,31 @@ export const mapInput: {
  * @category constructors
  */
 export const counter: {
+  /**
+   * Represents a Counter metric that tracks cumulative numerical values over time.
+   * Counters can be incremented and decremented and provide a running total of changes.
+   *
+   * @param name - The name of the counter metric.
+   * @param options - An optional configuration for the counter:
+   * - description - A description of the counter.
+   * - bigint - Indicates if the counter uses 'bigint' data type.
+   * - incremental - Set to 'true' for a counter that only increases. With this configuration, Effect ensures that non-incremental updates have no impact on the counter, making it exclusively suitable for counting upwards.
+   *
+   * @example
+   * import { Metric } from "effect"
+   *
+   * const numberCounter = Metric.counter("count", {
+   *   description: "A number counter"
+   * });
+   *
+   * const bigintCounter = Metric.counter("count", {
+   *   description: "A bigint counter",
+   *   bigint: true
+   * });
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
   (
     name: string,
     options?: {
@@ -190,6 +231,31 @@ export const counter: {
       readonly incremental?: boolean | undefined
     }
   ): Metric.Counter<number>
+  /**
+   * Represents a Counter metric that tracks cumulative numerical values over time.
+   * Counters can be incremented and decremented and provide a running total of changes.
+   *
+   * @param name - The name of the counter metric.
+   * @param options - An optional configuration for the counter:
+   * - description - A description of the counter.
+   * - bigint - Indicates if the counter uses 'bigint' data type.
+   * - incremental - Set to 'true' for a counter that only increases. With this configuration, Effect ensures that non-incremental updates have no impact on the counter, making it exclusively suitable for counting upwards.
+   *
+   * @example
+   * import { Metric } from "effect"
+   *
+   * const numberCounter = Metric.counter("count", {
+   *   description: "A number counter"
+   * });
+   *
+   * const bigintCounter = Metric.counter("count", {
+   *   description: "A bigint counter",
+   *   bigint: true
+   * });
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
   (
     name: string,
     options: {
@@ -233,7 +299,23 @@ export const frequency: (
  * @category constructors
  */
 export const withConstantInput: {
+  /**
+   * Returns a new metric that is powered by this one, but which accepts updates
+   * of any type, and translates them to updates with the specified constant
+   * update value.
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
   <In>(input: In): <Type, Out>(self: Metric<Type, In, Out>) => Metric<Type, unknown, Out>
+  /**
+   * Returns a new metric that is powered by this one, but which accepts updates
+   * of any type, and translates them to updates with the specified constant
+   * update value.
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
   <Type, In, Out>(self: Metric<Type, In, Out>, input: In): Metric<Type, unknown, Out>
 } = internal.withConstantInput
 
@@ -271,14 +353,68 @@ export const fromMetricKey: <Type extends MetricKeyType.MetricKeyType<any, any>>
  * @category constructors
  */
 export const gauge: {
-  (name: string, options?: {
-    readonly description?: string | undefined
-    readonly bigint?: false | undefined
-  }): Metric.Gauge<number>
-  (name: string, options: {
-    readonly description?: string | undefined
-    readonly bigint: true
-  }): Metric.Gauge<bigint>
+  /**
+   * Represents a Gauge metric that tracks and reports a single numerical value at a specific moment.
+   * Gauges are suitable for metrics that represent instantaneous values, such as memory usage or CPU load.
+   *
+   * @param name - The name of the gauge metric.
+   * @param options - An optional configuration for the gauge:
+   * - description - A description of the gauge metric.
+   * - bigint - Indicates if the counter uses 'bigint' data type.
+   *
+   * @example
+   * import { Metric } from "effect"
+   *
+   * const numberGauge = Metric.gauge("memory_usage", {
+   *   description: "A gauge for memory usage"
+   * });
+   *
+   * const bigintGauge = Metric.gauge("cpu_load", {
+   *   description: "A gauge for CPU load",
+   *   bigint: true
+   * });
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
+  (
+    name: string,
+    options?: {
+      readonly description?: string | undefined
+      readonly bigint?: false | undefined
+    }
+  ): Metric.Gauge<number>
+  /**
+   * Represents a Gauge metric that tracks and reports a single numerical value at a specific moment.
+   * Gauges are suitable for metrics that represent instantaneous values, such as memory usage or CPU load.
+   *
+   * @param name - The name of the gauge metric.
+   * @param options - An optional configuration for the gauge:
+   * - description - A description of the gauge metric.
+   * - bigint - Indicates if the counter uses 'bigint' data type.
+   *
+   * @example
+   * import { Metric } from "effect"
+   *
+   * const numberGauge = Metric.gauge("memory_usage", {
+   *   description: "A gauge for memory usage"
+   * });
+   *
+   * const bigintGauge = Metric.gauge("cpu_load", {
+   *   description: "A gauge for CPU load",
+   *   bigint: true
+   * });
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
+  (
+    name: string,
+    options: {
+      readonly description?: string | undefined
+      readonly bigint: true
+    }
+  ): Metric.Gauge<bigint>
 } = internal.gauge
 
 /**
@@ -319,9 +455,25 @@ export const increment: (
  * @category combinators
  */
 export const incrementBy: {
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   (amount: number): (self: Metric.Counter<number> | Metric.Counter<number>) => Effect.Effect<void>
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   (amount: bigint): (self: Metric.Counter<bigint> | Metric.Gauge<bigint>) => Effect.Effect<void>
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   (self: Metric.Counter<number> | Metric.Gauge<number>, amount: number): Effect.Effect<void>
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   (self: Metric.Counter<bigint> | Metric.Gauge<bigint>, amount: bigint): Effect.Effect<void>
 } = internal.incrementBy
 
@@ -334,7 +486,23 @@ export const incrementBy: {
  * @category mapping
  */
 export const map: {
+  /**
+   * Returns a new metric that is powered by this one, but which outputs a new
+   * state type, determined by transforming the state type of this metric by the
+   * specified function.
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <Out, Out2>(f: (out: Out) => Out2): <Type, In>(self: Metric<Type, In, Out>) => Metric<Type, In, Out2>
+  /**
+   * Returns a new metric that is powered by this one, but which outputs a new
+   * state type, determined by transforming the state type of this metric by the
+   * specified function.
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <Type, In, Out, Out2>(self: Metric<Type, In, Out>, f: (out: Out) => Out2): Metric<Type, In, Out2>
 } = internal.map
 
@@ -343,7 +511,15 @@ export const map: {
  * @category mapping
  */
 export const mapType: {
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <Type, Type2>(f: (type: Type) => Type2): <In, Out>(self: Metric<Type, In, Out>) => Metric<Type2, In, Out>
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <Type, In, Out, Type2>(self: Metric<Type, In, Out>, f: (type: Type) => Type2): Metric<Type2, In, Out>
 } = internal.mapType
 
@@ -356,7 +532,23 @@ export const mapType: {
  * @category utils
  */
 export const modify: {
+  /**
+   * Modifies the metric with the specified update message. For example, if the
+   * metric were a gauge, the update would increment the method by the provided
+   * amount.
+   *
+   * @since 3.6.5
+   * @category utils
+   */
   <In>(input: In): <Type, Out>(self: Metric<Type, In, Out>) => Effect.Effect<void>
+  /**
+   * Modifies the metric with the specified update message. For example, if the
+   * metric were a gauge, the update would increment the method by the provided
+   * amount.
+   *
+   * @since 3.6.5
+   * @category utils
+   */
   <Type, In, Out>(self: Metric<Type, In, Out>, input: In): Effect.Effect<void>
 } = internal.modify
 
@@ -365,9 +557,25 @@ export const modify: {
  * @category aspects
  */
 export const set: {
+  /**
+   * @since 2.0.0
+   * @category aspects
+   */
   (value: number): (self: Metric.Gauge<number>) => Effect.Effect<void>
+  /**
+   * @since 2.0.0
+   * @category aspects
+   */
   (value: bigint): (self: Metric.Gauge<bigint>) => Effect.Effect<void>
+  /**
+   * @since 2.0.0
+   * @category aspects
+   */
   (self: Metric.Gauge<number>, value: number): Effect.Effect<void>
+  /**
+   * @since 2.0.0
+   * @category aspects
+   */
   (self: Metric.Gauge<bigint>, value: bigint): Effect.Effect<void>
 } = internal.set
 
@@ -457,7 +665,21 @@ export const summaryTimestamp: (
  * @category utils
  */
 export const tagged: {
+  /**
+   * Returns a new metric, which is identical in every way to this one, except
+   * the specified tags have been added to the tags of this metric.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <Type, In, Out>(key: string, value: string): (self: Metric<Type, In, Out>) => Metric<Type, In, Out>
+  /**
+   * Returns a new metric, which is identical in every way to this one, except
+   * the specified tags have been added to the tags of this metric.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <Type, In, Out>(self: Metric<Type, In, Out>, key: string, value: string): Metric<Type, In, Out>
 } = internal.tagged
 
@@ -471,9 +693,27 @@ export const tagged: {
  * @category utils
  */
 export const taggedWithLabelsInput: {
+  /**
+   * Returns a new metric, which is identical in every way to this one, except
+   * dynamic tags are added based on the update values. Note that the metric
+   * returned by this method does not return any useful information, due to the
+   * dynamic nature of the added tags.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <In>(
     f: (input: In) => Iterable<MetricLabel.MetricLabel>
   ): <Type, Out>(self: Metric<Type, In, Out>) => Metric<Type, In, void>
+  /**
+   * Returns a new metric, which is identical in every way to this one, except
+   * dynamic tags are added based on the update values. Note that the metric
+   * returned by this method does not return any useful information, due to the
+   * dynamic nature of the added tags.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <Type, In, Out>(
     self: Metric<Type, In, Out>,
     f: (input: In) => Iterable<MetricLabel.MetricLabel>
@@ -488,7 +728,21 @@ export const taggedWithLabelsInput: {
  * @category utils
  */
 export const taggedWithLabels: {
+  /**
+   * Returns a new metric, which is identical in every way to this one, except
+   * the specified tags have been added to the tags of this metric.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <Type, In, Out>(extraTags: Iterable<MetricLabel.MetricLabel>): (self: Metric<Type, In, Out>) => Metric<Type, In, Out>
+  /**
+   * Returns a new metric, which is identical in every way to this one, except
+   * the specified tags have been added to the tags of this metric.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <Type, In, Out>(self: Metric<Type, In, Out>, extraTags: Iterable<MetricLabel.MetricLabel>): Metric<Type, In, Out>
 } = internal.taggedWithLabels
 
@@ -531,9 +785,25 @@ export const timerWithBoundaries: (
  * @category aspects
  */
 export const trackAll: {
+  /**
+   * Returns an aspect that will update this metric with the specified constant
+   * value every time the aspect is applied to an effect, regardless of whether
+   * that effect fails or succeeds.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <In>(
     input: In
   ): <Type, Out>(self: Metric<Type, In, Out>) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the specified constant
+   * value every time the aspect is applied to an effect, regardless of whether
+   * that effect fails or succeeds.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, In, Out>(
     self: Metric<Type, In, Out>,
     input: In
@@ -548,7 +818,21 @@ export const trackAll: {
  * @category aspects
  */
 export const trackDefect: {
+  /**
+   * Returns an aspect that will update this metric with the defects of the
+   * effects that it is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, Out>(metric: Metric<Type, unknown, Out>): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the defects of the
+   * effects that it is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A, E, R, Type, Out>(self: Effect.Effect<A, E, R>, metric: Metric<Type, unknown, Out>): Effect.Effect<A, E, R>
 } = internal.trackDefect
 
@@ -561,10 +845,26 @@ export const trackDefect: {
  * @category aspects
  */
 export const trackDefectWith: {
+  /**
+   * Returns an aspect that will update this metric with the result of applying
+   * the specified function to the defect throwables of the effects that the
+   * aspect is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, In, Out>(
     metric: Metric<Type, In, Out>,
     f: (defect: unknown) => In
   ): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the result of applying
+   * the specified function to the defect throwables of the effects that the
+   * aspect is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A, E, R, Type, In, Out>(
     self: Effect.Effect<A, E, R>,
     metric: Metric<Type, In, Out>,
@@ -581,9 +881,25 @@ export const trackDefectWith: {
  * @category aspects
  */
 export const trackDuration: {
+  /**
+   * Returns an aspect that will update this metric with the duration that the
+   * effect takes to execute. To call this method, the input type of the metric
+   * must be `Duration`.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, Out>(
     metric: Metric<Type, Duration.Duration, Out>
   ): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the duration that the
+   * effect takes to execute. To call this method, the input type of the metric
+   * must be `Duration`.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A, E, R, Type, Out>(
     self: Effect.Effect<A, E, R>,
     metric: Metric<Type, Duration.Duration, Out>
@@ -599,10 +915,26 @@ export const trackDuration: {
  * @category aspects
  */
 export const trackDurationWith: {
+  /**
+   * Returns an aspect that will update this metric with the duration that the
+   * effect takes to execute. To call this method, you must supply a function
+   * that can convert the `Duration` to the input type of this metric.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, In, Out>(
     metric: Metric<Type, In, Out>,
     f: (duration: Duration.Duration) => In
   ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the duration that the
+   * effect takes to execute. To call this method, you must supply a function
+   * that can convert the `Duration` to the input type of this metric.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A, E, R, Type, In, Out>(
     self: Effect.Effect<A, E, R>,
     metric: Metric<Type, In, Out>,
@@ -618,9 +950,23 @@ export const trackDurationWith: {
  * @category aspects
  */
 export const trackError: {
+  /**
+   * Returns an aspect that will update this metric with the failure value of
+   * the effects that it is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, In, Out>(
     metric: Metric<Type, In, Out>
   ): <A, E extends In, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the failure value of
+   * the effects that it is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A, E extends In, R, Type, In, Out>(
     self: Effect.Effect<A, E, R>,
     metric: Metric<Type, In, Out>
@@ -636,10 +982,26 @@ export const trackError: {
  * @category aspects
  */
 export const trackErrorWith: {
+  /**
+   * Returns an aspect that will update this metric with the result of applying
+   * the specified function to the error value of the effects that the aspect is
+   * applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, In, Out, In2>(
     metric: Metric<Type, In, Out>,
     f: (error: In2) => In
   ): <A, E extends In2, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the result of applying
+   * the specified function to the error value of the effects that the aspect is
+   * applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A, E extends In2, R, Type, In, Out, In2>(
     self: Effect.Effect<A, E, R>,
     metric: Metric<Type, In, Out>,
@@ -655,9 +1017,23 @@ export const trackErrorWith: {
  * @category aspects
  */
 export const trackSuccess: {
+  /**
+   * Returns an aspect that will update this metric with the success value of
+   * the effects that it is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, In, Out>(
     metric: Metric<Type, In, Out>
   ): <A extends In, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the success value of
+   * the effects that it is applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A extends In, E, R, Type, In, Out>(
     self: Effect.Effect<A, E, R>,
     metric: Metric<Type, In, Out>
@@ -673,10 +1049,26 @@ export const trackSuccess: {
  * @category aspects
  */
 export const trackSuccessWith: {
+  /**
+   * Returns an aspect that will update this metric with the result of applying
+   * the specified function to the success value of the effects that the aspect is
+   * applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <Type, In, Out, In2>(
     metric: Metric<Type, In, Out>,
     f: (value: In2) => In
   ): <A extends In2, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Returns an aspect that will update this metric with the result of applying
+   * the specified function to the success value of the effects that the aspect is
+   * applied to.
+   *
+   * @since 2.0.0
+   * @category aspects
+   */
   <A extends In2, E, R, Type, In, Out, In2>(
     self: Effect.Effect<A, E, R>,
     metric: Metric<Type, In, Out>,
@@ -693,7 +1085,23 @@ export const trackSuccessWith: {
  * @category utils
  */
 export const update: {
+  /**
+   * Updates the metric with the specified update message. For example, if the
+   * metric were a counter, the update would increment the method by the
+   * provided amount.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <In>(input: In): <Type, Out>(self: Metric<Type, In, Out>) => Effect.Effect<void>
+  /**
+   * Updates the metric with the specified update message. For example, if the
+   * metric were a counter, the update would increment the method by the
+   * provided amount.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <Type, In, Out>(self: Metric<Type, In, Out>, input: In): Effect.Effect<void>
 } = internal.update
 
@@ -717,19 +1125,22 @@ export const withNow: <Type, In, Out>(self: Metric<Type, readonly [In, number],
  * @category zipping
  */
 export const zip: {
-  <Type2, In2, Out2>(
-    that: Metric<Type2, In2, Out2>
-  ): <Type, In, Out>(
+  /**
+   * @since 2.0.0
+   * @category zipping
+   */
+  <Type2, In2, Out2>(that: Metric<Type2, In2, Out2>): <Type, In, Out>(
     self: Metric<Type, In, Out>
   ) => Metric<
     readonly [Type, Type2], // readonly because invariant
     readonly [In, In2], // readonly because contravariant
     [Out, Out2]
   >
-  <Type, In, Out, Type2, In2, Out2>(
-    self: Metric<Type, In, Out>,
-    that: Metric<Type2, In2, Out2>
-  ): Metric<
+  /**
+   * @since 2.0.0
+   * @category zipping
+   */
+  <Type, In, Out, Type2, In2, Out2>(self: Metric<Type, In, Out>, that: Metric<Type2, In2, Out2>): Metric<
     readonly [Type, Type2], // readonly because invariant
     readonly [In, In2], // readonly because contravariant
     [Out, Out2]

package/src/MetricHook.ts

@@ -116,7 +116,15 @@ export const frequency: (_key: MetricKey.MetricKey.Frequency) => MetricHook.Freq
  * @category constructors
  */
 export const gauge: {
+  /**
+   * @since 2.0.0
+   * @category constructors
+   */
   (key: MetricKey.MetricKey.Gauge<number>, startAt: number): MetricHook.Gauge<number>
+  /**
+   * @since 2.0.0
+   * @category constructors
+   */
   (key: MetricKey.MetricKey.Gauge<bigint>, startAt: bigint): MetricHook.Gauge<bigint>
 } = internal.gauge
 
@@ -137,7 +145,15 @@ export const summary: (key: MetricKey.MetricKey.Summary) => MetricHook.Summary =
  * @category utils
  */
 export const onUpdate: {
+  /**
+   * @since 2.0.0
+   * @category utils
+   */
   <In, Out>(f: (input: In) => void): (self: MetricHook<In, Out>) => MetricHook<In, Out>
+  /**
+   * @since 2.0.0
+   * @category utils
+   */
   <In, Out>(self: MetricHook<In, Out>, f: (input: In) => void): MetricHook<In, Out>
 } = internal.onUpdate
 
@@ -146,6 +162,14 @@ export const onUpdate: {
  * @category utils
  */
 export const onModify: {
+  /**
+   * @since 3.6.5
+   * @category utils
+   */
   <In, Out>(f: (input: In) => void): (self: MetricHook<In, Out>) => MetricHook<In, Out>
+  /**
+   * @since 3.6.5
+   * @category utils
+   */
   <In, Out>(self: MetricHook<In, Out>, f: (input: In) => void): MetricHook<In, Out>
 } = internal.onModify