decoders 2.0.0-beta1 → 2.0.0-beta13

package/Decoder.mjs

@@ -0,0 +1,215 @@
+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);
+    } catch (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.
+
+  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 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);
+    });
+  }
+  /**
+   * 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;
+    }
+
+    var result = decode(blob);
+
+    if (result.ok) {
+      return result.value;
+    } else {
+      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;
+  }
+  /**
+   * 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.
+   *
+   * > _**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;
+    });
+  }
+  /**
+   * 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);
+    });
+  }
+  /**
+   * 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(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/NotSupportedTSVersion.d.ts

@@ -0,0 +1 @@
+"Package `decoders` requires TypeScript >= 4.1.0"