decoders 2.0.0-beta1 → 2.0.0-beta13

package/_utils.d.ts

@@ -0,0 +1,9 @@
+import { Annotation } from './annotate';
+
+export function asDate(value: unknown): Date | null;
+export function isMultiline(s: string): boolean;
+export function indent(s: string, prefix?: string): string;
+export function summarize(
+    ann: Annotation,
+    keypath?: ReadonlyArray<number | string>,
+): string[];

package/{cjs/_utils.js → _utils.js}

@@ -4,34 +4,28 @@ exports.__esModule = true;
 exports.INDENT = void 0;
 exports.asDate = asDate;
 exports.indent = indent;
-exports.isDate = isDate;
 exports.isMultiline = isMultiline;
 exports.summarize = summarize;
-// $FlowFixMe[unclear-type] - deliberate casting
+// $FlowFixMe[unclear-type] - deliberate use of `any`
 // Two spaces of indentation
 var INDENT = '  ';
 /**
- * `x instanceof Date` checks are unreliable across stack frames (that information
- * might get lost by the JS runtime), so we'll have to reside to more runtime
- * inspection checks.
- *
- * Taken from https://stackoverflow.com/a/44198641
- */
-
-exports.INDENT = INDENT;
-
-function isDate(value) {
-  return !!value && // $FlowFixMe[method-unbinding]
-  Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value);
-}
-/**
- * Is value is a valid Date instance, then return that.  If not, then return
+ * Is value is a valid Date instance, then return that. If not, then return
  * null.
  */
 
