decoders 2.0.0-beta12 → 2.0.0-beta13

package/CHANGELOG.md

@@ -1,47 +1,65 @@
 ## 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.
+This is a breaking change, which brings numerous benefits:
 
-Potentially breaking changes:
+-   A **simpler API** 😇
+-   Smaller **bundle size** (67% reduction 😱)
+-   **Tree-shaking** support 🍃
+-   Runtime **speed** 🏎️
+-   Better documentation 📚
+-   Better support for writing your own decoders 🛠️
+
+Please see the [migration guide](./MIGRATING-v2.md) for precise instructions on how to
+adjust your v1 code.
+
+The main change is the brand new `Decoder<T>` API! The **tl;dr** is:
+
+| Replace this v1 pattern...           |     | ...with this v2 API                        | Notes                                                                        |
+| :----------------------------------- | --- | :----------------------------------------- | :--------------------------------------------------------------------------- |
+| `mydecoder(input)`                   | →   | `mydecoder.decode(input)`                  | [migration instructions](./MIGRATING-v2.md#stop-calling-decoders)            |
+| `guard(mydecoder)(input)`            | →   | `mydecoder.verify(input)`                  | [migration instructions](./MIGRATING-v2.md#guards-are-no-longer-a-thing)     |
+| `map(mydecoder, ...)`                | →   | `mydecoder.transform(...)`                 | [migration instructions](./MIGRATING-v2.md#map-is-now-transform)             |
+| `compose(mydecoder, predicate(...))` | →   | `mydecoder.refine(...)`                    | [migration instructions](./MIGRATING-v2.md#compose--predicate-is-now-refine) |
+| `describe(mydecoder, ...)`           | →   | `mydecoder.describe(...)`                  |                                                                              |
+| `mydecoder(input).value()`           | →   | `mydecoder.value(input)`                   |                                                                              |
+| `either`, `either3`, ..., `either9`  | →   | `either`                                   | [migration instructions](./MIGRATING-v2.md#eitherN-is-now-simply-either)     |
+| `tuple1`, `tuple2`, ... `tuple6`     | →   | `tuple`                                    | [migration instructions](./MIGRATING-v2.md#tupleN-is-now-simply-tuple)       |
+| `dispatch`                           | →   | `taggedUnion`                              | [migration instructions](./MIGRATING-v2.md#dispatch-is-now-taggedUnion)      |
+| `url(...)`                           | →   | `httpsUrl` / `url` (signature has changed) | [migration instructions](./MIGRATING-v2.md#signature-of-url-has-changed)     |
+
+The full documentation is available on [**decoders.cc**](https://decoders.cc).
+
+Other features:
+
+-   Include ES modules in published NPM builds (yay tree-shaking! 🍃)
+-   Much smaller total bundle size (**67% smaller** compared to v1 😱)
+
+Other 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 support for Flow versions below 0.142.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:
+-   Direct reliance on `lemons` has been removed
 
--   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)
+New decoders:
+
+-   [`always`](https://decoders.cc/api.html#always)
+-   [`anyNumber`](https://decoders.cc/api.html#anyNumber)
+-   [`never`](https://decoders.cc/api.html#never)
+-   [`prep()`](https://decoders.cc/api.html#prep)
+-   [`set()`](https://decoders.cc/api.html#set)
+-   [`uuid`](https://decoders.cc/api.html#uuid)
+-   [`uuidv1`](https://decoders.cc/api.html#uuidv1)
+-   [`uuidv4`](https://decoders.cc/api.html#uuidv4)
+
+Other improvements:
+
+-   [`optional()`](https://decoders.cc/api.html#optional),
+    [`nullable()`](https://decoders.cc/api.html#nullable), and
+    [`maybe()`](https://decoders.cc/api.html#maybe) now each take an optional 2nd param to
+    specify a default value
 -   Better error messages for nested `either`s
--   Guard API now has a simpler way to specify formatters
 
 Implementation changes:
 

package/Decoder.d.ts

@@ -4,25 +4,91 @@ 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,
+
+export type AcceptanceFn<T, InputT = unknown> = (
+    blob: InputT,
     ok: (value: T) => DecodeResult<T>,
     err: (msg: string | Annotation) => DecodeResult<T>,
 ) => DecodeResult<T>;
 
 export interface Decoder<T> {
+    /**
+     * Verifies untrusted input. Either returns a value, or throws a decoding
+     * error.
+     */
     verify(blob: unknown, formatterFn?: (ann: Annotation) => string | Error): T;
+
+    /**
+     * Verifies untrusted input. Either returns a value, or returns undefined.
+     */
     value(blob: unknown): T | undefined;
+
+    /**
+     * Verifies untrusted input. Always returns a DecodeResult, which is either
+     * an "ok" value or an "error" annotation.
+     */
     decode(blob: unknown): DecodeResult<T>;
+
+    /**
+     * Build a new decoder from the the current one, with an extra acceptance
+     * criterium.
+     */
     refine<N extends T>(predicate: (value: T) => value is N, msg: string): Decoder<N>;
     refine(predicate: (value: T) => boolean, msg: string): Decoder<T>;
+
+    /**
+     * Build a new decoder from the current one, with an extra rejection
+     * criterium.
+     */
     reject(rejectFn: (value: T) => string | Annotation | null): Decoder<T>;
+
+    /**
+     * Build a new decoder from the current one, modifying its outputted value.
+     */
     transform<V>(transformFn: (value: T) => V): Decoder<V>;
+
+    /**
+     * Build a new decoder from the current one, with a mutated error message
+     * in case of a rejection.
+     */
     describe(message: string): Decoder<T>;
-    then<V>(nextDecodeFn: DecodeFn<V, T>): Decoder<V>;
-    peek<V>(nextDecodeFn: DecodeFn<V, [unknown, T]>): Decoder<V>;
+
+    /**
+     * Chain together the current decoder with another acceptance function.
+     */
+    then<V>(next: AcceptanceFn<V, T>): Decoder<V>;
+
+    // Experimental APIs (please don't rely on these yet)
+    peek_UNSTABLE<V>(next: AcceptanceFn<V, [unknown, T]>): Decoder<V>;
 }
 
+/**
+ * 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 string>      // string
+ *   DecoderType<typeof truthy>      // boolean
+ *
+ */
 export type DecoderType<T> = T extends Decoder<infer V> ? V : never;
 
-export function define<T>(fn: DecodeFn<T>): Decoder<T>;
+/**
+ * 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 with error ``message``
+ *
+ * The expected return value should be a `DecodeResult<T>`, which can be
+ * obtained by returning the result of calling the provided `ok` or `err`
+ * helper functions. Please note that `ok()` and `err()` don't perform side
+ * effects! You'll need to _return_ those values.
+ */
+export function define<T>(fn: AcceptanceFn<T>): Decoder<T>;

package/Decoder.js

@@ -19,38 +19,52 @@ function noThrow(fn) {
     }
   };
 }
+
+function format(err, formatter) {
+  var formatted = formatter(err); // Formatter functions may return a string or an error for convenience of
+  // writing them. If it already returns an Error, return it unmodified. If
+  // it returns a string, wrap it in a "Decoding error" instance.
+
+  if (typeof formatted === 'string') {
+    var _err = new Error('\n' + formatted);
+
+    _err.name = 'Decoding error';
+    return _err;
+  } else {
+    return formatted;
+  }
+}
 /**
  * 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
+ * 3. `err` - Call `err(message)` to reject the input with error ``message``
  *
  * 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.
+ * obtained by returning the result of calling the provided `ok` or `err`
+ * helper functions. Please note that `ok()` and `err()` don't perform side
+ * effects! You'll need to _return_ those values.
  */
 
 
-function define(decodeFn) {
+function define(fn) {
   /**
-   * Validates the raw/untrusted/unknown input and either accepts or rejects
-   * it.
+   * Verifies the 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 fn(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.
+   * Verifies the untrusted/unknown input and either accepts or rejects it.
+   * When accepted, returns a value of type `T`. Otherwise fail with
+   * a runtime error.
    */
 
 
@@ -64,26 +78,13 @@ function define(decodeFn) {
     if (result.ok) {
       return result.value;
     } else {
-      // Formatters may return a string or an error for convenience of
-      // writing them. If it already returns an Error, throw it
-      // unmodified. If it returns a string, wrap it in a "Decoding
-      // error" instance from it and throw that.
-      var strOrErr = formatter(result.error);
-
-      if (typeof strOrErr === 'string') {
-        var _err = new Error('\n' + strOrErr);
-
-        _err.name = 'Decoding error';
-        throw _err;
-      } else {
-        throw strOrErr;
-      }
+      throw format(result.error, formatter);
     }
   }
   /**
-   * Verified the (raw/untrusted/unknown) input and either accepts or rejects
-   * it. When accepted, returns the decoded `T` value directly. Otherwise
-   * returns `undefined`.
+   * Verifies the 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.
@@ -121,23 +122,21 @@ function define(decodeFn) {
   /**
    * 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.
+   * > _**NOTE:** This is an advanced, low-level, API. It's not recommended
+   * > to reach for this construct unless there is no other way. Most cases can
+   * > be covered more elegantly by `.transform()` or `.refine()` instead._
    *
-   * 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 the current decoder accepts an input, the resulting ``T`` value will
+   * get passed into the given ``next`` acceptance function to further decide
+   * whether or not the value should get accepted or rejected.
    *
-   * If it helps, you can think of `define(nextFn)` as equivalent to
-   * `unknown.then(nextFn)`.
+   * This works similar to how you would `define()` a new decoder, except
+   * that the ``blob`` param will now be ``T`` (a known type), rather than
+   * ``unknown``. This will allow the function to make a stronger assumption
+   * about its input and avoid re-refining inputs.
    *
-   * 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()`.
+   * If it helps, you can think of `define(...)` as equivalent to
+   * `unknown.then(...)`.
    */
 
 

package/Decoder.js.flow

@@ -4,47 +4,85 @@ import { annotate } from './annotate';
 import { formatInline } from './format';
 import { err as makeErr, ok as makeOk } from './result';
 import type { Annotation } from './annotate';
+import type { Formatter } from './format';
 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,
+
+export type AcceptanceFn<T, InputT = mixed> = (
+    blob: InputT,
     ok: (value: T) => DecodeResult<T>,
     err: (msg: string | Annotation) => DecodeResult<T>,
 ) => DecodeResult<T>;
 
+export type Decoder<T> = {|
+    /**
+     * Verifies untrusted input. Either returns a value, or throws a decoding
+     * error.
+     */
+    verify(blob: mixed, formatter?: Formatter): T,
+
+    /**
+     * Verifies untrusted input. Either returns a value, or returns undefined.
+     */
+    value(blob: mixed): T | void,
+
+    /**
+     * Verifies untrusted input. Always returns a DecodeResult, which is either
+     * an "ok" value or an "error" annotation.
+     */
+    decode(blob: mixed): DecodeResult<T>,
+
+    /**
+     * Build a new decoder from the the current one, with an extra acceptance
+     * criterium.
+     */
+    refine(predicateFn: (value: T) => boolean, errmsg: string): Decoder<T>,
+
+    /**
+     * Build a new decoder from the current one, with an extra rejection
+     * criterium.
+     */
+    reject(rejectFn: (value: T) => string | Annotation | null): Decoder<T>,
+
+    /**
+     * Build a new decoder from the current one, modifying its outputted value.
+     */
+    transform<V>(transformFn: (value: T) => V): Decoder<V>,
+
+    /**
+     * Build a new decoder from the current one, with a mutated error message
+     * in case of a rejection.
+     */
+    describe(message: string): Decoder<T>,
+
+    /**
+     * Chain together the current decoder with another acceptance function.
+     */
+    then<V>(next: AcceptanceFn<V, T>): Decoder<V>,
+
+    // Experimental APIs (please don't rely on these yet)
+    peek_UNSTABLE<V>(next: AcceptanceFn<V, [mixed, T]>): Decoder<V>,
+|};
+
 /**
  * Helper type to return the "type" of a Decoder.
  *
  * You can use it on types:
  *
- *   DecoderType<Decoder<string>>       // => string
- *   DecoderType<Decoder<number[]>>     // => number[]
+ *   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
+ *   DecoderType<typeof 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 | Error): 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 {
@@ -56,65 +94,65 @@ function noThrow<T, V>(fn: (value: T) => V): (T) => DecodeResult<V> {
     };
 }
 
+function format(err: Annotation, formatter: Formatter): Error {
+    const formatted = formatter(err);
+
+    // Formatter functions may return a string or an error for convenience of
+    // writing them. If it already returns an Error, return it unmodified. If
+    // it returns a string, wrap it in a "Decoding error" instance.
+    if (typeof formatted === 'string') {
+        const err = new Error('\n' + formatted);
+        err.name = 'Decoding error';
+        return err;
+    } else {
+        return formatted;
+    }
+}
+
 /**
  * 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
+ * 3. `err` - Call `err(message)` to reject the input with error ``message``
  *
  * 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.
+ * obtained by returning the result of calling the provided `ok` or `err`
+ * helper functions. Please note that `ok()` and `err()` don't perform side
+ * effects! You'll need to _return_ those values.
  */
-export function define<T>(decodeFn: DecodeFn<T>): Decoder<T> {
+export function define<T>(fn: AcceptanceFn<T>): Decoder<T> {
     /**
-     * Validates the raw/untrusted/unknown input and either accepts or rejects
-     * it.
+     * Verifies the 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) =>
+        return fn(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.
+     * Verifies the untrusted/unknown input and either accepts or rejects it.
+     * When accepted, returns a value of type `T`. Otherwise fail with
+     * a runtime error.
      */
-    function verify(
-        blob: mixed,
-        formatter: (Annotation) => string | Error = formatInline,
-    ): T {
+    function verify(blob: mixed, formatter: Formatter = formatInline): T {
         const result = decode(blob);
         if (result.ok) {
             return result.value;
         } else {
-            // Formatters may return a string or an error for convenience of
-            // writing them. If it already returns an Error, throw it
-            // unmodified. If it returns a string, wrap it in a "Decoding
-            // error" instance from it and throw that.
-            const strOrErr = formatter(result.error);
-            if (typeof strOrErr === 'string') {
-                const err = new Error('\n' + strOrErr);
-                err.name = 'Decoding error';
-                throw err;
-            } else {
-                throw strOrErr;
-            }
+            throw format(result.error, formatter);
         }
     }
 
     /**
-     * Verified the (raw/untrusted/unknown) input and either accepts or rejects
-     * it. When accepted, returns the decoded `T` value directly. Otherwise
-     * returns `undefined`.
+     * Verifies the 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.
@@ -151,25 +189,23 @@ export function define<T>(decodeFn: DecodeFn<T>): Decoder<T> {
     /**
      * 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.
+     * > _**NOTE:** This is an advanced, low-level, API. It's not recommended
+     * > to reach for this construct unless there is no other way. Most cases can
+     * > be covered more elegantly by `.transform()` or `.refine()` instead._
      *
-     * 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 the current decoder accepts an input, the resulting ``T`` value will
+     * get passed into the given ``next`` acceptance function to further decide
+     * whether or not the value should get accepted or rejected.
      *
-     * If it helps, you can think of `define(nextFn)` as equivalent to
-     * `unknown.then(nextFn)`.
+     * This works similar to how you would `define()` a new decoder, except
+     * that the ``blob`` param will now be ``T`` (a known type), rather than
+     * ``unknown``. This will allow the function to make a stronger assumption
+     * about its input and avoid re-refining inputs.
      *
-     * 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()`.
+     * If it helps, you can think of `define(...)` as equivalent to
+     * `unknown.then(...)`.
      */
-    function then<V>(next: DecodeFn<V, T>): Decoder<V> {
+    function then<V>(next: AcceptanceFn<V, T>): Decoder<V> {
         return define((blob, ok, err) => {
             const result = decode(blob);
             return result.ok ? next(result.value, ok, err) : result;
@@ -227,7 +263,7 @@ export function define<T>(decodeFn: DecodeFn<T>): Decoder<T> {
      *
      * This is an advanced, low-level, decoder.
      */
-    function peek_UNSTABLE<V>(next: DecodeFn<V, [mixed, T]>): Decoder<V> {
+    function peek_UNSTABLE<V>(next: AcceptanceFn<V, [mixed, T]>): Decoder<V> {
         return define((blob, ok, err) => {
             const result = decode(blob);
             return result.ok ? next([blob, result.value], ok, err) : result;