decoders 1.25.4 → 2.0.0-beta1

package/{tuple.js.flow → cjs/stdlib/tuple.js.flow}

@@ -1,16 +1,15 @@
 // @flow strict
 
-import { annotate } from 'debrief';
-import { Err, Ok } from 'lemons/Result';
-
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
+import { err, errValue, isErr, ok, unwrap, value } from '../result';
 import { poja } from './array';
-import type { Decoder } from './types';
-import { compose, predicate } from './utils';
+import type { Decoder } from '../_types';
 
 const ntuple = (n: number) =>
     compose(
         poja,
-        predicate((arr) => arr.length === n, `Must be a ${n}-tuple`)
+        predicate((arr) => arr.length === n, `Must be a ${n}-tuple`),
     );
 
 /**
@@ -23,11 +22,11 @@ export function tuple1<T>(decoder1: Decoder<T>): Decoder<[T]> {
 
         const result1 = decoder1(blob1);
         try {
-            return Ok([result1.unwrap()]);
+            return ok([unwrap(result1)]);
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return Err(annotate(result1.errValue()));
+            return err(annotate(errValue(result1)));
         }
     });
 }
@@ -38,7 +37,7 @@ export function tuple1<T>(decoder1: Decoder<T>): Decoder<[T]> {
  */
 export function tuple2<T1, T2>(
     decoder1: Decoder<T1>,
-    decoder2: Decoder<T2>
+    decoder2: Decoder<T2>,
 ): Decoder<[T1, T2]> {
     return compose(ntuple(2), (blobs: $ReadOnlyArray<mixed>) => {
         const [blob1, blob2] = blobs;
@@ -46,15 +45,15 @@ export function tuple2<T1, T2>(
         const result1 = decoder1(blob1);
         const result2 = decoder2(blob2);
         try {
-            return Ok([result1.unwrap(), result2.unwrap()]);
+            return ok([unwrap(result1), unwrap(result2)]);
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return Err(
+            return err(
                 annotate([
-                    result1.isErr() ? result1.errValue() : result1.value(),
-                    result2.isErr() ? result2.errValue() : result2.value(),
-                ])
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                ]),
             );
         }
     });
@@ -67,7 +66,7 @@ export function tuple2<T1, T2>(
 export function tuple3<T1, T2, T3>(
     decoder1: Decoder<T1>,
     decoder2: Decoder<T2>,
-    decoder3: Decoder<T3>
+    decoder3: Decoder<T3>,
 ): Decoder<[T1, T2, T3]> {
     return compose(ntuple(3), (blobs: $ReadOnlyArray<mixed>) => {
         const [blob1, blob2, blob3] = blobs;
@@ -76,16 +75,16 @@ export function tuple3<T1, T2, T3>(
         const result2 = decoder2(blob2);
         const result3 = decoder3(blob3);
         try {
-            return Ok([result1.unwrap(), result2.unwrap(), result3.unwrap()]);
+            return ok([unwrap(result1), unwrap(result2), unwrap(result3)]);
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return Err(
+            return err(
                 annotate([
-                    result1.isErr() ? result1.errValue() : result1.value(),
-                    result2.isErr() ? result2.errValue() : result2.value(),
-                    result3.isErr() ? result3.errValue() : result3.value(),
-                ])
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                    isErr(result3) ? errValue(result3) : value(result3),
+                ]),
             );
         }
     });
@@ -99,7 +98,7 @@ export function tuple4<T1, T2, T3, T4>(
     decoder1: Decoder<T1>,
     decoder2: Decoder<T2>,
     decoder3: Decoder<T3>,
-    decoder4: Decoder<T4>
+    decoder4: Decoder<T4>,
 ): Decoder<[T1, T2, T3, T4]> {
     return compose(ntuple(4), (blobs: $ReadOnlyArray<mixed>) => {
         const [blob1, blob2, blob3, blob4] = blobs;
@@ -109,22 +108,22 @@ export function tuple4<T1, T2, T3, T4>(
         const result3 = decoder3(blob3);
         const result4 = decoder4(blob4);
         try {
-            return Ok([
-                result1.unwrap(),
-                result2.unwrap(),
-                result3.unwrap(),
-                result4.unwrap(),
+            return ok([
+                unwrap(result1),
+                unwrap(result2),
+                unwrap(result3),
+                unwrap(result4),
             ]);
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return Err(
+            return err(
                 annotate([
-                    result1.isErr() ? result1.errValue() : result1.value(),
-                    result2.isErr() ? result2.errValue() : result2.value(),
-                    result3.isErr() ? result3.errValue() : result3.value(),
-                    result4.isErr() ? result4.errValue() : result4.value(),
-                ])
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                    isErr(result3) ? errValue(result3) : value(result3),
+                    isErr(result4) ? errValue(result4) : value(result4),
+                ]),
             );
         }
     });
@@ -139,7 +138,7 @@ export function tuple5<T1, T2, T3, T4, T5>(
     decoder2: Decoder<T2>,
     decoder3: Decoder<T3>,
     decoder4: Decoder<T4>,
-    decoder5: Decoder<T5>
+    decoder5: Decoder<T5>,
 ): Decoder<[T1, T2, T3, T4, T5]> {
     return compose(ntuple(5), (blobs: $ReadOnlyArray<mixed>) => {
         const [blob1, blob2, blob3, blob4, blob5] = blobs;
@@ -150,24 +149,24 @@ export function tuple5<T1, T2, T3, T4, T5>(
         const result4 = decoder4(blob4);
         const result5 = decoder5(blob5);
         try {
-            return Ok([
-                result1.unwrap(),
-                result2.unwrap(),
-                result3.unwrap(),
-                result4.unwrap(),
-                result5.unwrap(),
+            return ok([
+                unwrap(result1),
+                unwrap(result2),
+                unwrap(result3),
+                unwrap(result4),
+                unwrap(result5),
             ]);
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return Err(
+            return err(
                 annotate([
-                    result1.isErr() ? result1.errValue() : result1.value(),
-                    result2.isErr() ? result2.errValue() : result2.value(),
-                    result3.isErr() ? result3.errValue() : result3.value(),
-                    result4.isErr() ? result4.errValue() : result4.value(),
-                    result5.isErr() ? result5.errValue() : result5.value(),
-                ])
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                    isErr(result3) ? errValue(result3) : value(result3),
+                    isErr(result4) ? errValue(result4) : value(result4),
+                    isErr(result5) ? errValue(result5) : value(result5),
+                ]),
             );
         }
     });
@@ -183,7 +182,7 @@ export function tuple6<T1, T2, T3, T4, T5, T6>(
     decoder3: Decoder<T3>,
     decoder4: Decoder<T4>,
     decoder5: Decoder<T5>,
-    decoder6: Decoder<T6>
+    decoder6: Decoder<T6>,
 ): Decoder<[T1, T2, T3, T4, T5, T6]> {
     return compose(ntuple(6), (blobs: $ReadOnlyArray<mixed>) => {
         const [blob1, blob2, blob3, blob4, blob5, blob6] = blobs;
@@ -195,26 +194,26 @@ export function tuple6<T1, T2, T3, T4, T5, T6>(
         const result5 = decoder5(blob5);
         const result6 = decoder6(blob6);
         try {
-            return Ok([
-                result1.unwrap(),
-                result2.unwrap(),
-                result3.unwrap(),
-                result4.unwrap(),
-                result5.unwrap(),
-                result6.unwrap(),
+            return ok([
+                unwrap(result1),
+                unwrap(result2),
+                unwrap(result3),
+                unwrap(result4),
+                unwrap(result5),
+                unwrap(result6),
             ]);
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return Err(
+            return err(
                 annotate([
-                    result1.isErr() ? result1.errValue() : result1.value(),
-                    result2.isErr() ? result2.errValue() : result2.value(),
-                    result3.isErr() ? result3.errValue() : result3.value(),
-                    result4.isErr() ? result4.errValue() : result4.value(),
-                    result5.isErr() ? result5.errValue() : result5.value(),
-                    result6.isErr() ? result6.errValue() : result6.value(),
-                ])
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                    isErr(result3) ? errValue(result3) : value(result3),
+                    isErr(result4) ? errValue(result4) : value(result4),
+                    isErr(result5) ? errValue(result5) : value(result5),
+                    isErr(result6) ? errValue(result6) : value(result6),
+                ]),
             );
         }
     });

package/es/_guard.js

@@ -0,0 +1,15 @@
+import * as Result from './result';
+import { formatInline } from './format';
+export function guard(decoder, formatter) {
+  if (formatter === void 0) {
+    formatter = formatInline;
+  }
+
+  return function (blob) {
+    return Result.unwrap(Result.mapError(decoder(blob), function (annotation) {
+      var err = new Error('\n' + formatter(annotation));
+      err.name = 'Decoding error';
+      return err;
+    }));
+  };
+}

package/es/_utils.js

@@ -0,0 +1,93 @@
+// $FlowFixMe[unclear-type] - deliberate casting
+// Two spaces of indentation
+export var INDENT = '  ';
+/**
+ * `x instanceof Date` checks are unreliable across stack frames (that information
+ * might get lost by the JS runtime), so we'll have to reside to more runtime
+ * inspection checks.
+ *
+ * Taken from https://stackoverflow.com/a/44198641
+ */
+
+export function isDate(value) {
+  return !!value && // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value);
+}
+/**
+ * Is value is a valid Date instance, then return that.  If not, then return
+ * null.
+ */
+
+export function asDate(value) {
+  return isDate(value) ? value : null;
+}
+export function isMultiline(s) {
+  return s.indexOf('\n') >= 0;
+}
+export function indent(s, prefix) {
+  if (prefix === void 0) {
+    prefix = INDENT;
+  }
+
+  if (isMultiline(s)) {
+    return s.split('\n').map(function (line) {
+      return prefix + line;
+    }).join('\n');
+  } else {
+    return prefix + s;
+  }
+}
+/**
+ * Walks the annotation tree and emits the annotation's key path within the
+ * object tree, and the message as a series of messages (array of strings).
+ */
+
+export function summarize(ann, keypath) {
+  if (keypath === void 0) {
+    keypath = [];
+  }
+
+  var result = [];
+
+  if (ann.type === 'array') {
+    var items = ann.items;
+    var index = 0;
+    items.forEach(function (ann) {
+      summarize(ann, [].concat(keypath, [index++])).forEach(function (item) {
+        return (// Collect to results
+          result.push(item)
+        );
+      });
+    });
+  } else if (ann.type === 'object') {
+    var fields = ann.fields;
+    Object.keys(fields).forEach(function (key) {
+      var value = fields[key];
+      summarize(value, [].concat(keypath, [key])).forEach(function (item) {
+        return (// Collect to results
+          result.push(item)
+        );
+      });
+    });
+  }
+
+  var text = ann.text;
+
+  if (!text) {
+    return result;
+  }
+
+  var prefix;
+
+  if (keypath.length === 0) {
+    prefix = '';
+  } else if (keypath.length === 1) {
+    prefix = typeof keypath[0] === 'number' ? "Value at index " + keypath[0] + ": " : "Value at key " + JSON.stringify(keypath[0]) + ": ";
+  } else {
+    prefix = "Value at keypath " + keypath.map(function (x) {
+      return x.toString();
+    }).join('.') + ": ";
+  }
+
+  return [].concat(result, [prefix + text]);
+}

package/es/annotate.js

@@ -0,0 +1,144 @@
+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); }
+
+var _register = new WeakSet();
+
+function brand(ann) {
+  _register.add(ann);
+
+  return ann;
+}
+
+export function object(fields, text) {
+  return brand({
+    type: 'object',
+    fields: fields,
+    text: text
+  });
+}
+export function array(items, text) {
+  return brand({
+    type: 'array',
+    items: items,
+    text: text
+  });
+}
+export function func(text) {
+  return brand({
+    type: 'function',
+    text: text
+  });
+}
+export function unknown(value, text) {
+  return brand({
+    type: 'unknown',
+    value: value,
+    text: text
+  });
+}
+export function scalar(value, text) {
+  return brand({
+    type: 'scalar',
+    value: value,
+    text: text
+  });
+}
+export function circularRef(text) {
+  return brand({
+    type: 'circular-ref',
+    text: text
+  });
+}
+/**
+ * Given an existing Annotation, set the annotation's text to a new value.
+ */
+
+export function updateText(annotation, text) {
+  if (text !== undefined) {
+    return brand(_extends({}, annotation, {
+      text: text
+    }));
+  } else {
+    return annotation;
+  }
+}
+/**
+ * Given an existing ObjectAnnotation, merges new Annotations in there.
+ */
+
+export function merge(objAnnotation, fields) {
+  var newFields = _extends({}, objAnnotation.fields, fields);
+
+  return object(newFields, objAnnotation.text);
+}
+export function asAnnotation(thing) {
+  return typeof thing === 'object' && thing !== null && _register.has(thing) ? thing : undefined;
+}
+
+function annotateArray(value, text, seen) {
+  seen.add(value);
+  var items = value.map(function (v) {
+    return annotate(v, undefined, seen);
+  });
+  return array(items, text);
+}
+
+function annotateObject(obj, text, seen) {
+  seen.add(obj);
+  var fields = {};
+  Object.keys(obj).forEach(function (key) {
+    var value = obj[key];
+    fields[key] = annotate(value, undefined, seen);
+  });
+  return object(fields, text);
+}
+
+function annotate(value, text, seen) {
+  if (value === null || value === undefined || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'symbol' || typeof value.getMonth === 'function') {
+    return scalar(value, text);
+  }
+
+  var ann = asAnnotation(value);
+
+  if (ann) {
+    return updateText(ann, text);
+  }
+
+  if (Array.isArray(value)) {
+    // "Circular references" can only exist in objects or arrays
+    if (seen.has(value)) {
+      return circularRef(text);
+    } else {
+      return annotateArray(value, text, seen);
+    }
+  }
+
+  if (typeof value === 'object') {
+    // "Circular references" can only exist in objects or arrays
+    if (seen.has(value)) {
+      return circularRef(text);
+    } else {
+      return annotateObject(value, text, seen);
+    }
+  }
+
+  if (typeof value === 'function') {
+    return func(text);
+  }
+
+  return unknown(value, text);
+}
+
+function public_annotate(value, text) {
+  return annotate(value, text, new WeakSet());
+}
+
+function public_annotateObject(obj, text) {
+  return annotateObject(obj, text, new WeakSet());
+}
+
+export { // This construct just ensures the "seen" weakmap (used for circular
+// reference detection) isn't made part of the public API.
+public_annotate as annotate, public_annotateObject as annotateObject, //
+// NOTE: Don't acces theses private APIs directly. They are only exported here
+// to better enable unit testing.
+annotate as __private_annotate };

package/es/format/index.js

@@ -0,0 +1,2 @@
+export { formatInline } from './inline';
+export { formatShort } from './short';

package/es/format/inline.js

@@ -0,0 +1,137 @@
+import { asDate, indent, INDENT, isMultiline } from '../_utils';
+
+function serializeString(s, width) {
+  if (width === void 0) {
+    width = 80;
+  }
+
+  // Full string
+  // Abbreviated to $maxlen i.e. "Vincent Driess..." [truncated]
+  var ser = JSON.stringify(s);
+
+  if (ser.length <= width) {
+    return ser;
+  } // Cut off a bit
+
+
+  var truncated = s.substring(0, width - 15) + '...';
+  ser = JSON.stringify(truncated) + ' [truncated]';
+  return ser;
+}
+
+function serializeArray(annotation, prefix) {
+  var items = annotation.items;
+
+  if (items.length === 0) {
+    return '[]';
+  }
+
+  var result = [];
+  items.forEach(function (item) {
+    var _serializeAnnotation = serializeAnnotation(item, prefix + INDENT),
+        ser = _serializeAnnotation[0],
+        ann = _serializeAnnotation[1];
+
+    result.push(prefix + INDENT + ser + ',');
+
+    if (ann !== undefined) {
+      result.push(indent(ann, prefix + INDENT));
+    }
+  });
+  return ['['].concat(result, [prefix + ']']).join('\n');
+}
+
+function serializeObject(annotation, prefix) {
+  var fields = annotation.fields;
+  var fieldNames = Object.keys(fields);
+
+  if (fieldNames.length === 0) {
+    return '{}';
+  }
+
+  var result = [];
+  fieldNames.forEach(function (key) {
+    var valueAnnotation = fields[key];
+    var kser = serializeValue(key);
+    var valPrefix = prefix + INDENT + ' '.repeat(kser.length + 2);
+
+    var _serializeAnnotation2 = serializeAnnotation(valueAnnotation, prefix + INDENT),
+        vser = _serializeAnnotation2[0],
+        vann = _serializeAnnotation2[1];
+
+    result.push(prefix + INDENT + kser + ': ' + vser + ',');
+
+    if (vann !== undefined) {
+      result.push(indent(vann, valPrefix));
+    }
+  });
+  return ['{'].concat(result, [prefix + '}']).join('\n');
+}
+
+export function serializeValue(value) {
+  // istanbul ignore else
+  if (typeof value === 'string') {
+    return serializeString(value);
+  } else if (typeof value === 'number' || typeof value === 'boolean') {
+    return value.toString();
+  } else if (value === null) {
+    return 'null';
+  } else if (value === undefined) {
+    return 'undefined';
+  } else {
+    var valueAsDate = asDate(value);
+
+    if (valueAsDate !== null) {
+      return "new Date(" + JSON.stringify(valueAsDate.toISOString()) + ")";
+    } else if (value instanceof Date) {
+      // NOTE: Using `instanceof Date` is unreliable way of checking dates.
+      // If this case occurs (and it didn't pass the prior isDate())
+      // check, then this must be the case where it's an invalid date.
+      return '(Invalid Date)';
+    } else {
+      return '(unserializable)';
+    }
+  }
+}
+export function serializeAnnotation(ann, prefix) {
+  if (prefix === void 0) {
+    prefix = '';
+  }
+
+  // The serialized data (the input object echoed back)
+  var serialized;
+
+  if (ann.type === 'array') {
+    serialized = serializeArray(ann, prefix);
+  } else if (ann.type === 'object') {
+    serialized = serializeObject(ann, prefix);
+  } else if (ann.type === 'function') {
+    serialized = '<function>';
+  } else if (ann.type === 'circular-ref') {
+    serialized = '<circular ref>';
+  } else if (ann.type === 'unknown') {
+    serialized = '???';
+  } else {
+    serialized = serializeValue(ann.value);
+  }
+
+  var text = ann.text;
+
+  if (text !== undefined) {
+    var sep = '^'.repeat(isMultiline(serialized) ? 1 : serialized.length);
+    return [serialized, [sep, text].join(isMultiline(text) ? '\n' : ' ')];
+  } else {
+    return [serialized, undefined];
+  }
+}
+export function formatInline(ann) {
+  var _serializeAnnotation3 = serializeAnnotation(ann),
+      serialized = _serializeAnnotation3[0],
+      annotation = _serializeAnnotation3[1];
+
+  if (annotation !== undefined) {
+    return serialized + '\n' + annotation;
+  } else {
+    return serialized;
+  }
+}

package/es/format/short.js

@@ -0,0 +1,4 @@
+import { summarize as _summarize } from '../_utils';
+export function formatShort(ann) {
+  return _summarize(ann, []).join('\n');
+}

package/es/index.js

@@ -0,0 +1,37 @@
+/**
+ * Elm-like JSON decoders, for use with Flow.
+ * See http://elmplayground.com/decoding-json-in-elm-1 for an introduction.
+ *
+ * Why? All JSON responses coming from our API endpoints are just that: free-form
+ * JSON data.  To Flow, the only type classification possilbe is "any" -- effectively
+ * turning off all type checks for anything related to JSON.  To the receiving end
+ * (our frontend), the structure of that data is completely opaque to any type
+ * checkers since JSON values can be anything: an object, an array, null, a string,
+ * a bool, etc.  Our type system is not a runtime type system, so we need a way of
+ * "converting" an any-type JSON value into a type that we want to work with in our
+ * frontend code base.
+ *
+ * Elm's solution to this problem is to define composable decoders: functions that
+ * take anything and either fail with an error, or guarantee to return the expected
+ * type.  In our case, it's fine to fail with a runtime error.
+ *
+ */
+export { guard } from './_guard';
+export { compose, map, predicate } from './stdlib/composition';
+export { array, nonEmptyArray, poja } from './stdlib/array';
+export { boolean, numericBoolean, truthy } from './stdlib/boolean';
+export { constant, hardcoded, mixed, null_, undefined_, unknown } from './stdlib/constants';
+export { date, iso8601 } from './stdlib/date';
+export { describe } from './stdlib/describe';
+export { dispatch } from './stdlib/dispatch';
+export { either, either3, either4, either5, either6, either7, either8, either9, oneOf } from './stdlib/either';
+export { fail } from './stdlib/fail';
+export { instanceOf } from './stdlib/instanceOf';
+export { json, jsonObject, jsonArray } from './stdlib/json';
+export { lazy } from './stdlib/lazy';
+export { mapping, dict } from './stdlib/mapping';
+export { integer, number, positiveInteger, positiveNumber } from './stdlib/number';
+export { exact, inexact, object, pojo } from './stdlib/object';
+export { maybe, nullable, optional } from './stdlib/optional';
+export { email, nonEmptyString, regex, string, url } from './stdlib/string';
+export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './stdlib/tuple';