PR 1762

Author: gcanti

docs/modules/Either.ts.md

@@ -1043,22 +1043,96 @@ Added in v3.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`.
+
 **Signature**
 
 ```ts
 export declare const getAltValidation: <E>(S: Semigroup<E>) => Alt2C<'Either', E>
 ```
 
+**Example**
+
+```ts
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+import * as S from 'fp-ts/Semigroup'
+import * as string from 'fp-ts/string'
+
+const parseString = (u: unknown): E.Either<string, string> =>
+  typeof u === 'string' ? E.right(u) : E.left('not a string')
+
+const parseNumber = (u: unknown): E.Either<string, number> =>
+  typeof u === 'number' ? E.right(u) : E.left('not a number')
+
+const parse = (u: unknown): E.Either<string, string | number> =>
+  pipe(
+    parseString(u),
+    E.alt<string, string | number>(() => parseNumber(u))
+  )
+
+assert.deepStrictEqual(parse(true), E.left('not a number')) // <= last error
+
+const Alt = E.getAltValidation(pipe(string.Semigroup, S.intercalate(', ')))
+
+const parseAll = (u: unknown): E.Either<string, string | number> =>
+  pipe(
+    parseString(u),
+    Alt.alt<string | number>(() => parseNumber(u))
+  )
+
+assert.deepStrictEqual(parseAll(true), E.left('not a string, not a number')) // <= all errors
+```
+
 Added in v3.0.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`.
+
 **Signature**
 
 ```ts
 export declare const getApplicativeValidation: <E>(S: Semigroup<E>) => Applicative2C<'Either', E>
 ```
 
+**Example**
+
+```ts
+import * as A from 'fp-ts/Apply'
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+import * as S from 'fp-ts/Semigroup'
+import * as string from 'fp-ts/string'
+
+const parseString = (u: unknown): E.Either<string, string> =>
+  typeof u === 'string' ? E.right(u) : E.left('not a string')
+
+const parseNumber = (u: unknown): E.Either<string, number> =>
+  typeof u === 'number' ? E.right(u) : E.left('not a number')
+
+interface Person {
+  readonly name: string
+  readonly age: number
+}
+
+const parsePerson = (input: Record<string, unknown>): E.Either<string, Person> =>
+  pipe(E.Do, E.apS('name', parseString(input.name)), E.apS('age', parseNumber(input.age)))
+
+assert.deepStrictEqual(parsePerson({}), E.left('not a string')) // <= first error
+
+const Applicative = E.getApplicativeValidation(pipe(string.Semigroup, S.intercalate(', ')))
+
+const apS = A.apS(Applicative)
+
+const parsePersonAll = (input: Record<string, unknown>): E.Either<string, Person> =>
+  pipe(E.Do, apS('name', parseString(input.name)), apS('age', parseNumber(input.age)))
+
+assert.deepStrictEqual(parsePersonAll({}), E.left('not a string, not a number')) // <= all errors
+```
+
 Added in v3.0.0
 
 ## getCompactable

docs/modules/IOEither.ts.md

@@ -901,6 +901,11 @@ Added in v3.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`.
+
+See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+
 **Signature**
 
 ```ts
@@ -911,6 +916,11 @@ Added in v3.0.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`.
+
+See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation).
+
 **Signature**
 
 ```ts

docs/modules/ReaderEither.ts.md

@@ -997,6 +997,11 @@ Added in v3.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`.
+
+See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+
 **Signature**
 
 ```ts
@@ -1007,6 +1012,11 @@ Added in v3.0.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`.
+
+See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation).
+
 **Signature**
 
 ```ts

docs/modules/ReaderTaskEither.ts.md

@@ -1464,6 +1464,11 @@ Added in v3.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`.
+
+See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+
 **Signature**
 
 ```ts
@@ -1474,6 +1479,11 @@ Added in v3.0.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`.
+
+See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation).
+
 **Signature**
 
 ```ts

docs/modules/TaskEither.ts.md

@@ -1138,6 +1138,11 @@ Added in v3.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`.
+
+See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+
 **Signature**
 
 ```ts
@@ -1148,6 +1153,11 @@ Added in v3.0.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).
+
 **Signature**
 
 ```ts

src/Either.ts

@@ -865,6 +865,55 @@ export const Applicative: Applicative2<URI> = {
 }
 
 /**
+ * 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`.
+ *
+ * @example
+ * import * as A from 'fp-ts/Apply'
+ * import * as E from 'fp-ts/Either'
+ * import { pipe } from 'fp-ts/function'
+ * import * as S from 'fp-ts/Semigroup'
+ * import * as string from 'fp-ts/string'
+ *
+ * const parseString = (u: unknown): E.Either<string, string> =>
+ *   typeof u === 'string' ? E.right(u) : E.left('not a string')
+ *
+ * const parseNumber = (u: unknown): E.Either<string, number> =>
+ *   typeof u === 'number' ? E.right(u) : E.left('not a number')
+ *
+ * interface Person {
+ *   readonly name: string
+ *   readonly age: number
+ * }
+ *
+ * const parsePerson = (
+ *   input: Record<string, unknown>
+ * ): E.Either<string, Person> =>
+ *   pipe(
+ *     E.Do,
+ *     E.apS('name', parseString(input.name)),
+ *     E.apS('age', parseNumber(input.age))
+ *   )
+ *
+ * assert.deepStrictEqual(parsePerson({}), E.left('not a string')) // <= first error
+ *
+ * const Applicative = E.getApplicativeValidation(
+ *   pipe(string.Semigroup, S.intercalate(', '))
+ * )
+ *
+ * const apS = A.apS(Applicative)
+ *
+ * const parsePersonAll = (
+ *   input: Record<string, unknown>
+ * ): E.Either<string, Person> =>
+ *   pipe(
+ *     E.Do,
+ *     apS('name', parseString(input.name)),
+ *     apS('age', parseNumber(input.age))
+ *   )
+ *
+ * assert.deepStrictEqual(parsePersonAll({}), E.left('not a string, not a number')) // <= all errors
+ *
  * @category instances
  * @since 3.0.0
  */
@@ -954,6 +1003,36 @@ export const Alt: Alt2<URI> = {
 }
 
 /**
+ * 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`.
+ *
+ * @example
+ * import * as E from 'fp-ts/Either'
+ * import { pipe } from 'fp-ts/function'
+ * import * as S from 'fp-ts/Semigroup'
+ * import * as string from 'fp-ts/string'
+ *
+ * const parseString = (u: unknown): E.Either<string, string> =>
+ *   typeof u === 'string' ? E.right(u) : E.left('not a string')
+ *
+ * const parseNumber = (u: unknown): E.Either<string, number> =>
+ *   typeof u === 'number' ? E.right(u) : E.left('not a number')
+ *
+ * const parse = (u: unknown): E.Either<string, string | number> =>
+ *   pipe(
+ *     parseString(u),
+ *     E.alt<string, string | number>(() => parseNumber(u))
+ *   )
+ *
+ * assert.deepStrictEqual(parse(true), E.left('not a number')) // <= last error
+ *
+ * const Alt = E.getAltValidation(pipe(string.Semigroup, S.intercalate(', ')))
+ *
+ * const parseAll = (u: unknown): E.Either<string, string | number> =>
+ *   pipe(parseString(u), Alt.alt<string | number>(() => parseNumber(u)))
+ *
+ * assert.deepStrictEqual(parseAll(true), E.left('not a string, not a number')) // <= all errors
+ *
  * @category instances
  * @since 3.0.0
  */

src/IOEither.ts

@@ -415,6 +415,11 @@ 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`.
+ *
+ * See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation).
+ *
  * @category instances
  * @since 3.0.0
  */
@@ -425,6 +430,11 @@ export const getApplicativeIOValidation = <E>(S: Semigroup<E>): Applicative2C<UR
 })
 
 /**
+ * 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`.
+ *
+ * See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+ *
  * @category instances
  * @since 3.0.0
  */

src/ReaderEither.ts

@@ -424,6 +424,11 @@ declare module './HKT' {
 }
 
 /**
+ * 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`.
+ *
+ * See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation).
+ *
  * @category instances
  * @since 3.0.0
  */
@@ -434,6 +439,11 @@ export const getApplicativeReaderValidation = <E>(S: Semigroup<E>): 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`.
+ *
+ * See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+ *
  * @category instances
  * @since 3.0.0
  */

src/ReaderTaskEither.ts

@@ -682,6 +682,11 @@ 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`.
+ *
+ * See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation).
+ *
  * @category instances
  * @since 3.0.0
  */
@@ -692,6 +697,11 @@ export const getApplicativeReaderTaskValidation = <E>(A: Apply1<T.URI>, 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`.
+ *
+ * See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+ *
  * @category instances
  * @since 3.0.0
  */

src/TaskEither.ts

@@ -636,6 +636,11 @@ 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`.
+ *
+ * See [`getApplicativeValidation`](./Either.ts.html#getapplicativevalidation).
+ *
  * @category instances
  * @since 3.0.0
  */
@@ -646,6 +651,11 @@ export const getApplicativeTaskValidation = <E>(A: Apply1<T.URI>, S: Semigroup<E
 })
 
 /**
+ * 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`.
+ *
+ * See [`getAltValidation`](./Either.ts.html#getaltvalidation).
+ *
  * @category instances
  * @since 3.0.0
  */