decoders 2.10.1 → 2.12.0

package/dist/index.d.cts

@@ -109,7 +109,6 @@ type DecodeResult<T> = Result<T, Annotation>;
  * 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
@@ -151,16 +150,18 @@ interface Decoder<T> {
      */
     describe(message: string): Decoder<T>;
     /**
-     * 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.
+     * Send the output of the current decoder into an 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._
      */
-    chain<V>(next: Next<V, T>): Decoder<V>;
+    chain<V>(next: (blob: T, ok: (value: V) => DecodeResult<V>, err: (msg: string | Annotation) => DecodeResult<V>) => DecodeResult<V> | Decoder<V>): Decoder<V>;
+    /** @deprecated To send the output into another decoder, use `.pipe()` instead. */
+    chain<V>(next: Decoder<V>): Decoder<V>;
     /**
      * Send the output of this decoder as input to another decoder.
      *
@@ -178,7 +179,7 @@ interface Decoder<T> {
     /**
      * The Standard Schema interface for this decoder.
      */
-    '~standard': StandardSchemaV1.Props<unknown, T>;
+    readonly '~standard': StandardSchemaV1.Props<unknown, T>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -218,6 +219,46 @@ type Formatter = (err: Annotation) => string | Error;
 declare function formatInline(ann: Annotation): string;
 declare function formatShort(ann: Annotation): string;
 
+/**
+ * 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;
+}>;
+
 /**
  * Accepts any array, but doesn't validate its items further.
  *
@@ -227,7 +268,7 @@ declare const poja: Decoder<unknown[]>;
 /**
  * Accepts arrays of whatever the given decoder accepts.
  */
-declare function array<T>(decoder: Decoder<T>): Decoder<T[]>;
+declare function array<T>(decoder: Decoder<T>, options?: SizeOptions): Decoder<T[]>;
 /**
  * Like `array()`, but will reject arrays with 0 elements.
  */
@@ -365,7 +406,7 @@ declare const isoDate: Decoder<Date>;
 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`. */
+/** @deprecated Renamed to `isoDate`. */
 declare const iso8601: Decoder<Date>;
 /** @deprecated Renamed to `flexDate`. This alias will be removed in 3.x. */
 declare const datelike: Decoder<Date>;
@@ -401,46 +442,6 @@ declare const jsonArray: Decoder<JSONArray>;
  */
 declare const json: Decoder<JSONValue>;
 
-/**
- * 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;
 }
@@ -475,21 +476,28 @@ declare function prep<T>(mapperFn: (blob: unknown) => unknown, decoder: Decoder<
  */
 declare const anyNumber: Decoder<number>;
 /**
- * Accepts finite numbers (can be integer or float values). Values `NaN`,
- * or positive and negative `Infinity` will get rejected.
+ * Accepts only finite numbers (e.g. -3.14, 0, 1, 42, ...).
+ * Integers or floats, but not `NaN` or `Infinity`.
  */
 declare const number: Decoder<number>;
 /**
- * Accepts only finite whole numbers.
+ * Accepts only integers (e.g. ..., -2, -1, 0, 1, 2, ...).
+ * Whole numbers, and finite.
  */
 declare const integer: Decoder<number>;
 /**
- * Accepts only non-negative (zero or positive) finite numbers.
+ * Accepts only non-negative numbers (e.g. 0, 0.5, 1, 3.14, ...).
+ * Integers or floats, >= 0, and finite.
  */
-declare const positiveNumber: Decoder<number>;
+declare const nonNegativeNumber: Decoder<number>;
 /**
- * Accepts only non-negative (zero or positive) finite whole numbers.
+ * Accepts only the natural numbers (e.g. 0, 1, 2, 3, ...).
+ * Whole numbers, >= 0, and finite.
  */
+declare const natural: Decoder<number>;
+/** @deprecated Renamed to `nonNegativeNumber`. */
+declare const positiveNumber: Decoder<number>;
+/** @deprecated Renamed to `natural`. */
 declare const positiveInteger: Decoder<number>;
 /**
  * Accepts numbers greater than or equal to the given minimum.
@@ -665,9 +673,10 @@ declare function either<TDecoders extends readonly Decoder<unknown>[]>(...decode
  * 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>;
+declare function oneOf<const C extends Scalar>(constants: readonly C[]): Decoder<C>;
 /**
- * Accepts and return an enum value.
+ * Accepts and return an enum value. Works with TypeScript enums, as well as
+ * with `as const` objects.
  */
 declare function enum_<TEnum extends Record<string, string | number>>(enumObj: TEnum): Decoder<TEnum[keyof TEnum]>;
 /**
@@ -724,4 +733,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 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 };
+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, natural, never, nonEmptyArray, nonEmptyString, nonNegativeNumber, 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

@@ -109,7 +109,6 @@ type DecodeResult<T> = Result<T, Annotation>;
  * 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
@@ -151,16 +150,18 @@ interface Decoder<T> {
      */
     describe(message: string): Decoder<T>;
     /**
-     * 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.
+     * Send the output of the current decoder into an 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._
      */
-    chain<V>(next: Next<V, T>): Decoder<V>;
+    chain<V>(next: (blob: T, ok: (value: V) => DecodeResult<V>, err: (msg: string | Annotation) => DecodeResult<V>) => DecodeResult<V> | Decoder<V>): Decoder<V>;
+    /** @deprecated To send the output into another decoder, use `.pipe()` instead. */
+    chain<V>(next: Decoder<V>): Decoder<V>;
     /**
      * Send the output of this decoder as input to another decoder.
      *
@@ -178,7 +179,7 @@ interface Decoder<T> {
     /**
      * The Standard Schema interface for this decoder.
      */
-    '~standard': StandardSchemaV1.Props<unknown, T>;
+    readonly '~standard': StandardSchemaV1.Props<unknown, T>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -218,6 +219,46 @@ type Formatter = (err: Annotation) => string | Error;
 declare function formatInline(ann: Annotation): string;
 declare function formatShort(ann: Annotation): string;
 
+/**
+ * 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;
+}>;
+
 /**
  * Accepts any array, but doesn't validate its items further.
  *
@@ -227,7 +268,7 @@ declare const poja: Decoder<unknown[]>;
 /**
  * Accepts arrays of whatever the given decoder accepts.
  */
-declare function array<T>(decoder: Decoder<T>): Decoder<T[]>;
+declare function array<T>(decoder: Decoder<T>, options?: SizeOptions): Decoder<T[]>;
 /**
  * Like `array()`, but will reject arrays with 0 elements.
  */
@@ -365,7 +406,7 @@ declare const isoDate: Decoder<Date>;
 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`. */
+/** @deprecated Renamed to `isoDate`. */
 declare const iso8601: Decoder<Date>;
 /** @deprecated Renamed to `flexDate`. This alias will be removed in 3.x. */
 declare const datelike: Decoder<Date>;
@@ -401,46 +442,6 @@ declare const jsonArray: Decoder<JSONArray>;
  */
 declare const json: Decoder<JSONValue>;
 
-/**
- * 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;
 }
@@ -475,21 +476,28 @@ declare function prep<T>(mapperFn: (blob: unknown) => unknown, decoder: Decoder<
  */
 declare const anyNumber: Decoder<number>;
 /**
- * Accepts finite numbers (can be integer or float values). Values `NaN`,
- * or positive and negative `Infinity` will get rejected.
+ * Accepts only finite numbers (e.g. -3.14, 0, 1, 42, ...).
+ * Integers or floats, but not `NaN` or `Infinity`.
  */
 declare const number: Decoder<number>;
 /**
- * Accepts only finite whole numbers.
+ * Accepts only integers (e.g. ..., -2, -1, 0, 1, 2, ...).
+ * Whole numbers, and finite.
  */
 declare const integer: Decoder<number>;
 /**
- * Accepts only non-negative (zero or positive) finite numbers.
+ * Accepts only non-negative numbers (e.g. 0, 0.5, 1, 3.14, ...).
+ * Integers or floats, >= 0, and finite.
  */
-declare const positiveNumber: Decoder<number>;
+declare const nonNegativeNumber: Decoder<number>;
 /**
- * Accepts only non-negative (zero or positive) finite whole numbers.
+ * Accepts only the natural numbers (e.g. 0, 1, 2, 3, ...).
+ * Whole numbers, >= 0, and finite.
  */
+declare const natural: Decoder<number>;
+/** @deprecated Renamed to `nonNegativeNumber`. */
+declare const positiveNumber: Decoder<number>;
+/** @deprecated Renamed to `natural`. */
 declare const positiveInteger: Decoder<number>;
 /**
  * Accepts numbers greater than or equal to the given minimum.
@@ -665,9 +673,10 @@ declare function either<TDecoders extends readonly Decoder<unknown>[]>(...decode
  * 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>;
+declare function oneOf<const C extends Scalar>(constants: readonly C[]): Decoder<C>;
 /**
- * Accepts and return an enum value.
+ * Accepts and return an enum value. Works with TypeScript enums, as well as
+ * with `as const` objects.
  */
 declare function enum_<TEnum extends Record<string, string | number>>(enumObj: TEnum): Decoder<TEnum[keyof TEnum]>;
 /**
@@ -724,4 +733,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 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 };
+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, natural, never, nonEmptyArray, nonEmptyString, nonNegativeNumber, 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 };