decoders 2.1.0 → 2.2.0-test2

package/lib/objects.js.flow

@@ -1,238 +0,0 @@
-// @flow strict
-
-import { annotateObject, merge, updateText } from '../annotate';
-import { define } from '../Decoder';
-import { subtract } from '../_utils';
-import type { Annotation } from '../annotate';
-import type { _Any as AnyDecoder } from '../_utils';
-import type { Decoder, DecodeResult } from '../Decoder';
-
-/**
- * Accepts any "plain old JavaScript object", but doesn't validate its keys or
- * values further.
- */
-export const pojo: Decoder<{| [string]: mixed |}> = define((blob, ok, err) =>
-    blob !== null &&
-    blob !== undefined &&
-    typeof blob === 'object' &&
-    // This still seems to be the only reliable way to determine whether
-    // something is a pojo... ¯\_(ツ)_/¯
-    // $FlowFixMe[method-unbinding]
-    Object.prototype.toString.call(blob) === '[object Object]'
-        ? ok(
-              // NOTE:
-              // Since Flow 0.98, typeof o === 'object' refines to
-              //     {| +[string]: mixed |}
-              // instead of
-              //     {| [string]: mixed |}
-              //
-              // For rationale, see https://github.com/facebook/flow/issues/7685.
-              // In this case, we don't want to output a read-only version of
-              // the object 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 Object to a writeable one in ES6 seems
-              // to be to use object-spread. (Going off this benchmark:
-              // https://thecodebarbarian.com/object-assign-vs-object-spread.html)
-              // $FlowFixMe[incompatible-variance]
-              blob,
-          )
-        : err('Must be an object'),
-);
-
-/**
- * Accepts objects with fields matching the given decoders. Extra fields that
- * exist on the input object are ignored and will not be returned.
- */
-export function object<O: { +[field: string]: AnyDecoder, ... }>(
-    decodersByKey: O,
-): Decoder<$ObjMap<O, <T>(Decoder<T>) => T>> {
-    // Compute this set at decoder definition time
-    const knownKeys = new Set(Object.keys(decodersByKey));
-
-    return pojo.then((plainObj, ok, err) => {
-        const actualKeys = new Set(Object.keys(plainObj));
-
-        // At this point, "missingKeys" will also include all fields that may
-        // validly be optional. We'll let the underlying decoder decide and
-        // remove the key from this missing set if the decoder accepts the
-        // value.
-        const missingKeys = subtract(knownKeys, actualKeys);
-
-        let record = {};
-        let errors: { [key: string]: Annotation } | null = null;
-
-        Object.keys(decodersByKey).forEach((key) => {
-            const decoder = decodersByKey[key];
-            const rawValue = plainObj[key];
-            const result: DecodeResult<mixed> = decoder.decode(rawValue);
-
-            if (result.ok) {
-                const value = result.value;
-                if (value !== undefined) {
-                    record[key] = value;
-                }
-
-                // If this succeeded, remove the key from the missing keys
-                // tracker
-                missingKeys.delete(key);
-            } else {
-                const ann = result.error;
-
-                // Keep track of the annotation, but don't return just yet. We
-                // want to collect more error information.
-                if (rawValue === undefined) {
-                    // Explicitly add it to the missing set if the value is
-                    // undefined.  This covers explicit undefineds to be
-                    // treated the same as implicit undefineds (aka missing
-                    // keys).
-                    missingKeys.add(key);
-                } else {
-                    if (errors === null) {
-                        errors = {};
-                    }
-                    errors[key] = ann;
-                }
-            }
-        });
-
-        // Deal with errors now. There are two classes of errors we want to
-        // report.  First of all, we want to report any inline errors in this
-        // object.  Lastly, any fields that are missing should be annotated on
-        // the outer object itself.
-        if (errors || missingKeys.size > 0) {
-            let objAnn = annotateObject(plainObj);
-
-            if (errors) {
-                objAnn = merge(objAnn, errors);
-            }
-
-            if (missingKeys.size > 0) {
-                const errMsg = Array.from(missingKeys)
-                    .map((key) => `"${key}"`)
-                    .join(', ');
-                const pluralized = missingKeys.size > 1 ? 'keys' : 'key';
-                objAnn = updateText(objAnn, `Missing ${pluralized}: ${errMsg}`);
-            }
-
-            return err(objAnn);
-        }
-
-        return ok(record);
-    });
-}
-
-/**
- * Like `object()`, but will reject inputs that contain extra fields that are
- * not specified explicitly.
- */
-export function exact<O: { +[field: string]: AnyDecoder, ... }>(
-    decodersByKey: O,
-): Decoder<$ObjMap<$Exact<O>, <T>(Decoder<T>) => T>> {
-    // Compute this set at decoder definition time
-    const allowedKeys = new Set(Object.keys(decodersByKey));
-
-    // Check the inputted object for any unexpected extra keys
-    const checked = pojo.reject((plainObj) => {
-        const actualKeys = new Set(Object.keys(plainObj));
-        const extraKeys = subtract(actualKeys, allowedKeys);
-        return extraKeys.size > 0
-            ? `Unexpected extra keys: ${Array.from(extraKeys).join(', ')}`
-            : // Don't reject
-              null;
-    });
-
-    // Defer to the "object" decoder for doing the real decoding work.  Since
-    // we made sure there are no superfluous keys in this structure, it's now
-    // safe to force-cast it to an $Exact<> type.
-    return checked.then(object(decodersByKey).decode);
-}
-
-/**
- * Like `object()`, but will pass through any extra fields on the input object
- * unvalidated that will thus be of `unknown` type statically.
- */
-export function inexact<O: { +[field: string]: AnyDecoder }>(
-    decodersByKey: O,
-): Decoder<$ObjMap<O, <T>(Decoder<T>) => T> & { +[string]: mixed }> {
-    return pojo.then((plainObj) => {
-        const allkeys = new Set(Object.keys(plainObj));
-        const decoder = object(decodersByKey).transform(
-            (safepart: $ObjMap<O, <T>(Decoder<T>) => T>) => {
-                const safekeys = new Set(Object.keys(decodersByKey));
-
-                // To account for hard-coded keys that aren't part of the input
-                safekeys.forEach((k) => allkeys.add(k));
-
-                const rv = {};
-                allkeys.forEach((k) => {
-                    if (safekeys.has(k)) {
-                        const value = safepart[k];
-                        if (value !== undefined) {
-                            rv[k] = value;
-                        }
-                    } else {
-                        rv[k] = plainObj[k];
-                    }
-                });
-                return rv;
-            },
-        );
-        return decoder.decode(plainObj);
-    });
-}
-
-/**
- * Accepts objects where all values match the given decoder, and returns the
- * result as a `Record<string, T>`.
- *
- * The main difference between `object()` and `dict()` is that you'd typically
- * use `object()` if this is a record-like object, where all field names are
- * known and the values are heterogeneous. Whereas with `dict()` the keys are
- * typically dynamic and the values homogeneous, like in a dictionary,
- * a lookup table, or a cache.
- */
-export function dict<T>(decoder: Decoder<T>): Decoder<{ [string]: T }> {
-    return pojo.then((plainObj, ok, err) => {
-        let rv: { [key: string]: T } = {};
-        let errors: { [key: string]: Annotation } | null = null;
-
-        Object.keys(plainObj).forEach((key: string) => {
-            const value = plainObj[key];
-            const result = decoder.decode(value);
-            if (result.ok) {
-                if (errors === null) {
-                    rv[key] = result.value;
-                }
-            } else {
-                rv = {}; // Clear the success value so it can get garbage collected early
-                if (errors === null) {
-                    errors = {};
-                }
-                errors[key] = result.error;
-            }
-        });
-
-        if (errors !== null) {
-            return err(merge(annotateObject(plainObj), errors));
-        } else {
-            return ok(rv);
-        }
-    });
-}
-
-/**
- * Similar to `dict()`, but returns the result as a `Map<string, T>` (an [ES6
- * Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map))
- * instead.
- */
-export function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>> {
-    return dict(decoder).transform(
-        (obj) =>
-            new Map(
-                // This is effectively Object.entries(obj), but in a way that Flow
-                // will know the types are okay
-                Object.keys(obj).map((key) => [key, obj[key]]),
-            ),
-    );
-}

