effect 4.0.0-beta.103 → 4.0.0-beta.104

package/dist/Effect.d.ts

@@ -15,7 +15,7 @@ import type * as Cause from "./Cause.ts";
 import type { Clock } from "./Clock.ts";
 import * as Context from "./Context.ts";
 import * as Duration from "./Duration.ts";
-import type { ExecutionPlan } from "./ExecutionPlan.ts";
+import type * as ExecutionPlan from "./ExecutionPlan.ts";
 import * as Exit from "./Exit.ts";
 import type { Fiber } from "./Fiber.ts";
 import type * as Filter from "./Filter.ts";
@@ -7155,6 +7155,14 @@ export declare const ignoreCause: <Arg extends Effect<any, any, any> | {
  * and retry timing is derived per step (the first attempt uses the remaining
  * attempts schedule; later retries apply the step schedule at least once).
  *
+ * Attempts can be observed from outside the effect by passing
+ * `options.onEvent`, which receives an `ExecutionPlan.Event` before each
+ * attempt and after it settles. The handler is awaited inline before and after
+ * every attempt, so events are strictly ordered; keep it cheap. It cannot
+ * fail, which keeps observation from changing the plan's outcome, and its
+ * requirements are added to the resulting effect. Terminal events run like
+ * finalizers, so they are emitted even when the attempt is interrupted.
+ *
  * **Example** (Retrying with an execution plan)
  *
  * ```ts import.meta.vitest
@@ -7179,6 +7187,36 @@ export declare const ignoreCause: <Arg extends Effect<any, any, any> | {
  * Effect.runSync(program) // => "good"
  * ```
  *
+ * **Example** (Observing execution-plan attempts)
+ *
+ * ```ts import.meta.vitest
+ * import { Context, Effect, ExecutionPlan, Layer } from "effect"
+ *
+ * const Endpoint = Context.Service<{ url: string }>("Endpoint")
+ *
+ * const fetchUrl = Effect.gen(function*() {
+ *   const endpoint = yield* Effect.service(Endpoint)
+ *   if (endpoint.url === "bad") {
+ *     return yield* Effect.fail("Unavailable")
+ *   }
+ *   return endpoint.url
+ * })
+ *
+ * const plan = ExecutionPlan.make(
+ *   { provide: Layer.succeed(Endpoint, { url: "bad" }) },
+ *   { provide: Layer.succeed(Endpoint, { url: "good" }) }
+ * )
+ *
+ * const events: Array<string> = []
+ * const program = Effect.withExecutionPlan(fetchUrl, plan, {
+ *   onEvent: (event) => Effect.sync(() => events.push(`${event._tag}:${event.stepIndex}`))
+ * })
+ *
+ * await Effect.runPromise(program) // => "good"
+ *
+ * events // => ["AttemptStart:0", "AttemptFailure:0", "AttemptStart:1", "AttemptSuccess:1"]
+ * ```
+ *
  * @category error handling
  * @since 3.16.0
  */
@@ -7193,6 +7231,14 @@ export declare const withExecutionPlan: {
      * and retry timing is derived per step (the first attempt uses the remaining
      * attempts schedule; later retries apply the step schedule at least once).
      *
+     * Attempts can be observed from outside the effect by passing
+     * `options.onEvent`, which receives an `ExecutionPlan.Event` before each
+     * attempt and after it settles. The handler is awaited inline before and after
+     * every attempt, so events are strictly ordered; keep it cheap. It cannot
+     * fail, which keeps observation from changing the plan's outcome, and its
+     * requirements are added to the resulting effect. Terminal events run like
+     * finalizers, so they are emitted even when the attempt is interrupted.
+     *
      * **Example** (Retrying with an execution plan)
      *
      * ```ts import.meta.vitest
@@ -7217,15 +7263,47 @@ export declare const withExecutionPlan: {
      * Effect.runSync(program) // => "good"
      * ```
      *
+     * **Example** (Observing execution-plan attempts)
+     *
+     * ```ts import.meta.vitest
+     * import { Context, Effect, ExecutionPlan, Layer } from "effect"
+     *
+     * const Endpoint = Context.Service<{ url: string }>("Endpoint")
+     *
+     * const fetchUrl = Effect.gen(function*() {
+     *   const endpoint = yield* Effect.service(Endpoint)
+     *   if (endpoint.url === "bad") {
+     *     return yield* Effect.fail("Unavailable")
+     *   }
+     *   return endpoint.url
+     * })
+     *
+     * const plan = ExecutionPlan.make(
+     *   { provide: Layer.succeed(Endpoint, { url: "bad" }) },
+     *   { provide: Layer.succeed(Endpoint, { url: "good" }) }
+     * )
+     *
+     * const events: Array<string> = []
+     * const program = Effect.withExecutionPlan(fetchUrl, plan, {
+     *   onEvent: (event) => Effect.sync(() => events.push(`${event._tag}:${event.stepIndex}`))
+     * })
+     *
+     * await Effect.runPromise(program) // => "good"
+     *
+     * events // => ["AttemptStart:0", "AttemptFailure:0", "AttemptStart:1", "AttemptSuccess:1"]
+     * ```
+     *
      * @category error handling
      * @since 3.16.0
      */
-    <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
+    <Input, Provides, PlanE, PlanR, RX = never>(plan: ExecutionPlan.ExecutionPlan<{
         provides: Provides;
         input: Input;
         error: PlanE;
         requirements: PlanR;
-    }>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>;
+    }>, options?: {
+        readonly onEvent?: ((event: ExecutionPlan.Event<Input | PlanE>) => Effect<void, never, RX>) | undefined;
+    }): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR | RX>;
     /**
      * Applies an `ExecutionPlan` to an effect, retrying with step-provided resources
      * until it succeeds or the plan is exhausted.
@@ -7236,6 +7314,14 @@ export declare const withExecutionPlan: {
      * and retry timing is derived per step (the first attempt uses the remaining
      * attempts schedule; later retries apply the step schedule at least once).
      *
+     * Attempts can be observed from outside the effect by passing
+     * `options.onEvent`, which receives an `ExecutionPlan.Event` before each
+     * attempt and after it settles. The handler is awaited inline before and after
+     * every attempt, so events are strictly ordered; keep it cheap. It cannot
+     * fail, which keeps observation from changing the plan's outcome, and its
+     * requirements are added to the resulting effect. Terminal events run like
+     * finalizers, so they are emitted even when the attempt is interrupted.
+     *
      * **Example** (Retrying with an execution plan)
      *
      * ```ts import.meta.vitest
@@ -7260,15 +7346,47 @@ export declare const withExecutionPlan: {
      * Effect.runSync(program) // => "good"
      * ```
      *
+     * **Example** (Observing execution-plan attempts)
+     *
+     * ```ts import.meta.vitest
+     * import { Context, Effect, ExecutionPlan, Layer } from "effect"
+     *
+     * const Endpoint = Context.Service<{ url: string }>("Endpoint")
+     *
+     * const fetchUrl = Effect.gen(function*() {
+     *   const endpoint = yield* Effect.service(Endpoint)
+     *   if (endpoint.url === "bad") {
+     *     return yield* Effect.fail("Unavailable")
+     *   }
+     *   return endpoint.url
+     * })
+     *
+     * const plan = ExecutionPlan.make(
+     *   { provide: Layer.succeed(Endpoint, { url: "bad" }) },
+     *   { provide: Layer.succeed(Endpoint, { url: "good" }) }
+     * )
+     *
+     * const events: Array<string> = []
+     * const program = Effect.withExecutionPlan(fetchUrl, plan, {
+     *   onEvent: (event) => Effect.sync(() => events.push(`${event._tag}:${event.stepIndex}`))
+     * })
+     *
+     * await Effect.runPromise(program) // => "good"
+     *
+     * events // => ["AttemptStart:0", "AttemptFailure:0", "AttemptStart:1", "AttemptSuccess:1"]
+     * ```
+     *
      * @category error handling
      * @since 3.16.0
      */
-    <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
+    <A, E extends Input, R, Provides, Input, PlanE, PlanR, RX = never>(effect: Effect<A, E, R>, plan: ExecutionPlan.ExecutionPlan<{
         provides: Provides;
         input: Input;
         error: PlanE;
         requirements: PlanR;
-    }>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>;
+    }>, options?: {
+        readonly onEvent?: ((event: ExecutionPlan.Event<E | PlanE>) => Effect<void, never, RX>) | undefined;
+    }): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR | RX>;
 };
 /**
  * Runs an effect and reports any errors to the configured `ErrorReporter`s.
@@ -11113,7 +11231,7 @@ export declare const updateService: {
      * @category providing services
      * @since 2.0.0
      */
