decoders 2.0.0-beta12 → 2.0.0-beta13

package/Decoder.mjs

@@ -12,38 +12,52 @@ function noThrow(fn) {
     }
   };
 }
+
+function format(err, formatter) {
+  var formatted = formatter(err); // Formatter functions may return a string or an error for convenience of
+  // writing them. If it already returns an Error, return it unmodified. If
+  // it returns a string, wrap it in a "Decoding error" instance.
+
+  if (typeof formatted === 'string') {
+    var _err = new Error('\n' + formatted);
+
+    _err.name = 'Decoding error';
+    return _err;
+  } else {
+    return formatted;
+  }
+}
 /**
  * Defines a new `Decoder<T>`, by implementing a custom acceptance function.
  * The function receives three arguments:
  *
  * 1. `blob` - the raw/unknown input (aka your external data)
  * 2. `ok` - Call `ok(value)` to accept the input and return ``value``
- * 3. `err` - Call `err(message)` to reject the input and use "message" in the
- *    annotation
+ * 3. `err` - Call `err(message)` to reject the input with error ``message``
  *
  * The expected return value should be a `DecodeResult<T>`, which can be
- * obtained by returning the result from the provided `ok` or `err` helper
- * functions.
+ * obtained by returning the result of calling the provided `ok` or `err`
+ * helper functions. Please note that `ok()` and `err()` don't perform side
+ * effects! You'll need to _return_ those values.
  */
 
 
