decoders 2.1.0 → 2.2.0-test

package/Decoder.d.ts

@@ -1,94 +0,0 @@
-import { Annotation } from './annotate';
-import { Result } from './result';
-
-export type Scalar = string | number | boolean | symbol | undefined | null;
-
-export type DecodeResult<T> = Result<T, Annotation>;
-
-export type AcceptanceFn<T, InputT = unknown> = (
-    blob: InputT,
-    ok: (value: T) => DecodeResult<T>,
-    err: (msg: string | Annotation) => DecodeResult<T>,
-) => DecodeResult<T>;
-
-export interface Decoder<T> {
-    /**
-     * Verifies untrusted input. Either returns a value, or throws a decoding
-     * error.
-     */
-    verify(blob: unknown, formatterFn?: (ann: Annotation) => string | Error): T;
-
-    /**
-     * Verifies untrusted input. Either returns a value, or returns undefined.
-     */
-    value(blob: unknown): T | undefined;
-
-    /**
-     * Verifies untrusted input. Always returns a DecodeResult, which is either
-     * an "ok" value or an "error" annotation.
-     */
-    decode(blob: unknown): DecodeResult<T>;
-
-    /**
-     * Build a new decoder from the the current one, with an extra acceptance
-     * criterium.
-     */
-    refine<N extends T>(predicate: (value: T) => value is N, msg: string): Decoder<N>;
-    refine(predicate: (value: T) => boolean, msg: string): Decoder<T>;
-
-    /**
-     * Build a new decoder from the current one, with an extra rejection
-     * criterium.
-     */
-    reject(rejectFn: (value: T) => string | Annotation | null): Decoder<T>;
-
-    /**
-     * Build a new decoder from the current one, modifying its outputted value.
-     */
-    transform<V>(transformFn: (value: T) => V): Decoder<V>;
-
-    /**
-     * Build a new decoder from the current one, with a mutated error message
-     * in case of a rejection.
-     */
-    describe(message: string): Decoder<T>;
-
-    /**
-     * Chain together the current decoder with another acceptance function.
-     */
-    then<V>(next: AcceptanceFn<V, T>): Decoder<V>;
-
-    // Experimental APIs (please don't rely on these yet)
-    peek_UNSTABLE<V>(next: AcceptanceFn<V, [unknown, T]>): Decoder<V>;
-}
-
-/**
- * Helper type to return the "type" of a Decoder.
- *
- * You can use it on types:
- *
- *   DecoderType<Decoder<string>>    // string
- *   DecoderType<Decoder<number[]>>  // number[]
- *
- * Or on "values", by using the `typeof` keyword:
- *
- *   DecoderType<typeof string>      // string
- *   DecoderType<typeof truthy>      // boolean
- *
- */
-export type DecoderType<T> = T extends Decoder<infer V> ? V : never;
-
-/**
- * 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<T>(fn: AcceptanceFn<T>): Decoder<T>;

package/Decoder.js

@@ -1,105 +0,0 @@
-'use strict'
-
-exports.__esModule = true
-exports.define = define
-var _annotate = require('./annotate')
-var _format = require('./format')
-var _result = require('./result')
-
-function noThrow(fn) {
-  return function (t) {
-    try {
-      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)))
-    }
-  }
-}
-function format(err, formatter) {
-  var formatted = formatter(err)
-  if (typeof formatted === 'string') {
-    var _err = new Error('\n' + formatted)
-    _err.name = 'Decoding error'
-    return _err
-  } else {
-    return formatted
-  }
-}
-
-function define(fn) {
-  function decode(blob) {
-    return fn(blob, _result.ok, function (msg) {
-      return (0, _result.err)(typeof msg === 'string' ? (0, _annotate.annotate)(blob, msg) : msg)
-    })
-  }
-
-  function verify(blob, formatter) {
-    if (formatter === void 0) {
-      formatter = _format.formatInline
-    }
-    var result = decode(blob)
-    if (result.ok) {
-      return result.value
-    } else {
-      throw format(result.error, formatter)
-    }
-  }
-
-  function value(blob) {
-    return decode(blob).value
-  }
-
-  function transform(transformFn) {
-    return then(noThrow(transformFn))
-  }
-
-  function refine(predicateFn, errmsg) {
-    return reject(function (value) {
-      return predicateFn(value) ? null : errmsg
-    })
-  }
-
-  function then(next) {
-    return define(function (blob, ok, err) {
-      var result = decode(blob)
-      return result.ok ? next(result.value, ok, err) : result
-    })
-  }
-
-  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)
-    })
-  }
-
-  function describe(message) {
-    return define(function (blob, _, err) {
-      var result = decode(blob)
-      if (result.ok) {
-        return result
-      } else {
-        return err((0, _annotate.annotate)(result.error, message))
-      }
-    })
-  }
-
-  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,
-    peek_UNSTABLE: peek_UNSTABLE,
-  })
-}

package/Decoder.js.flow

@@ -1,286 +0,0 @@
-// @flow strict
-
-import { annotate } from './annotate';
-import { formatInline } from './format';
-import { err as makeErr, ok as makeOk } from './result';
-import type { Annotation } from './annotate';
-import type { Formatter } from './format';
-import type { Result } from './result';
-
-export type Scalar = string | number | boolean | symbol | void | null;
-
-export type DecodeResult<T> = Result<T, Annotation>;
-
-export type AcceptanceFn<T, InputT = mixed> = (
-    blob: InputT,
-    ok: (value: T) => DecodeResult<T>,
-    err: (msg: string | Annotation) => DecodeResult<T>,
-) => DecodeResult<T>;
-
-export type Decoder<T> = {|
-    /**
-     * Verifies untrusted input. Either returns a value, or throws a decoding
-     * error.
-     */
-    verify(blob: mixed, formatter?: Formatter): T,
-
-    /**
-     * Verifies untrusted input. Either returns a value, or returns undefined.
-     */
-    value(blob: mixed): T | void,
-
-    /**
-     * Verifies untrusted input. Always returns a DecodeResult, which is either
-     * an "ok" value or an "error" annotation.
-     */
-    decode(blob: mixed): DecodeResult<T>,
-
-    /**
-     * Build a new decoder from the the current one, with an extra acceptance
-     * criterium.
-     */
-    refine(predicateFn: (value: T) => boolean, errmsg: string): Decoder<T>,
-
-    /**
-     * Build a new decoder from the current one, with an extra rejection
-     * criterium.
-     */
-    reject(rejectFn: (value: T) => string | Annotation | null): Decoder<T>,
-
-    /**
-     * Build a new decoder from the current one, modifying its outputted value.
-     */
-    transform<V>(transformFn: (value: T) => V): Decoder<V>,
-
-    /**
-     * Build a new decoder from the current one, with a mutated error message
-     * in case of a rejection.
-     */
-    describe(message: string): Decoder<T>,
-
-    /**
-     * Chain together the current decoder with another acceptance function.
-     */
-    then<V>(next: AcceptanceFn<V, T>): Decoder<V>,
-
-    // Experimental APIs (please don't rely on these yet)
-    peek_UNSTABLE<V>(next: AcceptanceFn<V, [mixed, T]>): Decoder<V>,
-|};
-
-/**
- * Helper type to return the "type" of a Decoder.
- *
- * You can use it on types:
- *
- *   DecoderType<Decoder<string>>    // string
- *   DecoderType<Decoder<number[]>>  // number[]
- *
- * Or on "values", by using the `typeof` keyword:
- *
- *   DecoderType<typeof string>      // string
- *   DecoderType<typeof truthy>      // boolean
- *
- */
-export type DecoderType<D> = $Call<<T>(Decoder<T>) => T, D>;
-
-function noThrow<T, V>(fn: (value: T) => V): (T) => DecodeResult<V> {
-    return (t) => {
-        try {
-            const v = fn(t);
-            return makeOk(v);
-        } catch (e) {
-            return makeErr(annotate(t, e instanceof Error ? e.message : String(e)));
-        }
-    };
-}
-
-function format(err: Annotation, formatter: Formatter): Error {
-    const 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') {
-        const 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<T>(fn: AcceptanceFn<T>): Decoder<T> {
-    /**
-     * 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: mixed): DecodeResult<T> {
-        return fn(blob, makeOk, (msg: Annotation | string) =>
-            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: mixed, formatter: Formatter = formatInline): T {
-        const 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: mixed): T | void {
-        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<V>(transformFn: (T) => V): Decoder<V> {
-        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: (value: T) => boolean, errmsg: string): Decoder<T> {
-        return reject((value) =>
-            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<V>(next: AcceptanceFn<V, T>): Decoder<V> {
-        return define((blob, ok, err) => {
-            const 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: (value: T) => string | Annotation | null): Decoder<T> {
-        return then((value, ok, err) => {
-            const 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: string): Decoder<T> {
-        return define((blob, _, err) => {
-            // Decode using the given decoder...
-            const 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<V>(next: AcceptanceFn<V, [mixed, T]>): Decoder<V> {
-        return define((blob, ok, err) => {
-            const result = decode(blob);
-            return result.ok ? next([blob, result.value], ok, err) : result;
-        });
-    }
-
-    return Object.freeze({
-        verify,
-        value,
-        decode,
-        transform,
-        refine,
-        reject,
-        describe,
-        then,
-
-        // EXPERIMENTAL - please DO NOT rely on this method
-        peek_UNSTABLE,
-    });
-}

package/Decoder.mjs

@@ -1,101 +0,0 @@
-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)
-  if (typeof formatted === 'string') {
-    var _err = new Error('\n' + formatted)
-    _err.name = 'Decoding error'
-    return _err
-  } else {
-    return formatted
-  }
-}
-
-export function define(fn) {
-  function decode(blob) {
-    return fn(blob, makeOk, function (msg) {
-      return makeErr(typeof msg === 'string' ? annotate(blob, msg) : msg)
-    })
-  }
-
-  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)
-    }
-  }
-
-  function value(blob) {
-    return decode(blob).value
-  }
-
-  function transform(transformFn) {
-    return then(noThrow(transformFn))
-  }
-
-  function refine(predicateFn, errmsg) {
-    return reject(function (value) {
-      return predicateFn(value) ? null : errmsg
-    })
-  }
-
-  function then(next) {
-    return define(function (blob, ok, err) {
-      var result = decode(blob)
-      return result.ok ? next(result.value, ok, err) : result
-    })
-  }
-
-  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)
-    })
-  }
-
-  function describe(message) {
-    return define(function (blob, _, err) {
-      var result = decode(blob)
-      if (result.ok) {
-        return result
-      } else {
-        return err(annotate(result.error, message))
-      }
-    })
-  }
-
-  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,
-    peek_UNSTABLE: peek_UNSTABLE,
-  })
-}

package/NotSupportedTSVersion.d.ts

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

package/_utils.d.ts

@@ -1,9 +0,0 @@
-import { Annotation } from './annotate';
-
-export function asDate(value: unknown): Date | null;
-export function isMultiline(s: string): boolean;
-export function indent(s: string, prefix?: string): string;
-export function summarize(
-    ann: Annotation,
-    keypath?: ReadonlyArray<number | string>,
-): string[];

package/_utils.js

@@ -1,80 +0,0 @@
-'use strict'
-
-exports.__esModule = true
-exports.INDENT = void 0
-exports.asDate = asDate
-exports.indent = indent
-exports.isMultiline = isMultiline
-exports.subtract = subtract
-exports.summarize = summarize
-var INDENT = '  '
-
-exports.INDENT = INDENT
-function subtract(xs, ys) {
-  var result = new Set()
-  xs.forEach(function (x) {
-    if (!ys.has(x)) {
-      result.add(x)
-    }
-  })
-  return result
-}
-
-function asDate(value) {
-  return !!value && Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value) ? value : null
-}
-function isMultiline(s) {
-  return s.indexOf('\n') >= 0
-}
-function indent(s, prefix) {
-  if (prefix === void 0) {
-    prefix = INDENT
-  }
-  if (isMultiline(s)) {
-    return s
-      .split('\n')
-      .map(function (line) {
-        return '' + prefix + line
-      })
-      .join('\n')
-  } else {
-    return '' + prefix + s
-  }
-}
-
-function summarize(ann, keypath) {
-  if (keypath === void 0) {
-    keypath = []
-  }
-  var result = []
-  if (ann.type === 'array') {
-    var items = ann.items
-    var index = 0
-    items.forEach(function (ann) {
-      summarize(ann, [].concat(keypath, [index++])).forEach(function (item) {
-        return result.push(item)
-      })
-    })
-  } else if (ann.type === 'object') {
-    var fields = ann.fields
-    Object.keys(fields).forEach(function (key) {
-      var value = fields[key]
-      summarize(value, [].concat(keypath, [key])).forEach(function (item) {
-        return result.push(item)
-      })
-    })
-  }
-  var text = ann.text
-  if (!text) {
-    return result
-  }
-  var prefix
-  if (keypath.length === 0) {
-    prefix = ''
-  } else if (keypath.length === 1) {
-    prefix = typeof keypath[0] === 'number' ? 'Value at index ' + keypath[0] + ': ' : 'Value at key ' + JSON.stringify(keypath[0]) + ': '
-  } else {
-    prefix = 'Value at keypath ' + keypath.map(String).join('.') + ': '
-  }
-  return [].concat(result, ['' + prefix + text])
-}