decoders 2.0.0-beta1 → 2.0.0-beta10

package/lib/utilities.mjs

@@ -0,0 +1,79 @@
+import { annotate } from '../annotate.mjs';
+import { define } from '../Decoder.mjs';
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+export function instanceOf(klass) {
+  return define(function (blob, ok, err) {
+    return blob instanceof klass ? ok(blob) : err("Must be " + // $FlowFixMe[incompatible-use] - klass.name is fine?
+    klass.name + " instance");
+  });
+}
+/**
+ * Lazily evaluate the given decoder. This is useful to build self-referential
+ * types for recursive data structures.
+ *
+ * Example:
+ *
+ * ```ts
+ * type Tree = {
+ *     value: string;
+ *     children: Array<Tree>;
+ *     //              ^^^^
+ *     //              Self-reference defining a recursive type
+ * };
+ *
+ * const treeDecoder: Decoder<Tree> = object({
+ *     value: string,
+ *     children: array(lazy(() => treeDecoder)),
+ *     //              ^^^^^^^^^^^^^^^^^^^^^^^
+ *     //              Use lazy() like this to refer to the treeDecoder which is
+ *     //              getting defined here
+ * });
+ * ```
+ */
+
+export function lazy(decoderFn) {
+  return define(function (blob) {
+    return decoderFn().decode(blob);
+  });
+}
+/**
+ * Pre-process the data input before passing it into the decoder. This gives
+ * you the ability to arbitrarily customize the input on the fly before passing
+ * it to the decoder. Of course, the input value at that point is still of
+ * ``unknown`` type, so you will have to deal with that accordingly.
+ */
+
+export function prep(mapperFn, decoder) {
+  return define(function (originalInput, _, err) {
+    var blob;
+
+    try {
+      blob = mapperFn(originalInput);
+    } catch (e) {
+      return err(annotate(originalInput, e.message));
+    }
+
+    var r = decoder.decode(blob);
+    return r.ok ? r : err(annotate(originalInput, r.error.text)); //                             ^^^^^^^^^^^^^
+    //                             Annotates the _original_ input value
+    //                             (instead of echoing back blob)
+  });
+}
+/**
+ * Rejects all inputs, and always fails with the given error message. May be
+ * useful for explicitly disallowing keys, or for testing purposes.
+ */
+
+export function never(msg) {
+  return define(function (_, __, err) {
+    return err(msg);
+  });
+}
+/**
+ * Alias of never().
+ */
+
+export var fail = never;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decoders",
-    "version": "2.0.0-beta1",
+    "version": "2.0.0-beta10",
     "description": "Elegant and battle-tested validation library for type-safe input data (for TypeScript and Flow)",
     "license": "MIT",
     "repository": {
@@ -12,43 +12,93 @@
     "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": "./index.mjs",
     "keywords": [
-        "decoder",
         "decoders",
-        "guard",
-        "object",
+        "Decoder",
+        "always",
+        "and",
         "array",
-        "string",
-        "email",
-        "regex",
-        "number",
-        "integer",
         "boolean",
-        "truthy",
+        "then",
+        "compose",
+        "constant",
         "date",
-        "mapping",
+        "decode",
+        "decoder",
+        "decoders",
+        "define",
+        "describe",
         "dict",
+        "either",
+        "email",
+        "exact",
+        "fail",
+        "hardcoded",
+        "httpsUrl",
+        "inexact",
+        "instanceOf",
+        "integer",
+        "iso8601",
+        "json",
+        "jsonArray",
+        "jsonObject",
+        "lazy",
+        "map",
+        "mapping",
+        "maybe",
         "mixed",
+        "mixedarray",
+        "never",
+        "nonEmptyArray",
+        "nonEmptyString",
+        "nullable",
+        "null_",
+        "number",
+        "numericBoolean",
+        "object",
+        "oneOf",
+        "optional",
+        "poja",
+        "pojo",
+        "positiveInteger",
+        "positiveNumber",
+        "predicate",
+        "prep",
+        "regex",
+        "set",
+        "string",
+        "taggedUnion",
+        "transform",
+        "truthy",
+        "tuple",
         "tuple2",
+        "undefined_",
         "unknown",
-        "optional",
-        "nullable",
-        "maybe",
-        "compose",
-        "map",
-        "predicate"
+        "url",
+        "uuid",
+        "uuidv1",
+        "uuidv4",
+        "verify",
+        "DecodeResult",
+        "DecoderType",
+        "JSONArray",
+        "JSONObject",
+        "JSONValue"
     ],
-    "types": "./ts/index.d.ts",
     "githubUrl": "https://github.com/nvie/decoders",
-    "sideEffects": false
+    "sideEffects": false,
+    "typesVersions": {
+        ">=4.1.0": {
+            "*": [
+                "*"
+            ]
+        },
+        "*": {
+            "*": [
+                "NotSupportedTSVersion.d.ts"
+            ]
+        }
+    }
 }

