effect 4.0.0-rc.118 → 4.0.1

package/dist/Effect.d.ts

@@ -391,13 +391,13 @@ export declare const all: <const Arg extends Iterable<Effect<any, any, any>> | R
     readonly mode?: "default" | "result" | undefined;
 }>(arg: Arg, options?: O) => All.Return<Arg, O>;
 /**
- * Applies an effectful function to each element and partitions failures and
- * successes.
+ * Applies an effectful function to each element and partitions successes and
+ * failures.
  *
  * **Details**
  *
- * The returned tuple is `[excluded, satisfying]`, where `excluded` contains
- * all failures and `satisfying` contains all successes.
+ * The returned tuple is `[passes, fails]`, where `passes` contains all
+ * successes and `fails` contains all failures.
  *
  * This function runs every effect and never fails. Use `concurrency` to control
  * parallelism.
@@ -411,7 +411,7 @@ export declare const all: <const Arg extends Iterable<Effect<any, any, any>> | R
  *   n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
  * )
  *
- * await Effect.runPromise(program) // => [['0 is even', '2 is even'], [1, 3]]
+ * await Effect.runPromise(program) // => [[1, 3], ['0 is even', '2 is even']]
  * ```
  *
  * @category collecting
@@ -419,13 +419,13 @@ export declare const all: <const Arg extends Iterable<Effect<any, any, any>> | R
  */
 export declare const partition: {
     /**
-     * Applies an effectful function to each element and partitions failures and
-     * successes.
+     * Applies an effectful function to each element and partitions successes and
+     * failures.
      *
      * **Details**
      *
-     * The returned tuple is `[excluded, satisfying]`, where `excluded` contains
-     * all failures and `satisfying` contains all successes.
+     * The returned tuple is `[passes, fails]`, where `passes` contains all
+     * successes and `fails` contains all failures.
      *
      * This function runs every effect and never fails. Use `concurrency` to control
      * parallelism.
@@ -439,7 +439,7 @@ export declare const partition: {
      *   n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
      * )
      *
-     * await Effect.runPromise(program) // => [['0 is even', '2 is even'], [1, 3]]
+     * await Effect.runPromise(program) // => [[1, 3], ['0 is even', '2 is even']]
      * ```
      *
      * @category collecting
@@ -447,15 +447,15 @@ export declare const partition: {
      */
     <A, B, E, R>(f: (a: A, i: number) => Effect<B, E, R>, options?: {
         readonly concurrency?: Concurrency | undefined;
-    }): (elements: Iterable<A>) => Effect<[excluded: Array<E>, satisfying: Array<B>], never, R>;
+    }): (elements: Iterable<A>) => Effect<[passes: Array<B>, fails: Array<E>], never, R>;
     /**
-     * Applies an effectful function to each element and partitions failures and
-     * successes.
+     * Applies an effectful function to each element and partitions successes and
+     * failures.
      *
      * **Details**
      *
-     * The returned tuple is `[excluded, satisfying]`, where `excluded` contains
-     * all failures and `satisfying` contains all successes.
+     * The returned tuple is `[passes, fails]`, where `passes` contains all
+     * successes and `fails` contains all failures.
      *
      * This function runs every effect and never fails. Use `concurrency` to control
      * parallelism.
@@ -469,7 +469,7 @@ export declare const partition: {
      *   n % 2 === 0 ? Effect.fail(`${n} is even`) : Effect.succeed(n)
      * )
      *
-     * await Effect.runPromise(program) // => [['0 is even', '2 is even'], [1, 3]]
+     * await Effect.runPromise(program) // => [[1, 3], ['0 is even', '2 is even']]
      * ```
      *
      * @category collecting
@@ -477,7 +477,7 @@ export declare const partition: {
      */
     <A, B, E, R>(elements: Iterable<A>, f: (a: A, i: number) => Effect<B, E, R>, options?: {
         readonly concurrency?: Concurrency | undefined;
-    }): Effect<[excluded: Array<E>, satisfying: Array<B>], never, R>;
+    }): Effect<[passes: Array<B>, fails: Array<E>], never, R>;
 };
 /**
  * Reduces elements from left to right with an effectful accumulator function.
@@ -12919,6 +12919,11 @@ export declare const onExitFilter: {
  * evaluations of the same effect will return the cached result without
  * re-executing the logic.
  *
+ * Concurrent callers share the pending computation, which is interrupted only
+ * once every caller waiting on it has been interrupted. Interrupted
+ * computations are never cached, so the next evaluation starts a fresh
+ * computation.
+ *
  * **Example** (Memoizing an effect until invalidated)
  *
  * ```ts import.meta.vitest
@@ -12979,11 +12984,12 @@ export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A
  * `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.
+ * Interrupted computations are never cached and do not call the function.
  *
  * The TTL starts when the computation completes. Concurrent callers share the
- * pending computation. A zero TTL expires immediately, and an infinite TTL
+ * pending computation, which is interrupted only once every caller waiting on
+ * it has been interrupted. The next evaluation then starts a fresh
+ * computation. A zero TTL expires immediately, and an infinite TTL
  * keeps the result indefinitely.
  *
  * **Example** (Memoizing an effect with TTL)
@@ -13063,11 +13069,12 @@ export declare const cachedWithTTL: {
      * `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.
+     * Interrupted computations are never cached and do not call the function.
      *
      * The TTL starts when the computation completes. Concurrent callers share the
-     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * pending computation, which is interrupted only once every caller waiting on
+     * it has been interrupted. The next evaluation then starts a fresh
+     * computation. A zero TTL expires immediately, and an infinite TTL
      * keeps the result indefinitely.
      *
      * **Example** (Memoizing an effect with TTL)
@@ -13147,11 +13154,12 @@ export declare const cachedWithTTL: {
      * `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.
+     * Interrupted computations are never cached and do not call the function.
      *
      * The TTL starts when the computation completes. Concurrent callers share the
-     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * pending computation, which is interrupted only once every caller waiting on
+     * it has been interrupted. The next evaluation then starts a fresh
+     * computation. A zero TTL expires immediately, and an infinite TTL
      * keeps the result indefinitely.
      *
      * **Example** (Memoizing an effect with TTL)
@@ -13231,11 +13239,12 @@ export declare const cachedWithTTL: {
      * `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.
+     * Interrupted computations are never cached and do not call the function.
      *
      * The TTL starts when the computation completes. Concurrent callers share the
-     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * pending computation, which is interrupted only once every caller waiting on
+     * it has been interrupted. The next evaluation then starts a fresh
+     * computation. A zero TTL expires immediately, and an infinite TTL
      * keeps the result indefinitely.
      *
      * **Example** (Memoizing an effect with TTL)
@@ -13315,11 +13324,12 @@ export declare const cachedWithTTL: {
      * `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.
+     * Interrupted computations are never cached and do not call the function.
      *
      * The TTL starts when the computation completes. Concurrent callers share the
-     * pending computation. A zero TTL expires immediately, and an infinite TTL
+     * pending computation, which is interrupted only once every caller waiting on
+     * it has been interrupted. The next evaluation then starts a fresh
+     * computation. A zero TTL expires immediately, and an infinite TTL
      * keeps the result indefinitely.
      *
      * **Example** (Memoizing an effect with TTL)
@@ -13376,8 +13386,8 @@ export declare const cachedWithTTL: {
     <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
- * invalidation before expiration.
+ * Creates a cached effect result for a fixed duration or a duration computed
+ * from its `Exit` and allows manual invalidation before expiration.
  *
  * **When to use**
  *
@@ -13435,8 +13445,67 @@ export declare const cachedWithTTL: {
  */
 export declare const cachedInvalidateWithTTL: {
     /**
-     * Creates a cached effect result for a specified duration and allows manual
-     * invalidation before expiration.
+     * Creates a cached effect result for a fixed duration or a duration computed
+     * from its `Exit` and allows manual invalidation before expiration.
+     *
+     * **When to use**
+     *
+     * Use when an effect result should be cached for a bounded time and callers
+     * also need a manual invalidation effect to force recomputation before
+     * expiration.
+     *
+     * **Details**
+     *
+     * This function behaves similarly to {@link cachedWithTTL} by caching the
+     * result of an effect for a specified period of time. However, it introduces an
+     * additional feature: it provides an effect that allows you to manually
+     * invalidate the cached result before it naturally expires.
+     *
+     * This gives you more control over the cache, allowing you to refresh the
+     * result when needed, even if the original cache has not yet expired.
+     *
+     * Once the cache is invalidated, the next time the effect is evaluated, the
+     * result will be recomputed, and the cache will be refreshed.
+     *
+     * **Example** (Memoizing with TTL and invalidation)
+     *
+     * ```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, invalidate] = yield* Effect.cachedInvalidateWithTTL(
+     *     expensiveTask,
+     *     "1 hour"
+     *   )
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* invalidate
+     *   yield* cached.pipe(Effect.andThen(record))
+     * })
+     *
+     * Effect.runSync(program)
+     * output // => ["expensive task...", "result 1", "result 1", "expensive task...", "result 2"]
+     * ```
+     *
+     * @see {@link cached} for a similar function that caches the result
+     * indefinitely.
+     * @see {@link cachedWithTTL} for a similar function that caches the result for
+     * a specified duration but does not include an effect for manual invalidation.
+     * @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>, Effect<void>]>;
+    /**
+     * Creates a cached effect result for a fixed duration or a duration computed
+     * from its `Exit` and allows manual invalidation before expiration.
      *
      * **When to use**
      *
@@ -13494,8 +13563,67 @@ export declare const cachedInvalidateWithTTL: {
      */
     (timeToLive: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<[Effect<A, E, R>, Effect<void>]>;
     /**
-     * Creates a cached effect result for a specified duration and allows manual
-     * invalidation before expiration.
+     * Creates a cached effect result for a fixed duration or a duration computed
+     * from its `Exit` and allows manual invalidation before expiration.
+     *
+     * **When to use**
+     *
+     * Use when an effect result should be cached for a bounded time and callers
+     * also need a manual invalidation effect to force recomputation before
+     * expiration.
+     *
+     * **Details**
+     *
+     * This function behaves similarly to {@link cachedWithTTL} by caching the
+     * result of an effect for a specified period of time. However, it introduces an
+     * additional feature: it provides an effect that allows you to manually
+     * invalidate the cached result before it naturally expires.
+     *
+     * This gives you more control over the cache, allowing you to refresh the
+     * result when needed, even if the original cache has not yet expired.
+     *
+     * Once the cache is invalidated, the next time the effect is evaluated, the
+     * result will be recomputed, and the cache will be refreshed.
+     *
+     * **Example** (Memoizing with TTL and invalidation)
+     *
+     * ```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, invalidate] = yield* Effect.cachedInvalidateWithTTL(
+     *     expensiveTask,
+     *     "1 hour"
+     *   )
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* cached.pipe(Effect.andThen(record))
+     *   yield* invalidate
+     *   yield* cached.pipe(Effect.andThen(record))
+     * })
+     *
+     * Effect.runSync(program)
+     * output // => ["expensive task...", "result 1", "result 1", "expensive task...", "result 2"]
+     * ```
+     *
+     * @see {@link cached} for a similar function that caches the result
+     * indefinitely.
+     * @see {@link cachedWithTTL} for a similar function that caches the result for
+     * a specified duration but does not include an effect for manual invalidation.
+     * @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>, Effect<void>]>;
+    /**
+     * Creates a cached effect result for a fixed duration or a duration computed
+     * from its `Exit` and allows manual invalidation before expiration.
      *
      * **When to use**
      *
@@ -13551,7 +13679,7 @@ export declare const cachedInvalidateWithTTL: {
      * @category caching
      * @since 2.0.0
      */
-    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input): Effect<[Effect<A, E, R>, Effect<void>]>;
+    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input | ((exit: Exit.Exit<A, E>) => Duration.Input)): Effect<[Effect<A, E, R>, Effect<void>]>;
 };
 /**
  * Returns an effect that is immediately interrupted.