decoders 1.25.2 → 1.26.0-beta2

package/es/index.js

@@ -0,0 +1,1039 @@
+import { summarize, serialize, annotate, indent, isAnnotation, annotateFields } from 'debrief';
+import { Ok, Err } from 'lemons';
+import _toConsumableArray from '@babel/runtime/helpers/toConsumableArray';
+import _defineProperty from '@babel/runtime/helpers/defineProperty';
+import _typeof from '@babel/runtime/helpers/typeof';
+import _slicedToArray from '@babel/runtime/helpers/slicedToArray';
+
+/**
+ * Alternative for serialize() that does not echo back the input value.
+ */
+function serializeSimple(annotation) {
+  return summarize(annotation).join('\n');
+}
+
+function guard(decoder, options) {
+  var o = options || {};
+  var style = o.style || 'inline';
+  var serializer = style === 'inline' ? serialize // Normal serializer, which echoes back inputted value and inlines errors
+  : serializeSimple; // Only returns error messages, without echoing back input
+
+  return function (blob) {
+    return decoder(blob).mapError(function (annotation) {
+      var err = new Error('\n' + serializer(annotation));
+      err.name = 'Decoding error';
+      return err;
+    }).unwrap();
+  };
+}
+
+/**
+ * `x instanceof Date` checks are unreliable across stack frames (that information
+ * might get lost by the JS runtime), so we'll have to reside to more runtime
+ * inspection checks.
+ *
+ * Taken from https://stackoverflow.com/a/44198641
+ */
+var isDate = function isDate(value) {
+  return value !== undefined && value !== null && // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value);
+};
+/**
+ * Given a decoder T and a mapping function from T's to V's, returns a decoder
+ * for V's.  This is useful to change the original input data.
+ */
+
+function map(decoder, mapper) {
+  return compose(decoder, function (x) {
+    try {
+      return Ok(mapper(x));
+    } catch (e) {
+      return Err(annotate(x, e instanceof Error ? e.message : String(e)));
+    }
+  });
+}
+/**
+ * Compose two decoders by passing the result of the first into the second.
+ * The second decoder may assume as its input type the output type of the first
+ * decoder (so it's not necessary to accept the typical "mixed").  This is
+ * useful for "narrowing down" the checks.  For example, if you want to write
+ * a decoder for positive numbers, you can compose it from an existing decoder
+ * for any number, and a decoder that, assuming a number, checks if it's
+ * positive.  Very often combined with the predicate() helper as the second
+ * argument.
+ */
+
+function compose(decoder, next) {
+  return function (blob) {
+    return decoder(blob).andThen(next);
+  };
+}
+/**
+ * Factory function returning a Decoder<T>, given a predicate function that
+ * accepts/rejects the input of type T.
+ */
+
+function predicate(predicate, msg) {
+  return function (value) {
+    return predicate(value) ? Ok(value) : Err(annotate(value, msg));
+  };
+}
+
+function _createForOfIteratorHelper$2(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray$2(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
+
+function _unsupportedIterableToArray$2(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray$2(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray$2(o, minLen); }
+
+function _arrayLikeToArray$2(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+/**
+ * Like a "Plain Old JavaScript Object", but for arrays: "Plain Old JavaScript
+ * Array" ^_^
+ */
+
+var poja = function poja(blob) {
+  if (!Array.isArray(blob)) {
+    return Err(annotate(blob, 'Must be an array'));
+  }
+
+  return Ok( // NOTE: Since Flow 0.98, Array.isArray() returns $ReadOnlyArray<mixed>
+  // instead of Array<mixed>.  For rationale, see
+  // https://github.com/facebook/flow/issues/7684.  In this case, we
+  // don't want to output read-only types because it's up to the user of
+  // decoders to determine what they want to do with the decoded output.
+  // If they want to write items into the array, that's fine!
+  // The fastest way to turn a read-only array into a normal array in
+  // Javascript is to use .slice() on it, see this benchmark:
+  // http://jsben.ch/lO6C5
+  blob.slice());
+};
+/**
+ * Given an iterable of Result instances, exhaust them all and return:
+ * - An [index, err] tuple, indicating the (index of the) first Err instance
+ *   encountered; or
+ * - a new Ok with an array of all unwrapped Ok'ed values
+ */
+
+function all(iterable, blobs) {
+  var results = [];
+  var index = 0;
+
+  var _iterator = _createForOfIteratorHelper$2(iterable),
+      _step;
+
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var result = _step.value;
+
+      try {
+        var value = result.unwrap();
+        results.push(value);
+      } catch (ann) {
+        // Rewrite the annotation to include the index information, and inject it into the original blob
+        var clone = _toConsumableArray(blobs);
+
+        clone.splice(index, 1, annotate(ann, ann.annotation !== undefined ? "".concat(ann.annotation, " (at index ").concat(index, ")") : "index ".concat(index))); // const errValue = [];
+        // if (index > 0) {
+        //     errValue.push('...'); // TODO: make special mark, not string!
+        // }
+        // errValue.push(
+        // );
+        // if (index < iterable.length - 1) {
+        //     errValue.push('...'); // TODO: make special mark, not string!
+        // }
+
+        return Err(annotate(clone));
+      }
+
+      index++;
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+
+  return Ok(results);
+}
+/**
+ * Given a T, builds a decoder that assumes an array input and returns an
+ * Array<T>.
+ */
+
+
+function members(decoder) {
+  return function (blobs) {
+    var results = blobs.map(decoder);
+    var result = all(results, blobs);
+    return result;
+  };
+}
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, given a Decoder
+ * for `T`.  Err otherwise.
+ */
+
+
+function array(decoder) {
+  return compose(poja, members(decoder));
+}
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, but will reject
+ * empty arrays.
+ */
+
+function nonEmptyArray(decoder) {
+  return compose(array(decoder), predicate(function (arr) {
+    return arr.length > 0;
+  }, 'Must be non-empty array'));
+}
+
+var anyNumber = function anyNumber(blob) {
+  return typeof blob === 'number' && !Number.isNaN(blob) ? Ok(blob) : Err(annotate(blob, 'Must be number'));
+};
+
+var isInteger = function isInteger(n) {
+  return Number.isInteger(n);
+};
+
+var isFinite = function isFinite(n) {
+  return Number.isFinite(n);
+};
+
+var number = compose(anyNumber, predicate(isFinite, 'Number must be finite'));
+var positiveNumber = compose(number, predicate(function (n) {
+  return n >= 0;
+}, 'Number must be positive')); // Integers
+
+var integer = compose(number, predicate(isInteger, 'Number must be an integer'));
+var positiveInteger = compose(integer, predicate(function (n) {
+  return n >= 0;
+}, 'Number must be positive'));
+
+/**
+ * Decoder that only returns Ok for boolean inputs.  Err otherwise.
+ */
+
+var _boolean = function _boolean(blob) {
+  return typeof blob === 'boolean' ? Ok(blob) : Err(annotate(blob, 'Must be boolean'));
+};
+var truthy = function truthy(blob) {
+  return Ok(!!blob);
+};
+/**
+ * Decoder that only returns Ok for numeric input values representing booleans.
+ * Returns their boolean representation.  Err otherwise.
+ */
+
+var numericBoolean = map(number, function (n) {
+  return !!n;
+});
+
+/**
+ * Decoder that only returns Ok for `null` inputs.  Err otherwise.
+ */
+var null_ = function null_(blob) {
+  return blob === null ? Ok(blob) : Err(annotate(blob, 'Must be null'));
+};
+/**
+ * Decoder that only returns Ok for `undefined` inputs.  Err otherwise.
+ */
+
+var undefined_ = function undefined_(blob) {
+  return blob === undefined ? Ok(blob) : Err(annotate(blob, 'Must be undefined'));
+};
+/**
+ * Decoder that only returns Ok for the given value constant.  Err otherwise.
+ */
+
+function constant(value) {
+  return function (blob) {
+    return blob === value ? Ok(value) : Err(annotate(blob, "Must be constant ".concat(String(value))));
+  };
+}
+/**
+ * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
+ */
+
+function hardcoded(value) {
+  return function (_) {
+    return Ok(value);
+  };
+}
+/**
+ * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
+ */
+
+var mixed = function mixed(blob) {
+  return Ok(blob);
+};
+/**
+ * Alias of mixed.
+ */
+
+var unknown = mixed;
+
+/** Match groups in this regex:
+ * \1 - the scheme
+ * \2 - the username/password (optional)
+ * \3 - the host
+ * \4 - the port (optional)
+ * \5 - the path (optional)
+ */
+
+var url_re = /^([A-Za-z]{3,9}(?:[+][A-Za-z]{3,9})?):\/\/(?:([-;:&=+$,\w]+)@)?(?:([A-Za-z0-9.-]+)(?::([0-9]{2,5}))?)(\/(?:[-+~%/.,\w]*)?(?:\?[-+=&;%@.,\w]*)?(?:#[.,!/\w]*)?)?$/; // The URL schemes the url() decoder accepts by default
+
+var DEFAULT_SCHEMES = ['https'];
+/**
+ * Decoder that only returns Ok for string inputs.  Err otherwise.
+ */
+
+var string = function string(blob) {
+  return typeof blob === 'string' ? Ok(blob) : Err(annotate(blob, 'Must be string'));
+};
+/**
+ * Decoder that only returns Ok for non-empty string inputs.  Err otherwise.
+ */
+
+var nonEmptyString = regex(/\S/, 'Must be non-empty string');
+/**
+ * Decoder that only returns Ok for string inputs that match the regular
+ * expression.  Err otherwise.  Will always validate that the input is a string
+ * before testing the regex.
+ */
+
+function regex(regex, msg) {
+  return compose(string, predicate(function (s) {
+    return regex.test(s);
+  }, msg));
+}
+/**
+ * Decoder that only returns Ok for string inputs that match the almost perfect
+ * email regex, taken from http://emailregex.com.  Err otherwise.
+ */
+
+var email = regex(/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, 'Must be email');
+/**
+ * Decoder that only returns Ok for string inputs that match URLs of the
+ * expected scheme.  Defaults to only accept HTTPS URLs.  Err otherwise.
+ *
+ * Variants that can be used:
+ *
+ * - url()                      accepts only https:// URLs
+ * - url([])                    accepts any URL scheme
+ * - url(['http'])              accepts only HTTP
+ * - url(['https', 'git+ssh'])  accepts both https:// and git+ssh:// URLs
+ */
+
+var url = function url() {
+  var schemes = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : DEFAULT_SCHEMES;
+  return compose(string, function (value) {
+    var matches = value.match(url_re);
+
+    if (!matches) {
+      return Err(annotate(value, 'Must be URL'));
+    } else {
+      var scheme = matches[1];
+
+      if (schemes.length === 0 || schemes.includes(scheme.toLowerCase())) {
+        return Ok(value);
+      } else {
+        return Err(annotate(value, "URL scheme must be any of: ".concat(schemes.join(', '))));
+      }
+    }
+  });
+};
+
+// Only matches the shape.  This "over-matches" some values that still aren't
+// valid dates (like 9999-99-99), but those will be caught by JS Date's
+// internal validations
+var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+var date = function date(value) {
+  return isDate(value) ? Ok(value) : Err(annotate(value, 'Must be a Date'));
+};
+/**
+ * Decoder that only returns Ok for strings that are valid ISO8601 date
+ * strings.  Err otherwise.
+ */
+
+var iso8601 = map( // Input itself needs to match the ISO8601 regex...
+regex(iso8601_re, 'Must be ISO8601 format'), // Make sure it is a _valid_ date
+function (value) {
+  var date = new Date(value);
+
+  if (isNaN(date.getTime())) {
+    throw new Error('Must be valid date/time value');
+  }
+
+  return date;
+});
+
+/**
+ * Wrap another decoder, and override the error message in case it fails. This
+ * is useful to "simplify" otherwise potentially complex error messages, or to
+ * use language in those error messages that can be relayed to end users (for
+ * example to show in form errors).
+ */
+function describe(decoder, message) {
+  return function (blob) {
+    return decoder(blob).mapError(function (err) {
+      return annotate(err, message);
+    });
+  };
+}
+
+/**
+ * Indents and adds a dash in front of this (potentially multiline) string.
+ */
+// istanbul ignore next
+function itemize() {
+  var s = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
+  return '-' + indent(s).substring(1);
+}
+
+function either(d1, d2) {
+  return function (blob) {
+    return d1(blob).dispatch(function (value1) {
+      return Ok(value1);
+    }, function (err1) {
+      return d2(blob).dispatch(function (value2) {
+        return Ok(value2);
+      }, function (err2) {
+        return Err(annotate(blob, ['Either:', itemize(summarize(err1).join('\n')), itemize(summarize(err2).join('\n'))].join('\n')));
+      });
+    });
+  };
+}
+function either3(d1, d2, d3) {
+  return either(d1, either(d2, d3));
+}
+function either4(d1, d2, d3, d4) {
+  return either(d1, either3(d2, d3, d4));
+}
+function either5(d1, d2, d3, d4, d5) {
+  return either(d1, either4(d2, d3, d4, d5));
+}
+function either6(d1, d2, d3, d4, d5, d6) {
+  return either(d1, either5(d2, d3, d4, d5, d6));
+}
+function either7(d1, d2, d3, d4, d5, d6, d7) {
+  return either(d1, either6(d2, d3, d4, d5, d6, d7));
+}
+function either8(d1, d2, d3, d4, d5, d6, d7, d8) {
+  return either(d1, either7(d2, d3, d4, d5, d6, d7, d8));
+}
+function either9(d1, d2, d3, d4, d5, d6, d7, d8, d9) {
+  return either(d1, either8(d2, d3, d4, d5, d6, d7, d8, d9));
+}
+function oneOf(constants) {
+  return function (blob) {
+    var winner = constants.find(function (c) {
+      return c === blob;
+    });
+
+    if (winner !== undefined) {
+      return Ok(winner);
+    }
+
+    return Err(annotate(blob, "Must be one of ".concat(constants.map(function (value) {
+      return JSON.stringify(value);
+    }).join(', '))));
+  };
+}
+
+function ownKeys$1(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) { symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); } keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread$1(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys$1(Object(source), true).forEach(function (key) { _defineProperty(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys$1(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+
+function _createForOfIteratorHelper$1(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray$1(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
+
+function _unsupportedIterableToArray$1(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray$1(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray$1(o, minLen); }
+
+function _arrayLikeToArray$1(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function isPojo(o) {
+  return o !== null && o !== undefined && _typeof(o) === 'object' && // This still seems to be the only reliable way to determine whether
+  // something is a pojo... ¯\_(ツ)_/¯
+  // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(o) === '[object Object]';
+}
+
+function subtract(xs, ys) {
+  var result = new Set();
+
+  var _iterator = _createForOfIteratorHelper$1(xs),
+      _step;
+
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var x = _step.value;
+
+      if (!ys.has(x)) {
+        result.add(x);
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+
+  return result;
+}
+
+var pojo = function pojo(blob) {
+  return isPojo(blob) ? Ok( // NOTE:
+  // Since Flow 0.98, typeof o === 'object' refines to
+  //     {| +[string]: mixed |}
+  // instead of
+  //     {| [string]: mixed |}
+  //
+  // For rationale, see https://github.com/facebook/flow/issues/7685.
+  // In this case, we don't want to output a read-only version of
+  // the object because it's up to the user of decoders to
+  // determine what they want to do with the decoded output.  If they
+  // want to write items into the array, that's fine!  The fastest
+  // way to turn a read-only Object to a writeable one in ES6 seems
+  // to be to use object-spread. (Going off this benchmark:
+  // https://thecodebarbarian.com/object-assign-vs-object-spread.html)
+  _objectSpread$1({}, blob)) : Err(annotate(blob, 'Must be an object'));
+};
+/**
+ * Given a mapping of fields-to-decoders, builds a decoder for an object type.
+ *
+ * For example, given decoders for a number and a string, we can construct an
+ * "object description" like so:
+ *
+ *   { id: number, name: string }
+ *
+ * Which is of type:
+ *
+ *   { id: Decoder<number>, name: Decoder<string> }
+ *
+ * Passing this to object() will produce the following return type:
+ *
+ *   Decoder<{ id: number, name: string }>
+ *
+ * Put simply: it'll "peel off" all of the nested Decoders, puts them together
+ * in an object, and wraps it in a Decoder<...>.
+ */
+
+function object(mapping) {
+  var known = new Set(Object.keys(mapping));
+  return compose(pojo, function (blob) {
+    var actual = new Set(Object.keys(blob)); // At this point, "missing" will also include all fields that may
+    // validly be optional.  We'll let the underlying decoder decide and
+    // remove the key from this missing set if the decoder accepts the
+    // value.
+
+    var missing = subtract(known, actual);
+    var record = {};
+
+    var fieldErrors = _objectSpread$1({}, null); // NOTE: We're using .keys() here over .entries(), since .entries()
+    // will type the value part as "mixed"
+
+
+    for (var _i = 0, _Object$keys = Object.keys(mapping); _i < _Object$keys.length; _i++) {
+      var _key = _Object$keys[_i];
+      var decoder = mapping[_key];
+      var rawValue = blob[_key];
+      var result = decoder(rawValue);
+
+      try {
+        var value = result.unwrap();
+
+        if (value !== undefined) {
+          record[_key] = value;
+        } // If this succeeded, remove the key from the missing keys
+        // tracker
+
+
+        missing["delete"](_key);
+      } catch (ann) {
+        /* istanbul ignore next */
+        if (!isAnnotation(ann)) {
+          throw ann;
+        } // Keep track of the annotation, but don't return just yet. We
+        // want to collect more error information.
+
+
+        if (rawValue === undefined) {
+          // Explicitly add it to the missing set if the value is
+          // undefined.  This covers explicit undefineds to be
+          // treated the same as implicit undefineds (aka missing
+          // keys).
+          missing.add(_key);
+        } else {
+          fieldErrors[_key] = ann;
+        }
+      }
+    } // Deal with errors now. There are two classes of errors we want to
+    // report.  First of all, we want to report any inline errors in this
+    // object.  Lastly, any fields that are missing should be annotated on
+    // the outer object itself.
+
+
+    var fieldsWithErrors = Object.keys(fieldErrors);
+
+    if (fieldsWithErrors.length > 0 || missing.size > 0) {
+      var err;
+
+      if (fieldsWithErrors.length > 0) {
+        var errorlist = fieldsWithErrors.map(function (k) {
+          return [k, fieldErrors[k]];
+        });
+        err = annotateFields(blob, errorlist);
+      } else {
+        err = annotate(blob);
+      }
+
+      if (missing.size > 0) {
+        var errMsg = Array.from(missing).map(function (key) {
+          return "\"".concat(key, "\"");
+        }).join(', ');
+        var pluralized = missing.size > 1 ? 'keys' : 'key';
+        err = annotate(err, "Missing ".concat(pluralized, ": ").concat(errMsg));
+      }
+
+      return Err(err);
+    }
+
+    return Ok(record);
+  });
+}
+function exact(mapping) {
+  // Check the inputted object for any superfluous keys
+  var allowed = new Set(Object.keys(mapping));
+  var checked = compose(pojo, function (blob) {
+    var actual = new Set(Object.keys(blob));
+    var superfluous = subtract(actual, allowed);
+
+    if (superfluous.size > 0) {
+      return Err(annotate(blob, "Superfluous keys: ".concat(Array.from(superfluous).join(', '))));
+    }
+
+    return Ok(blob);
+  }); // Defer to the "object" decoder for doing the real decoding work.  Since
+  // we made sure there are no superfluous keys in this structure, it's now
+  // safe to force-cast it to an $Exact<> type.
+
+  var decoder = object(mapping);
+  return compose(checked, decoder);
+}
+function inexact(mapping) {
+  return compose(pojo, function (blob) {
+    var allkeys = new Set(Object.keys(blob));
+    var decoder = map(object(mapping), function (safepart) {
+      var safekeys = new Set(Object.keys(mapping)); // To account for hard-coded keys that aren't part of the input
+
+      var _iterator2 = _createForOfIteratorHelper$1(safekeys),
+          _step2;
+
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var k = _step2.value;
+          allkeys.add(k);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+
+      var rv = {};
+
+      var _iterator3 = _createForOfIteratorHelper$1(allkeys),
+          _step3;
+
+      try {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var _k = _step3.value;
+
+          if (safekeys.has(_k)) {
+            var value = safepart[_k];
+
+            if (value !== undefined) {
+              rv[_k] = value;
+            }
+          } else {
+            rv[_k] = blob[_k];
+          }
+        }
+      } catch (err) {
+        _iterator3.e(err);
+      } finally {
+        _iterator3.f();
+      }
+
+      return rv;
+    });
+    return decoder(blob);
+  });
+}
+
+/**
+ * Dispatches to one of several given decoders, based on the value found at
+ * runtime in the given field.  For example, suppose you have these decoders:
+ *
+ *     const rectangle = object({
+ *         type: constant('rect'),
+ *         x: number,
+ *         y: number,
+ *         width: number,
+ *         height: number,
+ *     });
+ *
+ *     const circle = object({
+ *         type: constant('circle'),
+ *         cx: number,
+ *         cy: number,
+ *         r: number,
+ *      });
+ *
+ * Then these two decoders are equivalent:
+ *
+ *     const shape = either(rectangle, circle)
+ *     const shape = dispatch('type', { rectangle, circle })
+ *
+ * Will be of type Decoder<Rectangle | Circle>.
+ *
+ * But the dispatch version will typically be more runtime-efficient.  The
+ * reason is that it will first do minimal work to "look ahead" into the `type`
+ * field here, and based on that value, pick the decoder to invoke.
+ *
+ * The `either` version will simply try to invoke each decoder, until it finds
+ * one that matches.
+ *
+ * Also, the error messages will be less ambiguous using `dispatch()`.
+ */
+function dispatch(field, mapping) {
+  var base = object(_defineProperty({}, field, oneOf(Object.keys(mapping))));
+  return function (blob) {
+    return base(blob).andThen(function (baseObj) {
+      var decoderName = baseObj[field];
+      var decoder = mapping[decoderName];
+      return decoder(blob);
+    });
+  };
+}
+
+/**
+ * Decoder that always fails with the given error message, no matter what the input.
+ */
+function fail(msg) {
+  return function (blob) {
+    return Err(annotate(blob, msg));
+  };
+}
+
+function instanceOf(klass) {
+  return function (blob) {
+    return blob instanceof klass ? Ok(blob) : Err(annotate(blob, "Must be ".concat( // $FlowFixMe[incompatible-use] - klass.name is fine?
+    klass.name, " instance")));
+  };
+}
+
+/**
+ * Given an function returning a Decoder, will use that decoder to decode the
+ * value. This is typically used to build decoders for recursive or
+ * self-referential types.
+ */
+function lazy(decoderFn) {
+  return function (blob) {
+    var decoder = decoderFn();
+    return decoder(blob);
+  };
+}
+
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) { symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); } keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { _defineProperty(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+/**
+ * Given an object, will decode a Map of string keys to whatever values.
+ *
+ * For example, given a decoder for a Person, we can verify a Person lookup
+ * table structure (of type Map<string, Person>) like so:
+ *
+ *   mapping(person)
+ *
+ */
+
+function mapping(decoder) {
+  return compose(pojo, // $FlowFixMe[unclear-type] (not really an issue) - deliberate use of Object here
+  function (blob) {
+    var tuples = [];
+    var errors = [];
+    Object.keys(blob).forEach(function (key) {
+      var value = blob[key];
+      var result = decoder(value);
+
+      try {
+        var okValue = result.unwrap();
+
+        if (errors.length === 0) {
+          tuples.push([key, okValue]);
+        }
+      } catch (e) {
+        /* istanbul ignore else */
+        if (isAnnotation(e)) {
+          tuples.length = 0; // Clear the tuples array
+
+          errors.push([key, e]);
+        } else {
+          // Otherwise, simply rethrow it
+
+          /* istanbul ignore next */
+          throw e;
+        }
+      }
+    });
+
+    if (errors.length > 0) {
+      return Err(annotateFields(blob, errors));
+    } else {
+      return Ok(new Map(tuples));
+    }
+  });
+}
+
+function mapToObject(mapping) {
+  var result = _objectSpread({}, null);
+
+  var _iterator = _createForOfIteratorHelper(mapping.entries()),
+      _step;
+
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var _step$value = _slicedToArray(_step.value, 2),
+          k = _step$value[0],
+          v = _step$value[1];
+
+      result[k] = v;
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+
+  return result;
+}
+/**
+ * Like mapping(), but returns an object rather than a Map instance.
+ */
+
+
+function dict(decoder) {
+  return map(mapping(decoder), mapToObject);
+}
+
+var jsonObject = lazy(function () {
+  return dict(json);
+});
+var jsonArray = lazy(function () {
+  return array(json);
+});
+var json = either6(null_, string, number, _boolean, jsonObject, jsonArray);
+
+/**
+ * Builds a Decoder that returns Ok for either `undefined` or `T` values,
+ * given a Decoder for `T`.  Err otherwise.
+ */
+function optional(decoder) {
+  return either(undefined_, decoder);
+}
+/**
+ * Builds a Decoder that returns Ok for either `null` or `T` values,
+ * given a Decoder for `T`.  Err otherwise.
+ */
+
+function nullable(decoder) {
+  return either(null_, decoder);
+}
+/**
+ * Decoder that only returns Ok for `null` or `undefined` inputs.
+ * This is effectively equivalent to either(null_, undefined_), but combines
+ * their error message output into a single line for convenience.
+ */
+
+var undefined_or_null = function undefined_or_null(blob) {
+  return blob === undefined || blob === null ? Ok(blob) : // Combine error message into a single line
+  Err(annotate(blob, 'Must be undefined or null'));
+};
+/**
+ * Decoder that only returns Ok for `null` or `undefined` inputs.
+ */
+
+
+function maybe(decoder) {
+  return either(undefined_or_null, decoder);
+}
+
+var ntuple = function ntuple(n) {
+  return compose(poja, predicate(function (arr) {
+    return arr.length === n;
+  }, "Must be a ".concat(n, "-tuple")));
+};
+/**
+ * Builds a Decoder that returns Ok for 1-tuple of [T], given a Decoder for T.
+ * Err otherwise.
+ */
+
+
+function tuple1(decoder1) {
+  return compose(ntuple(1), function (blobs) {
+    var _blobs = _slicedToArray(blobs, 1),
+        blob1 = _blobs[0];
+
+    var result1 = decoder1(blob1);
+
+    try {
+      return Ok([result1.unwrap()]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return Err(annotate(result1.errValue()));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 2-tuples of [T1, T2], given Decoders
+ * for T1 and T2.  Err otherwise.
+ */
+
+function tuple2(decoder1, decoder2) {
+  return compose(ntuple(2), function (blobs) {
+    var _blobs2 = _slicedToArray(blobs, 2),
+        blob1 = _blobs2[0],
+        blob2 = _blobs2[1];
+
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+
+    try {
+      return Ok([result1.unwrap(), result2.unwrap()]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return Err(annotate([result1.isErr() ? result1.errValue() : result1.value(), result2.isErr() ? result2.errValue() : result2.value()]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 3-tuples of [T1, T2, T3], given
+ * Decoders for T1, T2, and T3.  Err otherwise.
+ */
+
+function tuple3(decoder1, decoder2, decoder3) {
+  return compose(ntuple(3), function (blobs) {
+    var _blobs3 = _slicedToArray(blobs, 3),
+        blob1 = _blobs3[0],
+        blob2 = _blobs3[1],
+        blob3 = _blobs3[2];
+
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+
+    try {
+      return Ok([result1.unwrap(), result2.unwrap(), result3.unwrap()]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return Err(annotate([result1.isErr() ? result1.errValue() : result1.value(), result2.isErr() ? result2.errValue() : result2.value(), result3.isErr() ? result3.errValue() : result3.value()]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 4-tuples of [T1, T2, T3, T4], given
+ * Decoders for T1, T2, T3, and T4.  Err otherwise.
+ */
+
+function tuple4(decoder1, decoder2, decoder3, decoder4) {
+  return compose(ntuple(4), function (blobs) {
+    var _blobs4 = _slicedToArray(blobs, 4),
+        blob1 = _blobs4[0],
+        blob2 = _blobs4[1],
+        blob3 = _blobs4[2],
+        blob4 = _blobs4[3];
+
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+    var result4 = decoder4(blob4);
+
+    try {
+      return Ok([result1.unwrap(), result2.unwrap(), result3.unwrap(), result4.unwrap()]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return Err(annotate([result1.isErr() ? result1.errValue() : result1.value(), result2.isErr() ? result2.errValue() : result2.value(), result3.isErr() ? result3.errValue() : result3.value(), result4.isErr() ? result4.errValue() : result4.value()]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 5-tuples of [T1, T2, T3, T4, T5], given
+ * Decoders for T1, T2, T3, T4, and T5.  Err otherwise.
+ */
+
+function tuple5(decoder1, decoder2, decoder3, decoder4, decoder5) {
+  return compose(ntuple(5), function (blobs) {
+    var _blobs5 = _slicedToArray(blobs, 5),
+        blob1 = _blobs5[0],
+        blob2 = _blobs5[1],
+        blob3 = _blobs5[2],
+        blob4 = _blobs5[3],
+        blob5 = _blobs5[4];
+
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+    var result4 = decoder4(blob4);
+    var result5 = decoder5(blob5);
+
+    try {
+      return Ok([result1.unwrap(), result2.unwrap(), result3.unwrap(), result4.unwrap(), result5.unwrap()]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return Err(annotate([result1.isErr() ? result1.errValue() : result1.value(), result2.isErr() ? result2.errValue() : result2.value(), result3.isErr() ? result3.errValue() : result3.value(), result4.isErr() ? result4.errValue() : result4.value(), result5.isErr() ? result5.errValue() : result5.value()]));
+    }
+  });
+}
+/**
+ * Builds a Decoder that returns Ok for 5-tuples of [T1, T2, T3, T4, T5], given
+ * Decoders for T1, T2, T3, T4, T5, and T6.  Err otherwise.
+ */
+
+function tuple6(decoder1, decoder2, decoder3, decoder4, decoder5, decoder6) {
+  return compose(ntuple(6), function (blobs) {
+    var _blobs6 = _slicedToArray(blobs, 6),
+        blob1 = _blobs6[0],
+        blob2 = _blobs6[1],
+        blob3 = _blobs6[2],
+        blob4 = _blobs6[3],
+        blob5 = _blobs6[4],
+        blob6 = _blobs6[5];
+
+    var result1 = decoder1(blob1);
+    var result2 = decoder2(blob2);
+    var result3 = decoder3(blob3);
+    var result4 = decoder4(blob4);
+    var result5 = decoder5(blob5);
+    var result6 = decoder6(blob6);
+
+    try {
+      return Ok([result1.unwrap(), result2.unwrap(), result3.unwrap(), result4.unwrap(), result5.unwrap(), result6.unwrap()]);
+    } catch (e) {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return Err(annotate([result1.isErr() ? result1.errValue() : result1.value(), result2.isErr() ? result2.errValue() : result2.value(), result3.isErr() ? result3.errValue() : result3.value(), result4.isErr() ? result4.errValue() : result4.value(), result5.isErr() ? result5.errValue() : result5.value(), result6.isErr() ? result6.errValue() : result6.value()]));
+    }
+  });
+}
+
+export { array, _boolean as boolean, compose, constant, date, describe, dict, dispatch, either, either3, either4, either5, either6, either7, either8, either9, email, exact, fail, guard, hardcoded, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, map, mapping, maybe, mixed, nonEmptyArray, nonEmptyString, null_, nullable, number, numericBoolean, object, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, predicate, regex, string, truthy, tuple1, tuple2, tuple3, tuple4, tuple5, tuple6, undefined_, unknown, url };