decoders 2.0.0-beta9 → 2.0.0

package/lib/unions.mjs

@@ -0,0 +1,146 @@
+import { define } from '../Decoder.mjs';
+import { indent, summarize } from '../_utils.mjs';
+import { object } from './objects.mjs';
+import { prep } from './utilities.mjs';
+var EITHER_PREFIX = 'Either:\n';
+/**
+ * Indents and adds a dash in front of this (potentially multiline) string.
+ */
+
+function itemize(s) {
+  return '-' + indent(s).substring(1);
+}
+/**
+ * Nests another error as an item under a new-to-be-created "Either error". If
+ * the given subitem already is an "Either error" of itself, don't indent, but
+ * just "inject" its items at the same error level, for nicely flattened either
+ * expressions.
+ *
+ * Avoids:
+ *
+ *     Either:
+ *     - Either:
+ *       - Must be P
+ *       - Either:
+ *         - Must be Q
+ *         - Must be R
+ *     - Must be S
+ *
+ * And "flattens" these to:
+ *
+ *     Either:
+ *     - Must be P
+ *     - Must be Q
+ *     - Must be R
+ *     - Must be S
+ *
+ */
+
+
+function nest(errText) {
+  return errText.startsWith(EITHER_PREFIX) ? errText.substr(EITHER_PREFIX.length) : itemize(errText);
+} // prettier-ignore
+
+
+function _either() {
+  for (var _len = arguments.length, decoders = new Array(_len), _key = 0; _key < _len; _key++) {
+    decoders[_key] = arguments[_key];
+  }
+
+  if (decoders.length === 0) {
+    throw new Error('Pass at least one decoder to either()');
+  }
+
+  return define(function (blob, _, err) {
+    // Collect errors here along the way
+    var errors = [];
+
+    for (var _i = 0; _i < decoders.length; _i++) {
+      var result = decoders[_i].decode(blob);
+
+      if (result.ok) {
+        return result;
+      } else {
+        errors.push(result.error);
+      }
+    } // Decoding all alternatives failed, return the combined error message
+
+
+    var text = EITHER_PREFIX + errors.map(function (err) {
+      return nest(summarize(err).join('\n'));
+    }).join('\n');
+    return err(text);
+  });
+}
+/**
+ * Accepts values accepted by any of the given decoders.
+ *
+ * The decoders are tried on the input one by one, in the given order. The
+ * first one that accepts the input "wins". If all decoders reject the input,
+ * the input gets rejected.
+ */
+
+
+export var either = _either;
+/**
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
+ */
+
+export function oneOf(constants) {
+  return define(function (blob, ok, err) {
+    var winner = constants.find(function (c) {
+      return c === blob;
+    });
+
+    if (winner !== undefined) {
+      return ok(winner);
+    }
+
+    return err("Must be one of " + constants.map(function (value) {
+      return JSON.stringify(value);
+    }).join(', '));
+  });
+}
+/**
+ * If you are decoding tagged unions you may want to use the `taggedUnion()`
+ * decoder instead of the general purpose `either()` decoder to get better
+ * error messages and better performance.
+ *
+ * This decoder is optimized for [tagged
+ * unions](https://en.wikipedia.org/wiki/Tagged_union), i.e. a union of
+ * objects where one field is used as the discriminator.
+ *
+ * ```ts
+ * const A = object({ tag: constant('A'), foo: string });
+ * const B = object({ tag: constant('B'), bar: number });
+ *
+ * const AorB = taggedUnion('tag', { A, B });
+ * //                        ^^^
+ * ```
+ *
+ * Decoding now works in two steps:
+ *
+ * 1. Look at the `'tag'` field in the incoming object (this is the field
+ *    that decides which decoder will be used)
+ * 2. If the value is `'A'`, then decoder `A` will be used. If it's `'B'`, then
+ *    decoder `B` will be used. Otherwise, this will fail.
+ *
+ * This is effectively equivalent to `either(A, B)`, but will provide better
+ * error messages and is more performant at runtime because it doesn't have to
+ * try all decoders one by one.
+ */
+
+export function taggedUnion(field, mapping) {
+  var _object;
+
+  var base = object((_object = {}, _object[field] = prep(String, oneOf(Object.keys(mapping))), _object)).transform(function (o) {
+    return o[field];
+  });
+  return base.peek_UNSTABLE(function (_ref) {
+    var blob = _ref[0],
+        key = _ref[1];
+    var decoder = mapping[key];
+    return decoder.decode(blob);
+  });
+}

package/lib/utilities.d.ts

