decoders 2.0.0-beta9 → 2.0.0

package/core/composition.js

@@ -1,82 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.compose = compose;
-exports.predicate = predicate;
-exports.prep = prep;
-exports.transform = transform;
-
-var _result = require("../result");
-
-var _annotate = require("../annotate");
-
-/**
- * Accepts any value the given decoder accepts, and on success, will call the
- * mapper value **on the decoded result**. If the mapper function throws an
- * error, the whole decoder will fail using the error message as the failure
- * reason.
- */
-function transform(decoder, transformFn) {
-  return compose(decoder, function (x) {
-    try {
-      return (0, _result.ok)(transformFn(x));
-    } catch (e) {
-      return (0, _result.err)((0, _annotate.annotate)(x, e instanceof Error ? e.message : String(e)));
-    }
-  });
-}
-/**
- * Compose two decoders by passing the result of the first into the second.
- * The second decoder may assume as its input type the output type of the first
- * decoder (so it's not necessary to accept the typical "mixed").  This is
- * useful for "narrowing down" the checks.  For example, if you want to write
- * a decoder for positive numbers, you can compose it from an existing decoder
- * for any number, and a decoder that, assuming a number, checks if it's
- * positive.  Very often combined with the predicate() helper as the second
- * argument.
- */
-
-
-function compose(decoder, next) {
-  return function (blob) {
-    return (0, _result.andThen)(decoder(blob), next);
-  };
-}
-/**
- * Factory function returning a Decoder<T>, given a predicate function that
- * accepts/rejects the input of type T.
- */
-
-
-function predicate(decoder, predicateFn, msg) {
-  return function (blob) {
-    return (0, _result.andThen)(decoder(blob), function (value) {
-      return predicateFn(value) ? (0, _result.ok)(value) : (0, _result.err)((0, _annotate.annotate)(value, msg));
-    });
-  };
-}
-/**
- * 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 function (blob) {
-    var blob2;
-
-    try {
-      blob2 = mapperFn(blob);
-    } catch (e) {
-      return (0, _result.err)((0, _annotate.annotate)(blob, e.message));
-    }
-
-    return (0, _result.orElse)(decoder(blob2), function (ann) {
-      return (0, _result.err)((0, _annotate.annotate)(blob, ann.text));
-    } //                    ^^^^ Annotates the _original_ input value
-    //                         (instead of echoing back blob2 in the output)
-    );
-  };
-}

package/core/composition.js.flow

@@ -1,74 +0,0 @@
-// @flow strict
-
-import { andThen, err, ok, orElse } from '../result';
-import { annotate } from '../annotate';
-import type { Decoder } from '../_types';
-
-/**
- * Accepts any value the given decoder accepts, and on success, will call the
- * mapper value **on the decoded result**. If the mapper function throws an
- * error, the whole decoder will fail using the error message as the failure
- * reason.
- */
-export function transform<T, V>(decoder: Decoder<T>, transformFn: (T) => V): Decoder<V> {
-    return compose(decoder, (x) => {
-        try {
-            return ok(transformFn(x));
-        } catch (e) {
-            return err(annotate(x, e instanceof Error ? e.message : String(e)));
-        }
-    });
-}
-
-/**
- * Compose two decoders by passing the result of the first into the second.
- * The second decoder may assume as its input type the output type of the first
- * decoder (so it's not necessary to accept the typical "mixed").  This is
- * useful for "narrowing down" the checks.  For example, if you want to write
- * a decoder for positive numbers, you can compose it from an existing decoder
- * for any number, and a decoder that, assuming a number, checks if it's
- * positive.  Very often combined with the predicate() helper as the second
- * argument.
- */
-export function compose<T, V>(decoder: Decoder<T>, next: Decoder<V, T>): Decoder<V> {
-    return (blob: mixed) => andThen(decoder(blob), next);
-}
-
-/**
- * Factory function returning a Decoder<T>, given a predicate function that
- * accepts/rejects the input of type T.
- */
-export function predicate<T>(
-    decoder: Decoder<T>,
-    predicateFn: (T) => boolean,
-    msg: string,
-): Decoder<T> {
-    return (blob: mixed) =>
-        andThen(decoder(blob), (value) =>
-            predicateFn(value) ? ok(value) : err(annotate(value, msg)),
-        );
-}
-
-/**
- * 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<I, T>(mapperFn: (mixed) => I, decoder: Decoder<T, I>): Decoder<T> {
-    return (blob: mixed) => {
-        let blob2;
-        try {
-            blob2 = mapperFn(blob);
-        } catch (e) {
-            return err(annotate(blob, e.message));
-        }
-
-        return orElse(
-            decoder(blob2),
-            (ann) => err(annotate(blob, ann.text)),
-            //                    ^^^^ Annotates the _original_ input value
-            //                         (instead of echoing back blob2 in the output)
-        );
-    };
-}

package/core/composition.mjs

@@ -1,70 +0,0 @@
-import { andThen, err, ok, orElse } from '../result.mjs';
-import { annotate } from '../annotate.mjs';
-
-/**
- * Accepts any value the given decoder accepts, and on success, will call the
- * mapper value **on the decoded result**. If the mapper function throws an
- * error, the whole decoder will fail using the error message as the failure
- * reason.
- */
-export function transform(decoder, transformFn) {
-  return compose(decoder, function (x) {
-    try {
-      return ok(transformFn(x));
-    } catch (e) {
-      return err(annotate(x, e instanceof Error ? e.message : String(e)));
-    }
-  });
-}
-/**
- * Compose two decoders by passing the result of the first into the second.
- * The second decoder may assume as its input type the output type of the first
- * decoder (so it's not necessary to accept the typical "mixed").  This is
- * useful for "narrowing down" the checks.  For example, if you want to write
- * a decoder for positive numbers, you can compose it from an existing decoder
- * for any number, and a decoder that, assuming a number, checks if it's
- * positive.  Very often combined with the predicate() helper as the second
- * argument.
- */
-
-export function compose(decoder, next) {
-  return function (blob) {
-    return andThen(decoder(blob), next);
-  };
-}
-/**
- * Factory function returning a Decoder<T>, given a predicate function that
- * accepts/rejects the input of type T.
- */
-
-export function predicate(decoder, predicateFn, msg) {
-  return function (blob) {
-    return andThen(decoder(blob), function (value) {
-      return predicateFn(value) ? ok(value) : err(annotate(value, msg));
-    });
-  };
-}
-/**
- * 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 function (blob) {
-    var blob2;
-
-    try {
-      blob2 = mapperFn(blob);
-    } catch (e) {
-      return err(annotate(blob, e.message));
-    }
-
-    return orElse(decoder(blob2), function (ann) {
-      return err(annotate(blob, ann.text));
-    } //                    ^^^^ Annotates the _original_ input value
-    //                         (instead of echoing back blob2 in the output)
-    );
-  };
-}

package/core/constants.d.ts

@@ -1,11 +0,0 @@
-import { Decoder, Scalar } from '../_types';
-
-// Constants
-
-export const null_: Decoder<null>;
-export const undefined_: Decoder<undefined>;
-export function constant<T extends Scalar>(value: T): Decoder<T>;
-export function hardcoded<T extends Scalar>(value: T): Decoder<T>;
-export function hardcoded<T>(value: T): Decoder<T>;
-export const mixed: Decoder<unknown>;
-export const unknown: Decoder<unknown>;

package/core/constants.js

@@ -1,65 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.constant = constant;
-exports.hardcoded = hardcoded;
-exports.unknown = exports.undefined_ = exports.null_ = exports.mixed = void 0;
-
-var _annotate = require("../annotate");
-
-var _result = require("../result");
-
-/**
- * Decoder that only returns Ok for `null` inputs.  Err otherwise.
- */
-var null_ = function null_(blob) {
-  return blob === null ? (0, _result.ok)(blob) : (0, _result.err)((0, _annotate.annotate)(blob, 'Must be null'));
-};
-/**
- * Decoder that only returns Ok for `undefined` inputs.  Err otherwise.
- */
-
-
-exports.null_ = null_;
-
-var undefined_ = function undefined_(blob) {
-  return blob === undefined ? (0, _result.ok)(blob) : (0, _result.err)((0, _annotate.annotate)(blob, 'Must be undefined'));
-};
-/**
- * Decoder that only returns Ok for the given value constant.  Err otherwise.
- */
-
-
-exports.undefined_ = undefined_;
-
-function constant(value) {
-  return function (blob) {
-    return blob === value ? (0, _result.ok)(value) : (0, _result.err)((0, _annotate.annotate)(blob, "Must be constant " + String(value)));
-  };
-}
-/**
- * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
- */
-
-
-function hardcoded(value) {
-  return function () {
-    return (0, _result.ok)(value);
-  };
-}
-/**
- * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
- */
-
-
-var unknown = function unknown(blob) {
-  return (0, _result.ok)(blob);
-};
-/**
- * Alias of unknown.
- */
-
-
-exports.unknown = unknown;
-var mixed = unknown;
-exports.mixed = mixed;

package/core/constants.js.flow

@@ -1,44 +0,0 @@
-// @flow strict
-
-import { annotate } from '../annotate';
-import { err, ok } from '../result';
-import type { Decoder, Scalar } from '../_types';
-
-/**
- * Decoder that only returns Ok for `null` inputs.  Err otherwise.
- */
-export const null_: Decoder<null> = (blob: mixed) =>
-    blob === null ? ok(blob) : err(annotate(blob, 'Must be null'));
-
-/**
- * Decoder that only returns Ok for `undefined` inputs.  Err otherwise.
- */
-export const undefined_: Decoder<void> = (blob: mixed) =>
-    blob === undefined ? ok(blob) : err(annotate(blob, 'Must be undefined'));
-
-/**
- * Decoder that only returns Ok for the given value constant.  Err otherwise.
- */
-export function constant<T: Scalar>(value: T): Decoder<T> {
-    return (blob: mixed) =>
-        blob === value
-            ? ok(value)
-            : err(annotate(blob, `Must be constant ${String(value)}`));
-}
-
-/**
- * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
- */
-export function hardcoded<T>(value: T): Decoder<T> {
-    return () => ok(value);
-}
-
-/**
- * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
- */
-export const unknown: Decoder<mixed> = (blob: mixed) => ok(blob);
-
-/**
- * Alias of unknown.
- */
-export const mixed: Decoder<mixed> = unknown;

