decoders 1.26.0-beta2 → 2.0.0-beta3

package/_esm/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 './core/composition';
+export { array, nonEmptyArray, poja } from './core/array';
+export { boolean, numericBoolean, truthy } from './core/boolean';
+export { constant, hardcoded, mixed, null_, undefined_, unknown } from './core/constants';
+export { date, iso8601 } from './core/date';
+export { describe } from './core/describe';
+export { dispatch } from './core/dispatch';
+export { either, either3, either4, either5, either6, either7, either8, either9, oneOf } from './core/either';
+export { fail } from './core/fail';
+export { instanceOf } from './core/instanceOf';
+export { json, jsonObject, jsonArray } from './core/json';
+export { lazy } from './core/lazy';
+export { mapping, dict } from './core/mapping';
+export { integer, number, positiveInteger, positiveNumber } from './core/number';
+export { exact, inexact, object, pojo } from './core/object';
+export { maybe, nullable, optional } from './core/optional';
+export { email, nonEmptyString, regex, string, url } from './core/string';
+export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './core/tuple';

package/{cjs → _esm}/index.js.flow

@@ -18,17 +18,28 @@
  * type.  In our case, it's fine to fail with a runtime error.
  *
  */
-import type { $DecoderType, $GuardType, Decoder, Guard } from './types';
+export type {
+    Decoder,
+    DecodeResult,
+    DecoderType,
+    Guard,
+    GuardType,
+    Predicate,
+    Scalar,
+} from './_types';
 
-export { guard } from './guard';
-export { compose, map, predicate } from './utils';
+export type { JSONValue, JSONObject, JSONArray } from './core/json';
 
-export { array, nonEmptyArray, poja } from './array';
-export { boolean, numericBoolean, truthy } from './boolean';
-export { constant, hardcoded, mixed, null_, undefined_, unknown } from './constants';
-export { date, iso8601 } from './date';
-export { describe } from './describe';
-export { dispatch } from './dispatch';
+export { guard } from './_guard';
+
+export { compose, map, predicate } from './core/composition';
+
+export { array, nonEmptyArray, poja } from './core/array';
+export { boolean, numericBoolean, truthy } from './core/boolean';
+export { constant, hardcoded, mixed, null_, undefined_, unknown } from './core/constants';
+export { date, iso8601 } from './core/date';
+export { describe } from './core/describe';
+export { dispatch } from './core/dispatch';
 export {
     either,
     either3,
@@ -39,18 +50,14 @@ export {
     either8,
     either9,
     oneOf,
-} from './either';
-export { fail } from './fail';
-export { instanceOf } from './instanceOf';
-export { json, jsonObject, jsonArray } from './json';
-export { lazy } from './lazy';
-export { mapping, dict } from './mapping';
-export { integer, number, positiveInteger, positiveNumber } from './number';
-export { exact, inexact, object, pojo } from './object';
-export { maybe, nullable, optional } from './optional';
-export { email, nonEmptyString, regex, string, url } from './string';
-export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './tuple';
-
-export type { Decoder, Guard };
-export type { $DecoderType, $GuardType };
-export type { JSONValue, JSONObject, JSONArray } from './json';
+} from './core/either';
+export { fail } from './core/fail';
+export { instanceOf } from './core/instanceOf';
+export { json, jsonObject, jsonArray } from './core/json';
+export { lazy } from './core/lazy';
+export { mapping, dict } from './core/mapping';
+export { integer, number, positiveInteger, positiveNumber } from './core/number';
+export { exact, inexact, object, pojo } from './core/object';
+export { maybe, nullable, optional } from './core/optional';
+export { email, nonEmptyString, regex, string, url } from './core/string';
+export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './core/tuple';

package/_esm/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/_esm/result.js.flow

