decoders 2.0.0-beta1 → 2.0.0-beta13

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/lib/objects.js

@@ -0,0 +1,240 @@
+"use strict";
+
+exports.__esModule = true;
+exports.dict = dict;
+exports.exact = exact;
+exports.inexact = inexact;
+exports.mapping = mapping;
+exports.object = object;
+exports.pojo = void 0;
+
+var _annotate = require("../annotate");
+
+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 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.
+ */
+
+
+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
+  //     {| [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.
+ */
+
+exports.pojo = pojo;
+
+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 = (0, _annotate.annotateObject)(plainObj);
+
+      if (errors) {
+        objAnn = (0, _annotate.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 = (0, _annotate.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.
+ */
+
+
+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.
+ */
+
+
+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.
+ */
+
+
+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((0, _annotate.merge)((0, _annotate.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.
+ */
+
+
+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]];
+    }));
+  });
+}