decoders 2.0.0-beta3 → 2.0.0-beta7

package/result.js.flow

@@ -6,8 +6,8 @@
  *     | Err <error>
  */
 
-type Ok<+T> = {| +type: 'ok', +value: T |};
-type Err<+E> = {| +type: 'err', +error: E |};
+type Ok<+T> = {| +type: 'ok', +value: T, +error: void |};
+type Err<+E> = {| +type: 'err', +value: void, +error: E |};
 
 export type Result<+T, +E> = Ok<T> | Err<E>;
 
@@ -15,40 +15,14 @@ export type Result<+T, +E> = Ok<T> | Err<E>;
  * Create a new Result instance representing a successful computation.
  */
 export function ok<T>(value: T): Ok<T> {
-    return { type: 'ok', value };
+    return { type: 'ok', value, error: undefined };
 }
 
 /**
  * Create a new Result instance representing a failed computation.
  */
 export function err<E>(error: E): Err<E> {
-    return { type: 'err', error };
-}
-
-export function toString(result: Result<mixed, mixed>): string {
-    return result.type === 'ok'
-        ? `Ok(${String(result.value)})`
-        : `Err(${String(result.error)})`;
-}
-
-export function isOk(result: Result<mixed, mixed>): boolean {
-    return result.type === 'ok';
-}
-
-export function isErr(result: Result<mixed, mixed>): boolean {
-    return result.type === 'err';
-}
-
-export function withDefault<T>(result: Result<T, mixed>, defaultValue: T): T {
-    return result.type === 'ok' ? result.value : defaultValue;
-}
-
-export function value<T>(result: Result<T, mixed>): void | T {
-    return result.type === 'ok' ? result.value : undefined;
-}
-
-export function errValue<E>(result: Result<mixed, E>): void | E {
-    return result.type === 'err' ? result.error : undefined;
+    return { type: 'err', value: undefined, error };
 }
 
 /**
@@ -79,48 +53,6 @@ export function dispatch<T, E, O>(
     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
@@ -148,7 +80,7 @@ export function orElse<T, E, E2>(
 /**
  * Transform an Ok result. Will not touch Err results.
  */
-export function map<T, E, T2>(
+export function mapOk<T, E, T2>(
     result: Result<T, E>,
     mapper: (value: T) => T2,
 ): Result<T2, E> {

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

@@ -10,7 +10,8 @@
 export function ok(value) {
   return {
     type: 'ok',
-    value: value
+    value: value,
+    error: undefined
   };
 }
 /**
@@ -20,27 +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 value(result) {
-  return result.type === 'ok' ? result.value : undefined;
-}
-export function errValue(result) {
-  return result.type === 'err' ? result.error : undefined;
-}
 /**
  * Unwrap the value from this Result instance if this is an "Ok" result.
  * Otherwise, will throw the "Err" error via a runtime exception.
@@ -63,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
@@ -127,7 +69,7 @@ export function orElse(result1, lazyResult2) {
  * Transform an Ok result. Will not touch Err results.
  */
 
-export function map(result, mapper) {
+export function mapOk(result, mapper) {
   return result.type === 'ok' ? ok(mapper(result.value)) : result;
 }
 /**

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);