effect 4.0.0-rc.112 → 4.0.0-rc.113

package/src/Effect.ts

@@ -40,7 +40,7 @@ import { CurrentLogAnnotations, CurrentLogSpans } from "./References.ts"
 import type * as Request from "./Request.ts"
 import type { RequestResolver } from "./RequestResolver.ts"
 import type * as Result from "./Result.ts"
-import type { Schedule } from "./Schedule.ts"
+import type { Metadata as ScheduleMetadata, Schedule } from "./Schedule.ts"
 import type { Scheduler } from "./Scheduler.ts"
 import type { Scope } from "./Scope.ts"
 import type {
@@ -331,13 +331,8 @@ export declare namespace All {
           ] ? Mode extends true ? Result.Result<_A, _E> : _A
             : never
         },
-      Mode extends true ? never
-        : keyof T extends never ? never
-        : T[keyof T] extends Effect<infer _A, infer _E, infer _R> ? _E
-        : never,
-      keyof T extends never ? never
-        : T[keyof T] extends Effect<infer _A, infer _E, infer _R> ? _R
-        : never
+      Mode extends true ? never : Error<ObjectValues<T>>,
+      Services<ObjectValues<T>>
     >
     : never
 
@@ -377,6 +372,8 @@ export declare namespace All {
     : [Arg] extends [Iterable<EffectAny>] ? ReturnIterable<Arg, IsDiscard<O>, IsResult<O>>
     : [Arg] extends [Record<string, EffectAny>] ? ReturnObject<Arg, IsDiscard<O>, IsResult<O>>
     : never
+
+  type ObjectValues<T> = T extends unknown ? T[keyof T] : never
 }
 
 /**
@@ -1403,11 +1400,152 @@ export const promise: <A>(
  * @category constructors
  * @since 2.0.0
  */
