add ExecutionPlan module (#4910)

Author: tim-smart

.changeset/public-books-unite.md

@@ -0,0 +1,44 @@
+---
+"effect": minor
+---
+
+add ExecutionPlan module
+
+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.
+
+```ts
+import { type AiLanguageModel } from "@effect/ai"
+import type { Layer } from "effect"
+import { Effect, ExecutionPlan, Schedule } from "effect"
+
+declare const layerBad: Layer.Layer<AiLanguageModel.AiLanguageModel>
+declare const layerGood: Layer.Layer<AiLanguageModel.AiLanguageModel>
+
+const ThePlan = ExecutionPlan.make(
+  {
+    // First try with the bad layer 2 times with a 3 second delay between attempts
+    provide: layerBad,
+    attempts: 2,
+    schedule: Schedule.spaced(3000)
+  },
+  // Then try with the bad layer 3 times with a 1 second delay between attempts
+  {
+    provide: layerBad,
+    attempts: 3,
+    schedule: Schedule.spaced(1000)
+  },
+  // Finally try with the good layer.
+  //
+  // If `attempts` is omitted, the plan will only attempt once, unless a schedule is provided.
+  {
+    provide: layerGood
+  }
+)
+
+declare const effect: Effect.Effect<
+  void,
+  never,
+  AiLanguageModel.AiLanguageModel
+>
+const withPlan: Effect.Effect<void> = Effect.withExecutionPlan(effect, ThePlan)
+```

packages/effect/docgen.json

@@ -13,6 +13,7 @@
     "paths": {
       "effect": ["../../../effect/src/index.js"],
       "effect/*": ["../../../effect/src/*.js"],
+      "@effect/ai": ["../../../ai/ai/src/index.js"],
       "@effect/platform": ["../../../platform/src/index.js"],
       "@effect/platform/*": ["../../../platform/src/*.js"],
       "@effect/printer": ["../../../printer/src/index.js"],

packages/effect/src/Effect.ts

@@ -12,6 +12,7 @@ import type * as Deferred from "./Deferred.js"
 import type * as Duration from "./Duration.js"
 import type * as Either from "./Either.js"
 import type { Equivalence } from "./Equivalence.js"
+import type { ExecutionPlan } from "./ExecutionPlan.js"
 import type { ExecutionStrategy } from "./ExecutionStrategy.js"
 import type * as Exit from "./Exit.js"
 import type * as Fiber from "./Fiber.js"
@@ -32,6 +33,7 @@ import * as effect from "./internal/core-effect.js"
 import * as core from "./internal/core.js"
 import * as defaultServices from "./internal/defaultServices.js"
 import * as circular from "./internal/effect/circular.js"
+import * as internalExecutionPlan from "./internal/executionPlan.js"
 import * as fiberRuntime from "./internal/fiberRuntime.js"
 import * as layer from "./internal/layer.js"
 import * as option_ from "./internal/option.js"
@@ -4398,22 +4400,33 @@ export declare namespace Retry {
 export const retry: {
   <E, O extends NoExcessProperties<Retry.Options<E>, O>>(
     options: O
-  ): <A, R>(
-    self: Effect<A, E, R>
-  ) => Retry.Return<R, E, A, O>
-  <B, E, R1>(
-    policy: Schedule.Schedule<B, NoInfer<E>, R1>
-  ): <A, R>(self: Effect<A, E, R>) => Effect<A, E, R1 | R>
+  ): <A, R>(self: Effect<A, E, R>) => Retry.Return<R, E, A, O>
+  <B, E, R1>(policy: Schedule.Schedule<B, NoInfer<E>, R1>): <A, R>(self: Effect<A, E, R>) => Effect<A, E, R1 | R>
   <A, E, R, O extends NoExcessProperties<Retry.Options<E>, O>>(
     self: Effect<A, E, R>,
     options: O
   ): Retry.Return<R, E, A, O>
-  <A, E, R, B, R1>(
-    self: Effect<A, E, R>,
-    policy: Schedule.Schedule<B, E, R1>
-  ): Effect<A, E, R1 | R>
+  <A, E, R, B, R1>(self: Effect<A, E, R>, policy: Schedule.Schedule<B, NoInfer<E>, R1>): Effect<A, E, R1 | R>
 } = schedule_.retry_combined
 
+/**
+ * Apply an `ExecutionPlan` to the effect, which allows you to fallback to
+ * different resources in case of failure.
+ *
+ * @since 3.16.0
+ * @category Error handling
+ * @experimental
+ */
+export const withExecutionPlan: {
+  <Input, Provides, PlanE, PlanR>(
+    plan: 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>
+  <A, E extends Input, R, Provides, Input, PlanE, PlanR>(
+    effect: Effect<A, E, R>,
+    plan: ExecutionPlan<{ provides: Provides; input: Input; error: PlanE; requirements: PlanR }>
+  ): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
+} = internalExecutionPlan.withExecutionPlan
+
 /**
  * Retries a failing effect and runs a fallback effect if retries are exhausted.
  *
@@ -10348,7 +10361,7 @@ export const scheduleForked: {
     self: Effect<A, E, R>,
     schedule: Schedule.Schedule<Out, unknown, R2>
   ): Effect<Fiber.RuntimeFiber<Out, E>, never, Scope.Scope | R | R2>
-} = circular.scheduleForked
+} = schedule_.scheduleForked
 
 /**
  * Runs an effect repeatedly according to a schedule, starting from a specified