decoders 2.0.0-beta6 → 2.0.0-beta7

package/_esm/core/either.js.flow

@@ -1,151 +0,0 @@
-// @flow strict
-
-import * as Result from '../result';
-import { annotate } from '../annotate';
-import { indent, summarize } from '../_utils';
-import type { Decoder, Scalar } from '../_types';
-
-/**
- * Indents and adds a dash in front of this (potentially multiline) string.
- */
-function itemize(s: string): string {
-    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: string): string {
-    const EITHER_PREFIX = 'Either:\n';
-    return errText.startsWith(EITHER_PREFIX)
-        ? errText.substr(EITHER_PREFIX.length)
-        : itemize(errText);
-}
-
-export function either<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2> {
-    return (blob: mixed) =>
-        Result.orElse(d1(blob), (err1) =>
-            Result.orElse(d2(blob), (err2) => {
-                const serr1 = summarize(err1).join('\n');
-                const serr2 = summarize(err2).join('\n');
-                const text = ['Either:', nest(serr1), nest(serr2)].join('\n');
-                return Result.err(annotate(blob, text));
-            }),
-        );
-}
-
-export function either3<T1, T2, T3>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-): Decoder<T1 | T2 | T3> {
-    return either(d1, either(d2, d3));
-}
-
-export function either4<T1, T2, T3, T4>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-): Decoder<T1 | T2 | T3 | T4> {
-    return either(d1, either3(d2, d3, d4));
-}
-
-export function either5<T1, T2, T3, T4, T5>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-): Decoder<T1 | T2 | T3 | T4 | T5> {
-    return either(d1, either4(d2, d3, d4, d5));
-}
-
-export function either6<T1, T2, T3, T4, T5, T6>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6> {
-    return either(d1, either5(d2, d3, d4, d5, d6));
-}
-
-export function either7<T1, T2, T3, T4, T5, T6, T7>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7> {
-    return either(d1, either6(d2, d3, d4, d5, d6, d7));
-}
-
-export function either8<T1, T2, T3, T4, T5, T6, T7, T8>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-    d8: Decoder<T8>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8> {
-    return either(d1, either7(d2, d3, d4, d5, d6, d7, d8));
-}
-
-export function either9<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-    d8: Decoder<T8>,
-    d9: Decoder<T9>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8 | T9> {
-    return either(d1, either8(d2, d3, d4, d5, d6, d7, d8, d9));
-}
-
-export function oneOf<T: Scalar>(constants: $ReadOnlyArray<T>): Decoder<T> {
-    return (blob: mixed) => {
-        const winner = constants.find((c) => c === blob);
-        if (winner !== undefined) {
-            return Result.ok(winner);
-        }
-        return Result.err(
-            annotate(
-                blob,
-                `Must be one of ${constants
-                    .map((value) => JSON.stringify(value))
-                    .join(', ')}`,
-            ),
-        );
-    };
-}

package/_esm/core/fail.js.flow

@@ -1,12 +0,0 @@
-// @flow strict
-
-import * as Result from '../result';
-import { annotate } from '../annotate';
-import type { Decoder } from '../_types';
-
-/**
- * Decoder that always fails with the given error message, no matter what the input.
- */
-export function fail(msg: string): Decoder<empty> {
-    return (blob: mixed) => Result.err(annotate(blob, msg));
-}

package/_esm/core/instanceOf.js

@@ -1,8 +0,0 @@
-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/_esm/core/instanceOf.js.flow

@@ -1,20 +0,0 @@
-// @flow strict
-
-import * as Result from '../result';
-import { annotate } from '../annotate';
-import type { Decoder } from '../_types';
-
-export function instanceOf<T>(klass: Class<T>): Decoder<T> {
-    return (blob: mixed) =>
-        blob instanceof klass
-            ? Result.ok(blob)
-            : Result.err(
-                  annotate(
-                      blob,
-                      `Must be ${
-                          // $FlowFixMe[incompatible-use] - klass.name is fine?
-                          klass.name
-                      } instance`,
-                  ),
-              );
-}