package/result.d.ts

@@ -0,0 +1,16 @@
+export interface Ok<T> {
+    ok: true;
+    value: T;
+    error: undefined;
+}
+
+export interface Err<E> {
+    ok: false;
+    value: undefined;
+    error: E;
+}
+
+export type Result<T, E> = Ok<T> | Err<E>;
+
+export function ok<T>(value: T): Ok<T>;
+export function err<E>(error: E): Err<E>;

package/result.js

@@ -0,0 +1,34 @@
+"use strict";
+
+exports.__esModule = true;
+exports.err = err;
+exports.ok = ok;
+
+/**
+ * Result <value> <error>
+ *     = Ok <value>
+ *     | Err <error>
+ */
+
+/**
+ * Create a new Result instance representing a successful computation.
+ */
+function ok(value) {
+  return {
+    ok: true,
+    value: value,
+    error: undefined
+  };
+}
+/**
+ * Create a new Result instance representing a failed computation.
+ */
+
+
+function err(error) {
+  return {
+    ok: false,
+    value: undefined,
+    error: error
+  };
+}

package/result.js.flow

@@ -0,0 +1,26 @@
+// @flow strict
+
+/**
+ * Result <value> <error>
+ *     = Ok <value>
+ *     | Err <error>
+ */
+
+type Ok<+T> = {| +ok: true, +value: T, +error: void |};
+type Err<+E> = {| +ok: false, +value: void, +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 { ok: true, value, error: undefined };
+}
+
+/**
+ * Create a new Result instance representing a failed computation.
+ */
+export function err<E>(error: E): Err<E> {
+    return { ok: false, value: undefined, error };
+}

package/result.mjs

@@ -0,0 +1,27 @@
+/**
+ * Result <value> <error>
+ *     = Ok <value>
+ *     | Err <error>
+ */
+
+/**
+ * Create a new Result instance representing a successful computation.
+ */
+export function ok(value) {
+  return {
+    ok: true,
+    value: value,
+    error: undefined
+  };
+}
+/**
+ * Create a new Result instance representing a failed computation.
+ */
+
+export function err(error) {
+  return {
+    ok: false,
+    value: undefined,
+    error: error
+  };
+}

package/cjs/_guard.js

@@ -1,26 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.guard = guard;
-
-var Result = _interopRequireWildcard(require("./result"));
-
-var _format = require("./format");
-
-function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
-
-function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { "default": obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj["default"] = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
-
-function guard(decoder, formatter) {
-  if (formatter === void 0) {
-    formatter = _format.formatInline;
-  }
-
-  return function (blob) {
-    return Result.unwrap(Result.mapError(decoder(blob), function (annotation) {
-      var err = new Error('\n' + formatter(annotation));
-      err.name = 'Decoding error';
-      return err;
-    }));
-  };
-}

package/cjs/_guard.js.flow

@@ -1,20 +0,0 @@
-// @flow strict
-
-import * as Result from './result';
-import { formatInline } from './format';
-import type { Annotation } from './annotate';
-import type { Decoder, Guard } from './_types';
-
-export function guard<T>(
-    decoder: Decoder<T>,
-    formatter: (Annotation) => string = formatInline,
-): Guard<T> {
-    return (blob: mixed) =>
-        Result.unwrap(
-            Result.mapError(decoder(blob), (annotation) => {
-                const err = new Error('\n' + formatter(annotation));
-                err.name = 'Decoding error';
-                return err;
-            }),
-        );
-}

package/cjs/_types.js

@@ -1 +0,0 @@
-"use strict";

package/cjs/_types.js.flow

@@ -1,20 +0,0 @@
-// @flow strict
-
-import type { Annotation } from './annotate';
-import type { Result } from './result';
-
-export type Scalar = string | number | boolean | symbol | void | null;
-
-export type Predicate<T> = (T) => boolean;
-export type DecodeResult<T> = Result<T, Annotation>;
-
-export type Decoder<T, F = mixed> = (F) => DecodeResult<T>;
-export type Guard<T> = (mixed) => T;
-
-/**
- * A "type function" which informs Flow about how a type will be modified at runtime.
- * Read this as "given a Guard of type T, I can produce a value of type T".  This
- * definition helps construct $ObjMap types.
- */
-export type DecoderType = <T>(Decoder<T>) => T;
-export type GuardType = <T>(Guard<T>) => T;

package/cjs/format/index.js

@@ -1,12 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.formatShort = exports.formatInline = void 0;
-
-var _inline = require("./inline");
-
-exports.formatInline = _inline.formatInline;
-
-var _short = require("./short");
-
-exports.formatShort = _short.formatShort;

package/cjs/format/index.js.flow

@@ -1,4 +0,0 @@
-// @flow strict
-
-export { formatInline } from './inline';
-export { formatShort } from './short';

package/cjs/format/short.js

@@ -1,10 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.formatShort = formatShort;
-
-var _utils = require("../_utils");
-
-function formatShort(ann) {
-  return (0, _utils.summarize)(ann, []).join('\n');
-}

package/cjs/format/short.js.flow

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

@@ -1,120 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.url = exports.unknown = exports.undefined_ = exports.tuple6 = exports.tuple5 = exports.tuple4 = exports.tuple3 = exports.tuple2 = exports.tuple1 = exports.truthy = exports.string = exports.regex = exports.predicate = 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.mixed = exports.maybe = exports.mapping = exports.map = exports.lazy = exports.jsonObject = exports.jsonArray = exports.json = exports.iso8601 = exports.integer = exports.instanceOf = exports.inexact = exports.hardcoded = exports.guard = exports.fail = exports.exact = exports.email = exports.either9 = exports.either8 = exports.either7 = exports.either6 = exports.either5 = exports.either4 = exports.either3 = exports.either = exports.dispatch = exports.dict = exports.describe = exports.date = exports.constant = exports.compose = exports["boolean"] = exports.array = void 0;
-
-var _guard = require("./_guard");
-
-exports.guard = _guard.guard;
-
-var _composition = require("./stdlib/composition");
-
-exports.compose = _composition.compose;
-exports.map = _composition.map;
-exports.predicate = _composition.predicate;
-
-var _array = require("./stdlib/array");
-
-exports.array = _array.array;
-exports.nonEmptyArray = _array.nonEmptyArray;
-exports.poja = _array.poja;
-
-var _boolean = require("./stdlib/boolean");
-
-exports["boolean"] = _boolean["boolean"];
-exports.numericBoolean = _boolean.numericBoolean;
-exports.truthy = _boolean.truthy;
-
-var _constants = require("./stdlib/constants");
-
-exports.constant = _constants.constant;
-exports.hardcoded = _constants.hardcoded;
-exports.mixed = _constants.mixed;
-exports.null_ = _constants.null_;
-exports.undefined_ = _constants.undefined_;
-exports.unknown = _constants.unknown;
-
-var _date = require("./stdlib/date");
-
-exports.date = _date.date;
-exports.iso8601 = _date.iso8601;
-
-var _describe = require("./stdlib/describe");
-
-exports.describe = _describe.describe;
-
-var _dispatch = require("./stdlib/dispatch");
-
-exports.dispatch = _dispatch.dispatch;
-
-var _either = require("./stdlib/either");
-
-exports.either = _either.either;
-exports.either3 = _either.either3;
-exports.either4 = _either.either4;
-exports.either5 = _either.either5;
-exports.either6 = _either.either6;
-exports.either7 = _either.either7;
-exports.either8 = _either.either8;
-exports.either9 = _either.either9;
-exports.oneOf = _either.oneOf;
-
-var _fail = require("./stdlib/fail");
-
-exports.fail = _fail.fail;
-
-var _instanceOf = require("./stdlib/instanceOf");
-
-exports.instanceOf = _instanceOf.instanceOf;
-
-var _json = require("./stdlib/json");
-
-exports.json = _json.json;
-exports.jsonObject = _json.jsonObject;
-exports.jsonArray = _json.jsonArray;
-
-var _lazy = require("./stdlib/lazy");
-
-exports.lazy = _lazy.lazy;
-
-var _mapping = require("./stdlib/mapping");
-
-exports.mapping = _mapping.mapping;
-exports.dict = _mapping.dict;
-
-var _number = require("./stdlib/number");
-
-exports.integer = _number.integer;
-exports.number = _number.number;
-exports.positiveInteger = _number.positiveInteger;
-exports.positiveNumber = _number.positiveNumber;
-
-var _object = require("./stdlib/object");
-
-exports.exact = _object.exact;
-exports.inexact = _object.inexact;
-exports.object = _object.object;
-exports.pojo = _object.pojo;
-
-var _optional = require("./stdlib/optional");
-
-exports.maybe = _optional.maybe;
-exports.nullable = _optional.nullable;
-exports.optional = _optional.optional;
-
-var _string = require("./stdlib/string");
-
-exports.email = _string.email;
-exports.nonEmptyString = _string.nonEmptyString;
-exports.regex = _string.regex;
-exports.string = _string.string;
-exports.url = _string.url;
-
-var _tuple = require("./stdlib/tuple");
-
-exports.tuple1 = _tuple.tuple1;
-exports.tuple2 = _tuple.tuple2;
-exports.tuple3 = _tuple.tuple3;
-exports.tuple4 = _tuple.tuple4;
-exports.tuple5 = _tuple.tuple5;
-exports.tuple6 = _tuple.tuple6;

package/cjs/index.js.flow

@@ -1,63 +0,0 @@
-// @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 './stdlib/json';
-
-export { guard } from './_guard';
-
-export { compose, map, predicate } from './stdlib/composition';
-
-export { array, nonEmptyArray, poja } from './stdlib/array';
-export { boolean, numericBoolean, truthy } from './stdlib/boolean';
-export {
-    constant,
-    hardcoded,
-    mixed,
-    null_,
-    undefined_,
-    unknown,
-} from './stdlib/constants';
-export { date, iso8601 } from './stdlib/date';
-export { describe } from './stdlib/describe';
-export { dispatch } from './stdlib/dispatch';
-export {
-    either,
-    either3,
-    either4,
-    either5,
-    either6,
-    either7,
-    either8,
-    either9,
-    oneOf,
-} from './stdlib/either';
-export { fail } from './stdlib/fail';
-export { instanceOf } from './stdlib/instanceOf';
-export { json, jsonObject, jsonArray } from './stdlib/json';
-export { lazy } from './stdlib/lazy';
-export { mapping, dict } from './stdlib/mapping';
-export { integer, number, positiveInteger, positiveNumber } from './stdlib/number';
-export { exact, inexact, object, pojo } from './stdlib/object';
-export { maybe, nullable, optional } from './stdlib/optional';
-export { email, nonEmptyString, regex, string, url } from './stdlib/string';
-export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './stdlib/tuple';