package/core/constants.mjs

@@ -1,46 +0,0 @@
-import { annotate } from '../annotate.mjs';
-import { err, ok } from '../result.mjs';
-
-/**
- * Decoder that only returns Ok for `null` inputs.  Err otherwise.
- */
-export var null_ = function null_(blob) {
-  return blob === null ? ok(blob) : err(annotate(blob, 'Must be null'));
-};
-/**
- * Decoder that only returns Ok for `undefined` inputs.  Err otherwise.
- */
-
-export var undefined_ = function undefined_(blob) {
-  return blob === undefined ? ok(blob) : err(annotate(blob, 'Must be undefined'));
-};
-/**
- * Decoder that only returns Ok for the given value constant.  Err otherwise.
- */
-
-export function constant(value) {
-  return function (blob) {
-    return blob === value ? ok(value) : err(annotate(blob, "Must be constant " + String(value)));
-  };
-}
-/**
- * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
- */
-
-export function hardcoded(value) {
-  return function () {
-    return ok(value);
-  };
-}
-/**
- * Decoder that always returns Ok for the given hardcoded value, no matter what the input.
- */
-
-export var unknown = function unknown(blob) {
-  return ok(blob);
-};
-/**
- * Alias of unknown.
- */
-
-export var mixed = unknown;

package/core/date.d.ts

