decoders 2.0.0-beta1 → 2.0.0-beta2

package/format/inline.js.flow

@@ -0,0 +1,122 @@
+// @flow strict
+
+import { asDate, indent, INDENT, isMultiline } from '../_utils';
+import type { Annotation, ArrayAnnotation, ObjectAnnotation } from '../annotate';
+
+function serializeString(s: string, width: number = 80): string {
+    // Full string
+    // Abbreviated to $maxlen i.e. "Vincent Driess..." [truncated]
+    let ser = JSON.stringify(s);
+    if (ser.length <= width) {
+        return ser;
+    }
+
+    // Cut off a bit
+    const truncated = s.substring(0, width - 15) + '...';
+    ser = JSON.stringify(truncated) + ' [truncated]';
+    return ser;
+}
+
+function serializeArray(annotation: ArrayAnnotation, prefix: string): string {
+    const { items } = annotation;
+    if (items.length === 0) {
+        return '[]';
+    }
+
+    const result = [];
+    items.forEach((item) => {
+        const [ser, ann] = serializeAnnotation(item, prefix + INDENT);
+        result.push(prefix + INDENT + ser + ',');
+        if (ann !== undefined) {
+            result.push(indent(ann, prefix + INDENT));
+        }
+    });
+    return ['[', ...result, prefix + ']'].join('\n');
+}
+
+function serializeObject(annotation: ObjectAnnotation, prefix: string): string {
+    const { fields } = annotation;
+
+    const fieldNames = Object.keys(fields);
+    if (fieldNames.length === 0) {
+        return '{}';
+    }
+
+    const result = [];
+    fieldNames.forEach((key) => {
+        const valueAnnotation = fields[key];
+        const kser = serializeValue(key);
+
+        const valPrefix = prefix + INDENT + ' '.repeat(kser.length + 2);
+        const [vser, vann] = serializeAnnotation(valueAnnotation, prefix + INDENT);
+
+        result.push(prefix + INDENT + kser + ': ' + vser + ',');
+        if (vann !== undefined) {
+            result.push(indent(vann, valPrefix));
+        }
+    });
+    return ['{', ...result, prefix + '}'].join('\n');
+}
+
+export function serializeValue(value: mixed): string {
+    // istanbul ignore else
+    if (typeof value === 'string') {
+        return serializeString(value);
+    } else if (typeof value === 'number' || typeof value === 'boolean') {
+        return value.toString();
+    } else if (value === null) {
+        return 'null';
+    } else if (value === undefined) {
+        return 'undefined';
+    } else {
+        const valueAsDate = asDate(value);
+        if (valueAsDate !== null) {
+            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())
+            // check, then this must be the case where it's an invalid date.
+            return '(Invalid Date)';
+        } else {
+            return '(unserializable)';
+        }
+    }
+}
+
+export function serializeAnnotation(
+    ann: Annotation,
+    prefix: string = '',
+): [string, string | void] {
+    // The serialized data (the input object echoed back)
+    let serialized;
+    if (ann.type === 'array') {
+        serialized = serializeArray(ann, prefix);
+    } else if (ann.type === 'object') {
+        serialized = serializeObject(ann, prefix);
+    } else if (ann.type === 'function') {
+        serialized = '<function>';
+    } else if (ann.type === 'circular-ref') {
+        serialized = '<circular ref>';
+    } else if (ann.type === 'unknown') {
+        serialized = '???';
+    } else {
+        serialized = serializeValue(ann.value);
+    }
+
+    const text = ann.text;
+    if (text !== undefined) {
+        const sep = '^'.repeat(isMultiline(serialized) ? 1 : serialized.length);
+        return [serialized, [sep, text].join(isMultiline(text) ? '\n' : ' ')];
+    } else {
+        return [serialized, undefined];
+    }
+}
+
+export function formatInline(ann: Annotation): string {
+    const [serialized, annotation] = serializeAnnotation(ann);
+    if (annotation !== undefined) {
+        return serialized + '\n' + annotation;
+    } else {
+        return serialized;
+    }
+}

package/format/short.js.flow

@@ -0,0 +1,8 @@
+// @flow strict
+
+import { summarize as _summarize } from '../_utils';
+import type { Annotation } from '../annotate';
+
+export function formatShort(ann: Annotation): string {
+    return _summarize(ann, []).join('\n');
+}

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