package/lib/objects.mjs

@@ -1,128 +0,0 @@
-import { annotateObject, merge, updateText } from '../annotate.mjs'
-import { define } from '../Decoder.mjs'
-import { subtract } from '../_utils.mjs'
-
-export var pojo = define(function (blob, ok, err) {
-  return blob !== null && blob !== undefined && typeof blob === 'object' && Object.prototype.toString.call(blob) === '[object Object]' ? ok(blob) : err('Must be an object')
-})
-
-export function object(decodersByKey) {
-  var knownKeys = new Set(Object.keys(decodersByKey))
-  return pojo.then(function (plainObj, ok, err) {
-    var actualKeys = new Set(Object.keys(plainObj))
-    var missingKeys = subtract(knownKeys, actualKeys)
-    var record = {}
-    var errors = null
-    Object.keys(decodersByKey).forEach(function (key) {
-      var decoder = decodersByKey[key]
-      var rawValue = plainObj[key]
-      var result = decoder.decode(rawValue)
-      if (result.ok) {
-        var value = result.value
-        if (value !== undefined) {
-          record[key] = value
-        }
-        missingKeys['delete'](key)
-      } else {
-        var ann = result.error
-        if (rawValue === undefined) {
-          missingKeys.add(key)
-        } else {
-          if (errors === null) {
-            errors = {}
-          }
-          errors[key] = ann
-        }
-      }
-    })
-    if (errors || missingKeys.size > 0) {
-      var objAnn = annotateObject(plainObj)
-      if (errors) {
-        objAnn = merge(objAnn, errors)
-      }
-      if (missingKeys.size > 0) {
-        var errMsg = Array.from(missingKeys)
-          .map(function (key) {
-            return '"' + key + '"'
-          })
-          .join(', ')
-        var pluralized = missingKeys.size > 1 ? 'keys' : 'key'
-        objAnn = updateText(objAnn, 'Missing ' + pluralized + ': ' + errMsg)
-      }
-      return err(objAnn)
-    }
-    return ok(record)
-  })
-}
-
-export function exact(decodersByKey) {
-  var allowedKeys = new Set(Object.keys(decodersByKey))
-  var checked = pojo.reject(function (plainObj) {
-    var actualKeys = new Set(Object.keys(plainObj))
-    var extraKeys = subtract(actualKeys, allowedKeys)
-    return extraKeys.size > 0 ? 'Unexpected extra keys: ' + Array.from(extraKeys).join(', ') : null
-  })
-  return checked.then(object(decodersByKey).decode)
-}
-
-export function inexact(decodersByKey) {
-  return pojo.then(function (plainObj) {
-    var allkeys = new Set(Object.keys(plainObj))
-    var decoder = object(decodersByKey).transform(function (safepart) {
-      var safekeys = new Set(Object.keys(decodersByKey))
-      safekeys.forEach(function (k) {
-        return allkeys.add(k)
-      })
-      var rv = {}
-      allkeys.forEach(function (k) {
-        if (safekeys.has(k)) {
-          var value = safepart[k]
-          if (value !== undefined) {
-            rv[k] = value
-          }
-        } else {
-          rv[k] = plainObj[k]
-        }
-      })
-      return rv
-    })
-    return decoder.decode(plainObj)
-  })
-}
-
-export function dict(decoder) {
-  return pojo.then(function (plainObj, ok, err) {
-    var rv = {}
-    var errors = null
-    Object.keys(plainObj).forEach(function (key) {
-      var value = plainObj[key]
-      var result = decoder.decode(value)
-      if (result.ok) {
-        if (errors === null) {
-          rv[key] = result.value
-        }
-      } else {
-        rv = {}
-        if (errors === null) {
-          errors = {}
-        }
-        errors[key] = result.error
-      }
-    })
-    if (errors !== null) {
-      return err(merge(annotateObject(plainObj), errors))
-    } else {
-      return ok(rv)
-    }
-  })
-}
-
-export function mapping(decoder) {
-  return dict(decoder).transform(function (obj) {
-    return new Map(
-      Object.keys(obj).map(function (key) {
-        return [key, obj[key]]
-      })
-    )
-  })
-}

