decoders 2.0.0-beta1 → 2.0.0-beta2

package/core/number.js.flow

@@ -0,0 +1,34 @@
+// @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/core/object.js.flow

@@ -0,0 +1,203 @@
+// @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/core/optional.js.flow

@@ -0,0 +1,41 @@
+// @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/core/string.js.flow

@@ -0,0 +1,82 @@
+// @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(', ')}`),
+                );
+            }
+        }
+    });

package/core/tuple.js.flow

@@ -0,0 +1,220 @@
+// @flow strict
+
+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';
+
+const ntuple = (n: number) =>
+    compose(
+        poja,
+        predicate((arr) => arr.length === n, `Must be a ${n}-tuple`),
+    );
+
+/**
+ * Builds a Decoder that returns Ok for 1-tuple of [T], given a Decoder for T.
+ * Err otherwise.
+ */
+export function tuple1<T>(decoder1: Decoder<T>): Decoder<[T]> {
+    return compose(ntuple(1), (blobs: $ReadOnlyArray<mixed>) => {
+        const [blob1] = blobs;
+
+        const result1 = decoder1(blob1);
+        try {
+            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(errValue(result1)));
+        }
+    });
+}
+
+/**
+ * Builds a Decoder that returns Ok for 2-tuples of [T1, T2], given Decoders
+ * for T1 and T2.  Err otherwise.
+ */
+export function tuple2<T1, T2>(
+    decoder1: Decoder<T1>,
+    decoder2: Decoder<T2>,
+): Decoder<[T1, T2]> {
+    return compose(ntuple(2), (blobs: $ReadOnlyArray<mixed>) => {
+        const [blob1, blob2] = blobs;
+
+        const result1 = decoder1(blob1);
+        const result2 = decoder2(blob2);
+        try {
+            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(
+                annotate([
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                ]),
+            );
+        }
+    });
+}
+
+/**
+ * Builds a Decoder that returns Ok for 3-tuples of [T1, T2, T3], given
+ * Decoders for T1, T2, and T3.  Err otherwise.
+ */
+export function tuple3<T1, T2, T3>(
+    decoder1: Decoder<T1>,
+    decoder2: Decoder<T2>,
+    decoder3: Decoder<T3>,
+): Decoder<[T1, T2, T3]> {
+    return compose(ntuple(3), (blobs: $ReadOnlyArray<mixed>) => {
+        const [blob1, blob2, blob3] = blobs;
+
+        const result1 = decoder1(blob1);
+        const result2 = decoder2(blob2);
+        const result3 = decoder3(blob3);
+        try {
+            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(
+                annotate([
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                    isErr(result3) ? errValue(result3) : value(result3),
+                ]),
+            );
+        }
+    });
+}
+
+/**
+ * Builds a Decoder that returns Ok for 4-tuples of [T1, T2, T3, T4], given
+ * Decoders for T1, T2, T3, and T4.  Err otherwise.
+ */
+export function tuple4<T1, T2, T3, T4>(
+    decoder1: Decoder<T1>,
+    decoder2: Decoder<T2>,
+    decoder3: Decoder<T3>,
+    decoder4: Decoder<T4>,
+): Decoder<[T1, T2, T3, T4]> {
+    return compose(ntuple(4), (blobs: $ReadOnlyArray<mixed>) => {
+        const [blob1, blob2, blob3, blob4] = blobs;
+
+        const result1 = decoder1(blob1);
+        const result2 = decoder2(blob2);
+        const result3 = decoder3(blob3);
+        const result4 = decoder4(blob4);
+        try {
+            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(
+                annotate([
+                    isErr(result1) ? errValue(result1) : value(result1),
+                    isErr(result2) ? errValue(result2) : value(result2),
+                    isErr(result3) ? errValue(result3) : value(result3),
+                    isErr(result4) ? errValue(result4) : value(result4),
+                ]),
+            );
+        }
+    });
+}
+
+/**
+ * Builds a Decoder that returns Ok for 5-tuples of [T1, T2, T3, T4, T5], given
+ * Decoders for T1, T2, T3, T4, and T5.  Err otherwise.
+ */
+export function tuple5<T1, T2, T3, T4, T5>(
+    decoder1: Decoder<T1>,
+    decoder2: Decoder<T2>,
+    decoder3: Decoder<T3>,
+    decoder4: Decoder<T4>,
+    decoder5: Decoder<T5>,
+): Decoder<[T1, T2, T3, T4, T5]> {
+    return compose(ntuple(5), (blobs: $ReadOnlyArray<mixed>) => {
+        const [blob1, blob2, blob3, blob4, blob5] = blobs;
+
+        const result1 = decoder1(blob1);
+        const result2 = decoder2(blob2);
+        const result3 = decoder3(blob3);
+        const result4 = decoder4(blob4);
+        const result5 = decoder5(blob5);
+        try {
+            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(
+                annotate([
+                    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),
+                ]),
+            );
+        }
+    });
+}
+
+/**
+ * Builds a Decoder that returns Ok for 5-tuples of [T1, T2, T3, T4, T5], given
+ * Decoders for T1, T2, T3, T4, T5, and T6.  Err otherwise.
+ */
+export function tuple6<T1, T2, T3, T4, T5, T6>(
+    decoder1: Decoder<T1>,
+    decoder2: Decoder<T2>,
+    decoder3: Decoder<T3>,
+    decoder4: Decoder<T4>,
+    decoder5: Decoder<T5>,
+    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;
+
+        const result1 = decoder1(blob1);
+        const result2 = decoder2(blob2);
+        const result3 = decoder3(blob3);
+        const result4 = decoder4(blob4);
+        const result5 = decoder5(blob5);
+        const result6 = decoder6(blob6);
+        try {
+            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(
+                annotate([
+                    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/format/index.js.flow

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