-export function define(decodeFn) {
+export function define(fn) {
   /**
-   * Validates the raw/untrusted/unknown input and either accepts or rejects
-   * it.
+   * Verifies the untrusted/unknown input and either accepts or rejects it.
    *
    * Contrasted with `.verify()`, calls to `.decode()` will never fail and
    * instead return a result type.
    */
   function decode(blob) {
-    return decodeFn(blob, makeOk, function (msg) {
+    return fn(blob, makeOk, function (msg) {
       return makeErr(typeof msg === 'string' ? annotate(blob, msg) : msg);
     });
   }
   /**
-   * Verified the (raw/untrusted/unknown) input and either accepts or rejects
-   * it. When accepted, returns the decoded `T` value directly. Otherwise
-   * fail with a runtime error.
+   * Verifies the untrusted/unknown input and either accepts or rejects it.
+   * When accepted, returns a value of type `T`. Otherwise fail with
+   * a runtime error.
    */
 
 
@@ -57,26 +71,13 @@ export function define(decodeFn) {
     if (result.ok) {
       return result.value;
     } else {
-      // Formatters may return a string or an error for convenience of
-      // writing them. If it already returns an Error, throw it
-      // unmodified. If it returns a string, wrap it in a "Decoding
-      // error" instance from it and throw that.
-      var strOrErr = formatter(result.error);
-
-      if (typeof strOrErr === 'string') {
-        var _err = new Error('\n' + strOrErr);
-
-        _err.name = 'Decoding error';
-        throw _err;
-      } else {
-        throw strOrErr;
-      }
+      throw format(result.error, formatter);
     }
   }
   /**
-   * Verified the (raw/untrusted/unknown) input and either accepts or rejects
-   * it. When accepted, returns the decoded `T` value directly. Otherwise
-   * returns `undefined`.
+   * Verifies the untrusted/unknown input and either accepts or rejects it.
+   * When accepted, returns the decoded `T` value directly. Otherwise returns
+   * `undefined`.
    *
    * Use this when you're not interested in programmatically handling the
    * error message.
@@ -114,23 +115,21 @@ export function define(decodeFn) {
   /**
    * Chain together the current decoder with another.
    *
-   * First, the current decoder must accept the input. If so, it will pass
-   * the successfully decoded result to the given ``next`` function to
-   * further decide whether or not the value should get accepted or rejected.
+   * > _**NOTE:** This is an advanced, low-level, API. It's not recommended
+   * > to reach for this construct unless there is no other way. Most cases can
+   * > be covered more elegantly by `.transform()` or `.refine()` instead._
    *
-   * The argument to `.then()` is a decoding function, just like one you
-   * would pass to `define()`. The key difference with `define()` is that
-   * `define()` must always assume an ``unknown`` input, whereas with
-   * a `.then()` call the provided ``next`` function will receive a ``T`` as
-   * its input. This will allow the function to make a stronger assumption
-   * about its input.
+   * If the current decoder accepts an input, the resulting ``T`` value will
+   * get passed into the given ``next`` acceptance function to further decide
+   * whether or not the value should get accepted or rejected.
    *
-   * If it helps, you can think of `define(nextFn)` as equivalent to
-   * `unknown.then(nextFn)`.
+   * This works similar to how you would `define()` a new decoder, except
+   * that the ``blob`` param will now be ``T`` (a known type), rather than
+   * ``unknown``. This will allow the function to make a stronger assumption
+   * about its input and avoid re-refining inputs.
    *
-   * This is an advanced, low-level, decoder. It's not recommended to reach
-   * for this low-level construct when implementing custom decoders. Most
-   * cases can be covered by `.transform()` or `.refine()`.
+   * If it helps, you can think of `define(...)` as equivalent to
+   * `unknown.then(...)`.
    */
 
 

package/README.md

@@ -22,14 +22,19 @@ solve both of these problems at once.**
 ```typescript
 import { array, iso8601, number, object, optional, string } from 'decoders';
 
-// External data, for example JSON.parse()'ed from a request payload
+//
+// Incoming data at runtime
+//
 const externalData = {
     id: 123,
     name: 'Alison Roberts',
-    createdAt: '2022-01-11T12:26:37.024Z',
-    tags: ['foo', 'bar', 'qux'],
+    createdAt: '1994-01-11T12:26:37.024Z',
+    tags: ['foo', 'bar'],
 };
 
+//
+// Write the decoder (= what you expect the data to look like)
+//
 const userDecoder = object({
     id: number,
     name: string,
@@ -37,82 +42,96 @@ const userDecoder = object({
     tags: array(string),
 });
 
-// NOTE: TypeScript will automatically infer this type for the `user` variable
-// interface User {
-//     id: number;
-//     name: string;
-//     createdAt?: Date;
-//     tags: string[];
-// }
-
+//
+// Call .verify() on the incoming data
+//
 const user = userDecoder.verify(externalData);
+//    ^^^^
+//    TypeScript can automatically infer this type now:
+//
+//    {
+//      id: number;
+//      name: string;
+//      createdAt?: Date;
+//      tags: string[];
+//    }
+//
 ```
 
 ## Documentation
 
-<div id="guard"></div>
-<div id="primitives"></div>
-<div id="compositions"></div>
+<div id="$DecoderType"></div>
+<div id="DecodeResult"></div>
+<div id="Decoder"></div>
+<div id="DecoderType"></div>
+<div id="Guard"></div>
+<div id="JSONArray"></div>
+<div id="JSONObject"></div>
+<div id="JSONValue"></div>
+<div id="Scalar"></div>
+<div id="adding-predicates"></div>
+<div id="always"></div>
+<div id="anyNumber"></div>
+<div id="array"></div>
+<div id="boolean"></div>
 <div id="building-custom-decoders"></div>
-<div id="number"></div>
-<div id="integer"></div>
-<div id="positiveNumber"></div>
-<div id="positiveInteger"></div>
-<div id="string"></div>
-<div id="nonEmptyString"></div>
-<div id="regex"></div>
+<div id="compose"></div>
+<div id="compositions"></div>
+<div id="constant"></div>
+<div id="date"></div>
+<div id="define"></div>
+<div id="describe"></div>
+<div id="dict"></div>
+<div id="either"></div>
 <div id="email"></div>
-<div id="url"></div>
+<div id="exact"></div>
+<div id="fail"></div>
+<div id="guard"></div>
+<div id="hardcoded"></div>
 <div id="httpsUrl"></div>
-<div id="uuid"></div>
-<div id="uuidv1"></div>
-<div id="uuidv4"></div>
-<div id="boolean"></div>
-<div id="string"></div>
-<div id="truthy"></div>
-<div id="numericBoolean"></div>
-<div id="date"></div>
+<div id="inexact"></div>
+<div id="instanceOf"></div>
+<div id="integer"></div>
 <div id="iso8601"></div>
-<div id="null_"></div>
-<div id="undefined_"></div>
-<div id="constant"></div>
-<div id="always"></div>
-<div id="hardcoded"></div>
-<div id="never"></div>
-<div id="fail"></div>
-<div id="unknown"></div>
-<div id="mixed"></div>
-<div id="optional"></div>
-<div id="nullable"></div>
+<div id="json"></div>
+<div id="jsonArray"></div>
+<div id="jsonObject"></div>
+<div id="lazy"></div>
+<div id="mapping"></div>
 <div id="maybe"></div>
-<div id="array"></div>
+<div id="mixed"></div>
+<div id="never"></div>
 <div id="nonEmptyArray"></div>
-<div id="poja"></div>
-<div id="tuple"></div>
-<div id="set"></div>
+<div id="nonEmptyString"></div>
+<div id="null_"></div>
+<div id="nullable"></div>
+<div id="number"></div>
+<div id="numericBoolean"></div>
 <div id="object"></div>
-<div id="exact"></div>
-<div id="inexact"></div>
-<div id="pojo"></div>
-<div id="dict"></div>
-<div id="mapping"></div>
-<div id="json"></div>
-<div id="jsonObject"></div>
-<div id="jsonArray"></div>
-<div id="either"></div>
-<div id="taggedUnion"></div>
 <div id="oneOf"></div>
-<div id="instanceOf"></div>
-<div id="transform"></div>
-<div id="compose"></div>
+<div id="optional"></div>
+<div id="poja"></div>
+<div id="pojo"></div>
+<div id="positiveInteger"></div>
+<div id="positiveNumber"></div>
 <div id="predicate"></div>
 <div id="prep"></div>
-<div id="describe"></div>
-<div id="lazy"></div>
+<div id="primitives"></div>
+<div id="regex"></div>
+<div id="set"></div>
+<div id="string"></div>
+<div id="taggedUnion"></div>
 <div id="the-difference-between-object-exact-and-inexact"></div>
-<div id="building-custom-decoders"></div>
+<div id="transform"></div>
 <div id="transformation"></div>
-<div id="adding-predicates"></div>
+<div id="truthy"></div>
+<div id="tuple"></div>
+<div id="undefined_"></div>
+<div id="unknown"></div>
+<div id="url"></div>
+<div id="uuid"></div>
+<div id="uuidv1"></div>
+<div id="uuidv4"></div>
 
 Documentation for v1 can be found
 [here](https://github.com/nvie/decoders/tree/v1.25.5#readme).  

package/format.d.ts

@@ -1,4 +1,6 @@
 import { Annotation } from './annotate';
 
-export function formatInline(ann: Annotation): string;
-export function formatShort(ann: Annotation): string;
+export type Formatter = (err: Annotation) => string | Error;
+
+export const formatInline: Formatter;
+export const formatShort: Formatter;

package/format.js.flow

@@ -3,6 +3,8 @@
 import { summarize as _summarize, asDate, INDENT, indent, isMultiline } from './_utils';
 import type { Annotation, ArrayAnnotation, ObjectAnnotation } from './annotate';
 
+export type Formatter = (err: Annotation) => string | Error;
+
 function serializeString(s: string, width: number = 80): string {
     // Full string
     // Abbreviated to $maxlen i.e. "Vincent Driess..." [truncated]

package/index.d.ts

@@ -17,7 +17,7 @@ export { array, nonEmptyArray, poja, set, tuple } from './lib/arrays';
 export { boolean, numericBoolean, truthy } from './lib/booleans';
 export { date, iso8601 } from './lib/dates';
 export { dict, exact, inexact, mapping, object, pojo } from './lib/objects';
-export { either, oneOf, taggedUnion, dispatch } from './lib/unions';
+export { either, oneOf, taggedUnion } from './lib/unions';
 export {
     email,
     httpsUrl,

package/index.js

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.uuidv4 = exports.uuidv1 = exports.uuid = exports.url = exports.unknown = exports.undefined_ = exports.tuple = exports.truthy = exports.taggedUnion = exports.string = exports.set = exports.regex = exports.prep = exports.positiveNumber = exports.positiveInteger = exports.pojo = exports.poja = exports.optional = exports.oneOf = exports.object = exports.numericBoolean = exports.number = exports.nullable = exports.null_ = exports.nonEmptyString = exports.nonEmptyArray = exports.never = exports.mixed = exports.maybe = exports.mapping = exports.lazy = exports.jsonObject = exports.jsonArray = exports.json = exports.iso8601 = exports.integer = exports.instanceOf = exports.inexact = exports.httpsUrl = exports.hardcoded = exports.fail = exports.exact = exports.email = exports.either = exports.dispatch = exports.dict = exports.define = exports.date = exports.constant = exports["boolean"] = exports.array = exports.anyNumber = exports.always = void 0;
+exports.uuidv4 = exports.uuidv1 = exports.uuid = exports.url = exports.unknown = exports.undefined_ = exports.tuple = exports.truthy = exports.taggedUnion = exports.string = exports.set = exports.regex = exports.prep = exports.positiveNumber = exports.positiveInteger = exports.pojo = exports.poja = exports.optional = exports.oneOf = exports.object = exports.numericBoolean = exports.number = exports.nullable = exports.null_ = exports.nonEmptyString = exports.nonEmptyArray = exports.never = exports.mixed = exports.maybe = exports.mapping = exports.lazy = exports.jsonObject = exports.jsonArray = exports.json = exports.iso8601 = exports.integer = exports.instanceOf = exports.inexact = exports.httpsUrl = exports.hardcoded = exports.fail = exports.exact = exports.email = exports.either = exports.dict = exports.define = exports.date = exports.constant = exports["boolean"] = exports.array = exports.anyNumber = exports.always = void 0;
 
 var _Decoder = require("./Decoder");
 
@@ -53,7 +53,6 @@ var _unions = require("./lib/unions");
 exports.either = _unions.either;
 exports.oneOf = _unions.oneOf;
 exports.taggedUnion = _unions.taggedUnion;
-exports.dispatch = _unions.dispatch;
 
 var _strings = require("./lib/strings");
 

package/index.js.flow

@@ -21,7 +21,7 @@ export { array, nonEmptyArray, poja, set, tuple } from './lib/arrays';
 export { boolean, numericBoolean, truthy } from './lib/booleans';
 export { date, iso8601 } from './lib/dates';
 export { dict, exact, inexact, mapping, object, pojo } from './lib/objects';
-export { either, oneOf, taggedUnion, dispatch } from './lib/unions';
+export { either, oneOf, taggedUnion } from './lib/unions';
 export {
     email,
     httpsUrl,

package/index.mjs

@@ -4,7 +4,7 @@ export { array, nonEmptyArray, poja, set, tuple } from './lib/arrays.mjs';
 export { boolean, numericBoolean, truthy } from './lib/booleans.mjs';
 export { date, iso8601 } from './lib/dates.mjs';
 export { dict, exact, inexact, mapping, object, pojo } from './lib/objects.mjs';
-export { either, oneOf, taggedUnion, dispatch } from './lib/unions.mjs';
+export { either, oneOf, taggedUnion } from './lib/unions.mjs';
 export { email, httpsUrl, nonEmptyString, regex, string, url, uuid, uuidv1, uuidv4 } from './lib/strings.mjs';
 export { fail, instanceOf, lazy, never, prep } from './lib/utilities.mjs';
 export { anyNumber, integer, number, positiveInteger, positiveNumber } from './lib/numbers.mjs';

package/lib/arrays.d.ts

@@ -2,11 +2,33 @@
 
 import { Decoder } 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<unknown[]>;
+
+/**
+ * Accepts arrays of whatever the given decoder accepts.
+ */
 export function array<T>(decoder: Decoder<T>): Decoder<T[]>;
+
+/**
+ * Like `array()`, but will reject arrays with 0 elements.
+ */
 export function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<[T, ...T[]]>;
+
+/**
+ * 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>>;
 
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
 export function tuple<A>(a: Decoder<A>): Decoder<[A]>;
 export function tuple<A, B>(a: Decoder<A>, b: Decoder<B>): Decoder<[A, B]>;
 export function tuple<A, B, C>(

package/lib/arrays.js

@@ -101,10 +101,6 @@ var ntuple = function ntuple(n) {
 }; // 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];
@@ -133,6 +129,11 @@ function _tuple() {
     }
   });
 }
+/**
+ * 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

@@ -97,7 +97,7 @@ const ntuple = (n: number) =>
     poja.refine((arr) => arr.length === n, `Must be a ${n}-tuple`);
 
 // prettier-ignore
-interface TupleFuncSignature {
+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]>;
@@ -106,10 +106,6 @@ interface TupleFuncSignature {
     <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;
@@ -135,4 +131,8 @@ function _tuple(...decoders: $ReadOnlyArray<Decoder<mixed>>): Decoder<Array<mixe
     });
 }
 
-export const tuple: TupleFuncSignature = (_tuple: _Any);
+/**
+ * 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

@@ -87,10 +87,6 @@ var ntuple = function ntuple(n) {
 }; // 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];
@@ -119,5 +115,10 @@ function _tuple() {
     }
   });
 }
+/**
+ * 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

@@ -1,38 +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,
+    defaultValue: (() => V) | V,
 ): Decoder<NonNullable<T> | V>;
 export function optional<T, V>(
     decoder: Decoder<T>,
-    defaultValue: V,
+    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,
+    defaultValue: (() => V) | V,
 ): Decoder<NonNullable<T> | V>;
 export function nullable<T, V>(
     decoder: Decoder<T>,
-    defaultValue: V,
+    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,
+    defaultValue: (() => V) | V,
 ): Decoder<NonNullable<T> | V>;
 export function maybe<T, V>(
     decoder: Decoder<T>,
-    defaultValue: V,
+    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): 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): Decoder<T>;
-export const mixed: Decoder<unknown>;
+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

@@ -29,22 +29,26 @@ var undefined_or_null = (0, _Decoder.define)(function (blob, ok, err) {
   err('Must be undefined or null');
 });
 
-/**
- * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
- */
 function _maybeish(emptyCase) {
   function _inner(decoder
   /* defaultValue */
   ) {
-    var _arguments = arguments;
     var rv = (0, _unions.either)(emptyCase, decoder);
-    return (// If a default value is provided...
-      arguments.length >= 2 ? // ...then return the default value
-      rv.transform(function (value) {
-        return value != null ? value : _arguments[1];
-      }) : // Otherwise the "normal" empty case
-      rv
-    );
+
+    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;
@@ -101,7 +105,13 @@ function constant(value) {
 
 
 function always(value) {
-  return (0, _Decoder.define)(function (blob
+  return (0, _Decoder.define)(typeof value === 'function' ? function (blob
+  /* ignored */
+  , ok, _) {
+    return (// $FlowFixMe[incompatible-use]
+      ok(value())
+    );
+  } : function (blob
   /* ignored */
   , ok, _) {
     return ok(value);