decoders 2.0.0-beta1 → 2.0.0-beta13

package/lib/objects.js.flow

@@ -0,0 +1,246 @@
+// @flow strict
+
+import { annotateObject, merge, updateText } from '../annotate';
+import { define } from '../Decoder';
+import type { Annotation } from '../annotate';
+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();
+    xs.forEach((x) => {
+        if (!ys.has(x)) {
+            result.add(x);
+        }
+    });
+    return result;
+}
+
+/**
+ * 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
+              //     {| +[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)
+              { ...blob },
+          )
+        : err('Must be an object'),
+);
+
+/**
+ * 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, ... }>(
+    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, "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 missingKeys = subtract(knownKeys, actualKeys);
+
+        let record = {};
+        let errors: { [key: string]: Annotation } | null = null;
+
+        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;
+                if (value !== undefined) {
+                    record[key] = value;
+                }
+
+                // If this succeeded, remove the key from the missing keys
+                // tracker
+                missingKeys.delete(key);
+            } else {
+                const 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).
+                    missingKeys.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 || missingKeys.size > 0) {
+            let objAnn = annotateObject(plainObj);
+
+            if (errors) {
+                objAnn = merge(objAnn, errors);
+            }
+
+            if (missingKeys.size > 0) {
+                const errMsg = Array.from(missingKeys)
+                    .map((key) => `"${key}"`)
+                    .join(', ');
+                const pluralized = missingKeys.size > 1 ? 'keys' : 'key';
+                objAnn = updateText(objAnn, `Missing ${pluralized}: ${errMsg}`);
+            }
+
+            return err(objAnn);
+        }
+
+        return ok(record);
+    });
+}
+
+/**
+ * Like `object()`, but will reject inputs that contain extra fields that are
+ * not specified explicitly.
+ */
+export function exact<O: { +[field: string]: AnyDecoder, ... }>(
+    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.
+    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 }>(
+    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));
+
+                const rv = {};
+                allkeys.forEach((k) => {
+                    if (safekeys.has(k)) {
+                        const value = safepart[k];
+                        if (value !== undefined) {
+                            rv[k] = value;
+                        }
+                    } else {
+                        rv[k] = plainObj[k];
+                    }
+                });
+                return rv;
+            },
+        );
+        return decoder.decode(plainObj);
+    });
+}
+
+/**
+ * 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 pojo.then((plainObj, ok, err) => {
+        let rv: { [key: string]: T } = {};
+        let errors: { [key: string]: Annotation } | null = null;
+
+        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;
+                }
+            } else {
+                rv = {}; // Clear the success value so it can get garbage collected early
+                if (errors === null) {
+                    errors = {};
+                }
+                errors[key] = result.error;
+            }
+        });
+
+        if (errors !== null) {
+            return err(merge(annotateObject(plainObj), errors));
+        } else {
+            return ok(rv);
+        }
+    });
+}
+
+/**
+ * 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 dict(decoder).transform(
+        (obj) =>
+            new Map(
+                // This is effectively Object.entries(obj), but in a way that Flow
+                // will know the types are okay
+                Object.keys(obj).map((key) => [key, obj[key]]),
+            ),
+    );
+}

package/lib/objects.mjs

@@ -0,0 +1,223 @@
+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 { annotateObject, merge, updateText } from '../annotate.mjs';
+import { define } from '../Decoder.mjs';
+
+function subtract(xs, ys) {
+  var result = new Set();
+  xs.forEach(function (x) {
+    if (!ys.has(x)) {
+      result.add(x);
+    }
+  });
+  return result;
+}
+/**
+ * Accepts any "plain old JavaScript object", but doesn't validate its keys or
+ * values further.
+ */
+
+
+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
+  //     {| [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)) : err('Must be an object');
+});
+/**
+ * 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) {
+  // 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 missingKeys = subtract(knownKeys, actualKeys);
+    var record = {};
+    var errors = null;
+    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;
+
+        if (value !== undefined) {
+          record[key] = value;
+        } // If this succeeded, remove the key from the missing keys
+        // tracker
+
+
+        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.
+
+        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).
+          missingKeys.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 || missingKeys.size > 0) {
+      var objAnn = annotateObject(plainObj);
+
+      if (errors) {
+        objAnn = merge(objAnn, errors);
+      }
+
+      if (missingKeys.size > 0) {
+        var errMsg = Array.from(missingKeys).map(function (key) {
+          return "\"" + key + "\"";
+        }).join(', ');
+        var pluralized = missingKeys.size > 1 ? 'keys' : 'key';
+        objAnn = updateText(objAnn, "Missing " + pluralized + ": " + errMsg);
+      }
+
+      return err(objAnn);
+    }
+
+    return ok(record);
+  });
+}
+/**
+ * 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
+
+  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.
+
+  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(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);
+      });
+      var rv = {};
+      allkeys.forEach(function (k) {
+        if (safekeys.has(k)) {
+          var value = safepart[k];
+
+          if (value !== undefined) {
+            rv[k] = value;
+          }
+        } else {
+          rv[k] = plainObj[k];
+        }
+      });
+      return rv;
+    });
+    return decoder.decode(plainObj);
+  });
+}
+/**
+ * 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 pojo.then(function (plainObj, ok, err) {
+    var rv = {};
+    var errors = null;
+    Object.keys(plainObj).forEach(function (key) {
+      var value = plainObj[key];
+      var result = decoder.decode(value);
+
+      if (result.ok) {
+        if (errors === null) {
+          rv[key] = result.value;
+        }
+      } else {
+        rv = {}; // Clear the success value so it can get garbage collected early
+
+        if (errors === null) {
+          errors = {};
+        }
+
+        errors[key] = result.error;
+      }
+    });
+
+    if (errors !== null) {
+      return err(merge(annotateObject(plainObj), errors));
+    } else {
+      return ok(rv);
+    }
+  });
+}
+/**
+ * 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 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) {
+      return [key, obj[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>;

package/lib/strings.js

@@ -0,0 +1,101 @@
+"use strict";
+
+exports.__esModule = true;
+exports.nonEmptyString = exports.httpsUrl = exports.email = void 0;
+exports.regex = regex;
+exports.uuidv4 = exports.uuidv1 = exports.uuid = exports.url = exports.string = void 0;
+
+var _Decoder = require("../Decoder");
+
+var _unions = require("./unions");
+
+var _utilities = require("./utilities");
+
+/** 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]*)?)?$/;
+/**
+ * Accepts and returns strings.
+ */
+
+var string = (0, _Decoder.define)(function (blob, ok, err) {
+  return typeof blob === 'string' ? ok(blob) : err('Must be string');
+});
+/**
+ * Like `string`, but will reject the empty string or strings containing only whitespace.
+ */
+
+exports.string = string;
+var nonEmptyString = regex(/\S/, 'Must be non-empty string');
+/**
+ * Accepts and returns strings that match the given regular expression.
+ */
+
+exports.nonEmptyString = nonEmptyString;
+
+function regex(regex, msg) {
+  return string.refine(function (s) {
+    return regex.test(s);
+  }, msg);
+}
+/**
+ * Accepts and returns strings that are syntactically valid email addresses.
+ * (This will not mean that the email address actually exist.)
+ */
+
+
+var email = regex( // The almost perfect email regex, taken from https://emailregex.com/
+/^(([^<>()[\]\\.,;:\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');
+/**
+ * Accepts strings that are valid URLs, returns the value as a URL instance.
+ */
+
+exports.email = email;
+var url = (0, _unions.either)(regex(url_re, 'Must be URL').transform(function (value) {
+  return new URL(value);
+}), (0, _utilities.instanceOf)(URL));
+/**
+ * Accepts strings that are valid URLs, but only HTTPS ones. Returns the value
+ * as a URL instance.
+ */
+
+exports.url = url;
+var httpsUrl = url.refine(function (value) {
+  return value.protocol === 'https:';
+}, 'Must be an HTTPS URL');
+/**
+ * Accepts strings that are valid
+ * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
+ * (universally unique identifier).
+ */
+
+exports.httpsUrl = httpsUrl;
+var uuid = regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, 'Must be uuid');
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv1](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_%28date-time_and_MAC_address%29)
+ * strings.
+ */
+
+exports.uuid = uuid;
+var uuidv1 = // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)
+uuid.refine(function (value) {
+  return value[14] === '1';
+}, 'Must be uuidv1');
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_%28random%29)
+ * strings.
+ */
+
+exports.uuidv1 = uuidv1;
+var uuidv4 = // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
+uuid.refine(function (value) {
+  return value[14] === '4';
+}, 'Must be uuidv4');
+exports.uuidv4 = uuidv4;