decoders 2.3.0-test4 → 2.4.0

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,9 +53,14 @@ 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>;
-type AcceptanceFn<T, InputT = unknown> = (blob: InputT, ok: (value: T) => DecodeResult<T>, err: (msg: string | Annotation) => DecodeResult<T>) => DecodeResult<T>;
+/**
+ * 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<O, I = unknown> = (blob: I, ok: (value: O) => DecodeResult<O>, err: (msg: string | Annotation) => DecodeResult<O>) => DecodeResult<O>;
+type Next<O, I = unknown> = Decoder<O> | ((blob: I, ok: (value: O) => DecodeResult<O>, err: (msg: string | Annotation) => DecodeResult<O>) => DecodeResult<O> | Decoder<O>);
 interface Decoder<T> {
     /**
      * Verifies untrusted input. Either returns a value, or throws a decoding
@@ -94,24 +97,45 @@ 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 decoder or acceptance
+     * function. The given acceptance function will receive the output of the
+     * current decoder as its input.
+     *
+     * > _**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()`, `.refine()`, or `.pipe()`
+     * > instead._
+     */
+    then<V>(next: Next<V, T>): Decoder<V>;
+    /**
+     * Send the output of this decoder as input to another decoder.
+     *
+     * This can be useful to validate the results of a transform, i.e.:
+     *
+     *   string
+     *     .transform((s) => s.split(','))
+     *     .pipe(array(nonEmptyString))
+     *
+     * You can also conditionally pipe:
+     *
+     *   string.pipe((s) => s.startsWith('@') ? username : email)
      */
