decoders 2.0.0-beta1 → 2.0.0-beta13

package/lib/arrays.js

@@ -0,0 +1,139 @@
+"use strict";
+
+exports.__esModule = true;
+exports.array = array;
+exports.nonEmptyArray = nonEmptyArray;
+exports.poja = void 0;
+exports.set = set;
+exports.tuple = void 0;
+
+var _annotate = require("../annotate");
+
+var _Decoder = require("../Decoder");
+
+/**
+ * Accepts any array, but doesn't validate its items further.
+ *
+ * "poja" means "plain old JavaScript array", a play on `pojo()`.
+ */
+var poja = (0, _Decoder.define)(function (blob, ok, err) {
+  if (!Array.isArray(blob)) {
+    return err('Must be an array');
+  }
+
+  return 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
+ */
+
+exports.poja = poja;
+
+function all(items, blobs, // TODO: Make this less ugly
+ok, err) {
+  var results = [];
+
+  for (var index = 0; index < items.length; ++index) {
+    var result = items[index];
+
+    if (result.ok) {
+      results.push(result.value);
+    } else {
+      var ann = result.error; // Rewrite the annotation to include the index information, and inject it into the original blob
+
+      var clone = [].concat(blobs);
+      clone.splice(index, 1, (0, _annotate.annotate)(ann, ann.text ? ann.text + " (at index " + index + ")" : "index " + index));
+      return err((0, _annotate.annotate)(clone));
+    }
+  }
+
+  return ok(results);
+}
+/**
+ * Accepts arrays of whatever the given decoder accepts.
+ */
+
+
+function array(decoder) {
+  return poja.then(function (blobs, ok, err) {
+    var results = blobs.map(decoder.decode);
+    return all(results, blobs, ok, err);
+  });
+}
+/**
+ * Like `array()`, but will reject arrays with 0 elements.
+ */
+
+
+function nonEmptyArray(decoder) {
+  return array(decoder).refine(function (arr) {
+    return arr.length > 0;
+  }, 'Must be non-empty array');
+}
+/**
+ * Similar to `array()`, but returns the result as an [ES6
+ * Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+ */
+
+
+function set(decoder) {
+  return array(decoder).transform(function (items) {
+    return new Set(items);
+  });
+}
+
+var ntuple = function ntuple(n) {
+  return poja.refine(function (arr) {
+    return arr.length === n;
+  }, "Must be a " + n + "-tuple");
+}; // prettier-ignore
+
+
+function _tuple() {
+  for (var _len = arguments.length, decoders = new Array(_len), _key = 0; _key < _len; _key++) {
+    decoders[_key] = arguments[_key];
+  }
+
+  return ntuple(decoders.length).then(function (blobs, ok, err) {
+    var allOk = true;
+    var rvs = decoders.map(function (decoder, i) {
+      var blob = blobs[i];
+      var result = decoder.decode(blob);
+
+      if (result.ok) {
+        return result.value;
+      } else {
+        allOk = false;
+        return result.error;
+      }
+    });
+
+    if (allOk) {
+      return ok(rvs);
+    } else {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err((0, _annotate.annotate)(rvs));
+    }
+  });
+}
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
+
+
+var tuple = _tuple;
+exports.tuple = tuple;

package/lib/arrays.js.flow

@@ -0,0 +1,138 @@
+// @flow strict
+
+import { annotate } from '../annotate';
+import { define } from '../Decoder';
+import type { _Any } from '../_utils';
+import type { Annotation } from '../annotate';
+import type { Decoder, DecodeResult } from '../Decoder';
+
+/**
+ * Accepts any array, but doesn't validate its items further.
+ *
+ * "poja" means "plain old JavaScript array", a play on `pojo()`.
+ */
+export const poja: Decoder<Array<mixed>> = define((blob, ok, err) => {
+    if (!Array.isArray(blob)) {
+        return err('Must be an array');
+    }
+    return 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>,
+
+    // TODO: Make this less ugly
+    ok: (Array<T>) => DecodeResult<Array<T>>,
+    err: (Annotation) => DecodeResult<Array<T>>,
+): DecodeResult<Array<T>> {
+    const results: Array<T> = [];
+    for (let index = 0; index < items.length; ++index) {
+        const result = items[index];
+        if (result.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}`,
+                ),
+            );
+
+            return err(annotate(clone));
+        }
+    }
+    return ok(results);
+}
+
+/**
+ * Accepts arrays of whatever the given decoder accepts.
+ */
+export function array<T>(decoder: Decoder<T>): Decoder<Array<T>> {
+    return poja.then((blobs: $ReadOnlyArray<mixed>, ok, err) => {
+        const results = blobs.map(decoder.decode);
+        return all(results, blobs, ok, err);
+    });
+}
+
+/**
+ * Like `array()`, but will reject arrays with 0 elements.
+ */
+export function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<Array<T>> {
+    return array(decoder).refine((arr) => arr.length > 0, 'Must be non-empty array');
+}
+
+/**
+ * Similar to `array()`, but returns the result as an [ES6
+ * Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+ */
+export function set<T>(decoder: Decoder<T>): Decoder<Set<T>> {
+    return array(decoder).transform((items) => new Set(items));
+}
+
+const ntuple = (n: number) =>
+    poja.refine((arr) => arr.length === n, `Must be a ${n}-tuple`);
+
+// prettier-ignore
+interface TupleT {
+    <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]>;
+}
+
+function _tuple(...decoders: $ReadOnlyArray<Decoder<mixed>>): Decoder<Array<mixed>> {
+    return ntuple(decoders.length).then((blobs, ok, err) => {
+        let allOk = true;
+
+        const rvs = decoders.map((decoder, i) => {
+            const blob = blobs[i];
+            const result = decoder.decode(blob);
+            if (result.ok) {
+                return result.value;
+            } else {
+                allOk = false;
+                return result.error;
+            }
+        });
+
+        if (allOk) {
+            return ok(rvs);
+        } else {
+            // If a decoder error has happened while unwrapping all the
+            // results, try to construct a good error message
+            return err(annotate(rvs));
+        }
+    });
+}
+
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
+export const tuple: TupleT = (_tuple: _Any);

package/lib/arrays.mjs

@@ -0,0 +1,124 @@
+import { annotate } from '../annotate.mjs';
+import { define } from '../Decoder.mjs';
+
+/**
+ * Accepts any array, but doesn't validate its items further.
+ *
+ * "poja" means "plain old JavaScript array", a play on `pojo()`.
+ */
+export var poja = define(function (blob, ok, err) {
+  if (!Array.isArray(blob)) {
+    return err('Must be an array');
+  }
+
+  return 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(items, blobs, // TODO: Make this less ugly
+ok, err) {
+  var results = [];
+
+  for (var index = 0; index < items.length; ++index) {
+    var result = items[index];
+
+    if (result.ok) {
+      results.push(result.value);
+    } else {
+      var ann = result.error; // Rewrite the annotation to include the index information, and inject it into the original blob
+
+      var clone = [].concat(blobs);
+      clone.splice(index, 1, annotate(ann, ann.text ? ann.text + " (at index " + index + ")" : "index " + index));
+      return err(annotate(clone));
+    }
+  }
+
+  return ok(results);
+}
+/**
+ * Accepts arrays of whatever the given decoder accepts.
+ */
+
+
+export function array(decoder) {
+  return poja.then(function (blobs, ok, err) {
+    var results = blobs.map(decoder.decode);
+    return all(results, blobs, ok, err);
+  });
+}
+/**
+ * Like `array()`, but will reject arrays with 0 elements.
+ */
+
+export function nonEmptyArray(decoder) {
+  return array(decoder).refine(function (arr) {
+    return arr.length > 0;
+  }, 'Must be non-empty array');
+}
+/**
+ * Similar to `array()`, but returns the result as an [ES6
+ * Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+ */
+
+export function set(decoder) {
+  return array(decoder).transform(function (items) {
+    return new Set(items);
+  });
+}
+
+var ntuple = function ntuple(n) {
+  return poja.refine(function (arr) {
+    return arr.length === n;
+  }, "Must be a " + n + "-tuple");
+}; // prettier-ignore
+
+
+function _tuple() {
+  for (var _len = arguments.length, decoders = new Array(_len), _key = 0; _key < _len; _key++) {
+    decoders[_key] = arguments[_key];
+  }
+
+  return ntuple(decoders.length).then(function (blobs, ok, err) {
+    var allOk = true;
+    var rvs = decoders.map(function (decoder, i) {
+      var blob = blobs[i];
+      var result = decoder.decode(blob);
+
+      if (result.ok) {
+        return result.value;
+      } else {
+        allOk = false;
+        return result.error;
+      }
+    });
+
+    if (allOk) {
+      return ok(rvs);
+    } else {
+      // If a decoder error has happened while unwrapping all the
+      // results, try to construct a good error message
+      return err(annotate(rvs));
+    }
+  });
+}
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
+
+
+export var tuple = _tuple;

package/lib/basics.d.ts

@@ -0,0 +1,93 @@
+import { Decoder, Scalar } from '../Decoder';
+
+/**
+ * Accepts and returns only the literal `null` value.
+ */
+export const null_: Decoder<null>;
+
+/**
+ * Accepts and returns only the literal `undefined` value.
+ */
+export const undefined_: Decoder<undefined>;
+
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
+export function optional<T>(decoder: Decoder<T>): Decoder<T | undefined>;
+export function optional<T, V extends Scalar>(
+    decoder: Decoder<T>,
+    defaultValue: (() => V) | V,
+): Decoder<NonNullable<T> | V>;
+export function optional<T, V>(
+    decoder: Decoder<T>,
+    defaultValue: (() => V) | V,
+): Decoder<NonNullable<T> | V>;
+
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ *
+ * If a default value is explicitly provided, return that instead in the `null`
+ * case.
+ */
+export function nullable<T>(decoder: Decoder<T>): Decoder<T | null>;
+export function nullable<T, V extends Scalar>(
+    decoder: Decoder<T>,
+    defaultValue: (() => V) | V,
+): Decoder<NonNullable<T> | V>;
+export function nullable<T, V>(
+    decoder: Decoder<T>,
+    defaultValue: (() => V) | V,
+): Decoder<NonNullable<T> | V>;
+
+/**
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `null`/`undefined` case.
+ */
+export function maybe<T>(decoder: Decoder<T>): Decoder<T | null | undefined>;
+export function maybe<T, V extends Scalar>(
+    decoder: Decoder<T>,
+    defaultValue: (() => V) | V,
+): Decoder<NonNullable<T> | V>;
+export function maybe<T, V>(
+    decoder: Decoder<T>,
+    defaultValue: (() => V) | V,
+): Decoder<NonNullable<T> | V>;
+
+/**
+ * Accepts only the given constant value.
+ */
+export function constant<T extends Scalar>(value: T): Decoder<T>;
+
+/**
+ * Accepts anything, completely ignores it, and always returns the provided
+ * value instead.
+ *
+ * This is useful to manually add extra fields to object decoders.
+ */
+export function always<T extends Scalar>(value: T): Decoder<T>;
+export function always<T>(value: (() => T) | T): Decoder<T>;
+
+/**
+ * Alias of always.
+ */
+export function hardcoded<T extends Scalar>(value: T): Decoder<T>;
+export function hardcoded<T>(value: (() => T) | T): Decoder<T>;
+
+/**
+ * Accepts anything and returns it unchanged.
+ *
+ * Useful for situation in which you don't know or expect a specific type. Of
+ * course, the downside is that you won't know the type of the value statically
+ * and you'll have to further refine it yourself.
+ */
+export const unknown: Decoder<unknown>;
+
+/**
+ * Alias of unknown.
+ */
+export const mixed: Decoder<unknown>;

package/lib/basics.js

@@ -0,0 +1,144 @@
+"use strict";
+
+exports.__esModule = true;
+exports.always = always;
+exports.constant = constant;
+exports.unknown = exports.undefined_ = exports.optional = exports.nullable = exports.null_ = exports.mixed = exports.maybe = exports.hardcoded = void 0;
+
+var _Decoder = require("../Decoder");
+
+var _unions = require("./unions");
+
+/**
+ * Accepts and returns only the literal `null` value.
+ */
+var null_ = (0, _Decoder.define)(function (blob, ok, err) {
+  return blob === null ? ok(blob) : err('Must be null');
+});
+/**
+ * Accepts and returns only the literal `undefined` value.
+ */
+
+exports.null_ = null_;
+var undefined_ = (0, _Decoder.define)(function (blob, ok, err) {
+  return blob === undefined ? ok(blob) : err('Must be undefined');
+});
+exports.undefined_ = undefined_;
+var undefined_or_null = (0, _Decoder.define)(function (blob, ok, err) {
+  return blob === undefined || blob === null ? ok(blob) : // Combine error message into a single line for readability
+  err('Must be undefined or null');
+});
+
+function _maybeish(emptyCase) {
+  function _inner(decoder
+  /* defaultValue */
+  ) {
+    var rv = (0, _unions.either)(emptyCase, decoder);
+
+    if ( // If a default value is provided...
+    arguments.length >= 2) {
+      // ...then return the default value
+      var _defaultValue = arguments[1];
+
+      var _defaultValue2 = typeof _defaultValue === 'function' ? _defaultValue() : _defaultValue;
+
+      return rv.transform(function (value) {
+        return value != null ? value : _defaultValue2;
+      });
+    } else {
+      // Otherwise the "normal" empty case
+      return rv;
+    }
+  }
+
+  return _inner;
+}
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ *
+ * If a default value is explicitly provided, return that instead in the `null`
+ * case.
+ */
+
+
+var nullable = _maybeish(null_);
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
+
+
+exports.nullable = nullable;
+
+var optional = _maybeish(undefined_);
+/**
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `null`/`undefined` case.
+ */
+
+
+exports.optional = optional;
+
+var maybe = _maybeish(undefined_or_null);
+/**
+ * Accepts only the given constant value.
+ */
+
+
+exports.maybe = maybe;
+
+function constant(value) {
+  return (0, _Decoder.define)(function (blob, ok, err) {
+    return blob === value ? ok(value) : err("Must be constant " + String(value));
+  });
+}
+/**
+ * Accepts anything, completely ignores it, and always returns the provided
+ * value instead.
+ *
+ * This is useful to manually add extra fields to object decoders.
+ */
+
+
+function always(value) {
+  return (0, _Decoder.define)(typeof value === 'function' ? function (blob
+  /* ignored */
+  , ok, _) {
+    return (// $FlowFixMe[incompatible-use]
+      ok(value())
+    );
+  } : function (blob
+  /* ignored */
+  , ok, _) {
+    return ok(value);
+  });
+}
+/**
+ * Alias of always.
+ */
+
+
+var hardcoded = always;
+/**
+ * Accepts anything and returns it unchanged.
+ *
+ * Useful for situation in which you don't know or expect a specific type. Of
+ * course, the downside is that you won't know the type of the value statically
+ * and you'll have to further refine it yourself.
+ */
+
+exports.hardcoded = hardcoded;
+var unknown = (0, _Decoder.define)(function (blob, ok, _) {
+  return ok(blob);
+});
+/**
+ * Alias of unknown.
+ */
+
+exports.unknown = unknown;
+var mixed = unknown;
+exports.mixed = mixed;