decoders 2.0.0-beta4 → 2.0.0-beta8

package/{_esm/result.js → result.mjs}

@@ -10,7 +10,8 @@
 export function ok(value) {
   return {
     type: 'ok',
-    value: value
+    value: value,
+    error: undefined
   };
 }
 /**
@@ -20,30 +21,10 @@ export function ok(value) {
 export function err(error) {
   return {
     type: 'err',
+    value: undefined,
     error: error
   };
 }
-export function toString(result) {
-  return result.type === 'ok' ? "Ok(" + String(result.value) + ")" : "Err(" + String(result.error) + ")";
-}
-export function isOk(result) {
-  return result.type === 'ok';
-}
-export function isErr(result) {
-  return result.type === 'err';
-}
-export function withDefault(result, defaultValue) {
-  return result.type === 'ok' ? result.value : defaultValue;
-}
-export function okValue(result) {
-  return result.type === 'ok' ? result.value : undefined;
-}
-export function errValue(result) {
-  return result.type === 'err' ? result.error : undefined;
-}
-export function okOrErrValue(result) {
-  return result.type === 'ok' ? result.value : result.error;
-}
 /**
  * Unwrap the value from this Result instance if this is an "Ok" result.
  * Otherwise, will throw the "Err" error via a runtime exception.
@@ -66,48 +47,6 @@ export function expect(result, message) {
 export function dispatch(result, okCallback, errCallback) {
   return result.type === 'ok' ? okCallback(result.value) : errCallback(result.error);
 }
-/**
- * If the given result is OK, defers to the other result. Otherwise returns the
- * error result.
- *
- * It's like saying A && B, but on Result.
- *
- * Examples:
- *
- *     Result.ok(42)     && Result.ok('hi')    // => Ok('hi')
- *     Result.err('boo') && Result.ok('hi')    // => Err('boo')
- *     Result.ok(42)     && Result.err('boo')  // => Err('boo')
- *     Result.err('boo') && Result.err('boo')  // => Err('boo')
- *
- */
-// export function and<T, E, T2>(
-//     result1: Result<T, E>,
-//     result2: Result<T2, E>,
-// ): Result<T2, E> {
-//     return result1.type === 'ok' ? result2 : result1;
-// }
-
-/**
- * If the given result is OK, return that result. Otherwise, defers to the
- * other result.
- *
- * It's like saying A || B, but on Result.
- *
- * Examples:
- *
- *     Result.ok(42)      || Result.ok('hi')    // => Ok(42)
- *     Result.err('boo')  || Result.ok('hi')    // => Ok('hi')
- *     Result.ok(42)      || Result.err('boo')  // => Ok(42)
- *     Result.err('bleh') || Result.err('boo')  // => Err('boo')
- *
- */
-// export function or<T, E, E2>(
-//     result1: Result<T, E>,
-//     result2: Result<T, E2>,
-// ): Result<T, E2> {
-//     return result1.type === 'ok' ? result1 : result2;
-// }
-
 /**
  * Like .and(), aka &&, but the second argument gets evaluated lazily only if
  * the first result is an Ok result. If so, it has access to the Ok value from

package/_esm/_guard.js.flow

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

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

@@ -1,97 +0,0 @@
-// @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/_esm/annotate.js.flow

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

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

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

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

@@ -1,46 +0,0 @@
-// @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;