@@ -7,25 +7,25 @@ var _guard = require("./_guard");
 
 exports.guard = _guard.guard;
 
-var _composition = require("./stdlib/composition");
+var _composition = require("./core/composition");
 
 exports.compose = _composition.compose;
 exports.map = _composition.map;
 exports.predicate = _composition.predicate;
 
-var _array = require("./stdlib/array");
+var _array = require("./core/array");
 
 exports.array = _array.array;
 exports.nonEmptyArray = _array.nonEmptyArray;
 exports.poja = _array.poja;
 
-var _boolean = require("./stdlib/boolean");
+var _boolean = require("./core/boolean");
 
 exports["boolean"] = _boolean["boolean"];
 exports.numericBoolean = _boolean.numericBoolean;
 exports.truthy = _boolean.truthy;
 
-var _constants = require("./stdlib/constants");
+var _constants = require("./core/constants");
 
 exports.constant = _constants.constant;
 exports.hardcoded = _constants.hardcoded;
@@ -34,20 +34,20 @@ exports.null_ = _constants.null_;
 exports.undefined_ = _constants.undefined_;
 exports.unknown = _constants.unknown;
 
-var _date = require("./stdlib/date");
+var _date = require("./core/date");
 
 exports.date = _date.date;
 exports.iso8601 = _date.iso8601;
 
-var _describe = require("./stdlib/describe");
+var _describe = require("./core/describe");
 
 exports.describe = _describe.describe;
 
-var _dispatch = require("./stdlib/dispatch");
+var _dispatch = require("./core/dispatch");
 
 exports.dispatch = _dispatch.dispatch;
 
-var _either = require("./stdlib/either");
+var _either = require("./core/either");
 
 exports.either = _either.either;
 exports.either3 = _either.either3;
@@ -59,50 +59,50 @@ exports.either8 = _either.either8;
 exports.either9 = _either.either9;
 exports.oneOf = _either.oneOf;
 
-var _fail = require("./stdlib/fail");
+var _fail = require("./core/fail");
 
 exports.fail = _fail.fail;
 
-var _instanceOf = require("./stdlib/instanceOf");
+var _instanceOf = require("./core/instanceOf");
 
 exports.instanceOf = _instanceOf.instanceOf;
 
-var _json = require("./stdlib/json");
+var _json = require("./core/json");
 
 exports.json = _json.json;
 exports.jsonObject = _json.jsonObject;
 exports.jsonArray = _json.jsonArray;
 
-var _lazy = require("./stdlib/lazy");
+var _lazy = require("./core/lazy");
 
 exports.lazy = _lazy.lazy;
 
-var _mapping = require("./stdlib/mapping");
+var _mapping = require("./core/mapping");
 
 exports.mapping = _mapping.mapping;
 exports.dict = _mapping.dict;
 
-var _number = require("./stdlib/number");
+var _number = require("./core/number");
 
 exports.integer = _number.integer;
 exports.number = _number.number;
 exports.positiveInteger = _number.positiveInteger;
 exports.positiveNumber = _number.positiveNumber;
 
-var _object = require("./stdlib/object");
+var _object = require("./core/object");
 
 exports.exact = _object.exact;
 exports.inexact = _object.inexact;
 exports.object = _object.object;
 exports.pojo = _object.pojo;
 
-var _optional = require("./stdlib/optional");
+var _optional = require("./core/optional");
 
 exports.maybe = _optional.maybe;
 exports.nullable = _optional.nullable;
 exports.optional = _optional.optional;
 
-var _string = require("./stdlib/string");
+var _string = require("./core/string");
 
 exports.email = _string.email;
 exports.nonEmptyString = _string.nonEmptyString;
@@ -110,7 +110,7 @@ exports.regex = _string.regex;
 exports.string = _string.string;
 exports.url = _string.url;
 
-var _tuple = require("./stdlib/tuple");
+var _tuple = require("./core/tuple");
 
 exports.tuple1 = _tuple.tuple1;
 exports.tuple2 = _tuple.tuple2;

package/index.js.flow

