decoders 1.25.4 → 2.0.0-beta1

package/es/result.js

@@ -0,0 +1,139 @@
+/**
+ * Result <value> <error>
+ *     = Ok <value>
+ *     | Err <error>
+ */
+
+/**
+ * Create a new Result instance representing a successful computation.
+ */
+export function ok(value) {
+  return {
+    type: 'ok',
+    value: value
+  };
+}
+/**
+ * Create a new Result instance representing a failed computation.
+ */
+
+export function err(error) {
+  return {
+    type: 'err',
+    error: error
+  };
+}
+export function toString(result) {
+  return result.type === 'ok' ? "Ok(" + String(result.value) + ")" : "Err(" + String(result.error) + ")";
+}
+export function isOk(result) {
+  return result.type === 'ok';
+}
+export function isErr(result) {
+  return result.type === 'err';
+}
+export function withDefault(result, defaultValue) {
+  return result.type === 'ok' ? result.value : defaultValue;
+}
+export function value(result) {
+  return result.type === 'ok' ? result.value : undefined;
+}
+export function errValue(result) {
+  return result.type === 'err' ? result.error : undefined;
+}
+/**
+ * Unwrap the value from this Result instance if this is an "Ok" result.
+ * Otherwise, will throw the "Err" error via a runtime exception.
+ */
+
+export function unwrap(result) {
+  if (result.type === 'ok') {
+    return result.value;
+  } else {
+    throw result.error;
+  }
+}
+export function expect(result, message) {
+  if (result.type === 'ok') {
+    return result.value;
+  } else {
+    throw message instanceof Error ? message : new Error(message);
+  }
+}
+export function dispatch(result, okCallback, errCallback) {
+  return result.type === 'ok' ? okCallback(result.value) : errCallback(result.error);
+}
+/**
+ * If the given result is OK, defers to the other result. Otherwise returns the
+ * error result.
+ *
+ * It's like saying A && B, but on Result.
+ *
+ * Examples:
+ *
+ *     Result.ok(42)     && Result.ok('hi')    // => Ok('hi')
+ *     Result.err('boo') && Result.ok('hi')    // => Err('boo')
+ *     Result.ok(42)     && Result.err('boo')  // => Err('boo')
+ *     Result.err('boo') && Result.err('boo')  // => Err('boo')
+ *
+ */
+// export function and<T, E, T2>(
+//     result1: Result<T, E>,
+//     result2: Result<T2, E>,
+// ): Result<T2, E> {
+//     return result1.type === 'ok' ? result2 : result1;
+// }
+
+/**
+ * If the given result is OK, return that result. Otherwise, defers to the
+ * other result.
+ *
+ * It's like saying A || B, but on Result.
+ *
+ * Examples:
+ *
+ *     Result.ok(42)      || Result.ok('hi')    // => Ok(42)
+ *     Result.err('boo')  || Result.ok('hi')    // => Ok('hi')
+ *     Result.ok(42)      || Result.err('boo')  // => Ok(42)
+ *     Result.err('bleh') || Result.err('boo')  // => Err('boo')
+ *
+ */
+// export function or<T, E, E2>(
+//     result1: Result<T, E>,
+//     result2: Result<T, E2>,
+// ): Result<T, E2> {
+//     return result1.type === 'ok' ? result1 : result2;
+// }
+
+/**
+ * Like .and(), aka &&, but the second argument gets evaluated lazily only if
+ * the first result is an Ok result. If so, it has access to the Ok value from
+ * the first argument.
+ */
+
+export function andThen(result1, lazyResult2) {
+  return result1.type === 'ok' ? lazyResult2(result1.value) : result1;
+}
+/**
+ * Like .or(), aka ||, but the second argument gets evaluated lazily only if
+ * the first result is an Err result. If so, it has access to the Err value
+ * from the first argument.
+ */
+
+export function orElse(result1, lazyResult2) {
+  return result1.type === 'ok' ? result1 : lazyResult2(result1.error);
+}
+/**
+ * Transform an Ok result. Will not touch Err results.
+ */
+
+export function map(result, mapper) {
+  return result.type === 'ok' ? ok(mapper(result.value)) : result;
+}
+/**
+ * Transform an Err value. Will not touch Ok results.
+ */
+
+export function mapError(result, mapper) {
+  return result.type === 'ok' ? result : err(mapper(result.error));
+}

package/es/stdlib/array.js

@@ -0,0 +1,91 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
+
+/**
+ * Like a "Plain Old JavaScript Object", but for arrays: "Plain Old JavaScript
+ * Array" ^_^
+ */
+export var poja = function poja(blob) {
+  if (!Array.isArray(blob)) {
+    return Result.err(annotate(blob, 'Must be an array'));
+  }
+
+  return Result.ok( // NOTE: Since Flow 0.98, Array.isArray() returns $ReadOnlyArray<mixed>
+  // instead of Array<mixed>.  For rationale, see
+  // https://github.com/facebook/flow/issues/7684.  In this case, we
+  // don't want to output read-only types 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 array into a normal array in
+  // Javascript is to use .slice() on it, see this benchmark:
+  // http://jsben.ch/lO6C5
+  blob.slice());
+};
+/**
+ * Given an array of Result instances, loop over them all and return:
+ * - An [index, err] tuple, indicating the (index of the) first Err instance
+ *   encountered; or
+ * - a new Ok with an array of all unwrapped Ok'ed values
+ */
+
+function all(items, blobs) {
+  var results = [];
+
+  for (var index = 0; index < items.length; ++index) {
+    var result = items[index];
+
+    if (result.type === 'ok') {
+      results.push(result.value);
+    } else {
+      var ann = result.error; // Rewrite the annotation to include the index information, and inject it into the original blob
+
+      var clone = [].concat(blobs);
+      clone.splice(index, 1, annotate(ann, ann.text ? ann.text + " (at index " + index + ")" : "index " + index)); // const errValue = [];
+      // if (index > 0) {
+      //     errValue.push('...'); // TODO: make special mark, not string!
+      // }
+      // errValue.push(
+      // );
+      // if (index < iterable.length - 1) {
+      //     errValue.push('...'); // TODO: make special mark, not string!
+      // }
+
+      return Result.err(annotate(clone));
+    }
+  }
+
+  return Result.ok(results);
+}
+/**
+ * Given a T, builds a decoder that assumes an array input and returns an
+ * Array<T>.
+ */
+
+
+function members(decoder) {
+  return function (blobs) {
+    var results = blobs.map(decoder);
+    var result = all(results, blobs);
+    return result;
+  };
+}
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, given a Decoder
+ * for `T`.  Err otherwise.
+ */
+
+
+export function array(decoder) {
+  return compose(poja, members(decoder));
+}
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, but will reject
+ * empty arrays.
+ */
+
+export function nonEmptyArray(decoder) {
+  return compose(array(decoder), predicate(function (arr) {
+    return arr.length > 0;
+  }, 'Must be non-empty array'));
+}

package/es/stdlib/boolean.js

@@ -0,0 +1,28 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { map } from './composition';
+import { number } from './number';
+
+/**
+ * Decoder that only returns Ok for boolean inputs.  Err otherwise.
+ */
+var _boolean = function _boolean(blob) {
+  return typeof blob === 'boolean' ? Result.ok(blob) : Result.err(annotate(blob, 'Must be boolean'));
+};
+/**
+ * Decoder that returns true for all truthy values, and false otherwise.  Never fails.
+ */
+
+
+export { _boolean as boolean };
+export var truthy = function truthy(blob) {
+  return Result.ok(!!blob);
+};
+/**
+ * Decoder that only returns Ok for numeric input values representing booleans.
+ * Returns their boolean representation.  Err otherwise.
+ */
+
+export var numericBoolean = map(number, function (n) {
+  return !!n;
+});

package/es/stdlib/composition.js

