effect 4.0.0-rc.113 → 4.0.0-rc.114

package/dist/Effect.d.ts

@@ -12949,8 +12949,8 @@ export declare const onExitFilter: {
  */
 export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
 /**
- * Returns an effect that caches its result for a specified `Duration`,
- * known as "timeToLive" (TTL).
+ * Returns an effect that caches its result for a fixed duration or a duration
+ * computed from its `Exit`, known as "timeToLive" (TTL).
  *
  * **When to use**
  *
@@ -12969,6 +12969,17 @@ export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A
  * After the specified duration has passed, the cache expires, and the effect
  * will be recomputed upon the next evaluation.
  *
+ * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+ * `Duration.Input`. The function runs once after each fresh computation,
+ * including failures, so successes and failures can have different TTLs. It
+ * does not run when the cache is created or when a cached result is reused.
+ * The callback also receives interruption exits, which are cached for the
+ * returned duration.
+ *
+ * The TTL starts when the computation completes. Concurrent callers share the
+ * pending computation. A zero TTL expires immediately, and an infinite TTL
+ * keeps the result indefinitely.
+ *
  * **Example** (Memoizing an effect with TTL)
  *
  * ```ts import.meta.vitest
@@ -12993,6 +13004,26 @@ export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A
  * output // => ["expensive task...", "result 1", "result 1", "result 1"]
  * ```
  *
+ * **Example** (Caching successes while retrying failures)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Exit } from "effect"
+ *
+ * let attempts = 0
+ * const task = Effect.suspend(() =>
+ *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+ * )
+ * const program = Effect.gen(function*() {
+ *   const cached = yield* task.pipe(
+ *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+ *   )
+ *   yield* Effect.exit(cached)
+ *   return yield* cached
+ * })
+ *
+ * Effect.runSync(program) // => 42
+ * ```
+ *
  * @see {@link cached} for a similar function that caches the result
  * indefinitely.
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -13002,8 +13033,8 @@ export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A
  */
 export declare const cachedWithTTL: {
     /**
-     * Returns an effect that caches its result for a specified `Duration`,
-     * known as "timeToLive" (TTL).
+     * Returns an effect that caches its result for a fixed duration or a duration
+     * computed from its `Exit`, known as "timeToLive" (TTL).
      *
      * **When to use**
      *
@@ -13022,6 +13053,17 @@ export declare const cachedWithTTL: {
      * After the specified duration has passed, the cache expires, and the effect
      * will be recomputed upon the next evaluation.
      *
+     * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+     * `Duration.Input`. The function runs once after each fresh computation,
+     * including failures, so successes and failures can have different TTLs. It
+     * does not run when the cache is created or when a cached result is reused.
+     * The callback also receives interruption exits, which are cached for the
+     * returned duration.
+     *
+     * The TTL starts when the computation completes. Concurrent callers share the
+     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * keeps the result indefinitely.
+     *
      * **Example** (Memoizing an effect with TTL)
      *
      * ```ts import.meta.vitest
@@ -13046,6 +13088,110 @@ export declare const cachedWithTTL: {
      * output // => ["expensive task...", "result 1", "result 1", "result 1"]
      * ```
      *
+     * **Example** (Caching successes while retrying failures)
+     *
+     * ```ts import.meta.vitest
+     * import { Effect, Exit } from "effect"
+     *
+     * let attempts = 0
+     * const task = Effect.suspend(() =>
+     *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+     * )
+     * const program = Effect.gen(function*() {
+     *   const cached = yield* task.pipe(
+     *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+     *   )
+     *   yield* Effect.exit(cached)
+     *   return yield* cached
+     * })
+     *
+     * Effect.runSync(program) // => 42
+     * ```
+     *
+     * @see {@link cached} for a similar function that caches the result
+     * indefinitely.
+     * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+     * additional effect for manually invalidating the cached value.
+     * @category caching
+     * @since 2.0.0
+     */
+    <A, E>(timeToLive: (exit: Exit.Exit<A, E>) => Duration.Input): <R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
+    /**
+     * Returns an effect that caches its result for a fixed duration or a duration
+     * computed from its `Exit`, known as "timeToLive" (TTL).
+     *
+     * **When to use**
+     *
+     * Use when you need a costly effect result to be reused for a bounded duration
+     * before being recomputed.
+     *
+     * **Details**
+     *
+     * This function is used to cache the result of an effect for a specified amount
+     * of time. This means that the first time the effect is evaluated, its result
+     * is computed and stored.
+     *
+     * If the effect is evaluated again within the specified `timeToLive`, the
+     * cached result will be used, avoiding recomputation.
+     *
+     * After the specified duration has passed, the cache expires, and the effect
+     * will be recomputed upon the next evaluation.
+     *
+     * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+     * `Duration.Input`. The function runs once after each fresh computation,
+     * including failures, so successes and failures can have different TTLs. It
+     * does not run when the cache is created or when a cached result is reused.
+     * The callback also receives interruption exits, which are cached for the
+     * returned duration.
+     *
+     * The TTL starts when the computation completes. Concurrent callers share the
+     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * keeps the result indefinitely.
+     *
+     * **Example** (Memoizing an effect with TTL)
+     *
+     * ```ts import.meta.vitest
+     * import { Effect } from "effect"
+     * const output: Array<unknown> = []
+     * const record = (value: unknown) => Effect.sync(() => { output.push(value) })
+     *
+     * let i = 1
+     * const expensiveTask = Effect.sync(() => {
+     *   void output.push("expensive task...")
+     *   return `result ${i++}`
+     * })
+     *
+     * const program = Effect.gen(function*() {
+     *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "1 hour")
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* cached.pipe(Effect.andThen(record))
+     * })
+     *
+     * Effect.runSync(program)
+     * output // => ["expensive task...", "result 1", "result 1", "result 1"]
+     * ```
+     *
+     * **Example** (Caching successes while retrying failures)
+     *
+     * ```ts import.meta.vitest
+     * import { Effect, Exit } from "effect"
+     *
+     * let attempts = 0
+     * const task = Effect.suspend(() =>
+     *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+     * )
+     * const program = Effect.gen(function*() {
+     *   const cached = yield* task.pipe(
+     *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+     *   )
+     *   yield* Effect.exit(cached)
+     *   return yield* cached
+     * })
+     *
+     * Effect.runSync(program) // => 42
+     * ```
+     *
      * @see {@link cached} for a similar function that caches the result
      * indefinitely.
      * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -13055,8 +13201,8 @@ export declare const cachedWithTTL: {
      */
     (timeToLive: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
     /**
-     * Returns an effect that caches its result for a specified `Duration`,
-     * known as "timeToLive" (TTL).
+     * Returns an effect that caches its result for a fixed duration or a duration
+     * computed from its `Exit`, known as "timeToLive" (TTL).
      *
      * **When to use**
      *
@@ -13075,6 +13221,17 @@ export declare const cachedWithTTL: {
      * After the specified duration has passed, the cache expires, and the effect
      * will be recomputed upon the next evaluation.
      *
+     * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+     * `Duration.Input`. The function runs once after each fresh computation,
+     * including failures, so successes and failures can have different TTLs. It
+     * does not run when the cache is created or when a cached result is reused.
+     * The callback also receives interruption exits, which are cached for the
+     * returned duration.
+     *
+     * The TTL starts when the computation completes. Concurrent callers share the
+     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * keeps the result indefinitely.
+     *
      * **Example** (Memoizing an effect with TTL)
      *
      * ```ts import.meta.vitest
@@ -13099,6 +13256,110 @@ export declare const cachedWithTTL: {
      * output // => ["expensive task...", "result 1", "result 1", "result 1"]
      * ```
      *
+     * **Example** (Caching successes while retrying failures)
+     *
+     * ```ts import.meta.vitest
+     * import { Effect, Exit } from "effect"
+     *
+     * let attempts = 0
+     * const task = Effect.suspend(() =>
+     *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+     * )
+     * const program = Effect.gen(function*() {
+     *   const cached = yield* task.pipe(
+     *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+     *   )
+     *   yield* Effect.exit(cached)
+     *   return yield* cached
+     * })
+     *
+     * Effect.runSync(program) // => 42
+     * ```
+     *
+     * @see {@link cached} for a similar function that caches the result
+     * indefinitely.
+     * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+     * additional effect for manually invalidating the cached value.
+     * @category caching
+     * @since 2.0.0
+     */
+    <A, E>(timeToLive: Duration.Input | ((exit: Exit.Exit<A, E>) => Duration.Input)): <R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
+    /**
+     * Returns an effect that caches its result for a fixed duration or a duration
+     * computed from its `Exit`, known as "timeToLive" (TTL).
+     *
+     * **When to use**
+     *
+     * Use when you need a costly effect result to be reused for a bounded duration
+     * before being recomputed.
+     *
+     * **Details**
+     *
+     * This function is used to cache the result of an effect for a specified amount
+     * of time. This means that the first time the effect is evaluated, its result
+     * is computed and stored.
+     *
+     * If the effect is evaluated again within the specified `timeToLive`, the
+     * cached result will be used, avoiding recomputation.
+     *
+     * After the specified duration has passed, the cache expires, and the effect
+     * will be recomputed upon the next evaluation.
+     *
+     * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+     * `Duration.Input`. The function runs once after each fresh computation,
+     * including failures, so successes and failures can have different TTLs. It
+     * does not run when the cache is created or when a cached result is reused.
+     * The callback also receives interruption exits, which are cached for the
+     * returned duration.
+     *
+     * The TTL starts when the computation completes. Concurrent callers share the
+     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * keeps the result indefinitely.
+     *
+     * **Example** (Memoizing an effect with TTL)
+     *
+     * ```ts import.meta.vitest
+     * import { Effect } from "effect"
+     * const output: Array<unknown> = []
+     * const record = (value: unknown) => Effect.sync(() => { output.push(value) })
+     *
+     * let i = 1
+     * const expensiveTask = Effect.sync(() => {
+     *   void output.push("expensive task...")
+     *   return `result ${i++}`
+     * })
+     *
+     * const program = Effect.gen(function*() {
+     *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "1 hour")
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* cached.pipe(Effect.andThen(record))
+     * })
+     *
+     * Effect.runSync(program)
+     * output // => ["expensive task...", "result 1", "result 1", "result 1"]
+     * ```
+     *
+     * **Example** (Caching successes while retrying failures)
+     *
+     * ```ts import.meta.vitest
+     * import { Effect, Exit } from "effect"
+     *
+     * let attempts = 0
+     * const task = Effect.suspend(() =>
+     *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+     * )
+     * const program = Effect.gen(function*() {
+     *   const cached = yield* task.pipe(
+     *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+     *   )
+     *   yield* Effect.exit(cached)
+     *   return yield* cached
+     * })
+     *
+     * Effect.runSync(program) // => 42
+     * ```
+     *
      * @see {@link cached} for a similar function that caches the result
      * indefinitely.
      * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -13106,7 +13367,7 @@ export declare const cachedWithTTL: {
      * @category caching
      * @since 2.0.0
      */
-    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input): Effect<Effect<A, E, R>>;
+    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input | ((exit: Exit.Exit<A, E>) => Duration.Input)): Effect<Effect<A, E, R>>;
 };
 /**
  * Creates a cached effect result for a specified duration and allows manual