decoders 2.9.1-pre.0 → 2.9.2

package/dist/index.d.cts

@@ -351,20 +351,23 @@ declare const date: Decoder<Date>;
 /**
  * Accepts and returns [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings.
  */
-declare const dateString: Decoder<string>;
+declare const isoDateString: Decoder<string>;
 /**
  * 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>;
+declare const isoDate: 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 flexDate: Decoder<Date>;
+/** @deprecated Renamed to `isoDateString`. This alias will be removed in 3.x. */
+declare const dateString: Decoder<string>;
+/** Alias of `isoDate`. */
+declare const iso8601: Decoder<Date>;
+/** @deprecated Renamed to `flexDate`. This alias will be removed in 3.x. */
 declare const datelike: Decoder<Date>;
 
 type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
@@ -398,11 +401,45 @@ declare const jsonArray: Decoder<JSONArray>;
  */
 declare const json: Decoder<JSONValue>;
 
-type SizeOptions = {
-    min?: number;
-    max?: number;
-    size?: number;
+/**
+ * Forces TypeScript to "evaluate" named helper types, making API signatures
+ * clearer in IDEs.
+ *
+ * @see https://effectivetypescript.com/2022/02/25/gentips-4-display/
+ */
+type Resolve$1<T> = T extends (...args: unknown[]) => unknown ? T : {
+    [K in keyof T]: T[K];
 };
+/**
+ * Relaxes a discriminated union type definition, by explicitly adding
+ * properties defined in any other member as optional `never`.
+ *
+ * This makes accessing the members much more relaxed in TypeScript.
+ */
+type Relax<T> = DistributiveRelax<T, T extends any ? keyof T : never>;
+type DistributiveRelax<T, Ks extends string | number | symbol> = T extends any ? Resolve$1<{
+    [K in keyof T]: T[K];
+} & {
+    [K in Exclude<Ks, keyof T>]?: never;
+}> : never;
+
+type SizeOptions = Relax<{
+    size: number;
+} | {
+    min: number;
+    max?: number;
+} | {
+    min?: number;
+    max: number;
+}>;
+/**
+ * Anything with a .length or .size property, like strings, arrays, or sets.
+ */
+type Sized = Relax<{
+    length: number;
+} | {
+    size: number;
+}>;
 
 interface Klass<T> extends Function {
     new (...args: readonly any[]): T;
@@ -417,6 +454,10 @@ declare function instanceOf<K extends Klass<any>>(klass: K): Decoder<Instance<K>
  * types for recursive data structures.
  */
 declare function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;
+/**
+ * Only accept strings, arrays, or sets with given length constraints.
+ */
+declare function sized<T extends Sized>(decoder: Decoder<T>, options: SizeOptions): 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
@@ -450,6 +491,24 @@ declare const positiveNumber: Decoder<number>;
  * Accepts only non-negative (zero or positive) finite whole numbers.
  */
 declare const positiveInteger: Decoder<number>;
+/**
+ * Accepts numbers greater than or equal to the given minimum.
+ * Defaults to the ``number`` decoder if none is provided. Pass a
+ * different decoder to further restrict accepted values, e.g. ``min(0, integer)``.
+ */
+declare function min(min: number, decoder?: Decoder<number>): Decoder<number>;
+/**
+ * Accepts numbers less than or equal to the given maximum.
+ * Defaults to the ``number`` decoder if none is provided. Pass a
+ * different decoder to further restrict accepted values, e.g. ``max(100, integer)``.
+ */
+declare function max(max: number, decoder?: Decoder<number>): Decoder<number>;
+/**
+ * Accepts numbers within the given range (bounds are inclusive).
+ * Defaults to the ``number`` decoder if none is provided. Pass a
+ * different decoder to further restrict accepted values, e.g. ``between(1, 10, integer)``.
+ */
+declare function between(min: number, max: number, decoder?: Decoder<number>): Decoder<number>;
 /**
  * Accepts any valid ``bigint`` value.
  */
@@ -535,6 +594,10 @@ declare function endsWith<S extends string>(suffix: S): Decoder<`${string}${S}`>
  * (This will not mean that the email address actually exist.)
  */
 declare const email: Decoder<string>;
+/**
+ * Accepts strings that are valid URLs.
+ */
+declare const urlString: Decoder<string>;
 /**
  * Accepts strings that are valid URLs, returns the value as a URL instance.
  */
@@ -550,9 +613,10 @@ declare const httpsUrl: Decoder<URL>;
  */
 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.
+ * Accepts and returns [Nano ID](https://zelark.github.io/nano-id-cc) string
+ * values. By default, expects a standard 21-char nanoid, but you can
+ * optionally specify different size constraints. It assumes the default nanoid
+ * alphabet.
  */
 declare function nanoid(options?: SizeOptions): Decoder<string>;
 /**
@@ -660,4 +724,4 @@ declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
  */
 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 
-export { type Annotation, type ArrayAnnotation, type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type ObjectAnnotation, type Ok, type OpaqueAnnotation, type Result, type Scalar, type ScalarAnnotation, type SizeOptions, public_annotate as _annotate, always, anyNumber, anything, array, bigint, boolean, constant, date, dateString, datelike, decimal, define, either, email, endsWith, enum_, err, exact, fail, formatInline, formatShort, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, isDate, isDecoder, isPlainObject, isPromiseLike, iso8601, json, jsonArray, jsonObject, lazy, mapping, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, setFromArray, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };
+export { type Annotation, type ArrayAnnotation, type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type ObjectAnnotation, type Ok, type OpaqueAnnotation, type Relax, type Result, type Scalar, type ScalarAnnotation, type SizeOptions, type Sized, public_annotate as _annotate, always, anyNumber, anything, array, between, bigint, boolean, constant, date, dateString, datelike, decimal, define, either, email, endsWith, enum_, err, exact, fail, flexDate, formatInline, formatShort, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, isDate, isDecoder, isPlainObject, isPromiseLike, iso8601, isoDate, isoDateString, json, jsonArray, jsonObject, lazy, mapping, max, min, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, setFromArray, sized, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, urlString, uuid, uuidv1, uuidv4 };

package/dist/index.d.ts

@@ -351,20 +351,23 @@ declare const date: Decoder<Date>;
 /**
  * Accepts and returns [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings.
  */
-declare const dateString: Decoder<string>;
+declare const isoDateString: Decoder<string>;
 /**
  * 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>;
+declare const isoDate: 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 flexDate: Decoder<Date>;
+/** @deprecated Renamed to `isoDateString`. This alias will be removed in 3.x. */
+declare const dateString: Decoder<string>;
+/** Alias of `isoDate`. */
+declare const iso8601: Decoder<Date>;
+/** @deprecated Renamed to `flexDate`. This alias will be removed in 3.x. */
 declare const datelike: Decoder<Date>;
 
 type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
@@ -398,11 +401,45 @@ declare const jsonArray: Decoder<JSONArray>;
  */
 declare const json: Decoder<JSONValue>;
 
-type SizeOptions = {
-    min?: number;
-    max?: number;
-    size?: number;
+/**
+ * Forces TypeScript to "evaluate" named helper types, making API signatures
+ * clearer in IDEs.
+ *
+ * @see https://effectivetypescript.com/2022/02/25/gentips-4-display/
+ */
+type Resolve$1<T> = T extends (...args: unknown[]) => unknown ? T : {
+    [K in keyof T]: T[K];
 };
+/**
+ * Relaxes a discriminated union type definition, by explicitly adding
+ * properties defined in any other member as optional `never`.
+ *
+ * This makes accessing the members much more relaxed in TypeScript.
+ */
+type Relax<T> = DistributiveRelax<T, T extends any ? keyof T : never>;
+type DistributiveRelax<T, Ks extends string | number | symbol> = T extends any ? Resolve$1<{
+    [K in keyof T]: T[K];
+} & {
+    [K in Exclude<Ks, keyof T>]?: never;
+}> : never;
+
+type SizeOptions = Relax<{
+    size: number;
+} | {
+    min: number;
+    max?: number;
+} | {
+    min?: number;
+    max: number;
+}>;
+/**
+ * Anything with a .length or .size property, like strings, arrays, or sets.
+ */
+type Sized = Relax<{
+    length: number;
+} | {
+    size: number;
+}>;
 
 interface Klass<T> extends Function {
     new (...args: readonly any[]): T;
@@ -417,6 +454,10 @@ declare function instanceOf<K extends Klass<any>>(klass: K): Decoder<Instance<K>
  * types for recursive data structures.
  */
 declare function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;
+/**
+ * Only accept strings, arrays, or sets with given length constraints.
+ */
+declare function sized<T extends Sized>(decoder: Decoder<T>, options: SizeOptions): 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
@@ -450,6 +491,24 @@ declare const positiveNumber: Decoder<number>;
  * Accepts only non-negative (zero or positive) finite whole numbers.
  */
 declare const positiveInteger: Decoder<number>;
+/**
+ * Accepts numbers greater than or equal to the given minimum.
+ * Defaults to the ``number`` decoder if none is provided. Pass a
+ * different decoder to further restrict accepted values, e.g. ``min(0, integer)``.
+ */
+declare function min(min: number, decoder?: Decoder<number>): Decoder<number>;
+/**
+ * Accepts numbers less than or equal to the given maximum.
+ * Defaults to the ``number`` decoder if none is provided. Pass a
+ * different decoder to further restrict accepted values, e.g. ``max(100, integer)``.
+ */
+declare function max(max: number, decoder?: Decoder<number>): Decoder<number>;
+/**
+ * Accepts numbers within the given range (bounds are inclusive).
+ * Defaults to the ``number`` decoder if none is provided. Pass a
+ * different decoder to further restrict accepted values, e.g. ``between(1, 10, integer)``.
+ */
+declare function between(min: number, max: number, decoder?: Decoder<number>): Decoder<number>;
 /**
  * Accepts any valid ``bigint`` value.
  */
@@ -535,6 +594,10 @@ declare function endsWith<S extends string>(suffix: S): Decoder<`${string}${S}`>
  * (This will not mean that the email address actually exist.)
  */
 declare const email: Decoder<string>;
+/**
+ * Accepts strings that are valid URLs.
+ */
+declare const urlString: Decoder<string>;
 /**
  * Accepts strings that are valid URLs, returns the value as a URL instance.
  */
@@ -550,9 +613,10 @@ declare const httpsUrl: Decoder<URL>;
  */
 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.
+ * Accepts and returns [Nano ID](https://zelark.github.io/nano-id-cc) string
+ * values. By default, expects a standard 21-char nanoid, but you can
+ * optionally specify different size constraints. It assumes the default nanoid
+ * alphabet.
  */
 declare function nanoid(options?: SizeOptions): Decoder<string>;
 /**
@@ -660,4 +724,4 @@ declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
  */
 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 
-export { type Annotation, type ArrayAnnotation, type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type ObjectAnnotation, type Ok, type OpaqueAnnotation, type Result, type Scalar, type ScalarAnnotation, type SizeOptions, public_annotate as _annotate, always, anyNumber, anything, array, bigint, boolean, constant, date, dateString, datelike, decimal, define, either, email, endsWith, enum_, err, exact, fail, formatInline, formatShort, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, isDate, isDecoder, isPlainObject, isPromiseLike, iso8601, json, jsonArray, jsonObject, lazy, mapping, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, setFromArray, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };
+export { type Annotation, type ArrayAnnotation, type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type ObjectAnnotation, type Ok, type OpaqueAnnotation, type Relax, type Result, type Scalar, type ScalarAnnotation, type SizeOptions, type Sized, public_annotate as _annotate, always, anyNumber, anything, array, between, bigint, boolean, constant, date, dateString, datelike, decimal, define, either, email, endsWith, enum_, err, exact, fail, flexDate, formatInline, formatShort, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, isDate, isDecoder, isPlainObject, isPromiseLike, iso8601, isoDate, isoDateString, json, jsonArray, jsonObject, lazy, mapping, max, min, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, setFromArray, sized, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, urlString, uuid, uuidv1, uuidv4 };