effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/ErrorReporter.ts

@@ -13,7 +13,8 @@
  * Use the annotation symbols (`ignore`, `severity`, `attributes`) on your
  * error classes to control reporting behavior per-error.
  *
- * @example
+ * **Example** (Reporting errors with annotations)
+ *
  * ```ts
  * import { Data, Effect, ErrorReporter } from "effect"
  *
@@ -61,14 +62,19 @@ import type { ReadonlyRecord } from "./Record.ts"
 import type * as Scope from "./Scope.ts"
 
 /**
- * @since 4.0.0
+ * String literal type used as the runtime type identifier for
+ * `ErrorReporter` values.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export type TypeId = "~effect/ErrorReporter"
 
 /**
- * @since 4.0.0
+ * Runtime type identifier attached to `ErrorReporter` values.
+ *
  * @category Type Identifiers
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/ErrorReporter"
 
@@ -81,8 +87,8 @@ export const TypeId: TypeId = "~effect/ErrorReporter"
  * modules. Use {@link make} to create a reporter — it handles deduplication
  * and per-error annotation extraction automatically.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface ErrorReporter {
   readonly [TypeId]: TypeId
@@ -101,7 +107,8 @@ export interface ErrorReporter {
  * and resolves the `ignore`, `severity`, and `attributes` annotations on
  * each error before invoking your callback.
  *
- * @example
+ * **Example** (Forwarding errors to the console)
+ *
  * ```ts
  * import { ErrorReporter } from "effect"
  *
