decoders 2.0.0-beta8 → 2.0.0-beta9

package/CHANGELOG.md

@@ -10,9 +10,12 @@ Potentially breaking changes:
 -   Drop support for Flow versions below 0.142.0
 -   Drop support for TypeScript versions below 4.1.0
 -   Drop all package dependencies
+-   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:
-    -   `dispatch` has been renamed to `disjointUnion` - see
-        [migration instructions](./MIGRATING-v2.md#dispatch-is-now-disjointUnion)
     -   API of `guard` has changed (but only if you used its undocumented second argument
         😉) - see [migration instructions](./MIGRATING-v2.md#changes-to-the-guard-api)
     -   API of `predicate` has changed - see
@@ -24,6 +27,12 @@ New features:
 
 -   Include ES modules in published NPM builds (yay tree-shaking! 🍃)
 -   Much smaller total bundle size
+-   New decoders:
+    -   [`prep()`](https://nvie.com/decoders/api#prep)
+    -   [`set()`](https://nvie.com/decoders/api#set)
+    -   [`uuid`](https://nvie.com/decoders/api#uuid)
+    -   [`uuidv1`](https://nvie.com/decoders/api#uuidv1)
+    -   [`uuidv4`](https://nvie.com/decoders/api#uuidv4)
 -   Better error messages for nested `either`s
 -   Guard API now has a simpler way to specify formatters
 

package/README.md

@@ -68,14 +68,92 @@ And then, you can use it to decode values:
 ... })
 ```
 
+## Understanding decoders and guards
+
+At the heart, a decoder is a function that will take _any_ unsafe input, verify it, and
+either return an "ok" or an annotated "err" result. It will never throw an error when
+called.
+
+A guard is a convenience wrapper which will use the decoder
+
 ## API
 
 The decoders package consists of a few building blocks:
 
+-   [Guards](#guards)
 -   [Primitives](#primitives)
 -   [Compositions](#compositions)
 -   [Building custom decoders](#building-custom-decoders)
 
+### Guards
+
+<a name="guard" href="#guard">#</a> <b>guard</b>(decoder: <i>Decoder&lt;T&gt;</i>,
+formatter?: <i>Annotation => string</i>): <i>Guard&lt;T&gt;</i>
+[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/_guard.js 'Source')
+
+Turns any given `Decoder<T>` into a `Guard<T>`.
+
+A guard works like a decoder, but will either:
+
+-   Return the decoded value (aka the happy path)
+-   Or throw an exception
+
+So a Guard bypasses the intermediate "Result" type that decoders output. An "ok" result
+will get returned, an "err" result will be formatted into an error message and thrown.
+
+The typical usage is that you keep composing decoders until you have one decoder for your
+entire input object, and then use a guard to wrap that outer decoder. Decoders can be
+composed to build larger decoders. Guards cannot be composed.
+
+#### Formatting error messsages
+
+By default, `guard()` will use the `formatInline` error formatter. You can pass another
+built-in formatter as the second argument, or provide your own. (This will require
+understanding the internal `Annotation` datastructure that decoders uses for error
+reporting.)
+
+Built-in formatters are:
+
+-   `formatInline` (default) — will echo back the input object and inline error messages
+    smartly. Example:
+
+    ```typescript
+    import { array, guard, object, string } from 'decoders';
+    import { formatInline } from 'decoders/format';
+
+    const mydecoder = array(object({ name: string, age: number }));
+
+    const defaultGuard = guard(mydecoder, formatInline);
+    defaultGuard([{ name: 'Alice', age: '33' }]);
+    ```
+
+    Will throw the following error message:
+
+    ```text
+    Decoding error:
+    [
+      {
+        name: 'Alice',
+        age: '33',
+             ^^^^ Must be number
+      },
+    ]
+    ```
+
+-   `formatShort` — will report the _path_ into the object where the error happened.
+    Example:
+
+    ```typescript
+    import { formatShort } from 'decoders/format';
+    const customGuard = guard(mydecoder, formatShort);
+    ```
+
+    Will throw the following error message:
+
+    ```text
+    Decoding error: Value at keypath 0.age: Must be number
+    ```
+
 ### Primitives
 
 <a name="number" href="#number">#</a> <b>number</b>: <i>Decoder&lt;number&gt;</i>
@@ -319,6 +397,65 @@ const gitUrl: Decoder<URL> = predicate(
 
 ---
 
+<a name="uuid" href="#uuid">#</a> <b>uuid</b>: <i>Decoder&lt;string&gt;</i>
+[(source)](https://github.com/nvie/decoders/blob/main/src/core/string.js 'Source')
+
+Accepts strings that are valid [UUIDs][wiki-uuid] (universally unique identifier).
+
+<!-- prettier-ignore-start -->
+```javascript
+const verify = guard(uuid);
+
+// 👍
+verify('123e4567-e89b-12d3-a456-426614174000') === '123e4567-e89b-12d3-a456-426614174000'
+verify('123E4567-E89B-12D3-A456-426614174000') === '123E4567-E89B-12D3-A456-426614174000'
+
+// 👎
+verify('123E4567E89B12D3A456426614174000');      // throws
+verify('abcdefgh-ijkl-mnop-qrst-uvwxyz012345');  // throws
+```
+<!-- prettier-ignore-end -->
+
+---
+
+<a name="uuidv1" href="#uuidv1">#</a> <b>uuidv1</b>: <i>Decoder&lt;string&gt;</i>
+[(source)](https://github.com/nvie/decoders/blob/main/src/core/string.js 'Source')
+
+Like `uuid`, but only accepts [UUIDv1s][wiki-uuidv1] strings.
+
+<!-- prettier-ignore-start -->
+```javascript
+const verify = guard(uuidv1);
+
+// 👍
+verify('123e4567-e89b-12d3-a456-426614174000') === '123e4567-e89b-42d3-a456-426614174000'
+
+// 👎
+verify('123e4567-e89b-42d3-a456-426614174000')  // throws
+```
+<!-- prettier-ignore-end -->
+
+---
+
+<a name="uuidv4" href="#uuidv4">#</a> <b>uuidv4</b>: <i>Decoder&lt;string&gt;</i>
+[(source)](https://github.com/nvie/decoders/blob/main/src/core/string.js 'Source')
+
+Like `uuid`, but only accepts [UUIDv4s][wiki-uuidv4] strings.
+
+<!-- prettier-ignore-start -->
+```javascript
+const verify = guard(uuidv4);
+
+// 👍
+verify('123e4567-e89b-42d3-a456-426614174000') === '123e4567-e89b-42d3-a456-426614174000'
+
+// 👎
+verify('123e4567-e89b-12d3-a456-426614174000')  // throws
+```
+<!-- prettier-ignore-end -->
+
+---
+
 <a name="boolean" href="#boolean">#</a> <b>boolean</b>: <i>Decoder&lt;boolean&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/boolean.js 'Source')
 
@@ -459,7 +596,7 @@ verify('hello world'); // throws
 ---
 
 <a name="undefined_" href="#undefined_">#</a> <b>undefined\_</b>:
-<i>Decoder&lt;void&gt;</i>
+<i>Decoder&lt;undefined&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/constants.js 'Source')
 
 Accepts only the literal `undefined` value.
@@ -567,15 +704,13 @@ verify({ a: 'foo', b: 'bar' });  // throws
 
 <a name="unknown" href="#unknown">#</a> <b>unknown</b>: <i>Decoder&lt;unknown&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/constants.js 'Source')
-<a name="mixed" href="#mixed">#</a> <b>unknown</b>: <i>Decoder&lt;mixed&gt;</i>
+<a name="mixed" href="#mixed">#</a> <b>mixed</b>: <i>Decoder&lt;mixed&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/constants.js 'Source')<br />
 
 Accepts any value and returns it unchanged. Useful for situation in which you don't know
 or expect a specific type. Of course, the downside is that you won't know the type of the
 value statically and you'll have to further refine it yourself.
 
-(Unknown is called `mixed` in Flow.)
-
 ```javascript
 const verify = guard(mixed);
 
@@ -591,14 +726,14 @@ verify([1, 2]) === [1, 2];
 
 ### Compositions
 
-Composite decoders are "higher order" decoders that can build new decoders from existing
-decoders that can already decode a "subtype". Examples are: if you already have a decoder
-for a `Point` (= `Decoder<Point>`), then you can use `array()` to automatically build a
-decoder for arrays of points: `array(pointDecoder)`, which will be of type
-`Decoder<Array<Point>>`.
+Composite decoders can build new decoders from existing decoders that can already decode a
+"subtype". Examples are: if you already have a `string` decoder (of type
+`Decoder<string>`), then you can use `array(string)` to automatically build a decoder for
+arrays of strings, which will be of type `Decoder<Array<string>>`.
 
 <a name="optional" href="#optional">#</a>
-<b>optional</b><i>&lt;T&gt;</i>(<i>Decoder&lt;T&gt;</i>): <i>Decoder&lt;T | void&gt;</i>
+<b>optional</b><i>&lt;T&gt;</i>(<i>Decoder&lt;T&gt;</i>): <i>Decoder&lt;T |
+undefined&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/optional.js 'Source')
 
 Accepts only the literal value `undefined`, or whatever the given decoder accepts.
@@ -752,38 +887,17 @@ verify('hi');  // throws
 
 ---
 
-<a name="tuple1" href="#tuple1">#</a>
-<b>tuple1</b><i>&lt;T1&gt;</i>(<i>Decoder&lt;T1&gt;</i>): <i>Decoder&lt;[T1]&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/tuple.js 'Source')<br />
-<a name="tuple2" href="#tuple2">#</a> <b>tuple2</b><i>&lt;T1,
-T2&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>): <i>Decoder&lt;[T1,
-T2]&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/tuple.js 'Source')<br />
-<a name="tuple3" href="#tuple3">#</a> <b>tuple3</b><i>&lt;T1, T2,
-T3&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>, <i>Decoder&lt;T3&gt;</i>):
-<i>Decoder&lt;[T1, T2, T3]&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/tuple.js 'Source')<br />
-<a name="tuple4" href="#tuple4">#</a> <b>tuple4</b><i>&lt;T1, T2, T3,
-T4&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>, <i>Decoder&lt;T3&gt;</i>,
-<i>Decoder&lt;T4&gt;</i>): <i>Decoder&lt;[T1, T2, T3, T4]&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/tuple.js 'Source')<br />
-<a name="tuple5" href="#tuple5">#</a> <b>tuple5</b><i>&lt;T1, T2, T3, T4,
-T5&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>, <i>Decoder&lt;T3&gt;</i>,
-<i>Decoder&lt;T3&gt;</i>, <i>Decoder&lt;T4&gt;</i>, <i>Decoder&lt;T5&gt;</i>):
-<i>Decoder&lt;[T1, T2, T3, T4, T5]&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/tuple.js 'Source')<br />
-<a name="tuple6" href="#tuple6">#</a> <b>tuple6</b><i>&lt;T1, T2, T3, T4, T5,
-T6&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>, <i>Decoder&lt;T3&gt;</i>,
-<i>Decoder&lt;T4&gt;</i>, <i>Decoder&lt;T5&gt;</i>, <i>Decoder&lt;T6&gt;</i>):
-<i>Decoder&lt;[T1, T2, T3, T4, T5, T6]&gt;</i>
+<a name="tuple" href="#tuple">#</a> <b>tuple</b><i>&lt;A, B, C,
+...&gt;</i>(<i>Decoder&lt;A&gt;</i>, <i>Decoder&lt;B&gt;</i>, <i>Decoder&lt;C&gt;</i>):
+<i>Decoder&lt;[A, B, C, ...]&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/tuple.js 'Source')
 