@@ -1,4 +0,0 @@
-import { Decoder } from '../_types';
-
-export const date: Decoder<Date>;
-export const iso8601: Decoder<Date>;

package/core/date.js

@@ -1,42 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.iso8601 = exports.date = void 0;
-
-var _annotate = require("../annotate");
-
-var _result = require("../result");
-
-var _utils = require("../_utils");
-
-var _string = require("./string");
-
-var _composition = require("./composition");
-
-// Only matches the shape.  This "over-matches" some values that still aren't
-// valid dates (like 9999-99-99), but those will be caught by JS Date's
-// internal validations
-var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
-
-var date = function date(value) {
-  return (0, _utils.isDate)(value) ? (0, _result.ok)(value) : (0, _result.err)((0, _annotate.annotate)(value, 'Must be a Date'));
-};
-/**
- * Decoder that only returns Ok for strings that are valid ISO8601 date
- * strings.  Err otherwise.
- */
-
-
-exports.date = date;
-var iso8601 = (0, _composition.transform)( // Input itself needs to match the ISO8601 regex...
-(0, _string.regex)(iso8601_re, 'Must be ISO8601 format'), // Make sure it is a _valid_ date
-function (value) {
-  var date = new Date(value);
-
-  if (isNaN(date.getTime())) {
-    throw new Error('Must be valid date/time value');
-  }
-
-  return date;
-});
-exports.iso8601 = iso8601;

package/core/date.js.flow

@@ -1,38 +0,0 @@
-// @flow strict
-
-import { annotate } from '../annotate';
-import { err, ok } from '../result';
-import { isDate } from '../_utils';
-import { regex } from './string';
-import { transform } from './composition';
-import type { Decoder } from '../_types';
-
-// $FlowFixMe[unclear-type] (not really an issue) - deliberate casting
-type cast = any;
-
-// Only matches the shape.  This "over-matches" some values that still aren't
-// valid dates (like 9999-99-99), but those will be caught by JS Date's
-// internal validations
-const iso8601_re =
-    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
-
-export const date: Decoder<Date> = (value: mixed) =>
-    isDate(value) ? ok(((value: cast): Date)) : err(annotate(value, 'Must be a Date'));
-
-/**
- * Decoder that only returns Ok for strings that are valid ISO8601 date
- * strings.  Err otherwise.
- */
-export const iso8601: Decoder<Date> = transform(
-    // Input itself needs to match the ISO8601 regex...
-    regex(iso8601_re, 'Must be ISO8601 format'),
-
-    // Make sure it is a _valid_ date
-    (value: string) => {
-        const date = new Date(value);
-        if (isNaN(date.getTime())) {
-            throw new Error('Must be valid date/time value');
-        }
-        return date;
-    },
-);

package/core/date.mjs

@@ -1,28 +0,0 @@
-import { annotate } from '../annotate.mjs';
-import { err, ok } from '../result.mjs';
-import { isDate } from '../_utils.mjs';
-import { regex } from './string.mjs';
-import { transform } from './composition.mjs';
-// Only matches the shape.  This "over-matches" some values that still aren't
-// valid dates (like 9999-99-99), but those will be caught by JS Date's
-// internal validations
-var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
-export var date = function date(value) {
-  return isDate(value) ? ok(value) : err(annotate(value, 'Must be a Date'));
-};
-/**
- * Decoder that only returns Ok for strings that are valid ISO8601 date
- * strings.  Err otherwise.
- */
-
-export var iso8601 = transform( // Input itself needs to match the ISO8601 regex...
-regex(iso8601_re, 'Must be ISO8601 format'), // Make sure it is a _valid_ date
-function (value) {
-  var date = new Date(value);
-
-  if (isNaN(date.getTime())) {
-    throw new Error('Must be valid date/time value');
-  }
-
-  return date;
-});

package/core/describe.d.ts

@@ -1,3 +0,0 @@
-import { Decoder } from '../_types';
-
-export function describe<T>(decoder: Decoder<T>, msg: string): Decoder<T>;

