Merge pull request #24 from mojotech/em/where

Add `where` method for testing constraints on a decoder

Author: mulias

docs/classes/_decoder_.decoder.md

@@ -33,6 +33,7 @@ Alternatively, the main decoder `run()` method returns an object of type `Result
 * [run](_decoder_.decoder.md#run)
 * [runPromise](_decoder_.decoder.md#runpromise)
 * [runWithException](_decoder_.decoder.md#runwithexception)
+* [where](_decoder_.decoder.md#where)
 * [anyJson](_decoder_.decoder.md#anyjson)
 * [array](_decoder_.decoder.md#array)
 * [boolean](_decoder_.decoder.md#boolean)
@@ -104,9 +105,11 @@ ___
 
 ▸ **andThen**B(f: *`function`*): [Decoder](_decoder_.decoder.md)<`B`>
 
-Chain together a sequence of decoders. The first decoder will run, and then the function will determine what decoder to run second. If the result of the first decoder succeeds then `f` will be applied to the decoded value. If it fails the error will propagate through. One use case for `andThen` is returning a custom error message.
+Chain together a sequence of decoders. The first decoder will run, and then the function will determine what decoder to run second. If the result of the first decoder succeeds then `f` will be applied to the decoded value. If it fails the error will propagate through.
 
-Example:
+This is a very powerful method -- it can act as both the `map` and `where` methods, can improve error messages for edge cases, and can be used to make a decoder for custom types.
+
+Example of adding an error message:
 
 ```
 const versionDecoder = valueAt(['version'], number());
@@ -128,14 +131,24 @@ decoder.run({version: 5, x: 'abc'})
 // =>
 // {
 //   ok: false,
-//   error: {
-//     ...
-//     at: 'input',
-//     message: 'Unable to decode info, version 5 is not supported.'
-//   }
+//   error: {... message: 'Unable to decode info, version 5 is not supported.'}
 // }
 ```
 
+Example of decoding a custom type:
+
+```
+// nominal type for arrays with a length of at least one
+type NonEmptyArray<T> = T[] & { __nonEmptyArrayBrand__: void };
+
+const nonEmptyArrayDecoder = <T>(values: Decoder<T>): Decoder<NonEmptyArray<T>> =>
+  array(values).andThen(arr =>
+    arr.length > 0
+      ? succeed(createNonEmptyArray(arr))
+      : fail(`expected a non-empty array, got an empty array`)
+  );
+```
+
 **Type parameters:**
 
 #### B 
@@ -244,6 +257,41 @@ Run the decoder and return the value on success, or throw an exception with a fo
 
 **Returns:** `A`
 
+___
+<a id="where"></a>
+
+###  where
+
+▸ **where**(test: *`function`*, errorMessage: *`string`*): [Decoder](_decoder_.decoder.md)<`A`>
+
+Add constraints to a decoder _without_ changing the resulting type. The `test` argument is a predicate function which returns true for valid inputs. When `test` fails on an input, the decoder fails with the given `errorMessage`.
+
+```
+const chars = (length: number): Decoder<string> =>
+  string().where(
+    (s: string) => s.length === length,
+    `expected a string of length ${length}`
+  );
+
+chars(5).run('12345')
+// => {ok: true, result: '12345'}
+
+chars(2).run('HELLO')
+// => {ok: false, error: {... message: 'expected a string of length 2'}}
+
+chars(12).run(true)
+// => {ok: false, error: {... message: 'expected a string, got a boolean'}}
+```
+
+**Parameters:**
+
+| Param | Type |
+| ------ | ------ |
+| test | `function` |
+| errorMessage | `string` |
+
+**Returns:** [Decoder](_decoder_.decoder.md)<`A`>
+
 ___
 <a id="anyjson"></a>
 

src/decoder.ts

@@ -679,10 +679,13 @@ export class Decoder<A> {
    * Chain together a sequence of decoders. The first decoder will run, and
    * then the function will determine what decoder to run second. If the result
    * of the first decoder succeeds then `f` will be applied to the decoded
-   * value. If it fails the error will propagate through. One use case for
-   * `andThen` is returning a custom error message.
+   * value. If it fails the error will propagate through.
    *
-   * Example:
+   * This is a very powerful method -- it can act as both the `map` and `where`
+   * methods, can improve error messages for edge cases, and can be used to
+   * make a decoder for custom types.
+   *
+   * Example of adding an error message:
    * ```
    * const versionDecoder = valueAt(['version'], number());
    * const infoDecoder3 = object({a: boolean()});