-Accepts a _n_-tuple (an array with exactly _n_ items) of values accepted by the _n_ given
+Accepts a tuple (an array with exactly _n_ items) of values accepted by the _n_ given
 decoders.
 
 <!-- prettier-ignore-start -->
 ```javascript
-const verify = guard(tuple2(string, number));
+const verify = guard(tuple(string, number));
 
 // 👍
 verify(['hello', 1.2]) === ['hello', 1.2];
@@ -797,6 +911,26 @@ verify(['a', 1, 'c']);       // throws, too many items
 
 ---
 
+<a name="set" href="#set">#</a> <b>set</b><i>&lt;T&gt;</i>(<i>Decoder&lt;T&gt;</i>):
+<i>Decoder&lt;Set&lt;T&gt;&gt;</i>
+[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/array.js 'Source')
+
+Similar to [`array`](#array), but returns the result as an ES6 Set.
+
+<!-- prettier-ignore-start -->
+```javascript
+const verify = guard(set(string));
+
+// 👍
+verify(['hello', 'world'])  // ≈ new Set(['hello', 'world']);
+
+// 👎
+verify(['hello', 1.2]);     // throws
+```
+<!-- prettier-ignore-end -->
+
+---
+
 <a name="object" href="#object">#</a> <b>object</b><i>&lt;O: { [field: string]:
 Decoder&lt;any&gt; }&gt;</i>(mapping: O): <i>Decoder&lt;{ ... }&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/object.js 'Source')
@@ -913,7 +1047,7 @@ verify(null);        // throws
 
 <a name="dict" href="#dict">#</a> <b>dict</b><i>&lt;T&gt;</i>(<i>Decoder&lt;T&gt;</i>):
 <i>Decoder&lt;{ [string]: &lt;T&gt;}&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/mapping.js 'Source')
+[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/object.js 'Source')
 
 Accepts objects where all values match the given decoder, and returns the result as a
 `{ [string]: T }`.
@@ -943,7 +1077,7 @@ verify({
 <a name="mapping" href="#mapping">#</a>
 <b>mapping</b><i>&lt;T&gt;</i>(<i>Decoder&lt;T&gt;</i>): <i>Decoder&lt;Map&lt;string,
 T&gt;&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/mapping.js 'Source')
+[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/object.js 'Source')
 
 Like `dict()`, but returns the result as a `Map<string, T>` instead.
 
@@ -1042,22 +1176,13 @@ verify(null);               // throws
 
 ---
 
-<a name="either" href="#either">#</a> <b>either</b><i>&lt;T1,
-T2&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>): <i>Decoder&lt;T1 |
-T2&gt;</i><br />
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/either.js 'Source')<br />
-<a name="either2" href="#either2">#</a> <b>either2</b><i>&lt;T1,
-T2&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>): <i>Decoder&lt;T1 |
-T2&gt;</i><br />
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/either.js 'Source')<br />
-<a name="either3" href="#either3">#</a> <b>either3</b><i>&lt;T1, T2,
-T3&gt;</i>(<i>Decoder&lt;T1&gt;</i>, <i>Decoder&lt;T2&gt;</i>, <i>Decoder&lt;T3&gt;</i>):
-<i>Decoder&lt;T1 | T2 | T3&gt;</i>
+<a name="either" href="#either">#</a> <b>either</b><i>&lt;A, B, C,
+...&gt;</i>(<i>Decoder&lt;A&gt;</i>, <i>Decoder&lt;B&gt;</i>, <i>Decoder&lt;C&gt;</i>,
+...): <i>Decoder&lt;A | B | C | ...&gt;</i><br />
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/either.js 'Source')<br />
-...
 
-Accepts any value that is accepted by any of the given decoders. Eithers exist for arities
-up until 9 (`either`, `either3`, `either4`, ..., `either9`).
+Accepts any value that is accepted by any of the given decoders. The decoders are
+attempted on the input in given order. The first one that accepts the input "wins".
 
 <!-- prettier-ignore-start -->
 ```javascript
