Add result decoder

Decoder to prevent error propagation. Always succeeds, but instead of
returning the decoded value, return a `Result` object containing either
the successfully decoded value, or the decoder failure error.

Author: Elias Mulhall

src/combinators.ts

@@ -56,5 +56,8 @@ export const succeed = Decoder.succeed;
 /** See `Decoder.fail` */
 export const fail = Decoder.fail;
 
+/** See `Decoder.result` */
+export const result = Decoder.result;
+
 /** See `Decoder.lazy` */
 export const lazy = Decoder.lazy;

src/decoder.ts

@@ -338,19 +338,8 @@ export class Decoder<A> {
    * array(array(boolean())).run([[true], [], [true, false, false]])
    * // => {ok: true, result: [[true], [], [true, false, false]]}
    *
-   *
-   * const validNumbersDecoder = array()
-   *   .map((arr: unknown[]) => arr.map(number().run))
-   *   .map(Result.successes)
-   *
-   * validNumbersDecoder.run([1, true, 2, 3, 'five', 4, []])
-   * // {ok: true, result: [1, 2, 3, 4]}
-   *
-   * validNumbersDecoder.run([false, 'hi', {}])
-   * // {ok: true, result: []}
-   *
-   * validNumbersDecoder.run(false)
-   * // {ok: false, error: {..., message: "expected an array, got a boolean"}}
+   * array().map(a => a.length).run(['a', true, 15, 'z'])
+   * // => {ok: true, result: 4}
    * ```
    */
   static array(): Decoder<unknown[]>;
@@ -642,6 +631,32 @@ export class Decoder<A> {
   static fail = <A>(errorMessage: string): Decoder<A> =>
     new Decoder((_, context) => decoderError(context, errorMessage));
 
+  /**
+   * Decoder to prevent error propagation. Always succeeds, but instead of
+   * returning the decoded value, return a `Result` object containing either
+   * the successfully decoded value, or the decoder failure error.
+   *
+   * Example:
+   * ```
+   * array(result(string())).run(['a', 1])
+   * // => {
+   * //   ok: true,
+   * //   result: [
+   * //     {ok: true, result: 'a'},
+   * //     {ok: false, error: {..., message: 'expected a string, got a number'}}
+   * //   ]
+   * // }
+   *
+   * array(result(number())).map(Result.successes).run([1, true, 2, 3, [], 4])
+   * // => {ok: true, result: [1, 2, 3, 4]}
+   *
+   * array(result(boolean())).run(false)
+   * // => {ok: false, error: {..., message: "expected an array, got a boolean"}}
+   * ```
+   */
+  static result = <A>(decoder: Decoder<A>): Decoder<DecoderResult<A>> =>
+    new Decoder((json: unknown) => Result.ok(decoder.run(json)));
+
   /**
    * Decoder that allows for validating recursive data structures. Unlike with
    * functions, decoders assigned to variables can't reference themselves

src/index.ts

@@ -22,5 +22,6 @@ export {
   valueAt,
   succeed,
   fail,
+  result,
   lazy
 } from './combinators';

test/json-decode.test.ts

@@ -20,6 +20,7 @@ import {
   valueAt,
   succeed,
   tuple,
+  result,
   fail,
   lazy
 } from '../src/index';
@@ -329,18 +330,18 @@ describe('array', () => {
   });
 
   it('decodes any array when the array members decoder is not specified', () => {
-    const validNumbersDecoder = array()
-      .map((arr: unknown[]) => arr.map(number().run))
-      .map(Result.successes);
-
-    expect(validNumbersDecoder.run([1, true, 2, 3, 'five', 4, []])).toEqual({
+    expect(array().run([1, true, 2, 3, 'five', 4, []])).toEqual({
       ok: true,
-      result: [1, 2, 3, 4]
+      result: [1, true, 2, 3, 'five', 4, []]
     });
 
-    expect(validNumbersDecoder.run([false, 'hi', {}])).toEqual({ok: true, result: []});
+    expect(
+      array()
+        .map(a => a.length)
+        .run(['a', true, 15, 'z'])
+    ).toEqual({ok: true, result: 4});
 
-    expect(validNumbersDecoder.run(false)).toMatchObject({
+    expect(array().run(false)).toMatchObject({
       ok: false,
       error: {message: 'expected an array, got a boolean'}
     });
@@ -778,6 +779,56 @@ describe('fail', () => {
   });
 });
 
+describe('result', () => {
+  describe('can decode properties of an object separately', () => {
+    type PropResults<T> = {[K in keyof T]: DecoderResult<T[K]>};
+    interface Book {
+      title: string;
+      author: string;
+      pageCount?: number;
+    }
+
+    const decoder: Decoder<PropResults<Book>> = object({
+      title: result(string()),
+      author: result(string()),
+      pageCount: result(optional(number()))
+    });
+
+    it('succeeds when given an object', () => {
+      const book = {title: 'The Only Harmless Great Thing', author: 'Brooke Bolander'};
+      expect(decoder.run(book)).toEqual({
+        ok: true,
+        result: {
+          author: {ok: true, result: 'Brooke Bolander'},
+          pageCount: {ok: true, result: undefined},
+          title: {ok: true, result: 'The Only Harmless Great Thing'}
+        }
+      });
+    });
+  });
+
+  describe('can decode items of an array separately', () => {
+    it('succeeds even when some array items fail to decode', () => {
+      const decoder = array(result(string()));
+      expect(decoder.run(['a', 1])).toMatchObject({
+        ok: true,
+        result: [
+          {ok: true, result: 'a'},
+          {ok: false, error: {message: 'expected a string, got a number'}}
+        ]
+      });
+    });
+
+    it('fails when the array decoder fails', () => {
+      const decoder = array(result(boolean()));
+      expect(decoder.run(false)).toMatchObject({
+        ok: false,
+        error: {message: 'expected an array, got a boolean'}
+      });
+    });
+  });
+});
+
 describe('lazy', () => {
   describe('decoding a primitive data type', () => {
     const decoder = lazy(() => string());