decoders 2.0.0-beta9 → 2.0.0

package/lib/numbers.d.ts

@@ -0,0 +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>;
+
+/**
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
+ * or positive and negative `Infinity` will get rejected.
+ */
+export const number: 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

@@ -0,0 +1,51 @@
+"use strict";
+
+exports.__esModule = true;
+exports.positiveNumber = exports.positiveInteger = exports.number = exports.integer = exports.anyNumber = void 0;
+
+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.
+ */
+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`,
+ * or positive and negative `Infinity` will get rejected.
+ */
+
+exports.anyNumber = anyNumber;
+var number = anyNumber.refine(function (n) {
+  return Number.isFinite(n);
+}, 'Number must be finite');
+/**
+ * Accepts only finite whole numbers.
+ */
+
+exports.number = number;
+var integer = number.refine(function (n) {
+  return Number.isInteger(n);
+}, 'Number must be an integer');
+/**
+ * Accepts only positive finite numbers.
+ */
+
+exports.integer = integer;
+var positiveNumber = number.refine(function (n) {
+  return n >= 0;
+}, 'Number must be positive');
+/**
+ * Accepts only positive finite whole numbers.
+ */
+
+exports.positiveNumber = positiveNumber;
+var positiveInteger = integer.refine(function (n) {
+  return n >= 0;
+}, 'Number must be positive');
+exports.positiveInteger = positiveInteger;

package/lib/numbers.js.flow

@@ -0,0 +1,48 @@
+// @flow strict
+
+import { define } from '../Decoder';
+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.
+ */
+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`,
+ * or positive and negative `Infinity` will get rejected.
+ */
+export const number: Decoder<number> = anyNumber.refine(
+    (n) => Number.isFinite(n),
+    'Number must be finite',
+);
+
+/**
+ * Accepts only finite whole numbers.
+ */
+export const integer: Decoder<number> = number.refine(
+    (n) => Number.isInteger(n),
+    'Number must be an integer',
+);
+
+/**
+ * Accepts only positive finite numbers.
+ */
+export const positiveNumber: Decoder<number> = number.refine(
+    (n) => n >= 0,
+    'Number must be positive',
+);
+
+/**
+ * Accepts only positive finite whole numbers.
+ */
+export const positiveInteger: Decoder<number> = integer.refine(
+    (n) => n >= 0,
+    'Number must be positive',
+);

package/lib/numbers.mjs

