decoders 2.0.0-beta11 → 2.0.0-beta12

package/Decoder.d.ts

@@ -11,7 +11,7 @@ export type DecodeFn<T, I = unknown> = (
 ) => DecodeResult<T>;
 
 export interface Decoder<T> {
-    verify(blob: unknown, formatterFn?: (ann: Annotation) => string): T;
+    verify(blob: unknown, formatterFn?: (ann: Annotation) => string | Error): T;
     value(blob: unknown): T | undefined;
     decode(blob: unknown): DecodeResult<T>;
     refine<N extends T>(predicate: (value: T) => value is N, msg: string): Decoder<N>;

package/Decoder.js

@@ -64,10 +64,20 @@ function define(decodeFn) {
     if (result.ok) {
       return result.value;
     } else {
-      var _err = new Error('\n' + formatter(result.error));
+      // 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);
 
-      _err.name = 'Decoding error';
-      throw _err;
+      if (typeof strOrErr === 'string') {
+        var _err = new Error('\n' + strOrErr);
+
+        _err.name = 'Decoding error';
+        throw _err;
+      } else {
+        throw strOrErr;
+      }
     }
   }
   /**

package/Decoder.js.flow

@@ -32,7 +32,7 @@ export type DecodeFn<T, I = mixed> = (
 export type DecoderType<D> = $Call<<T>(Decoder<T>) => T, D>;
 
 export type Decoder<T> = {|
-    verify(blob: mixed, formatterFn?: (Annotation) => string): T,
+    verify(blob: mixed, formatterFn?: (Annotation) => string | Error): T,
     value(blob: mixed): T | void,
     decode(blob: mixed): DecodeResult<T>,
     refine(predicateFn: (value: T) => boolean, errmsg: string): Decoder<T>,
@@ -88,14 +88,26 @@ export function define<T>(decodeFn: DecodeFn<T>): Decoder<T> {
      * it. When accepted, returns the decoded `T` value directly. Otherwise
      * fail with a runtime error.
      */
-    function verify(blob: mixed, formatter: (Annotation) => string = formatInline): T {
+    function verify(
+        blob: mixed,
+        formatter: (Annotation) => string | Error = formatInline,
+    ): T {
         const result = decode(blob);
         if (result.ok) {
             return result.value;
         } else {
-            const err = new Error('\n' + formatter(result.error));
-            err.name = 'Decoding error';
-            throw err;
+            // 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.
+            const strOrErr = formatter(result.error);
+            if (typeof strOrErr === 'string') {
+                const err = new Error('\n' + strOrErr);
+                err.name = 'Decoding error';
+                throw err;
+            } else {
+                throw strOrErr;
+            }
         }
     }
 

package/Decoder.mjs

@@ -57,10 +57,20 @@ export function define(decodeFn) {
     if (result.ok) {
       return result.value;
     } else {
-      var _err = new Error('\n' + formatter(result.error));
+      // 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);
 
-      _err.name = 'Decoding error';
-      throw _err;
+      if (typeof strOrErr === 'string') {
+        var _err = new Error('\n' + strOrErr);
+
+        _err.name = 'Decoding error';
+        throw _err;
+      } else {
+        throw strOrErr;
+      }
     }
   }
   /**

package/lib/basics.d.ts

@@ -3,8 +3,32 @@ 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 optional<T, V extends Scalar>(
+    decoder: Decoder<T>,
+    defaultValue: V,
+): Decoder<NonNullable<T> | V>;
+export function optional<T, V>(
+    decoder: Decoder<T>,
+    defaultValue: V,
+): Decoder<NonNullable<T> | V>;
 export function nullable<T>(decoder: Decoder<T>): Decoder<T | null>;
+export function nullable<T, V extends Scalar>(
+    decoder: Decoder<T>,
+    defaultValue: V,
+): Decoder<NonNullable<T> | V>;
+export function nullable<T, V>(
+    decoder: Decoder<T>,
+    defaultValue: V,
+): Decoder<NonNullable<T> | V>;
 export function maybe<T>(decoder: Decoder<T>): Decoder<T | null | undefined>;
+export function maybe<T, V extends Scalar>(
+    decoder: Decoder<T>,
+    defaultValue: V,
+): Decoder<NonNullable<T> | V>;
+export function maybe<T, V>(
+    decoder: Decoder<T>,
+    defaultValue: V,
+): Decoder<NonNullable<T> | V>;
 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>;

package/lib/basics.js

@@ -3,12 +3,7 @@
 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;
+exports.unknown = exports.undefined_ = exports.optional = exports.nullable = exports.null_ = exports.mixed = exports.maybe = exports.hardcoded = void 0;
 
 var _Decoder = require("../Decoder");
 
@@ -28,40 +23,70 @@ 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_;
+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');
+});
 
-function optional(decoder) {
-  return (0, _unions.either)(undefined_, decoder);
+/**
+ * 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
+    );
+  }
+
+  return _inner;
 }
 /**
  * Accepts whatever the given decoder accepts, or `null`.
+ *
+ * If a default value is explicitly provided, return that instead in the `null`
+ * case.
  */
 
 
-function nullable(decoder) {
-  return (0, _unions.either)(null_, decoder);
-}
+var nullable = _maybeish(null_);
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
 
-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');
-});
+
+exports.nullable = nullable;
+
+var optional = _maybeish(undefined_);
 /**
  * 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.
  */
 
