decoders 2.0.0-beta1 → 2.0.0-beta5

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];
+}

package/annotate.js.flow

@@ -0,0 +1,218 @@
+// @flow strict
+
+type cast = $FlowFixMe;
+
+const _register: WeakSet<{ ... }> = new WeakSet();
+
+export type ObjectAnnotation = {|
+    +type: 'object',
+    +fields: { +[key: string]: Annotation },
+    +text?: string,
+|};
+
+export type ArrayAnnotation = {|
+    +type: 'array',
+    +items: $ReadOnlyArray<Annotation>,
+    +text?: string,
+|};
+
+export type ScalarAnnotation = {|
+    +type: 'scalar',
+    +value: mixed,
+    +text?: string,
+|};
+
+export type FunctionAnnotation = {|
+    +type: 'function',
+    +text?: string,
+|};
+
+export type CircularRefAnnotation = {|
+    +type: 'circular-ref',
+    +text?: string,
+|};
+
+export type UnknownAnnotation = {|
+    +type: 'unknown',
+    +value: mixed,
+    +text?: string,
+|};
+
+export type Annotation =
+    | ObjectAnnotation
+    | ArrayAnnotation
+    | ScalarAnnotation
+    | FunctionAnnotation
+    | CircularRefAnnotation
+    | UnknownAnnotation;
+
+function brand<A: Annotation>(ann: A): A {
+    _register.add(ann);
+    return ann;
+}
+
+export function object(
+    fields: { +[key: string]: Annotation },
+    text?: string,
+): ObjectAnnotation {
+    return brand({ type: 'object', fields, text });
+}
+
+export function array(items: $ReadOnlyArray<Annotation>, text?: string): ArrayAnnotation {
+    return brand({
+        type: 'array',
+        items,
+        text,
+    });
+}
+
+export function func(text?: string): FunctionAnnotation {
+    return brand({
+        type: 'function',
+        text,
+    });
+}
+
+export function unknown(value: mixed, text?: string): UnknownAnnotation {
+    return brand({
+        type: 'unknown',
+        value,
+        text,
+    });
+}
+
+export function scalar(value: mixed, text?: string): ScalarAnnotation {
+    return brand({
+        type: 'scalar',
+        value,
+        text,
+    });
+}
+
+export function circularRef(text?: string): CircularRefAnnotation {
+    return brand({
+        type: 'circular-ref',
+        text,
+    });
+}
+
+/**
+ * Given an existing Annotation, set the annotation's text to a new value.
+ */
+export function updateText<A: Annotation>(annotation: A, text?: string): A {
+    if (text !== undefined) {
+        return brand({ ...annotation, text });
+    } else {
+        return annotation;
+    }
+}
+
+/**
+ * Given an existing ObjectAnnotation, merges new Annotations in there.
+ */
+export function merge(
+    objAnnotation: ObjectAnnotation,
+    fields: { +[key: string]: Annotation },
+): ObjectAnnotation {
+    const newFields = { ...objAnnotation.fields, ...fields };
+    return object(newFields, objAnnotation.text);
+}
+
+export function asAnnotation(thing: mixed): Annotation | void {
+    return typeof thing === 'object' && thing !== null && _register.has(thing)
+        ? ((thing: cast): Annotation)
+        : undefined;
+}
+
+type RefSet = WeakSet<{ ... } | $ReadOnlyArray<mixed>>;
+
+function annotateArray(
+    value: $ReadOnlyArray<mixed>,
+    text?: string,
+    seen: RefSet,
+): ArrayAnnotation | CircularRefAnnotation {
+    seen.add(value);
+
+    const items = value.map((v) => annotate(v, undefined, seen));
+    return array(items, text);
+}
+
+function annotateObject(
+    obj: { +[string]: mixed },
+    text?: string,
+    seen: RefSet,
+): ObjectAnnotation {
+    seen.add(obj);
+
+    const fields = {};
+    Object.keys(obj).forEach((key) => {
+        const value = obj[key];
+        fields[key] = annotate(value, undefined, seen);
+    });
+    return object(fields, text);
+}
+
+function annotate(value: mixed, text?: string, seen: RefSet): Annotation {
+    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);
+    }
+
+    const 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: mixed, text?: string): Annotation {
+    return annotate(value, text, new WeakSet());
+}
+
+function public_annotateObject(
+    obj: { +[string]: mixed },
+    text?: string,
+): ObjectAnnotation {
+    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/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);
+        });
+    };
+}