@@ -0,0 +1,41 @@
+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.
+ */
+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`,
+ * or positive and negative `Infinity` will get rejected.
+ */
+
+export var number = anyNumber.refine(function (n) {
+  return Number.isFinite(n);
+}, 'Number must be finite');
+/**
+ * Accepts only finite whole numbers.
+ */
+
+export var integer = number.refine(function (n) {
+  return Number.isInteger(n);
+}, 'Number must be an integer');
+/**
+ * Accepts only positive finite numbers.
+ */
+
+export var positiveNumber = number.refine(function (n) {
+  return n >= 0;
+}, 'Number must be positive');
+/**
+ * Accepts only positive finite whole numbers.
+ */
+
+export var positiveInteger = integer.refine(function (n) {
+  return n >= 0;
+}, 'Number must be positive');

package/lib/objects.d.ts

@@ -0,0 +1,75 @@
+/// <reference lib="es6" />
+
+import { Decoder, DecoderType } from '../Decoder';
+import { AllowImplicit } from './_helpers';
+
+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] }>;
+//         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+//         This is basically just equivalent to:
+//             ObjectDecoderType<O>
+//
+//         But by "resolving" this with a mapped type, we remove the helper
+//         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<
+    { [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] } & {
+        [extra: string]: unknown;
+    }
+>;
+
+/**
+ * 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/{core/object.js → lib/objects.js}

@@ -10,19 +10,10 @@ exports.pojo = void 0;
 
 var _annotate = require("../annotate");
 
-var _composition = require("./composition");
-
-var _result = require("../result");
+var _Decoder = require("../Decoder");
 
 function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 
-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();
   xs.forEach(function (x) {
@@ -32,9 +23,17 @@ function subtract(xs, ys) {
   });
   return result;
 }
+/**
+ * Accepts any "plain old JavaScript object", but doesn't validate its keys or
+ * values further.
+ */
 
-var pojo = function pojo(blob) {
-  return isPojo(blob) ? (0, _result.ok)( // NOTE:
+
+var pojo = (0, _Decoder.define)(function (blob, ok, err) {
+  return blob !== null && blob !== undefined && typeof blob === 'object' && // This still seems to be the only reliable way to determine whether
+  // something is a pojo... ¯\_(ツ)_/¯
+  // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(blob) === '[object Object]' ? ok( // NOTE:
   // Since Flow 0.98, typeof o === 'object' refines to
   //     {| +[string]: mixed |}
   // instead of
@@ -48,46 +47,31 @@ var pojo = function pojo(blob) {
   // 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)
-  _extends({}, blob)) : (0, _result.err)((0, _annotate.annotate)(blob, 'Must be an object'));
-};
+  _extends({}, blob)) : err('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<...>.
+ * Accepts objects with fields matching the given decoders. Extra fields that
+ * exist on the input object are ignored and will not be returned.
  */
 
-
 exports.pojo = pojo;
 
-function object(mapping) {
-  var known = new Set(Object.keys(mapping));
-  return (0, _composition.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
+function object(decodersByKey) {
+  // Compute this set at decoder definition time
+  var knownKeys = new Set(Object.keys(decodersByKey));
+  return pojo.then(function (plainObj, ok, err) {
+    var actualKeys = new Set(Object.keys(plainObj)); // At this point, "missingKeys" 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 missingKeys = subtract(knownKeys, actualKeys);
     var record = {};
     var errors = null;
-    Object.keys(mapping).forEach(function (key) {
-      var decoder = mapping[key];
-      var rawValue = blob[key];
-      var result = decoder(rawValue);
+    Object.keys(decodersByKey).forEach(function (key) {
+      var decoder = decodersByKey[key];
+      var rawValue = plainObj[key];
+      var result = decoder.decode(rawValue);
 
       if (result.ok) {
         var value = result.value;
@@ -98,7 +82,7 @@ function object(mapping) {
         // tracker
 
 
-        missing["delete"](key);
+        missingKeys["delete"](key);
       } else {
         var ann = result.error; // Keep track of the annotation, but don't return just yet. We
         // want to collect more error information.
@@ -108,7 +92,7 @@ function object(mapping) {
           // undefined.  This covers explicit undefineds to be
           // treated the same as implicit undefineds (aka missing
           // keys).
-          missing.add(key);
+          missingKeys.add(key);
         } else {
           if (errors === null) {
             errors = {};
@@ -122,53 +106,59 @@ function object(mapping) {
     // object.  Lastly, any fields that are missing should be annotated on
     // the outer object itself.
 
-    if (errors || missing.size > 0) {
-      var objAnn = (0, _annotate.annotateObject)(blob);
+    if (errors || missingKeys.size > 0) {
+      var objAnn = (0, _annotate.annotateObject)(plainObj);
 
       if (errors) {
         objAnn = (0, _annotate.merge)(objAnn, errors);
       }
 
-      if (missing.size > 0) {
-        var errMsg = Array.from(missing).map(function (key) {
+      if (missingKeys.size > 0) {
+        var errMsg = Array.from(missingKeys).map(function (key) {
           return "\"" + key + "\"";
         }).join(', ');
-        var pluralized = missing.size > 1 ? 'keys' : 'key';
+        var pluralized = missingKeys.size > 1 ? 'keys' : 'key';
         objAnn = (0, _annotate.updateText)(objAnn, "Missing " + pluralized + ": " + errMsg);
       }
 
-      return (0, _result.err)(objAnn);
+      return err(objAnn);
     }
 
-    return (0, _result.ok)(record);
+    return ok(record);
   });
 }
+/**
+ * Like `object()`, but will reject inputs that contain extra fields that are
+ * not specified explicitly.
+ */
 
-function exact(mapping) {
-  // Check the inputted object for any superfluous keys
-  var allowed = new Set(Object.keys(mapping));
-  var checked = (0, _composition.compose)(pojo, function (blob) {
-    var actual = new Set(Object.keys(blob));
-    var superfluous = subtract(actual, allowed);
 
-    if (superfluous.size > 0) {
-      return (0, _result.err)((0, _annotate.annotate)(blob, "Superfluous keys: " + Array.from(superfluous).join(', ')));
-    }
+function exact(decodersByKey) {
+  // Compute this set at decoder definition time
+  var allowedKeys = new Set(Object.keys(decodersByKey)); // Check the inputted object for any unexpected extra keys
 
-    return (0, _result.ok)(blob);
+  var checked = pojo.reject(function (plainObj) {
+    var actualKeys = new Set(Object.keys(plainObj));
+    var extraKeys = subtract(actualKeys, allowedKeys);
+    return extraKeys.size > 0 ? "Unexpected extra keys: " + Array.from(extraKeys).join(', ') : // Don't reject
+    null;
   }); // 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 (0, _composition.compose)(checked, decoder);
+  return checked.then(object(decodersByKey).decode);
 }
+/**
+ * Like `object()`, but will pass through any extra fields on the input object
+ * unvalidated that will thus be of `unknown` type statically.
+ */
 
-function inexact(mapping) {
-  return (0, _composition.compose)(pojo, function (blob) {
-    var allkeys = new Set(Object.keys(blob));
-    var decoder = (0, _composition.transform)(object(mapping), function (safepart) {
-      var safekeys = new Set(Object.keys(mapping)); // To account for hard-coded keys that aren't part of the input
+
+function inexact(decodersByKey) {
+  return pojo.then(function (plainObj) {
+    var allkeys = new Set(Object.keys(plainObj));
+    var decoder = object(decodersByKey).transform(function (safepart) {
+      var safekeys = new Set(Object.keys(decodersByKey)); // To account for hard-coded keys that aren't part of the input
 
       safekeys.forEach(function (k) {
         return allkeys.add(k);
@@ -182,26 +172,33 @@ function inexact(mapping) {
             rv[k] = value;
           }
         } else {
-          rv[k] = blob[k];
+          rv[k] = plainObj[k];
         }
       });
       return rv;
     });
-    return decoder(blob);
+    return decoder.decode(plainObj);
   });
 }
 /**
- * Like mapping(), but returns an object rather than a Map instance.
+ * 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.
  */
 
 
 function dict(decoder) {
-  return (0, _composition.compose)(pojo, function (blob) {
+  return pojo.then(function (plainObj, ok, err) {
     var rv = {};
     var errors = null;
-    Object.keys(blob).forEach(function (key) {
-      var value = blob[key];
-      var result = decoder(value);
+    Object.keys(plainObj).forEach(function (key) {
+      var value = plainObj[key];
+      var result = decoder.decode(value);
 
       if (result.ok) {
         if (errors === null) {
@@ -219,25 +216,21 @@ function dict(decoder) {
     });
 
     if (errors !== null) {
-      return (0, _result.err)((0, _annotate.merge)((0, _annotate.annotateObject)(blob), errors));
+      return err((0, _annotate.merge)((0, _annotate.annotateObject)(plainObj), errors));
     } else {
-      return (0, _result.ok)(rv);
+      return ok(rv);
     }
   });
 }
 /**
- * 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)
- *
+ * 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.
  */
 
 
 function mapping(decoder) {
-  return (0, _composition.transform)(dict(decoder), function (obj) {
+  return dict(decoder).transform(function (obj) {
     return new Map( // This is effectively Object.entries(obj), but in a way that Flow
     // will know the types are okay
     Object.keys(obj).map(function (key) {