package/_esm/core/json.js

@@ -1,15 +0,0 @@
-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/_esm/core/json.js.flow

@@ -1,28 +0,0 @@
-// @flow strict
-
-import { array } from './array';
-import { 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';
-import type { Decoder } from '../_types';
-
-export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
-export type JSONObject = { [string]: JSONValue };
-export type JSONArray = Array<JSONValue>;
-
-export const jsonObject: Decoder<JSONObject> = lazy(() => dict(json));
-
-export const jsonArray: Decoder<JSONArray> = lazy(() => array(json));
-
-export const json: Decoder<JSONValue> = either6(
-    null_,
-    string,
-    number,
-    boolean,
-    jsonObject,
-    jsonArray,
-);

package/_esm/core/lazy.js.flow

@@ -1,15 +0,0 @@
-// @flow strict
-
-import type { Decoder } from '../_types';
-
-/**
- * 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<T>(decoderFn: () => Decoder<T>): Decoder<T> {
-    return (blob: mixed) => {
-        const decoder = decoderFn();
-        return decoder(blob);
-    };
-}

package/_esm/core/mapping.js.flow

@@ -1,54 +0,0 @@
-// @flow strict
-
-import * as Result from '../result';
-import { annotateObject } from '../annotate';
-import { compose, map } from './composition';
-import { merge } from '../annotate';
-import { pojo } from './object';
-import type { Annotation } from '../annotate';
-import type { Decoder } from '../_types';
-
-/**
- * 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<T>(decoder: Decoder<T>): Decoder<Map<string, T>> {
-    return compose(pojo, (blob: { +[key: string]: mixed }) => {
-        let tuples: Array<[string, T]> = [];
-        let errors: { [key: string]: Annotation } | null = null;
-
-        Object.keys(blob).forEach((key: string) => {
-            const value = blob[key];
-            const 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<T>(decoder: Decoder<T>): Decoder<{ [string]: T }> {
-    return map(mapping(decoder), (m) => Object.fromEntries(m));
-}

package/_esm/core/number.js.flow

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

package/_esm/core/object.js.flow

@@ -1,203 +0,0 @@
-// @flow strict
-
-import * as Result from '../result';
-import { annotate, annotateObject, merge, updateText } from '../annotate';
-import { compose, map } from './composition';
-import type { Annotation } from '../annotate';
-import type { Decoder, DecoderType } from '../_types';
-
-// $FlowFixMe[unclear-type] (not really an issue) - deliberate use of `any` - not sure how we should get rid of this
-type AnyDecoder = any;
-
-// $FlowFixMe[unclear-type] (not really an issue) - deliberately casting
-type cast = any;
-
-function isPojo(o: mixed): boolean %checks {
-    return (
-        o !== null &&
-        o !== undefined &&
-        typeof o === 'object' &&
-        // This still seems to be the only reliable way to determine whether
-        // something is a pojo... ¯\_(ツ)_/¯
-        // $FlowFixMe[method-unbinding]
-        Object.prototype.toString.call(o) === '[object Object]'
-    );
-}
-
-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;
-}
-
-export const pojo: Decoder<{| [string]: mixed |}> = (blob: mixed) => {
-    return isPojo(blob)
-        ? Result.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 },
-          )
-        : Result.err(annotate(blob, 'Must be an object'));
-};
-
-/**
- * Given a mapping of fields-to-decoders, builds a decoder for an object type.
- *
- * For example, given decoders for a number and a string, we can construct an
- * "object description" like so:
- *
- *   { id: number, name: string }
- *
- * Which is of type:
- *
- *   { id: Decoder<number>, name: Decoder<string> }
- *
- * Passing this to object() will produce the following return type:
- *
- *   Decoder<{ id: number, name: string }>
- *
- * Put simply: it'll "peel off" all of the nested Decoders, puts them together
- * in an object, and wraps it in a Decoder<...>.
- */
-export function object<O: { +[field: string]: AnyDecoder, ... }>(
-    mapping: O,
-): Decoder<$ObjMap<O, DecoderType>> {
-    const known = new Set(Object.keys(mapping));
-    return compose(pojo, (blob: { +[string]: mixed }) => {
-        const actual = new Set(Object.keys(blob));
-
-        // At this point, "missing" 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 missing = subtract(known, actual);
-
-        let record = {};
-        let errors: { [key: string]: Annotation } | null = null;
-
-        Object.keys(mapping).forEach((key) => {
-            const decoder = mapping[key];
-            const rawValue = blob[key];
-            const result = decoder(rawValue);
-
-            if (result.type === 'ok') {
-                const value = result.value;
-                if (value !== undefined) {
-                    record[key] = value;
-                }
-
-                // If this succeeded, remove the key from the missing keys
-                // tracker
-                missing.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).
-                    missing.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 || missing.size > 0) {
-            let objAnn = annotateObject(blob);
-
-            if (errors) {
-                objAnn = merge(objAnn, errors);
-            }
-
-            if (missing.size > 0) {
-                const errMsg = Array.from(missing)
-                    .map((key) => `"${key}"`)
-                    .join(', ');
-                const pluralized = missing.size > 1 ? 'keys' : 'key';
-                objAnn = updateText(objAnn, `Missing ${pluralized}: ${errMsg}`);
-            }
-
-            return Result.err(objAnn);
-        }
-
-        return Result.ok(record);
-    });
-}
-
-export function exact<O: { +[field: string]: AnyDecoder, ... }>(
-    mapping: O,
-): Decoder<$ObjMap<$Exact<O>, DecoderType>> {
-    // Check the inputted object for any superfluous keys
-    const allowed = new Set(Object.keys(mapping));
-    const checked = compose(pojo, (blob: {| [string]: mixed |}) => {
-        const actual = new Set(Object.keys(blob));
-        const superfluous = subtract(actual, allowed);
-        if (superfluous.size > 0) {
-            return Result.err(
-                annotate(blob, `Superfluous keys: ${Array.from(superfluous).join(', ')}`),
-            );
-        }
-        return Result.ok(blob);
-    });
-
-    // 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.
-    const decoder = ((object(mapping): cast): Decoder<$ObjMap<$Exact<O>, DecoderType>>);
-    return compose(checked, decoder);
-}
-
-export function inexact<O: { +[field: string]: AnyDecoder }>(
-    mapping: O,
-): Decoder<$ObjMap<O, DecoderType> & { +[string]: mixed }> {
-    return compose(pojo, (blob: {| [string]: mixed |}) => {
-        const allkeys = new Set(Object.keys(blob));
-        const decoder = map(object(mapping), (safepart: $ObjMap<O, DecoderType>) => {
-            const safekeys = new Set(Object.keys(mapping));
-
-            // 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] = blob[k];
-                }
-            });
-            return rv;
-        });
-        return decoder(blob);
-    });
-}

