decoders 2.2.0 → 2.3.0-beta.1

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 interface ObjectAnnotation {
     readonly type: 'object';
-    readonly fields: {
-        readonly [key: string]: Annotation;
-    };
+    readonly fields: ReadonlyMap<string, Annotation>;
     readonly text?: string;
 }
 interface ArrayAnnotation {
@@ -55,8 +53,12 @@ declare function ok<T>(value: T): Ok<T>;
  */
 declare function err<E>(error: E): Err<E>;
 
-type Scalar = string | number | boolean | symbol | undefined | null;
 type DecodeResult<T> = Result<T, Annotation>;
+/**
+ * A function taking a untrusted input, and returning a DecodeResult<T>. The
+ * `ok()` and `err()` constructor functions are provided as the 2nd and 3rd
+ * param. One of these should be called and its value returned.
+ */
 type AcceptanceFn<T, InputT = unknown> = (blob: InputT, ok: (value: T) => DecodeResult<T>, err: (msg: string | Annotation) => DecodeResult<T>) => DecodeResult<T>;
 interface Decoder<T> {
     /**
@@ -94,24 +96,37 @@ interface Decoder<T> {
      */
     describe(message: string): Decoder<T>;
     /**
-     * Chain together the current decoder with another acceptance function.
+     * Send the output of the current decoder into another acceptance function.
+     * The given acceptance function will receive the output of the current
+     * decoder as its input, making it partially trusted.
+     *
+     * 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.
+     *
+     * > _**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 it helps, you can think of `define(...)` as equivalent to
+     * `unknown.then(...)`.
      */
     then<V>(next: AcceptanceFn<V, T>): Decoder<V>;
-    peek_UNSTABLE<V>(next: AcceptanceFn<V, [unknown, T]>): Decoder<V>;
 }
 /**
- * Helper type to return the "type" of a Decoder.
+ * Helper type to return the output type of a Decoder.
+ * It’s the inverse of Decoder<T>.
  *
- * You can use it on types:
+ * You can use it at the type level:
  *
  *   DecoderType<Decoder<string>>    // string
  *   DecoderType<Decoder<number[]>>  // number[]
  *
- * Or on "values", by using the `typeof` keyword:
+ * Or on decoder instances, by using the `typeof` keyword:
  *
  *   DecoderType<typeof string>      // string
  *   DecoderType<typeof truthy>      // boolean
- *
  */
 type DecoderType<D extends Decoder<any>> = D extends Decoder<infer T> ? T : never;
 /**
@@ -129,36 +144,39 @@ type DecoderType<D extends Decoder<any>> = D extends Decoder<infer T> ? T : neve
  */
 declare function define<T>(fn: AcceptanceFn<T>): Decoder<T>;
 
-type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
-type JSONObject = {
-    [key: string]: JSONValue | undefined;
-};
-type JSONArray = JSONValue[];
+type Formatter = (err: Annotation) => string | Error;
+declare function formatInline(ann: Annotation): string;
+declare function formatShort(ann: Annotation): string;
+
 /**
- * Accepts objects that contain only valid JSON values.
+ * Accepts any array, but doesn't validate its items further.
+ *
+ * "poja" means "plain old JavaScript array", a play on `pojo()`.
  */
-declare const jsonObject: Decoder<JSONObject>;
+declare const poja: Decoder<unknown[]>;
 /**
- * Accepts arrays that contain only valid JSON values.
+ * Accepts arrays of whatever the given decoder accepts.
  */
-declare const jsonArray: Decoder<JSONArray>;
+declare function array<T>(decoder: Decoder<T>): Decoder<T[]>;
 /**
- * Accepts any value that's a valid JSON value.
- *
- * In other words: any value returned by `JSON.parse()` should decode without
- * failure.
- *
- * ```typescript
- * type JSONValue =
- *     | null
- *     | string
- *     | number
- *     | boolean
- *     | { [string]: JSONValue }
- *     | JSONValue[]
- * ```
+ * Like `array()`, but will reject arrays with 0 elements.
  */
-declare const json: Decoder<JSONValue>;
+declare function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<[T, ...T[]]>;
+/**
+ * Similar to `array()`, but returns the result as an [ES6
+ * Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+ */
+declare function set<T>(decoder: Decoder<T>): Decoder<Set<T>>;
+type TupleDecoderType<Ds extends readonly Decoder<unknown>[]> = {
+    [K in keyof Ds]: DecoderType<Ds[K]>;
+};
+/**
+ * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
+ * _n_ given decoders.
+ */
+declare function tuple<Ds extends readonly [first: Decoder<unknown>, ...rest: readonly Decoder<unknown>[]]>(...decoders: Ds): Decoder<TupleDecoderType<Ds>>;
+
+type Scalar = string | number | boolean | symbol | undefined | null;
 
 /**
  * Accepts and returns only the literal `null` value.
@@ -186,15 +204,20 @@ declare function optional<T, V>(decoder: Decoder<T>, defaultValue: (() => V) | V
 declare function nullable<T>(decoder: Decoder<T>): Decoder<T | null>;
 declare function nullable<T, C extends Scalar>(decoder: Decoder<T>, defaultValue: (() => C) | C): Decoder<NonNullable<T> | C>;
 declare function nullable<T, V>(decoder: Decoder<T>, defaultValue: (() => V) | V): Decoder<NonNullable<T> | V>;
+/**
+ * @deprecated
+ * Alias of nullish().
+ */
+declare const maybe: typeof nullish;
 /**
  * Accepts whatever the given decoder accepts, or `null`, or `undefined`.
  *
  * If a default value is explicitly provided, return that instead in the
  * `null`/`undefined` case.
  */
-declare function maybe<T>(decoder: Decoder<T>): Decoder<T | null | undefined>;
-declare function maybe<T, C extends Scalar>(decoder: Decoder<T>, defaultValue: (() => C) | C): Decoder<NonNullable<T> | C>;
-declare function maybe<T, V>(decoder: Decoder<T>, defaultValue: (() => V) | V): Decoder<NonNullable<T> | V>;
+declare function nullish<T>(decoder: Decoder<T>): Decoder<T | null | undefined>;
+declare function nullish<T, C extends Scalar>(decoder: Decoder<T>, defaultValue: (() => C) | C): Decoder<NonNullable<T> | C>;
+declare function nullish<T, V>(decoder: Decoder<T>, defaultValue: (() => V) | V): Decoder<NonNullable<T> | V>;
 /**
  * Accepts only the given constant value.
  */
@@ -208,6 +231,16 @@ declare function constant<C extends Scalar>(value: C): Decoder<C>;
 declare function always<C extends Scalar>(value: C): Decoder<C>;
 declare function always<T>(value: (() => T) | 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.
+ */
+declare function never(msg: string): Decoder<never>;
+/**
+ * Alias of never().
+ */
+declare const fail: typeof never;
+/**
+ * @deprecated
  * Alias of always.
  */
 declare const hardcoded: typeof always;
@@ -220,40 +253,11 @@ declare const hardcoded: typeof always;
  */
 declare const unknown: Decoder<unknown>;
 /**
+ * @deprecated
  * Alias of unknown.
  */
 declare const mixed: Decoder<unknown>;
 
-/**
- * Accepts any array, but doesn't validate its items further.
- *
- * "poja" means "plain old JavaScript array", a play on `pojo()`.
- */
-declare const poja: Decoder<unknown[]>;
-/**
- * Accepts arrays of whatever the given decoder accepts.
- */
-declare function array<T>(decoder: Decoder<T>): Decoder<T[]>;
-/**
- * Like `array()`, but will reject arrays with 0 elements.
- */
-declare function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<[T, ...T[]]>;
-/**
- * Similar to `array()`, but returns the result as an [ES6
- * Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
- */
-declare function set<T>(decoder: Decoder<T>): Decoder<Set<T>>;
-/**
- * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
- * _n_ given decoders.
- */
-declare function tuple<A>(a: Decoder<A>): Decoder<[A]>;
-declare function tuple<A, B>(a: Decoder<A>, b: Decoder<B>): Decoder<[A, B]>;
-declare function tuple<A, B, C>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>): Decoder<[A, B, C]>;
-declare function tuple<A, B, C, D>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>): Decoder<[A, B, C, D]>;
-declare function tuple<A, B, C, D, E>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>, e: Decoder<E>): Decoder<[A, B, C, D, E]>;
-declare function tuple<A, B, C, D, E, F>(a: Decoder<A>, b: Decoder<B>, c: Decoder<C>, d: Decoder<D>, e: Decoder<E>, f: Decoder<F>): Decoder<[A, B, C, D, E, F]>;
-
 /**
  * Accepts and returns booleans.
  */
