implement OptionalDecoder class to replace optional

Author: Elias Mulhall

src/combinators.ts

@@ -1,4 +1,4 @@
-import {Decoder} from './decoder';
+import {Decoder, OptionalDecoder} from './decoder';
 
 /** See `Decoder.string` */
 export function string(): Decoder<string> {
@@ -36,7 +36,7 @@ export const array: <A>(decoder: Decoder<A>) => Decoder<A[]> = Decoder.array;
 export const dict: <A>(decoder: Decoder<A>) => Decoder<{[name: string]: A}> = Decoder.dict;
 
 /** See `Decoder.optional` */
-export const optional = Decoder.optional;
+export const optional = OptionalDecoder.optional;
 
 /** See `Decoder.oneOf` */
 export const oneOf: <A>(...decoders: Decoder<A>[]) => Decoder<A> = Decoder.oneOf;

src/decoder.ts

@@ -14,25 +14,44 @@ export interface DecoderError {
 }
 
 /**
- * Defines a mapped type over an interface `A`. `DecoderObject<A>` is an
- * interface that has all the keys or `A`, but each key's property type is
- * mapped to a decoder for that type. This type is used when creating decoders
- * for objects.
+ * Helper type with no semantic meaning, used as part of a trick in
+ * `DecoderObject` to distinguish between optional properties and properties
+ * that may have a value of undefined, but aren't optional.
+ */
+type HideUndefined<T> = {};
+
+/**
+ * Defines a mapped type over an interface `A`. This type is used when creating
+ * decoders for objects.
+ *
+ * `DecoderObject<A>` is an interface that has all the properties or `A`, but
+ * each property's type is mapped to a decoder for that type. If a property is
+ * required in `A`, the decoder type is `Decoder<proptype>`. If a property is
+ * optional in `A`, then that property is required in `DecoderObject<A>`, but
+ * the decoder type is `OptionalDecoder<proptype> | Decoder<proptype>`.
+ *
+ * The `OptionalDecoder` type is only returned by the `optional` decoder.
  *
  * Example:
  * ```
- * interface X {
+ * interface ABC {
  *   a: boolean;
- *   b: string;
+ *   b?: string;
+ *   c: number | undefined;
  * }
  *
- * const decoderObject: DecoderObject<X> = {
- *   a: boolean(),
- *   b: string()
+ * DecoderObject<ABC> === {
+ *   a: Decoder<boolean>;
+ *   b: OptionalDecoder<string> | Decoder<string>;
+ *   c: Decoder<number | undefined>;
  * }
  * ```
  */
-export type DecoderObject<A> = {[t in keyof A]: Decoder<A[t]>};
+export type DecoderObject<T> = {
+  [P in keyof T]-?: undefined extends {[Q in keyof T]: HideUndefined<T[Q]>}[P]
+    ? OptionalDecoder<Exclude<T[P], undefined>> | Decoder<Exclude<T[P], undefined>>
+    : Decoder<T[P]>
+};
 
 /**
  * Type guard for `DecoderError`. One use case of the type guard is in the
@@ -112,6 +131,7 @@ const prependAt = (newAt: string, {at, ...rest}: Partial<DecoderError>): Partial
  * things with a `Result` as with the decoder methods.
  */
 export class Decoder<A> {
+  readonly _kind = 'Decoder';
   /**
    * The Decoder class constructor is kept private to separate the internal
    * `decode` function from the external `run` function. The distinction
@@ -280,15 +300,17 @@ export class Decoder<A> {
         let obj: any = {};
         for (const key in decoders) {
           if (decoders.hasOwnProperty(key)) {
-            const r = decoders[key].decode(json[key]);
-            if (r.ok === true) {
-              // tslint:disable-next-line:strict-type-predicates
-              if (r.result !== undefined) {
-                obj[key] = r.result;
-              }
-            } else if (json[key] === undefined) {
+            // hack: type as any to access the private `decode` method on OptionalDecoder
+            const decoder: any = decoders[key];
+            const r = decoder.decode(json[key]);
+            if (
+              (r.ok === true && decoder._kind === 'Decoder') ||
+              (r.ok === true && decoder._kind === 'OptionalDecoder' && r.result !== undefined)
+            ) {
+              obj[key] = r.result;
+            } else if (r.ok === false && json[key] === undefined) {
               return Result.err({message: `the key '${key}' is required but was not present`});
-            } else {
+            } else if (r.ok === false) {
               return Result.err(prependAt(`.${key}`, r.error));
             }
           }
@@ -363,28 +385,6 @@ export class Decoder<A> {
       }
     });
 
-  /**
-   * Decoder for values that may be `undefined`. This is primarily helpful for
-   * decoding interfaces with optional fields.
-   *
-   * Example:
-   * ```
-   * interface User {
-   *   id: number;
-   *   isOwner?: boolean;
-   * }
-   *
-   * const decoder: Decoder<User> = object({
-   *   id: number(),
-   *   isOwner: optional(boolean())
-   * });
-   * ```
-   */
-  static optional = <A>(decoder: Decoder<A>): Decoder<undefined | A> =>
-    new Decoder<undefined | A>(
-      (json: any) => (json === undefined ? Result.ok(undefined) : decoder.decode(json))
-    );
-
   /**
    * Decoder that attempts to run each decoder in `decoders` and either succeeds
    * with the first successful decoder, or fails after all decoders have failed.
@@ -655,3 +655,34 @@ export class Decoder<A> {
       Result.andThen(value => f(value).decode(json), this.decode(json))
     );
 }
+
+export class OptionalDecoder<A> {
+  readonly _kind = 'OptionalDecoder';
+
+  private constructor(
+    private decode: (json: any) => Result.Result<A | undefined, Partial<DecoderError>>
+  ) {}
+
+  static optional = <A>(decoder: Decoder<A>): OptionalDecoder<A> =>
+    new OptionalDecoder(
+      // hack: type decoder as any to access the private `decode` method on Decoder
+      (json: any) => (json === undefined ? Result.ok(undefined) : (decoder as any).decode(json))
+    );
+
+  map = <B>(f: (value: A) => B): OptionalDecoder<B> =>
+    new OptionalDecoder<B>((json: any) =>
+      Result.map(
+        (value: A | undefined) => (value === undefined ? undefined : f(value)),
+        this.decode(json)
+      )
+    );
+
+  andThen = <B>(f: (value: A) => Decoder<B>): OptionalDecoder<B> =>
+    new OptionalDecoder<B>((json: any) =>
+      Result.andThen(
+        (value: A | undefined) =>
+          value === undefined ? Result.ok(undefined) : (f(value) as any).decode(json),
+        this.decode(json)
+      )
+    );
+}