decoders 1.25.5 → 2.0.0-beta2

package/_esm/core/object.js

@@ -0,0 +1,175 @@
+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 * as Result from '../result';
+import { annotate, annotateObject, merge, updateText } from '../annotate';
+import { compose, map } from './composition';
+
+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) {
+    if (!ys.has(x)) {
+      result.add(x);
+    }
+  });
+  return result;
+}
+
+export var pojo = function pojo(blob) {
+  return isPojo(blob) ? Result.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)
+  _extends({}, blob)) : Result.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<...>.
+ */
+
+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
+    // remove the key from this missing set if the decoder accepts the
+    // value.
+
+    var missing = subtract(known, actual);
+    var record = {};
+    var errors = null;
+    Object.keys(mapping).forEach(function (key) {
+      var decoder = mapping[key];
+      var rawValue = blob[key];
+      var result = decoder(rawValue);
+
+      if (result.type === 'ok') {
+        var value = result.value;
+
+        if (value !== undefined) {
+          record[key] = value;
+        } // If this succeeded, remove the key from the missing keys
+        // tracker
+
+
+        missing["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.
+
+        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 {
+          if (errors === null) {
+            errors = {};
+          }
+
+          errors[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.
+
+    if (errors || missing.size > 0) {
+      var objAnn = annotateObject(blob);
+
+      if (errors) {
+        objAnn = merge(objAnn, errors);
+      }
+
+      if (missing.size > 0) {
+        var errMsg = Array.from(missing).map(function (key) {
+          return "\"" + key + "\"";
+        }).join(', ');
+        var pluralized = missing.size > 1 ? 'keys' : 'key';
+        objAnn = updateText(objAnn, "Missing " + pluralized + ": " + errMsg);
+      }
+
+      return Result.err(objAnn);
+    }
+
+    return Result.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 Result.err(annotate(blob, "Superfluous keys: " + Array.from(superfluous).join(', ')));
+    }
+
+    return Result.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);
+}
+export 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
+
+      safekeys.forEach(function (k) {
+        return allkeys.add(k);
+      });
+      var rv = {};
+      allkeys.forEach(function (k) {
+        if (safekeys.has(k)) {
+          var value = safepart[k];
+
+          if (value !== undefined) {
+            rv[k] = value;
+          }
+        } else {
+          rv[k] = blob[k];
+        }
+      });
+      return rv;
+    });
+    return decoder(blob);
+  });
+}

package/{object.js.flow → _esm/core/object.js.flow}

@@ -1,11 +1,10 @@
 // @flow strict
 