@@ -280,9 +284,94 @@ declare const date: Decoder<Date>;
  */
 declare const iso8601: Decoder<Date>;
 
+type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+type JSONObject = {
+    [key: string]: JSONValue | undefined;
+};
+type JSONArray = JSONValue[];
+/**
+ * Accepts objects that contain only valid JSON values.
+ */
+declare const jsonObject: Decoder<JSONObject>;
+/**
+ * Accepts arrays that contain only valid JSON values.
+ */
+declare const jsonArray: Decoder<JSONArray>;
+/**
+ * Accepts any value that's a valid JSON value.
+ *
+ * In other words: any value returned by `JSON.parse()` should decode without
+ * failure.
+ *
+ * ```typescript
+ * type JSONValue =
+ *     | null
+ *     | string
+ *     | number
+ *     | boolean
+ *     | { [string]: JSONValue }
+ *     | JSONValue[]
+ * ```
+ */
+declare const json: Decoder<JSONValue>;
+
+interface Klass<T> extends Function {
+    new (...args: readonly any[]): T;
+}
+type Instance<K> = K extends Klass<infer T> ? T : never;
+/**
+ * Accepts any value that is an ``instanceof`` the given class.
+ */
+declare function instanceOf<K extends Klass<any>>(klass: K): Decoder<Instance<K>>;
+/**
+ * Lazily evaluate the given decoder. This is useful to build self-referential
+ * types for recursive data structures.
+ */
+declare 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.
+ */
+declare function prep<T>(mapperFn: (blob: unknown) => unknown, decoder: Decoder<T>): Decoder<T>;
+
+/**
+ * Accepts any valid ``number`` value.
+ *
+ * This also accepts special values like `NaN` and `Infinity`. Unless you
+ * want to deliberately accept those, you'll likely want to use the
+ * `number` decoder instead.
+ */
+declare const anyNumber: Decoder<number>;
+/**
+ * Accepts finite numbers (can be integer or float values). Values `NaN`,
+ * or positive and negative `Infinity` will get rejected.
+ */
+declare const number: Decoder<number>;
+/**
+ * Accepts only finite whole numbers.
+ */
+declare const integer: Decoder<number>;
+/**
+ * Accepts only non-negative (zero or positive) finite numbers.
+ */
+declare const positiveNumber: Decoder<number>;
+/**
+ * Accepts only non-negative (zero or positive) finite whole numbers.
+ */
+declare const positiveInteger: Decoder<number>;
+/**
+ * Accepts any valid ``bigint`` value.
+ */
+declare const bigint: Decoder<bigint>;
+
 type RequiredKeys<T extends object> = {
     [K in keyof T]: undefined extends T[K] ? never : K;
 }[keyof T];