@@ -1072,17 +1197,21 @@ verify(false);  // throws
 ```
 <!-- prettier-ignore-end -->
 
+**NOTE to Flow users:** In Flow, there is a max of 16 arguments with this construct. (This
+is no problem in TypeScript.) If you hit the 16 argument limit, you can work around that
+by stacking, e.g. do `either(<15 arguments here>, either(...))`.
+
 ---
 
-<a name="disjointUnion" href="#disjointUnion">#</a> <b>disjointUnion</b><i>&lt;O: {
-[field: string]: (Decoder&lt;T&gt; | Decoder&lt;V&gt; | ...) }&gt;</i>(field: string,
-mapping: O): <i>Decoder&lt;T | V | ...&gt;</i>
+<a name="taggedUnion" href="#taggedUnion">#</a> <b>taggedUnion</b><i>&lt;O: { [field:
+string]: (Decoder&lt;T&gt; | Decoder&lt;V&gt; | ...) }&gt;</i>(field: string, mapping: O):
+<i>Decoder&lt;T | V | ...&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/dispatch.js 'Source')
 
 **NOTE:** In decoders@1.x, this was called `dispatch()`.
 
-Like the `either` family, but only for building unions of object types with a common field
-(like a `type` field) that lets you distinguish members.
+Like `either`, but only for building unions of object types with a common field (like a
+`type` field) that lets you distinguish members.
 
 The following two decoders are effectively equivalent:
 
@@ -1092,14 +1221,14 @@ type Circle = { __type: 'circle', cx: number, cy: number, r: number };
 //              ^^^^^^
 //              Field that defines which decoder to pick
 //                                               vvvvvv
-const shape1: Decoder<Rect | Circle> = disjointUnion('__type', { rect, circle });
+const shape1: Decoder<Rect | Circle> = taggedUnion('__type', { rect, circle });
 const shape2: Decoder<Rect | Circle> = either(rect, circle);
 ```
 
