decoders 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v2.0.2
+
+-   ![](./docs/assets/tiny-ts-logo.png) Fix TypeScript types for `formatShort` and
+    `formatInline` helper functions
+
+## v2.0.1
+
+-   ![](./docs/assets/tiny-ts-logo.png) **TypeScript-only:** Fix definition of JSONObject
+    to reflect that its values might always be `undefined` as well.
+
+-   ![](./docs/assets/tiny-ts-logo.png) **TypeScript-only:** Changed return types of
+    `{ [key: string]: T }` to `Record<string, T>`.
+
+-   ![](./docs/assets/tiny-ts-logo.png) **TypeScript-only:** Fine-tune the type of
+    [`instanceOf()`](https://decoders.cc/api.html#instanceOf).
+
 ## v2.0.0
 
 This is a breaking change, which brings numerous benefits:

package/Decoder.js

@@ -1,210 +1,104 @@
-"use strict";
+'use strict'
 
-exports.__esModule = true;
-exports.define = define;
+exports.__esModule = true
+exports.define = define
 
-var _annotate = require("./annotate");
+var _annotate = require('./annotate')
 
-var _format = require("./format");
+var _format = require('./format')
 
-var _result = require("./result");
+var _result = require('./result')
 
 function noThrow(fn) {
   return function (t) {
     try {
-      var v = fn(t);
-      return (0, _result.ok)(v);
+      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)));
+      return (0, _result.err)((0, _annotate.annotate)(t, e instanceof Error ? e.message : String(e)))
     }
-  };
+  }
 }
 
 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.
+  var formatted = formatter(err)
 
   if (typeof formatted === 'string') {
-    var _err = new Error('\n' + formatted);
+    var _err = new Error('\n' + formatted)
 
-    _err.name = 'Decoding error';
-    return _err;
+    _err.name = 'Decoding error'
+    return _err
   } else {
-    return formatted;
+    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 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.
- */
-
 
 function define(fn) {
-  /**
-   * 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 fn(blob, _result.ok, function (msg) {
-      return (0, _result.err)(typeof msg === 'string' ? (0, _annotate.annotate)(blob, msg) : msg);
-    });
+      return (0, _result.err)(typeof msg === 'string' ? (0, _annotate.annotate)(blob, msg) : msg)
+    })
   }
-  /**
-   * 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, formatter) {
     if (formatter === void 0) {
-      formatter = _format.formatInline;
+      formatter = _format.formatInline
     }
 
-    var result = decode(blob);
+    var result = decode(blob)
 
     if (result.ok) {
-      return result.value;
+      return result.value
     } else {
-      throw format(result.error, formatter);
+      throw format(result.error, formatter)
     }
   }
-  /**
-   * 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.
-   */
-
 
   function value(blob) {
-    return decode(blob).value;
+    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));
+    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;
-    });
+      return predicateFn(value) ? null : errmsg
+    })
   }
-  /**
-   * Chain together the current decoder with another.
-   *
-   * > _**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._
-   *
-   * 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.
-   *
-   * 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.
-   *
-   * If it helps, you can think of `define(...)` as equivalent to
-   * `unknown.then(...)`.
-   */
-
 
   function then(next) {
     return define(function (blob, ok, err) {
-      var result = decode(blob);
-      return result.ok ? next(result.value, ok, err) : result;
-    });
+      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);
-    });
+      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);
+      var result = decode(blob)
 
       if (result.ok) {
-        return result;
+        return result
       } else {
-        // ...but in case of error, annotate this with the custom given
-        // message instead
-        return err((0, _annotate.annotate)(result.error, message));
+        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;
-    });
+      var result = decode(blob)
+      return result.ok ? next([blob, result.value], ok, err) : result
+    })
   }
 
   return Object.freeze({
@@ -216,7 +110,6 @@ function define(fn) {
     reject: reject,
     describe: describe,
     then: then,
-    // EXPERIMENTAL - please DO NOT rely on this method
-    peek_UNSTABLE: peek_UNSTABLE
-  });
-}
+    peek_UNSTABLE: peek_UNSTABLE,
+  })
+}

package/Decoder.js.flow

