decoders 2.0.0-beta9 → 2.0.0

package/lib/strings.js

@@ -0,0 +1,101 @@
+"use strict";
+
+exports.__esModule = true;
+exports.nonEmptyString = exports.httpsUrl = exports.email = void 0;
+exports.regex = regex;
+exports.uuidv4 = exports.uuidv1 = exports.uuid = exports.url = exports.string = void 0;
+
+var _Decoder = require("../Decoder");
+
+var _unions = require("./unions");
+
+var _utilities = require("./utilities");
+
+/** Match groups in this regex:
+ * \1 - the scheme
+ * \2 - the username/password (optional)
+ * \3 - the host
+ * \4 - the port (optional)
+ * \5 - the path (optional)
+ */
+var url_re = /^([A-Za-z]{3,9}(?:[+][A-Za-z]{3,9})?):\/\/(?:([-;:&=+$,\w]+)@)?(?:([A-Za-z0-9.-]+)(?::([0-9]{2,5}))?)(\/(?:[-+~%/.,\w]*)?(?:\?[-+=&;%@.,\w]*)?(?:#[.,!/\w]*)?)?$/;
+/**
+ * Accepts and returns strings.
+ */
+
+var string = (0, _Decoder.define)(function (blob, ok, err) {
+  return typeof blob === 'string' ? ok(blob) : err('Must be string');
+});
+/**
+ * Like `string`, but will reject the empty string or strings containing only whitespace.
+ */
+
+exports.string = string;
+var nonEmptyString = regex(/\S/, 'Must be non-empty string');
+/**
+ * Accepts and returns strings that match the given regular expression.
+ */
+
+exports.nonEmptyString = nonEmptyString;
+
+function regex(regex, msg) {
+  return string.refine(function (s) {
+    return regex.test(s);
+  }, msg);
+}
+/**
+ * Accepts and returns strings that are syntactically valid email addresses.
+ * (This will not mean that the email address actually exist.)
+ */
+
+
+var email = regex( // The almost perfect email regex, taken from https://emailregex.com/
+/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, 'Must be email');
+/**
+ * Accepts strings that are valid URLs, returns the value as a URL instance.
+ */
+
+exports.email = email;
+var url = (0, _unions.either)(regex(url_re, 'Must be URL').transform(function (value) {
+  return new URL(value);
+}), (0, _utilities.instanceOf)(URL));
+/**
+ * Accepts strings that are valid URLs, but only HTTPS ones. Returns the value
+ * as a URL instance.
+ */
+
+exports.url = url;
+var httpsUrl = url.refine(function (value) {
+  return value.protocol === 'https:';
+}, 'Must be an HTTPS URL');
+/**
+ * Accepts strings that are valid
+ * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
+ * (universally unique identifier).
+ */
+
+exports.httpsUrl = httpsUrl;
+var uuid = regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, 'Must be uuid');
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv1](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_%28date-time_and_MAC_address%29)
+ * strings.
+ */
+
+exports.uuid = uuid;
+var uuidv1 = // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)
+uuid.refine(function (value) {
+  return value[14] === '1';
+}, 'Must be uuidv1');
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_%28random%29)
+ * strings.
+ */
+
+exports.uuidv1 = uuidv1;
+var uuidv4 = // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
+uuid.refine(function (value) {
+  return value[14] === '4';
+}, 'Must be uuidv4');
+exports.uuidv4 = uuidv4;

package/lib/strings.js.flow