-export const tryPromise: <A, E = Cause.UnknownError>(
-  options:
-    | { readonly try: (signal: AbortSignal) => PromiseLike<A>; readonly catch: (error: unknown) => E }
-    | ((signal: AbortSignal) => PromiseLike<A>)
-) => Effect<A, E> = internal.tryPromise
+export const tryPromise: {
+  /**
+   * Creates an `Effect` from an asynchronous computation that may throw or
+   * reject, mapping failures into the error channel.
+   *
+   * **When to use**
+   *
+   * Use when you need to perform asynchronous operations that might fail, such
+   * as fetching data from an API, and want thrown exceptions or rejected promises
+   * captured as Effect errors.
+   *
+   * **Details**
+   *
+   * The promise thunk is evaluated when the effect runs. If it returns a promise
+   * that resolves, the resolved value becomes the success value. If the thunk
+   * throws before returning a promise, or if the returned promise rejects, the
+   * thrown or rejected value is mapped into the error channel.
+   *
+   * Passing the thunk directly maps failures to {@link Cause.UnknownError}.
+   * Passing `{ try, catch }` uses `catch` to map failures to an error of type
+   * `E`.
+   *
+   * The thunk receives an `AbortSignal` that is aborted if the effect is
+   * interrupted. The underlying asynchronous operation only stops if it observes
+   * that signal.
+   *
+   * **Gotchas**
+   *
+   * If `catch` throws while mapping the error, that thrown value is treated as a
+   * defect. Return the error value you want in the error channel instead of
+   * throwing it.
+   *
+   * **Example** (Wrapping a fetch request that may fail)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   *
+   * const getTodo = (id: number) =>
+   *   Effect.tryPromise(() => Promise.resolve({ id, completed: false }))
+   *
+   * //      ┌─── Effect<{ id: number; completed: boolean }, UnknownError, never>
+   * //      ▼
+   * const program = getTodo(1)
+   * await Effect.runPromise(program) // => { id: 1, completed: false }
+   * ```
+   *
+   * **Example** (Mapping Promise rejections to a tagged error)
+   *
+   * ```ts import.meta.vitest
+   * import { Data, Effect } from "effect"
+   *
+   * class TodoFetchError extends Data.TaggedError("TodoFetchError")<{ readonly cause: unknown }> {}
+   *
+   * const getTodo = (id: number) =>
+   *   Effect.tryPromise({
+   *     try: () => Promise.reject(`Todo ${id} is unavailable`),
+   *     // remap the error
+   *     catch: (cause) => new TodoFetchError({ cause })
+   *   })
+   *
+   * //      ┌─── Effect<never, TodoFetchError, never>
+   * //      ▼
+   * const program = Effect.flip(getTodo(1))
+   * const error = await Effect.runPromise(program)
+   * error._tag // => "TodoFetchError"
+   * ```
+   *
+   * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
+   * @category constructors
+   * @since 2.0.0
+   */
+  <A>(options: (signal: AbortSignal) => PromiseLike<A>): Effect<A, Cause.UnknownError>
+  /**
+   * Creates an `Effect` from an asynchronous computation that may throw or
+   * reject, mapping failures into the error channel.
+   *
+   * **When to use**
+   *
+   * Use when you need to perform asynchronous operations that might fail, such
+   * as fetching data from an API, and want thrown exceptions or rejected promises
+   * captured as Effect errors.
+   *
+   * **Details**
+   *
+   * The promise thunk is evaluated when the effect runs. If it returns a promise
+   * that resolves, the resolved value becomes the success value. If the thunk
+   * throws before returning a promise, or if the returned promise rejects, the
+   * thrown or rejected value is mapped into the error channel.
+   *
+   * Passing the thunk directly maps failures to {@link Cause.UnknownError}.
+   * Passing `{ try, catch }` uses `catch` to map failures to an error of type
+   * `E`.
+   *
+   * The thunk receives an `AbortSignal` that is aborted if the effect is
+   * interrupted. The underlying asynchronous operation only stops if it observes
+   * that signal.
+   *
+   * **Gotchas**
+   *
+   * If `catch` throws while mapping the error, that thrown value is treated as a
+   * defect. Return the error value you want in the error channel instead of
+   * throwing it.
+   *
+   * **Example** (Wrapping a fetch request that may fail)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   *
+   * const getTodo = (id: number) =>
+   *   Effect.tryPromise(() => Promise.resolve({ id, completed: false }))
+   *
+   * //      ┌─── Effect<{ id: number; completed: boolean }, UnknownError, never>
+   * //      ▼
+   * const program = getTodo(1)
+   * await Effect.runPromise(program) // => { id: 1, completed: false }
+   * ```
+   *
+   * **Example** (Mapping Promise rejections to a tagged error)
+   *
+   * ```ts import.meta.vitest
+   * import { Data, Effect } from "effect"
+   *
+   * class TodoFetchError extends Data.TaggedError("TodoFetchError")<{ readonly cause: unknown }> {}
+   *
+   * const getTodo = (id: number) =>
+   *   Effect.tryPromise({
+   *     try: () => Promise.reject(`Todo ${id} is unavailable`),
+   *     // remap the error
+   *     catch: (cause) => new TodoFetchError({ cause })
+   *   })
+   *
+   * //      ┌─── Effect<never, TodoFetchError, never>
+   * //      ▼
+   * const program = Effect.flip(getTodo(1))
+   * const error = await Effect.runPromise(program)
+   * error._tag // => "TodoFetchError"
+   * ```
+   *
+   * @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
+   * @category constructors
+   * @since 2.0.0
+   */
+  <A, E>(
+    options: { readonly try: (signal: AbortSignal) => PromiseLike<A>; readonly catch: (error: unknown) => E }
+  ): Effect<A, E>
+} = internal.tryPromise
 
 /**
  * Creates an `Effect` that always succeeds with a given value.
@@ -2251,12 +2389,13 @@ export const failCauseSync: <E>(
  */
 export const die: (defect: unknown) => Effect<never> = internal.die
 
