decoders 2.0.0-beta1 → 2.0.0-beta2

package/core/array.js.flow

@@ -0,0 +1,103 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { compose, predicate } from './composition';
+import type { Decoder, DecodeResult } from '../_types';
+
+/**
+ * Like a "Plain Old JavaScript Object", but for arrays: "Plain Old JavaScript
+ * Array" ^_^
+ */
+export const poja: Decoder<Array<mixed>> = (blob: mixed) => {
+    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<T>(
+    items: $ReadOnlyArray<DecodeResult<T>>,
+    blobs: $ReadOnlyArray<mixed>,
+): DecodeResult<Array<T>> {
+    const results: Array<T> = [];
+    for (let index = 0; index < items.length; ++index) {
+        const result = items[index];
+        if (result.type === 'ok') {
+            results.push(result.value);
+        } else {
+            const ann = result.error;
+
+            // Rewrite the annotation to include the index information, and inject it into the original blob
+            const clone = [...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<T>(decoder: Decoder<T>): Decoder<Array<T>, Array<mixed>> {
+    return (blobs: $ReadOnlyArray<mixed>) => {
+        const results = blobs.map(decoder);
+        const 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<T>(decoder: Decoder<T>): Decoder<Array<T>> {
+    return compose(poja, members(decoder));
+}
+
+/**
+ * Builds a Decoder that returns Ok for values of `Array<T>`, but will reject
+ * empty arrays.
+ */
+export function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<Array<T>> {
+    return compose(
+        array(decoder),
+        predicate((arr) => arr.length > 0, 'Must be non-empty array'),
+    );
+}

package/core/boolean.js.flow

@@ -0,0 +1,29 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { map } from './composition';
+import { number } from './number';
+import type { Decoder } from '../_types';
+
+/**
+ * Decoder that only returns Ok for boolean inputs.  Err otherwise.
+ */
+export const boolean: Decoder<boolean> = (blob: mixed) => {
+    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 const truthy: Decoder<boolean> = (blob: mixed) => {
+    return Result.ok(!!blob);
+};
+
+/**
+ * Decoder that only returns Ok for numeric input values representing booleans.
+ * Returns their boolean representation.  Err otherwise.
+ */
+export const numericBoolean: Decoder<boolean> = map(number, (n) => !!n);

package/core/composition.js.flow

@@ -0,0 +1,43 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import type { Decoder } from '../_types';
+
+/**
+ * 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<T, V>(decoder: Decoder<T>, mapper: (T) => V): Decoder<V> {
+    return compose(decoder, (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<T, V>(decoder: Decoder<T>, next: Decoder<V, T>): Decoder<V> {
+    return (blob: mixed) => 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<T>(predicate: (T) => boolean, msg: string): Decoder<T, T> {
+    return (value: T) => {
+        return predicate(value) ? Result.ok(value) : Result.err(annotate(value, msg));
+    };
+}

package/core/constants.js.flow

@@ -0,0 +1,46 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import type { Decoder, Scalar } from '../_types';
+
+/**
+ * Decoder that only returns Ok for `null` inputs.  Err otherwise.
+ */
+export const null_: Decoder<null> = (blob: mixed) =>
+    blob === null ? Result.ok(blob) : Result.err(annotate(blob, 'Must be null'));
+
+/**
+ * Decoder that only returns Ok for `undefined` inputs.  Err otherwise.
+ */
+export const undefined_: Decoder<void> = (blob: mixed) =>
+    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<T: Scalar>(value: T): Decoder<T> {
+    return (blob: mixed) =>
+        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<T>(value: T): Decoder<T> {
+    return () => Result.ok(value);
+}
+
+/**
+ * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
+ */
+export const unknown: Decoder<mixed> = (blob: mixed) => Result.ok(blob);
+
+/**
+ * Alias of unknown.
+ */
+export const mixed: Decoder<mixed> = unknown;

package/core/date.js.flow

@@ -0,0 +1,40 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import { isDate } from '../_utils';
+import { map } from './composition';
+import { regex } from './string';
+import type { Decoder } from '../_types';
+
+// $FlowFixMe[unclear-type] (not really an issue) - deliberate casting
+type cast = any;
+
+// 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
+const iso8601_re =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+export const date: Decoder<Date> = (value: mixed) =>
+    isDate(value)
+        ? Result.ok(((value: cast): Date))
+        : Result.err(annotate(value, 'Must be a Date'));
+
+/**
+ * Decoder that only returns Ok for strings that are valid ISO8601 date
+ * strings.  Err otherwise.
+ */
+export const iso8601: Decoder<Date> = map(
+    // Input itself needs to match the ISO8601 regex...
+    regex(iso8601_re, 'Must be ISO8601 format'),
+
+    // Make sure it is a _valid_ date
+    (value: string) => {
+        const date = new Date(value);
+        if (isNaN(date.getTime())) {
+            throw new Error('Must be valid date/time value');
+        }
+        return date;
+    },
+);

package/core/describe.js.flow

@@ -0,0 +1,17 @@
+// @flow strict
+
+import * as Result from '../result';
+import { annotate } from '../annotate';
+import type { Decoder } from '../_types';
+
+/**
+ * Wrap another decoder, and override the error message in case it fails. This
+ * is useful to "simplify" otherwise potentially complex error messages, or to
+ * use language in those error messages that can be relayed to end users (for
+ * example to show in form errors).
+ */
+export function describe<T>(decoder: Decoder<T>, message: string): Decoder<T> {
+    return (blob: mixed) => {
+        return Result.mapError(decoder(blob), (err) => annotate(err, message));
+    };
+}

package/core/dispatch.js.flow

@@ -0,0 +1,58 @@
+// @flow strict
+
+import * as Result from '../result';
+import { object } from './object';
+import { oneOf } from './either';
+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 anything = any;
+
+/**
+ * Dispatches to one of several given decoders, based on the value found at
+ * runtime in the given field.  For example, suppose you have these decoders:
+ *
+ *     const rectangle = object({
+ *         type: constant('rect'),
+ *         x: number,
+ *         y: number,
+ *         width: number,
+ *         height: number,
+ *     });
+ *
+ *     const circle = object({
+ *         type: constant('circle'),
+ *         cx: number,
+ *         cy: number,
+ *         r: number,
+ *      });
+ *
+ * Then these two decoders are equivalent:
+ *
+ *     const shape = either(rectangle, circle)
+ *     const shape = dispatch('type', { rectangle, circle })
+ *
+ * Will be of type Decoder<Rectangle | Circle>.
+ *
+ * But the dispatch version will typically be more runtime-efficient.  The
+ * reason is that it will first do minimal work to "look ahead" into the `type`
+ * field here, and based on that value, pick the decoder to invoke.
+ *
+ * The `either` version will simply try to invoke each decoder, until it finds
+ * one that matches.
+ *
+ * Also, the error messages will be less ambiguous using `dispatch()`.
+ */
+export function dispatch<O: { +[field: string]: Decoder<anything>, ... }>(
+    field: string,
+    mapping: O,
+): Decoder<$Values<$ObjMap<O, DecoderType>>> {
+    const base = object({ [field]: oneOf(Object.keys(mapping)) });
+    return (blob: mixed) => {
+        return Result.andThen(base(blob), (baseObj) => {
+            const decoderName = baseObj[field];
+            const decoder = mapping[decoderName];
+            return decoder(blob);
+        });
+    };
+}

package/core/either.js.flow

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

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

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

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

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

@@ -0,0 +1,54 @@
+// @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));
+}