decoders 2.0.0-beta1 → 2.0.0-beta5

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## v2.0.0-beta
 
+Upgrading to v2 _can_, but doesn't _have_ to be a breaking change for you. If upgrading
+causes errors for you, please see the [migration guide](./MIGRATING-v2.md) for
+instructions.
+
 Potentially breaking changes:
 
 -   Drop support for all Node versions below 12.x

package/{es/stdlib → _esm/core}/tuple.js

@@ -1,6 +1,6 @@
 import { annotate } from '../annotate';
 import { compose, predicate } from './composition';
-import { err, errValue, isErr, ok, unwrap, value } from '../result';
+import { err, ok, okOrErrValue, unwrap } from '../result';
 import { poja } from './array';
 
 var ntuple = function ntuple(n) {
@@ -24,7 +24,7 @@ export function tuple1(decoder1) {
     } catch (e) {
       // If a decoder error has happened while unwrapping all the
       // results, try to construct a good error message
-      return err(annotate(errValue(result1)));
+      return err(annotate([okOrErrValue(result1)]));
     }
   });
 }
@@ -45,7 +45,7 @@ export function tuple2(decoder1, decoder2) {
     } catch (e) {
       // If a decoder error has happened while unwrapping all the
       // results, try to construct a good error message
-      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2)]));
+      return err(annotate([okOrErrValue(result1), okOrErrValue(result2)]));
     }
   });
 }
@@ -68,7 +68,7 @@ export function tuple3(decoder1, decoder2, decoder3) {
     } catch (e) {
       // If a decoder error has happened while unwrapping all the
       // results, try to construct a good error message
-      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3)]));
+      return err(annotate([okOrErrValue(result1), okOrErrValue(result2), okOrErrValue(result3)]));
     }
   });
 }
@@ -93,7 +93,7 @@ export function tuple4(decoder1, decoder2, decoder3, decoder4) {
     } catch (e) {
       // If a decoder error has happened while unwrapping all the
       // results, try to construct a good error message
-      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3), isErr(result4) ? errValue(result4) : value(result4)]));
+      return err(annotate([okOrErrValue(result1), okOrErrValue(result2), okOrErrValue(result3), okOrErrValue(result4)]));
     }
   });
 }
@@ -120,7 +120,7 @@ export function tuple5(decoder1, decoder2, decoder3, decoder4, decoder5) {
     } catch (e) {
       // If a decoder error has happened while unwrapping all the
       // results, try to construct a good error message
-      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3), isErr(result4) ? errValue(result4) : value(result4), isErr(result5) ? errValue(result5) : value(result5)]));
+      return err(annotate([okOrErrValue(result1), okOrErrValue(result2), okOrErrValue(result3), okOrErrValue(result4), okOrErrValue(result5)]));
     }
   });
 }
@@ -149,7 +149,7 @@ export function tuple6(decoder1, decoder2, decoder3, decoder4, decoder5, decoder
     } catch (e) {
       // If a decoder error has happened while unwrapping all the
       // results, try to construct a good error message
-      return err(annotate([isErr(result1) ? errValue(result1) : value(result1), isErr(result2) ? errValue(result2) : value(result2), isErr(result3) ? errValue(result3) : value(result3), isErr(result4) ? errValue(result4) : value(result4), isErr(result5) ? errValue(result5) : value(result5), isErr(result6) ? errValue(result6) : value(result6)]));
+      return err(annotate([okOrErrValue(result1), okOrErrValue(result2), okOrErrValue(result3), okOrErrValue(result4), okOrErrValue(result5), okOrErrValue(result6)]));
     }
   });
 }

package/{cjs/stdlib → _esm/core}/tuple.js.flow

@@ -2,7 +2,7 @@
 
 import { annotate } from '../annotate';
 import { compose, predicate } from './composition';
-import { err, errValue, isErr, ok, unwrap, value } from '../result';
+import { err, ok, okOrErrValue, unwrap } from '../result';
 import { poja } from './array';
 import type { Decoder } from '../_types';
 
@@ -26,7 +26,7 @@ export function tuple1<T>(decoder1: Decoder<T>): Decoder<[T]> {
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return err(annotate(errValue(result1)));
+            return err(annotate([okOrErrValue(result1)]));
         }
     });
 }
@@ -49,12 +49,7 @@ export function tuple2<T1, T2>(
         } catch (e) {
             // If a decoder error has happened while unwrapping all the
             // results, try to construct a good error message
-            return err(
-                annotate([
-                    isErr(result1) ? errValue(result1) : value(result1),
-                    isErr(result2) ? errValue(result2) : value(result2),
-                ]),
-            );
+            return err(annotate([okOrErrValue(result1), okOrErrValue(result2)]));
         }
     });
 }
