decoders 2.0.0-beta1 → 2.0.0-beta10

package/lib/arrays.js

@@ -0,0 +1,138 @@
+"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
+
+
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
+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));
+    }
+  });
+}
+
+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 TupleFuncSignature {
+    <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]>;
+}
+
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
+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));
+        }
+    });
+}
+
+export const tuple: TupleFuncSignature = (_tuple: _Any);

package/lib/arrays.mjs

@@ -0,0 +1,123 @@
+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
+
+
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
+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));
+    }
+  });
+}
+
+export var tuple = _tuple;

package/lib/basics.d.ts

@@ -0,0 +1,14 @@
+import { Decoder, Scalar } from '../Decoder';
+
+export const null_: Decoder<null>;
+export const undefined_: Decoder<undefined>;
+export function optional<T>(decoder: Decoder<T>): Decoder<T | undefined>;
+export function nullable<T>(decoder: Decoder<T>): Decoder<T | null>;
+export function maybe<T>(decoder: Decoder<T>): Decoder<T | null | undefined>;
+export function constant<T extends Scalar>(value: T): Decoder<T>;
+export function always<T extends Scalar>(value: T): Decoder<T>;
+export function always<T>(value: T): Decoder<T>;
+export function hardcoded<T extends Scalar>(value: T): Decoder<T>;
+export function hardcoded<T>(value: T): Decoder<T>;
+export const mixed: Decoder<unknown>;
+export const unknown: Decoder<unknown>;

package/lib/basics.js

@@ -0,0 +1,109 @@
+"use strict";
+
+exports.__esModule = true;
+exports.always = always;
+exports.constant = constant;
+exports.hardcoded = void 0;
+exports.maybe = maybe;
+exports.null_ = exports.mixed = void 0;
+exports.nullable = nullable;
+exports.optional = optional;
+exports.unknown = exports.undefined_ = 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');
+});
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ */
+
+exports.undefined_ = undefined_;
+
+function optional(decoder) {
+  return (0, _unions.either)(undefined_, decoder);
+}
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ */
+
+
+function nullable(decoder) {
+  return (0, _unions.either)(null_, decoder);
+}
+
+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');
+});
+/**
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
+ */
+
+function maybe(decoder) {
+  return (0, _unions.either)(undefined_or_null, decoder);
+}
+/**
+ * Accepts only the given constant value.
+ */
+
+
+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)(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;

package/lib/basics.js.flow

@@ -0,0 +1,85 @@
+// @flow strict
+
+import { define } from '../Decoder';
+import { either } from './unions';
+import type { Decoder, Scalar } from '../Decoder';
+
+/**
+ * Accepts and returns only the literal `null` value.
+ */
+export const null_: Decoder<null> = define((blob, ok, err) =>
+    blob === null ? ok(blob) : err('Must be null'),
+);
+
+/**
+ * Accepts and returns only the literal `undefined` value.
+ */
+export const undefined_: Decoder<void> = define((blob, ok, err) =>
+    blob === undefined ? ok(blob) : err('Must be undefined'),
+);
+
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ */
+export function optional<T>(decoder: Decoder<T>): Decoder<void | T> {
+    return either(undefined_, decoder);
+}
+
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ */
+export function nullable<T>(decoder: Decoder<T>): Decoder<null | T> {
+    return either(null_, decoder);
+}
+
+const undefined_or_null: Decoder<null | void> = define((blob, ok, err) =>
+    blob === undefined || blob === null
+        ? ok(blob)
+        : // Combine error message into a single line for readability
+          err('Must be undefined or null'),
+);
+
+/**
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
+ */
+export function maybe<T>(decoder: Decoder<T>): Decoder<T | null | void> {
+    return either(undefined_or_null, decoder);
+}
+
+/**
+ * Accepts only the given constant value.
+ */
+export function constant<T: Scalar>(value: T): Decoder<T> {
+    return define((blob, ok, err) =>
+        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.
+ */
+export function always<T>(value: T): Decoder<T> {
+    return define((blob /* ignored */, ok, _) => ok(value));
+}
+
+/**
+ * Alias of always.
+ */
+export const hardcoded: <T>(T) => Decoder<T> = 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.
+ */
+export const unknown: Decoder<mixed> = define((blob, ok, _) => ok(blob));
+
+/**
+ * Alias of unknown.
+ */
+export const mixed: Decoder<mixed> = unknown;

package/lib/basics.mjs

@@ -0,0 +1,85 @@
+import { define } from '../Decoder.mjs';
+import { either } from './unions.mjs';
+
+/**
+ * Accepts and returns only the literal `null` value.
+ */
+export var null_ = define(function (blob, ok, err) {
+  return blob === null ? ok(blob) : err('Must be null');
+});
+/**
+ * Accepts and returns only the literal `undefined` value.
+ */
+
+export var undefined_ = define(function (blob, ok, err) {
+  return blob === undefined ? ok(blob) : err('Must be undefined');
+});
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ */
+
+export function optional(decoder) {
+  return either(undefined_, decoder);
+}
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ */
+
+export function nullable(decoder) {
+  return either(null_, decoder);
+}
+var undefined_or_null = 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');
+});
+/**
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
+ */
+
+export function maybe(decoder) {
+  return either(undefined_or_null, decoder);
+}
+/**
+ * Accepts only the given constant value.
+ */
+
+export function constant(value) {
+  return 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.
+ */
+
+export function always(value) {
+  return define(function (blob
+  /* ignored */
+  , ok, _) {
+    return ok(value);
+  });
+}
+/**
+ * Alias of always.
+ */
+
+export 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.
+ */
+
+export var unknown = define(function (blob, ok, _) {
+  return ok(blob);
+});
+/**
+ * Alias of unknown.
+ */
+
+export var mixed = unknown;

package/{ts/boolean.d.ts → lib/booleans.d.ts}

@@ -1,4 +1,4 @@
-import { Decoder } from '../_types';
+import { Decoder } from '../Decoder';
 
 export const boolean: Decoder<boolean>;
 export const truthy: Decoder<boolean>;