decoders 2.0.0-beta1 → 2.0.0-beta2

package/{es → _esm}/index.js

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

@@ -21,25 +21,18 @@
 export type { Decoder, Guard } from './_types';
 export type { DecoderType, GuardType } from './_types';
 
-export type { JSONValue, JSONObject, JSONArray } from './stdlib/json';
+export type { JSONValue, JSONObject, JSONArray } from './core/json';
 
 export { guard } from './_guard';
 
-export { compose, map, predicate } from './stdlib/composition';
+export { compose, map, predicate } from './core/composition';
 
-export { array, nonEmptyArray, poja } from './stdlib/array';
-export { boolean, numericBoolean, truthy } from './stdlib/boolean';
-export {
-    constant,
-    hardcoded,
-    mixed,
-    null_,
-    undefined_,
-    unknown,
-} from './stdlib/constants';
-export { date, iso8601 } from './stdlib/date';
-export { describe } from './stdlib/describe';
-export { dispatch } from './stdlib/dispatch';
+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,
@@ -50,14 +43,14 @@ export {
     either8,
     either9,
     oneOf,
-} from './stdlib/either';
-export { fail } from './stdlib/fail';
-export { instanceOf } from './stdlib/instanceOf';
-export { json, jsonObject, jsonArray } from './stdlib/json';
-export { lazy } from './stdlib/lazy';
-export { mapping, dict } from './stdlib/mapping';
-export { integer, number, positiveInteger, positiveNumber } from './stdlib/number';
-export { exact, inexact, object, pojo } from './stdlib/object';
-export { maybe, nullable, optional } from './stdlib/optional';
-export { email, nonEmptyString, regex, string, url } from './stdlib/string';
-export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './stdlib/tuple';
+} 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/_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.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.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,
+};