From ed2b205db201e79f91a1125273508eb27d4b879d Mon Sep 17 00:00:00 2001 From: gcanti Date: Thu, 8 Sep 2022 16:46:48 +0200 Subject: [PATCH] docs: add example to TaskEither.getApplicativeTaskValidation --- docs/modules/Either.ts.md | 4 +-- docs/modules/IOEither.ts.md | 4 +-- docs/modules/ReaderEither.ts.md | 4 +-- docs/modules/ReaderTaskEither.ts.md | 4 +-- docs/modules/TaskEither.ts.md | 52 ++++++++++++++++++++++++++--- src/Either.ts | 4 +-- src/IOEither.ts | 4 +-- src/ReaderEither.ts | 4 +-- src/ReaderTaskEither.ts | 4 +-- src/TaskEither.ts | 50 +++++++++++++++++++++++++-- 10 files changed, 111 insertions(+), 23 deletions(-) diff --git a/docs/modules/Either.ts.md b/docs/modules/Either.ts.md index a2015d197..9d0aecc7d 100644 --- a/docs/modules/Either.ts.md +++ b/docs/modules/Either.ts.md @@ -1196,7 +1196,7 @@ Added in v2.0.0 ## getAltValidation The default [`Alt`](#alt) instance returns the last error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. **Signature** @@ -1239,7 +1239,7 @@ Added in v2.7.0 ## getApplicativeValidation The default [`Applicative`](#applicative) instance returns the first error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. **Signature** diff --git a/docs/modules/IOEither.ts.md b/docs/modules/IOEither.ts.md index c1b20a450..53d72e887 100644 --- a/docs/modules/IOEither.ts.md +++ b/docs/modules/IOEither.ts.md @@ -990,7 +990,7 @@ Added in v2.0.0 ## getAltIOValidation The default [`Alt`](#alt) instance returns the last error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. See [`getAltValidation`](./Either.ts.html#getaltvalidation). @@ -1005,7 +1005,7 @@ Added in v2.7.0 ## getApplicativeIOValidation The default [`ApplicativePar`](#applicativepar) instance returns the first error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). diff --git a/docs/modules/ReaderEither.ts.md b/docs/modules/ReaderEither.ts.md index 17468a4fe..c4a496117 100644 --- a/docs/modules/ReaderEither.ts.md +++ b/docs/modules/ReaderEither.ts.md @@ -1089,7 +1089,7 @@ Added in v2.0.0 ## getAltReaderValidation The default [`Alt`](#alt) instance returns the last error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. See [`getAltValidation`](./Either.ts.html#getaltvalidation). @@ -1104,7 +1104,7 @@ Added in v2.7.0 ## getApplicativeReaderValidation The default [`Applicative`](#applicative) instance returns the first error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). diff --git a/docs/modules/ReaderTaskEither.ts.md b/docs/modules/ReaderTaskEither.ts.md index 28d426aab..ffceaddd0 100644 --- a/docs/modules/ReaderTaskEither.ts.md +++ b/docs/modules/ReaderTaskEither.ts.md @@ -1600,7 +1600,7 @@ Added in v2.0.0 ## getAltReaderTaskValidation The default [`Alt`](#alt) instance returns the last error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. See [`getAltValidation`](./Either.ts.html#getaltvalidation). @@ -1615,7 +1615,7 @@ Added in v2.7.0 ## getApplicativeReaderTaskValidation The default [`ApplicativePar`](#applicativepar) instance returns the first error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). diff --git a/docs/modules/TaskEither.ts.md b/docs/modules/TaskEither.ts.md index 50b41662d..b3c9e8dd9 100644 --- a/docs/modules/TaskEither.ts.md +++ b/docs/modules/TaskEither.ts.md @@ -1253,7 +1253,7 @@ Added in v2.0.0 ## getAltTaskValidation The default [`Alt`](#alt) instance returns the last error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. +get all errors you need to provide a way to concatenate them via a `Semigroup`. See [`getAltValidation`](./Either.ts.html#getaltvalidation). @@ -1268,9 +1268,7 @@ Added in v2.7.0 ## getApplicativeTaskValidation The default [`ApplicativePar`](#applicativepar) instance returns the first error, if you want to -get all errors you need to provide an way to concatenate them via a `Semigroup`. - -See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). +get all errors you need to provide a way to concatenate them via a `Semigroup`. **Signature** @@ -1278,6 +1276,52 @@ See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). export declare function getApplicativeTaskValidation(A: Apply1, S: Semigroup): Applicative2C ``` +**Example** + +```ts +import * as E from 'fp-ts/Either' +import { pipe } from 'fp-ts/function' +import * as RA from 'fp-ts/ReadonlyArray' +import * as S from 'fp-ts/Semigroup' +import * as string from 'fp-ts/string' +import * as T from 'fp-ts/Task' +import * as TE from 'fp-ts/TaskEither' + +interface User { + readonly id: string + readonly name: string +} + +const remoteDatabase: ReadonlyArray = [ + { id: 'id1', name: 'John' }, + { id: 'id2', name: 'Mary' }, + { id: 'id3', name: 'Joey' }, +] + +const fetchUser = (id: string): TE.TaskEither => + pipe( + remoteDatabase, + RA.findFirst((user) => user.id === id), + TE.fromOption(() => `${id} not found`) + ) + +async function test() { + assert.deepStrictEqual( + await pipe(['id4', 'id5'], RA.traverse(TE.ApplicativePar)(fetchUser))(), + E.left('id4 not found') // <= first error + ) + + const Applicative = TE.getApplicativeTaskValidation(T.ApplyPar, pipe(string.Semigroup, S.intercalate(', '))) + + assert.deepStrictEqual( + await pipe(['id4', 'id5'], RA.traverse(Applicative)(fetchUser))(), + E.left('id4 not found, id5 not found') // <= all errors + ) +} + +test() +``` + Added in v2.7.0 ## getCompactable diff --git a/src/Either.ts b/src/Either.ts index 704f7ee54..a3dc9509e 100644 --- a/src/Either.ts +++ b/src/Either.ts @@ -347,7 +347,7 @@ export const getWitherable = (M: Monoid): Witherable2C => { /** * The default [`Applicative`](#applicative) instance returns the first error, if you want to - * get all errors you need to provide an way to concatenate them via a `Semigroup`. + * get all errors you need to provide a way to concatenate them via a `Semigroup`. * * @example * import * as A from 'fp-ts/Apply' @@ -415,7 +415,7 @@ export const getApplicativeValidation = (SE: Semigroup): Applicative2C(S: Semigroup): Applicative2C(M: Monoid): Filterable3C { /** * The default [`Applicative`](#applicative) instance returns the first error, if you want to - * get all errors you need to provide an way to concatenate them via a `Semigroup`. + * get all errors you need to provide a way to concatenate them via a `Semigroup`. * * See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). * @@ -536,7 +536,7 @@ export function getApplicativeReaderValidation(S: Semigroup): Applicative3 /** * The default [`Alt`](#alt) instance returns the last error, if you want to - * get all errors you need to provide an way to concatenate them via a `Semigroup`. + * get all errors you need to provide a way to concatenate them via a `Semigroup`. * * See [`getAltValidation`](./Either.ts.html#getaltvalidation). * diff --git a/src/ReaderTaskEither.ts b/src/ReaderTaskEither.ts index ee5122526..038a301fa 100644 --- a/src/ReaderTaskEither.ts +++ b/src/ReaderTaskEither.ts @@ -784,7 +784,7 @@ export function getFilterable(M: Monoid): Filterable3C { /** * The default [`ApplicativePar`](#applicativepar) instance returns the first error, if you want to - * get all errors you need to provide an way to concatenate them via a `Semigroup`. + * get all errors you need to provide a way to concatenate them via a `Semigroup`. * * See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). * @@ -804,7 +804,7 @@ export function getApplicativeReaderTaskValidation(A: Apply1, S: Semig /** * The default [`Alt`](#alt) instance returns the last error, if you want to - * get all errors you need to provide an way to concatenate them via a `Semigroup`. + * get all errors you need to provide a way to concatenate them via a `Semigroup`. * * See [`getAltValidation`](./Either.ts.html#getaltvalidation). * diff --git a/src/TaskEither.ts b/src/TaskEither.ts index 4ef205974..da5aa43e2 100644 --- a/src/TaskEither.ts +++ b/src/TaskEither.ts @@ -682,9 +682,53 @@ declare module './HKT' { /** * The default [`ApplicativePar`](#applicativepar) instance returns the first error, if you want to - * get all errors you need to provide an way to concatenate them via a `Semigroup`. + * get all errors you need to provide a way to concatenate them via a `Semigroup`. * - * See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation). + * @example + * import * as E from 'fp-ts/Either' + * import { pipe } from 'fp-ts/function' + * import * as RA from 'fp-ts/ReadonlyArray' + * import * as S from 'fp-ts/Semigroup' + * import * as string from 'fp-ts/string' + * import * as T from 'fp-ts/Task' + * import * as TE from 'fp-ts/TaskEither' + * + * interface User { + * readonly id: string + * readonly name: string + * } + * + * const remoteDatabase: ReadonlyArray = [ + * { id: 'id1', name: 'John' }, + * { id: 'id2', name: 'Mary' }, + * { id: 'id3', name: 'Joey' } + * ] + * + * const fetchUser = (id: string): TE.TaskEither => + * pipe( + * remoteDatabase, + * RA.findFirst((user) => user.id === id), + * TE.fromOption(() => `${id} not found`) + * ) + * + * async function test() { + * assert.deepStrictEqual( + * await pipe(['id4', 'id5'], RA.traverse(TE.ApplicativePar)(fetchUser))(), + * E.left('id4 not found') // <= first error + * ) + * + * const Applicative = TE.getApplicativeTaskValidation( + * T.ApplyPar, + * pipe(string.Semigroup, S.intercalate(', ')) + * ) + * + * assert.deepStrictEqual( + * await pipe(['id4', 'id5'], RA.traverse(Applicative)(fetchUser))(), + * E.left('id4 not found, id5 not found') // <= all errors + * ) + * } + * + * test() * * @category instances * @since 2.7.0 @@ -702,7 +746,7 @@ export function getApplicativeTaskValidation(A: Apply1, S: Semigroup