effect 3.3.5 → 3.4.1

package/dist/dts/Effect.d.ts

@@ -253,7 +253,7 @@ export declare const isEffect: (u: unknown) => u is Effect<unknown, unknown, unk
  *   yield* cached.pipe(Effect.andThen(Console.log))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // expensive task...
  * // result 1
@@ -297,7 +297,7 @@ export declare const cachedWithTTL: {
  *   yield* cached.pipe(Effect.andThen(Console.log))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // expensive task...
  * // result 1
@@ -340,7 +340,7 @@ export declare const cachedInvalidateWithTTL: {
  *   yield* cached.pipe(Effect.andThen(Console.log))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // non-cached version:
  * // expensive task...
@@ -376,7 +376,7 @@ export declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A
  *   console.log(yield* memoized(10))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Example Output:
  * // non-memoized version:
  * // 2
@@ -403,7 +403,7 @@ export declare const cachedFunction: <A, B, E, R>(f: (a: A) => Effect<B, E, R>,
  *   yield* Effect.repeatN(task2, 2)
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // task1
  * // task1
@@ -1539,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.
@@ -2975,8 +3001,27 @@ export declare const tap: {
     <A, E, R, X>(self: Effect<A, E, R>, f: NotFunction<X>): [X] extends [Effect<infer _A1, infer E1, infer R1>] ? Effect<A, E | E1, R | R1> : [X] extends [PromiseLike<infer _A1>] ? Effect<A, E | Cause.UnknownException, R> : Effect<A, E, R>;
 };
 /**
- * Returns an effect that effectfully "peeks" at the failure or success of
- * this effect.
+ * Inspects both success and failure outcomes of an effect, performing different actions based on the result.
+ *
+ * @example
+ * import { Effect, Random, Console } from "effect"
+ *
+ * // Simulate an effect that might fail
+ * const task = Effect.filterOrFail(
+ *   Random.nextRange(-1, 1),
+ *   (n) => n >= 0,
+ *   () => "random number is negative"
+ * )
+ *
+ * // Define an effect that logs both success and failure outcomes of the 'task'
+ * const tapping = Effect.tapBoth(task, {
+ *   onFailure: (error) => Console.log(`failure: ${error}`),
+ *   onSuccess: (randomNumber) => Console.log(`random number: ${randomNumber}`)
+ * })
+ *
+ * Effect.runFork(tapping)
+ * // Example Output:
+ * // failure: random number is negative
  *
  * @since 2.0.0
  * @category sequencing
@@ -2992,7 +3037,36 @@ export declare const tapBoth: {
     }): Effect<A, E | E2 | E3, R | R2 | R3>;
 };
 /**
- * Returns an effect that effectually "peeks" at the defect of this effect.
+ * Specifically inspects non-recoverable failures or defects in an effect (i.e., one or more `Die` causes).
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
+ *
+ * // this won't log anything because is not a defect
+ * const tapping1 = Effect.tapDefect(task1, (cause) =>
+ *   Console.log(`defect: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping1)
+ * // No Output
+ *
+ * // Simulate a severe failure in the system by causing a defect with a specific message.
+ * const task2: Effect.Effect<number, string> = Effect.dieMessage(
+ *   "Something went wrong"
+ * )
+ *
+ * // This will only log defects, not errors
+ * const tapping2 = Effect.tapDefect(task2, (cause) =>
+ *   Console.log(`defect: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping2)
+ * // Output:
+ * // defect: RuntimeException: Something went wrong
+ * //   ... stack trace ...
  *
  * @since 2.0.0
  * @category sequencing
@@ -3002,7 +3076,23 @@ export declare const tapDefect: {
     <A, E, R, X, E2, R2>(self: Effect<A, E, R>, f: (cause: Cause.Cause<never>) => Effect<X, E2, R2>): Effect<A, E | E2, R | R2>;
 };
 /**
- * Returns an effect that effectfully "peeks" at the failure of this effect.
+ * Executes an effectful operation to inspect the failure of an effect without altering it.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task: Effect.Effect<number, string> = Effect.fail("NetworkError")
+ *
+ * // Log the error message if the task fails. This function only executes if there is an error,
+ * // providing a method to handle or inspect errors without altering the outcome of the original effect.
+ * const tapping = Effect.tapError(task, (error) =>
+ *   Console.log(`expected error: ${error}`)
+ * )
+ *
+ * Effect.runFork(tapping)
+ * // Output:
+ * // expected error: NetworkError
  *
  * @since 2.0.0
  * @category sequencing
@@ -3012,7 +3102,33 @@ export declare const tapError: {
     <A, E, R, X, E2, R2>(self: Effect<A, E, R>, f: (e: E) => Effect<X, E2, R2>): Effect<A, E | E2, R | R2>;
 };
 /**
- * Returns an effect that effectfully "peeks" at the specific tagged failure of this effect.
+ * Specifically inspects a failure with a particular tag, allowing focused error handling.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * class NetworkError {
+ *   readonly _tag = "NetworkError"
+ *   constructor(readonly statusCode: number) {}
+ * }
+ * class ValidationError {
+ *   readonly _tag = "ValidationError"
+ *   constructor(readonly field: string) {}
+ * }
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task: Effect.Effect<number, NetworkError | ValidationError> =
+ *   Effect.fail(new NetworkError(504))
+ *
+ * // Apply an error handling function only to errors tagged as "NetworkError",
+ * // and log the corresponding status code of the error.
+ * const tapping = Effect.tapErrorTag(task, "NetworkError", (error) =>
+ *   Console.log(`expected error: ${error.statusCode}`)
+ * )
+ *
+ * Effect.runFork(tapping)
+ * // Output:
+ * // expected error: 504
  *
  * @since 2.0.0
  * @category sequencing
@@ -3030,8 +3146,37 @@ export declare const tapErrorTag: {
     }>) => Effect<A1, E1, R1>): Effect<A, E | E1, R | R1>;
 };
 /**
- * Returns an effect that effectually "peeks" at the cause of the failure of
- * this effect.
+ * Inspects the underlying cause of an effect's failure.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
+ *
+ * // This will log the cause of any expected error or defect
+ * const tapping1 = Effect.tapErrorCause(task1, (cause) =>
+ *   Console.log(`error cause: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping1)
+ * // Output:
+ * // error cause: Error: NetworkError
+ *
+ * // Simulate a severe failure in the system by causing a defect with a specific message.
+ * const task2: Effect.Effect<number, string> = Effect.dieMessage(
+ *   "Something went wrong"
+ * )
+ *
+ * // This will log the cause of any expected error or defect
+ * const tapping2 = Effect.tapErrorCause(task2, (cause) =>
+ *   Console.log(`error cause: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping2)
+ * // Output:
+ * // error cause: RuntimeException: Something went wrong
+ * //   ... stack trace ...
  *
  * @since 2.0.0
  * @category sequencing
@@ -3875,6 +4020,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
  */
@@ -3949,6 +4143,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
  */