@@ -0,0 +1,34 @@
+import { Decoder } from '../Decoder';
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+export function instanceOf<T>(klass: new (...args: readonly any[]) => T): Decoder<T>;
+
+/**
+ * Lazily evaluate the given decoder. This is useful to build self-referential
+ * types for recursive data structures.
+ */
+export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;
+
+/**
+ * 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<T>(
+    mapperFn: (blob: unknown) => unknown,
+    decoder: Decoder<T>,
+): Decoder<T>;
+
+/**
+ * Rejects all inputs, and always fails with the given error message. May be
+ * useful for explicitly disallowing keys, or for testing purposes.
+ */
+export function never(msg: string): Decoder<never>;
+
+/**
+ * Alias of never().
+ */
+export function fail(msg: string): Decoder<never>;

package/lib/utilities.js

@@ -0,0 +1,75 @@
+"use strict";
+
+exports.__esModule = true;
+exports.fail = void 0;
+exports.instanceOf = instanceOf;
+exports.lazy = lazy;
+exports.never = never;
+exports.prep = prep;
+
+var _annotate = require("../annotate");
+
+var _Decoder = require("../Decoder");
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+function instanceOf(klass) {
+  return (0, _Decoder.define)(function (blob, ok, err) {
+    return blob instanceof klass ? ok(blob) : err("Must be " + // $FlowFixMe[incompatible-use] - klass.name is fine?
+    klass.name + " instance");
+  });
+}
+/**
+ * Lazily evaluate the given decoder. This is useful to build self-referential
+ * types for recursive data structures.
+ */
+
+
+function lazy(decoderFn) {
+  return (0, _Decoder.define)(function (blob) {
+    return decoderFn().decode(blob);
+  });
+}
+/**
+ * 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 (0, _Decoder.define)(function (originalInput, _, err) {
+    var blob;
+
+    try {
+      blob = mapperFn(originalInput);
+    } catch (e) {
+      return err((0, _annotate.annotate)(originalInput, e.message));
+    }
+
+    var r = decoder.decode(blob);
+    return r.ok ? r : err((0, _annotate.annotate)(originalInput, r.error.text)); //                             ^^^^^^^^^^^^^
+    //                             Annotates the _original_ input value
+    //                             (instead of echoing back blob)
+  });
+}
+/**
+ * Rejects all inputs, and always fails with the given error message. May be
+ * useful for explicitly disallowing keys, or for testing purposes.
+ */
+
+
+function never(msg) {
+  return (0, _Decoder.define)(function (_, __, err) {
+    return err(msg);
+  });
+}
+/**
+ * Alias of never().
+ */
+
+
+var fail = never;
+exports.fail = fail;

package/lib/utilities.js.flow

@@ -0,0 +1,65 @@
+// @flow strict
+
+import { annotate } from '../annotate';
+import { define } from '../Decoder';
+import type { Decoder } from '../Decoder';
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+export function instanceOf<T>(klass: Class<T>): Decoder<T> {
+    return define((blob, ok, err) =>
+        blob instanceof klass
+            ? ok(blob)
+            : err(
+                  `Must be ${
+                      // $FlowFixMe[incompatible-use] - klass.name is fine?
+                      klass.name
+                  } instance`,
+              ),
+    );
+}
+
+/**
+ * Lazily evaluate the given decoder. This is useful to build self-referential
+ * types for recursive data structures.
+ */
+export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T> {
+    return define((blob) => decoderFn().decode(blob));
+}
+
+/**
+ * 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<T>(mapperFn: (mixed) => mixed, decoder: Decoder<T>): Decoder<T> {
+    return define((originalInput, _, err) => {
+        let blob;
+        try {
+            blob = mapperFn(originalInput);
+        } catch (e) {
+            return err(annotate(originalInput, e.message));
+        }
+
+        const r = decoder.decode(blob);
+        return r.ok ? r : err(annotate(originalInput, r.error.text));
+        //                             ^^^^^^^^^^^^^
+        //                             Annotates the _original_ input value
+        //                             (instead of echoing back blob)
+    });
+}
+
+/**
+ * Rejects all inputs, and always fails with the given error message. May be
+ * useful for explicitly disallowing keys, or for testing purposes.
+ */
+export function never(msg: string): Decoder<empty> {
+    return define((_, __, err) => err(msg));
+}
+
+/**
+ * Alias of never().
+ */
+export const fail: (msg: string) => Decoder<empty> = never;

package/lib/utilities.mjs

