effect 2.0.0-next.47 → 2.0.0-next.49

package/src/Metric.ts

@@ -156,7 +156,26 @@ export const mapInput: {
 } = internal.mapInput
 
 /**
- * A counter, which can be incremented by numbers.
+ * 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 * as Metric from "effect/Metric"
+ *
+ * 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
@@ -181,8 +200,16 @@ export const counter: {
 } = internal.counter
 
 /**
- * A string histogram metric, which keeps track of the counts of different
- * strings.
+ * Creates a Frequency metric to count occurrences of events.
+ * Frequency metrics are used to count the number of times specific events or incidents occur.
+ *
+ * @param name - The name of the Frequency metric.
+ * @param description - An optional description of the Frequency metric.
+ *
+ * @example
+ * import * as Metric from "effect/Metric"
+ *
+ * const errorFrequency = Metric.frequency("error_frequency", "Counts the occurrences of errors.");
  *
  * @since 2.0.0
  * @category constructors
@@ -212,7 +239,25 @@ export const fromMetricKey: <Type extends MetricKeyType.MetricKeyType<any, any>>
   internal.fromMetricKey
 
 /**
- * A gauge, which can be set to a value.
+ * 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 * as Metric from "effect/Metric"
+ *
+ * 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
@@ -223,8 +268,21 @@ export const gauge: {
 } = internal.gauge
 
 /**
- * A numeric histogram metric, which keeps track of the count of numbers that
- * fall in bins with the specified boundaries.
+ * Represents a Histogram metric that records observations in specified value boundaries.
+ * Histogram metrics are useful for measuring the distribution of values within a range.
+ *
+ * @param name - The name of the histogram metric.
+ * @param boundaries - The boundaries for defining the histogram's value ranges.
+ * @param description - A description of the histogram metric.
+ *
+ * @example
+ * import * as Metric from "effect/Metric"
+ * import * as MetricBoundaries from "effect/MetricBoundaries"
+ *
+ * const latencyHistogram = Metric.histogram("latency_histogram",
+ *   MetricBoundaries.linear({ start: 0, width: 10, count: 11 }),
+ *   "Measures the distribution of request latency."
+ * );
  *
  * @since 2.0.0
  * @category constructors
@@ -311,6 +369,30 @@ export const succeed: <Out>(out: Out) => Metric<void, unknown, Out> = internal.s
 export const sync: <Out>(evaluate: LazyArg<Out>) => Metric<void, unknown, Out> = internal.sync
 
 /**
+ * Creates a Summary metric that records observations and calculates quantiles.
+ * Summary metrics provide statistical information about a set of values, including quantiles.
+ *
+ * @param options - An object with configuration options for the Summary metric:
+ * - name - The name of the Summary metric.
+ * - maxAge - The maximum age of observations to retain.
+ * - maxSize - The maximum number of observations to keep.
+ * - error - The error percentage when calculating quantiles.
+ * - quantiles - An `Chunk` of quantiles to calculate (e.g., [0.5, 0.9]).
+ * - description - An optional description of the Summary metric.
+ *
+ * @example
+ * import * as Metric from "effect/Metric"
+ * import * as Chunk from "effect/Chunk"
+ *
+ * const responseTimesSummary = Metric.summary({
+ *   name: "response_times_summary",
+ *   maxAge: "60 seconds", // Retain observations for 60 seconds.
+ *   maxSize: 1000, // Keep a maximum of 1000 observations.
+ *   error: 0.01, // Allow a 1% error when calculating quantiles.
+ *   quantiles: Chunk.make(0.5, 0.9, 0.99), // Calculate 50th, 90th, and 99th percentiles.
+ *   description: "Measures the distribution of response times."
+ * });
+ *
  * @since 2.0.0
  * @category constructors
  */

package/src/Predicate.ts

@@ -110,16 +110,16 @@ export const isBoolean = (input: unknown): input is boolean => typeof input ===
  * @param input - The value to test.
  *
  * @example
