decoders 1.26.0-test1 → 2.0.0-beta12

package/Decoder.mjs

@@ -0,0 +1,216 @@
+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)));
+    }
+  };
+}
+/**
+ * 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
+ *
+ * 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.
+ */
+
+
+export function define(decodeFn) {
+  /**
+   * Validates the raw/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, makeOk, function (msg) {
+      return 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.
+   */
+
+
+  function verify(blob, formatter) {
+    if (formatter === void 0) {
+      formatter = formatInline;
+    }
+
+    var 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.
+      var strOrErr = formatter(result.error);
+
+      if (typeof strOrErr === 'string') {
+        var _err = new Error('\n' + strOrErr);
+
+        _err.name = 'Decoding error';
+        throw _err;
+      } else {
+        throw strOrErr;
+      }
+    }
+  }
+  /**
+   * Verified the (raw/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.
+   *
+   * 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.
+   *
+   * 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 it helps, you can think of `define(nextFn)` as equivalent to
+   * `unknown.then(nextFn)`.
+   *
+   * 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()`.
+   */
+
+
+  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"