decoders 1.26.0-beta2 → 2.0.0-beta11

package/CHANGELOG.md

@@ -1,6 +1,52 @@
-## v1.26.0-beta1
-
--   Include ES modules in published NPM builds
+## v2.0.0-beta
+
+This is a breaking change, which brings numerous benefits including speed, bundle size,
+and simplicity. Please see the [migration guide](./MIGRATING-v2.md) for instructions on
+how to adjust your code.
+
+Potentially breaking changes:
+
+-   Drop support for all Node versions below 12.x
+-   Drop support for Flow versions below 0.142.0
+-   Drop support for TypeScript versions below 4.1.0
+-   Drop all package dependencies
+-   Removed decoders:
+    -   `guard()` no longer exists, see
+        [migration instructions](./MIGRATING-v2.md#guards-are-no-longer-a-thing)
+    -   `eitherN()` (now simply `either()`, see
+        [migration instructions](./MIGRATING-v2.md#eitherN-is-now-simply-either))
+    -   `tupleN()` (now simply `tuple()`, see
+        [migration instructions](./MIGRATING-v2.md#tupleN-is-now-simply-tuple))
+-   Renamed decoders:
+    -   `map()` → `transform()` - see
+        [migration instructions](./MIGRATING-v2.md#map-is-now-transform)
+    -   `dispatch()` → `taggedUnion()` - see
+        [migration instructions](./MIGRATING-v2.md#dispatch-is-now-taggedUnion)
+-   Decoders that have changed:
+    -   API of `predicate()` has changed - see
+        [migration instructions](./MIGRATING-v2.md#predicate-is-now-a-first-class-citizen)
+    -   API of `url` decoder has changed - see
+        [migration instructions](./MIGRATING-v2.md#url-decoder-has-changed)
+
+New features:
+
+-   Include ES modules in published NPM builds (yay tree-shaking! 🍃)
+-   Much smaller total bundle size
+-   New decoders:
+    -   [`always`](https://nvie.com/decoders/api#always)
+    -   [`never`](https://nvie.com/decoders/api#never)
+    -   [`prep()`](https://nvie.com/decoders/api#prep)
+    -   [`set()`](https://nvie.com/decoders/api#set)
+    -   [`uuidv1`](https://nvie.com/decoders/api#uuidv1)
+    -   [`uuidv4`](https://nvie.com/decoders/api#uuidv4)
+    -   [`uuid`](https://nvie.com/decoders/api#uuid)
+-   Better error messages for nested `either`s
+-   Guard API now has a simpler way to specify formatters
+
+Implementation changes:
+
+-   Major reorganization of internal module structure
+-   Various simplification of internals
 
 ## v1.25.5
 
@@ -326,7 +372,7 @@ to upgrade:
     ```javascript
     const mydecoder: Decoder<string> = predicate(
         (s) => s.startsWith('x'),
-        'Must start with "x"'
+        'Must start with "x"',
     );
     ```
 
@@ -336,7 +382,7 @@ to upgrade:
     const mydecoder: Decoder<string, string> = predicate(
         //                               ^^^^^^ Provide the input type to predicate() decoders
         (s) => s.startsWith('x'),
-        'Must start with "x"'
+        'Must start with "x"',
     );
     ```
 
@@ -560,6 +606,6 @@ to upgrade:
         object({
             name: string,
             age: number,
-        })
+        }),
     );
     ```

package/Decoder.d.ts

@@ -0,0 +1,28 @@
+import { Annotation } from './annotate';
+import { Result } from './result';
+
+export type Scalar = string | number | boolean | symbol | undefined | null;
+
+export type DecodeResult<T> = Result<T, Annotation>;
+export type DecodeFn<T, I = unknown> = (
+    blob: I,
+    ok: (value: T) => DecodeResult<T>,
+    err: (msg: string | Annotation) => DecodeResult<T>,
+) => DecodeResult<T>;
+
+export interface Decoder<T> {
+    verify(blob: unknown, formatterFn?: (ann: Annotation) => string): T;
+    value(blob: unknown): T | undefined;
+    decode(blob: unknown): DecodeResult<T>;
+    refine<N extends T>(predicate: (value: T) => value is N, msg: string): Decoder<N>;
+    refine(predicate: (value: T) => boolean, msg: string): Decoder<T>;
+    reject(rejectFn: (value: T) => string | Annotation | null): Decoder<T>;
+    transform<V>(transformFn: (value: T) => V): Decoder<V>;
+    describe(message: string): Decoder<T>;
+    then<V>(nextDecodeFn: DecodeFn<V, T>): Decoder<V>;
+    peek<V>(nextDecodeFn: DecodeFn<V, [unknown, T]>): Decoder<V>;
+}
+
+export type DecoderType<T> = T extends Decoder<infer V> ? V : never;
+
+export function define<T>(fn: DecodeFn<T>): Decoder<T>;

package/Decoder.js

@@ -0,0 +1,213 @@
+"use strict";
+
+exports.__esModule = true;
+exports.define = define;
+
+var _annotate = require("./annotate");
+
+var _format = require("./format");
+
+var _result = require("./result");
+
+function noThrow(fn) {
+  return function (t) {
+    try {
+      var v = fn(t);
+      return (0, _result.ok)(v);
+    } catch (e) {
+      return (0, _result.err)((0, _annotate.annotate)(t, e instanceof Error ? e.message : String(e)));
+    }
+  };
+}
+/**
+ * Defines a new `Decoder<T>`, by implementing a custom acceptance function.
+ * The function receives three arguments:
+ *
+ * 1. `blob` - the raw/unknown input (aka your external data)
+ * 2. `ok` - Call `ok(value)` to accept the input and return ``value``
+ * 3. `err` - Call `err(message)` to reject the input and use "message" in the
+ *    annotation
+ *
+ * The expected return value should be a `DecodeResult<T>`, which can be
+ * obtained by returning the result from the provided `ok` or `err` helper
+ * functions.
+ */
+
+
+function define(decodeFn) {
+  /**
+   * Validates the raw/untrusted/unknown input and either accepts or rejects
+   * it.
+   *
+   * Contrasted with `.verify()`, calls to `.decode()` will never fail and
+   * instead return a result type.
+   */
+  function decode(blob) {
+    return decodeFn(blob, _result.ok, function (msg) {
+      return (0, _result.err)(typeof msg === 'string' ? (0, _annotate.annotate)(blob, msg) : msg);
+    });
+  }
+  /**
+   * Verified the (raw/untrusted/unknown) input and either accepts or rejects
+   * it. When accepted, returns the decoded `T` value directly. Otherwise
+   * fail with a runtime error.
+   */
+
+
+  function verify(blob, formatter) {
+    if (formatter === void 0) {
+      formatter = _format.formatInline;
+    }
+
+    var result = decode(blob);
+
+    if (result.ok) {
+      return result.value;
+    } else {
+      var _err = new Error('\n' + formatter(result.error));
+
+      _err.name = 'Decoding error';
+      throw _err;
+    }
+  }
+  /**
+   * Verified the (raw/untrusted/unknown) input and either accepts or rejects
+   * it. When accepted, returns the decoded `T` value directly. Otherwise
+   * returns `undefined`.
+   *
+   * Use this when you're not interested in programmatically handling the
+   * error message.
+   */
+
+
+  function value(blob) {
+    return decode(blob).value;
+  }
+  /**
+   * Accepts any value the given decoder accepts, and on success, will call
+   * the given function **on the decoded result**. If the transformation
+   * function throws an error, the whole decoder will fail using the error
+   * message as the failure reason.
+   */
+
+
+  function transform(transformFn) {
+    return then(noThrow(transformFn));
+  }
+  /**
+   * Adds an extra predicate to a decoder. The new decoder is like the
+   * original decoder, but only accepts values that also meet the
+   * predicate.
+   */
+
+
+  function refine(predicateFn, errmsg) {
+    return reject(function (value) {
+      return predicateFn(value) ? // Don't reject
+      null : // Reject with the given error message
+      errmsg;
+    });
+  }
+  /**
+   * Chain together the current decoder with another.
+   *
+   * First, the current decoder must accept the input. If so, it will pass
+   * the successfully decoded result to the given ``next`` function to
+   * further decide whether or not the value should get accepted or rejected.
+   *
+   * The argument to `.then()` is a decoding function, just like one you
+   * would pass to `define()`. The key difference with `define()` is that
+   * `define()` must always assume an ``unknown`` input, whereas with
+   * a `.then()` call the provided ``next`` function will receive a ``T`` as
+   * its input. This will allow the function to make a stronger assumption
+   * about its input.
+   *
+   * If it helps, you can think of `define(nextFn)` as equivalent to
+   * `unknown.then(nextFn)`.
+   *
+   * This is an advanced, low-level, decoder. It's not recommended to reach
+   * for this low-level construct when implementing custom decoders. Most
+   * cases can be covered by `.transform()` or `.refine()`.
+   */
+
+
+  function then(next) {
+    return define(function (blob, ok, err) {
+      var result = decode(blob);
+      return result.ok ? next(result.value, ok, err) : result;
+    });
+  }
+  /**
+   * Adds an extra predicate to a decoder. The new decoder is like the
+   * original decoder, but only accepts values that aren't rejected by the
+   * given function.
+   *
+   * The given function can return `null` to accept the decoded value, or
+   * return a specific error message to reject.
+   *
+   * Unlike `.refine()`, you can use this function to return a dynamic error
+   * message.
+   */
+
+
+  function reject(rejectFn) {
+    return then(function (value, ok, err) {
+      var errmsg = rejectFn(value);
+      return errmsg === null ? ok(value) : err(typeof errmsg === 'string' ? (0, _annotate.annotate)(value, errmsg) : errmsg);
+    });
+  }
+  /**
+   * Uses the given decoder, but will use an alternative error message in
+   * case it rejects. This can be used to simplify or shorten otherwise
+   * long or low-level/technical errors.
+   */
+
+
+  function describe(message) {
+    return define(function (blob, _, err) {
+      // Decode using the given decoder...
+      var result = decode(blob);
+
+      if (result.ok) {
+        return result;
+      } else {
+        // ...but in case of error, annotate this with the custom given
+        // message instead
+        return err((0, _annotate.annotate)(result.error, message));
+      }
+    });
+  }
+  /**
+   * WARNING: This is an EXPERIMENTAL API that will likely change in the
+   * future. Please DO NOT rely on it.
+   *
+   * Chain together the current decoder with another, but also pass along
+   * the original input.
+   *
+   * This is like `.then()`, but instead of this function receiving just
+   * the decoded result ``T``, it also receives the original input.
+   *
+   * This is an advanced, low-level, decoder.
+   */
+
+
+  function peek_UNSTABLE(next) {
+    return define(function (blob, ok, err) {
+      var result = decode(blob);
+      return result.ok ? next([blob, result.value], ok, err) : result;
+    });
+  }
+
+  return Object.freeze({
+    verify: verify,
+    value: value,
+    decode: decode,
+    transform: transform,
+    refine: refine,
+    reject: reject,
+    describe: describe,
+    then: then,
+    // EXPERIMENTAL - please DO NOT rely on this method
+    peek_UNSTABLE: peek_UNSTABLE
+  });
+}

package/Decoder.js.flow

@@ -0,0 +1,238 @@
+// @flow strict
+
+import { annotate } from './annotate';
+import { formatInline } from './format';
+import { err as makeErr, ok as makeOk } from './result';
+import type { Annotation } from './annotate';
+import type { Result } from './result';
+
+export type Scalar = string | number | boolean | symbol | void | null;
+
+export type DecodeResult<T> = Result<T, Annotation>;
+export type DecodeFn<T, I = mixed> = (
+    blob: I,
+    ok: (value: T) => DecodeResult<T>,
+    err: (msg: string | Annotation) => DecodeResult<T>,
+) => DecodeResult<T>;
+
+/**
+ * Helper type to return the "type" of a Decoder.
+ *
+ * You can use it on types:
+ *
+ *   DecoderType<Decoder<string>>       // => string
+ *   DecoderType<Decoder<number[]>>     // => number[]
+ *
+ * Or on "values", by using the `typeof` keyword:
+ *
+ *   DecoderType<typeof array(string)>  // => string[]
+ *   DecoderType<typeof truthy>         // => boolean
+ *
+ */
+export type DecoderType<D> = $Call<<T>(Decoder<T>) => T, D>;
+
+export type Decoder<T> = {|
+    verify(blob: mixed, formatterFn?: (Annotation) => string): T,
+    value(blob: mixed): T | void,
+    decode(blob: mixed): DecodeResult<T>,
+    refine(predicateFn: (value: T) => boolean, errmsg: string): Decoder<T>,
+    reject(rejectFn: (value: T) => string | Annotation | null): Decoder<T>,
+    transform<V>(transformFn: (value: T) => V): Decoder<V>,
+    describe(message: string): Decoder<T>,
+    then<V>(next: DecodeFn<V, T>): Decoder<V>,
+
+    // Experimental APIs (please don't rely on these yet)
+    peek_UNSTABLE<V>(next: DecodeFn<V, [mixed, T]>): Decoder<V>,
+|};
+
+function noThrow<T, V>(fn: (value: T) => V): (T) => DecodeResult<V> {
+    return (t) => {
+        try {
+            const v = fn(t);
+            return makeOk(v);
+        } catch (e) {
+            return makeErr(annotate(t, e instanceof Error ? e.message : String(e)));
+        }
+    };
+}
+
+/**
+ * Defines a new `Decoder<T>`, by implementing a custom acceptance function.
+ * The function receives three arguments:
+ *
+ * 1. `blob` - the raw/unknown input (aka your external data)
+ * 2. `ok` - Call `ok(value)` to accept the input and return ``value``
+ * 3. `err` - Call `err(message)` to reject the input and use "message" in the
+ *    annotation
+ *
+ * The expected return value should be a `DecodeResult<T>`, which can be
+ * obtained by returning the result from the provided `ok` or `err` helper
+ * functions.
+ */
+export function define<T>(decodeFn: DecodeFn<T>): Decoder<T> {
+    /**
+     * Validates the raw/untrusted/unknown input and either accepts or rejects
+     * it.
+     *
+     * Contrasted with `.verify()`, calls to `.decode()` will never fail and
+     * instead return a result type.
+     */
+    function decode(blob: mixed): DecodeResult<T> {
+        return decodeFn(blob, makeOk, (msg: Annotation | string) =>
+            makeErr(typeof msg === 'string' ? annotate(blob, msg) : msg),
+        );
+    }
+
+    /**
+     * Verified the (raw/untrusted/unknown) input and either accepts or rejects
+     * it. When accepted, returns the decoded `T` value directly. Otherwise
+     * fail with a runtime error.
+     */
+    function verify(blob: mixed, formatter: (Annotation) => string = formatInline): T {
+        const result = decode(blob);
+        if (result.ok) {
+            return result.value;
+        } else {
+            const err = new Error('\n' + formatter(result.error));
+            err.name = 'Decoding error';
+            throw err;
+        }
+    }
+
+    /**
+     * Verified the (raw/untrusted/unknown) input and either accepts or rejects
+     * it. When accepted, returns the decoded `T` value directly. Otherwise
+     * returns `undefined`.
+     *
+     * Use this when you're not interested in programmatically handling the
+     * error message.
+     */
+    function value(blob: mixed): T | void {
+        return decode(blob).value;
+    }
+
+    /**
+     * Accepts any value the given decoder accepts, and on success, will call
+     * the given function **on the decoded result**. If the transformation
+     * function throws an error, the whole decoder will fail using the error
+     * message as the failure reason.
+     */
+    function transform<V>(transformFn: (T) => V): Decoder<V> {
+        return then(noThrow(transformFn));
+    }
+
+    /**
+     * Adds an extra predicate to a decoder. The new decoder is like the
+     * original decoder, but only accepts values that also meet the
+     * predicate.
+     */
+    function refine(predicateFn: (value: T) => boolean, errmsg: string): Decoder<T> {
+        return reject((value) =>
+            predicateFn(value)
+                ? // Don't reject
+                  null
+                : // Reject with the given error message
+                  errmsg,
+        );
+    }
+
+    /**
+     * Chain together the current decoder with another.
+     *
+     * First, the current decoder must accept the input. If so, it will pass
+     * the successfully decoded result to the given ``next`` function to
+     * further decide whether or not the value should get accepted or rejected.
+     *
+     * The argument to `.then()` is a decoding function, just like one you
+     * would pass to `define()`. The key difference with `define()` is that
+     * `define()` must always assume an ``unknown`` input, whereas with
+     * a `.then()` call the provided ``next`` function will receive a ``T`` as
+     * its input. This will allow the function to make a stronger assumption
+     * about its input.
+     *
+     * If it helps, you can think of `define(nextFn)` as equivalent to
+     * `unknown.then(nextFn)`.
+     *
+     * This is an advanced, low-level, decoder. It's not recommended to reach
+     * for this low-level construct when implementing custom decoders. Most
+     * cases can be covered by `.transform()` or `.refine()`.
+     */
+    function then<V>(next: DecodeFn<V, T>): Decoder<V> {
+        return define((blob, ok, err) => {
+            const result = decode(blob);
+            return result.ok ? next(result.value, ok, err) : result;
+        });
+    }
+
+    /**
+     * Adds an extra predicate to a decoder. The new decoder is like the
+     * original decoder, but only accepts values that aren't rejected by the
+     * given function.
+     *
+     * The given function can return `null` to accept the decoded value, or
+     * return a specific error message to reject.
+     *
+     * Unlike `.refine()`, you can use this function to return a dynamic error
+     * message.
+     */
+    function reject(rejectFn: (value: T) => string | Annotation | null): Decoder<T> {
+        return then((value, ok, err) => {
+            const errmsg = rejectFn(value);
+            return errmsg === null
+                ? ok(value)
+                : err(typeof errmsg === 'string' ? annotate(value, errmsg) : errmsg);
+        });
+    }
+
+    /**
+     * Uses the given decoder, but will use an alternative error message in
+     * case it rejects. This can be used to simplify or shorten otherwise
+     * long or low-level/technical errors.
+     */
+    function describe(message: string): Decoder<T> {
+        return define((blob, _, err) => {
+            // Decode using the given decoder...
+            const result = decode(blob);
+            if (result.ok) {
+                return result;
+            } else {
+                // ...but in case of error, annotate this with the custom given
+                // message instead
+                return err(annotate(result.error, message));
+            }
+        });
+    }
+
+    /**
+     * WARNING: This is an EXPERIMENTAL API that will likely change in the
+     * future. Please DO NOT rely on it.
+     *
+     * Chain together the current decoder with another, but also pass along
+     * the original input.
+     *
+     * This is like `.then()`, but instead of this function receiving just
+     * the decoded result ``T``, it also receives the original input.
+     *
+     * This is an advanced, low-level, decoder.
+     */
+    function peek_UNSTABLE<V>(next: DecodeFn<V, [mixed, T]>): Decoder<V> {
+        return define((blob, ok, err) => {
+            const result = decode(blob);
+            return result.ok ? next([blob, result.value], ok, err) : result;
+        });
+    }
+
+    return Object.freeze({
+        verify,
+        value,
+        decode,
+        transform,
+        refine,
+        reject,
+        describe,
+        then,
+
+        // EXPERIMENTAL - please DO NOT rely on this method
+        peek_UNSTABLE,
+    });
+}