+exports.INDENT = INDENT;
 
 function asDate(value) {
-  return isDate(value) ? value : null;
+  //
+  // `x instanceof Date` checks are unreliable across stack frames (that
+  // information might get lost by the JS runtime), so we'll have to reside
+  // to more runtime inspection checks.
+  //
+  // Taken from https://stackoverflow.com/a/44198641
+  //
+  return !!value && // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value) ? value : null;
 }
 
 function isMultiline(s) {

package/{cjs/_utils.js.flow → _utils.js.flow}

@@ -2,34 +2,30 @@
 
 import type { Annotation } from './annotate';
 
-// $FlowFixMe[unclear-type] - deliberate casting
-type cast = any;
+// $FlowFixMe[unclear-type] - deliberate use of `any`
+export type _Any = any;
 
 // Two spaces of indentation
 export const INDENT = '  ';
 
 /**
- * `x instanceof Date` checks are unreliable across stack frames (that information
- * might get lost by the JS runtime), so we'll have to reside to more runtime
- * inspection checks.
- *
- * Taken from https://stackoverflow.com/a/44198641
+ * Is value is a valid Date instance, then return that. If not, then return
+ * null.
  */
-export function isDate(value: mixed): boolean {
-    return (
-        !!value &&
+export function asDate(value: mixed): Date | null {
+    //
+    // `x instanceof Date` checks are unreliable across stack frames (that
+    // information might get lost by the JS runtime), so we'll have to reside
+    // to more runtime inspection checks.
+    //
+    // Taken from https://stackoverflow.com/a/44198641
+    //
+    return !!value &&
         // $FlowFixMe[method-unbinding]
         Object.prototype.toString.call(value) === '[object Date]' &&
         !isNaN(value)
-    );
-}
-
-/**
- * Is value is a valid Date instance, then return that.  If not, then return
- * null.
- */
-export function asDate(value: mixed): Date | null {
-    return isDate(value) ? ((value: cast): Date) : null;
+        ? ((value: _Any): Date)
+        : null;
 }
 
 export function isMultiline(s: string): boolean {

package/{es/_utils.js → _utils.mjs}

@@ -1,25 +1,21 @@
-// $FlowFixMe[unclear-type] - deliberate casting
+// $FlowFixMe[unclear-type] - deliberate use of `any`
 // Two spaces of indentation
 export var INDENT = '  ';
 /**
- * `x instanceof Date` checks are unreliable across stack frames (that information
- * might get lost by the JS runtime), so we'll have to reside to more runtime
- * inspection checks.
- *
- * Taken from https://stackoverflow.com/a/44198641
- */
-
-export function isDate(value) {
-  return !!value && // $FlowFixMe[method-unbinding]
-  Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value);
-}
-/**
- * Is value is a valid Date instance, then return that.  If not, then return
+ * Is value is a valid Date instance, then return that. If not, then return
  * null.
  */
 
 export function asDate(value) {
-  return isDate(value) ? value : null;
+  //
+  // `x instanceof Date` checks are unreliable across stack frames (that
+  // information might get lost by the JS runtime), so we'll have to reside
+  // to more runtime inspection checks.
+  //
+  // Taken from https://stackoverflow.com/a/44198641
+  //
+  return !!value && // $FlowFixMe[method-unbinding]
+  Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value) ? value : null;
 }
 export function isMultiline(s) {
   return s.indexOf('\n') >= 0;

package/{ts/annotate.d.ts → annotate.d.ts}

@@ -1,29 +1,35 @@
 export interface ObjectAnnotation {
-    type: 'object';
-    fields: { [key: string]: Annotation };
-    text?: string;
+    readonly type: 'object';
+    readonly fields: { readonly [key: string]: Annotation };
+    readonly text?: string;
 }
 
 export interface ArrayAnnotation {
-    type: 'array';
-    items: readonly Annotation[];
-    text?: string;
+    readonly type: 'array';
+    readonly items: readonly Annotation[];
+    readonly text?: string;
 }
 
 export interface ScalarAnnotation {
-    type: 'scalar';
-    value: unknown;
-    text?: string;
+    readonly type: 'scalar';
+    readonly value: unknown;
+    readonly text?: string;
 }
 
 export interface FunctionAnnotation {
-    type: 'function';
-    text?: string;
+    readonly type: 'function';
+    readonly text?: string;
 }
 
 export interface CircularRefAnnotation {
-    type: 'circular-ref';
-    text?: string;
+    readonly type: 'circular-ref';
+    readonly text?: string;
+}
+
+export interface UnknownAnnotation {
+    readonly type: 'unknown';
+    readonly value: unknown;
+    readonly text?: string;
 }
 
 export type Annotation =
@@ -31,28 +37,26 @@ export type Annotation =
     | ArrayAnnotation
     | ScalarAnnotation
     | FunctionAnnotation
-    | CircularRefAnnotation;
+    | CircularRefAnnotation
+    | UnknownAnnotation;
 
 export function object(
-    fields: { [key: string]: Annotation },
+    fields: { readonly [key: string]: Annotation },
     text?: string,
 ): ObjectAnnotation;
 export function array(items: readonly Annotation[], text?: string): ArrayAnnotation;
 export function func(text?: string): FunctionAnnotation;
+export function unknown(value: unknown, text?: string): UnknownAnnotation;
 export function scalar(value: unknown, text?: string): ScalarAnnotation;
 export function circularRef(text?: string): CircularRefAnnotation;
-
 export function updateText<A extends Annotation>(annotation: A, text?: string): A;
-
 export function merge(
     objAnnotation: ObjectAnnotation,
-    fields: { [key: string]: Annotation },
+    fields: { readonly [key: string]: Annotation },
 ): ObjectAnnotation;
-
 export function asAnnotation(thing: unknown): Annotation | void;
-
 export function annotate(value: unknown, text?: string): Annotation;
 export function annotateObject(
-    obj: { [key: string]: unknown },
+    obj: { readonly [field: string]: unknown },
     text?: string,
 ): ObjectAnnotation;

package/format.d.ts

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

package/{cjs/format/inline.js → format.js}

@@ -2,10 +2,11 @@
 
 exports.__esModule = true;
 exports.formatInline = formatInline;
+exports.formatShort = formatShort;
 exports.serializeAnnotation = serializeAnnotation;
 exports.serializeValue = serializeValue;
 
-var _utils = require("../_utils");
+var _utils = require("./_utils");
 
 function serializeString(s, width) {
   if (width === void 0) {
@@ -92,7 +93,7 @@ function serializeValue(value) {
       return "new Date(" + JSON.stringify(valueAsDate.toISOString()) + ")";
     } else if (value instanceof Date) {
       // NOTE: Using `instanceof Date` is unreliable way of checking dates.
-      // If this case occurs (and it didn't pass the prior isDate())
+      // If this case occurs (and it didn't pass the prior asDate())
       // check, then this must be the case where it's an invalid date.
       return '(Invalid Date)';
     } else {
@@ -143,4 +144,8 @@ function formatInline(ann) {
   } else {
     return serialized;
   }
+}
+
+function formatShort(ann) {
+  return (0, _utils.summarize)(ann, []).join('\n');
 }

package/{cjs/format/inline.js.flow → format.js.flow}

@@ -1,7 +1,9 @@
 // @flow strict
 
-import { asDate, indent, INDENT, isMultiline } from '../_utils';
-import type { Annotation, ArrayAnnotation, ObjectAnnotation } from '../annotate';
+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
@@ -74,7 +76,7 @@ export function serializeValue(value: mixed): string {
             return `new Date(${JSON.stringify(valueAsDate.toISOString())})`;
         } else if (value instanceof Date) {
             // NOTE: Using `instanceof Date` is unreliable way of checking dates.
-            // If this case occurs (and it didn't pass the prior isDate())
+            // If this case occurs (and it didn't pass the prior asDate())
             // check, then this must be the case where it's an invalid date.
             return '(Invalid Date)';
         } else {
@@ -120,3 +122,7 @@ export function formatInline(ann: Annotation): string {
         return serialized;
     }
 }
+
+export function formatShort(ann: Annotation): string {
+    return _summarize(ann, []).join('\n');
+}

package/{es/format/inline.js → format.mjs}

@@ -1,4 +1,4 @@
-import { asDate, indent, INDENT, isMultiline } from '../_utils';
+import { summarize as _summarize, asDate, INDENT, indent, isMultiline } from './_utils.mjs';
 
 function serializeString(s, width) {
   if (width === void 0) {
@@ -85,7 +85,7 @@ export function serializeValue(value) {
       return "new Date(" + JSON.stringify(valueAsDate.toISOString()) + ")";
     } else if (value instanceof Date) {
       // NOTE: Using `instanceof Date` is unreliable way of checking dates.
-      // If this case occurs (and it didn't pass the prior isDate())
+      // If this case occurs (and it didn't pass the prior asDate())
       // check, then this must be the case where it's an invalid date.
       return '(Invalid Date)';
     } else {
@@ -134,4 +134,7 @@ export function formatInline(ann) {
   } else {
     return serialized;
   }
+}
+export function formatShort(ann) {
+  return _summarize(ann, []).join('\n');
 }

package/index.d.ts

@@ -0,0 +1,40 @@
+export { DecodeResult, Decoder, DecoderType, Scalar, define } from './Decoder';
+export { JSONValue, JSONObject, JSONArray } from './lib/json';
+
+export {
+    always,
+    constant,
+    hardcoded,
+    maybe,
+    mixed,
+    nullable,
+    null_,
+    optional,
+    undefined_,
+    unknown,
+} from './lib/basics';
+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 } from './lib/unions';
+export {
+    email,
+    httpsUrl,
+    nonEmptyString,
+    regex,
+    string,
+    url,
+    uuid,
+    uuidv1,
+    uuidv4,
+} from './lib/strings';
+export { fail, instanceOf, lazy, never, prep } from './lib/utilities';
+export {
+    anyNumber,
+    integer,
+    number,
+    positiveInteger,
+    positiveNumber,
+} from './lib/numbers';
+export { json, jsonObject, jsonArray } from './lib/json';

package/index.js

@@ -0,0 +1,89 @@
+"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.dict = exports.define = exports.date = exports.constant = exports["boolean"] = exports.array = exports.anyNumber = exports.always = void 0;
+
+var _Decoder = require("./Decoder");
+
+exports.define = _Decoder.define;
+
+var _basics = require("./lib/basics");
+
+exports.always = _basics.always;
+exports.constant = _basics.constant;
+exports.hardcoded = _basics.hardcoded;
+exports.maybe = _basics.maybe;
+exports.mixed = _basics.mixed;
+exports.nullable = _basics.nullable;
+exports.null_ = _basics.null_;
+exports.optional = _basics.optional;
+exports.undefined_ = _basics.undefined_;
+exports.unknown = _basics.unknown;
+
+var _arrays = require("./lib/arrays");
+
+exports.array = _arrays.array;
+exports.nonEmptyArray = _arrays.nonEmptyArray;
+exports.poja = _arrays.poja;
+exports.set = _arrays.set;
+exports.tuple = _arrays.tuple;
+
+var _booleans = require("./lib/booleans");
+
+exports["boolean"] = _booleans["boolean"];
+exports.numericBoolean = _booleans.numericBoolean;
+exports.truthy = _booleans.truthy;
+
+var _dates = require("./lib/dates");
+
+exports.date = _dates.date;
+exports.iso8601 = _dates.iso8601;
+
+var _objects = require("./lib/objects");
+
+exports.dict = _objects.dict;
+exports.exact = _objects.exact;
+exports.inexact = _objects.inexact;
+exports.mapping = _objects.mapping;
+exports.object = _objects.object;
+exports.pojo = _objects.pojo;
+
+var _unions = require("./lib/unions");
+
+exports.either = _unions.either;
+exports.oneOf = _unions.oneOf;
+exports.taggedUnion = _unions.taggedUnion;
+
+var _strings = require("./lib/strings");
+
+exports.email = _strings.email;
+exports.httpsUrl = _strings.httpsUrl;
+exports.nonEmptyString = _strings.nonEmptyString;
+exports.regex = _strings.regex;
+exports.string = _strings.string;
+exports.url = _strings.url;
+exports.uuid = _strings.uuid;
+exports.uuidv1 = _strings.uuidv1;
+exports.uuidv4 = _strings.uuidv4;
+
+var _utilities = require("./lib/utilities");
+
+exports.fail = _utilities.fail;
+exports.instanceOf = _utilities.instanceOf;
+exports.lazy = _utilities.lazy;
+exports.never = _utilities.never;
+exports.prep = _utilities.prep;
+
+var _numbers = require("./lib/numbers");
+
+exports.anyNumber = _numbers.anyNumber;
+exports.integer = _numbers.integer;
+exports.number = _numbers.number;
+exports.positiveInteger = _numbers.positiveInteger;
+exports.positiveNumber = _numbers.positiveNumber;
+
+var _json = require("./lib/json");
+
+exports.json = _json.json;
+exports.jsonObject = _json.jsonObject;
+exports.jsonArray = _json.jsonArray;

package/index.js.flow

@@ -0,0 +1,44 @@
+// @flow strict
+
+export type { Decoder, DecodeResult, DecoderType, Scalar } from './Decoder';
+export type { JSONValue, JSONObject, JSONArray } from './lib/json';
+
+export { define } from './Decoder';
+
+export {
+    always,
+    constant,
+    hardcoded,
+    maybe,
+    mixed,
+    nullable,
+    null_,
+    optional,
+    undefined_,
+    unknown,
+} from './lib/basics';
+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 } from './lib/unions';
+export {
+    email,
+    httpsUrl,
+    nonEmptyString,
+    regex,
+    string,
+    url,
+    uuid,
+    uuidv1,
+    uuidv4,
+} from './lib/strings';
+export { fail, instanceOf, lazy, never, prep } from './lib/utilities';
+export {
+    anyNumber,
+    integer,
+    number,
+    positiveInteger,
+    positiveNumber,
+} from './lib/numbers';
+export { json, jsonObject, jsonArray } from './lib/json';

package/index.mjs

@@ -0,0 +1,11 @@
+export { define } from './Decoder.mjs';
+export { always, constant, hardcoded, maybe, mixed, nullable, null_, optional, undefined_, unknown } from './lib/basics.mjs';
+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 } 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';
+export { json, jsonObject, jsonArray } from './lib/json.mjs';

package/lib/arrays.d.ts

@@ -0,0 +1,59 @@
+/// <reference lib="es6" />
+
+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>(
+    a: Decoder<A>,
+    b: Decoder<B>,
+    c: Decoder<C>,
+): Decoder<[A, B, C]>;
+export function tuple<A, B, C, D>(
+    a: Decoder<A>,
+    b: Decoder<B>,
+    c: Decoder<C>,
+    d: Decoder<D>,
+): Decoder<[A, B, C, D]>;
+export function tuple<A, B, C, D, E>(
+    a: Decoder<A>,
+    b: Decoder<B>,
+    c: Decoder<C>,
+    d: Decoder<D>,
+    e: Decoder<E>,
+): Decoder<[A, B, C, D, E]>;
+export function tuple<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]>;