decoders 2.0.0-beta12 → 2.0.0-beta13

package/lib/basics.js.flow

@@ -28,23 +28,28 @@ const undefined_or_null: Decoder<null | void> = define((blob, ok, err) =>
 
 interface Maybeish<E> {
     <T>(decoder: Decoder<T>): Decoder<E | T>;
-    <T, V>(decoder: Decoder<T>, defaultValue: V): Decoder<$NonMaybeType<T> | V>;
+    <T, V>(
+        decoder: Decoder<T>,
+        defaultValue: (() => V) | V,
+    ): Decoder<$NonMaybeType<T> | V>;
 }
 
-/**
- * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
- */
 function _maybeish<E>(emptyCase: Decoder<E>): Maybeish<E> {
     function _inner(decoder /* defaultValue */) {
         const rv = either(emptyCase, decoder);
-        return (
+        if (
             // If a default value is provided...
             arguments.length >= 2
-                ? // ...then return the default value
-                  rv.transform((value) => value ?? arguments[1])
-                : // Otherwise the "normal" empty case
-                  rv
-        );
+        ) {
+            // ...then return the default value
+            const _defaultValue = arguments[1];
+            const defaultValue =
+                typeof _defaultValue === 'function' ? _defaultValue() : _defaultValue;
+            return rv.transform((value) => value ?? defaultValue);
+        } else {
+            // Otherwise the "normal" empty case
+            return rv;
+        }
     }
 
     return (_inner: _Any);
@@ -89,8 +94,14 @@ export function constant<T: Scalar>(value: T): Decoder<T> {
  *
  * This is useful to manually add extra fields to object decoders.
  */
-export function always<T>(value: T): Decoder<T> {
-    return define((blob /* ignored */, ok, _) => ok(value));
+export function always<T>(value: (() => T) | T): Decoder<T> {
+    return define(
+        typeof value === 'function'
+            ? (blob /* ignored */, ok, _) =>
+                  // $FlowFixMe[incompatible-use]
+                  ok(value())
+            : (blob /* ignored */, ok, _) => ok(value),
+    );
 }
 
 /**

package/lib/basics.mjs

@@ -19,22 +19,26 @@ var undefined_or_null = define(function (blob, ok, err) {
   err('Must be undefined or null');
 });
 
-/**
- * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
- */
 function _maybeish(emptyCase) {
   function _inner(decoder
   /* defaultValue */
   ) {
-    var _arguments = arguments;
     var rv = either(emptyCase, decoder);
-    return (// If a default value is provided...
-      arguments.length >= 2 ? // ...then return the default value
-      rv.transform(function (value) {
-        return value != null ? value : _arguments[1];
-      }) : // Otherwise the "normal" empty case
-      rv
-    );
+
+    if ( // If a default value is provided...
+    arguments.length >= 2) {
+      // ...then return the default value
+      var _defaultValue = arguments[1];
+
+      var _defaultValue2 = typeof _defaultValue === 'function' ? _defaultValue() : _defaultValue;
+
+      return rv.transform(function (value) {
+        return value != null ? value : _defaultValue2;
+      });
+    } else {
+      // Otherwise the "normal" empty case
+      return rv;
+    }
   }
 
   return _inner;
@@ -81,7 +85,13 @@ export function constant(value) {
  */
 
 export function always(value) {
-  return define(function (blob
+  return define(typeof value === 'function' ? function (blob
+  /* ignored */
+  , ok, _) {
+    return (// $FlowFixMe[incompatible-use]
+      ok(value())
+    );
+  } : function (blob
   /* ignored */
   , ok, _) {
     return ok(value);

package/lib/booleans.d.ts

@@ -1,5 +1,16 @@
 import { Decoder } from '../Decoder';
 
+/**
+ * Accepts and returns booleans.
+ */
 export const boolean: Decoder<boolean>;
+
+/**
+ * Accepts anything and will return its "truth" value. Will never reject.
+ */
 export const truthy: Decoder<boolean>;
+
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
 export const numericBoolean: Decoder<boolean>;

package/lib/booleans.js

@@ -14,7 +14,7 @@ var _boolean = (0, _Decoder.define)(function (blob, ok, err) {
   return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean');
 });
 /**
- * Accepts anything and will return its “truth” value. Will never reject.
+ * Accepts anything and will return its "truth" value. Will never reject.
  */
 
 

package/lib/booleans.js.flow

@@ -12,7 +12,7 @@ export const boolean: Decoder<boolean> = define((blob, ok, err) => {
 });
 
 /**
- * Accepts anything and will return its “truth” value. Will never reject.
+ * Accepts anything and will return its "truth" value. Will never reject.
  */
 export const truthy: Decoder<boolean> = define((blob, ok, _) => ok(!!blob));
 

package/lib/booleans.mjs

@@ -8,7 +8,7 @@ var _boolean = define(function (blob, ok, err) {
   return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean');
 });
 /**
- * Accepts anything and will return its “truth” value. Will never reject.
+ * Accepts anything and will return its "truth" value. Will never reject.
  */
 
 

package/lib/dates.d.ts

@@ -1,4 +1,15 @@
 import { Decoder } from '../Decoder';
 
+/**
+ * Accepts and returns `Date` instances.
+ */
 export const date: Decoder<Date>;
+
+/**
+ * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
+ * returns them as `Date` instances.
+ *
+ * This is very useful for working with dates in APIs: serialize them as
+ * `.toISOString()` when sending, decode them with `iso8601` when receiving.
+ */
 export const iso8601: Decoder<Date>;

package/lib/dates.js

@@ -23,7 +23,7 @@ var date = (0, _Decoder.define)(function (blob, ok, err) {
 });
 /**
  * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
- * returns then as `Date` instances.
+ * returns them as `Date` instances.
  *
  * This is very useful for working with dates in APIs: serialize them as
  * `.toISOString()` when sending, decode them with `iso8601` when receiving.

package/lib/dates.js.flow

@@ -21,7 +21,7 @@ export const date: Decoder<Date> = define((blob, ok, err) => {
 
 /**
  * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
- * returns then as `Date` instances.
+ * returns them as `Date` instances.
  *
  * This is very useful for working with dates in APIs: serialize them as
  * `.toISOString()` when sending, decode them with `iso8601` when receiving.

package/lib/dates.mjs

@@ -15,7 +15,7 @@ export var date = define(function (blob, ok, err) {
 });
 /**
  * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
- * returns then as `Date` instances.
+ * returns them as `Date` instances.
  *
  * This is very useful for working with dates in APIs: serialize them as
  * `.toISOString()` when sending, decode them with `iso8601` when receiving.

package/lib/json.d.ts

@@ -6,6 +6,30 @@ export interface JSONObject {
 }
 export type JSONArray = JSONValue[];
 
+/**
+ * Accepts any value that's a valid JSON value.
+ *
+ * In other words: any value returned by `JSON.parse()` should decode without
+ * failure.
+ *
+ * ```typescript
+ * type JSONValue =
+ *     | null
+ *     | string
+ *     | number
+ *     | boolean
+ *     | { [string]: JSONValue }
+ *     | JSONValue[]
+ * ```
+ */
 export const json: Decoder<JSONValue>;
+
+/**
+ * Like `json`, but will only decode when the JSON value is an array.
+ */
 export const jsonArray: Decoder<JSONArray>;
+
+/**
+ * Like `json`, but will only decode when the JSON value is an object.
+ */
 export const jsonObject: Decoder<JSONObject>;

package/lib/numbers.d.ts

@@ -1,7 +1,31 @@
 import { Decoder } from '../Decoder';
 
+/**
+ * Accepts any valid ``number`` value.
+ *
+ * This also accepts special values like `NaN` and `Infinity`. Unless you
+ * want to deliberately accept those, you'll likely want to use the
+ * `number` decoder instead.
+ */
 export const anyNumber: Decoder<number>;
-export const integer: Decoder<number>;
+
+/**
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
+ * or positive and negative `Infinity` will get rejected.
+ */
 export const number: Decoder<number>;
-export const positiveInteger: Decoder<number>;
+
+/**
+ * Accepts only finite whole numbers.
+ */
+export const integer: Decoder<number>;
+
+/**
+ * Accepts only positive finite numbers.
+ */
 export const positiveNumber: Decoder<number>;
+
+/**
+ * Accepts only positive finite whole numbers.
+ */
+export const positiveInteger: Decoder<number>;

package/lib/numbers.js

@@ -8,16 +8,15 @@ var _Decoder = require("../Decoder");
 /**
  * Accepts any valid ``number`` value.
  *
- * This also accepts special values like `NaN` and `Infinity`. Unless you want
- * to deliberately accept those, you'll likely want to use the `number` decoder
- * instead.
+ * This also accepts special values like `NaN` and `Infinity`. Unless you
+ * want to deliberately accept those, you'll likely want to use the
+ * `number` decoder instead.
  */
 var anyNumber = (0, _Decoder.define)(function (blob, ok, err) {
   return typeof blob === 'number' ? ok(blob) : err('Must be number');
 });
 /**
- * Accepts finite numbers (can be integer or float values). Values
- * `NaN`,
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
  * or positive and negative `Infinity` will get rejected.
  */
 

package/lib/numbers.js.flow

@@ -6,17 +6,16 @@ import type { Decoder } from '../Decoder';
 /**
  * Accepts any valid ``number`` value.
  *
- * This also accepts special values like `NaN` and `Infinity`. Unless you want
- * to deliberately accept those, you'll likely want to use the `number` decoder
- * instead.
+ * This also accepts special values like `NaN` and `Infinity`. Unless you
+ * want to deliberately accept those, you'll likely want to use the
+ * `number` decoder instead.
  */
 export const anyNumber: Decoder<number> = define((blob, ok, err) =>
     typeof blob === 'number' ? ok(blob) : err('Must be number'),
 );
 
 /**
- * Accepts finite numbers (can be integer or float values). Values
- * `NaN`,
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
  * or positive and negative `Infinity` will get rejected.
  */
 export const number: Decoder<number> = anyNumber.refine(

package/lib/numbers.mjs

@@ -3,16 +3,15 @@ import { define } from '../Decoder.mjs';
 /**
  * Accepts any valid ``number`` value.
  *
- * This also accepts special values like `NaN` and `Infinity`. Unless you want
- * to deliberately accept those, you'll likely want to use the `number` decoder
- * instead.
+ * This also accepts special values like `NaN` and `Infinity`. Unless you
+ * want to deliberately accept those, you'll likely want to use the
+ * `number` decoder instead.
  */
 export var anyNumber = define(function (blob, ok, err) {
   return typeof blob === 'number' ? ok(blob) : err('Must be number');
 });
 /**
- * Accepts finite numbers (can be integer or float values). Values
- * `NaN`,
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
  * or positive and negative `Infinity` will get rejected.
  */
 

package/lib/objects.d.ts

@@ -7,8 +7,17 @@ export type ObjectDecoderType<T> = AllowImplicit<{
     [key in keyof T]: DecoderType<T[key]>;
 }>;
 
+/**
+ * Accepts any "plain old JavaScript object", but doesn't validate its keys or
+ * values further.
+ */
 export const pojo: Decoder<{ [key: string]: unknown }>;
 
+/**
+ * Accepts objects with fields matching the given decoders. Extra fields that
+ * exist on the input object are ignored and will not be returned.
+ */
+export function object(decodersByKey: Record<any, never>): Decoder<Record<string, never>>;
 export function object<O extends { [key: string]: Decoder<any> }>(
     decodersByKey: O,
 ): Decoder<{ [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] }>;
@@ -20,12 +29,24 @@ export function object<O extends { [key: string]: Decoder<any> }>(
 //         type names from the inferred type here, making this much easier to
 //         work with while developing.
 
+/**
+ * Like `object()`, but will reject inputs that contain extra fields that are
+ * not specified explicitly.
+ */
+export function exact(decodersByKey: Record<any, never>): Decoder<Record<string, never>>;
 export function exact<O extends { [key: string]: Decoder<any> }>(
     decodersByKey: O,
 ): Decoder<{ [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] }>;
 //         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 //         Ditto (see above)
 
+/**
+ * Like `object()`, but will pass through any extra fields on the input object
+ * unvalidated that will thus be of `unknown` type statically.
+ */
+export function inexact(
+    decodersByKey: Record<any, never>,
+): Decoder<{ [extra: string]: unknown }>;
 export function inexact<O extends { [key: string]: Decoder<any> }>(
     decodersByKey: O,
 ): Decoder<
@@ -34,5 +55,21 @@ export function inexact<O extends { [key: string]: Decoder<any> }>(
     }
 >;
 
-export function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;
+/**
+ * Accepts objects where all values match the given decoder, and returns the
+ * result as a `{ [string]: T }`.
+ *
+ * The main difference between `object()` and `dict()` is that you'd typically
+ * use `object()` if this is a record-like object, where all field names are
+ * known and the values are heterogeneous. Whereas with `dict()` the keys are
+ * typically dynamic and the values homogeneous, like in a dictionary,
+ * a lookup table, or a cache.
+ */
 export function dict<T>(decoder: Decoder<T>): Decoder<{ [key: string]: T }>;
+
+/**
+ * Similar to `dict()`, but returns the result as a `Map<string, T>` (an [ES6
+ * Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map))
+ * instead.
+ */
+export function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;

package/lib/strings.d.ts

@@ -2,12 +2,55 @@
 
 import { Decoder } from '../Decoder';
 
+/**
+ * Accepts and returns strings.
+ */
 export const string: Decoder<string>;
+
+/**
+ * Like `string`, but will reject the empty string or strings containing only whitespace.
+ */
 export const nonEmptyString: Decoder<string>;
+
+/**
+ * Accepts and returns strings that match the given regular expression.
+ */
 export function regex(regex: RegExp, msg: string): Decoder<string>;
+
+/**
+ * Accepts and returns strings that are syntactically valid email addresses.
+ * (This will not mean that the email address actually exist.)
+ */
 export const email: Decoder<string>;
+
+/**
+ * Accepts strings that are valid URLs, returns the value as a URL instance.
+ */
 export const url: Decoder<URL>;
+
+/**
+ * Accepts strings that are valid URLs, but only HTTPS ones. Returns the value
+ * as a URL instance.
+ */
 export const httpsUrl: Decoder<URL>;
+
+/**
+ * Accepts strings that are valid
+ * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
+ * (universally unique identifier).
+ */
 export const uuid: Decoder<string>;
+
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv1](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_%28date-time_and_MAC_address%29)
+ * strings.
+ */
 export const uuidv1: Decoder<string>;
+
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_%28random%29)
+ * strings.
+ */
 export const uuidv4: Decoder<string>;

package/lib/unions.d.ts

@@ -4,75 +4,52 @@ export type Values<T extends object> = T[keyof T];
 
 export type DecoderTypes<T> = T extends ReadonlyArray<Decoder<infer U>> ? U : never;
 
+/**
+ * Accepts values accepted by any of the given decoders.
+ *
+ * The decoders are tried on the input one by one, in the given order. The
+ * first one that accepts the input "wins". If all decoders reject the input,
+ * the input gets rejected.
+ */
 export function either<T extends ReadonlyArray<Decoder<any>>>(
     ...args: T
 ): Decoder<DecoderTypes<T>>;
-// export function either<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
-// export function either2<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
-// export function either3<T1, T2, T3>(
-//     d1: Decoder<T1>,
-//     d2: Decoder<T2>,
-//     d3: Decoder<T3>,
-// ): Decoder<T1 | T2 | T3>;
-// export function either4<T1, T2, T3, T4>(
-//     d1: Decoder<T1>,
-//     d2: Decoder<T2>,
-//     d3: Decoder<T3>,
-//     d4: Decoder<T4>,
-// ): Decoder<T1 | T2 | T3 | T4>;
-// export function either5<T1, T2, T3, T4, T5>(
-//     d1: Decoder<T1>,
-//     d2: Decoder<T2>,
-//     d3: Decoder<T3>,
-//     d4: Decoder<T4>,
-//     d5: Decoder<T5>,
-// ): Decoder<T1 | T2 | T3 | T4 | T5>;
-// export function either6<T1, T2, T3, T4, T5, T6>(
-//     d1: Decoder<T1>,
-//     d2: Decoder<T2>,
-//     d3: Decoder<T3>,
-//     d4: Decoder<T4>,
-//     d5: Decoder<T5>,
-//     d6: Decoder<T6>,
-// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6>;
-// export function either7<T1, T2, T3, T4, T5, T6, T7>(
-//     d1: Decoder<T1>,
-//     d2: Decoder<T2>,
-//     d3: Decoder<T3>,
-//     d4: Decoder<T4>,
-//     d5: Decoder<T5>,
-//     d6: Decoder<T6>,
-//     d7: Decoder<T7>,
-// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7>;
-// export function either8<T1, T2, T3, T4, T5, T6, T7, T8>(
-//     d1: Decoder<T1>,
-//     d2: Decoder<T2>,
-//     d3: Decoder<T3>,
-//     d4: Decoder<T4>,
-//     d5: Decoder<T5>,
-//     d6: Decoder<T6>,
-//     d7: Decoder<T7>,
-//     d8: Decoder<T8>,
-// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8>;
-// export function either9<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
-//     d1: Decoder<T1>,
-//     d2: Decoder<T2>,
-//     d3: Decoder<T3>,
-//     d4: Decoder<T4>,
-//     d5: Decoder<T5>,
-//     d6: Decoder<T6>,
-//     d7: Decoder<T7>,
-//     d8: Decoder<T8>,
-//     d9: Decoder<T9>,
-// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8 | T9>;
+
+/**
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
+ */
 export function oneOf<T extends Scalar>(constants: readonly T[]): Decoder<T>;
 
+/**
+ * If you are decoding tagged unions you may want to use the `taggedUnion()`
+ * decoder instead of the general purpose `either()` decoder to get better
+ * error messages and better performance.
+ *
+ * This decoder is optimized for [tagged
+ * unions](https://en.wikipedia.org/wiki/Tagged_union), i.e. a union of
+ * objects where one field is used as the discriminator.
+ *
+ * ```ts
+ * const A = object({ tag: constant('A'), foo: string });
+ * const B = object({ tag: constant('B'), bar: number });
+ *
+ * const AorB = taggedUnion('tag', { A, B });
+ * //                        ^^^
+ * ```
+ *
+ * Decoding now works in two steps:
+ *
+ * 1. Look at the `'tag'` field in the incoming object (this is the field
+ *    that decides which decoder will be used)
+ * 2. If the value is `'A'`, then decoder `A` will be used. If it's `'B'`, then
+ *    decoder `B` will be used. Otherwise, this will fail.
+ *
+ * This is effectively equivalent to `either(A, B)`, but will provide better
+ * error messages and is more performant at runtime because it doesn't have to
+ * try all decoders one by one.
+ */
 export function taggedUnion<O extends { [key: string]: Decoder<any> }>(
     field: string,
     mapping: O,
 ): Decoder<Values<{ [key in keyof O]: DecoderType<O[key]> }>>;
-
-export function dispatch<O extends { [key: string]: Decoder<any> }>(
-    field: string,
-    mapping: O,
-): Decoder<Values<{ [key in keyof O]: DecoderType<O[key]> }>>;

package/lib/unions.js

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.either = exports.dispatch = void 0;
+exports.either = void 0;
 exports.oneOf = oneOf;
 exports.taggedUnion = taggedUnion;
 
@@ -94,8 +94,8 @@ function _either() {
 
 var either = _either;
 /**
- * Accepts any value that is strictly-equal (using ===) to one of the specified
- * values.
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
  */
 
 exports.either = either;
@@ -124,11 +124,13 @@ function oneOf(constants) {
  * unions](https://en.wikipedia.org/wiki/Tagged_union), i.e. a union of
  * objects where one field is used as the discriminator.
  *
- *   const A = object({ tag: constant('A'), foo: string });
- *   const B = object({ tag: constant('B'), bar: number });
+ * ```ts
+ * const A = object({ tag: constant('A'), foo: string });
+ * const B = object({ tag: constant('B'), bar: number });
  *
- *   const AorB = taggedUnion('tag', { A, B });
- *   //                        ^^^
+ * const AorB = taggedUnion('tag', { A, B });
+ * //                        ^^^
+ * ```
  *
  * Decoding now works in two steps:
  *
@@ -155,7 +157,4 @@ function taggedUnion(field, mapping) {
     var decoder = mapping[key];
     return decoder.decode(blob);
   });
-}
-
-var dispatch = taggedUnion;
-exports.dispatch = dispatch;
+}

package/lib/unions.js.flow

@@ -48,7 +48,7 @@ function nest(errText: string): string {
 }
 
 // prettier-ignore
-interface EitherDecoderSignatures {
+interface EitherT {
   <A>(a: Decoder<A>): Decoder<A>;
   <A, B>(a: Decoder<A>, b: Decoder<B>): Decoder<A | B>;
   <A, B, C>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>): Decoder<A | B | C>;
@@ -93,11 +93,11 @@ function _either(...decoders: $ReadOnlyArray<Decoder<mixed>>): Decoder<mixed> {
  * first one that accepts the input "wins". If all decoders reject the input,
  * the input gets rejected.
  */
-export const either: EitherDecoderSignatures = (_either: _Any);
+export const either: EitherT = (_either: _Any);
 
 /**
- * Accepts any value that is strictly-equal (using ===) to one of the specified
- * values.
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
  */
 export function oneOf<T: Scalar>(constants: $ReadOnlyArray<T>): Decoder<T> {
     return define((blob, ok, err) => {
@@ -122,11 +122,13 @@ export function oneOf<T: Scalar>(constants: $ReadOnlyArray<T>): Decoder<T> {
  * unions](https://en.wikipedia.org/wiki/Tagged_union), i.e. a union of
  * objects where one field is used as the discriminator.
  *
- *   const A = object({ tag: constant('A'), foo: string });
- *   const B = object({ tag: constant('B'), bar: number });
+ * ```ts
+ * const A = object({ tag: constant('A'), foo: string });
+ * const B = object({ tag: constant('B'), bar: number });
  *
- *   const AorB = taggedUnion('tag', { A, B });
- *   //                        ^^^
+ * const AorB = taggedUnion('tag', { A, B });
+ * //                        ^^^
+ * ```
  *
  * Decoding now works in two steps:
  *
@@ -151,8 +153,3 @@ export function taggedUnion<O: { +[field: string]: Decoder<_Any>, ... }>(
         return decoder.decode(blob);
     });
 }
-
-export const dispatch: <O: { +[field: string]: Decoder<_Any>, ... }>(
-    field: string,
-    mapping: O,
-) => Decoder<$Values<$ObjMap<O, <T>(Decoder<T>) => T>>> = taggedUnion;