From 551ffd671664a830d5a879f4ae7218a26c0d47dc Mon Sep 17 00:00:00 2001 From: Aymen Hmaidi Date: Fri, 10 Apr 2026 00:49:35 +0100 Subject: [PATCH] docs(TaskEither): clarify foldW vs matchW signature differences Explain that matchW handlers return plain values (auto-lifted to Task), while foldW handlers must return Task values. Also highlight the important difference from Either.foldW which expects plain-value handlers. Closes #1955 --- src/TaskEither.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/TaskEither.ts b/src/TaskEither.ts index 28235f17f..03cf8f0b9 100644 --- a/src/TaskEither.ts +++ b/src/TaskEither.ts @@ -163,6 +163,11 @@ export const match: (onLeft: (e: E) => B, onRight: (a: A) => B) => (ma: * * The `W` suffix (short for **W**idening) means that the handler return types will be merged. * + * Note: unlike [`foldW`](#foldw) (which is an alias of [`matchEW`](#matchew)), the handlers here return **plain values** + * (not `Task` values). The results are automatically lifted into `Task`. Use `matchW` when your handlers are pure + * functions. If your handlers need to perform async operations and return a `Task`, use [`foldW`](#foldw) / + * [`matchEW`](#matchew) instead. + * * @category pattern matching * @since 2.10.0 */ @@ -204,6 +209,14 @@ export const matchEW: ( /** * Alias of [`matchEW`](#matchew). * + * Note: unlike [`matchW`](#matchw) (where handlers return plain values), the handlers here must return **`Task` values**. + * This is useful when your error or success handlers themselves need to perform async operations. If your handlers are + * pure functions returning plain values, use [`matchW`](#matchw) instead. + * + * **Important**: despite the similar name, `foldW` in `TaskEither` behaves differently from `foldW` in `Either`. + * In `Either`, `foldW` is an alias of `matchW` and expects plain-value handlers. In `TaskEither`, `foldW` is an alias + * of `matchEW` and expects handlers that return `Task` values. + * * @category pattern matching * @since 2.10.0 */