-const try_: <A, E = Cause.UnknownError>(
-  options: {
+const try_: {
+  <A>(options: LazyArg<A>): Effect<A, Cause.UnknownError>
+  <A, E>(options: {
     readonly try: LazyArg<A>
     readonly catch: (error: unknown) => E
-  } | LazyArg<A>
-) => Effect<A, E> = internal.try
+  }): Effect<A, E>
+} = internal.try
 
 export {
   /**
@@ -2393,6 +2532,26 @@ export const withFiber: <A, E = never, R = never>(
   evaluate: (fiber: Fiber<unknown, unknown>) => Effect<A, E, R>
 ) => Effect<A, E, R> = core.withFiber
 
+/**
+ * Accesses the current fiber to compute a successful value.
+ *
+ * **Example** (Computing a value from the current fiber)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.withFiberSucceed((fiber) => typeof fiber.id)
+ *
+ * Effect.runSync(program) // => "number"
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const withFiberSucceed: <A, R = never>(
+  evaluate: (fiber: Fiber<unknown, unknown>) => A
+) => Effect<A, never, R> = core.withFiberSucceed
+
 // -----------------------------------------------------------------------------
 // Conversions
 // -----------------------------------------------------------------------------
@@ -7012,7 +7171,7 @@ export const tapDefect: {
    * @category sequencing
    * @since 2.0.0
    */
-  <E, B, E2, R2>(f: (defect: unknown) => Effect<B, E2, R2>): <A, R>(self: Effect<A, E, R>) => Effect<A, E | E2, R | R2>
+  <B, E2, R2>(f: (defect: unknown) => Effect<B, E2, R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | E2, R | R2>
   /**
    * Runs an effectful operation when the source effect dies with a defect.
    *
@@ -8080,8 +8239,8 @@ export const withErrorReporting: <
 >(
   effectOrOptions: Arg,
   options?: { readonly defectsOnly?: boolean | undefined } | undefined
-) => [Arg] extends [Effect<infer _A, infer _E, infer _R>] ? Arg : <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> =
-  internal.withErrorReporting
+) => [Arg] extends [Effect<infer A, infer E, infer R>] ? Effect<A, E, R>
+  : <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> = internal.withErrorReporting
 
 // -----------------------------------------------------------------------------
 // Fallback
@@ -8473,21 +8632,8 @@ export const timeoutOption: {
 } = internal.timeoutOption
 
 /**
- * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
- *
- * **When to use**
- *
- * Use when a timeout of an `Effect` should switch to a fallback effect.
- *
- * **Details**
- *
- * The fallback effect is created lazily by `orElse` and may introduce its own
- * success, failure, and requirement types.
- *
- * **Gotchas**
- *
- * If the timeout wins, the source effect is interrupted before the fallback is
- * run.
+ * Applies a timeout to an effect, lazily evaluating `orElse` after interrupting
+ * the source if the timeout is reached.
  *
  * **Example** (Falling back on timeout)
  *
@@ -8514,21 +8660,8 @@ export const timeoutOption: {
  */
 export const timeoutOrElse: {
   /**
-   * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
-   *
-   * **When to use**
-   *
-   * Use when a timeout of an `Effect` should switch to a fallback effect.
-   *
-   * **Details**
-   *
-   * The fallback effect is created lazily by `orElse` and may introduce its own
-   * success, failure, and requirement types.
-   *
-   * **Gotchas**
-   *
-   * If the timeout wins, the source effect is interrupted before the fallback is
-   * run.
+   * Applies a timeout to an effect, lazily evaluating `orElse` after interrupting
+   * the source if the timeout is reached.
    *
    * **Example** (Falling back on timeout)
    *
@@ -8560,21 +8693,8 @@ export const timeoutOrElse: {
     }
   ): <A, E, R>(self: Effect<A, E, R>) => Effect<A | A2, E | E2, R | R2>
   /**
-   * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
-   *
-   * **When to use**
-   *
-   * Use when a timeout of an `Effect` should switch to a fallback effect.
-   *
-   * **Details**
-   *
-   * The fallback effect is created lazily by `orElse` and may introduce its own
-   * success, failure, and requirement types.
-   *
-   * **Gotchas**
-   *
-   * If the timeout wins, the source effect is interrupted before the fallback is
-   * run.
+   * Applies a timeout to an effect, lazily evaluating `orElse` after interrupting
+   * the source if the timeout is reached.
    *
    * **Example** (Falling back on timeout)
    *
@@ -13508,6 +13628,8 @@ export const onExitPrimitive: <A, E, R, XE = never, XR = never>(
  * Ensures that a cleanup function runs whether this effect succeeds, fails, or
  * is interrupted.
  *
+ * **Details**
+ *
  * If both the effect and the cleanup function fail, the two causes are merged.
  *
  * **Example** (Observing every exit)
@@ -13537,6 +13659,8 @@ export const onExit: {
    * Ensures that a cleanup function runs whether this effect succeeds, fails, or
    * is interrupted.
    *
+   * **Details**
+   *
    * If both the effect and the cleanup function fail, the two causes are merged.
    *
    * **Example** (Observing every exit)
@@ -13566,6 +13690,8 @@ export const onExit: {
    * Ensures that a cleanup function runs whether this effect succeeds, fails, or
    * is interrupted.
    *
+   * **Details**
+   *
    * If both the effect and the cleanup function fail, the two causes are merged.
    *
    * **Example** (Observing every exit)
@@ -15108,10 +15234,10 @@ export const repeat: {
  * const program = Effect.repeatOrElse(
  *   task,
  *   Schedule.recurs(3),
- *   (error, attempts) =>
+ *   (error, previous) =>
  *     Effect.sync(() => { output.push(
  *       `Final failure: ${error}, after ${
- *         Option.getOrElse(attempts, () => 0)
+ *         Option.isSome(previous) ? previous.value.attempt : 0
  *       } attempts`
  *     ) }).pipe(Effect.map(() => 0))
  * )
@@ -15160,10 +15286,10 @@ export const repeatOrElse: {
    * const program = Effect.repeatOrElse(
    *   task,
    *   Schedule.recurs(3),
-   *   (error, attempts) =>
+   *   (error, previous) =>
    *     Effect.sync(() => { output.push(
    *       `Final failure: ${error}, after ${
-   *         Option.getOrElse(attempts, () => 0)
+   *         Option.isSome(previous) ? previous.value.attempt : 0
    *       } attempts`
    *     ) }).pipe(Effect.map(() => 0))
    * )
@@ -15177,7 +15303,7 @@ export const repeatOrElse: {
    */
   <R2, A, B, E, E2, E3, R3>(
     schedule: Schedule<B, A, E2, R2>,
-    orElse: (error: E | E2, option: Option<B>) => Effect<B, E3, R3>
+    orElse: (error: E | E2, option: Option<ScheduleMetadata<B, A>>) => Effect<B, E3, R3>
   ): <R>(self: Effect<A, E, R>) => Effect<B, E3, R | R2 | R3>
   /**
    * Repeats an effect according to a schedule and runs a fallback effect if
@@ -15215,10 +15341,10 @@ export const repeatOrElse: {
    * const program = Effect.repeatOrElse(
    *   task,
    *   Schedule.recurs(3),
-   *   (error, attempts) =>
+   *   (error, previous) =>
    *     Effect.sync(() => { output.push(
    *       `Final failure: ${error}, after ${
-   *         Option.getOrElse(attempts, () => 0)
+   *         Option.isSome(previous) ? previous.value.attempt : 0
    *       } attempts`
    *     ) }).pipe(Effect.map(() => 0))
    * )
@@ -15233,7 +15359,7 @@ export const repeatOrElse: {
   <A, E, R, R2, B, E2, E3, R3>(
     self: Effect<A, E, R>,
     schedule: Schedule<B, A, E2, R2>,
-    orElse: (error: E | E2, option: Option<B>) => Effect<B, E3, R3>
+    orElse: (error: E | E2, option: Option<ScheduleMetadata<B, A>>) => Effect<B, E3, R3>
   ): Effect<B, E3, R | R2 | R3>
 } = internalSchedule.repeatOrElse
 
@@ -22864,14 +22990,10 @@ export const withLogSpan = dual<
 // -----------------------------------------------------------------------------
 
 /**
- * Updates the `Metric` every time the `Effect` is executed.
- *
- * **Details**
+ * Updates a metric after each effect execution, optionally mapping its `Exit` to
+ * the metric's input.
  *
- * Also accepts an optional function which can be used to map the `Exit` value
- * of the `Effect` into a valid `Input` for the `Metric`.
- *
- * **Example** (Incrementing a metric for each execution)
+ * **Example** (Counting executions)
  *
  * ```ts import.meta.vitest
  * import { Effect, Metric } from "effect"
@@ -22888,12 +23010,11 @@ export const withLogSpan = dual<
  * Effect.runSync(Metric.value(counter)).count // => 1
  * ```
  *
- * **Example** (Mapping exits before updating a metric)
+ * **Example** (Mapping exits)
  *
  * ```ts import.meta.vitest
  * import { Effect, Exit, Metric } from "effect"
  *
- * // Track different exit types with custom mapping
  * const exitTracker = Metric.frequency("exit_types", {
  *   description: "Tracks success/failure/defect counts"
  * })
@@ -22920,14 +23041,10 @@ export const track: {
   // -----------------------------------------------------------------------------
 
   /**
-   * Updates the `Metric` every time the `Effect` is executed.
-   *
-   * **Details**
-   *
-   * Also accepts an optional function which can be used to map the `Exit` value
-   * of the `Effect` into a valid `Input` for the `Metric`.
+   * Updates a metric after each effect execution, optionally mapping its `Exit` to
+   * the metric's input.
    *
-   * **Example** (Incrementing a metric for each execution)
+   * **Example** (Counting executions)
    *
    * ```ts import.meta.vitest
    * import { Effect, Metric } from "effect"
@@ -22944,12 +23061,11 @@ export const track: {
    * Effect.runSync(Metric.value(counter)).count // => 1
    * ```
    *
-   * **Example** (Mapping exits before updating a metric)
+   * **Example** (Mapping exits)
    *
    * ```ts import.meta.vitest
    * import { Effect, Exit, Metric } from "effect"
    *
-   * // Track different exit types with custom mapping
    * const exitTracker = Metric.frequency("exit_types", {
    *   description: "Tracks success/failure/defect counts"
    * })
@@ -22970,20 +23086,16 @@ export const track: {
    * @category metrics
    * @since 4.0.0
    */
-  <Input, State, E, A>(metric: Metric.Metric<Input, State>, f: (exit: Exit.Exit<A, E>) => Input): <E, R>(self: Effect<A, E, R>) => Effect<A, E, R>
+  <Input, State, E, A>(metric: Metric.Metric<Input, State>, f: (exit: Exit.Exit<A, E>) => Input): <E2 extends E, R>(self: Effect<A, E2, R>) => Effect<A, E2, R>
   // -----------------------------------------------------------------------------
   // Metrics
   // -----------------------------------------------------------------------------
 
   /**
-   * Updates the `Metric` every time the `Effect` is executed.
-   *
-   * **Details**
-   *
-   * Also accepts an optional function which can be used to map the `Exit` value
-   * of the `Effect` into a valid `Input` for the `Metric`.
+   * Updates a metric after each effect execution, optionally mapping its `Exit` to
+   * the metric's input.
    *
-   * **Example** (Incrementing a metric for each execution)
+   * **Example** (Counting executions)
    *
    * ```ts import.meta.vitest
    * import { Effect, Metric } from "effect"
@@ -23000,12 +23112,11 @@ export const track: {
    * Effect.runSync(Metric.value(counter)).count // => 1
    * ```
    *
-   * **Example** (Mapping exits before updating a metric)
+   * **Example** (Mapping exits)
    *
    * ```ts import.meta.vitest
    * import { Effect, Exit, Metric } from "effect"
    *
-   * // Track different exit types with custom mapping
    * const exitTracker = Metric.frequency("exit_types", {
    *   description: "Tracks success/failure/defect counts"
    * })
@@ -23032,14 +23143,10 @@ export const track: {
   // -----------------------------------------------------------------------------
 
   /**
-   * Updates the `Metric` every time the `Effect` is executed.
+   * Updates a metric after each effect execution, optionally mapping its `Exit` to
+   * the metric's input.
    *
-   * **Details**
-   *
-   * Also accepts an optional function which can be used to map the `Exit` value
-   * of the `Effect` into a valid `Input` for the `Metric`.
-   *
-   * **Example** (Incrementing a metric for each execution)
+   * **Example** (Counting executions)
    *
    * ```ts import.meta.vitest
    * import { Effect, Metric } from "effect"
@@ -23056,12 +23163,11 @@ export const track: {
    * Effect.runSync(Metric.value(counter)).count // => 1
    * ```
    *
-   * **Example** (Mapping exits before updating a metric)
+   * **Example** (Mapping exits)
    *
    * ```ts import.meta.vitest
    * import { Effect, Exit, Metric } from "effect"
    *
-   * // Track different exit types with custom mapping
    * const exitTracker = Metric.frequency("exit_types", {
    *   description: "Tracks success/failure/defect counts"
    * })
@@ -23092,14 +23198,10 @@ export const track: {
   // -----------------------------------------------------------------------------
 
   /**
-   * Updates the `Metric` every time the `Effect` is executed.
+   * Updates a metric after each effect execution, optionally mapping its `Exit` to
+   * the metric's input.
    *
-   * **Details**
-   *
-   * Also accepts an optional function which can be used to map the `Exit` value
-   * of the `Effect` into a valid `Input` for the `Metric`.
-   *
-   * **Example** (Incrementing a metric for each execution)
+   * **Example** (Counting executions)
    *
    * ```ts import.meta.vitest
    * import { Effect, Metric } from "effect"
@@ -23116,12 +23218,11 @@ export const track: {
    * Effect.runSync(Metric.value(counter)).count // => 1
    * ```
    *
-   * **Example** (Mapping exits before updating a metric)
+   * **Example** (Mapping exits)
    *
    * ```ts import.meta.vitest
    * import { Effect, Exit, Metric } from "effect"
    *
-   * // Track different exit types with custom mapping
    * const exitTracker = Metric.frequency("exit_types", {
    *   description: "Tracks success/failure/defect counts"
    * })
@@ -24647,6 +24748,9 @@ export declare namespace Effectify {
     : never
 }
 
+type EffectifyArgs<F extends (...args: Array<any>) => any> = Parameters<F> extends [...infer Args, any] ? Args
+  : Parameters<F>
+
 /**
  * Converts an error-first callback API into a function that returns an
  * `Effect`.
@@ -24807,7 +24911,7 @@ export const effectify: {
    */
   <F extends (...args: Array<any>) => any, E>(
     fn: F,
-    onError: (error: Effectify.EffectifyError<F>, args: Parameters<F>) => E
+    onError: (error: Effectify.EffectifyError<F>, args: EffectifyArgs<F>) => E
   ): Effectify.Effectify<F, E>
   /**
    * Converts an error-first callback API into a function that returns an
@@ -24863,8 +24967,8 @@ export const effectify: {
    */
   <F extends (...args: Array<any>) => any, E, E2>(
     fn: F,
-    onError: (error: Effectify.EffectifyError<F>, args: Parameters<F>) => E,
-    onSyncError: (error: unknown, args: Parameters<F>) => E2
+    onError: (error: Effectify.EffectifyError<F>, args: EffectifyArgs<F>) => E,
+    onSyncError: (error: unknown, args: EffectifyArgs<F>) => E2
   ): Effectify.Effectify<F, E | E2>
 } =
   (<A>(fn: Function, onError?: (e: any, args: any) => any, onSyncError?: (e: any, args: any) => any) =>