decoders 2.0.0-beta12 → 2.0.0-beta13

package/lib/unions.mjs

@@ -83,8 +83,8 @@ function _either() {
 
 export var either = _either;
 /**
- * Accepts any value that is strictly-equal (using ===) to one of the specified
- * values.
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
  */
 
 export function oneOf(constants) {
@@ -111,11 +111,13 @@ export function oneOf(constants) {
  * unions](https://en.wikipedia.org/wiki/Tagged_union), i.e. a union of
  * objects where one field is used as the discriminator.
  *
- *   const A = object({ tag: constant('A'), foo: string });
- *   const B = object({ tag: constant('B'), bar: number });
+ * ```ts
+ * const A = object({ tag: constant('A'), foo: string });
+ * const B = object({ tag: constant('B'), bar: number });
  *
- *   const AorB = taggedUnion('tag', { A, B });
- *   //                        ^^^
+ * const AorB = taggedUnion('tag', { A, B });
+ * //                        ^^^
+ * ```
  *
  * Decoding now works in two steps:
  *
@@ -141,5 +143,4 @@ export function taggedUnion(field, mapping) {
     var decoder = mapping[key];
     return decoder.decode(blob);
   });
-}
-export var dispatch = taggedUnion;
+}

package/lib/utilities.d.ts

@@ -1,10 +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

@@ -23,25 +23,6 @@ function instanceOf(klass) {
 /**
  * Lazily evaluate the given decoder. This is useful to build self-referential
  * types for recursive data structures.
- *
- * Example:
- *
- * ```ts
- * type Tree = {
- *     value: string;
- *     children: Array<Tree>;
- *     //              ^^^^
- *     //              Self-reference defining a recursive type
- * };
- *
- * const treeDecoder: Decoder<Tree> = object({
- *     value: string,
- *     children: array(lazy(() => treeDecoder)),
- *     //              ^^^^^^^^^^^^^^^^^^^^^^^
- *     //              Use lazy() like this to refer to the treeDecoder which is
- *     //              getting defined here
- * });
- * ```
  */
 
 

package/lib/utilities.js.flow

@@ -23,25 +23,6 @@ export function instanceOf<T>(klass: Class<T>): Decoder<T> {
 /**
  * Lazily evaluate the given decoder. This is useful to build self-referential
  * types for recursive data structures.
- *
- * Example:
- *
- * ```ts
- * type Tree = {
- *     value: string;
- *     children: Array<Tree>;
- *     //              ^^^^
- *     //              Self-reference defining a recursive type
- * };
- *
- * const treeDecoder: Decoder<Tree> = object({
- *     value: string,
- *     children: array(lazy(() => treeDecoder)),
- *     //              ^^^^^^^^^^^^^^^^^^^^^^^
- *     //              Use lazy() like this to refer to the treeDecoder which is
- *     //              getting defined here
- * });
- * ```
  */
 export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T> {
     return define((blob) => decoderFn().decode(blob));

package/lib/utilities.mjs

@@ -13,25 +13,6 @@ export function instanceOf(klass) {
 /**
  * Lazily evaluate the given decoder. This is useful to build self-referential
  * types for recursive data structures.
- *
- * Example:
- *
- * ```ts
- * type Tree = {
- *     value: string;
- *     children: Array<Tree>;
- *     //              ^^^^
- *     //              Self-reference defining a recursive type
- * };
- *
- * const treeDecoder: Decoder<Tree> = object({
- *     value: string,
- *     children: array(lazy(() => treeDecoder)),
- *     //              ^^^^^^^^^^^^^^^^^^^^^^^
- *     //              Use lazy() like this to refer to the treeDecoder which is
- *     //              getting defined here
- * });
- * ```
  */
 
 export function lazy(decoderFn) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decoders",
-    "version": "2.0.0-beta12",
+    "version": "2.0.0-beta13",
     "description": "Elegant and battle-tested validation library for type-safe input data (for TypeScript and Flow)",
     "license": "MIT",
     "repository": {