- * import { isBigint } from "effect/Predicate"
+ * import { isBigInt } from "effect/Predicate"
  *
- * assert.deepStrictEqual(isBigint(1n), true)
+ * assert.deepStrictEqual(isBigInt(1n), true)
  *
- * assert.deepStrictEqual(isBigint(1), false)
+ * assert.deepStrictEqual(isBigInt(1), false)
  *
  * @category guards
  * @since 2.0.0
  */
-export const isBigint = (input: unknown): input is bigint => typeof input === "bigint"
+export const isBigInt = (input: unknown): input is bigint => typeof input === "bigint"
 
 /**
  * Tests if a value is a `symbol`.

package/src/Stream.ts

@@ -4000,10 +4000,11 @@ export const withSpan: {
   (
     name: string,
     options?: {
-      readonly attributes?: Record<string, Tracer.AttributeValue>
+      readonly attributes?: Record<string, unknown>
       readonly links?: ReadonlyArray<Tracer.SpanLink>
       readonly parent?: Tracer.ParentSpan
       readonly root?: boolean
+      readonly sampled?: boolean
       readonly context?: Context.Context<never>
     }
   ): <R, E, A>(self: Stream<R, E, A>) => Stream<R, E, A>
@@ -4011,10 +4012,11 @@ export const withSpan: {
     self: Stream<R, E, A>,
     name: string,
     options?: {
-      readonly attributes?: Record<string, Tracer.AttributeValue>
+      readonly attributes?: Record<string, unknown>
       readonly links?: ReadonlyArray<Tracer.SpanLink>
       readonly parent?: Tracer.ParentSpan
       readonly root?: boolean
+      readonly sampled?: boolean
       readonly context?: Context.Context<never>
     }
   ): Stream<R, E, A>

package/src/TRef.ts

@@ -53,7 +53,7 @@ export interface TRef<A> {
 /**
  * @since 2.0.0
  */