-But using `disjointUnion()` will typically be more runtime-efficient than using
-`either()`. The reason is that `disjointUnion()` will first do minimal work to "look
-ahead" into the `type` field here, and based on that value, pick which decoder to invoke.
-Error messages will then also be tailored to the specific decoder.
+But using `taggedUnion()` will typically be more runtime-efficient than using `either()`.
+The reason is that `taggedUnion()` will first do minimal work to "look ahead" into the
+`type` field here, and based on that value, pick which decoder to invoke. Error messages
+will then also be tailored to the specific decoder.
 
 The `either()` version will instead try each decoder in turn until it finds one that
 matches. If none of the alternatives match, it needs to report all errors, which is
@@ -1167,8 +1296,9 @@ verify(3);      // throws
 
 ---
 
-<a name="map" href="#map">#</a> <b>map</b><i>&lt;T, V&gt;</i>(<i>Decoder&lt;T&gt;</i>,
-<i>&lt;T&gt;</i> =&gt; <i>&lt;V&gt;</i>): <i>Decoder&lt;V&gt;</i>
+<a name="transform" href="#transform">#</a> <b>transform</b><i>&lt;T,
+V&gt;</i>(<i>Decoder&lt;T&gt;</i>, <i>&lt;T&gt;</i> =&gt; <i>&lt;V&gt;</i>):
+<i>Decoder&lt;V&gt;</i>
 [&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/utils.js 'Source')<br />
 
 Accepts any value the given decoder accepts, and on success, will call the mapper value
