effect 4.0.0-beta.10 → 4.0.0-beta.11

package/src/ErrorReporter.ts

@@ -0,0 +1,459 @@
+/**
+ * Pluggable error reporting for Effect programs.
+ *
+ * Reporting is triggered by `Effect.withErrorReporting`,
+ * `ErrorReporter.report`, or built-in reporting boundaries in the HTTP and
+ * RPC server modules.
+ *
+ * Each reporter receives a structured callback with the failing `Cause`, a
+ * pretty-printed `Error`, severity, and any extra attributes attached to the
+ * original error — making it straightforward to forward failures to Sentry,
+ * Datadog, or a custom logging backend.
+ *
+ * Use the annotation symbols (`ignore`, `severity`, `attributes`) on your
+ * error classes to control reporting behavior per-error.
+ *
+ * @example
+ * ```ts
+ * import { Data, Effect, ErrorReporter } from "effect"
+ *
+ * // A reporter that logs to the console
+ * const consoleReporter = ErrorReporter.make(({ error, severity }) => {
+ *   console.error(`[${severity}]`, error.message)
+ * })
+ *
+ * // An error that should be ignored by reporters
+ * class NotFoundError extends Data.TaggedError("NotFoundError")<{}> {
+ *   readonly [ErrorReporter.ignore] = true
+ * }
+ *
+ * // An error with custom severity and attributes
+ * class RateLimitError extends Data.TaggedError("RateLimitError")<{
+ *   readonly retryAfter: number
+ * }> {
+ *   readonly [ErrorReporter.severity] = "Warn" as const
+ *   readonly [ErrorReporter.attributes] = {
+ *     retryAfter: this.retryAfter
+ *   }
+ * }
+ *
+ * // Opt in to error reporting with Effect.withErrorReporting
+ * const program = Effect.gen(function*() {
+ *   yield* new RateLimitError({ retryAfter: 60 })
+ * }).pipe(
+ *   Effect.withErrorReporting,
+ *   Effect.provide(ErrorReporter.layer([consoleReporter]))
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ */
+import type * as Cause from "./Cause.ts"
+import * as Effect from "./Effect.ts"
+import type * as Fiber from "./Fiber.ts"
+import * as effect from "./internal/effect.ts"
+import * as Layer from "./Layer.ts"
+import * as LogLevel from "./LogLevel.ts"
+import type { Severity } from "./LogLevel.ts"
+import type { ReadonlyRecord } from "./Record.ts"
+import type * as Scope from "./Scope.ts"
+import type * as ServiceMap from "./ServiceMap.ts"
+
+/**
+ * @since 4.0.0
+ * @category Type Identifiers
+ */
+export type TypeId = "~effect/ErrorReporter"
+
+/**
+ * @since 4.0.0
+ * @category Type Identifiers
+ */
+export const TypeId: TypeId = "~effect/ErrorReporter"
+
+/**
+ * An `ErrorReporter` receives reported failures and forwards them to an
+ * external system (logging service, error tracker, etc.).
+ *
+ * Reporting is triggered by `Effect.withErrorReporting`,
+ * `ErrorReporter.report`, or built-in boundaries in the HTTP and RPC server
+ * modules. Use {@link make} to create a reporter — it handles deduplication
+ * and per-error annotation extraction automatically.
+ *
+ * @since 4.0.0
+ * @category Models
+ */
+export interface ErrorReporter {
+  readonly [TypeId]: TypeId
+  report(options: {
+    readonly cause: Cause.Cause<unknown>
+    readonly fiber: Fiber.Fiber<unknown, unknown>
+    readonly timestamp: bigint
+  }): void
+}
+
+/**
+ * Creates an `ErrorReporter` from a callback.
+ *
+ * The returned reporter automatically deduplicates causes and individual
+ * errors (the same object is never reported twice), skips interruptions,
+ * and resolves the `ignore`, `severity`, and `attributes` annotations on
+ * each error before invoking your callback.
+ *
+ * @example
+ * ```ts
+ * import { ErrorReporter } from "effect"
+ *
+ * // Forward every failure to the console
+ * const consoleReporter = ErrorReporter.make(
+ *   ({ error, severity, attributes }) => {
+ *     console.error(`[${severity}]`, error.message, attributes)
+ *   }
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category Constructors
+ */
+export const make = (
+  report: (options: {
+    readonly cause: Cause.Cause<unknown>
+    readonly error: Error
+    readonly attributes: ReadonlyRecord<string, unknown>
+    readonly severity: Severity
+    readonly fiber: Fiber.Fiber<unknown, unknown>
+    readonly timestamp: bigint
+  }) => void
+): ErrorReporter => {
+  const reported = new WeakSet<Cause.Cause<unknown> | object>()
+  return {
+    [TypeId]: TypeId,
+    report(options) {
+      if (reported.has(options.cause)) return
+      reported.add(options.cause)
+      for (let i = 0; i < options.cause.reasons.length; i++) {
+        const reason = options.cause.reasons[i]
+        if (reason._tag === "Interrupt") continue
+        const original = reason._tag === "Fail" ? reason.error : reason.defect
+        const isObject = typeof original === "object" && original !== null
+        if (isObject) {
+          if (reported.has(original)) continue
+          reported.add(original)
+        }
+        if (isIgnored(original)) continue
+        const pretty = effect.causePrettyError(original as any, reason.annotations)
+        report({
+          ...options,
+          error: pretty,
+          severity: isObject ? getSeverity(original) : "Error",
+          attributes: isObject ? getAttributes(original) : emptyAttributes
+        })
+      }
+    }
+  }
+}
+
+/**
+ * A `ServiceMap.Reference` holding the set of active `ErrorReporter`s for the
+ * current fiber. Defaults to an empty set (no reporting).
+ *
+ * Prefer {@link layer} to configure reporters via the `Layer` API. Use this
+ * reference directly only when you need low-level control (e.g. reading the
+ * current reporters or swapping them inside a `FiberRef`).
+ *
+ * @since 4.0.0
+ * @category References
+ */
+export const CurrentErrorReporters: ServiceMap.Reference<ReadonlySet<ErrorReporter>> = effect.CurrentErrorReporters
+
+/**
+ * Creates a `Layer` that registers one or more `ErrorReporter`s.
+ *
+ * Reporters can be plain `ErrorReporter` values or effectful
+ * `Effect<ErrorReporter>` values that are resolved when the layer is built.
+ *
+ * By default the provided reporters **replace** any previously registered
+ * reporters. Set `mergeWithExisting: true` to add them alongside existing
+ * ones.
+ *
+ * @example
+ * ```ts
+ * import { Effect, ErrorReporter } from "effect"
+ *
+ * const consoleReporter = ErrorReporter.make(({ error, severity }) => {
+ *   console.error(`[${severity}]`, error.message)
+ * })
+ *
+ * const metricsReporter = ErrorReporter.make(({ severity }) => {
+ *   // increment an error counter by severity
+ * })
+ *
+ * // Replace all existing reporters
+ * const ReporterLive = ErrorReporter.layer([
+ *   consoleReporter,
+ *   metricsReporter
+ * ])
+ *
+ * // Add to existing reporters instead of replacing
+ * const ReporterMerged = ErrorReporter.layer(
+ *   [metricsReporter],
+ *   { mergeWithExisting: true }
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* Effect.fail("boom")
+ * }).pipe(
+ *   Effect.withErrorReporting,
+ *   Effect.provide(ReporterLive)
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category Layers
+ */
+export const layer = <
+  const Reporters extends ReadonlyArray<ErrorReporter | Effect.Effect<ErrorReporter, any, any>>
+>(
+  reporters: Reporters,
+  options?: { readonly mergeWithExisting?: boolean | undefined } | undefined
+): Layer.Layer<
+  never,
+  Reporters extends readonly [] ? never : Effect.Error<Reporters[number]>,
+  Exclude<
+    Reporters extends readonly [] ? never : Effect.Services<Reporters[number]>,
+    Scope.Scope
+  >
+> =>
+  Layer.effect(
+    CurrentErrorReporters,
+    Effect.withFiber(Effect.fnUntraced(function*(fiber) {
+      const currentReporters = new Set(
+        options?.mergeWithExisting === true ? fiber.getRef(effect.CurrentErrorReporters) : []
+      )
+      for (const reporter of reporters) {
+        currentReporters.add(Effect.isEffect(reporter) ? yield* reporter : reporter)
+      }
+      return currentReporters
+    }))
+  )
+
+/**
+ * Manually report a `Cause` to all registered `ErrorReporter`s on the
+ * current fiber.
+ *
+ * This is useful when you want to report an error for observability without
+ * actually failing the fiber.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect, ErrorReporter } from "effect"
+ *
+ * // Log the cause for monitoring, then continue with a fallback
+ * const program = Effect.gen(function*() {
+ *   const cause = Cause.fail("something went wrong")
+ *   yield* ErrorReporter.report(cause)
+ *   return "fallback value"
+ * })
+ * ```
+ *
+ * @since 4.0.0
+ * @category Reporting
+ */
+export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
+  Effect.withFiber((fiber) => {
+    effect.reportCauseUnsafe(fiber, cause)
+    return Effect.void
+  })
+
+/**
+ * Interface that errors can implement to control reporting behavior.
+ *
+ * All three annotation properties are optional:
+ * - `[ErrorReporter.ignore]` — when `true`, the error is never reported
+ * - `[ErrorReporter.severity]` — overrides the default `"Error"` severity
+ * - `[ErrorReporter.attributes]` — extra key/value pairs forwarded to reporters
+ *
+ * The global `Error` interface is augmented with `Reportable`, so these
+ * properties are available on all `Error` instances.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export interface Reportable {
+  readonly [ignore]?: boolean
+  readonly [severity]?: Severity
+  readonly [attributes]?: ReadonlyRecord<string, unknown>
+}
+
+declare global {
+  interface Error extends Reportable {}
+}
+
+/**
+ * Symbol key used to mark an error as unreportable.
+ *
+ * Set this property to `true` on any error class to prevent it from being
+ * forwarded to reporters. Useful for expected errors such as HTTP 404s.
+ *
+ * @example
+ * ```ts
+ * import { Data, ErrorReporter } from "effect"
+ *
+ * class NotFoundError extends Data.TaggedError("NotFoundError")<{}> {
+ *   readonly [ErrorReporter.ignore] = true
+ * }
+ * ```
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export type ignore = "~effect/ErrorReporter/ignore"
+
+/**
+ * Symbol key used to mark an error as unreportable.
+ *
+ * Set this property to `true` on any error class to prevent it from being
+ * forwarded to reporters. Useful for expected errors such as HTTP 404s.
+ *
+ * @example
+ * ```ts
+ * import { Data, ErrorReporter } from "effect"
+ *
+ * class NotFoundError extends Data.TaggedError("NotFoundError")<{}> {
+ *   readonly [ErrorReporter.ignore] = true
+ * }
+ * ```
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const ignore: ignore = "~effect/ErrorReporter/ignore"
+
+/**
+ * Returns `true` if the given value has the `ErrorReporter.ignore` annotation
+ * set to `true`.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const isIgnored = (u: unknown): boolean =>
+  typeof u === "object" && u !== null && ignore in u && u[ignore] === true
+
+/**
+ * Symbol key used to override the severity level of an error.
+ *
+ * When set, the reporter callback receives this value as `severity` instead
+ * of the default `"Error"`. Accepted values are the `LogLevel.Severity`
+ * literals: `"Trace"`, `"Debug"`, `"Info"`, `"Warn"`, `"Error"`, `"Fatal"`.
+ *
+ * @example
+ * ```ts
+ * import { Data, ErrorReporter } from "effect"
+ *
+ * class DeprecationWarning extends Data.TaggedError("DeprecationWarning")<{}> {
+ *   readonly [ErrorReporter.severity] = "Warn" as const
+ * }
+ * ```
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export type severity = "~effect/ErrorReporter/severity"
+
+/**
+ * Symbol key used to override the severity level of an error.
+ *
+ * When set, the reporter callback receives this value as `severity` instead
+ * of the default `"Error"`. Accepted values are the `LogLevel.Severity`
+ * literals: `"Trace"`, `"Debug"`, `"Info"`, `"Warn"`, `"Error"`, `"Fatal"`.
+ *
+ * @example
+ * ```ts
+ * import { Data, ErrorReporter } from "effect"
+ *
+ * class DeprecationWarning extends Data.TaggedError("DeprecationWarning")<{}> {
+ *   readonly [ErrorReporter.severity] = "Warn" as const
+ * }
+ * ```
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const severity: severity = "~effect/ErrorReporter/severity"
+
+/**
+ * Reads the `ErrorReporter.severity` annotation from an error object,
+ * falling back to `"Error"` when unset or invalid.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const getSeverity = (error: object): Severity => {
+  if (severity in error && LogLevel.values.includes(error[severity] as Severity)) {
+    return error[severity] as Severity
+  }
+  return "Error"
+}
+
+/**
+ * Symbol key used to attach extra key/value metadata to an error report.
+ *
+ * Reporters receive these attributes alongside the error, making it easy to
+ * include contextual information such as user IDs, request IDs, or any
+ * domain-specific data useful for debugging.
+ *
+ * @example
+ * ```ts
+ * import { Data, ErrorReporter } from "effect"
+ *
+ * class PaymentError extends Data.TaggedError("PaymentError")<{
+ *   readonly orderId: string
+ * }> {
+ *   readonly [ErrorReporter.attributes] = {
+ *     orderId: this.orderId
+ *   }
+ * }
+ * ```
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export type attributes = "~effect/ErrorReporter/attributes"
+
+/**
+ * Symbol key used to attach extra key/value metadata to an error report.
+ *
+ * Reporters receive these attributes alongside the error, making it easy to
+ * include contextual information such as user IDs, request IDs, or any
+ * domain-specific data useful for debugging.
+ *
+ * @example
+ * ```ts
+ * import { Data, ErrorReporter } from "effect"
+ *
+ * class PaymentError extends Data.TaggedError("PaymentError")<{
+ *   readonly orderId: string
+ * }> {
+ *   readonly [ErrorReporter.attributes] = {
+ *     orderId: this.orderId
+ *   }
+ * }
+ * ```
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const attributes: attributes = "~effect/ErrorReporter/attributes"
+
+/**
+ * Reads the `ErrorReporter.attributes` annotation from an error object,
+ * returning an empty record when unset.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const getAttributes = (error: object): ReadonlyRecord<string, unknown> => {
+  return attributes in error ? error[attributes] as any : emptyAttributes
+}
+
+const emptyAttributes: ReadonlyRecord<string, unknown> = {}

package/src/LogLevel.ts

@@ -142,6 +142,12 @@ import * as References from "./References.ts"
  */
 export type LogLevel = "All" | "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "Trace" | "None"
 
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export type Severity = "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "Trace"
+
 /**
  * @since 4.0.0
  * @category models

package/src/Logger.ts

@@ -115,8 +115,7 @@ import type { PlatformError } from "./PlatformError.ts"
 import * as Predicate from "./Predicate.ts"
 import { CurrentLogAnnotations, CurrentLogSpans } from "./References.ts"
 import type * as Scope from "./Scope.ts"
-import * as ServiceMap from "./ServiceMap.ts"
-import type * as Types from "./Types.ts"
+import type * as ServiceMap from "./ServiceMap.ts"
 
 const TypeId = "~effect/Logger"
 
@@ -144,8 +143,9 @@ const TypeId = "~effect/Logger"
  * @since 2.0.0
  * @category models
  */
