Add decoder method for testing constraints on a decoder

Author: Elias Mulhall

src/decoder.ts

@@ -666,4 +666,30 @@ export class Decoder<A> {
     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

@@ -771,6 +771,47 @@ describe('andThen', () => {
   });
 });
 
+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', () => {
   describe('can run a decoder with default value', () => {
     const decoder = number();