@@ -0,0 +1,60 @@
+import { annotate } from '../annotate.mjs';
+import { define } from '../Decoder.mjs';
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+export function instanceOf(klass) {
+  return define(function (blob, ok, err) {
+    return blob instanceof klass ? ok(blob) : err("Must be " + // $FlowFixMe[incompatible-use] - klass.name is fine?
+    klass.name + " instance");
+  });
+}
+/**
+ * Lazily evaluate the given decoder. This is useful to build self-referential
+ * types for recursive data structures.
+ */
+
+export function lazy(decoderFn) {
+  return define(function (blob) {
+    return decoderFn().decode(blob);
+  });
+}
+/**
+ * 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 define(function (originalInput, _, err) {
+    var blob;
+
+    try {
+      blob = mapperFn(originalInput);
+    } catch (e) {
+      return err(annotate(originalInput, e.message));
+    }
+
+    var r = decoder.decode(blob);
+    return r.ok ? r : err(annotate(originalInput, r.error.text)); //                             ^^^^^^^^^^^^^
+    //                             Annotates the _original_ input value
+    //                             (instead of echoing back blob)
+  });
+}
+/**
+ * Rejects all inputs, and always fails with the given error message. May be
+ * useful for explicitly disallowing keys, or for testing purposes.
+ */
+
+export function never(msg) {
+  return define(function (_, __, err) {
+    return err(msg);
+  });
+}
+/**
+ * Alias of never().
+ */
+
+export var fail = never;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decoders",
-    "version": "2.0.0-beta9",
+    "version": "2.0.0",
     "description": "Elegant and battle-tested validation library for type-safe input data (for TypeScript and Flow)",
     "license": "MIT",
     "repository": {
@@ -15,30 +15,77 @@
     "main": "./index.js",
     "module": "./index.mjs",
     "keywords": [
-        "decoder",
         "decoders",
-        "guard",
-        "object",
+        "Decoder",
+        "always",
+        "and",
         "array",
-        "string",
-        "email",
-        "regex",
-        "number",
-        "integer",
         "boolean",
-        "truthy",
+        "then",
+        "compose",
+        "constant",
         "date",
-        "mapping",
+        "decode",
+        "decoder",
+        "decoders",
+        "define",
+        "describe",
         "dict",
+        "either",
+        "email",
+        "exact",
+        "fail",
+        "hardcoded",
+        "httpsUrl",
+        "inexact",
+        "instanceOf",
+        "integer",
+        "iso8601",
+        "json",
+        "jsonArray",
+        "jsonObject",
+        "lazy",
+        "map",
+        "mapping",
+        "maybe",
         "mixed",
+        "mixedarray",
+        "never",
+        "nonEmptyArray",
+        "nonEmptyString",
+        "nullable",
+        "null_",
+        "number",
+        "numericBoolean",
+        "object",
+        "oneOf",
+        "optional",
+        "poja",
+        "pojo",
+        "positiveInteger",
+        "positiveNumber",
+        "predicate",
+        "prep",
+        "regex",
+        "set",
+        "string",
+        "taggedUnion",
+        "transform",
+        "truthy",
+        "tuple",
         "tuple2",
+        "undefined_",
         "unknown",
-        "optional",
-        "nullable",
-        "maybe",
-        "compose",
-        "map",
-        "predicate"
+        "url",
+        "uuid",
+        "uuidv1",
+        "uuidv4",
+        "verify",
+        "DecodeResult",
+        "DecoderType",
+        "JSONArray",
+        "JSONObject",
+        "JSONValue"
     ],
     "githubUrl": "https://github.com/nvie/decoders",
     "sideEffects": false,

package/result.d.ts

@@ -14,26 +14,3 @@ export type Result<T, E> = Ok<T> | Err<E>;
 
 export function ok<T>(value: T): Ok<T>;
 export function err<E>(error: E): Err<E>;
-export function unwrap<T>(result: Result<T, unknown>): T;
-export function expect<T>(result: Result<T, unknown>, message: string | Error): T;
-export function dispatch<T, E, O>(
-    result: Result<T, E>,
-    okCallback: (value: T) => O,
-    errCallback: (error: E) => O,
-): O;
-export function andThen<T, E, T2>(
-    result1: Result<T, E>,
-    lazyResult2: (value: T) => Result<T2, E>,
-): Result<T2, E>;
-export function orElse<T, E, E2>(
-    result1: Result<T, E>,
-    lazyResult2: (errValue: E) => Result<T, E2>,
-): Result<T, E2>;
-export function mapOk<T, E, T2>(
-    result: Result<T, E>,
-    mapper: (value: T) => T2,
-): Result<T2, E>;
-export function mapError<T, E, E2>(
-    result: Result<T, E>,
-    mapper: (error: E) => E2,
-): Result<T, E2>;

package/result.js

@@ -1,15 +1,8 @@
 "use strict";
 
 exports.__esModule = true;
-exports.andThen = andThen;
-exports.dispatch = dispatch;
 exports.err = err;
-exports.expect = expect;
-exports.mapError = mapError;
-exports.mapOk = mapOk;
 exports.ok = ok;
-exports.orElse = orElse;
-exports.unwrap = unwrap;
 
 /**
  * Result <value> <error>
@@ -38,65 +31,4 @@ function err(error) {
     value: undefined,
     error: error
   };
-}
-/**
- * Unwrap the value from this Result instance if this is an "Ok" result.
- * Otherwise, will throw the "Err" error via a runtime exception.
- */
-
-
-function unwrap(result) {
-  if (result.ok) {
-    return result.value;
-  } else {
-    throw result.error;
-  }
-}
-
-function expect(result, message) {
-  if (result.ok) {
-    return result.value;
-  } else {
-    throw message instanceof Error ? message : new Error(message);
-  }
-}
-
-function dispatch(result, okCallback, errCallback) {
-  return result.ok ? okCallback(result.value) : errCallback(result.error);
-}
-/**
- * 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
- * the first argument.
- */
-
-
-function andThen(result1, lazyResult2) {
-  return result1.ok ? lazyResult2(result1.value) : result1;
-}
-/**
- * Like .or(), aka ||, but the second argument gets evaluated lazily only if
- * the first result is an Err result. If so, it has access to the Err value
- * from the first argument.
- */
-
-
-function orElse(result1, lazyResult2) {
-  return result1.ok ? result1 : lazyResult2(result1.error);
-}
-/**
- * Transform an Ok result. Will not touch Err results.
- */
-
-
-function mapOk(result, mapper) {
-  return result.ok ? ok(mapper(result.value)) : result;
-}
-/**
- * Transform an Err value. Will not touch Ok results.
- */
-
-
-function mapError(result, mapper) {
-  return result.ok ? result : err(mapper(result.error));
 }

package/result.js.flow

@@ -24,75 +24,3 @@ export function ok<T>(value: T): Ok<T> {
 export function err<E>(error: E): Err<E> {
     return { ok: false, value: undefined, error };
 }
-
-/**
- * Unwrap the value from this Result instance if this is an "Ok" result.
- * Otherwise, will throw the "Err" error via a runtime exception.
- */
-export function unwrap<T>(result: Result<T, mixed>): T {
-    if (result.ok) {
-        return result.value;
-    } else {
-        throw result.error;
-    }
-}
-
-export function expect<T>(result: Result<T, mixed>, message: string | Error): T {
-    if (result.ok) {
-        return result.value;
-    } else {
-        throw message instanceof Error ? message : new Error(message);
-    }
-}
-
-export function dispatch<T, E, O>(
-    result: Result<T, E>,
-    okCallback: (value: T) => O,
-    errCallback: (error: E) => O,
-): O {
-    return result.ok ? okCallback(result.value) : errCallback(result.error);
-}
-
-/**
- * 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
- * the first argument.
- */
-export function andThen<T, E, T2>(
-    result1: Result<T, E>,
-    lazyResult2: (value: T) => Result<T2, E>,
-): Result<T2, E> {
-    return result1.ok ? lazyResult2(result1.value) : result1;
-}
-
-/**
- * Like .or(), aka ||, but the second argument gets evaluated lazily only if
- * the first result is an Err result. If so, it has access to the Err value
- * from the first argument.
- */
-export function orElse<T, E, E2>(
-    result1: Result<T, E>,
-    lazyResult2: (errValue: E) => Result<T, E2>,
-): Result<T, E2> {
-    return result1.ok ? result1 : lazyResult2(result1.error);
-}
-
-/**
- * Transform an Ok result. Will not touch Err results.
- */
-export function mapOk<T, E, T2>(
-    result: Result<T, E>,
-    mapper: (value: T) => T2,
-): Result<T2, E> {
-    return result.ok ? ok(mapper(result.value)) : result;
-}
-
-/**
- * Transform an Err value. Will not touch Ok results.
- */
-export function mapError<T, E, E2>(
-    result: Result<T, E>,
-    mapper: (error: E) => E2,
-): Result<T, E2> {
-    return result.ok ? result : err(mapper(result.error));
-}