@@ -703,16 +706,51 @@ export class Decoder<A> {
    * // =>
    * // {
    * //   ok: false,
-   * //   error: {
-   * //     ...
-   * //     at: 'input',
-   * //     message: 'Unable to decode info, version 5 is not supported.'
-   * //   }
+   * //   error: {... message: 'Unable to decode info, version 5 is not supported.'}
    * // }
    * ```
+   *
+   * Example of decoding a custom type:
+   * ```
+   * // nominal type for arrays with a length of at least one
+   * type NonEmptyArray<T> = T[] & { __nonEmptyArrayBrand__: void };
+   *
+   * const nonEmptyArrayDecoder = <T>(values: Decoder<T>): Decoder<NonEmptyArray<T>> =>
+   *   array(values).andThen(arr =>
+   *     arr.length > 0
+   *       ? succeed(createNonEmptyArray(arr))
+   *       : fail(`expected a non-empty array, got an empty array`)
+   *   );
+   * ```
    */
   andThen = <B>(f: (value: A) => Decoder<B>): Decoder<B> =>
     new Decoder<B>((json: any) =>
       Result.andThen(value => f(value).decode(json), this.decode(json))
     );
+
+  /**
+   * Add constraints to a decoder _without_ changing the resulting type. The
+   * `test` argument is a predicate function which returns true for valid
+   * inputs. When `test` fails on an input, the decoder fails with the given
+   * `errorMessage`.
+   *
+   * ```
+   * const chars = (length: number): Decoder<string> =>
+   *   string().where(
+   *     (s: string) => s.length === length,
+   *     `expected a string of length ${length}`
+   *   );
+   *
+   * chars(5).run('12345')
+   * // => {ok: true, result: '12345'}
+   *
+   * chars(2).run('HELLO')
+   * // => {ok: false, error: {... message: 'expected a string of length 2'}}
+   *
+   * chars(12).run(true)
+   * // => {ok: false, error: {... message: 'expected a string, got a boolean'}}
+   * ```
+   */
+  where = (test: (value: A) => boolean, errorMessage: string): Decoder<A> =>
+    this.andThen((value: A) => (test(value) ? Decoder.succeed(value) : Decoder.fail(errorMessage)));
 }

test/json-decode.test.ts

@@ -826,6 +826,70 @@ describe('andThen', () => {
       });
     });
   });
+
+  it('creates decoders for custom types', () => {
+    type NonEmptyArray<T> = T[] & {__nonEmptyArrayBrand__: void};
+    const createNonEmptyArray = <T>(arr: T[]): NonEmptyArray<T> => arr as NonEmptyArray<T>;
+
+    const nonEmptyArrayDecoder = <T>(values: Decoder<T>): Decoder<NonEmptyArray<T>> =>
+      array(values).andThen(
+        arr =>
+          arr.length > 0
+            ? succeed(createNonEmptyArray(arr))
+            : fail(`expected a non-empty array, got an empty array`)
+      );
+
+    expect(nonEmptyArrayDecoder(number()).run([1, 2, 3])).toEqual({
+      ok: true,
+      result: [1, 2, 3]
+    });
+
+    expect(nonEmptyArrayDecoder(number()).run([])).toMatchObject({
+      ok: false,
+      error: {message: 'expected a non-empty array, got an empty array'}
+    });
+  });
+});
+
+describe('where', () => {
+  const chars = (length: number): Decoder<string> =>
+    string().where((s: string) => s.length === length, `expected a string of length ${length}`);
+
+  const range = (min: number, max: number): Decoder<number> =>
+    number().where(
+      (n: number) => n >= min && n <= max,
+      `expected a number between ${min} and ${max}`
+    );
+
+  it('can test for strings of a given length', () => {
+    expect(chars(7).run('7777777')).toEqual({ok: true, result: '7777777'});
+
+    expect(chars(7).run('666666')).toMatchObject({
+      ok: false,
+      error: {message: 'expected a string of length 7'}
+    });
+  });
+
+  it('can test for numbers in a given range', () => {
+    expect(range(1, 9).run(7)).toEqual({ok: true, result: 7});
+
+    expect(range(1, 9).run(12)).toMatchObject({
+      ok: false,
+      error: {message: 'expected a number between 1 and 9'}
+    });
+  });
+
+  it('reports when the base decoder fails', () => {
+    expect(chars(7).run(false)).toMatchObject({
+      ok: false,
+      error: {message: 'expected a string, got a boolean'}
+    });
+
+    expect(range(0, 1).run(null)).toMatchObject({
+      ok: false,
+      error: {message: 'expected a number, got null'}
+    });
+  });
 });
 
 describe('Result', () => {