@@ -0,0 +1,42 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+
+/**
+ * Given a decoder T and a mapping function from T's to V's, returns a decoder
+ * for V's.  This is useful to change the original input data.
+ */
+export function map(decoder, mapper) {
+  return compose(decoder, function (x) {
+    try {
+      return Result.ok(mapper(x));
+    } catch (e) {
+      return Result.err(annotate(x, e instanceof Error ? e.message : String(e)));
+    }
+  });
+}
+/**
+ * Compose two decoders by passing the result of the first into the second.
+ * The second decoder may assume as its input type the output type of the first
+ * decoder (so it's not necessary to accept the typical "mixed").  This is
+ * useful for "narrowing down" the checks.  For example, if you want to write
+ * a decoder for positive numbers, you can compose it from an existing decoder
+ * for any number, and a decoder that, assuming a number, checks if it's
+ * positive.  Very often combined with the predicate() helper as the second
+ * argument.
+ */
+
+export function compose(decoder, next) {
+  return function (blob) {
+    return Result.andThen(decoder(blob), next);
+  };
+}
+/**
+ * Factory function returning a Decoder<T>, given a predicate function that
+ * accepts/rejects the input of type T.
+ */
+
+export function predicate(predicate, msg) {
+  return function (value) {
+    return predicate(value) ? Result.ok(value) : Result.err(annotate(value, msg));
+  };
+}

package/es/stdlib/constants.js

@@ -0,0 +1,46 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+
+/**
+ * Decoder that only returns Ok for `null` inputs.  Err otherwise.
+ */
+export var null_ = function null_(blob) {
+  return blob === null ? Result.ok(blob) : Result.err(annotate(blob, 'Must be null'));
+};
+/**
+ * Decoder that only returns Ok for `undefined` inputs.  Err otherwise.
+ */
+
+export var undefined_ = function undefined_(blob) {
+  return blob === undefined ? Result.ok(blob) : Result.err(annotate(blob, 'Must be undefined'));
+};
+/**
+ * Decoder that only returns Ok for the given value constant.  Err otherwise.
+ */
+
+export function constant(value) {
+  return function (blob) {
+    return blob === value ? Result.ok(value) : Result.err(annotate(blob, "Must be constant " + String(value)));
+  };
+}
+/**
+ * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
+ */
+
+export function hardcoded(value) {
+  return function () {
+    return Result.ok(value);
+  };
+}
+/**
+ * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
+ */
+
+export var unknown = function unknown(blob) {
+  return Result.ok(blob);
+};
+/**
+ * Alias of unknown.
+ */
+
+export var mixed = unknown;

package/es/stdlib/date.js

@@ -0,0 +1,28 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { isDate } from '../_utils';
+import { map } from './composition';
+import { regex } from './string';
+// Only matches the shape.  This "over-matches" some values that still aren't
+// valid dates (like 9999-99-99), but those will be caught by JS Date's
+// internal validations
+var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+export var date = function date(value) {
+  return isDate(value) ? Result.ok(value) : Result.err(annotate(value, 'Must be a Date'));
+};
+/**
+ * Decoder that only returns Ok for strings that are valid ISO8601 date
+ * strings.  Err otherwise.
+ */
+
+export var iso8601 = map( // Input itself needs to match the ISO8601 regex...
+regex(iso8601_re, 'Must be ISO8601 format'), // Make sure it is a _valid_ date
+function (value) {
+  var date = new Date(value);
+
+  if (isNaN(date.getTime())) {
+    throw new Error('Must be valid date/time value');
+  }
+
+  return date;
+});

package/{describe.js → es/stdlib/describe.js}

@@ -1,11 +1,5 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.describe = describe;
-
-var _debrief = require("debrief");
+import * as Result from '../result';
+import { annotate } from '../annotate';
 
 /**
  * Wrap another decoder, and override the error message in case it fails. This
@@ -13,10 +7,10 @@ var _debrief = require("debrief");
  * use language in those error messages that can be relayed to end users (for
  * example to show in form errors).
  */