@@ -1177,7 +1307,7 @@ fail using the error message as the failure reason.
 
 <!-- prettier-ignore-start -->
 ```javascript
-const upper = map(string, (s) => s.toUpperCase());
+const upper = transform(string, (s) => s.toUpperCase());
 const verify = guard(upper);
 
 // 👍
@@ -1207,7 +1337,7 @@ recommended to rely on this decoder directly for normal usage.
 <a name="predicate" href="#predicate">#</a>
 <b>predicate</b><i>&lt;T&gt;</i>(<i>Decoder&lt;T&gt;</i>, <i>&lt;T&gt; => boolean</i>,
 string): <i>Decoder&lt;T&gt;</i>
-[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/predicate.js 'Source')<br />
+[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/composition.js 'Source')<br />
 
 Accepts values that are accepted by the decoder _and_ also pass the predicate function.
 
@@ -1215,7 +1345,7 @@ Accepts values that are accepted by the decoder _and_ also pass the predicate fu
 ```typescript
 const odd = predicate(
   number,
-  (n) => n % 2 === 1,
+  (n) => n % 2 !== 0,
   'Must be odd'
 );
 const verify = guard(odd);
@@ -1234,6 +1364,38 @@ predicate][type-predicates], then this will be reflected in the return type, too
 
 ---
 