-export namespace TRef {
+export declare namespace TRef {
   /**
    * @since 2.0.0
    */

package/src/Tracer.ts

@@ -29,6 +29,7 @@ export interface Tracer {
     parent: Option.Option<ParentSpan>,
     context: Context.Context<never>,
     links: ReadonlyArray<SpanLink>,
+    sampled: boolean,
     startTime: bigint
   ) => Span
   readonly context: <X>(f: () => X, fiber: Fiber.RuntimeFiber<any, any>) => X
@@ -62,6 +63,7 @@ export interface ExternalSpan {
   readonly _tag: "ExternalSpan"
   readonly spanId: string
   readonly traceId: string
+  readonly sampled: boolean
   readonly context: Context.Context<never>
 }
 
@@ -77,17 +79,13 @@ export interface Span {
   readonly parent: Option.Option<ParentSpan>
   readonly context: Context.Context<never>
   readonly status: SpanStatus
-  readonly attributes: ReadonlyMap<string, AttributeValue>
+  readonly attributes: ReadonlyMap<string, unknown>
   readonly links: ReadonlyArray<SpanLink>
+  readonly sampled: boolean
   readonly end: (endTime: bigint, exit: Exit.Exit<unknown, unknown>) => void
-  readonly attribute: (key: string, value: AttributeValue) => void
-  readonly event: (name: string, startTime: bigint, attributes?: Record<string, AttributeValue>) => void
+  readonly attribute: (key: string, value: unknown) => void
+  readonly event: (name: string, startTime: bigint, attributes?: Record<string, unknown>) => void
 }
-/**
- * @since 2.0.0
- * @category models
- */
-export type AttributeValue = string | boolean | number
 
 /**
  * @since 2.0.0
@@ -96,7 +94,7 @@ export type AttributeValue = string | boolean | number
 export interface SpanLink {
   readonly _tag: "SpanLink"
   readonly span: ParentSpan
-  readonly attributes: Readonly<Record<string, AttributeValue>>
+  readonly attributes: Readonly<Record<string, unknown>>
 }
 
 /**
@@ -111,6 +109,17 @@ export const Tracer: Context.Tag<Tracer, Tracer> = internal.tracerTag
  */
 export const make: (options: Omit<Tracer, typeof TracerTypeId>) => Tracer = internal.make
 
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const externalSpan: (options: {
+  readonly spanId: string
+  readonly traceId: string
+  readonly sampled?: boolean | undefined
+  readonly context?: Context.Context<never> | undefined
+}) => ExternalSpan = internal.externalSpan
+
 /**
  * @since 2.0.0
  * @category constructors

package/src/index.ts

@@ -36,7 +36,7 @@ export {
  *
  * @since 2.0.0
  */
-export * as Bigint from "effect/Bigint"
+export * as BigInt from "effect/BigInt"
 
 /**
  * This module provides utility functions and type class instances for working with the `boolean` type in TypeScript.
@@ -388,6 +388,11 @@ export * as LogSpan from "effect/LogSpan"
  */
 export * as Logger from "effect/Logger"
 
+/**
+ * @since 1.0.0
+ */
+export * as Match from "effect/Match"
+
 /**
  * @since 2.0.0
  */

package/src/internal/cause.ts

@@ -59,7 +59,7 @@ const proto = {
         return { _id: "Cause", _tag: this._tag, failure: toJSON(this.error) }
       case "Sequential":
       case "Parallel":
-        return { _id: "Cause", _tag: this._tag, errors: toJSON(prettyErrors(this)) }
+        return { _id: "Cause", _tag: this._tag, left: toJSON(this.left), right: toJSON(this.right) }
     }
   },
   toString<E>(this: Cause.Cause<E>) {

package/src/internal/channel.ts

@@ -1176,6 +1176,7 @@ export const mergeAllWith = (
 > =>
   pipe(
     Effect.gen(function*($) {
+      const concurrencyN = concurrency === "unbounded" ? Number.MAX_SAFE_INTEGER : concurrency
       const input = yield* $(singleProducerAsyncInput.make<
         InErr & InErr1,
         InElem & InElem1,
@@ -1196,9 +1197,8 @@ export const mergeAllWith = (
       )
       const lastDone = yield* $(Ref.make<Option.Option<OutDone>>(Option.none()))
       const errorSignal = yield* $(Deferred.make<never, void>())
-      const withPermits = concurrency === "unbounded" ?
-        ((_: number) => identity) :
-        (yield* $(Effect.makeSemaphore(concurrency))).withPermits
+      const withPermits = (yield* $(Effect.makeSemaphore(concurrencyN)))
+        .withPermits
       const pull = yield* $(toPull(channels))
       const evaluatePull = (
         pull: Effect.Effect<Env | Env1, OutErr | OutErr1, Either.Either<OutDone, OutElem>>
@@ -1216,23 +1216,21 @@ export const mergeAllWith = (
             })
           ),
           Effect.repeatUntil(Option.isSome),
-          Effect.flatMap(Option.match({
-            onNone: () => Effect.unit,
-            onSome: (outDone) =>
-              Ref.update(
-                lastDone,
-                Option.match({
-                  onNone: () => Option.some(outDone),
-                  onSome: (lastDone) => Option.some(f(lastDone, outDone))
-                })
-              )
-          })),
+          Effect.flatMap((outDone) =>
+            Ref.update(
+              lastDone,
+              Option.match({
+                onNone: () => Option.some(outDone.value),
+                onSome: (lastDone) => Option.some(f(lastDone, outDone.value))
+              })
+            )
+          ),
           Effect.catchAllCause((cause) =>
             Cause.isInterrupted(cause) ?
               Effect.failCause(cause) :
               pipe(
                 Queue.offer(queue, Effect.failCause(cause)),
-                Effect.zipRight(Deferred.succeed<never, void>(errorSignal, void 0)),
+                Effect.zipRight(Deferred.succeed(errorSignal, void 0)),
                 Effect.asUnit
               )
           )
@@ -1246,88 +1244,83 @@ export const mergeAllWith = (
             ),
           onSuccess: Either.match({
             onLeft: (outDone) =>
-              Effect.raceWith(Deferred.await(errorSignal), withPermits(concurrency as number)(Effect.unit), {
-                onSelfDone: (_, permitAcquisition) => pipe(Fiber.interrupt(permitAcquisition), Effect.as(false)),
+              Effect.raceWith(Deferred.await(errorSignal), withPermits(concurrencyN)(Effect.unit), {
+                onSelfDone: (_, permitAcquisition) => Effect.as(Fiber.interrupt(permitAcquisition), false),
                 onOtherDone: (_, failureAwait) =>
-                  pipe(
+                  Effect.zipRight(
                     Fiber.interrupt(failureAwait),
-                    Effect.zipRight(
-                      pipe(
-                        Ref.get(lastDone),
-                        Effect.flatMap(Option.match({
-                          onNone: () => Queue.offer(queue, Effect.succeed(Either.left(outDone))),
-                          onSome: (lastDone) => Queue.offer(queue, Effect.succeed(Either.left(f(lastDone, outDone))))
-                        })),
-                        Effect.as(false)
-                      )
+                    pipe(
+                      Ref.get(lastDone),
+                      Effect.flatMap(Option.match({
+                        onNone: () => Queue.offer(queue, Effect.succeed(Either.left(outDone))),
+                        onSome: (lastDone) => Queue.offer(queue, Effect.succeed(Either.left(f(lastDone, outDone))))
+                      })),
+                      Effect.as(false)
                     )
                   )
               }),
             onRight: (channel) =>
-              pipe(
-                mergeStrategy,
-                _mergeStrategy.match({
-                  onBackPressure: () =>
-                    Effect.gen(function*($) {
-                      const latch = yield* $(Deferred.make<never, void>())
-                      const raceEffects: Effect.Effect<Env | Env1, OutErr | OutErr1, void> = pipe(
-                        queueReader,
-                        core.pipeTo(channel),
-                        toPull,
-                        Effect.flatMap((pull) =>
-                          pipe(
-                            evaluatePull(pull),
-                            Effect.race(Deferred.await(errorSignal))
-                          )
-                        ),
-                        Effect.scoped
-                      )
-                      yield* $(
-                        Deferred.succeed<never, void>(latch, void 0),
-                        Effect.zipRight(raceEffects),
-                        withPermits(1),
-                        Effect.forkScoped
-                      )
-                      yield* $(Deferred.await(latch))
-                      const errored = yield* $(Deferred.isDone(errorSignal))
-                      return !errored
-                    }),
-                  onBufferSliding: () =>
-                    Effect.gen(function*($) {
-                      const canceler = yield* $(Deferred.make<never, void>())
-                      const latch = yield* $(Deferred.make<never, void>())
-                      const size = yield* $(Queue.size(cancelers))
-                      yield* $(
-                        Queue.take(cancelers),
-                        Effect.flatMap((_) => Deferred.succeed<never, void>(_, void 0)),
-                        Effect.when(() => concurrency === "unbounded" ? false : size >= concurrency)
-                      )
-                      yield* $(Queue.offer(cancelers, canceler))
-                      const raceEffects: Effect.Effect<Env | Env1, OutErr | OutErr1, void> = pipe(
-                        queueReader,
-                        core.pipeTo(channel),
-                        toPull,
-                        Effect.flatMap((pull) =>
-                          pipe(
-                            evaluatePull(pull),
-                            Effect.race(Deferred.await(errorSignal)),
-                            Effect.race(Deferred.await(canceler))
-                          )
-                        ),
-                        Effect.scoped
-                      )
-                      yield* $(
-                        Deferred.succeed<never, void>(latch, void 0),
-                        Effect.zipRight(raceEffects),
-                        withPermits(1),
-                        Effect.forkScoped
-                      )
-                      yield* $(Deferred.await(latch))
-                      const errored = yield* $(Deferred.isDone(errorSignal))
-                      return !errored
-                    })
-                })
-              )
+              _mergeStrategy.match(mergeStrategy, {
+                onBackPressure: () =>
+                  Effect.gen(function*($) {
+                    const latch = yield* $(Deferred.make<never, void>())
+                    const raceEffects: Effect.Effect<Env | Env1, OutErr | OutErr1, void> = pipe(
+                      queueReader,
+                      core.pipeTo(channel),
+                      toPull,
+                      Effect.flatMap((pull) =>
+                        Effect.race(
+                          evaluatePull(pull),
+                          Deferred.await(errorSignal)
+                        )
+                      ),
+                      Effect.scoped
+                    )
+                    yield* $(
+                      Deferred.succeed<never, void>(latch, void 0),
+                      Effect.zipRight(raceEffects),
+                      withPermits(1),
+                      Effect.forkScoped
+                    )
+                    yield* $(Deferred.await(latch))
+                    const errored = yield* $(Deferred.isDone(errorSignal))
+                    return !errored
+                  }),
+                onBufferSliding: () =>
+                  Effect.gen(function*($) {
+                    const canceler = yield* $(Deferred.make<never, void>())
+                    const latch = yield* $(Deferred.make<never, void>())
+                    const size = yield* $(Queue.size(cancelers))
+                    yield* $(
+                      Queue.take(cancelers),
+                      Effect.flatMap((_) => Deferred.succeed<never, void>(_, void 0)),
+                      Effect.when(() => size >= concurrencyN)
+                    )
+                    yield* $(Queue.offer(cancelers, canceler))
+                    const raceEffects: Effect.Effect<Env | Env1, OutErr | OutErr1, void> = pipe(
+                      queueReader,
+                      core.pipeTo(channel),
+                      toPull,
+                      Effect.flatMap((pull) =>
+                        pipe(
+                          evaluatePull(pull),
+                          Effect.race(Deferred.await(errorSignal)),
+                          Effect.race(Deferred.await(canceler))
+                        )
+                      ),
+                      Effect.scoped
+                    )
+                    yield* $(
+                      Deferred.succeed<never, void>(latch, void 0),
+                      Effect.zipRight(raceEffects),
+                      withPermits(1),
+                      Effect.forkScoped
+                    )
+                    yield* $(Deferred.await(latch))
+                    const errored = yield* $(Deferred.isDone(errorSignal))
+                    return !errored
+                  })
+              })
           })
         }),
         Effect.repeatWhile(identity),
@@ -2302,10 +2295,11 @@ export const withSpan = dual<
   (
     name: string,
     options?: {
-      readonly attributes?: Record<string, Tracer.AttributeValue>
+      readonly attributes?: Record<string, unknown>
       readonly links?: ReadonlyArray<Tracer.SpanLink>
       readonly parent?: Tracer.ParentSpan
       readonly root?: boolean
+      readonly sampled?: boolean
       readonly context?: Context.Context<never>
     }
   ) => <Env, InErr, InElem, InDone, OutErr, OutElem, OutDone>(
@@ -2315,14 +2309,15 @@ export const withSpan = dual<
     self: Channel.Channel<Env, InErr, InElem, InDone, OutErr, OutElem, OutDone>,
     name: string,
     options?: {
-      readonly attributes?: Record<string, Tracer.AttributeValue>
+      readonly attributes?: Record<string, unknown>
       readonly links?: ReadonlyArray<Tracer.SpanLink>
       readonly parent?: Tracer.ParentSpan
       readonly root?: boolean
+      readonly sampled?: boolean
       readonly context?: Context.Context<never>
     }
   ) => Channel.Channel<Env, InErr, InElem, InDone, OutErr, OutElem, OutDone>
->(3, (self, name, options) => unwrapScoped(Effect.as(Effect.withSpanScoped(name, options), self)))
+>(3, (self, name, options) => unwrapScoped(Effect.as(Effect.setSpan(name, options), self)))
 
 /** @internal */
 export const writeAll = <OutElem>(