-function describe(decoder, message) {
+export function describe(decoder, message) {
   return function (blob) {
-    return decoder(blob).mapError(function (err) {
-      return (0, _debrief.annotate)(err, message);
+    return Result.mapError(decoder(blob), function (err) {
+      return annotate(err, message);
     });
   };
 }

package/{dispatch.js → es/stdlib/dispatch.js}

@@ -1,15 +1,6 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.dispatch = dispatch;
-
-var _either = require("./either");
-
-var _object2 = require("./object");
-
-function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+import * as Result from '../result';
+import { object } from './object';
+import { oneOf } from './either';
 
 /**
  * Dispatches to one of several given decoders, based on the value found at
@@ -46,10 +37,12 @@ function _defineProperty(obj, key, value) { if (key in obj) { Object.definePrope
  *
  * Also, the error messages will be less ambiguous using `dispatch()`.
  */
-function dispatch(field, mapping) {
-  var base = (0, _object2.object)(_defineProperty({}, field, (0, _either.oneOf)(Object.keys(mapping))));
+export function dispatch(field, mapping) {
+  var _object;
+
+  var base = object((_object = {}, _object[field] = oneOf(Object.keys(mapping)), _object));
   return function (blob) {
-    return base(blob).andThen(function (baseObj) {
+    return Result.andThen(base(blob), function (baseObj) {
       var decoderName = baseObj[field];
       var decoder = mapping[decoderName];
       return decoder(blob);

package/es/stdlib/either.js

@@ -0,0 +1,90 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { indent, summarize } from '../_utils';
+
+/**
+ * Indents and adds a dash in front of this (potentially multiline) string.
+ */
+function itemize(s) {
+  return '-' + indent(s).substring(1);
+}
+/**
+ * Nests another error as an item under a new-to-be-created "Either error". If
+ * the given subitem already is an "Either error" of itself, don't indent, but
+ * just "inject" its items at the same error level, for nicely flattened either
+ * expressions.
+ *
+ * Avoids:
+ *
+ *     Either:
+ *     - Either:
+ *       - Must be P
+ *       - Either:
+ *         - Must be Q
+ *         - Must be R
+ *     - Must be S
+ *
+ * And "flattens" these to:
+ *
+ *     Either:
+ *     - Must be P
+ *     - Must be Q
+ *     - Must be R
+ *     - Must be S
+ *
+ */
+
+
+function nest(errText) {
+  var EITHER_PREFIX = 'Either:\n';
+  return errText.startsWith(EITHER_PREFIX) ? errText.substr(EITHER_PREFIX.length) : itemize(errText);
+}
+
+export function either(d1, d2) {
+  return function (blob) {
+    return Result.orElse(d1(blob), function (err1) {
+      return Result.orElse(d2(blob), function (err2) {
+        var serr1 = summarize(err1).join('\n');
+        var serr2 = summarize(err2).join('\n');
+        var text = ['Either:', nest(serr1), nest(serr2)].join('\n');
+        return Result.err(annotate(blob, text));
+      });
+    });
+  };
+}
+export function either3(d1, d2, d3) {
+  return either(d1, either(d2, d3));
+}
+export function either4(d1, d2, d3, d4) {
+  return either(d1, either3(d2, d3, d4));
+}
+export function either5(d1, d2, d3, d4, d5) {
+  return either(d1, either4(d2, d3, d4, d5));
+}
+export function either6(d1, d2, d3, d4, d5, d6) {
+  return either(d1, either5(d2, d3, d4, d5, d6));
+}
+export function either7(d1, d2, d3, d4, d5, d6, d7) {
+  return either(d1, either6(d2, d3, d4, d5, d6, d7));
+}
+export function either8(d1, d2, d3, d4, d5, d6, d7, d8) {
+  return either(d1, either7(d2, d3, d4, d5, d6, d7, d8));
+}
+export function either9(d1, d2, d3, d4, d5, d6, d7, d8, d9) {
+  return either(d1, either8(d2, d3, d4, d5, d6, d7, d8, d9));
+}
+export function oneOf(constants) {
+  return function (blob) {
+    var winner = constants.find(function (c) {
+      return c === blob;
+    });
+
+    if (winner !== undefined) {
+      return Result.ok(winner);
+    }
+
+    return Result.err(annotate(blob, "Must be one of " + constants.map(function (value) {
+      return JSON.stringify(value);
+    }).join(', ')));
+  };
+}

package/es/stdlib/fail.js

@@ -0,0 +1,11 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+
+/**
+ * Decoder that always fails with the given error message, no matter what the input.
+ */
+export function fail(msg) {
+  return function (blob) {
+    return Result.err(annotate(blob, msg));
+  };
+}

package/es/stdlib/instanceOf.js

@@ -0,0 +1,8 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+export function instanceOf(klass) {
+  return function (blob) {
+    return blob instanceof klass ? Result.ok(blob) : Result.err(annotate(blob, "Must be " + // $FlowFixMe[incompatible-use] - klass.name is fine?
+    klass.name + " instance"));
+  };
+}

package/es/stdlib/json.js

@@ -0,0 +1,15 @@
+import { array } from './array';
+import { boolean as _boolean } from './boolean';
+import { dict } from './mapping';
+import { either6 } from './either';
+import { lazy } from './lazy';
+import { null_ } from './constants';
+import { number } from './number';
+import { string } from './string';
+export var jsonObject = lazy(function () {
+  return dict(json);
+});
+export var jsonArray = lazy(function () {
+  return array(json);
+});
+export var json = either6(null_, string, number, _boolean, jsonObject, jsonArray);

package/es/stdlib/lazy.js

@@ -0,0 +1,11 @@
+/**
+ * Given an function returning a Decoder, will use that decoder to decode the
+ * value. This is typically used to build decoders for recursive or
+ * self-referential types.
+ */
+export function lazy(decoderFn) {
+  return function (blob) {
+    var decoder = decoderFn();
+    return decoder(blob);
+  };
+}

package/es/stdlib/mapping.js

@@ -0,0 +1,54 @@
+import * as Result from '../result';
+import { annotateObject } from '../annotate';
+import { compose, map } from './composition';
+import { merge } from '../annotate';
+import { pojo } from './object';
+
+/**
+ * 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)
+ *
+ */
+export function mapping(decoder) {
+  return compose(pojo, function (blob) {
+    var tuples = [];
+    var errors = null;
+    Object.keys(blob).forEach(function (key) {
+      var value = blob[key];
+      var result = decoder(value);
+
+      if (result.type === 'ok') {
+        if (errors === null) {
+          tuples.push([key, result.value]);
+        }
+      } else {
+        tuples.length = 0; // Clear the tuples array
+
+        if (errors === null) {
+          errors = {};
+        }
+
+        errors[key] = result.error;
+      }
+    });
+
+    if (errors !== null) {
+      return Result.err(merge(annotateObject(blob), errors));
+    } else {
+      return Result.ok(new Map(tuples));
+    }
+  });
+}
+/**
+ * Like mapping(), but returns an object rather than a Map instance.
+ */
+
+export function dict(decoder) {
+  return map(mapping(decoder), function (m) {
+    return Object.fromEntries(m);
+  });
+}

package/es/stdlib/number.js

@@ -0,0 +1,25 @@
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
+
+var anyNumber = function anyNumber(blob) {
+  return typeof blob === 'number' && !Number.isNaN(blob) ? Result.ok(blob) : Result.err(annotate(blob, 'Must be number'));
+};
+
+var isInteger = function isInteger(n) {
+  return Number.isInteger(n);
+};
+
+var isFinite = function isFinite(n) {
+  return Number.isFinite(n);
+};
+
+export var number = compose(anyNumber, predicate(isFinite, 'Number must be finite'));
+export var positiveNumber = compose(number, predicate(function (n) {
+  return n >= 0;
+}, 'Number must be positive')); // Integers
+
+export var integer = compose(number, predicate(isInteger, 'Number must be an integer'));
+export var positiveInteger = compose(integer, predicate(function (n) {
+  return n >= 0;
+}, 'Number must be positive'));