package/lib/strings.d.ts

@@ -1,54 +0,0 @@
-import { Decoder } from '../Decoder';
-
-/**
- * Accepts and returns strings.
- */
-export const string: Decoder<string>;
-
-/**
- * Like `string`, but will reject the empty string or strings containing only whitespace.
- */
-export const nonEmptyString: Decoder<string>;
-
-/**
- * Accepts and returns strings that match the given regular expression.
- */
-export function regex(regex: RegExp, msg: string): Decoder<string>;
-
-/**
- * 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>;
-
-/**
- * Accepts strings that are valid URLs, returns the value as a URL instance.
- */
-export const url: Decoder<URL>;
-
-/**
- * Accepts strings that are valid URLs, but only HTTPS ones. Returns the value
- * as a URL instance.
- */
-export const httpsUrl: Decoder<URL>;
-
-/**
- * Accepts strings that are valid
- * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
- * (universally unique identifier).
- */
-export const uuid: Decoder<string>;
-
-/**
- * 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>;
-
-/**
- * Like `uuid`, but only accepts
- * [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_%28random%29)
- * strings.
- */
-export const uuidv4: Decoder<string>;

package/lib/strings.js

@@ -1,54 +0,0 @@
-'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')
-
-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]*)?)?$/
-
-var string = (0, _Decoder.define)(function (blob, ok, err) {
-  return typeof blob === 'string' ? ok(blob) : err('Must be string')
-})
-
-exports.string = string
-var nonEmptyString = regex(/\S/, 'Must be non-empty string')
-
-exports.nonEmptyString = nonEmptyString
-function regex(regex, msg) {
-  return string.refine(function (s) {
-    return regex.test(s)
-  }, msg)
-}
-
-var email = regex(/^(([^<>()[\]\\.,;:\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')
-
-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)
-)
-
-exports.url = url
-var httpsUrl = url.refine(function (value) {
-  return value.protocol === 'https:'
-}, 'Must be an HTTPS URL')
-
-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')
-
-exports.uuid = uuid
-var uuidv1 = uuid.refine(function (value) {
-  return value[14] === '1'
-}, 'Must be uuidv1')
-
-exports.uuidv1 = uuidv1
-var uuidv4 = uuid.refine(function (value) {
-  return value[14] === '4'
-}, 'Must be uuidv4')
-exports.uuidv4 = uuidv4

package/lib/strings.js.flow

@@ -1,90 +0,0 @@
-// @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

@@ -1,40 +0,0 @@
-import { define } from '../Decoder.mjs'
-import { either } from './unions.mjs'
-import { instanceOf } from './utilities.mjs'
-
-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]*)?)?$/
-
-export var string = define(function (blob, ok, err) {
-  return typeof blob === 'string' ? ok(blob) : err('Must be string')
-})
-
-export var nonEmptyString = regex(/\S/, 'Must be non-empty string')
-
-export function regex(regex, msg) {
-  return string.refine(function (s) {
-    return regex.test(s)
-  }, msg)
-}
-
-export var email = regex(/^(([^<>()[\]\\.,;:\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')
-
-export var url = either(
-  regex(url_re, 'Must be URL').transform(function (value) {
-    return new URL(value)
-  }),
-  instanceOf(URL)
-)
-
-export var httpsUrl = url.refine(function (value) {
-  return value.protocol === 'https:'
-}, 'Must be an HTTPS URL')
-
-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')
-
-export var uuidv1 = uuid.refine(function (value) {
-  return value[14] === '1'
-}, 'Must be uuidv1')
-
-export var uuidv4 = uuid.refine(function (value) {
-  return value[14] === '4'
-}, 'Must be uuidv4')

package/lib/unions.d.ts

@@ -1,55 +0,0 @@
-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 Record<string, Decoder<any>>>(
-    field: string,
-    mapping: O,
-): Decoder<Values<{ [key in keyof O]: DecoderType<O[key]> }>>;