effect 3.3.4 → 3.4.0

package/dist/dts/Effect.d.ts

@@ -228,8 +228,38 @@ export declare namespace Effect {
  */
 export declare const isEffect: (u: unknown) => u is Effect<unknown, unknown, unknown>;
 /**
- * Returns an effect that, if evaluated, will return the cached result of this
- * effect. Cached results will expire after `timeToLive` duration.
+ * Returns an effect that caches its result for a specified duration, known as
+ * the `timeToLive`. When the cache expires after the duration, the effect will be
+ * recomputed upon next evaluation.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * let i = 1
+ * const expensiveTask = Effect.promise<string>(() => {
+ *   console.log("expensive task...")
+ *   return new Promise((resolve) => {
+ *     setTimeout(() => {
+ *       resolve(`result ${i++}`)
+ *     }, 100)
+ *   })
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "150 millis")
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* Effect.sleep("100 millis")
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Output:
+ * // expensive task...
+ * // result 1
+ * // result 1
+ * // expensive task...
+ * // result 2
  *
  * @since 2.0.0
  * @category caching
@@ -239,10 +269,41 @@ export declare const cachedWithTTL: {
     <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.DurationInput): Effect<Effect<A, E>, never, R>;
 };
 /**
- * Returns an effect that, if evaluated, will return the cached result of this
- * effect. Cached results will expire after `timeToLive` duration. In
- * addition, returns an effect that can be used to invalidate the current
- * cached value before the `timeToLive` duration expires.
+ * Similar to {@link cachedWithTTL}, this function caches an effect's result for a
+ * specified duration. It also includes an additional effect for manually
+ * invalidating the cached value before it naturally expires.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * let i = 1
+ * const expensiveTask = Effect.promise<string>(() => {
+ *   console.log("expensive task...")
+ *   return new Promise((resolve) => {
+ *     setTimeout(() => {
+ *       resolve(`result ${i++}`)
+ *     }, 100)
+ *   })
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const [cached, invalidate] = yield* Effect.cachedInvalidateWithTTL(
+ *     expensiveTask,
+ *     "1 hour"
+ *   )
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* invalidate
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Output:
+ * // expensive task...
+ * // result 1
+ * // result 1
+ * // expensive task...
+ * // result 2
  *
  * @since 2.0.0
  * @category caching
@@ -252,39 +313,102 @@ export declare const cachedInvalidateWithTTL: {
     <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.DurationInput): Effect<[Effect<A, E>, Effect<void>], never, R>;
 };
 /**
- * Returns an effect that, if evaluated, will return the lazily computed
- * result of this effect.
+ * Returns an effect that computes a result lazily and caches it. Subsequent
+ * evaluations of this effect will return the cached result without re-executing
+ * the logic.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * let i = 1
+ * const expensiveTask = Effect.promise<string>(() => {
+ *   console.log("expensive task...")
+ *   return new Promise((resolve) => {
+ *     setTimeout(() => {
+ *       resolve(`result ${i++}`)
+ *     }, 100)
+ *   })
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   console.log("non-cached version:")
+ *   yield* expensiveTask.pipe(Effect.andThen(Console.log))
+ *   yield* expensiveTask.pipe(Effect.andThen(Console.log))
+ *   console.log("cached version:")
+ *   const cached = yield* Effect.cached(expensiveTask)
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Output:
+ * // non-cached version:
+ * // expensive task...
+ * // result 1
+ * // expensive task...
+ * // result 2
+ * // cached version:
+ * // expensive task...
+ * // result 3
+ * // result 3
  *
  * @since 2.0.0
  * @category caching
  */
 export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
 /**
- * Returns a memoized version of the specified effectual function.
+ * Returns a memoized version of a function with effects. Memoization ensures
+ * that results are stored and reused for the same inputs, reducing the need to
+ * recompute them.
+ *
+ * @example
+ * import { Effect, Random } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const randomNumber = (n: number) => Random.nextIntBetween(1, n)
+ *   console.log("non-memoized version:")
+ *   console.log(yield* randomNumber(10))
+ *   console.log(yield* randomNumber(10))
+ *
+ *   console.log("memoized version:")
+ *   const memoized = yield* Effect.cachedFunction(randomNumber)
+ *   console.log(yield* memoized(10))
+ *   console.log(yield* memoized(10))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Example Output:
+ * // non-memoized version:
+ * // 2
+ * // 8
+ * // memoized version:
+ * // 5
+ * // 5
  *
  * @since 2.0.0
  * @category caching
  */
 export declare const cachedFunction: <A, B, E, R>(f: (a: A) => Effect<B, E, R>, eq?: Equivalence<A>) => Effect<(a: A) => Effect<B, E, R>>;
 /**
- * Returns an effect that will be executed at most once, even if it is
- * evaluated multiple times.
+ * Returns an effect that executes only once, regardless of how many times it's
+ * called.
  *
  * @example
  * import { Effect, Console } from "effect"
  *
- * const program = Effect.gen(function* (_) {
- *   const twice = Console.log("twice")
- *   yield* _(twice, Effect.repeatN(1))
- *   const once = yield* _(Console.log("once"), Effect.once)
- *   yield* _(once, Effect.repeatN(1))
+ * const program = Effect.gen(function* () {
+ *   const task1 = Console.log("task1")
+ *   yield* Effect.repeatN(task1, 2)
+ *   const task2 = yield* Effect.once(Console.log("task2"))
+ *   yield* Effect.repeatN(task2, 2)
  * })
  *
  * Effect.runFork(program)
  * // Output:
- * // twice
- * // twice
- * // once
+ * // task1
+ * // task1
+ * // task1
+ * // task2
  *
  * @since 2.0.0
  * @category caching
@@ -1415,6 +1539,32 @@ export declare const uninterruptible: <A, E, R>(self: Effect<A, E, R>) => Effect
  * @category interruption
  */
 export declare const uninterruptibleMask: <A, E, R>(f: (restore: <AX, EX, RX>(effect: Effect<AX, EX, RX>) => Effect<AX, EX, RX>) => Effect<A, E, R>) => Effect<A, E, R>;
+/**
+ * Transforms a `Predicate` function into an `Effect` returning the input value if the predicate returns `true`
+ * or failing with specified error if the predicate fails
+ *
+ * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const isPositive = (n: number): boolean => n > 0
+ *
+ * // succeeds with `1`
+ * Effect.liftPredicate(1, isPositive, n => `${n} is not positive`)
+ *
+ * // fails with `"0 is not positive"`
+ * Effect.liftPredicate(0, isPositive, n => `${n} is not positive`)
+ *
+ * @category lifting
+ * @since 3.4.0
+ */
+export declare const liftPredicate: {
+    <A, B extends A, E>(refinement: Refinement<NoInfer<A>, B>, orFailWith: (a: NoInfer<A>) => E): (a: A) => Effect<B, E>;
+    <A, E>(predicate: Predicate<NoInfer<A>>, orFailWith: (a: NoInfer<A>) => E): (a: A) => Effect<A, E>;
+    <A, E, B extends A>(self: A, refinement: Refinement<A, B>, orFailWith: (a: A) => E): Effect<B, E>;
+    <A, E>(self: A, predicate: Predicate<NoInfer<A>>, orFailWith: (a: NoInfer<A>) => E): Effect<A, E>;
+};
 /**
  * This function maps the success value of an `Effect` value to a specified
  * constant value.
@@ -1758,7 +1908,7 @@ export declare const scope: Effect<Scope.Scope, never, Scope.Scope>;
  */
 export declare const scopeWith: <A, E, R>(f: (scope: Scope.Scope) => Effect<A, E, R>) => Effect<A, E, R | Scope.Scope>;
 /**
- * Scopes all resources uses in this workflow to the lifetime of the workflow,
+ * Scopes all resources used in this workflow to the lifetime of the workflow,
  * ensuring that their finalizers are run as soon as this workflow completes
  * execution, whether by success, failure, or interruption.
  *
@@ -3751,6 +3901,55 @@ export declare const validateWith: {
     } | undefined): Effect<C, E | E1, R | R1>;
 };
 /**
+ * The `Effect.zip` function allows you to combine two effects into a single
+ * effect. This combined effect yields a tuple containing the results of both
+ * input effects once they succeed.
+ *
+ * Note that `Effect.zip` processes effects sequentially: it first completes the
+ * effect on the left and then the effect on the right.
+ *
+ * If you want to run the effects concurrently, you can use the `concurrent` option.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const task1 = Effect.succeed(1).pipe(
+ *   Effect.delay("200 millis"),
+ *   Effect.tap(Effect.log("task1 done"))
+ * )
+ * const task2 = Effect.succeed("hello").pipe(
+ *   Effect.delay("100 millis"),
+ *   Effect.tap(Effect.log("task2 done"))
+ * )
+ *
+ * const task3 = Effect.zip(task1, task2)
+ *
+ * Effect.runPromise(task3).then(console.log)
+ * // Output:
+ * // timestamp=... level=INFO fiber=#0 message="task1 done"
+ * // timestamp=... level=INFO fiber=#0 message="task2 done"
+ * // [ 1, 'hello' ]
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const task1 = Effect.succeed(1).pipe(
+ *   Effect.delay("200 millis"),
+ *   Effect.tap(Effect.log("task1 done"))
+ * )
+ * const task2 = Effect.succeed("hello").pipe(
+ *   Effect.delay("100 millis"),
+ *   Effect.tap(Effect.log("task2 done"))
+ * )
+ *
+ * const task3 = Effect.zip(task1, task2, { concurrent: true })
+ *
+ * Effect.runPromise(task3).then(console.log)
+ * // Output:
+ * // timestamp=... level=INFO fiber=#0 message="task2 done"
+ * // timestamp=... level=INFO fiber=#0 message="task1 done"
+ * // [ 1, 'hello' ]
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -3825,6 +4024,35 @@ export declare const zipRight: {
     }): Effect<A2, E2 | E, R2 | R>;
 };
 /**
+ * The `Effect.zipWith` function operates similarly to {@link zip} by combining
+ * two effects. However, instead of returning a tuple, it allows you to apply a
+ * function to the results of the combined effects, transforming them into a
+ * single value
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const task1 = Effect.succeed(1).pipe(
+ *   Effect.delay("200 millis"),
+ *   Effect.tap(Effect.log("task1 done"))
+ * )
+ * const task2 = Effect.succeed("hello").pipe(
+ *   Effect.delay("100 millis"),
+ *   Effect.tap(Effect.log("task2 done"))
+ * )
+ *
+ * const task3 = Effect.zipWith(
+ *   task1,
+ *   task2,
+ *   (number, string) => number + string.length
+ * )
+ *
+ * Effect.runPromise(task3).then(console.log)
+ * // Output:
+ * // timestamp=... level=INFO fiber=#3 message="task1 done"
+ * // timestamp=... level=INFO fiber=#2 message="task2 done"
+ * // 6
+ *
  * @since 2.0.0
  * @category zipping
  */