decoders 2.0.0-beta8 → 2.0.0-beta9

package/core/boolean.js

@@ -7,10 +7,10 @@ var _annotate = require("../annotate");
 
 var _result = require("../result");
 
-var _composition = require("./composition");
-
 var _number = require("./number");
 
+var _composition = require("./composition");
+
 /**
  * Decoder that only returns Ok for boolean inputs.  Err otherwise.
  */
@@ -34,7 +34,7 @@ var truthy = function truthy(blob) {
 
 
 exports.truthy = truthy;
-var numericBoolean = (0, _composition.map)(_number.number, function (n) {
+var numericBoolean = (0, _composition.transform)(_number.number, function (n) {
   return !!n;
 });
 exports.numericBoolean = numericBoolean;

package/core/boolean.js.flow

@@ -2,8 +2,8 @@
 
 import { annotate } from '../annotate';
 import { err, ok } from '../result';
-import { map } from './composition';
 import { number } from './number';
+import { transform } from './composition';
 import type { Decoder } from '../_types';
 
 /**
@@ -24,4 +24,4 @@ export const truthy: Decoder<boolean> = (blob: mixed) => {
  * 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);
+export const numericBoolean: Decoder<boolean> = transform(number, (n) => !!n);

package/core/boolean.mjs

@@ -1,7 +1,7 @@
 import { annotate } from '../annotate.mjs';
 import { err, ok } from '../result.mjs';
-import { map } from './composition.mjs';
 import { number } from './number.mjs';
+import { transform } from './composition.mjs';
 
 /**
  * Decoder that only returns Ok for boolean inputs.  Err otherwise.
@@ -23,6 +23,6 @@ export var truthy = function truthy(blob) {
  * Returns their boolean representation.  Err otherwise.
  */
 
-export var numericBoolean = map(number, function (n) {
+export var numericBoolean = transform(number, function (n) {
   return !!n;
 });

package/core/composition.d.ts

@@ -1,6 +1,6 @@
 import { Decoder } from '../_types';
 
-export function map<T, V>(decoder: Decoder<T>, mapper: (value: T) => V): Decoder<V>;
+export function transform<T, V>(decoder: Decoder<T>, mapper: (value: T) => V): Decoder<V>;
 export function compose<T, V>(decoder: Decoder<T>, next: Decoder<V, T>): Decoder<V>;
 export function predicate<T, N extends T>(
     decoder: Decoder<T>,
@@ -12,3 +12,7 @@ export function predicate<T>(
     predicate: (value: T) => boolean,
     msg: string,
 ): Decoder<T>;
+export function prep<T, I>(
+    mapperFn: (blob: unknown) => I,
+    decoder: Decoder<T, I>,
+): Decoder<T>;

package/core/composition.js

@@ -2,21 +2,24 @@
 
 exports.__esModule = true;
 exports.compose = compose;
-exports.map = map;
 exports.predicate = predicate;
+exports.prep = prep;
+exports.transform = transform;
 
 var _result = require("../result");
 
 var _annotate = require("../annotate");
 
 /**
- * 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.
+ * Accepts any value the given decoder accepts, and on success, will call the
+ * mapper value **on the decoded result**. If the mapper function throws an
+ * error, the whole decoder will fail using the error message as the failure
+ * reason.
  */
-function map(decoder, mapper) {
+function transform(decoder, transformFn) {
   return compose(decoder, function (x) {
     try {
-      return (0, _result.ok)(mapper(x));
+      return (0, _result.ok)(transformFn(x));
     } catch (e) {
       return (0, _result.err)((0, _annotate.annotate)(x, e instanceof Error ? e.message : String(e)));
     }
@@ -51,4 +54,29 @@ function predicate(decoder, predicateFn, msg) {
       return predicateFn(value) ? (0, _result.ok)(value) : (0, _result.err)((0, _annotate.annotate)(value, msg));
     });
   };
+}
+/**
+ * Pre-process the data input before passing it into the decoder. This gives
+ * you the ability to arbitrarily customize the input on the fly before passing
+ * it to the decoder. Of course, the input value at that point is still of
+ * `unknown` type, so you will have to deal with that accordingly.
+ */
+
+
+function prep(mapperFn, decoder) {
+  return function (blob) {
+    var blob2;
+
+    try {
+      blob2 = mapperFn(blob);
+    } catch (e) {
+      return (0, _result.err)((0, _annotate.annotate)(blob, e.message));
+    }
+
+    return (0, _result.orElse)(decoder(blob2), function (ann) {
+      return (0, _result.err)((0, _annotate.annotate)(blob, ann.text));
+    } //                    ^^^^ Annotates the _original_ input value
+    //                         (instead of echoing back blob2 in the output)
+    );
+  };
 }

package/core/composition.js.flow

@@ -1,17 +1,19 @@
 // @flow strict
 
-import { andThen, err, ok } from '../result';
+import { andThen, err, ok, orElse } 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.
+ * Accepts any value the given decoder accepts, and on success, will call the
+ * mapper value **on the decoded result**. If the mapper function throws an
+ * error, the whole decoder will fail using the error message as the failure
+ * reason.
  */
-export function map<T, V>(decoder: Decoder<T>, mapper: (T) => V): Decoder<V> {
+export function transform<T, V>(decoder: Decoder<T>, transformFn: (T) => V): Decoder<V> {
     return compose(decoder, (x) => {
         try {
-            return ok(mapper(x));
+            return ok(transformFn(x));
         } catch (e) {
             return err(annotate(x, e instanceof Error ? e.message : String(e)));
         }
@@ -46,3 +48,27 @@ export function predicate<T>(
             predicateFn(value) ? ok(value) : err(annotate(value, msg)),
         );
 }
+
+/**
+ * Pre-process the data input before passing it into the decoder. This gives
+ * you the ability to arbitrarily customize the input on the fly before passing
+ * it to the decoder. Of course, the input value at that point is still of
+ * `unknown` type, so you will have to deal with that accordingly.
+ */
+export function prep<I, T>(mapperFn: (mixed) => I, decoder: Decoder<T, I>): Decoder<T> {
+    return (blob: mixed) => {
+        let blob2;
+        try {
+            blob2 = mapperFn(blob);
+        } catch (e) {
+            return err(annotate(blob, e.message));
+        }
+
+        return orElse(
+            decoder(blob2),
+            (ann) => err(annotate(blob, ann.text)),
+            //                    ^^^^ Annotates the _original_ input value
+            //                         (instead of echoing back blob2 in the output)
+        );
+    };
+}

package/core/composition.mjs

@@ -1,14 +1,16 @@
-import { andThen, err, ok } from '../result.mjs';
+import { andThen, err, ok, orElse } from '../result.mjs';
 import { annotate } from '../annotate.mjs';
 
 /**
- * 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.
+ * Accepts any value the given decoder accepts, and on success, will call the
+ * mapper value **on the decoded result**. If the mapper function throws an
+ * error, the whole decoder will fail using the error message as the failure
+ * reason.
  */
-export function map(decoder, mapper) {
+export function transform(decoder, transformFn) {
   return compose(decoder, function (x) {
     try {
-      return ok(mapper(x));
+      return ok(transformFn(x));
     } catch (e) {
       return err(annotate(x, e instanceof Error ? e.message : String(e)));
     }
@@ -41,4 +43,28 @@ export function predicate(decoder, predicateFn, msg) {
       return predicateFn(value) ? ok(value) : err(annotate(value, msg));
     });
   };
+}
+/**
+ * Pre-process the data input before passing it into the decoder. This gives
+ * you the ability to arbitrarily customize the input on the fly before passing
+ * it to the decoder. Of course, the input value at that point is still of
+ * `unknown` type, so you will have to deal with that accordingly.
+ */
+
+export function prep(mapperFn, decoder) {
+  return function (blob) {
+    var blob2;
+
+    try {
+      blob2 = mapperFn(blob);
+    } catch (e) {
+      return err(annotate(blob, e.message));
+    }
+
+    return orElse(decoder(blob2), function (ann) {
+      return err(annotate(blob, ann.text));
+    } //                    ^^^^ Annotates the _original_ input value
+    //                         (instead of echoing back blob2 in the output)
+    );
+  };
 }

package/core/date.js

@@ -9,10 +9,10 @@ var _result = require("../result");
 
 var _utils = require("../_utils");
 
-var _composition = require("./composition");
-
 var _string = require("./string");
 
+var _composition = require("./composition");
+
 // 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
@@ -28,7 +28,7 @@ var date = function date(value) {
 
 
 exports.date = date;
-var iso8601 = (0, _composition.map)( // Input itself needs to match the ISO8601 regex...
+var iso8601 = (0, _composition.transform)( // Input itself needs to match the ISO8601 regex...
 (0, _string.regex)(iso8601_re, 'Must be ISO8601 format'), // Make sure it is a _valid_ date
 function (value) {
   var date = new Date(value);

package/core/date.js.flow

@@ -3,8 +3,8 @@
 import { annotate } from '../annotate';
 import { err, ok } from '../result';
 import { isDate } from '../_utils';
-import { map } from './composition';
 import { regex } from './string';
+import { transform } from './composition';
 import type { Decoder } from '../_types';
 
 // $FlowFixMe[unclear-type] (not really an issue) - deliberate casting
@@ -23,7 +23,7 @@ export const date: Decoder<Date> = (value: mixed) =>
  * Decoder that only returns Ok for strings that are valid ISO8601 date
  * strings.  Err otherwise.
  */
-export const iso8601: Decoder<Date> = map(
+export const iso8601: Decoder<Date> = transform(
     // Input itself needs to match the ISO8601 regex...
     regex(iso8601_re, 'Must be ISO8601 format'),
 

package/core/date.mjs

@@ -1,8 +1,8 @@
 import { annotate } from '../annotate.mjs';
 import { err, ok } from '../result.mjs';
 import { isDate } from '../_utils.mjs';
-import { map } from './composition.mjs';
 import { regex } from './string.mjs';
+import { transform } from './composition.mjs';
 // 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
@@ -15,7 +15,7 @@ export var date = function date(value) {
  * strings.  Err otherwise.
  */
 
-export var iso8601 = map( // Input itself needs to match the ISO8601 regex...
+export var iso8601 = transform( // Input itself needs to match the ISO8601 regex...
 regex(iso8601_re, 'Must be ISO8601 format'), // Make sure it is a _valid_ date
 function (value) {
   var date = new Date(value);

package/core/dispatch.d.ts

@@ -2,7 +2,7 @@ import { Decoder, DecoderType } from '../_types';
 
 export type Values<T extends object> = T[keyof T];
 
-export function disjointUnion<O extends { [key: string]: Decoder<any> }>(
+export function taggedUnion<O extends { [key: string]: Decoder<any> }>(
     field: string,
     mapping: O,
 ): Decoder<Values<{ [key in keyof O]: DecoderType<O[key]> }>>;

package/core/dispatch.js

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.disjointUnion = disjointUnion;
+exports.taggedUnion = taggedUnion;
 
 var _result = require("../result");
 
@@ -9,6 +9,8 @@ var _object2 = require("./object");
 
 var _either = require("./either");
 
+var _composition = require("./composition");
+
 /**
  * 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:
@@ -31,23 +33,23 @@ var _either = require("./either");
  * Then these two decoders are equivalent:
  *
  *     const shape = either(rectangle, circle)
- *     const shape = disjointUnion('type', { rectangle, circle })
+ *     const shape = taggedUnion('type', { rectangle, circle })
  *
  * Will be of type Decoder<Rectangle | Circle>.
  *
- * But `disjointUnion` will typically be more runtime-efficient.  The reason is
+ * But `taggedUnion` 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 `disjointUnion()`.
+ * Also, the error messages will be less ambiguous using `taggedUnion()`.
  */
-function disjointUnion(field, mapping) {
+function taggedUnion(field, mapping) {
   var _object;
 
-  var base = (0, _object2.object)((_object = {}, _object[field] = (0, _either.oneOf)(Object.keys(mapping)), _object));
+  var base = (0, _object2.object)((_object = {}, _object[field] = (0, _composition.prep)(String, (0, _either.oneOf)(Object.keys(mapping))), _object));
   return function (blob) {
     return (0, _result.andThen)(base(blob), function (baseObj) {
       var decoderName = baseObj[field];

package/core/dispatch.js.flow

@@ -3,11 +3,10 @@
 import { andThen } from '../result';
 import { object } from './object';
 import { oneOf } from './either';
+import { prep } from './composition';
+import type { _Any } from '../_utils';
 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:
@@ -30,24 +29,26 @@ type anything = any;
  * Then these two decoders are equivalent:
  *
  *     const shape = either(rectangle, circle)
- *     const shape = disjointUnion('type', { rectangle, circle })
+ *     const shape = taggedUnion('type', { rectangle, circle })
  *
  * Will be of type Decoder<Rectangle | Circle>.
  *
- * But `disjointUnion` will typically be more runtime-efficient.  The reason is
+ * But `taggedUnion` 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 `disjointUnion()`.
+ * Also, the error messages will be less ambiguous using `taggedUnion()`.
  */
-export function disjointUnion<O: { +[field: string]: Decoder<anything>, ... }>(
+export function taggedUnion<O: { +[field: string]: Decoder<_Any>, ... }>(
     field: string,
     mapping: O,
 ): Decoder<$Values<$ObjMap<O, DecoderType>>> {
-    const base = object({ [field]: oneOf(Object.keys(mapping)) });
+    const base = object({
+        [field]: prep(String, oneOf(Object.keys(mapping))),
+    });
     return (blob: mixed) => {
         return andThen(base(blob), (baseObj) => {
             const decoderName = baseObj[field];

package/core/dispatch.mjs

@@ -1,6 +1,7 @@
 import { andThen } from '../result.mjs';
 import { object } from './object.mjs';
 import { oneOf } from './either.mjs';
+import { prep } from './composition.mjs';
 
 /**
  * Dispatches to one of several given decoders, based on the value found at
@@ -24,23 +25,23 @@ import { oneOf } from './either.mjs';
  * Then these two decoders are equivalent:
  *
  *     const shape = either(rectangle, circle)
- *     const shape = disjointUnion('type', { rectangle, circle })
+ *     const shape = taggedUnion('type', { rectangle, circle })
  *
  * Will be of type Decoder<Rectangle | Circle>.
  *
- * But `disjointUnion` will typically be more runtime-efficient.  The reason is
+ * But `taggedUnion` 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 `disjointUnion()`.
+ * Also, the error messages will be less ambiguous using `taggedUnion()`.
  */
-export function disjointUnion(field, mapping) {
+export function taggedUnion(field, mapping) {
   var _object;
 
-  var base = object((_object = {}, _object[field] = oneOf(Object.keys(mapping)), _object));
+  var base = object((_object = {}, _object[field] = prep(String, oneOf(Object.keys(mapping))), _object));
   return function (blob) {
     return andThen(base(blob), function (baseObj) {
       var decoderName = baseObj[field];

package/core/either.d.ts

@@ -1,61 +1,66 @@
 import { Decoder, Scalar } from '../_types';
 
-export function either<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
-export function either2<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
-export function either3<T1, T2, T3>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-): Decoder<T1 | T2 | T3>;
-export function either4<T1, T2, T3, T4>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-): Decoder<T1 | T2 | T3 | T4>;
-export function either5<T1, T2, T3, T4, T5>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-): Decoder<T1 | T2 | T3 | T4 | T5>;
-export function either6<T1, T2, T3, T4, T5, T6>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6>;
-export function either7<T1, T2, T3, T4, T5, T6, T7>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7>;
-export function either8<T1, T2, T3, T4, T5, T6, T7, T8>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-    d8: Decoder<T8>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8>;
-export function either9<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-    d8: Decoder<T8>,
-    d9: Decoder<T9>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8 | T9>;
+export type DecoderTypes<T> = T extends ReadonlyArray<Decoder<infer U>> ? U : never;
+
+export function either<T extends ReadonlyArray<Decoder<any>>>(
+    ...args: T
+): Decoder<DecoderTypes<T>>;
+// export function either<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
+// export function either2<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
+// export function either3<T1, T2, T3>(
+//     d1: Decoder<T1>,
+//     d2: Decoder<T2>,
+//     d3: Decoder<T3>,
+// ): Decoder<T1 | T2 | T3>;
+// export function either4<T1, T2, T3, T4>(
+//     d1: Decoder<T1>,
+//     d2: Decoder<T2>,
+//     d3: Decoder<T3>,
+//     d4: Decoder<T4>,
+// ): Decoder<T1 | T2 | T3 | T4>;
+// export function either5<T1, T2, T3, T4, T5>(
+//     d1: Decoder<T1>,
+//     d2: Decoder<T2>,
+//     d3: Decoder<T3>,
+//     d4: Decoder<T4>,
+//     d5: Decoder<T5>,
+// ): Decoder<T1 | T2 | T3 | T4 | T5>;
+// export function either6<T1, T2, T3, T4, T5, T6>(
+//     d1: Decoder<T1>,
+//     d2: Decoder<T2>,
+//     d3: Decoder<T3>,
+//     d4: Decoder<T4>,
+//     d5: Decoder<T5>,
+//     d6: Decoder<T6>,
+// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6>;
+// export function either7<T1, T2, T3, T4, T5, T6, T7>(
+//     d1: Decoder<T1>,
+//     d2: Decoder<T2>,
+//     d3: Decoder<T3>,
+//     d4: Decoder<T4>,
+//     d5: Decoder<T5>,
+//     d6: Decoder<T6>,
+//     d7: Decoder<T7>,
+// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7>;
+// export function either8<T1, T2, T3, T4, T5, T6, T7, T8>(
+//     d1: Decoder<T1>,
+//     d2: Decoder<T2>,
+//     d3: Decoder<T3>,
+//     d4: Decoder<T4>,
+//     d5: Decoder<T5>,
+//     d6: Decoder<T6>,
+//     d7: Decoder<T7>,
+//     d8: Decoder<T8>,
+// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8>;
+// export function either9<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
+//     d1: Decoder<T1>,
+//     d2: Decoder<T2>,
+//     d3: Decoder<T3>,
+//     d4: Decoder<T4>,
+//     d5: Decoder<T5>,
+//     d6: Decoder<T6>,
+//     d7: Decoder<T7>,
+//     d8: Decoder<T8>,
+//     d9: Decoder<T9>,
+// ): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8 | T9>;
 export function oneOf<T extends Scalar>(constants: readonly T[]): Decoder<T>;