@@ -0,0 +1,90 @@
+// @flow strict
+
+import { define } from '../Decoder';
+import { either } from './unions';
+import { instanceOf } from './utilities';
+import type { Decoder } from '../Decoder';
+
+/** Match groups in this regex:
+ * \1 - the scheme
+ * \2 - the username/password (optional)
+ * \3 - the host
+ * \4 - the port (optional)
+ * \5 - the path (optional)
+ */
+const url_re =
+    /^([A-Za-z]{3,9}(?:[+][A-Za-z]{3,9})?):\/\/(?:([-;:&=+$,\w]+)@)?(?:([A-Za-z0-9.-]+)(?::([0-9]{2,5}))?)(\/(?:[-+~%/.,\w]*)?(?:\?[-+=&;%@.,\w]*)?(?:#[.,!/\w]*)?)?$/;
+
+/**
+ * Accepts and returns strings.
+ */
+export const string: Decoder<string> = define((blob, ok, err) =>
+    typeof blob === 'string' ? ok(blob) : err('Must be string'),
+);
+
+/**
+ * Like `string`, but will reject the empty string or strings containing only whitespace.
+ */
+export const nonEmptyString: Decoder<string> = regex(/\S/, 'Must be non-empty string');
+
+/**
+ * Accepts and returns strings that match the given regular expression.
+ */
+export function regex(regex: RegExp, msg: string): Decoder<string> {
+    return string.refine((s) => regex.test(s), msg);
+}
+
+/**
+ * Accepts and returns strings that are syntactically valid email addresses.
+ * (This will not mean that the email address actually exist.)
+ */
+export const email: Decoder<string> = regex(
+    // The almost perfect email regex, taken from https://emailregex.com/
+    /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/,
+    'Must be email',
+);
+
+/**
+ * Accepts strings that are valid URLs, returns the value as a URL instance.
+ */
+export const url: Decoder<URL> = either(
+    regex(url_re, 'Must be URL').transform((value) => new URL(value)),
+    instanceOf(URL),
+);
+
+/**
+ * Accepts strings that are valid URLs, but only HTTPS ones. Returns the value
+ * as a URL instance.
+ */
+export const httpsUrl: Decoder<URL> = url.refine(
+    (value) => value.protocol === 'https:',
+    'Must be an HTTPS URL',
+);
+
+/**
+ * Accepts strings that are valid
+ * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
+ * (universally unique identifier).
+ */
+export const uuid: Decoder<string> = regex(
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    'Must be uuid',
+);
+
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv1](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_%28date-time_and_MAC_address%29)
+ * strings.
+ */
+export const uuidv1: Decoder<string> =
+    // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)
+    uuid.refine((value) => value[14] === '1', 'Must be uuidv1');
+
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_%28random%29)
+ * strings.
+ */
+export const uuidv4: Decoder<string> =
+    // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
+    uuid.refine((value) => value[14] === '4', 'Must be uuidv4');

package/lib/strings.mjs

@@ -0,0 +1,82 @@
+import { define } from '../Decoder.mjs';
+import { either } from './unions.mjs';
+import { instanceOf } from './utilities.mjs';
+
+/** Match groups in this regex:
+ * \1 - the scheme
+ * \2 - the username/password (optional)
+ * \3 - the host
+ * \4 - the port (optional)
+ * \5 - the path (optional)
+ */
+var url_re = /^([A-Za-z]{3,9}(?:[+][A-Za-z]{3,9})?):\/\/(?:([-;:&=+$,\w]+)@)?(?:([A-Za-z0-9.-]+)(?::([0-9]{2,5}))?)(\/(?:[-+~%/.,\w]*)?(?:\?[-+=&;%@.,\w]*)?(?:#[.,!/\w]*)?)?$/;
+/**
+ * Accepts and returns strings.
+ */
+
+export var string = define(function (blob, ok, err) {
+  return typeof blob === 'string' ? ok(blob) : err('Must be string');
+});
+/**
+ * Like `string`, but will reject the empty string or strings containing only whitespace.
+ */
+
+export var nonEmptyString = regex(/\S/, 'Must be non-empty string');
+/**
+ * Accepts and returns strings that match the given regular expression.
+ */
+
+export function regex(regex, msg) {
+  return string.refine(function (s) {
+    return regex.test(s);
+  }, msg);
+}
+/**
+ * Accepts and returns strings that are syntactically valid email addresses.
+ * (This will not mean that the email address actually exist.)
+ */
+
+export var email = regex( // The almost perfect email regex, taken from https://emailregex.com/
+/^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, 'Must be email');
+/**
+ * Accepts strings that are valid URLs, returns the value as a URL instance.
+ */
+
+export var url = either(regex(url_re, 'Must be URL').transform(function (value) {
+  return new URL(value);
+}), instanceOf(URL));
+/**
+ * Accepts strings that are valid URLs, but only HTTPS ones. Returns the value
+ * as a URL instance.
+ */
+
+export var httpsUrl = url.refine(function (value) {
+  return value.protocol === 'https:';
+}, 'Must be an HTTPS URL');
+/**
+ * Accepts strings that are valid
+ * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
+ * (universally unique identifier).
+ */
+
+export var uuid = regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, 'Must be uuid');
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv1](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_%28date-time_and_MAC_address%29)
+ * strings.
+ */
+
+export var uuidv1 = // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)
+uuid.refine(function (value) {
+  return value[14] === '1';
+}, 'Must be uuidv1');
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_%28random%29)
+ * strings.
+ */
+
+export var uuidv4 = // https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
+uuid.refine(function (value) {
+  return value[14] === '4';
+}, 'Must be uuidv4');

