decoders 2.1.0 → 2.2.0-test2

package/index.d.ts

@@ -1,40 +1,454 @@
-export { DecodeResult, Decoder, DecoderType, Scalar, define } from './Decoder';
-export { JSONValue, JSONObject, JSONArray } from './lib/json';
-
-export {
-    always,
-    constant,
-    hardcoded,
-    maybe,
-    mixed,
-    nullable,
-    null_,
-    optional,
-    undefined_,
-    unknown,
-} from './lib/basics';
-export { array, nonEmptyArray, poja, set, tuple } from './lib/arrays';
-export { boolean, numericBoolean, truthy } from './lib/booleans';
-export { date, iso8601 } from './lib/dates';
-export { dict, exact, inexact, mapping, object, pojo } from './lib/objects';
-export { either, oneOf, taggedUnion } from './lib/unions';
-export {
-    email,
-    httpsUrl,
-    nonEmptyString,
-    regex,
-    string,
-    url,
-    uuid,
-    uuidv1,
-    uuidv4,
-} from './lib/strings';
-export { fail, instanceOf, lazy, never, prep } from './lib/utilities';
-export {
-    anyNumber,
-    integer,
-    number,
-    positiveInteger,
-    positiveNumber,
-} from './lib/numbers';
-export { json, jsonObject, jsonArray } from './lib/json';
+import { A as Annotation } from './annotate-0PUmWHxH.js';
+import { Result } from './result.js';
+
+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>;
+type 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>;
+    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
+ *
+ */
+type DecoderType<D extends Decoder<any>> = D extends Decoder<infer T> ? T : 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.
+ */
+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[];
+/**
+ * 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>;
+
+/**
+ * Accepts and returns only the literal `null` value.
+ */
+declare const null_: Decoder<null>;
+/**
+ * Accepts and returns only the literal `undefined` value.
+ */
+declare const undefined_: Decoder<undefined>;
+/**
+ * Accepts whatever the given decoder accepts, or `undefined`.
+ *
+ * If a default value is explicitly provided, return that instead in the
+ * `undefined` case.
+ */
+declare function optional<T>(decoder: Decoder<T>): Decoder<T | undefined>;
+declare function optional<T, C extends Scalar>(decoder: Decoder<T>, defaultValue: (() => C) | C): Decoder<NonNullable<T> | C>;
+declare function optional<T, V>(decoder: Decoder<T>, defaultValue: (() => V) | V): Decoder<NonNullable<T> | V>;
+/**
+ * Accepts whatever the given decoder accepts, or `null`.
+ *
+ * If a default value is explicitly provided, return that instead in the `null`
+ * case.
+ */
+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>;
+/**
+ * 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>;
+/**
+ * Accepts only the given constant value.
+ */
+declare function constant<C extends Scalar>(value: C): Decoder<C>;
+/**
+ * Accepts anything, completely ignores it, and always returns the provided
+ * value instead.
+ *
+ * This is useful to manually add extra fields to object decoders.
+ */
+declare function always<C extends Scalar>(value: C): Decoder<C>;
+declare function always<T>(value: (() => T) | T): Decoder<T>;
+/**
+ * Alias of always.
+ */
+declare const hardcoded: typeof always;
+/**
+ * Accepts anything and returns it unchanged.
+ *
+ * Useful for situation in which you don't know or expect a specific type. Of
+ * course, the downside is that you won't know the type of the value statically
+ * and you'll have to further refine it yourself.
+ */
+declare const unknown: Decoder<unknown>;
+/**
+ * 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.
+ */
+declare const boolean: Decoder<boolean>;
+/**
+ * Accepts anything and will return its "truth" value. Will never reject.
+ */
+declare const truthy: Decoder<boolean>;
+/**
+ * Accepts numbers, but return their boolean representation.
+ */
+declare const numericBoolean: Decoder<boolean>;
+
+/**
+ * Accepts and returns `Date` instances.
+ */
+declare const date: Decoder<Date>;
+/**
+ * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
+ * returns them as `Date` instances.
+ *
+ * This is very useful for working with dates in APIs: serialize them as
+ * `.toISOString()` when sending, decode them with `iso8601` when receiving.
+ */
+declare const iso8601: Decoder<Date>;
+
+type RequiredKeys<T extends object> = {
+    [K in keyof T]: undefined extends T[K] ? never : K;
+}[keyof T];
+/**
+ * Transforms an object type, by marking all fields that contain "undefined"
+ * with a question mark, i.e. allowing implicit-undefineds when
+ * explicit-undefined are also allowed.
+ *
+ * For example, if:
+ *
+ *   type User = {
+ *     name: string;
+ *     age: number | null | undefined;
+ *   }
+ *
+ * Then UndefinedToOptional<User> will become equivalent to:
+ *
+ *   {
+ *     name: string;
+ *     age?: number | null | undefined;
+ *        ^
+ *        Note the question mark
+ *   }
+ */
+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;
+}>;
+/**
+ * Accepts any "plain old JavaScript object", but doesn't validate its keys or
+ * values further.
+ */
+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>>;
+/**
+ * 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];
+}>;
+/**
+ * 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]>;
+}>>;
+
+/**
+ * Accepts and returns strings.
+ */
+declare const string: Decoder<string>;
+/**
+ * Like `string`, but will reject the empty string or strings containing only whitespace.
+ */
+declare const nonEmptyString: Decoder<string>;
+/**
+ * Accepts and returns strings that match the given regular expression.
+ */
+declare function regex(regex: RegExp, msg: string): Decoder<string>;
+/**
+ * Accepts and returns strings that are syntactically valid email addresses.
+ * (This will not mean that the email address actually exist.)
+ */
+declare const email: Decoder<string>;
+/**
+ * Accepts strings that are valid URLs, returns the value as a URL instance.
+ */
+declare const url: Decoder<URL>;
+/**
+ * Accepts strings that are valid URLs, but only HTTPS ones. Returns the value
+ * as a URL instance.
+ */
+declare const httpsUrl: Decoder<URL>;
+/**
+ * Accepts strings that are valid
+ * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
+ * (universally unique identifier).
+ */
+declare const uuid: Decoder<string>;
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv1](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_%28date-time_and_MAC_address%29)
+ * strings.
+ */
+declare const uuidv1: Decoder<string>;
+/**
+ * Like `uuid`, but only accepts
+ * [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_%28random%29)
+ * 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.
+ */
+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.
+ *
+ * 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>;
+
+export { type DecodeResult, type Decoder, type DecoderType, type JSONArray, type JSONObject, type JSONValue, type Scalar, always, anyNumber, array, boolean, constant, date, define, dict, either, email, exact, fail, hardcoded, httpsUrl, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, never, nonEmptyArray, nonEmptyString, null_, nullable, number, numericBoolean, object, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, regex, set, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };