decoders 2.0.0-beta9 → 2.0.0

package/{core/object.js.flow → lib/objects.js.flow}

@@ -1,28 +1,10 @@
 // @flow strict
 
-import { annotate, annotateObject, merge, updateText } from '../annotate';
-import { compose, transform } from './composition';
-import { err, ok } from '../result';
+import { annotateObject, merge, updateText } from '../annotate';
+import { define } from '../Decoder';
 import type { Annotation } from '../annotate';
-import type { Decoder, DecodeResult, DecoderType } from '../_types';
-
-// $FlowFixMe[unclear-type] (not really an issue) - deliberate use of `any` - not sure how we should get rid of this
-type AnyDecoder = any;
-
-// $FlowFixMe[unclear-type] (not really an issue) - deliberately casting
-type cast = any;
-
-function isPojo(o: mixed): boolean %checks {
-    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]'
-    );
-}
+import type { _Any as AnyDecoder } from '../_utils';
+import type { Decoder, DecodeResult } from '../Decoder';
 
 function subtract(xs: Set<string>, ys: Set<string>): Set<string> {
     const result = new Set();
@@ -34,8 +16,18 @@ function subtract(xs: Set<string>, ys: Set<string>): Set<string> {
     return result;
 }
 
-export const pojo: Decoder<{| [string]: mixed |}> = (blob: mixed) => {
-    return isPojo(blob)
+/**
+ * Accepts any "plain old JavaScript object", but doesn't validate its keys or
+ * values further.
+ */
+export const pojo: Decoder<{| [string]: mixed |}> = define((blob, ok, err) =>
+    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
@@ -53,48 +45,35 @@ export const pojo: Decoder<{| [string]: mixed |}> = (blob: mixed) => {
               // https://thecodebarbarian.com/object-assign-vs-object-spread.html)
               { ...blob },
           )
-        : err(annotate(blob, 'Must be an object'));
-};
+        : 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.
  */
 export function object<O: { +[field: string]: AnyDecoder, ... }>(
-    mapping: O,
-): Decoder<$ObjMap<O, DecoderType>> {
-    const known = new Set(Object.keys(mapping));
-    return compose(pojo, (blob: { +[string]: mixed }) => {
-        const actual = new Set(Object.keys(blob));
+    decodersByKey: O,
+): Decoder<$ObjMap<O, <T>(Decoder<T>) => T>> {
+    // Compute this set at decoder definition time
+    const knownKeys = new Set(Object.keys(decodersByKey));
+
+    return pojo.then((plainObj, ok, err) => {
+        const actualKeys = new Set(Object.keys(plainObj));
 
-        // At this point, "missing" will also include all fields that may
-        // validly be optional.  We'll let the underlying decoder decide and
+        // 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.
-        const missing = subtract(known, actual);
+        const missingKeys = subtract(knownKeys, actualKeys);
 
         let record = {};
         let errors: { [key: string]: Annotation } | null = null;
 
-        Object.keys(mapping).forEach((key) => {
-            const decoder = mapping[key];
-            const rawValue = blob[key];
-            const result: DecodeResult<mixed> = decoder(rawValue);
+        Object.keys(decodersByKey).forEach((key) => {
+            const decoder = decodersByKey[key];
+            const rawValue = plainObj[key];
+            const result: DecodeResult<mixed> = decoder.decode(rawValue);
 
             if (result.ok) {
                 const value = result.value;
@@ -104,7 +83,7 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
 
                 // If this succeeded, remove the key from the missing keys
                 // tracker
-                missing.delete(key);
+                missingKeys.delete(key);
             } else {
                 const ann = result.error;
 
@@ -115,7 +94,7 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
                     // 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 = {};
@@ -129,18 +108,18 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
         // 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.
-        if (errors || missing.size > 0) {
-            let objAnn = annotateObject(blob);
+        if (errors || missingKeys.size > 0) {
+            let objAnn = annotateObject(plainObj);
 
             if (errors) {
                 objAnn = merge(objAnn, errors);
             }
 
-            if (missing.size > 0) {
-                const errMsg = Array.from(missing)
+            if (missingKeys.size > 0) {
+                const errMsg = Array.from(missingKeys)
                     .map((key) => `"${key}"`)
                     .join(', ');
-                const pluralized = missing.size > 1 ? 'keys' : 'key';
+                const pluralized = missingKeys.size > 1 ? 'keys' : 'key';
                 objAnn = updateText(objAnn, `Missing ${pluralized}: ${errMsg}`);
             }
 
@@ -151,38 +130,44 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
     });
 }
 
+/**
+ * Like `object()`, but will reject inputs that contain extra fields that are
+ * not specified explicitly.
+ */
 export function exact<O: { +[field: string]: AnyDecoder, ... }>(
-    mapping: O,
-): Decoder<$ObjMap<$Exact<O>, DecoderType>> {
-    // Check the inputted object for any superfluous keys
-    const allowed = new Set(Object.keys(mapping));
-    const checked = compose(pojo, (blob: {| [string]: mixed |}) => {
-        const actual = new Set(Object.keys(blob));
-        const superfluous = subtract(actual, allowed);
-        if (superfluous.size > 0) {
-            return err(
-                annotate(blob, `Superfluous keys: ${Array.from(superfluous).join(', ')}`),
-            );
-        }
-        return ok(blob);
+    decodersByKey: O,
+): Decoder<$ObjMap<$Exact<O>, <T>(Decoder<T>) => T>> {
+    // Compute this set at decoder definition time
+    const allowedKeys = new Set(Object.keys(decodersByKey));
+
+    // Check the inputted object for any unexpected extra keys
+    const checked = pojo.reject((plainObj) => {
+        const actualKeys = new Set(Object.keys(plainObj));
+        const 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.
-    const decoder = ((object(mapping): cast): Decoder<$ObjMap<$Exact<O>, DecoderType>>);
-    return 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.
+ */
 export function inexact<O: { +[field: string]: AnyDecoder }>(
-    mapping: O,
-): Decoder<$ObjMap<O, DecoderType> & { +[string]: mixed }> {
-    return compose(pojo, (blob: {| [string]: mixed |}) => {
-        const allkeys = new Set(Object.keys(blob));
-        const decoder = transform(
-            object(mapping),
-            (safepart: $ObjMap<O, DecoderType>) => {
-                const safekeys = new Set(Object.keys(mapping));
+    decodersByKey: O,
+): Decoder<$ObjMap<O, <T>(Decoder<T>) => T> & { +[string]: mixed }> {
+    return pojo.then((plainObj) => {
+        const allkeys = new Set(Object.keys(plainObj));
+        const decoder = object(decodersByKey).transform(
+            (safepart: $ObjMap<O, <T>(Decoder<T>) => T>) => {
+                const safekeys = new Set(Object.keys(decodersByKey));
 
                 // To account for hard-coded keys that aren't part of the input
                 safekeys.forEach((k) => allkeys.add(k));
@@ -195,27 +180,34 @@ export function inexact<O: { +[field: string]: AnyDecoder }>(
                             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.
  */
 export function dict<T>(decoder: Decoder<T>): Decoder<{ [string]: T }> {
-    return compose(pojo, (blob: { +[key: string]: mixed }) => {
+    return pojo.then((plainObj, ok, err) => {
         let rv: { [key: string]: T } = {};
         let errors: { [key: string]: Annotation } | null = null;
 
-        Object.keys(blob).forEach((key: string) => {
-            const value = blob[key];
-            const result = decoder(value);
+        Object.keys(plainObj).forEach((key: string) => {
+            const value = plainObj[key];
+            const result = decoder.decode(value);
             if (result.ok) {
                 if (errors === null) {
                     rv[key] = result.value;
@@ -230,7 +222,7 @@ export function dict<T>(decoder: Decoder<T>): Decoder<{ [string]: T }> {
         });
 
         if (errors !== null) {
-            return err(merge(annotateObject(blob), errors));
+            return err(merge(annotateObject(plainObj), errors));
         } else {
             return ok(rv);
         }
@@ -238,17 +230,12 @@ export function dict<T>(decoder: Decoder<T>): Decoder<{ [string]: T }> {
 }
 
 /**
- * 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.
  */
 export function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>> {
-    return transform(
-        dict(decoder),
+    return dict(decoder).transform(
         (obj) =>
             new Map(
                 // This is effectively Object.entries(obj), but in a way that Flow

package/{core/object.mjs → lib/objects.mjs}

@@ -1,15 +1,7 @@
 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); }
 
-import { annotate, annotateObject, merge, updateText } from '../annotate.mjs';
-import { compose, transform } from './composition.mjs';
-import { err, ok } from '../result.mjs';
-
-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]';
-}
+import { annotateObject, merge, updateText } from '../annotate.mjs';
+import { define } from '../Decoder.mjs';
 
 function subtract(xs, ys) {
   var result = new Set();
@@ -20,9 +12,17 @@ function subtract(xs, ys) {
   });
   return result;
 }
+/**
+ * Accepts any "plain old JavaScript object", but doesn't validate its keys or
+ * values further.
+ */
+
 
-export var pojo = function pojo(blob) {
-  return isPojo(blob) ? ok( // NOTE:
+export var pojo = 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
@@ -36,43 +36,29 @@ export 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)) : err(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.
  */
 
-export 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
+export 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;
@@ -83,7 +69,7 @@ export 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.
@@ -93,7 +79,7 @@ export 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 = {};
@@ -107,18 +93,18 @@ export 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 = annotateObject(blob);
+    if (errors || missingKeys.size > 0) {
+      var objAnn = annotateObject(plainObj);
 
       if (errors) {
         objAnn = 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 = updateText(objAnn, "Missing " + pluralized + ": " + errMsg);
       }
 
@@ -128,30 +114,36 @@ export function object(mapping) {
     return ok(record);
   });
 }
-export 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: " + Array.from(superfluous).join(', ')));
-    }
+/**
+ * Like `object()`, but will reject inputs that contain extra fields that are
+ * not specified explicitly.
+ */
+
+export 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 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 compose(checked, decoder);
+  return checked.then(object(decodersByKey).decode);
 }
-export function inexact(mapping) {
-  return compose(pojo, function (blob) {
-    var allkeys = new Set(Object.keys(blob));
-    var decoder = 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
+/**
+ * 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) {
+  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);
@@ -165,25 +157,32 @@ export 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.
  */
 
 export function dict(decoder) {
-  return 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) {
@@ -201,24 +200,20 @@ export function dict(decoder) {
     });
 
     if (errors !== null) {
-      return err(merge(annotateObject(blob), errors));
+      return err(merge(annotateObject(plainObj), errors));
     } else {
       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.
  */
 
 export function mapping(decoder) {
-  return 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) {

package/lib/strings.d.ts

@@ -0,0 +1,56 @@
+/// <reference lib="dom" />
+
+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>;