+type Resolve<T> = T extends (...args: readonly unknown[]) => unknown ? T : {
+    [K in keyof T]: T[K];
+};
 /**
  * Transforms an object type, by marking all fields that contain "undefined"
  * with a question mark, i.e. allowing implicit-undefineds when
@@ -305,12 +394,8 @@ type RequiredKeys<T extends object> = {
  *   }
  */
 type UndefinedToOptional<T extends object> = Resolve<Pick<Required<T>, RequiredKeys<T>> & Partial<T>>;
-type Resolve<T> = T extends (...args: readonly unknown[]) => unknown ? T : {
-    [K in keyof T]: T[K];
-};
-
-type ObjectDecoderType<T> = UndefinedToOptional<{
-    [K in keyof T]: T[K] extends Decoder<infer V> ? V : never;
+type ObjectDecoderType<Ds extends Record<string, Decoder<unknown>>> = UndefinedToOptional<{
+    [K in keyof Ds]: DecoderType<Ds[K]>;
 }>;
 /**
  * Accepts any "plain old JavaScript object", but doesn't validate its keys or
@@ -321,24 +406,20 @@ declare const pojo: Decoder<Record<string, unknown>>;
  * Accepts objects with fields matching the given decoders. Extra fields that
  * exist on the input object are ignored and will not be returned.
  */
-declare function object(decodersByKey: Record<any, never>): Decoder<Record<string, never>>;
-declare function object<DS extends Record<string, Decoder<any>>>(decodersByKey: DS): Decoder<ObjectDecoderType<DS>>;
+declare function object(decoders: Record<any, never>): Decoder<Record<string, never>>;
+declare function object<Ds extends Record<string, Decoder<unknown>>>(decoders: Ds): Decoder<ObjectDecoderType<Ds>>;
 /**
  * Like `object()`, but will reject inputs that contain extra fields that are
  * not specified explicitly.
  */
-declare function exact(decodersByKey: Record<any, never>): Decoder<Record<string, never>>;
-declare function exact<O extends Record<string, Decoder<any>>>(decodersByKey: O): Decoder<{
-    [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K];
-}>;
+declare function exact(decoders: Record<any, never>): Decoder<Record<string, never>>;
+declare function exact<Ds extends Record<string, Decoder<unknown>>>(decoders: Ds): Decoder<ObjectDecoderType<Ds>>;
 /**
  * Like `object()`, but will pass through any extra fields on the input object
  * unvalidated that will thus be of `unknown` type statically.
  */
-declare function inexact(decodersByKey: Record<any, never>): Decoder<Record<string, unknown>>;
-declare function inexact<O extends Record<string, Decoder<any>>>(decodersByKey: O): Decoder<{
-    [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K];
-} & Record<string, unknown>>;
+declare function inexact(decoders: Record<any, never>): Decoder<Record<string, unknown>>;
+declare function inexact<Ds extends Record<string, Decoder<unknown>>>(decoders: Ds): Decoder<ObjectDecoderType<Ds> & Record<string, unknown>>;
 /**
  * Accepts objects where all values match the given decoder, and returns the
  * result as a `Record<string, T>`.
@@ -357,53 +438,6 @@ declare function dict<T>(decoder: Decoder<T>): Decoder<Record<string, T>>;
  */
 declare function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;
 
-type Values<T extends object> = T[keyof T];
-type DecoderTypes<T> = T extends readonly Decoder<infer U>[] ? U : never;
-/**
- * Accepts values accepted by any of the given decoders.
- *
- * The decoders are tried on the input one by one, in the given order. The
- * first one that accepts the input "wins". If all decoders reject the input,
- * the input gets rejected.
- */
-declare function either<T extends readonly Decoder<any>[]>(...decoders: T): Decoder<DecoderTypes<T>>;
-/**
- * Accepts any value that is strictly-equal (using `===`) to one of the
- * specified values.
- */
-declare function oneOf<C extends Scalar>(constants: readonly C[]): Decoder<C>;
-/**
- * If you are decoding tagged unions you may want to use the `taggedUnion()`
- * decoder instead of the general purpose `either()` decoder to get better
- * error messages and better performance.
- *
- * This decoder is optimized for [tagged
- * unions](https://en.wikipedia.org/wiki/Tagged_union), i.e. a union of
- * objects where one field is used as the discriminator.
- *
- * ```ts
- * const A = object({ tag: constant('A'), foo: string });
- * const B = object({ tag: constant('B'), bar: number });
- *
- * const AorB = taggedUnion('tag', { A, B });
- * //                        ^^^
- * ```
- *
- * Decoding now works in two steps:
- *
- * 1. Look at the `'tag'` field in the incoming object (this is the field
- *    that decides which decoder will be used)
- * 2. If the value is `'A'`, then decoder `A` will be used. If it's `'B'`, then
- *    decoder `B` will be used. Otherwise, this will fail.
- *
- * This is effectively equivalent to `either(A, B)`, but will provide better
- * error messages and is more performant at runtime because it doesn't have to
- * try all decoders one by one.
- */
-declare function taggedUnion<O extends Record<string, Decoder<any>>>(field: string, mapping: O): Decoder<Values<{
-    [key in keyof O]: DecoderType<O[key]>;
-}>>;
-
 /**
  * Accepts and returns strings.
  */
@@ -449,64 +483,57 @@ declare const uuidv1: Decoder<string>;
  */
 declare const uuidv4: Decoder<string>;
 
-interface Klass<T> extends Function {
-    new (...args: readonly any[]): T;
-}
-type Instance<K> = K extends Klass<infer T> ? T : never;
-/**
- * Accepts any value that is an ``instanceof`` the given class.
- */
-declare function instanceOf<K extends Klass<any>>(klass: K): Decoder<Instance<K>>;
-/**
- * Lazily evaluate the given decoder. This is useful to build self-referential
- * types for recursive data structures.
- */
-declare 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.
- */
-declare 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.
- */
-declare function never(msg: string): Decoder<never>;
-/**
- * Alias of never().
- */
-declare const fail: typeof never;
-
 /**
- * Accepts any valid ``number`` value.
+ * Accepts values accepted by any of the given decoders.
  *
- * This also accepts special values like `NaN` and `Infinity`. Unless you
- * want to deliberately accept those, you'll likely want to use the
- * `number` decoder instead.
- */
-declare const anyNumber: Decoder<number>;
-/**
- * Accepts finite numbers (can be integer or float values). Values `NaN`,
- * or positive and negative `Infinity` will get rejected.
+ * The decoders are tried on the input one by one, in the given order. The
+ * first one that accepts the input "wins". If all decoders reject the input,
+ * the input gets rejected.
  */
-declare const number: Decoder<number>;
+declare function either<TDecoders extends readonly Decoder<unknown>[], T = DecoderType<TDecoders[number]>>(...decoders: TDecoders): Decoder<T>;
 /**
- * Accepts only finite whole numbers.
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
  */
-declare const integer: Decoder<number>;
+declare function oneOf<C extends Scalar>(constants: readonly C[]): Decoder<C>;
 /**
- * Accepts only non-negative (zero or positive) finite numbers.
+ * If you are decoding tagged unions you may want to use the `taggedUnion()`
+ * decoder instead of the general purpose `either()` decoder to get better
+ * error messages and better performance.
+ *
+ * This decoder is optimized for [tagged
+ * unions](https://en.wikipedia.org/wiki/Tagged_union), i.e. a union of
+ * objects where one field is used as the discriminator.
+ *
+ * ```ts
+ * const A = object({ tag: constant('A'), foo: string });
+ * const B = object({ tag: constant('B'), bar: number });
+ *
+ * const AorB = taggedUnion('tag', { A, B });
+ * //                        ^^^
+ * ```
+ *
+ * Decoding now works in two steps:
+ *
+ * 1. Look at the `'tag'` field in the incoming object (this is the field
+ *    that decides which decoder will be used)
+ * 2. If the value is `'A'`, then decoder `A` will be used. If it's `'B'`, then
+ *    decoder `B` will be used. Otherwise, this will fail.
+ *
+ * This is effectively equivalent to `either(A, B)`, but will provide better
+ * error messages and is more performant at runtime because it doesn't have to
+ * try all decoders one by one.
  */
-declare const positiveNumber: Decoder<number>;
+declare function taggedUnion<O extends Record<string, Decoder<unknown>>, T = DecoderType<O[keyof O]>>(field: string, mapping: O): Decoder<T>;
 /**
- * Accepts only non-negative (zero or positive) finite whole numbers.
+ * Briefly peek at a runtime input using a "scout" decoder first, then decide
+ * which decoder to run on the (original) input, based on the information that
+ * the "scout" extracted.
+ *
+ * It serves a similar purpose as `taggedUnion()`, but is a generalization that
+ * works even if there isn't a single discriminator, or the discriminator isn't
+ * a string.
  */
-declare const positiveInteger: Decoder<number>;
-
-type Formatter = (err: Annotation) => string | Error;
-declare function formatInline(ann: Annotation): string;
-declare function formatShort(ann: Annotation): string;
+declare function select<T, D extends Decoder<unknown>>(scout: Decoder<T>, selectFn: (result: T) => D): Decoder<DecoderType<D>>;
 
-export { type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type Ok, type Result, type Scalar, always, anyNumber, array, boolean, constant, date, define, dict, either, email, err, exact, fail, formatInline, formatShort, hardcoded, httpsUrl, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, never, nonEmptyArray, nonEmptyString, null_, nullable, number, numericBoolean, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, regex, set, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };
+export { type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type Ok, type Result, type Scalar, always, anyNumber, array, bigint, boolean, constant, date, define, dict, either, email, err, exact, fail, formatInline, formatShort, hardcoded, httpsUrl, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numericBoolean, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, regex, select, set, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };