decoders 2.0.0-beta1 → 2.0.0-beta13

package/lib/utilities.d.ts

@@ -0,0 +1,34 @@
+import { Decoder } from '../Decoder';
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+export function instanceOf<T>(klass: new (...args: readonly any[]) => T): Decoder<T>;
+
+/**
+ * Lazily evaluate the given decoder. This is useful to build self-referential
+ * types for recursive data structures.
+ */
+export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;
+
+/**
+ * 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<T>(
+    mapperFn: (blob: unknown) => unknown,
+    decoder: Decoder<T>,
+): Decoder<T>;
+
+/**
+ * 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: string): Decoder<never>;
+
+/**
+ * Alias of never().
+ */
+export function fail(msg: string): Decoder<never>;

package/lib/utilities.js

@@ -0,0 +1,75 @@
+"use strict";
+
+exports.__esModule = true;
+exports.fail = void 0;
+exports.instanceOf = instanceOf;
+exports.lazy = lazy;
+exports.never = never;
+exports.prep = prep;
+
+var _annotate = require("../annotate");
+
+var _Decoder = require("../Decoder");
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+function instanceOf(klass) {
+  return (0, _Decoder.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.
+ */
+
+
+function lazy(decoderFn) {
+  return (0, _Decoder.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.
+ */
+
+
+function prep(mapperFn, decoder) {
+  return (0, _Decoder.define)(function (originalInput, _, err) {
+    var blob;
+
+    try {
+      blob = mapperFn(originalInput);
+    } catch (e) {
+      return err((0, _annotate.annotate)(originalInput, e.message));
+    }
+
+    var r = decoder.decode(blob);
+    return r.ok ? r : err((0, _annotate.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.
+ */
+
+
+function never(msg) {
+  return (0, _Decoder.define)(function (_, __, err) {
+    return err(msg);
+  });
+}
+/**
+ * Alias of never().
+ */
+
+
+var fail = never;
+exports.fail = fail;

package/lib/utilities.js.flow

@@ -0,0 +1,65 @@
+// @flow strict
+
+import { annotate } from '../annotate';
+import { define } from '../Decoder';
+import type { Decoder } from '../Decoder';
+
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+export function instanceOf<T>(klass: Class<T>): Decoder<T> {
+    return define((blob, ok, err) =>
+        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.
+ */
+export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T> {
+    return define((blob) => 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<T>(mapperFn: (mixed) => mixed, decoder: Decoder<T>): Decoder<T> {
+    return define((originalInput, _, err) => {
+        let blob;
+        try {
+            blob = mapperFn(originalInput);
+        } catch (e) {
+            return err(annotate(originalInput, e.message));
+        }
+
+        const 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: string): Decoder<empty> {
+    return define((_, __, err) => err(msg));
+}
+
+/**
+ * Alias of never().
+ */
+export const fail: (msg: string) => Decoder<empty> = never;

package/lib/utilities.mjs

@@ -0,0 +1,60 @@
+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.
+ */
+
+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-beta13",
     "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');
-}