@@ -113,8 +120,8 @@ export interface ErrorReporter {
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make = (
   report: (options: {
@@ -162,8 +169,8 @@ export const make = (
  * reference directly only when you need low-level control (e.g. reading the
  * current reporters or swapping them inside a `FiberRef`).
  *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>> = references.CurrentErrorReporters
 
@@ -177,7 +184,8 @@ export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>
  * reporters. Set `mergeWithExisting: true` to add them alongside existing
  * ones.
  *
- * @example
+ * **Example** (Providing error reporters)
+ *
  * ```ts
  * import { Effect, ErrorReporter } from "effect"
  *
@@ -207,8 +215,8 @@ export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>
  * )
  * ```
  *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layer = <
   const Reporters extends ReadonlyArray<ErrorReporter | Effect.Effect<ErrorReporter, any, any>>
@@ -243,7 +251,8 @@ export const layer = <
  * This is useful when you want to report an error for observability without
  * actually failing the fiber.
  *
- * @example
+ * **Example** (Reporting a cause manually)
+ *
  * ```ts
  * import { Cause, Effect, ErrorReporter } from "effect"
  *
@@ -255,8 +264,8 @@ export const layer = <
  * })
  * ```
  *
- * @since 4.0.0
  * @category Reporting
+ * @since 4.0.0
  */
 export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
   Effect.withFiber((fiber) => {
@@ -265,18 +274,18 @@ export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
   })
 
 /**
- * Interface that errors can implement to control reporting behavior.
+ * Interface that object 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
+ * - `[ErrorReporter.ignore]` - when `true`, the error is not reported
+ * - `[ErrorReporter.severity]` - overrides the default `"Info"` 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.
+ * properties are available on `Error` instances at the type level.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export interface Reportable {
   readonly [ignore]?: boolean
@@ -289,32 +298,28 @@ declare global {
 }
 
 /**
- * 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.
+ * String property key used to mark an object error as ignored by error
+ * reporting.
  *
- * @example
- * ```ts
- * import { Data, ErrorReporter } from "effect"
- *
- * class NotFoundError extends Data.TaggedError("NotFoundError")<{}> {
- *   readonly [ErrorReporter.ignore] = true
- * }
- * ```
+ * Set this property to `true` on an error class or object error to prevent it
+ * from being forwarded to reporters. This is useful for expected failures such
+ * as HTTP 404 responses.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export type ignore = "~effect/ErrorReporter/ignore"
 
 /**
- * Symbol key used to mark an error as unreportable.
+ * Runtime property key used to mark an object error as ignored by error
+ * reporting.
  *
- * 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.
+ * Set `error[ErrorReporter.ignore]` to `true` to prevent the error from being
+ * forwarded to reporters. This is useful for expected failures such as HTTP 404
+ * responses.
+ *
+ * **Example** (Marking errors as ignored)
  *
- * @example
  * ```ts
  * import { Data, ErrorReporter } from "effect"
  *
@@ -323,8 +328,8 @@ export type ignore = "~effect/ErrorReporter/ignore"
  * }
  * ```
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const ignore: ignore = "~effect/ErrorReporter/ignore"
 
@@ -332,41 +337,31 @@ export const ignore: ignore = "~effect/ErrorReporter/ignore"
  * Returns `true` if the given value has the `ErrorReporter.ignore` annotation
  * set to `true`.
  *
+ * @category annotations
  * @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"`.
+ * String property key used to override the severity level of an object error.
  *
- * @example
- * ```ts
- * import { Data, ErrorReporter } from "effect"
- *
- * class DeprecationWarning extends Data.TaggedError("DeprecationWarning")<{}> {
- *   readonly [ErrorReporter.severity] = "Warn" as const
- * }
- * ```
+ * When set to a valid `LogLevel.Severity`, the reporter callback receives this
+ * value as `severity`. Missing or invalid values fall back to `"Info"`.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export type severity = "~effect/ErrorReporter/severity"
 
 /**
- * Symbol key used to override the severity level of an error.
+ * Runtime property key used to override the severity level of an object error.
+ *
+ * Set `error[ErrorReporter.severity]` to a valid `LogLevel.Severity` value.
+ * Missing or invalid values fall back to `"Info"`.
  *
- * 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** (Setting error severity annotations)
  *
- * @example
  * ```ts
  * import { Data, ErrorReporter } from "effect"
  *
@@ -375,17 +370,17 @@ export type severity = "~effect/ErrorReporter/severity"
  * }
  * ```
  *
+ * @category annotations
  * @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.
+ * falling back to `"Info"` when the annotation is unset or invalid.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const getSeverity = (error: object): Severity => {
   if (severity in error && LogLevel.values.includes(error[severity] as Severity)) {
@@ -395,38 +390,27 @@ export const getSeverity = (error: object): Severity => {
 }
 
 /**
- * Symbol key used to attach extra key/value metadata to an error report.
+ * String property key used to attach extra key/value metadata to an object
+ * 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
- *   }
- * }
- * ```
+ * include contextual information such as user IDs, request IDs, or other
+ * domain-specific debugging data.
  *
+ * @category annotations
  * @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.
+ * Runtime property key used to attach extra key/value metadata to an object
+ * 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.
+ * Set `error[ErrorReporter.attributes]` to a record of metadata that should be
+ * forwarded to reporters alongside the error.
+ *
+ * **Example** (Setting error attributes)
  *
- * @example
  * ```ts
  * import { Data, ErrorReporter } from "effect"
  *
@@ -439,8 +423,8 @@ export type attributes = "~effect/ErrorReporter/attributes"
  * }
  * ```
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const attributes: attributes = "~effect/ErrorReporter/attributes"
 
@@ -448,8 +432,8 @@ export const attributes: attributes = "~effect/ErrorReporter/attributes"
  * Reads the `ErrorReporter.attributes` annotation from an error object,
  * returning an empty record when unset.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const getAttributes = (error: object): ReadonlyRecord<string, unknown> => {
   return attributes in error ? error[attributes] as any : emptyAttributes

package/src/ExecutionPlan.ts

@@ -1,4 +1,41 @@
 /**
+ * The `ExecutionPlan` module provides a way to describe ordered fallback
+ * strategies for effects and streams that need different resources across
+ * repeated attempts. An `ExecutionPlan` is a non-empty list of steps, where
+ * each step supplies a `Context` or `Layer` and may control retries with an
+ * attempt limit, a `Schedule`, or a `while` predicate.
+ *
+ * **Mental model**
+ *
+ * - A plan is evaluated step by step until the wrapped effect or stream
+ *   succeeds, or until every step has been exhausted
+ * - Each step provides the services used while that step is active
+ * - `attempts` limits how many times a step may be tried
+ * - `schedule` controls retry timing and receives the failure input
+ * - `while` can stop retrying a step based on the failure input
+ * - `CurrentMetadata` exposes the current 1-based attempt and 0-based step
+ *   index to code running under a plan
+ *
+ * **Common tasks**
+ *
+ * - Build a plan with {@link make}
+ * - Run an effect with a plan using `Effect.withExecutionPlan`
+ * - Run a stream with a plan using `Stream.withExecutionPlan`
+ * - Combine plans in order with {@link merge}
+ * - Capture required services up front with `captureRequirements`
+ * - Inspect the current attempt and step with {@link CurrentMetadata}
+ *
+ * **Gotchas**
+ *
+ * - Plans must contain at least one step
+ * - `attempts` must be greater than zero when provided
+ * - If `attempts` is omitted, a step is attempted once unless a `schedule` is
+ *   provided
+ * - A `while` predicate returning `false` skips the remaining retries for that
+ *   step and moves the plan forward
+ * - Layer, schedule, and predicate requirements are tracked in the plan type
+ *   until they are provided or captured
+ *
  * @since 3.16.0
  */
 import type { NonEmptyReadonlyArray } from "./Array.ts"
@@ -13,29 +50,41 @@ import * as Predicate from "./Predicate.ts"
 import type * as Schedule from "./Schedule.ts"
 
 /**
+ * String literal type used as the runtime type identifier for `ExecutionPlan`
+ * values.
+ *
+ * @category type IDs
  * @since 3.16.0
- * @category Type IDs
  */
 export type TypeId = "~effect/ExecutionPlan"
 
 /**
+ * Runtime type identifier attached to `ExecutionPlan` values and used by
+ * `isExecutionPlan`.
+ *
+ * @category type IDs
  * @since 3.16.0
- * @category Type IDs
  */
 export const TypeId: TypeId = "~effect/ExecutionPlan"
 
 /**
+ * Returns `true` if a value is an `ExecutionPlan`.
+ *
+ * This is a type guard that checks for the `ExecutionPlan.TypeId` marker.
+ *
+ * @category guards
  * @since 3.16.0
- * @category Guards
  */
 export const isExecutionPlan = (u: unknown): u is ExecutionPlan<any> => Predicate.hasProperty(u, TypeId)
 
 /**
  * A `ExecutionPlan` can be used with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`, allowing you to provide different resources for each step of execution until the effect succeeds or the plan is exhausted.
  *
+ * **Example** (Defining fallback execution steps)
+ *
  * ```ts
- * import type { Layer } from "effect"
  * import { Effect, ExecutionPlan, Schedule } from "effect"
+ * import type { Layer } from "effect"
  * import type { LanguageModel } from "effect/unstable/ai"
  *
  * declare const layerBad: Layer.Layer<LanguageModel.LanguageModel>
@@ -70,8 +119,8 @@ export const isExecutionPlan = (u: unknown): u is ExecutionPlan<any> => Predicat
  * const withPlan: Effect.Effect<void> = Effect.withExecutionPlan(effect, ThePlan)
  * ```
  *
+ * @category models
  * @since 3.16.0
- * @category Models
  */
 export interface ExecutionPlan<
   Config extends {
@@ -109,8 +158,15 @@ export interface ExecutionPlan<
 }
 
 /**
- * @since 3.16.0
- * @category Models
+ * Base type-level configuration carried by an `ExecutionPlan`.
+ *
+ * `provides` tracks services supplied by plan steps, `input` tracks the error
+ * input consumed by schedules and `while` predicates, `error` tracks failures
+ * from plan layers or predicates, and `requirements` tracks services needed to
+ * build or run the plan.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export type ConfigBase = {
   provides: any
@@ -122,9 +178,11 @@ export type ConfigBase = {
 /**
  * Create an `ExecutionPlan`, which can be used with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`, allowing you to provide different resources for each step of execution until the effect succeeds or the plan is exhausted.
  *
+ * **Example** (Creating an execution plan)
+ *
  * ```ts
- * import type { Layer } from "effect"
  * import { Effect, ExecutionPlan, Schedule } from "effect"
+ * import type { Layer } from "effect"
  * import type { LanguageModel } from "effect/unstable/ai"
  *
  * declare const layerBad: Layer.Layer<LanguageModel.LanguageModel>
@@ -159,8 +217,8 @@ export type ConfigBase = {
  * const withPlan: Effect.Effect<void> = Effect.withExecutionPlan(effect, ThePlan)
  * ```
  *
+ * @category constructors
  * @since 3.16.0
- * @category Constructors
  */
 export const make = <const Steps extends NonEmptyReadonlyArray<make.Step>>(
   ...steps: Steps & { [K in keyof Steps]: make.Step }
@@ -195,10 +253,19 @@ export const make = <const Steps extends NonEmptyReadonlyArray<make.Step>>(
   }) as any)
 
 /**
+ * Namespace containing type helpers used by `ExecutionPlan.make`.
+ *
  * @since 3.16.0
  */
 export declare namespace make {
   /**
+   * Input shape for a single execution-plan step.
+   *
+   * Each step provides a `Context` or `Layer` and may limit attempts, add a
+   * `while` predicate for retry decisions, or attach a `Schedule` for retry
+   * timing.
+   *
+   * @category models
    * @since 3.16.0
    */
   export type Step = {
@@ -209,6 +276,10 @@ export declare namespace make {
   }
 
   /**
+   * Computes the intersection of services provided by a list of execution-plan
+   * steps.
+   *
+   * @category utility types
    * @since 3.16.1
    */
   export type StepProvides<Steps extends ReadonlyArray<any>, Out = unknown> = Steps extends
@@ -223,6 +294,9 @@ export declare namespace make {
     Out
 
   /**
+   * Computes the intersection of services provided by a list of execution plans.
+   *
+   * @category utility types
    * @since 3.16.1
    */
   export type PlanProvides<Plans extends ReadonlyArray<any>, Out = unknown> = Plans extends
@@ -231,6 +305,10 @@ export declare namespace make {
     Out
 
   /**
+   * Computes the input type consumed by the `while` predicates and schedules in
+   * a list of execution-plan steps.
+   *
+   * @category utility types
    * @since 3.16.0
    */
   export type StepInput<Steps extends ReadonlyArray<any>, Out = unknown> = Steps extends
@@ -245,6 +323,9 @@ export declare namespace make {
     Out
 
   /**
+   * Computes the combined input type consumed by a list of execution plans.
+   *
+   * @category utility types
    * @since 3.16.0
    */
   export type PlanInput<Plans extends ReadonlyArray<any>, Out = unknown> = Plans extends
@@ -285,8 +366,13 @@ const makeProto = <Provides, In, PlanE, PlanR>(
 }
 
 /**
- * @since 3.16.0
+ * Combines multiple execution plans by concatenating their steps in order.
+ *
+ * The resulting plan tries every step from the first plan, then every step from
+ * the next plan, and so on.
+ *
  * @category Combining
+ * @since 3.16.0
  */
 export const merge = <const Plans extends NonEmptyReadonlyArray<ExecutionPlan<any>>>(
   ...plans: Plans
@@ -298,8 +384,13 @@ export const merge = <const Plans extends NonEmptyReadonlyArray<ExecutionPlan<an
 }> => makeProto(plans.flatMap((plan) => plan.steps) as any)
 
 /**
- * @since 4.0.0
+ * Metadata describing the currently running execution-plan attempt.
+ *
+ * `attempt` is the current 1-based attempt number, and `stepIndex` is the
+ * 0-based index of the plan step currently being evaluated.
+ *
  * @category Metadata
+ * @since 4.0.0
  */
 export interface Metadata {
   readonly attempt: number
@@ -307,8 +398,11 @@ export interface Metadata {
 }
 
 /**
- * @since 4.0.0
+ * `Context.Reference` containing metadata for the currently running
+ * execution-plan attempt.
+ *
  * @category Metadata
+ * @since 4.0.0
  */
 export const CurrentMetadata = Context.Reference<Metadata>("effect/ExecutionPlan/CurrentMetadata", {
   defaultValue: constant({

package/src/Exit.ts

@@ -96,14 +96,15 @@ const TypeId = core.ExitTypeId
  * @see {@link Failure} for the failure case
  * @see {@link match} for pattern matching
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Exit<A, E = never> = Success<A, E> | Failure<A, E>
 
 /**
+ * Namespace containing helper types shared by `Exit` values.
+ *
  * @since 2.0.0
- * @category models
  */
 export declare namespace Exit {
   /**
@@ -111,8 +112,8 @@ export declare namespace Exit {
    *
    * Every Exit is also an Effect, so you can yield it in `Effect.gen`.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Proto<out A, out E = never> extends Effect.Effect<A, E> {
     readonly [TypeId]: typeof TypeId
@@ -141,8 +142,8 @@ export declare namespace Exit {
  * @see {@link isSuccess} to narrow an Exit to Success
  * @see {@link Failure} for the failure counterpart
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Success<out A, out E = never> extends Exit.Proto<A, E> {
   readonly _tag: "Success"
@@ -172,8 +173,8 @@ export interface Success<out A, out E = never> extends Exit.Proto<A, E> {
  * @see {@link isFailure} to narrow an Exit to Failure
  * @see {@link Success} for the success counterpart
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Failure<out A, out E> extends Exit.Proto<A, E> {
   readonly _tag: "Failure"