-    <I, A>(service: Context.Key<I, A>, f: (value: A) => A): <XA, E, R>(self: Effect<XA, E, R>) => Effect<XA, E, R | I>;
+    <I, A>(service: Context.Key<I, A>, f: (value: A) => NoInfer<A>): <XA, E, R>(self: Effect<XA, E, R>) => Effect<XA, E, R | I>;
     /**
      * Runs an effect with a service implementation transformed by the provided
      * function.
@@ -11149,7 +11267,7 @@ export declare const updateService: {
      * @category providing services
      * @since 2.0.0
      */
-    <XA, E, R, I, A>(self: Effect<XA, E, R>, service: Context.Key<I, A>, f: (value: A) => A): Effect<XA, E, R | I>;
+    <XA, E, R, I, A>(self: Effect<XA, E, R>, service: Context.Key<I, A>, f: (value: A) => NoInfer<A>): Effect<XA, E, R | I>;
 };
 /**
  * Updates a service for the lifetime of the current scope and restores its
@@ -11210,7 +11328,7 @@ export declare const updateService: {
  * @category providing services
  * @since 4.0.0
  */
-export declare const updateServiceScoped: <I, A>(service: Context.Key<I, A>, f: (value: A) => A, options?: {
+export declare const updateServiceScoped: <I, A>(service: Context.Key<I, A>, f: (value: A) => NoInfer<A>, options?: {
     readonly reset?: ((original: A, updated: A, current: A) => A) | undefined;
 } | undefined) => Effect<void, never, I | Scope>;
 /**
@@ -11614,7 +11732,7 @@ export declare const provideServiceEffect: {
      * @category providing services
      * @since 2.0.0
      */
-    <I, S, E2, R2>(service: Context.Key<I, S>, acquire: Effect<S, E2, R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | E2, Exclude<R, I> | R2>;
+    <I, S, E2, R2>(service: Context.Key<I, S>, acquire: Effect<NoInfer<S>, E2, R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | E2, Exclude<R, I> | R2>;
     /**
      * Provides one service to an effect using an effectful acquisition.
      *
@@ -11670,7 +11788,7 @@ export declare const provideServiceEffect: {
      * @category providing services
      * @since 2.0.0
      */
-    <A, E, R, I, S, E2, R2>(self: Effect<A, E, R>, service: Context.Key<I, S>, acquire: Effect<S, E2, R2>): Effect<A, E | E2, Exclude<R, I> | R2>;
+    <A, E, R, I, S, E2, R2>(self: Effect<A, E, R>, service: Context.Key<I, S>, acquire: Effect<NoInfer<S>, E2, R2>): Effect<A, E | E2, Exclude<R, I> | R2>;
 };
 /**
  * Returns the current scope for resource management.
@@ -14328,7 +14446,7 @@ export declare const schedule: {
      * @category repetition
      * @since 2.0.0
      */
-    <Output, Error, Env>(schedule: Schedule<Output, unknown, Error, Env>): <A, E, R>(self: Effect<A, E, R>) => Effect<Output, E, R | Env>;
+    <Output, Error, Env>(schedule: Schedule<Output, unknown, Error, Env>): <A, E, R>(self: Effect<A, E, R>) => Effect<Output, E | Error, R | Env>;
     /**
      * Runs an effect repeatedly according to a schedule and returns the schedule's
      * final output.
@@ -14369,7 +14487,7 @@ export declare const schedule: {
      * @category repetition
      * @since 2.0.0
      */
-    <A, E, R, Output, Error, Env>(self: Effect<A, E, R>, schedule: Schedule<Output, unknown, Error, Env>): Effect<Output, E, R | Env>;
+    <A, E, R, Output, Error, Env>(self: Effect<A, E, R>, schedule: Schedule<Output, unknown, Error, Env>): Effect<Output, E | Error, R | Env>;
 };
 /**
  * Runs an effect repeatedly according to a schedule that is initialized with a
@@ -14448,7 +14566,7 @@ export declare const scheduleFrom: {
      * @category repetition
      * @since 2.0.0
      */
-    <Input, Output, Error, Env>(initial: Input, schedule: Schedule<Output, Input, Error, Env>): <E, R>(self: Effect<Input, E, R>) => Effect<Output, E, R | Env>;
+    <Input, Output, Error, Env>(initial: Input, schedule: Schedule<Output, Input, Error, Env>): <E, R>(self: Effect<Input, E, R>) => Effect<Output, E | Error, R | Env>;
     /**
      * Runs an effect repeatedly according to a schedule that is initialized with a
      * specific schedule input.
@@ -14487,7 +14605,7 @@ export declare const scheduleFrom: {
      * @category repetition
      * @since 2.0.0
      */
-    <Input, E, R, Output, Error, Env>(self: Effect<Input, E, R>, initial: Input, schedule: Schedule<Output, Input, Error, Env>): Effect<Output, E, R | Env>;
+    <Input, E, R, Output, Error, Env>(self: Effect<Input, E, R>, initial: Input, schedule: Schedule<Output, Input, Error, Env>): Effect<Output, E | Error, R | Env>;
 };
 /**
  * Returns the current tracer from the context.