package/core/describe.js

@@ -1,22 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.describe = describe;
-
-var _annotate = require("../annotate");
-
-var _result = require("../result");
-
-/**
- * Wrap another decoder, and override the error message in case it fails. This
- * is useful to "simplify" otherwise potentially complex error messages, or to
- * use language in those error messages that can be relayed to end users (for
- * example to show in form errors).
- */
-function describe(decoder, message) {
-  return function (blob) {
-    return (0, _result.mapError)(decoder(blob), function (err) {
-      return (0, _annotate.annotate)(err, message);
-    });
-  };
-}

package/core/describe.js.flow

@@ -1,17 +0,0 @@
-// @flow strict
-
-import { annotate } from '../annotate';
-import { mapError } from '../result';
-import type { Decoder } from '../_types';
-
-/**
- * Wrap another decoder, and override the error message in case it fails. This
- * is useful to "simplify" otherwise potentially complex error messages, or to
- * use language in those error messages that can be relayed to end users (for
- * example to show in form errors).
- */
-export function describe<T>(decoder: Decoder<T>, message: string): Decoder<T> {
-    return (blob: mixed) => {
-        return mapError(decoder(blob), (err) => annotate(err, message));
-    };
-}

package/core/describe.mjs

@@ -1,16 +0,0 @@
-import { annotate } from '../annotate.mjs';
-import { mapError } from '../result.mjs';
-
-/**
- * Wrap another decoder, and override the error message in case it fails. This
- * is useful to "simplify" otherwise potentially complex error messages, or to
- * use language in those error messages that can be relayed to end users (for
- * example to show in form errors).
- */
-export function describe(decoder, message) {
-  return function (blob) {
-    return mapError(decoder(blob), function (err) {
-      return annotate(err, message);
-    });
-  };
-}

package/core/dispatch.d.ts

@@ -1,8 +0,0 @@
-import { Decoder, DecoderType } from '../_types';
-
-export type Values<T extends object> = T[keyof T];
-
-export function taggedUnion<O extends { [key: string]: Decoder<any> }>(
-    field: string,
-    mapping: O,
-): Decoder<Values<{ [key in keyof O]: DecoderType<O[key]> }>>;

package/core/dispatch.js

@@ -1,60 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.taggedUnion = taggedUnion;
-
-var _result = require("../result");
-
-var _object2 = require("./object");
-
-var _either = require("./either");
-
-var _composition = require("./composition");
-
-/**
- * Dispatches to one of several given decoders, based on the value found at
- * runtime in the given field.  For example, suppose you have these decoders:
- *
- *     const rectangle = object({
- *         type: constant('rect'),
- *         x: number,
- *         y: number,
- *         width: number,
- *         height: number,
- *     });
- *
- *     const circle = object({
- *         type: constant('circle'),
- *         cx: number,
- *         cy: number,
- *         r: number,
- *      });
- *
- * Then these two decoders are equivalent:
- *
- *     const shape = either(rectangle, circle)
- *     const shape = taggedUnion('type', { rectangle, circle })
- *
- * Will be of type Decoder<Rectangle | Circle>.
- *
- * But `taggedUnion` will typically be more runtime-efficient.  The reason is
- * that it will first do minimal work to "look ahead" into the `type` field
- * here, and based on that value, pick the decoder to invoke.
- *
- * The `either` version will simply try to invoke each decoder, until it finds
- * one that matches.
- *
- * Also, the error messages will be less ambiguous using `taggedUnion()`.
- */
-function taggedUnion(field, mapping) {
-  var _object;
-
-  var base = (0, _object2.object)((_object = {}, _object[field] = (0, _composition.prep)(String, (0, _either.oneOf)(Object.keys(mapping))), _object));
-  return function (blob) {
-    return (0, _result.andThen)(base(blob), function (baseObj) {
-      var decoderName = baseObj[field];
-      var decoder = mapping[decoderName];
-      return decoder(blob);
-    });
-  };
-}