-function maybe(decoder) {
-  return (0, _unions.either)(undefined_or_null, decoder);
-}
+
+exports.optional = optional;
+
+var maybe = _maybeish(undefined_or_null);
 /**
  * Accepts only the given constant value.
  */
 
 
+exports.maybe = maybe;
+
 function constant(value) {
   return (0, _Decoder.define)(function (blob, ok, err) {
     return blob === value ? ok(value) : err("Must be constant " + String(value));

package/lib/basics.js.flow

@@ -2,6 +2,7 @@
 
 import { define } from '../Decoder';
 import { either } from './unions';
+import type { _Any } from '../_utils';
 import type { Decoder, Scalar } from '../Decoder';
 
 /**
@@ -18,33 +19,60 @@ export const undefined_: Decoder<void> = define((blob, ok, err) =>
     blob === undefined ? ok(blob) : err('Must be undefined'),
 );
 
+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'),
+);
+
+interface Maybeish<E> {
+    <T>(decoder: Decoder<T>): Decoder<E | T>;
+    <T, V>(decoder: Decoder<T>, defaultValue: V): Decoder<$NonMaybeType<T> | V>;
+}
+
 /**
- * Accepts whatever the given decoder accepts, or `undefined`.
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
  */
-export function optional<T>(decoder: Decoder<T>): Decoder<void | T> {
-    return either(undefined_, decoder);
+function _maybeish<E>(emptyCase: Decoder<E>): Maybeish<E> {
+    function _inner(decoder /* defaultValue */) {
+        const rv = either(emptyCase, decoder);
+        return (
+            // If a default value is provided...
+            arguments.length >= 2
+                ? // ...then return the default value
+                  rv.transform((value) => value ?? arguments[1])
+                : // Otherwise the "normal" empty case
+                  rv
+        );
+    }
+
+    return (_inner: _Any);
 }
 
 /**
  * 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<null | T> {
-    return either(null_, decoder);
-}
+export const nullable: Maybeish<null> = _maybeish(null_);
 
-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 `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
+export const optional: Maybeish<void> = _maybeish(undefined_);
 
 /**
  * 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 | void> {
-    return either(undefined_or_null, decoder);
-}
+export const maybe: Maybeish<null | void> = _maybeish(undefined_or_null);
 
 /**
  * Accepts only the given constant value.

package/lib/basics.mjs

@@ -14,31 +14,56 @@ export var null_ = define(function (blob, ok, err) {
 export var undefined_ = define(function (blob, ok, err) {
   return blob === undefined ? ok(blob) : err('Must be undefined');
 });
+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 `undefined`.
+ * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
  */
+function _maybeish(emptyCase) {
+  function _inner(decoder
+  /* defaultValue */
+  ) {
+    var _arguments = arguments;
+    var rv = 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
+    );
+  }
 
-export function optional(decoder) {
-  return either(undefined_, decoder);
+  return _inner;
 }
 /**
  * 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(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');
-});
+
+export var nullable = _maybeish(null_);
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
+
+export var optional = _maybeish(undefined_);
 /**
  * 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(decoder) {
-  return either(undefined_or_null, decoder);
-}
+export var maybe = _maybeish(undefined_or_null);
 /**
  * Accepts only the given constant value.
  */

package/lib/objects.js.flow

@@ -2,8 +2,8 @@
 
 import { annotateObject, merge, updateText } from '../annotate';
 import { define } from '../Decoder';
-import type { _Any } from '../_utils';
 import type { Annotation } from '../annotate';
+import type { _Any as AnyDecoder } from '../_utils';
 import type { Decoder, DecodeResult } from '../Decoder';
 
 function subtract(xs: Set<string>, ys: Set<string>): Set<string> {
@@ -52,7 +52,7 @@ export const pojo: Decoder<{| [string]: mixed |}> = define((blob, ok, err) =>
  * 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]: Decoder<_Any>, ... }>(
+export function object<O: { +[field: string]: AnyDecoder, ... }>(
     decodersByKey: O,
 ): Decoder<$ObjMap<O, <T>(Decoder<T>) => T>> {
     // Compute this set at decoder definition time
@@ -134,7 +134,7 @@ export function object<O: { +[field: string]: Decoder<_Any>, ... }>(
  * Like `object()`, but will reject inputs that contain extra fields that are
  * not specified explicitly.
  */
-export function exact<O: { +[field: string]: Decoder<_Any>, ... }>(
+export function exact<O: { +[field: string]: AnyDecoder, ... }>(
     decodersByKey: O,
 ): Decoder<$ObjMap<$Exact<O>, <T>(Decoder<T>) => T>> {
     // Compute this set at decoder definition time
@@ -160,7 +160,7 @@ export function exact<O: { +[field: string]: Decoder<_Any>, ... }>(
  * 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]: Decoder<_Any> }>(
+export function inexact<O: { +[field: string]: AnyDecoder }>(
     decodersByKey: O,
 ): Decoder<$ObjMap<O, <T>(Decoder<T>) => T> & { +[string]: mixed }> {
     return pojo.then((plainObj) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decoders",
-    "version": "2.0.0-beta11",
+    "version": "2.0.0-beta12",
     "description": "Elegant and battle-tested validation library for type-safe input data (for TypeScript and Flow)",
     "license": "MIT",
     "repository": {