@@ -0,0 +1,166 @@
+// @flow strict
+
+/**
+ * Result <value> <error>
+ *     = Ok <value>
+ *     | Err <error>
+ */
+
+type Ok<+T> = {| +type: 'ok', +value: T |};
+type Err<+E> = {| +type: 'err', +error: E |};
+
+export type Result<+T, +E> = Ok<T> | Err<E>;
+
+/**
+ * Create a new Result instance representing a successful computation.
+ */
+export function ok<T>(value: T): Ok<T> {
+    return { type: 'ok', value };
+}
+
+/**
+ * Create a new Result instance representing a failed computation.
+ */
+export function err<E>(error: E): Err<E> {
+    return { type: 'err', error };
+}
+
+export function toString(result: Result<mixed, mixed>): string {
+    return result.type === 'ok'
+        ? `Ok(${String(result.value)})`
+        : `Err(${String(result.error)})`;
+}
+
+export function isOk(result: Result<mixed, mixed>): boolean {
+    return result.type === 'ok';
+}
+
+export function isErr(result: Result<mixed, mixed>): boolean {
+    return result.type === 'err';
+}
+
+export function withDefault<T>(result: Result<T, mixed>, defaultValue: T): T {
+    return result.type === 'ok' ? result.value : defaultValue;
+}
+
+export function value<T>(result: Result<T, mixed>): void | T {
+    return result.type === 'ok' ? result.value : undefined;
+}
+
+export function errValue<E>(result: Result<mixed, E>): void | E {
+    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<T>(result: Result<T, mixed>): T {
+    if (result.type === 'ok') {
+        return result.value;
+    } else {
+        throw result.error;
+    }
+}
+
+export function expect<T>(result: Result<T, mixed>, message: string | Error): T {
+    if (result.type === 'ok') {
+        return result.value;
+    } else {
+        throw message instanceof Error ? message : new Error(message);
+    }
+}
+
+export function dispatch<T, E, O>(
+    result: Result<T, E>,
+    okCallback: (value: T) => O,
+    errCallback: (error: E) => O,
+): O {
+    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<T, E, T2>(
+    result1: Result<T, E>,
+    lazyResult2: (value: T) => Result<T2, E>,
+): Result<T2, E> {
+    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<T, E, E2>(
+    result1: Result<T, E>,
+    lazyResult2: (errValue: E) => Result<T, E2>,
+): Result<T, E2> {
+    return result1.type === 'ok' ? result1 : lazyResult2(result1.error);
+}
+
+/**
+ * Transform an Ok result. Will not touch Err results.
+ */
+export function map<T, E, T2>(
+    result: Result<T, E>,
+    mapper: (value: T) => T2,
+): Result<T2, E> {
+    return result.type === 'ok' ? ok(mapper(result.value)) : result;
+}
+
+/**
+ * Transform an Err value. Will not touch Ok results.
+ */
+export function mapError<T, E, E2>(
+    result: Result<T, E>,
+    mapper: (error: E) => E2,
+): Result<T, E2> {
+    return result.type === 'ok' ? result : err(mapper(result.error));
+}

package/_guard.js

@@ -0,0 +1,26 @@
+"use strict";
+
+exports.__esModule = true;
+exports.guard = guard;
+
+var Result = _interopRequireWildcard(require("./result"));
+
+var _format = require("./format");
+
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { "default": obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj["default"] = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+
+function guard(decoder, formatter) {
+  if (formatter === void 0) {
+    formatter = _format.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/_guard.js.flow

@@ -0,0 +1,20 @@
+// @flow strict
+
+import * as Result from './result';
+import { formatInline } from './format';
+import type { Annotation } from './annotate';
+import type { Decoder, Guard } from './_types';
+
+export function guard<T>(
+    decoder: Decoder<T>,
+    formatter: (Annotation) => string = formatInline,
+): Guard<T> {
+    return (blob: mixed) =>
+        Result.unwrap(
+            Result.mapError(decoder(blob), (annotation) => {
+                const err = new Error('\n' + formatter(annotation));
+                err.name = 'Decoding error';
+                return err;
+            }),
+        );
+}

package/_types.js

@@ -0,0 +1 @@
+"use strict";

package/_types.js.flow

@@ -0,0 +1,20 @@
+// @flow strict
+
+import type { Annotation } from './annotate';
+import type { Result } from './result';
+
+export type Scalar = string | number | boolean | symbol | void | null;
+
+export type Predicate<T> = (T) => boolean;
+export type DecodeResult<T> = Result<T, Annotation>;
+
+export type Decoder<T, F = mixed> = (F) => DecodeResult<T>;
+export type Guard<T> = (mixed) => T;
+
+/**
+ * A "type function" which informs Flow about how a type will be modified at runtime.
+ * Read this as "given a Guard of type T, I can produce a value of type T".  This
+ * definition helps construct $ObjMap types.
+ */
+export type DecoderType = <T>(Decoder<T>) => T;
+export type GuardType = <T>(Guard<T>) => T;

package/_utils.js

@@ -0,0 +1,108 @@
+"use strict";
+
+exports.__esModule = true;
+exports.INDENT = void 0;
+exports.asDate = asDate;
+exports.indent = indent;
+exports.isDate = isDate;
+exports.isMultiline = isMultiline;
+exports.summarize = summarize;
+// $FlowFixMe[unclear-type] - deliberate casting
+// Two spaces of indentation
+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
+ */
+
+exports.INDENT = INDENT;
+
+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.
+ */
+
+
+function asDate(value) {
+  return isDate(value) ? value : null;
+}
+
+function isMultiline(s) {
+  return s.indexOf('\n') >= 0;
+}
+
+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).
+ */
+
+
+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/_utils.js.flow

@@ -0,0 +1,97 @@
+// @flow strict
+
+import type { Annotation } from './annotate';
+
+// $FlowFixMe[unclear-type] - deliberate casting
+type cast = any;
+
+// Two spaces of indentation
+export const 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: mixed): boolean {
+    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: mixed): Date | null {
+    return isDate(value) ? ((value: cast): Date) : null;
+}
+
+export function isMultiline(s: string): boolean {
+    return s.indexOf('\n') >= 0;
+}
+
+export function indent(s: string, prefix: string = INDENT): string {
+    if (isMultiline(s)) {
+        return s
+            .split('\n')
+            .map((line) => 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: Annotation,
+    keypath: $ReadOnlyArray<number | string> = [],
+): Array<string> {
+    const result: Array<string> = [];
+
+    if (ann.type === 'array') {
+        const items = ann.items;
+        let index = 0;
+        items.forEach((ann) => {
+            summarize(ann, [...keypath, index++]).forEach((item) =>
+                // Collect to results
+                result.push(item),
+            );
+        });
+    } else if (ann.type === 'object') {
+        const fields = ann.fields;
+        Object.keys(fields).forEach((key) => {
+            const value = fields[key];
+            summarize(value, [...keypath, key]).forEach((item) =>
+                // Collect to results
+                result.push(item),
+            );
+        });
+    }
+
+    const text = ann.text;
+    if (!text) {
+        return result;
+    }
+
+    let prefix: string;
+    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((x) => x.toString()).join('.')}: `;
+    }
+    return [...result, prefix + text];
+}