@@ -81,9 +76,9 @@ export function tuple3<T1, T2, T3>(
             // results, try to construct a good error message
             return err(
                 annotate([
-                    isErr(result1) ? errValue(result1) : value(result1),
-                    isErr(result2) ? errValue(result2) : value(result2),
-                    isErr(result3) ? errValue(result3) : value(result3),
+                    okOrErrValue(result1),
+                    okOrErrValue(result2),
+                    okOrErrValue(result3),
                 ]),
             );
         }
@@ -119,10 +114,10 @@ export function tuple4<T1, T2, T3, T4>(
             // results, try to construct a good error message
             return err(
                 annotate([
-                    isErr(result1) ? errValue(result1) : value(result1),
-                    isErr(result2) ? errValue(result2) : value(result2),
-                    isErr(result3) ? errValue(result3) : value(result3),
-                    isErr(result4) ? errValue(result4) : value(result4),
+                    okOrErrValue(result1),
+                    okOrErrValue(result2),
+                    okOrErrValue(result3),
+                    okOrErrValue(result4),
                 ]),
             );
         }
@@ -161,11 +156,11 @@ export function tuple5<T1, T2, T3, T4, T5>(
             // results, try to construct a good error message
             return err(
                 annotate([
-                    isErr(result1) ? errValue(result1) : value(result1),
-                    isErr(result2) ? errValue(result2) : value(result2),
-                    isErr(result3) ? errValue(result3) : value(result3),
-                    isErr(result4) ? errValue(result4) : value(result4),
-                    isErr(result5) ? errValue(result5) : value(result5),
+                    okOrErrValue(result1),
+                    okOrErrValue(result2),
+                    okOrErrValue(result3),
+                    okOrErrValue(result4),
+                    okOrErrValue(result5),
                 ]),
             );
         }
@@ -207,12 +202,12 @@ export function tuple6<T1, T2, T3, T4, T5, T6>(
             // results, try to construct a good error message
             return err(
                 annotate([
-                    isErr(result1) ? errValue(result1) : value(result1),
-                    isErr(result2) ? errValue(result2) : value(result2),
-                    isErr(result3) ? errValue(result3) : value(result3),
-                    isErr(result4) ? errValue(result4) : value(result4),
-                    isErr(result5) ? errValue(result5) : value(result5),
-                    isErr(result6) ? errValue(result6) : value(result6),
+                    okOrErrValue(result1),
+                    okOrErrValue(result2),
+                    okOrErrValue(result3),
+                    okOrErrValue(result4),
+                    okOrErrValue(result5),
+                    okOrErrValue(result6),
                 ]),
             );
         }

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

@@ -18,28 +18,28 @@
  * type.  In our case, it's fine to fail with a runtime error.
  *
  */
-export type { Decoder, Guard } from './_types';
-export type { DecoderType, GuardType } from './_types';
-
-export type { JSONValue, JSONObject, JSONArray } from './stdlib/json';
+export type {
+    Decoder,
+    DecodeResult,
+    DecoderType,
+    Guard,
+    GuardType,
+    Predicate,
+    Scalar,
+} from './_types';
+export type { Result } from './result';
+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 +50,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/{es → _esm}/result.js

@@ -10,7 +10,8 @@
 export function ok(value) {
   return {
     type: 'ok',
-    value: value
+    value: value,
+    error: undefined
   };
 }
 /**
@@ -20,6 +21,7 @@ export function ok(value) {
 export function err(error) {
   return {
     type: 'err',
+    value: undefined,
     error: error
   };
 }
@@ -34,13 +36,20 @@ export function isErr(result) {
 }
 export function withDefault(result, defaultValue) {
   return result.type === 'ok' ? result.value : defaultValue;
-}
-export function value(result) {
+} // TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { value } = result;
+
+export function okValue(result) {
   return result.type === 'ok' ? result.value : undefined;
-}
+} // TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { error } = result;
+
 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.
@@ -127,7 +136,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/{cjs → _esm}/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,14 +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 };
+    return { type: 'err', value: undefined, error };
 }
 
 export function toString(result: Result<mixed, mixed>): string {
@@ -43,14 +43,22 @@ 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 {
+// TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { value } = result;
+export function okValue<T>(result: Result<T, mixed>): void | T {
     return result.type === 'ok' ? result.value : undefined;
 }
 
+// TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { error } = result;
 export function errValue<E>(result: Result<mixed, E>): void | E {
     return result.type === 'err' ? result.error : undefined;
 }
 
+export function okOrErrValue<T, E>(result: Result<T, E>): T | E {
+    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.
@@ -148,7 +156,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/_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;