@@ -0,0 +1,56 @@
+// @flow strict
+
+/**
+ * Elm-like JSON decoders, for use with Flow.
+ * See http://elmplayground.com/decoding-json-in-elm-1 for an introduction.
+ *
+ * Why? All JSON responses coming from our API endpoints are just that: free-form
+ * JSON data.  To Flow, the only type classification possilbe is "any" -- effectively
+ * turning off all type checks for anything related to JSON.  To the receiving end
+ * (our frontend), the structure of that data is completely opaque to any type
+ * checkers since JSON values can be anything: an object, an array, null, a string,
+ * a bool, etc.  Our type system is not a runtime type system, so we need a way of
+ * "converting" an any-type JSON value into a type that we want to work with in our
+ * frontend code base.
+ *
+ * Elm's solution to this problem is to define composable decoders: functions that
+ * take anything and either fail with an error, or guarantee to return the expected
+ * type.  In our case, it's fine to fail with a runtime error.
+ *
+ */
+export type { Decoder, Guard } from './_types';
+export type { DecoderType, GuardType } from './_types';
+
+export type { JSONValue, JSONObject, JSONArray } from './core/json';
+
+export { guard } from './_guard';
+
+export { compose, map, predicate } from './core/composition';
+
+export { array, nonEmptyArray, poja } from './core/array';
+export { boolean, numericBoolean, truthy } from './core/boolean';
+export { constant, hardcoded, mixed, null_, undefined_, unknown } from './core/constants';
+export { date, iso8601 } from './core/date';
+export { describe } from './core/describe';
+export { dispatch } from './core/dispatch';
+export {
+    either,
+    either3,
+    either4,
+    either5,
+    either6,
+    either7,
+    either8,
+    either9,
+    oneOf,
+} from './core/either';
+export { fail } from './core/fail';
+export { instanceOf } from './core/instanceOf';
+export { json, jsonObject, jsonArray } from './core/json';
+export { lazy } from './core/lazy';
+export { mapping, dict } from './core/mapping';
+export { integer, number, positiveInteger, positiveNumber } from './core/number';
+export { exact, inexact, object, pojo } from './core/object';
+export { maybe, nullable, optional } from './core/optional';
+export { email, nonEmptyString, regex, string, url } from './core/string';
+export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './core/tuple';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decoders",
-    "version": "2.0.0-beta1",
+    "version": "2.0.0-beta2",
     "description": "Elegant and battle-tested validation library for type-safe input data (for TypeScript and Flow)",
     "license": "MIT",
     "repository": {
@@ -12,16 +12,8 @@
     "bugs": {
         "url": "https://github.com/nvie/decoders/issues"
     },
-    "main": "./cjs/index.js",
-    "module": "./es/index.js",
-    "type": "module",
-    "exports": {
-        "require": "./cjs/index.js",
-        "import": "./es/index.js"
-    },
-    "engines": {
-        "node": ">=12"
-    },
+    "main": "./index.js",
+    "module": "./_esm/index.js",
     "keywords": [
         "decoder",
         "decoders",
@@ -48,7 +40,6 @@
         "map",
         "predicate"
     ],
-    "types": "./ts/index.d.ts",
     "githubUrl": "https://github.com/nvie/decoders",
     "sideEffects": false
 }

package/result.js.flow

@@ -0,0 +1,166 @@
+// @flow strict
+
+/**
+ * Result <value> <error>
+ *     = Ok <value>
+ *     | Err <error>
+ */
+
+type Ok<+T> = {| +type: 'ok', +value: T |};
+type Err<+E> = {| +type: 'err', +error: E |};
+
+export type Result<+T, +E> = Ok<T> | Err<E>;
+
+/**
+ * Create a new Result instance representing a successful computation.
+ */
+export function ok<T>(value: T): Ok<T> {
+    return { type: 'ok', value };
+}
+
+/**
+ * Create a new Result instance representing a failed computation.
+ */
+export function err<E>(error: E): Err<E> {
+    return { type: 'err', error };
+}
+
+export function toString(result: Result<mixed, mixed>): string {
+    return result.type === 'ok'
+        ? `Ok(${String(result.value)})`
+        : `Err(${String(result.error)})`;
+}
+
+export function isOk(result: Result<mixed, mixed>): boolean {
+    return result.type === 'ok';
+}
+
+export function isErr(result: Result<mixed, mixed>): boolean {
+    return result.type === 'err';
+}
+
+export function withDefault<T>(result: Result<T, mixed>, defaultValue: T): T {
+    return result.type === 'ok' ? result.value : defaultValue;
+}
+
+export function value<T>(result: Result<T, mixed>): void | T {
+    return result.type === 'ok' ? result.value : undefined;
+}
+
+export function errValue<E>(result: Result<mixed, E>): void | E {
+    return result.type === 'err' ? result.error : undefined;
+}
+
+/**
+ * Unwrap the value from this Result instance if this is an "Ok" result.
+ * Otherwise, will throw the "Err" error via a runtime exception.
+ */
+export function unwrap<T>(result: Result<T, mixed>): T {
+    if (result.type === 'ok') {
+        return result.value;
+    } else {
+        throw result.error;
+    }
+}
+
+export function expect<T>(result: Result<T, mixed>, message: string | Error): T {
+    if (result.type === 'ok') {
+        return result.value;
+    } else {
+        throw message instanceof Error ? message : new Error(message);
+    }
+}
+
+export function dispatch<T, E, O>(
+    result: Result<T, E>,
+    okCallback: (value: T) => O,
+    errCallback: (error: E) => O,
+): O {
+    return result.type === 'ok' ? okCallback(result.value) : errCallback(result.error);
+}
+
+/**
+ * If the given result is OK, defers to the other result. Otherwise returns the
+ * error result.
+ *
+ * It's like saying A && B, but on Result.
+ *
+ * Examples:
+ *
+ *     Result.ok(42)     && Result.ok('hi')    // => Ok('hi')
+ *     Result.err('boo') && Result.ok('hi')    // => Err('boo')
+ *     Result.ok(42)     && Result.err('boo')  // => Err('boo')
+ *     Result.err('boo') && Result.err('boo')  // => Err('boo')
+ *
+ */
+// export function and<T, E, T2>(
+//     result1: Result<T, E>,
+//     result2: Result<T2, E>,
+// ): Result<T2, E> {
+//     return result1.type === 'ok' ? result2 : result1;
+// }
+
+/**
+ * If the given result is OK, return that result. Otherwise, defers to the
+ * other result.
+ *
+ * It's like saying A || B, but on Result.
+ *
+ * Examples:
+ *
+ *     Result.ok(42)      || Result.ok('hi')    // => Ok(42)
+ *     Result.err('boo')  || Result.ok('hi')    // => Ok('hi')
+ *     Result.ok(42)      || Result.err('boo')  // => Ok(42)
+ *     Result.err('bleh') || Result.err('boo')  // => Err('boo')
+ *
+ */
+// export function or<T, E, E2>(
+//     result1: Result<T, E>,
+//     result2: Result<T, E2>,
+// ): Result<T, E2> {
+//     return result1.type === 'ok' ? result1 : result2;
+// }
+
+/**
+ * Like .and(), aka &&, but the second argument gets evaluated lazily only if
+ * the first result is an Ok result. If so, it has access to the Ok value from
+ * the first argument.
+ */
+export function andThen<T, E, T2>(
+    result1: Result<T, E>,
+    lazyResult2: (value: T) => Result<T2, E>,
+): Result<T2, E> {
+    return result1.type === 'ok' ? lazyResult2(result1.value) : result1;
+}
+
+/**
+ * Like .or(), aka ||, but the second argument gets evaluated lazily only if
+ * the first result is an Err result. If so, it has access to the Err value
+ * from the first argument.
+ */
+export function orElse<T, E, E2>(
+    result1: Result<T, E>,
+    lazyResult2: (errValue: E) => Result<T, E2>,
+): Result<T, E2> {
+    return result1.type === 'ok' ? result1 : lazyResult2(result1.error);
+}
+
+/**
+ * Transform an Ok result. Will not touch Err results.
+ */
+export function map<T, E, T2>(
+    result: Result<T, E>,
+    mapper: (value: T) => T2,
+): Result<T2, E> {
+    return result.type === 'ok' ? ok(mapper(result.value)) : result;
+}
+
+/**
+ * Transform an Err value. Will not touch Ok results.
+ */
+export function mapError<T, E, E2>(
+    result: Result<T, E>,
+    mapper: (error: E) => E2,
+): Result<T, E2> {
+    return result.type === 'ok' ? result : err(mapper(result.error));
+}

package/ts/_guard.d.ts

@@ -1,7 +0,0 @@
-import { Annotation } from './annotate';
-import { Decoder, Guard } from './_types';
-
-export function guard<T>(
-    decoder: Decoder<T>,
-    formatter?: (annotation: Annotation) => string,
-): Guard<T>;

package/ts/_helpers.d.ts

@@ -1,79 +0,0 @@
-/**
- * Given a type like:
- *
- *   {
- *     a: string;
- *     b: number | undefined;
- *     c: null | undefined;
- *     d: null;
- *     e: undefined;
- *   }
- *
- * Will drop all the "undefined" types. In this case, only "e":
- *
- *   {
- *     a: string;
- *     b: number | undefined;
- *     c: null | undefined;
- *     d: null;
- *   }
- *
- */
-type Compact<T> = { [K in IsDefined<T, keyof T>]: T[K] };
-
-type IsDefined<T, K extends keyof T> = K extends any
-    ? T[K] extends undefined
-        ? never
-        : K
-    : never;
-
-//
-// HACK:
-// These weird conditionals test whether TypeScript is configured with the
-// `strictNullChecks` compiler option. We use these definitions to influence
-// what's considered a "required" vs an "optional" key for the AllowImplicit
-// type.
-//
-// If strictNullChecks is false, then we should not be emitting any `?` fields
-// and consider all fields "required" because everything is optional by default
-// in that mode anyway.
-//
-type NoStrictNullChecks = undefined extends string ? 1 : undefined;
-//                        ^^^^^^^^^^^^^^^^^^^^^^^^
-type StrictNullChecks = undefined extends string ? undefined : 1;
-//                      ^^^^^^^^^^^^^^^^^^^^^^^^
-
-export type RequiredKeys<T> = keyof Compact<{
-    [K in keyof T]: undefined extends T[K] ? NoStrictNullChecks : 1;
-}>;
-
-export type OptionalKeys<T> = keyof Compact<{
-    [K in keyof T]: undefined extends T[K] ? 1 : StrictNullChecks;
-}>;
-
-/**
- * Transforms an object type, by marking all fields that contain "undefined"
- * with a question mark, i.e. allowing implicit-undefineds when
- * explicit-undefined are also allowed.
- *
- * For example, if:
- *
- *   type User = {
- *     name: string;
- *     age: number | null | undefined;
- *   }
- *
- * Then AllowImplicit<User> will become equivalent to:
- *
- *   {
- *     name: string;
- *     age?: number | null;
- *        ^
- *        Note the question mark
- *   }
- */
-type AllowImplicit<T> = { [K in RequiredKeys<T>]-?: T[K] } & {
-    [K in OptionalKeys<T>]+?: Exclude<T[K], undefined>;
-};
-
-export { AllowImplicit };

package/ts/_types.d.ts

@@ -1,16 +0,0 @@
-import { Annotation } from './annotate';
-import { Result } from './result';
-
-export type Scalar = string | number | boolean | symbol | undefined | null;
-
-export interface Guard<T> {
-    (blob: unknown): T;
-}
-export type Predicate<T> = (value: T) => boolean;
-export type DecodeResult<T> = Result<T, Annotation>;
-export interface Decoder<T, F = unknown> {
-    (blob: F): DecodeResult<T>;
-}
-
-export type DecoderType<T> = T extends Decoder<infer V> ? V : never;
-export type GuardType<T> = T extends Guard<infer V> ? V : never;

package/ts/_utils.d.ts

@@ -1,13 +0,0 @@
-import { Decoder } from './_types';
-
-export function isDate(value: unknown): boolean;
-export function map<T, V>(decoder: Decoder<T>, mapper: (value: T) => V): Decoder<V>;
-export function compose<T, V>(decoder: Decoder<T>, next: Decoder<V, T>): Decoder<V>;
-export function predicate<T extends F, F = unknown>(
-    predicate: (value: F) => value is T,
-    msg: string,
-): Decoder<T, F>;
-export function predicate<T>(
-    predicate: (value: T) => boolean,
-    msg: string,
-): Decoder<T, T>;