effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/ErrorReporter.ts

@@ -65,6 +65,10 @@ import type * as Scope from "./Scope.ts"
  * String literal type used as the runtime type identifier for
  * `ErrorReporter` values.
  *
+ * **When to use**
+ *
+ * Use to refer to the runtime type identifier type in low-level integrations.
+ *
  * @category Type Identifiers
  * @since 4.0.0
  */
@@ -73,6 +77,10 @@ export type TypeId = "~effect/ErrorReporter"
 /**
  * Runtime type identifier attached to `ErrorReporter` values.
  *
+ * **When to use**
+ *
+ * Use to compare or attach the runtime identifier for `ErrorReporter` values.
+ *
  * @category Type Identifiers
  * @since 4.0.0
  */
@@ -82,6 +90,11 @@ export const TypeId: TypeId = "~effect/ErrorReporter"
  * An `ErrorReporter` receives reported failures and forwards them to an
  * external system such as a logging service or error tracker.
  *
+ * **When to use**
+ *
+ * Use as the interface for custom reporters that forward reported Effect
+ * failures to logging, monitoring, or error-tracking systems.
+ *
  * **Details**
  *
  * Reporting is triggered by `Effect.withErrorReporting`,
@@ -89,6 +102,11 @@ export const TypeId: TypeId = "~effect/ErrorReporter"
  * modules. Use {@link make} to create a reporter; it handles deduplication
  * and per-error annotation extraction automatically.
  *
+ * @see {@link make} for creating an `ErrorReporter` from a callback
+ * @see {@link layer} for registering reporters in the environment
+ * @see {@link report} for manually reporting a `Cause`
+ * @see {@link Effect.withErrorReporting} for reporting failures from an effect
+ *
  * @category models
  * @since 4.0.0
  */