package/_esm/core/optional.js.flow

@@ -1,41 +0,0 @@
-// @flow strict
-
-import * as Result from '../result';
-import { annotate } from '../annotate';
-import { either } from './either';
-import { null_, undefined_ } from './constants';
-import type { Decoder } from '../_types';
-
-/**
- * Builds a Decoder that returns Ok for either `undefined` or `T` values,
- * given a Decoder for `T`.  Err otherwise.
- */
-export function optional<T>(decoder: Decoder<T>): Decoder<void | T> {
-    return either(undefined_, decoder);
-}
-
-/**
- * Builds a Decoder that returns Ok for either `null` or `T` values,
- * given a Decoder for `T`.  Err otherwise.
- */
-export function nullable<T>(decoder: Decoder<T>): Decoder<null | T> {
-    return either(null_, decoder);
-}
-
-/**
- * Decoder that only returns Ok for `null` or `undefined` inputs.
- * This is effectively equivalent to either(null_, undefined_), but combines
- * their error message output into a single line for convenience.
- */
-const undefined_or_null: Decoder<null | void> = (blob: mixed) =>
-    blob === undefined || blob === null
-        ? Result.ok(blob)
-        : // Combine error message into a single line
-          Result.err(annotate(blob, 'Must be undefined or null'));
-
-/**
- * Decoder that only returns Ok for `null` or `undefined` inputs.
- */
-export function maybe<T>(decoder: Decoder<T>): Decoder<?T> {
-    return either(undefined_or_null, decoder);
-}

package/_esm/core/string.js.flow

@@ -1,82 +0,0 @@
-// @flow strict
-
-import * as Result from '../result';
-import { annotate } from '../annotate';
-import { compose, predicate } from './composition';
-import type { Decoder } from '../_types';
-
-/** Match groups in this regex:
- * \1 - the scheme
- * \2 - the username/password (optional)
- * \3 - the host
- * \4 - the port (optional)
- * \5 - the path (optional)
- */
-const url_re =
-    /^([A-Za-z]{3,9}(?:[+][A-Za-z]{3,9})?):\/\/(?:([-;:&=+$,\w]+)@)?(?:([A-Za-z0-9.-]+)(?::([0-9]{2,5}))?)(\/(?:[-+~%/.,\w]*)?(?:\?[-+=&;%@.,\w]*)?(?:#[.,!/\w]*)?)?$/;
-
-// The URL schemes the url() decoder accepts by default
-const DEFAULT_SCHEMES = ['https'];
-
-/**
- * Decoder that only returns Ok for string inputs.  Err otherwise.
- */
-export const string: Decoder<string> = (blob: mixed) => {
-    return typeof blob === 'string'
-        ? Result.ok(blob)
-        : Result.err(annotate(blob, 'Must be string'));
-};
-
-/**
- * Decoder that only returns Ok for non-empty string inputs.  Err otherwise.
- */
-export const nonEmptyString: Decoder<string> = regex(/\S/, 'Must be non-empty string');
-
-/**
- * Decoder that only returns Ok for string inputs that match the regular
- * expression.  Err otherwise.  Will always validate that the input is a string
- * before testing the regex.
- */
-export function regex(regex: RegExp, msg: string): Decoder<string> {
-    return compose(
-        string,
-        predicate((s) => regex.test(s), msg),
-    );
-}
-
-/**
- * Decoder that only returns Ok for string inputs that match the almost perfect
- * email regex, taken from http://emailregex.com.  Err otherwise.
- */
-export const email: Decoder<string> = regex(
-    /^(([^<>()[\]\\.,;:\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',
-);
-
-/**
- * Decoder that only returns Ok for string inputs that match URLs of the
- * expected scheme.  Defaults to only accept HTTPS URLs.  Err otherwise.
- *
- * Variants that can be used:
- *
- * - url()                      accepts only https:// URLs
- * - url([])                    accepts any URL scheme
- * - url(['http'])              accepts only HTTP
- * - url(['https', 'git+ssh'])  accepts both https:// and git+ssh:// URLs
- */
-export const url = (schemes: $ReadOnlyArray<string> = DEFAULT_SCHEMES): Decoder<string> =>
-    compose(string, (value: string) => {
-        const matches = value.match(url_re);
-        if (!matches) {
-            return Result.err(annotate(value, 'Must be URL'));
-        } else {
-            const scheme = matches[1];
-            if (schemes.length === 0 || schemes.includes(scheme.toLowerCase())) {
-                return Result.ok(value);
-            } else {
-                return Result.err(
-                    annotate(value, `URL scheme must be any of: ${schemes.join(', ')}`),
-                );
-            }
-        }
-    });