decoders 1.26.0-beta2 → 2.0.0-beta11

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>;

package/lib/booleans.js

@@ -0,0 +1,35 @@
+"use strict";
+
+exports.__esModule = true;
+exports.truthy = exports.numericBoolean = exports["boolean"] = void 0;
+
+var _Decoder = require("../Decoder");
+
+var _numbers = require("./numbers");
+
+/**
+ * Accepts and returns booleans.
+ */
+var _boolean = (0, _Decoder.define)(function (blob, ok, err) {
+  return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean');
+});
+/**
+ * Accepts anything and will return its “truth” value. Will never reject.
+ */
+
+
+exports["boolean"] = _boolean;
+var truthy = (0, _Decoder.define)(function (blob, ok, _) {
+  return ok(!!blob);
+});
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+
+exports.truthy = truthy;
+
+var numericBoolean = _numbers.number.transform(function (n) {
+  return !!n;
+});
+
+exports.numericBoolean = numericBoolean;

package/lib/booleans.js.flow

@@ -0,0 +1,22 @@
+// @flow strict
+
+import { define } from '../Decoder';
+import { number } from './numbers';
+import type { Decoder } from '../Decoder';
+
+/**
+ * Accepts and returns booleans.
+ */
+export const boolean: Decoder<boolean> = define((blob, ok, err) => {
+    return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean');
+});
+
+/**
+ * Accepts anything and will return its “truth” value. Will never reject.
+ */
+export const truthy: Decoder<boolean> = define((blob, ok, _) => ok(!!blob));
+
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+export const numericBoolean: Decoder<boolean> = number.transform((n) => !!n);

package/lib/booleans.mjs

@@ -0,0 +1,25 @@
+import { define } from '../Decoder.mjs';
+import { number } from './numbers.mjs';
+
+/**
+ * Accepts and returns booleans.
+ */
+var _boolean = define(function (blob, ok, err) {
+  return typeof blob === 'boolean' ? ok(blob) : err('Must be boolean');
+});
+/**
+ * Accepts anything and will return its “truth” value. Will never reject.
+ */
+
+
+export { _boolean as boolean };
+export var truthy = define(function (blob, ok, _) {
+  return ok(!!blob);
+});
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+
+export var numericBoolean = number.transform(function (n) {
+  return !!n;
+});

package/{ts/date.d.ts → lib/dates.d.ts}

@@ -1,4 +1,4 @@
-import { Decoder } from './types';
+import { Decoder } from '../Decoder';
 
 export const date: Decoder<Date>;
 export const iso8601: Decoder<Date>;

package/lib/dates.js

@@ -0,0 +1,44 @@
+"use strict";
+
+exports.__esModule = true;
+exports.iso8601 = exports.date = void 0;
+
+var _utils = require("../_utils");
+
+var _Decoder = require("../Decoder");
+
+var _strings = require("./strings");
+
+// 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
+var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+/**
+ * Accepts and returns `Date` instances.
+ */
+
+var date = (0, _Decoder.define)(function (blob, ok, err) {
+  var date = (0, _utils.asDate)(blob);
+  return date !== null ? ok(date) : err('Must be a Date');
+});
+/**
+ * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
+ * returns then as `Date` instances.
+ *
+ * This is very useful for working with dates in APIs: serialize them as
+ * `.toISOString()` when sending, decode them with `iso8601` when receiving.
+ */
+
+exports.date = date;
+var iso8601 = // Input itself needs to match the ISO8601 regex...
+(0, _strings.regex)(iso8601_re, 'Must be ISO8601 format').transform( // Make sure it is a _valid_ date
+function (value) {
+  var date = new Date(value);
+
+  if (isNaN(date.getTime())) {
+    throw new Error('Must be valid date/time value');
+  }
+
+  return date;
+});
+exports.iso8601 = iso8601;

package/lib/dates.js.flow

@@ -0,0 +1,40 @@
+// @flow strict
+
+import { asDate } from '../_utils';
+import { define } from '../Decoder';
+import { regex } from './strings';
+import type { Decoder } from '../Decoder';
+
+// 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
+const iso8601_re =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+/**
+ * Accepts and returns `Date` instances.
+ */
+export const date: Decoder<Date> = define((blob, ok, err) => {
+    const date = asDate(blob);
+    return date !== null ? ok(date) : err('Must be a Date');
+});
+
+/**
+ * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
+ * returns then as `Date` instances.
+ *
+ * This is very useful for working with dates in APIs: serialize them as
+ * `.toISOString()` when sending, decode them with `iso8601` when receiving.
+ */
+export const iso8601: Decoder<Date> =
+    // Input itself needs to match the ISO8601 regex...
+    regex(iso8601_re, 'Must be ISO8601 format').transform(
+        // Make sure it is a _valid_ date
+        (value: string) => {
+            const date = new Date(value);
+            if (isNaN(date.getTime())) {
+                throw new Error('Must be valid date/time value');
+            }
+            return date;
+        },
+    );

package/lib/dates.mjs

@@ -0,0 +1,34 @@
+import { asDate } from '../_utils.mjs';
+import { define } from '../Decoder.mjs';
+import { regex } from './strings.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
+var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+/**
+ * Accepts and returns `Date` instances.
+ */
+
+export var date = define(function (blob, ok, err) {
+  var date = asDate(blob);
+  return date !== null ? ok(date) : err('Must be a Date');
+});
+/**
+ * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
+ * returns then as `Date` instances.
+ *
+ * This is very useful for working with dates in APIs: serialize them as
+ * `.toISOString()` when sending, decode them with `iso8601` when receiving.
+ */
+
+export var iso8601 = // Input itself needs to match the ISO8601 regex...
+regex(iso8601_re, 'Must be ISO8601 format').transform( // Make sure it is a _valid_ date
+function (value) {
+  var date = new Date(value);
+
+  if (isNaN(date.getTime())) {
+    throw new Error('Must be valid date/time value');
+  }
+
+  return date;
+});

package/{ts → lib}/json.d.ts

@@ -1,4 +1,4 @@
-import { Decoder } from './types';
+import { Decoder } from '../Decoder';
 
 export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
 export interface JSONObject {