decoders 2.0.0-beta1 → 2.0.0-beta10

package/lib/unions.js

@@ -0,0 +1,161 @@
+"use strict";
+
+exports.__esModule = true;
+exports.either = exports.dispatch = void 0;
+exports.oneOf = oneOf;
+exports.taggedUnion = taggedUnion;
+
+var _Decoder = require("../Decoder");
+
+var _utils = require("../_utils");
+
+var _objects = require("./objects");
+
+var _utilities = require("./utilities");
+
+var EITHER_PREFIX = 'Either:\n';
+/**
+ * Indents and adds a dash in front of this (potentially multiline) string.
+ */
+
+function itemize(s) {
+  return '-' + (0, _utils.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 (0, _Decoder.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((0, _utils.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.
+ */
+
+
+var either = _either;
+/**
+ * Accepts any value that is strictly-equal (using ===) to one of the specified
+ * values.
+ */
+
+exports.either = either;
+
+function oneOf(constants) {
+  return (0, _Decoder.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.
+ *
+ *   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.
+ */
+
+
+function taggedUnion(field, mapping) {
+  var _object;
+
+  var base = (0, _objects.object)((_object = {}, _object[field] = (0, _utilities.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);
+  });
+}
+
+var dispatch = taggedUnion;
+exports.dispatch = dispatch;

package/lib/unions.js.flow

@@ -0,0 +1,158 @@
+// @flow strict
+
+import { define } from '../Decoder';
+import { indent, summarize } from '../_utils';
+import { object } from './objects';
+import { prep } from './utilities';
+import type { _Any } from '../_utils';
+import type { Decoder, DecodeResult, Scalar } from '../Decoder';
+
+const EITHER_PREFIX = 'Either:\n';
+
+/**
+ * Indents and adds a dash in front of this (potentially multiline) string.
+ */
+function itemize(s: string): string {
+    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: string): string {
+    return errText.startsWith(EITHER_PREFIX)
+        ? errText.substr(EITHER_PREFIX.length)
+        : itemize(errText);
+}
+
+// prettier-ignore
+interface EitherDecoderSignatures {
+  <A>(a: Decoder<A>): Decoder<A>;
+  <A, B>(a: Decoder<A>, b: Decoder<B>): Decoder<A | B>;
+  <A, B, C>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>): Decoder<A | B | C>;
+  <A, B, C, D>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>): Decoder<A | B | C | D>;
+  <A, B, C, D, E>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>, e: Decoder<E>): Decoder<A | B | C | D | E>;
+  <A, B, C, D, E, F>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>, e: Decoder<E>, f: Decoder<F>): Decoder<A | B | C | D | E | F>;
+  <A, B, C, D, E, F, G>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>, e: Decoder<E>, f: Decoder<F>, g: Decoder<G>): Decoder<A | B | C | D | E | F | G>;
+  <A, B, C, D, E, F, G, H>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>, e: Decoder<E>, f: Decoder<F>, g: Decoder<G>, h: Decoder<H>): Decoder<A | B | C | D | E | F | G | H>;
+  <A, B, C, D, E, F, G, H, I>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>, e: Decoder<E>, f: Decoder<F>, g: Decoder<G>, h: Decoder<H>, i: Decoder<I>): Decoder<A | B | C | D | E | F | G | H | I>;
+}
+
+function _either(...decoders: $ReadOnlyArray<Decoder<mixed>>): Decoder<mixed> {
+    if (decoders.length === 0) {
+        throw new Error('Pass at least one decoder to either()');
+    }
+
+    return define((blob, _, err) => {
+        // Collect errors here along the way
+        const errors = [];
+
+        for (let i = 0; i < decoders.length; i++) {
+            const result: DecodeResult<mixed> = decoders[i].decode(blob);
+            if (result.ok) {
+                return result;
+            } else {
+                errors.push(result.error);
+            }
+        }
+
+        // Decoding all alternatives failed, return the combined error message
+        const text =
+            EITHER_PREFIX +
+            errors.map((err) => 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 const either: EitherDecoderSignatures = (_either: _Any);
+
+/**
+ * Accepts any value that is strictly-equal (using ===) to one of the specified
+ * values.
+ */
+export function oneOf<T: Scalar>(constants: $ReadOnlyArray<T>): Decoder<T> {
+    return define((blob, ok, err) => {
+        const winner = constants.find((c) => c === blob);
+        if (winner !== undefined) {
+            return ok(winner);
+        }
+        return err(
+            `Must be one of ${constants
+                .map((value) => 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.
+ *
+ *   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<O: { +[field: string]: Decoder<_Any>, ... }>(
+    field: string,
+    mapping: O,
+): Decoder<$Values<$ObjMap<O, <T>(Decoder<T>) => T>>> {
+    const base: Decoder<string> = object({
+        [field]: prep(String, oneOf(Object.keys(mapping))),
+    }).transform((o) => o[field]);
+    return base.peek_UNSTABLE(([blob, key]) => {
+        const decoder = mapping[key];
+        return decoder.decode(blob);
+    });
+}
+
+export const dispatch: <O: { +[field: string]: Decoder<_Any>, ... }>(
+    field: string,
+    mapping: O,
+) => Decoder<$Values<$ObjMap<O, <T>(Decoder<T>) => T>>> = taggedUnion;

package/lib/unions.mjs

@@ -0,0 +1,145 @@
+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.
+ *
+ *   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);
+  });
+}
+export var dispatch = taggedUnion;

package/lib/utilities.d.ts

@@ -0,0 +1,10 @@
+import { Decoder } from '../Decoder';
+
+export function instanceOf<T>(klass: new (...args: readonly any[]) => T): Decoder<T>;
+export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;
+export function prep<T>(
+    mapperFn: (blob: unknown) => unknown,
+    decoder: Decoder<T>,
+): Decoder<T>;
+export function never(msg: string): Decoder<never>;
+export function fail(msg: string): Decoder<never>;

package/lib/utilities.js

@@ -0,0 +1,94 @@
+"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.
+ *
+ * Example:
+ *
+ * ```ts
+ * type Tree = {
+ *     value: string;
+ *     children: Array<Tree>;
+ *     //              ^^^^
+ *     //              Self-reference defining a recursive type
+ * };
+ *
+ * const treeDecoder: Decoder<Tree> = object({
+ *     value: string,
+ *     children: array(lazy(() => treeDecoder)),
+ *     //              ^^^^^^^^^^^^^^^^^^^^^^^
+ *     //              Use lazy() like this to refer to the treeDecoder which is
+ *     //              getting defined here
+ * });
+ * ```
+ */
+
+
+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,84 @@
+// @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.
+ *
+ * Example:
+ *
+ * ```ts
+ * type Tree = {
+ *     value: string;
+ *     children: Array<Tree>;
+ *     //              ^^^^
+ *     //              Self-reference defining a recursive type
+ * };
+ *
+ * const treeDecoder: Decoder<Tree> = object({
+ *     value: string,
+ *     children: array(lazy(() => treeDecoder)),
+ *     //              ^^^^^^^^^^^^^^^^^^^^^^^
+ *     //              Use lazy() like this to refer to the treeDecoder which is
+ *     //              getting defined here
+ * });
+ * ```
+ */
+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;