-import { annotate, annotateFields, isAnnotation } from 'debrief';
-import type { Annotation } from 'debrief';
-import { Err, Ok } from 'lemons/Result';
-
-import type { $DecoderType, Decoder } from './types';
-import { compose, map } from './utils';
+import * as Result from '../result';
+import { annotate, annotateObject, merge, updateText } from '../annotate';
+import { compose, map } from './composition';
+import type { Annotation } from '../annotate';
+import type { Decoder, 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;
@@ -27,17 +26,17 @@ function isPojo(o: mixed): boolean %checks {
 
 function subtract(xs: Set<string>, ys: Set<string>): Set<string> {
     const result = new Set();
-    for (const x of xs) {
+    xs.forEach((x) => {
         if (!ys.has(x)) {
             result.add(x);
         }
-    }
+    });
     return result;
 }
 
 export const pojo: Decoder<{| [string]: mixed |}> = (blob: mixed) => {
     return isPojo(blob)
-        ? Ok(
+        ? Result.ok(
               // NOTE:
               // Since Flow 0.98, typeof o === 'object' refines to
               //     {| +[string]: mixed |}
@@ -52,9 +51,9 @@ export const pojo: Decoder<{| [string]: mixed |}> = (blob: mixed) => {
               // 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)
-              { ...blob }
+              { ...blob },
           )
-        : Err(annotate(blob, 'Must be an object'));
+        : Result.err(annotate(blob, 'Must be an object'));
 };
 
 /**
@@ -77,10 +76,10 @@ export const pojo: Decoder<{| [string]: mixed |}> = (blob: mixed) => {
  * in an object, and wraps it in a Decoder<...>.
  */
 export function object<O: { +[field: string]: AnyDecoder, ... }>(
-    mapping: O
-): Decoder<$ObjMap<O, $DecoderType>> {
+    mapping: O,
+): Decoder<$ObjMap<O, DecoderType>> {
     const known = new Set(Object.keys(mapping));
-    return compose(pojo, (blob: {| [string]: mixed |}) => {
+    return compose(pojo, (blob: { +[string]: mixed }) => {
         const actual = new Set(Object.keys(blob));
 
         // At this point, "missing" will also include all fields that may
@@ -90,16 +89,15 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
         const missing = subtract(known, actual);
 
         let record = {};
-        const fieldErrors: { [key: string]: Annotation } = { ...null };
+        let errors: { [key: string]: Annotation } | null = null;
 
-        // NOTE: We're using .keys() here over .entries(), since .entries()
-        // will type the value part as "mixed"
-        for (const key of Object.keys(mapping)) {
+        Object.keys(mapping).forEach((key) => {
             const decoder = mapping[key];
             const rawValue = blob[key];
             const result = decoder(rawValue);
-            try {
-                const value = result.unwrap();
+
+            if (result.type === 'ok') {
+                const value = result.value;
                 if (value !== undefined) {
                     record[key] = value;
                 }
@@ -107,11 +105,8 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
                 // If this succeeded, remove the key from the missing keys
                 // tracker
                 missing.delete(key);
-            } catch (ann) {
-                /* istanbul ignore next */
-                if (!isAnnotation(ann)) {
-                    throw ann;
-                }
+            } else {
+                const ann = result.error;
 
                 // Keep track of the annotation, but don't return just yet. We
                 // want to collect more error information.
@@ -122,24 +117,23 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
                     // keys).
                     missing.add(key);
                 } else {
-                    fieldErrors[key] = ann;
+                    if (errors === null) {
+                        errors = {};
+                    }
+                    errors[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.
-        const fieldsWithErrors = Object.keys(fieldErrors);
-        if (fieldsWithErrors.length > 0 || missing.size > 0) {
-            let err;
+        if (errors || missing.size > 0) {
+            let objAnn = annotateObject(blob);
 
-            if (fieldsWithErrors.length > 0) {
-                const errorlist = fieldsWithErrors.map((k) => [k, fieldErrors[k]]);
-                err = annotateFields(blob, errorlist);
-            } else {
-                err = annotate(blob);
+            if (errors) {
+                objAnn = merge(objAnn, errors);
             }
 
             if (missing.size > 0) {
@@ -147,54 +141,52 @@ export function object<O: { +[field: string]: AnyDecoder, ... }>(
                     .map((key) => `"${key}"`)
                     .join(', ');
                 const pluralized = missing.size > 1 ? 'keys' : 'key';
-                err = annotate(err, `Missing ${pluralized}: ${errMsg}`);
+                objAnn = updateText(objAnn, `Missing ${pluralized}: ${errMsg}`);
             }
 
-            return Err(err);
+            return Result.err(objAnn);
         }
 
-        return Ok(record);
+        return Result.ok(record);
     });
 }
 
 export function exact<O: { +[field: string]: AnyDecoder, ... }>(
-    mapping: O
-): Decoder<$ObjMap<$Exact<O>, $DecoderType>> {
+    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 Result.err(
+                annotate(blob, `Superfluous keys: ${Array.from(superfluous).join(', ')}`),
             );
         }
-        return Ok(blob);
+        return Result.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.
-    const decoder = ((object(mapping): cast): Decoder<$ObjMap<$Exact<O>, $DecoderType>>);
+    const decoder = ((object(mapping): cast): Decoder<$ObjMap<$Exact<O>, DecoderType>>);
     return compose(checked, decoder);
 }
 
 export function inexact<O: { +[field: string]: AnyDecoder }>(
-    mapping: O
-): Decoder<$ObjMap<O, $DecoderType> & { +[string]: mixed }> {
+    mapping: O,
+): Decoder<$ObjMap<O, DecoderType> & { +[string]: mixed }> {
     return compose(pojo, (blob: {| [string]: mixed |}) => {
         const allkeys = new Set(Object.keys(blob));
-        const decoder = map(object(mapping), (safepart: $ObjMap<O, $DecoderType>) => {
+        const decoder = map(object(mapping), (safepart: $ObjMap<O, DecoderType>) => {
             const safekeys = new Set(Object.keys(mapping));
 
             // To account for hard-coded keys that aren't part of the input
-            for (const k of safekeys) {
-                allkeys.add(k);
-            }
+            safekeys.forEach((k) => allkeys.add(k));
 
             const rv = {};
-            for (const k of allkeys) {
+            allkeys.forEach((k) => {
                 if (safekeys.has(k)) {
                     const value = safepart[k];
                     if (value !== undefined) {
@@ -203,7 +195,7 @@ export function inexact<O: { +[field: string]: AnyDecoder }>(
                 } else {
                     rv[k] = blob[k];
                 }
-            }
+            });
             return rv;
         });
         return decoder(blob);

package/_esm/core/optional.js

@@ -0,0 +1,38 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { either } from './either';
+import { null_, undefined_ } from './constants';
+
+/**
+ * Builds a Decoder that returns Ok for either `undefined` or `T` values,
+ * given a Decoder for `T`.  Err otherwise.
+ */
+export 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.
+ */
+
+export 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 ? Result.ok(blob) : // Combine error message into a single line
+  Result.err(annotate(blob, 'Must be undefined or null'));
+};
+/**
+ * Decoder that only returns Ok for `null` or `undefined` inputs.
+ */
+
+
+export function maybe(decoder) {
+  return either(undefined_or_null, decoder);
+}

package/{optional.js.flow → _esm/core/optional.js.flow}

@@ -1,11 +1,10 @@
 // @flow strict
 
-import { annotate } from 'debrief';
-import { Err, Ok } from 'lemons/Result';
-
-import { null_, undefined_ } from './constants';
+import * as Result from '../result';
+import { annotate } from '../annotate';
 import { either } from './either';
-import type { Decoder } from './types';
+import { null_, undefined_ } from './constants';
+import type { Decoder } from '../_types';
 
 /**
  * Builds a Decoder that returns Ok for either `undefined` or `T` values,
@@ -30,9 +29,9 @@ export function nullable<T>(decoder: Decoder<T>): Decoder<null | T> {
  */
 const undefined_or_null: Decoder<null | void> = (blob: mixed) =>
     blob === undefined || blob === null
-        ? Ok(blob)
+        ? Result.ok(blob)
         : // Combine error message into a single line
-          Err(annotate(blob, 'Must be undefined or null'));
+          Result.err(annotate(blob, 'Must be undefined or null'));
 
 /**
  * Decoder that only returns Ok for `null` or `undefined` inputs.

package/{string.js → _esm/core/string.js}

@@ -1,17 +1,6 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.nonEmptyString = exports.email = void 0;
-exports.regex = regex;
-exports.url = exports.string = void 0;
-
-var _debrief = require("debrief");
-
-var _Result = require("lemons/Result");
-
-var _utils = require("./utils");
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
 
 /** Match groups in this regex:
  * \1 - the scheme
@@ -27,26 +16,22 @@ var DEFAULT_SCHEMES = ['https'];
  * Decoder that only returns Ok for string inputs.  Err otherwise.
  */
 
-var string = function string(blob) {
-  return typeof blob === 'string' ? (0, _Result.Ok)(blob) : (0, _Result.Err)((0, _debrief.annotate)(blob, 'Must be string'));
+export var string = function string(blob) {
+  return typeof blob === 'string' ? Result.ok(blob) : Result.err(annotate(blob, 'Must be string'));
 };
 /**
  * Decoder that only returns Ok for non-empty string inputs.  Err otherwise.
  */
 
-
-exports.string = string;
-var nonEmptyString = regex(/\S/, 'Must be non-empty string');
+export 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.
  */
 
-exports.nonEmptyString = nonEmptyString;
-
-function regex(regex, msg) {
-  return (0, _utils.compose)(string, (0, _utils.predicate)(function (s) {
+export function regex(regex, msg) {
+  return compose(string, predicate(function (s) {
     return regex.test(s);
   }, msg));
 }
@@ -55,8 +40,7 @@ function regex(regex, msg) {
  * 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');
+export 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.
@@ -69,25 +53,24 @@ var email = regex(/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@(
  * - url(['https', 'git+ssh'])  accepts both https:// and git+ssh:// URLs
  */
 
-exports.email = email;
+export var url = function url(schemes) {
+  if (schemes === void 0) {
+    schemes = DEFAULT_SCHEMES;
+  }
 
-var url = function url() {
-  var schemes = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : DEFAULT_SCHEMES;
-  return (0, _utils.compose)(string, function (value) {
+  return compose(string, function (value) {
     var matches = value.match(url_re);
 
     if (!matches) {
-      return (0, _Result.Err)((0, _debrief.annotate)(value, 'Must be URL'));
+      return Result.err(annotate(value, 'Must be URL'));
     } else {
       var scheme = matches[1];
 
       if (schemes.length === 0 || schemes.includes(scheme.toLowerCase())) {
-        return (0, _Result.Ok)(value);
+        return Result.ok(value);
       } else {
-        return (0, _Result.Err)((0, _debrief.annotate)(value, "URL scheme must be any of: ".concat(schemes.join(', '))));
+        return Result.err(annotate(value, "URL scheme must be any of: " + schemes.join(', ')));
       }
     }
   });
-};
-
-exports.url = url;
+};

package/{string.js.flow → _esm/core/string.js.flow}

@@ -1,10 +1,9 @@
 // @flow strict
 
-import { annotate } from 'debrief';
-import { Err, Ok } from 'lemons/Result';
-
-import type { Decoder } from './types';
-import { compose, predicate } from './utils';
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
+import type { Decoder } from '../_types';
 
 /** Match groups in this regex:
  * \1 - the scheme
@@ -23,7 +22,9 @@ const DEFAULT_SCHEMES = ['https'];
  * Decoder that only returns Ok for string inputs.  Err otherwise.
  */
 export const string: Decoder<string> = (blob: mixed) => {
-    return typeof blob === 'string' ? Ok(blob) : Err(annotate(blob, 'Must be string'));
+    return typeof blob === 'string'
+        ? Result.ok(blob)
+        : Result.err(annotate(blob, 'Must be string'));
 };
 
 /**
@@ -39,7 +40,7 @@ export const nonEmptyString: Decoder<string> = regex(/\S/, 'Must be non-empty st
 export function regex(regex: RegExp, msg: string): Decoder<string> {
     return compose(
         string,
-        predicate((s) => regex.test(s), msg)
+        predicate((s) => regex.test(s), msg),
     );
 }
 
@@ -49,7 +50,7 @@ export function regex(regex: RegExp, msg: string): Decoder<string> {
  */
 export const email: Decoder<string> = 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'
+    'Must be email',
 );
 
 /**
@@ -67,14 +68,14 @@ export const url = (schemes: $ReadOnlyArray<string> = DEFAULT_SCHEMES): Decoder<
     compose(string, (value: string) => {
         const matches = value.match(url_re);
         if (!matches) {
-            return Err(annotate(value, 'Must be URL'));
+            return Result.err(annotate(value, 'Must be URL'));
         } else {
             const scheme = matches[1];
             if (schemes.length === 0 || schemes.includes(scheme.toLowerCase())) {
-                return Ok(value);
+                return Result.ok(value);
             } else {
-                return Err(
-                    annotate(value, `URL scheme must be any of: ${schemes.join(', ')}`)
+                return Result.err(
+                    annotate(value, `URL scheme must be any of: ${schemes.join(', ')}`),
                 );
             }
         }