@@ -104,6 +122,11 @@ export interface ErrorReporter {
 /**
  * Creates an `ErrorReporter` from a callback.
  *
+ * **When to use**
+ *
+ * Use to define how reported failures are forwarded to a logging, monitoring,
+ * or error-tracking backend.
+ *
  * **Details**
  *
  * The returned reporter automatically deduplicates causes and individual
@@ -124,6 +147,9 @@ export interface ErrorReporter {
  * )
  * ```
  *
+ * @see {@link layer} for registering reporters in the environment
+ * @see {@link report} for manually reporting a `Cause`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -171,9 +197,8 @@ export const make = (
  *
  * **When to use**
  *
- * 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`).
+ * Use when low-level code needs to read or replace the current set of reporters
+ * directly.
  *
  * @category references
  * @since 4.0.0
@@ -183,6 +208,11 @@ export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>
 /**
  * Creates a `Layer` that registers one or more `ErrorReporter`s.
  *
+ * **When to use**
+ *
+ * Use to provide one or more error reporters to effects that perform error
+ * reporting.
+ *
  * **Details**
  *
  * Reporters can be plain `ErrorReporter` values or effectful
@@ -221,6 +251,9 @@ export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>
  * )
  * ```
  *
+ * @see {@link make} for creating an `ErrorReporter` from a callback
+ * @see {@link CurrentErrorReporters} for low-level access to the current reporters
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -256,8 +289,7 @@ export const layer = <
  *
  * **When to use**
  *
- * This is useful when you want to report an error for observability without
- * actually failing the fiber.
+ * Use to report a failure for observability without failing the current fiber.
  *
  * **Example** (Reporting a cause manually)
  *
@@ -284,6 +316,11 @@ export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
 /**
  * Interface that object errors can implement to control reporting behavior.
  *
+ * **When to use**
+ *
+ * Use as the annotation contract for object errors that customize how error
+ * reporting handles them.
+ *
  * **Details**
  *
  * All three annotation properties are optional: `[ErrorReporter.ignore]`
@@ -293,6 +330,11 @@ export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
  * augmented with `Reportable`, so these properties are available on `Error`
  * instances at the type level.
  *
+ * @see {@link ignore} for the runtime annotation key that suppresses reports
+ * @see {@link severity} for the runtime annotation key that overrides severity
+ * @see {@link attributes} for the runtime annotation key that attaches reporter
+ * metadata
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -310,6 +352,11 @@ declare global {
  * String property key used to mark an object error as ignored by error
  * reporting.
  *
+ * **When to use**
+ *
+ * Use to type the property key that suppresses reporting for expected object
+ * errors.
+ *
  * **Details**
  *
  * Set this property to `true` on an error class or object error to prevent it
@@ -325,6 +372,11 @@ export type ignore = "~effect/ErrorReporter/ignore"
  * Runtime property key used to mark an object error as ignored by error
  * reporting.
  *
+ * **When to use**
+ *
+ * Use to suppress reporting for expected object errors, such as HTTP 404
+ * responses.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.ignore]` to `true` to prevent the error from being
@@ -341,6 +393,10 @@ export type ignore = "~effect/ErrorReporter/ignore"
  * }
  * ```
  *
+ * @see {@link isIgnored} for checking whether a value carries this annotation
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -350,6 +406,13 @@ export const ignore: ignore = "~effect/ErrorReporter/ignore"
  * Returns `true` if the given value has the `ErrorReporter.ignore` annotation
  * set to `true`.
  *
+ * **When to use**
+ *
+ * Use to check whether an error value is annotated to be skipped before
+ * forwarding it to error reporting code.
+ *
+ * @see {@link ignore} for the annotation key this predicate reads
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -359,6 +422,11 @@ export const isIgnored = (u: unknown): boolean =>
 /**
  * String property key used to override the severity level of an object error.
  *
+ * **When to use**
+ *
+ * Use to type the property key that overrides the reporting severity for object
+ * errors.
+ *
  * **Details**
  *
  * When set to a valid `LogLevel.Severity`, the reporter callback receives this
@@ -372,6 +440,11 @@ export type severity = "~effect/ErrorReporter/severity"
 /**
  * Runtime property key used to override the severity level of an object error.
  *
+ * **When to use**
+ *
+ * Use to annotate object errors with the severity reporter callbacks should
+ * receive.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.severity]` to a valid `LogLevel.Severity` value.
@@ -387,6 +460,10 @@ export type severity = "~effect/ErrorReporter/severity"
  * }
  * ```
  *
+ * @see {@link getSeverity} for reading the severity stored under this key
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -396,6 +473,14 @@ export const severity: severity = "~effect/ErrorReporter/severity"
  * Reads the `ErrorReporter.severity` annotation from an error object,
  * falling back to `"Info"` when the annotation is unset or invalid.
  *
+ * **When to use**
+ *
+ * Use to inspect the severity that reporter callbacks will receive for an
+ * object error.
+ *
+ * @see {@link severity} for the annotation key used to override severity
+ * @see {@link Reportable} for the annotation properties recognized on object errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -410,6 +495,10 @@ export const getSeverity = (error: object): Severity => {
  * String property key used to attach extra key/value metadata to an object
  * error report.
  *
+ * **When to use**
+ *
+ * Use to type the property key that attaches metadata to object error reports.
+ *
  * **Details**
  *
  * Reporters receive these attributes alongside the error, making it easy to
@@ -425,6 +514,11 @@ export type attributes = "~effect/ErrorReporter/attributes"
  * Runtime property key used to attach extra key/value metadata to an object
  * error report.
  *
+ * **When to use**
+ *
+ * Use to attach domain metadata to object errors so reporter callbacks receive
+ * it with the reported failure.
+ *
  * **Details**
  *
  * Set `error[ErrorReporter.attributes]` to a record of metadata that should be
@@ -444,6 +538,12 @@ export type attributes = "~effect/ErrorReporter/attributes"
  * }
  * ```
  *
+ * @see {@link ignore} for suppressing reports for expected object errors
+ * @see {@link severity} for overriding reporter severity
+ * @see {@link getAttributes} for reading the metadata stored under this key
+ * @see {@link Reportable} for the annotation contract recognized on object
+ * errors
+ *
  * @category annotations
  * @since 4.0.0
  */
@@ -453,6 +553,24 @@ export const attributes: attributes = "~effect/ErrorReporter/attributes"
  * Reads the `ErrorReporter.attributes` annotation from an error object,
  * returning an empty record when unset.
  *
+ * **When to use**
+ *
+ * Use to inspect the attributes that reporter callbacks will receive for an
+ * object error.
+ *
+ * **Details**
+ *
+ * Returns the value stored under `ErrorReporter.attributes`, or the module's
+ * shared empty record when the annotation is absent.
+ *
+ * **Gotchas**
+ *
+ * The annotation value is returned as-is; this helper does not validate or
+ * clone it.
+ *
+ * @see {@link attributes} for the annotation key used to attach metadata
+ * @see {@link Reportable} for the annotation properties recognized on object errors
+ *
  * @category annotations
  * @since 4.0.0
  */

package/src/ExecutionPlan.ts

@@ -1,40 +1,84 @@
 /**
- * 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.
+ * Defines finite fallback plans for effects and streams that should retry the
+ * same work with different services. An `ExecutionPlan` is a non-empty
+ * sequence of steps. Each step provides a `Context` or `Layer`, and can limit
+ * or shape retries with `attempts`, `schedule`, and `while`.
+ *
+ * Use a plan with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`.
+ * Those APIs run the wrapped work with the first step, retry within that step
+ * as directed, then move to later steps until the work succeeds or the plan is
+ * exhausted.
  *
  * **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
+ * - A step is a resource profile for one part of a fallback strategy
+ * - The active step supplies the services visible to the wrapped effect or
+ *   stream
+ * - `attempts` caps the number of tries for a step
+ * - `schedule` controls retry timing and receives the wrapped work's failure
+ *   value
+ * - `while` can stop the current step early by inspecting the same failure
+ *   value
+ * - `CurrentMetadata` exposes the 1-based attempt number and 0-based step
+ *   index to code running under the active step
  *
  * **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}
+ * - Append fallback plans with {@link merge}
+ * - Apply a plan with `Effect.withExecutionPlan` or `Stream.withExecutionPlan`
+ * - Read active step and attempt information with {@link CurrentMetadata}
+ * - Carry the current environment into a plan with `captureRequirements`
+ *
+ * **Quickstart**
+ *
+ * **Example** (Retry with one layer, then fall back)
+ *
+ * ```ts
+ * import { Context, Effect, ExecutionPlan, Layer, Schedule } from "effect"
+ *
+ * class Endpoint extends Context.Service<Endpoint>()("Endpoint", {
+ *   make: Effect.succeed({ url: "primary" })
+ * }) {}
+ *
+ * const primary = Layer.succeed(Endpoint, Endpoint.of({ url: "primary" }))
+ * const fallback = Layer.succeed(Endpoint, Endpoint.of({ url: "fallback" }))
+ *
+ * const plan = ExecutionPlan.make(
+ *   {
+ *     provide: primary,
+ *     attempts: 2,
+ *     schedule: Schedule.recurs(1)
+ *   },
+ *   {
+ *     provide: fallback
+ *   }
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   const endpoint = yield* Endpoint
+ *   if (endpoint.url === "primary") {
+ *     return yield* Effect.fail("unavailable")
+ *   }
+ *   return endpoint.url
+ * }).pipe(Effect.withExecutionPlan(plan))
+ * ```
  *
  * **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
+ * - Without `attempts` or `schedule`, a step is tried once
+ * - A `schedule` can keep a step active until bounded by `attempts` or
+ *   stopped by `while`
+ * - Layer, schedule, and predicate requirements stay in the plan type until
+ *   they are provided or captured
+ *
+ * **See also**
+ *
+ * - {@link make} for constructing plans
+ * - {@link merge} for combining plans in order
+ * - {@link CurrentMetadata} for inspecting the active attempt
  *
  * @since 3.16.0
  */
@@ -71,6 +115,20 @@ export const TypeId: TypeId = "~effect/ExecutionPlan"
  * Returns `true` if a value is an `ExecutionPlan` by checking for the
  * `ExecutionPlan.TypeId` marker.
  *
+ * **When to use**
+ *
+ * Use when accepting an unknown value and you need to narrow it to an
+ * `ExecutionPlan` before reading plan fields or passing it to plan-consuming
+ * APIs.
+ *
+ * **Gotchas**
+ *
+ * This is a structural marker check; it does not validate the marker value or
+ * the shape of the plan steps.
+ *
+ * @see {@link make} for constructing execution plans that satisfy this guard
+ * @see {@link TypeId} for the runtime marker checked by this guard
+ *
  * @category guards
  * @since 3.16.0
  */
@@ -371,11 +429,18 @@ const makeProto = <Provides, In, PlanE, PlanR>(
 /**
  * Combines multiple execution plans by concatenating their steps in order.
  *
+ * **When to use**
+ *
+ * Use to combine separately defined fallback plans into one ordered plan before
+ * applying it to an effect or stream.
+ *
  * **Details**
  *
  * The resulting plan tries every step from the first plan, then every step from
  * the next plan, and so on.
  *
+ * @see {@link make} for building a plan from individual steps instead of combining existing plans
+ *
  * @category Combining
  * @since 3.16.0
  */