-export interface Logger<in Message, out Output> extends Logger.Variance<Message, Output>, Pipeable {
-  log: (options: Logger.Options<Message>) => Output
+export interface Logger<in Message, out Output> extends Pipeable {
+  readonly [TypeId]: typeof TypeId
+  log(options: Options<Message>): Output
 }
 
 /**
@@ -153,100 +153,32 @@ export interface Logger<in Message, out Output> extends Logger.Variance<Message,
  * ```ts
  * import { Effect, Logger } from "effect"
  *
- * // Access Logger namespace types and functionality
- * const customLogger = Logger.make((options) => {
- *   console.log(`Message: ${options.message}`)
- *   console.log(`Level: ${options.logLevel}`)
- *   console.log(`Date: ${options.date.toISOString()}`)
- *   console.log(`Fiber ID: ${options.fiber.id}`)
+ * // Options interface provides all logging context
+ * const detailedLogger = Logger.make((options) => {
+ *   const output = {
+ *     message: options.message,
+ *     level: options.logLevel,
+ *     timestamp: options.date.toISOString(),
+ *     fiberId: options.fiber.id,
+ *     hasCause: options.cause !== undefined
+ *   }
+ *   console.log(JSON.stringify(output))
  * })
  *
- * // The Logger namespace contains types like Options, Variance, etc.
- * const program = Effect.log("Hello World").pipe(
- *   Effect.provide(Logger.layer([customLogger]))
+ * const program = Effect.log("Processing request").pipe(
+ *   Effect.provide(Logger.layer([detailedLogger]))
  * )
  * ```
  *
  * @since 2.0.0
  * @category models
  */
-export declare namespace Logger {
-  /**
-   * @example
-   * ```ts
-   * import { Logger } from "effect"
-   *
-   * // Variance interface defines contravariance for Message and covariance for Output
-   * const customLogger = Logger.make<unknown, void>((options) => {
-   *   console.log(options.message)
-   * })
-   *
-   * // The logger can accept more specific message types (contravariance)
-   * // and can be used where less specific output types are expected (covariance)
-   * ```
-   *
-   * @since 2.0.0
-   * @category models
-   */
-  export interface Variance<in Message, out Output> {
-    readonly [TypeId]: VarianceStruct<Message, Output>
-  }
-
-  /**
-   * @example
-   * ```ts
-   * import { Logger } from "effect"
-   *
-   * // VarianceStruct defines the actual variance structure used internally
-   * // This structure ensures proper typing and variance behavior
-   * const logger = Logger.make<unknown, void>((options) => {
-   *   console.log(options.message)
-   * })
-   *
-   * // The variance structure handles contravariance for input Message type
-   * // and covariance for output Output type
-   * ```
-   *
-   * @since 4.0.0
-   * @category models
-   */
-  export interface VarianceStruct<in Message, out Output> {
-    _Message: Types.Contravariant<Message>
-    _Output: Types.Covariant<Output>
-  }
-
-  /**
-   * @example
-   * ```ts
-   * import { Effect, Logger } from "effect"
-   *
-   * // Options interface provides all logging context
-   * const detailedLogger = Logger.make((options) => {
-   *   const output = {
-   *     message: options.message,
-   *     level: options.logLevel,
-   *     timestamp: options.date.toISOString(),
-   *     fiberId: options.fiber.id,
-   *     hasCause: options.cause !== undefined
-   *   }
-   *   console.log(JSON.stringify(output))
-   * })
-   *
-   * const program = Effect.log("Processing request").pipe(
-   *   Effect.provide(Logger.layer([detailedLogger]))
-   * )
-   * ```
-   *
-   * @since 2.0.0
-   * @category models
-   */
-  export interface Options<out Message> {
-    readonly message: Message
-    readonly logLevel: LogLevel.LogLevel
-    readonly cause: Cause.Cause<unknown>
-    readonly fiber: Fiber.Fiber<unknown, unknown>
-    readonly date: Date
-  }
+export interface Options<out Message> {
+  readonly message: Message
+  readonly logLevel: LogLevel.LogLevel
+  readonly cause: Cause.Cause<unknown>
+  readonly fiber: Fiber.Fiber<unknown, unknown>
+  readonly date: Date
 }
 
 /**
@@ -562,7 +494,7 @@ const format = (
   quoteValue: (s: string) => string,
   space?: number | string | undefined
 ) =>
-({ cause, date, fiber, logLevel, message }: Logger.Options<unknown>): string => {
+({ cause, date, fiber, logLevel, message }: Options<unknown>): string => {
   const formatValue = (value: string): string => value.match(textOnly) ? value : quoteValue(value)
   const format = (label: string, value: string): string => `${effect.formatLabel(label)}=${formatValue(value)}`
   const append = (label: string, value: string): string => " " + format(label, value)
@@ -636,7 +568,7 @@ const format = (
  * @category constructors
  */
 export const make: <Message, Output>(
-  log: (options: Logger.Options<Message>) => Output
+  log: (options: Options<Message>) => Output
 ) => Logger<Message, Output> = effect.loggerMake
 
 /**
@@ -1389,7 +1321,7 @@ export const layer = <
   const Loggers extends ReadonlyArray<Logger<unknown, unknown> | Effect.Effect<Logger<unknown, unknown>, any, any>>
 >(
   loggers: Loggers,
-  options?: { mergeWithExisting: boolean }
+  options?: { readonly mergeWithExisting?: boolean | undefined } | undefined
 ): Layer.Layer<
   never,
   Loggers extends readonly [] ? never : Effect.Error<Loggers[number]>,
@@ -1398,13 +1330,14 @@ export const layer = <
     Scope.Scope
   >
 > =>
-  Layer.effectServices(
+  Layer.effect(
+    CurrentLoggers,
     withFiber(effect.fnUntraced(function*(fiber) {
       const currentLoggers = new Set(options?.mergeWithExisting === true ? fiber.getRef(effect.CurrentLoggers) : [])
       for (const logger of loggers) {
         currentLoggers.add(isEffect(logger) ? yield* logger : logger)
       }
-      return ServiceMap.make(effect.CurrentLoggers, currentLoggers)
+      return currentLoggers
     }))
   )
 

package/src/Queue.ts

@@ -1113,7 +1113,6 @@ export const collect = <A, E>(self: Dequeue<A, E | Done>): Effect<Array<A>, Pull
           while: constTrue,
           body: constant(takeAll(self)),
           step(items: Arr.NonEmptyArray<A>) {
-            out.push(...items)
             for (let i = 0; i < items.length; i++) {
               out.push(items[i])
             }

package/src/References.ts

@@ -11,7 +11,7 @@
  * @since 4.0.0
  */
 import { constTrue, constUndefined } from "./Function.ts"
-import type { LogLevel } from "./LogLevel.ts"
+import type { LogLevel, Severity } from "./LogLevel.ts"
 import type { ReadonlyRecord } from "./Record.ts"
 import { MaxOpsBeforeYield } from "./Scheduler.ts"
 import * as ServiceMap from "./ServiceMap.ts"
@@ -451,7 +451,7 @@ export const CurrentLogAnnotations = ServiceMap.Reference<ReadonlyRecord<string,
  * @category references
  * @since 4.0.0
  */
-export const CurrentLogLevel: ServiceMap.Reference<LogLevel> = ServiceMap.Reference<LogLevel>(
+export const CurrentLogLevel: ServiceMap.Reference<Severity> = ServiceMap.Reference<Severity>(
   "effect/References/CurrentLogLevel",
   { defaultValue: () => "Info" }
 )
@@ -516,9 +516,9 @@ export const MinimumLogLevel = ServiceMap.Reference<
  * @category references
  * @since 4.0.0
  */
-export const UnhandledLogLevel: ServiceMap.Reference<LogLevel | undefined> = ServiceMap.Reference(
+export const UnhandledLogLevel: ServiceMap.Reference<Severity | undefined> = ServiceMap.Reference(
   "effect/References/UnhandledLogLevel",
-  { defaultValue: (): LogLevel | undefined => "Error" }
+  { defaultValue: (): Severity | undefined => "Error" }
 )
 
 /**