-    then<V>(next: AcceptanceFn<V, T>): Decoder<V>;
-    peek_UNSTABLE<V>(next: AcceptanceFn<V, [unknown, T]>): Decoder<V>;
+    pipe<V, D extends Decoder<V>>(next: D): Decoder<DecoderType<D>>;
+    pipe<V, D extends Decoder<V>>(next: (blob: T) => D): Decoder<DecoderType<D>>;
 }
 /**
- * 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 +153,34 @@ 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[]]>;
+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.
@@ -187,8 +209,9 @@ 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().
+ * @deprecated Will get removed in a future version.
+ *
+ * Alias of `nullish()`.
  */
 declare const maybe: typeof nullish;
 /**
@@ -218,12 +241,13 @@ declare function always<T>(value: (() => T) | T): Decoder<T>;
  */
 declare function never(msg: string): Decoder<never>;
 /**
- * Alias of never().
+ * Alias of `never()`.
  */
 declare const fail: typeof never;
 /**
- * @deprecated
- * Alias of always.
+ * Alias of `always()`.
+ *
+ * @deprecated Will get removed in a future version.
  */
 declare const hardcoded: typeof always;
 /**
@@ -235,53 +259,56 @@ declare const hardcoded: typeof always;
  */
 declare const unknown: Decoder<unknown>;
 /**
- * @deprecated
- * Alias of unknown.
+ * Alias of `unknown`.
+ *
+ * @deprecated Will get removed in a future version.
  */
 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()`.
+ * Accepts and returns booleans.
  */
-declare const poja: Decoder<unknown[]>;
+declare const boolean: Decoder<boolean>;
 /**
- * Accepts arrays of whatever the given decoder accepts.
+ * Accepts anything and will return its "truth" value. Will never reject.
  */
-declare function array<T>(decoder: Decoder<T>): Decoder<T[]>;
+declare const truthy: Decoder<boolean>;
+
 /**
- * Like `array()`, but will reject arrays with 0 elements.
+ * Accepts objects where all values match the given decoder, and returns the
+ * result as a `Record<string, V>`.
  */
-declare function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<[T, ...T[]]>;
+declare function record<V>(valueDecoder: Decoder<V>): Decoder<Record<string, V>>;
 /**
- * Similar to `array()`, but returns the result as an [ES6
- * Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
+ * Accepts objects where all keys and values match the given decoders, and
+ * returns the result as a `Record<K, V>`. The given key decoder must return
+ * strings.
  */
-declare function set<T>(decoder: Decoder<T>): Decoder<Set<T>>;
+declare function record<K extends string, V>(keyDecoder: Decoder<K>, valueDecoder: Decoder<V>): Decoder<Record<K, V>>;
 /**
- * Accepts a tuple (an array with exactly _n_ items) of values accepted by the
- * _n_ given decoders.
+ * @deprecated Will get removed in a future version.
+ *
+ * Alias of `record()`.
  */
-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]>;
-
+declare const dict: typeof record;
 /**
- * Accepts and returns booleans.
+ * 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 const boolean: Decoder<boolean>;
+declare function setFromArray<T>(decoder: Decoder<T>): Decoder<Set<T>>;
 /**
- * Accepts anything and will return its "truth" value. Will never reject.
+ * Renamed to `setFromArray` to make room for a future `set()` decoder that
+ * works differently.
+ *
+ * @deprecated This decoder will change behavior in a future version.
  */
-declare const truthy: Decoder<boolean>;
+declare const set: typeof setFromArray;
 /**
- * Accepts numbers, but return their boolean representation.
+ * Similar to `record()`, but returns the result as a `Map<string, T>` (an [ES6
+ * Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map))
+ * instead.
  */
-declare const numericBoolean: Decoder<boolean>;
+declare function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;
 
 /**
  * Accepts and returns `Date` instances.
@@ -295,10 +322,107 @@ declare const date: Decoder<Date>;
  * `.toISOString()` when sending, decode them with `iso8601` when receiving.
  */
 declare const iso8601: Decoder<Date>;
+/**
+ * Accepts either a Date, or an ISO date string, returns a Date instance.
+ * This is commonly useful to build decoders that can be reused to validate
+ * object with Date instances as well as objects coming from JSON payloads.
+ */
+declare const datelike: 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>;
+
+type SizeOptions = {
+    min?: number;
+    max?: number;
+    size?: number;
+};
+
+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
@@ -321,12 +445,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
@@ -337,88 +457,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>>;
-/**
- * Accepts objects where all values match the given decoder, and returns the
- * result as a `Record<string, T>`.
- *
- * The main difference between `object()` and `dict()` is that you'd typically
- * use `object()` if this is a record-like object, where all field names are
- * known and the values are heterogeneous. Whereas with `dict()` the keys are
- * typically dynamic and the values homogeneous, like in a dictionary,
- * a lookup table, or a cache.
- */
-declare function dict<T>(decoder: Decoder<T>): Decoder<Record<string, T>>;
-/**
- * Similar to `dict()`, but returns the result as a `Map<string, T>` (an [ES6
- * Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map))
- * instead.
- */
-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]>;
-}>>;
+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 and returns strings.
@@ -446,6 +498,17 @@ declare const url: Decoder<URL>;
  * as a URL instance.
  */
 declare const httpsUrl: Decoder<URL>;
+/**
+ * Accepts and returns strings that are valid identifiers in most programming
+ * languages.
+ */
+declare const identifier: Decoder<string>;
+/**
+ * Accepts and returns [nanoid](https://zelark.github.io/nano-id-cc) string
+ * values. It assumes the default nanoid alphabet. If you're using a custom
+ * alphabet, use `regex()` instead.
+ */
+declare function nanoid(options?: SizeOptions): Decoder<string>;
 /**
  * Accepts strings that are valid
  * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
@@ -464,56 +527,77 @@ declare const uuidv1: Decoder<string>;
  * strings.
  */
 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.
+ * Accepts and returns strings with decimal digits only (base-10).
+ * To convert these to numbers, use the `numeric` decoder.
  */
-declare function instanceOf<K extends Klass<any>>(klass: K): Decoder<Instance<K>>;
+declare const decimal: Decoder<string>;
 /**
- * Lazily evaluate the given decoder. This is useful to build self-referential
- * types for recursive data structures.
+ * Accepts and returns strings with hexadecimal digits only (base-16).
  */
-declare function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;
+declare const hexadecimal: Decoder<string>;
 /**
- * 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.
+ * Accepts valid numerical strings (in base-10) and returns them as a number.
+ * To only accept numerical strings and keep them as string values, use the
+ * `decimal` decoder.
  */
-declare function prep<T>(mapperFn: (blob: unknown) => unknown, decoder: Decoder<T>): Decoder<T>;
+declare const numeric: Decoder<number>;
 
 /**
- * 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.
+ * 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 anyNumber: Decoder<number>;
+declare function either<TDecoders extends readonly Decoder<unknown>[]>(...decoders: TDecoders): Decoder<DecoderType<TDecoders[number]>>;
 /**
- * Accepts finite numbers (can be integer or float values). Values `NaN`,
- * or positive and negative `Infinity` will get rejected.
+ * Accepts any value that is strictly-equal (using `===`) to one of the
+ * specified values.
  */
-declare const number: Decoder<number>;
+declare function oneOf<C extends Scalar>(constants: readonly C[]): Decoder<C>;
 /**
- * Accepts only finite whole numbers.
+ * Accepts and return an enum value.
  */
-declare const integer: Decoder<number>;
+declare function enum_<TEnum extends Record<string, string | number>>(enumObj: TEnum): Decoder<TEnum[keyof TEnum]>;
 /**
- * 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, nullish, 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, type SizeOptions, always, anyNumber, array, bigint, boolean, constant, date, datelike, decimal, define, dict, either, email, enum_, err, exact, fail, formatInline, formatShort, hardcoded, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, set, setFromArray, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };