feat: ParseResult natural tranformations

Author: johannes-lindgren

packages/pure-parse/docs/guide/transformations.md

@@ -82,3 +82,14 @@ const parseUuid = recover(parseString, () => failure('A UUID must be a string'))
 formatResult(parseUuid('123e4567-e89b-12d3-a456-426614174000')) // -> ParseSuccess: 123e4567-e89b-12d3-a456-426614174000
 formatResult(parseUuid(123)) // -> ParseFailure: A UUID must be a string at $
 ```
+
+## Natural Transformations of `ParseResult`
+
+It's also possible to apply transformations on the `ParseResult` data type:
+
+| Function Name                                              | Use case                                                | Type Signature                                                                     |
+| ---------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| [mapResult](/api/utils/ParseResult.md#mapSuccess)          | Transform successful values                             | `(result: ParseResult<A>, fn: (A) => B) => ParseResult<B>`                         |
+| [mapFailure](/api/utils/ParseResult.md#mapFailure)         | Improve failure messages                                | `(result: ParseResult<A>, fn: (ParseFailure) => ParseFailure) => ParseResult<A>`   |
+| [flatMapResult](/api/utils/ParseResult.md#flatMapSuccess)  | Chain together a sequence of computations that may fail | `(result: ParseResult<A>, fn: (A) => ParseResult<B>) => ParseResult<B>`            |
+| [flatMapFailure](/api/utils/ParseResult.md#flatMapFailure) | Recover from failures                                   | `(result: ParseResult<A>, fn: (ParseFailure) => ParseResult<A>) => ParseResult<A>` |

packages/pure-parse/src/parsers/ParseResult.test.ts

@@ -8,6 +8,10 @@ import {
   ParseFailure,
   PathSegment,
   propagateFailure,
+  mapSuccess,
+  mapFailure,
+  flatMapSuccess,
+  flatMapFailure,
 } from './ParseResult'
 import { Equals } from '../internals'
 import { parseNumber } from './primitives'
@@ -144,4 +148,64 @@ describe('ParseResult', () => {
       })
     })
   })
+  describe('natural transformations', () => {
+    describe(mapSuccess, () => {
+      it('maps success values', () => {
+        const res = success(2)
+        const mapped = mapSuccess(res, (n) => n * 3)
+        expect(mapped).toEqual(success(6))
+      })
+      it('does not map failure values', () => {
+        const res = failure('Error occurred')
+        const mapped = mapSuccess(res, (n: number) => n * 3)
+        expect(mapped).toEqual(res)
+      })
+    })
+    describe(flatMapSuccess, () => {
+      it('allows chaining to another success', () => {
+        const res = parseNumber(5)
+        const flatMapped = flatMapSuccess(res, (n) => success(n * 2))
+        expect(flatMapped).toEqual(success(10))
+      })
+      it('allows chaining to failure', () => {
+        const res = parseNumber(5)
+        const flatMapped = flatMapSuccess(res, (n) =>
+          n > 10 ? success(n) : failure('Number is too small'),
+        )
+        expect(flatMapped).toEqual(failure('Number is too small'))
+      })
+    })
+    describe(mapFailure, () => {
+      it('maps failure values', () => {
+        const res = failure('Original error')
+        const mapped = mapFailure(res, (err) => ({
+          ...err,
+          message: 'Mapped error',
+        }))
+        expect(mapped).toEqual(failure('Mapped error'))
+      })
+      it('does not map success values', () => {
+        const res = success(42)
+        const mapped = mapFailure(res, (err) => ({
+          ...err,
+          message: 'Mapped error',
+        }))
+        expect(mapped).toEqual(res)
+      })
+    })
+    describe(flatMapFailure, () => {
+      it('allows recovery to success', () => {
+        const res = failure('Initial error')
+        const flatMapped = flatMapFailure(res, (err) => success(100))
+        expect(flatMapped).toEqual(success(100))
+      })
+      it('allows recovery to another failure', () => {
+        const res = failure('Initial error')
+        const flatMapped = flatMapFailure(res, (err) =>
+          failure(`Still failed: ${err.message}`),
+        )
+        expect(flatMapped).toEqual(failure('Still failed: Initial error'))
+      })
+    })
+  })
 })

packages/pure-parse/src/parsers/ParseResult.ts

@@ -141,3 +141,75 @@ export const propagateFailure = (
     path: [pathSegment, ...failureRes.error.path],
   },
 })
+
+/**
+ * Transform a successful result to a new value.
+ * @example
+ * Transform a successful parse result to a different type:
+ * ```ts
+ * const idResult = parseNumber(123)
+ * mapParseResult(idResult, (id) => id.toString()) // -> ParseSuccess<'123'>
+ * ```
+ * @see `map`
+ * @param result
+ * @param fn
+ */
+export const mapSuccess = <A, B>(
+  result: ParseResult<A>,
+  fn: (value: A) => B,
+): ParseResult<B> => (isSuccess(result) ? success(fn(result.value)) : result)
+
+/**
+ * Chain together a sequence of computations that may fail.
+ * @example
+ * ```
+ * const result = parseNumber(5)
+ * flatMapSuccess(result, (value) => success(value * 2)) // -> ParseSuccess<10>
+ * ```
+ * @see `chain`
+ * @param result
+ * @param fn
+ */
+export const flatMapSuccess = <T, U>(
+  result: ParseResult<T>,
+  fn: (value: T) => ParseResult<U>,
+): ParseResult<U> => (isSuccess(result) ? fn(result.value) : result)
+
+/**
+ * Transform a failure.
+ * @example
+ * An error contains too ambiguous information:
+ * ```ts
+ * const idResult = parseNumberFromString('abc')
+ * mapFailure(idResult, (error) => ({ message: 'An ID must be a number', path: error.path }))
+ * ```
+ * Map a failure result to a new value.
+ * @param result
+ * @param fn
+ */
+export const mapFailure = <T>(
+  result: ParseResult<T>,
+  fn: (failure: Failure) => Failure,
+): ParseResult<T> =>
+  isFailure(result)
+    ? {
+        tag: 'failure',
+        error: fn(result.error),
+      }
+    : result
+
+/**
+ * Recover from a failure by providing an alternative parsing result.
+ * @example
+ * ```
+ * const result = parseNumberFromString('abc')
+ * flatMapFailure(result, (error) => success(0)) // -> ParseSuccess<0>
+ * ```
+ * @see `withDefault`
+ * @param result
+ * @param fn
+ */
+export const flatMapFailure = <T>(
+  result: ParseResult<T>,
+  fn: (result: Failure) => ParseResult<T>,
+): ParseResult<T> => (isSuccess(result) ? result : fn(result.error))

packages/pure-parse/src/parsers/Parser.ts

@@ -52,13 +52,13 @@ export type UnsuccessfulParser = (data: unknown) => ParseFailure
  * parseToUpperCase(123) // -> ParseFailure
  * ```
  * @param parser
- * @param mapSuccess
+ * @param transformSuccess
  */
 export const map =
-  <A, B>(parser: Parser<A>, mapSuccess: (value: A) => B): Parser<B> =>
+  <A, B>(parser: Parser<A>, transformSuccess: (value: A) => B): Parser<B> =>
   (value) => {
     const result = parser(value)
-    return isSuccess(result) ? success(mapSuccess(result.value)) : result
+    return isSuccess(result) ? success(transformSuccess(result.value)) : result
   }
 
 /**