+<a name="prep" href="#prep">#</a> <b>prep</b><i>&lt;T, I&gt;</i>(<i>unknown => I</i>,
+<i>Decoder&lt;T, I&gt;</i>): <i>Decoder&lt;T&gt;</i>
+[&lt;&gt;](https://github.com/nvie/decoders/blob/main/src/core/composition.js 'Source')<br />
+
+Pre-process the raw 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.
+
+<!-- prettier-ignore-start -->
+```typescript
+const verify = prep(
+  // Will convert any input to an int first, before feeding it to
+  // positiveInteger. This will effectively also allow numeric strings
+  // to be accepted (and returned) as integers. If this ever throws,
+  // then the error message will be what gets annotated on the input.
+  x => parseInt(x),
+  positiveInteger,
+);
+
+// 👍
+verify(42) === 42;
+verify('3') === 3;
+
+// 👎
+verify('-3');  // throws: not a positive number
+verify('hi');  // throws: not a number
+```
+<!-- prettier-ignore-end -->
+
+---
+
 <a name="describe" href="#describe">#</a>
 <b>describe</b><i>&lt;T&gt;</i>(<i>Decoder&lt;T&gt;</i>, <i>string</i>):
 <i>Decoder&lt;T&gt;</i>
@@ -1304,13 +1466,13 @@ And a runtime input of:
 |                  | Extra properties | Output value                   | Inferred type                               |
 | ---------------- | ---------------- | ------------------------------ | ------------------------------------------- |
 | `object(thing)`  | discarded        | `{a: "hi", b: 42}`             | `{a: string, b: number}`                    |
-| `exact(thing)`   | not allowed      | ⚡️ Runtime error              | `{a: string, b: number}`                    |
+| `exact(thing)`   | not allowed      | n/a (rejected)                 | `{a: string, b: number}`                    |
 | `inexact(thing)` | retained         | `{a: "hi", b: 42, c: "extra"}` | `{a: string, b: number, [string]: unknown}` |
 
 ### Building custom decoders
 
-There are two main building blocks for defining your own custom decoders: `map()` and
-`compose()`.
+There are two main building blocks for defining your own custom decoders: `transform()`
+and `compose()`.
 
 There are roughly 3 use cases that you will want to use:
 
@@ -1325,7 +1487,7 @@ There are roughly 3 use cases that you will want to use:
 To read one type from the input, but return another, use:
 
 ```js
-const numericString: Decoder<number> = map(
+const numericString: Decoder<number> = transform(
     // At runtime, expect to read a string...
     string,
     // ...but return it as a number
@@ -1336,7 +1498,7 @@ const numericString: Decoder<number> = map(
 To read one type, but change its value before returning:
 
 ```js
-const upperCase: Decoder<string> = map(string, (s) => s.toUpperCase());
+const upperCase: Decoder<string> = transform(string, (s) => s.toUpperCase());
 ```
 
 **WARNING:** While you can map anything to anything, it's typically **NOT A GOOD IDEA to

package/_utils.js

@@ -7,7 +7,7 @@ exports.indent = indent;
 exports.isDate = isDate;
 exports.isMultiline = isMultiline;
 exports.summarize = summarize;
-// $FlowFixMe[unclear-type] - deliberate casting
+// $FlowFixMe[unclear-type] - deliberate use of `any`
 // Two spaces of indentation
 var INDENT = '  ';
 /**

package/_utils.js.flow

@@ -2,8 +2,8 @@
 
 import type { Annotation } from './annotate';
 
-// $FlowFixMe[unclear-type] - deliberate casting
-type cast = any;
+// $FlowFixMe[unclear-type] - deliberate use of `any`
+export type _Any = any;
 
 // Two spaces of indentation
 export const INDENT = '  ';
@@ -29,7 +29,7 @@ export function isDate(value: mixed): boolean {
  * null.
  */
 export function asDate(value: mixed): Date | null {
-    return isDate(value) ? ((value: cast): Date) : null;
+    return isDate(value) ? ((value: _Any): Date) : null;
 }
 
 export function isMultiline(s: string): boolean {

package/_utils.mjs

@@ -1,4 +1,4 @@
-// $FlowFixMe[unclear-type] - deliberate casting
+// $FlowFixMe[unclear-type] - deliberate use of `any`
 // Two spaces of indentation
 export var INDENT = '  ';
 /**

package/core/array.d.ts

@@ -1,5 +1,8 @@
+/// <reference lib="es6" />
+
 import { Decoder } from '../_types';
 
 export const poja: Decoder<unknown[]>;
 export function array<T>(decoder: Decoder<T>): Decoder<T[]>;
 export function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<[T, ...T[]]>;
+export function set<T>(decoder: Decoder<T>): Decoder<Set<T>>;

package/core/array.js

@@ -4,6 +4,7 @@ exports.__esModule = true;
 exports.array = array;
 exports.nonEmptyArray = nonEmptyArray;
 exports.poja = void 0;
+exports.set = set;
 
 var _annotate = require("../annotate");
 
@@ -47,7 +48,7 @@ function all(items, blobs) {
   for (var index = 0; index < items.length; ++index) {
     var result = items[index];
 
-    if (result.type === 'ok') {
+    if (result.ok) {
       results.push(result.value);
     } else {
       var ann = result.error; // Rewrite the annotation to include the index information, and inject it into the original blob
@@ -101,4 +102,14 @@ function nonEmptyArray(decoder) {
   return (0, _composition.predicate)(array(decoder), function (arr) {
     return arr.length > 0;
   }, 'Must be non-empty array');
+}
+/**
+ * Similar to `array()`, but returns the result as an ES6 Set.
+ */
+
+
+function set(decoder) {
+  return (0, _composition.transform)(array(decoder), function (items) {
+    return new Set(items);
+  });
 }

package/core/array.js.flow

@@ -1,7 +1,7 @@
 // @flow strict
 
 import { annotate } from '../annotate';
-import { compose, predicate } from './composition';
+import { compose, predicate, transform } from './composition';
 import { err, ok } from '../result';
 import type { Decoder, DecodeResult } from '../_types';
 
@@ -40,7 +40,7 @@ function all<T>(
     const results: Array<T> = [];
     for (let index = 0; index < items.length; ++index) {
         const result = items[index];
-        if (result.type === 'ok') {
+        if (result.ok) {
             results.push(result.value);
         } else {
             const ann = result.error;
@@ -98,3 +98,10 @@ export function array<T>(decoder: Decoder<T>): Decoder<Array<T>> {
 export function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<Array<T>> {
     return predicate(array(decoder), (arr) => arr.length > 0, 'Must be non-empty array');
 }
+
+/**
+ * Similar to `array()`, but returns the result as an ES6 Set.
+ */
+export function set<T>(decoder: Decoder<T>): Decoder<Set<T>> {
+    return transform(array(decoder), (items) => new Set(items));
+}

package/core/array.mjs

@@ -1,5 +1,5 @@
 import { annotate } from '../annotate.mjs';
-import { compose, predicate } from './composition.mjs';
+import { compose, predicate, transform } from './composition.mjs';
 import { err, ok } from '../result.mjs';
 
 /**
@@ -35,7 +35,7 @@ function all(items, blobs) {
   for (var index = 0; index < items.length; ++index) {
     var result = items[index];
 
-    if (result.type === 'ok') {
+    if (result.ok) {
       results.push(result.value);
     } else {
       var ann = result.error; // Rewrite the annotation to include the index information, and inject it into the original blob
@@ -88,4 +88,13 @@ export function nonEmptyArray(decoder) {
   return predicate(array(decoder), function (arr) {
     return arr.length > 0;
   }, 'Must be non-empty array');
+}
+/**
+ * Similar to `array()`, but returns the result as an ES6 Set.
+ */
+
+export function set(decoder) {
+  return transform(array(decoder), function (items) {
+    return new Set(items);
+  });
 }