package/lib/unions.d.ts

@@ -0,0 +1,55 @@
+import { Decoder, DecoderType, Scalar } from '../Decoder';
+
+export type Values<T extends object> = T[keyof T];
+
+export type DecoderTypes<T> = T extends ReadonlyArray<Decoder<infer U>> ? U : never;
+
+/**
+ * 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 function either<T extends ReadonlyArray<Decoder<any>>>(
+    ...args: T
+): Decoder<DecoderTypes<T>>;
+
+/**
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
+ */
+export function oneOf<T extends Scalar>(constants: readonly T[]): Decoder<T>;
+
+/**
+ * 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<O extends { [key: string]: Decoder<any> }>(
+    field: string,
+    mapping: O,
+): Decoder<Values<{ [key in keyof O]: DecoderType<O[key]> }>>;

package/lib/unions.js

@@ -0,0 +1,160 @@
+"use strict";
+
+exports.__esModule = true;
+exports.either = 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.
+ *
+ * ```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.
+ */
+
+
+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);
+  });
+}

package/{core/either.js.flow → lib/unions.js.flow}

@@ -1,10 +1,11 @@
 // @flow strict
 
-import { annotate } from '../annotate';
-import { err, ok } from '../result';
+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 '../_types';
+import type { Decoder, DecodeResult, Scalar } from '../Decoder';
 
 const EITHER_PREFIX = 'Either:\n';
 
@@ -47,7 +48,7 @@ function nest(errText: string): string {
 }
 
 // prettier-ignore
-interface EitherDecoderSignatures {
+interface EitherT {
   <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>;
@@ -64,12 +65,12 @@ function _either(...decoders: $ReadOnlyArray<Decoder<mixed>>): Decoder<mixed> {
         throw new Error('Pass at least one decoder to either()');
     }
 
-    return (blob: mixed) => {
+    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](blob);
+            const result: DecodeResult<mixed> = decoders[i].decode(blob);
             if (result.ok) {
                 return result;
             } else {
@@ -81,25 +82,74 @@ function _either(...decoders: $ReadOnlyArray<Decoder<mixed>>): Decoder<mixed> {
         const text =
             EITHER_PREFIX +
             errors.map((err) => nest(summarize(err).join('\n'))).join('\n');
-        return err(annotate(blob, text));
-    };
+        return err(text);
+    });
 }
 
-export const either: EitherDecoderSignatures = (_either: _Any);
+/**
+ * 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: EitherT = (_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 (blob: mixed) => {
+    return define((blob, ok, err) => {
         const winner = constants.find((c) => c === blob);
         if (winner !== undefined) {
             return ok(winner);
         }
         return err(
-            annotate(
-                blob,
-                `Must be one of ${constants
-                    .map((value) => JSON.stringify(value))
-                    .join(', ')}`,
-            ),
+            `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.
+ *
+ * ```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<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);
+    });
 }