@@ -101,7 +101,7 @@ function format(err: Annotation, formatter: Formatter): Error {
     // 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);
+        const err = new Error(`\n${formatted}`);
         err.name = 'Decoding error';
         return err;
     } else {

package/Decoder.mjs

@@ -1,203 +1,97 @@
-import { annotate } from './annotate.mjs';
-import { formatInline } from './format.mjs';
-import { err as makeErr, ok as makeOk } from './result.mjs';
+import { annotate } from './annotate.mjs'
+import { formatInline } from './format.mjs'
+import { err as makeErr, ok as makeOk } from './result.mjs'
 
 function noThrow(fn) {
   return function (t) {
     try {
-      var v = fn(t);
-      return makeOk(v);
+      var v = fn(t)
+      return makeOk(v)
     } catch (e) {
-      return makeErr(annotate(t, e instanceof Error ? e.message : String(e)));
+      return makeErr(annotate(t, e instanceof Error ? e.message : String(e)))
     }
-  };
+  }
 }
 
 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.
+  var formatted = formatter(err)
 
   if (typeof formatted === 'string') {
-    var _err = new Error('\n' + formatted);
+    var _err = new Error('\n' + formatted)
 
-    _err.name = 'Decoding error';
-    return _err;
+    _err.name = 'Decoding error'
+    return _err
   } else {
-    return formatted;
+    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 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(fn) {
-  /**
-   * 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 fn(blob, makeOk, function (msg) {
-      return makeErr(typeof msg === 'string' ? annotate(blob, msg) : msg);
-    });
+      return makeErr(typeof msg === 'string' ? annotate(blob, msg) : msg)
+    })
   }
-  /**
-   * 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, formatter) {
     if (formatter === void 0) {
-      formatter = formatInline;
+      formatter = formatInline
     }
 
-    var result = decode(blob);
+    var result = decode(blob)
 
     if (result.ok) {
-      return result.value;
+      return result.value
     } else {
-      throw format(result.error, formatter);
+      throw format(result.error, formatter)
     }
   }
-  /**
-   * 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.
-   */
-
 
   function value(blob) {
-    return decode(blob).value;
+    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));
+    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;
-    });
+      return predicateFn(value) ? null : errmsg
+    })
   }
-  /**
-   * Chain together the current decoder with another.
-   *
-   * > _**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._
-   *
-   * 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.
-   *
-   * 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.
-   *
-   * If it helps, you can think of `define(...)` as equivalent to
-   * `unknown.then(...)`.
-   */
-
 
   function then(next) {
     return define(function (blob, ok, err) {
-      var result = decode(blob);
-      return result.ok ? next(result.value, ok, err) : result;
-    });
+      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' ? annotate(value, errmsg) : errmsg);
-    });
+      var 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) {
     return define(function (blob, _, err) {
-      // Decode using the given decoder...
-      var result = decode(blob);
+      var result = decode(blob)
 
       if (result.ok) {
-        return result;
+        return result
       } else {
-        // ...but in case of error, annotate this with the custom given
-        // message instead
-        return err(annotate(result.error, message));
+        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(next) {
     return define(function (blob, ok, err) {
-      var result = decode(blob);
-      return result.ok ? next([blob, result.value], ok, err) : result;
-    });
+      var result = decode(blob)
+      return result.ok ? next([blob, result.value], ok, err) : result
+    })
   }
 
   return Object.freeze({
@@ -209,7 +103,6 @@ export function define(fn) {
     reject: reject,
     describe: describe,
     then: then,
-    // EXPERIMENTAL - please DO NOT rely on this method
-    peek_UNSTABLE: peek_UNSTABLE
-  });
-}
+    peek_UNSTABLE: peek_UNSTABLE,
+  })
+}

package/README.md

@@ -1,4 +1,4 @@
-<img alt="Decoders logo" src="./docs/assets/logo@2x.png" style="width: 100%; max-width: 830px; max-height: 248px" width="830" height="248" /><br />
+<img alt="Decoders logo" src="./docs/assets/logo@2x.png" style="width: 100%; max-width: 830px; max-height: 248px" width="830" /><br />
 
 [![npm](https://img.shields.io/npm/v/decoders.svg)](https://www.npmjs.com/package/decoders)
 [![Build Status](https://github.com/nvie/decoders/workflows/test/badge.svg)](https://github.com/nvie/decoders/actions)