UNPKG

type-fest

Version:

A collection of essential TypeScript types

326 lines (226 loc) • 8.37 kB
import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts'; import type {IsFloat} from './is-float.d.ts'; import type {IsInteger} from './is-integer.d.ts'; import type {IsNumericLiteral} from './is-numeric-literal.d.ts'; import type {IsAny} from './is-any.d.ts'; import type {IsNever} from './is-never.d.ts'; import type {Tagged} from './tagged.d.ts'; // For `@link` export type _Numeric = number | bigint; type Zero = 0 | 0n; /** Matches the hidden `Infinity` type. Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/32277) if you want to have this type as a built-in in TypeScript. @see {@link NegativeInfinity} @category Numeric */ // See https://github.com/microsoft/TypeScript/issues/31752 // eslint-disable-next-line no-loss-of-precision export type PositiveInfinity = 1e999; /** Matches the hidden `-Infinity` type. Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/32277) if you want to have this type as a built-in in TypeScript. @see {@link PositiveInfinity} @category Numeric */ // See https://github.com/microsoft/TypeScript/issues/31752 // eslint-disable-next-line no-loss-of-precision export type NegativeInfinity = -1e999; /** A finite `number`. You can't pass a `bigint` as they are already guaranteed to be finite. Use-case: Validating and documenting parameters. Note: TypeScript types the `NaN`, `Infinity`, and `-Infinity` values as `number`, so a wide `number` can't be proven finite and is rejected. To accept a value that is only known at runtime, accept a {@link Tagged} brand next to `Finite<T>` in the parameter type, as shown in the last example. Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/28682) if you want to have a `NaN` type as a built-in in TypeScript. @example ``` import type {Finite, PositiveInfinity} from 'type-fest'; type A = Finite<1.5>; //=> 1.5 type B = Finite<PositiveInfinity>; //=> never type C = Finite<number>; //=> never ``` @example ``` import type {Finite, Tagged} from 'type-fest'; type FiniteNumber = Tagged<number, 'Finite'>; function isFiniteNumber(value: number): value is FiniteNumber { return Number.isFinite(value); } declare function setScore<T extends number>(score: Finite<T> | FiniteNumber): void; setScore(1.5); declare const input: number; if (isFiniteNumber(input)) { setScore(input); } ``` @category Numeric */ export type Finite<T extends number> = T extends PositiveInfinity | NegativeInfinity ? never : IsNumericLiteral<T> extends true ? T : never; /** A `number` that is an integer. Use-case: Validating and documenting parameters. @example ``` import type {Integer} from 'type-fest'; type SomeInteger = Integer<1>; //=> 1 type IntegerWithDecimal = Integer<1.0>; //=> 1 type NegativeInteger = Integer<-1>; //=> -1 type Float = Integer<1.5>; //=> never // Supports non-decimal numbers type OctalInteger = Integer<0o10>; //=> 8 type BinaryInteger = Integer<0b10>; //=> 2 type HexadecimalInteger = Integer<0x10>; //=> 16 ``` @example ``` import type {Integer} from 'type-fest'; declare function setYear<T extends number>(length: Integer<T>): void; ``` @see {@link NegativeInteger} @see {@link NonNegativeInteger} @category Numeric */ // `${bigint}` is a type that matches a valid bigint literal without the `n` (ex. 1, 0b1, 0o1, 0x1) // Because T is a number and not a string we can effectively use this to filter out any numbers containing decimal points export type Integer<T> = T extends unknown // To distributive type ? IsInteger<T> extends true ? T : never : never; // Never happens /** A `number` that is not an integer. Use-case: Validating and documenting parameters. It does not accept `Infinity` or `-Infinity`. @example ``` import type {Float} from 'type-fest'; declare function setPercentage<T extends number>(length: Float<T>): void; ``` @see {@link Integer} @category Numeric */ export type Float<T> = T extends unknown // To distributive type ? IsFloat<T> extends true ? T : never : never; // Never happens /** A negative (`-∞ < x < 0`) `number` that is not an integer. Equivalent to `Negative<Float<T>>`. Use-case: Validating and documenting parameters. @see {@link Negative} @see {@link Float} @category Numeric */ export type NegativeFloat<T extends number> = Negative<Float<T>>; /** A negative `number`/`bigint` (`-∞ < x < 0`). Use-case: Validating and documenting parameters. It does not accept `-Infinity`. Note: A wide `number` or `bigint` can't be proven negative, so it is rejected. To accept a value that is only known at runtime, accept a branded type next to `Negative<T>` in the parameter type, as shown for {@link Finite}. @see {@link NegativeInteger} @see {@link NonNegative} @example ``` import type {Negative, NegativeInfinity} from 'type-fest'; type A = Negative<-1>; //=> -1 type B = Negative<0>; //=> never type C = Negative<NegativeInfinity>; //=> never type D = Negative<number>; //=> never ``` @example ``` import type {Negative} from 'type-fest'; declare function setOffset<T extends number>(offset: Negative<T>): void; ``` @category Numeric */ export type Negative<T extends _Numeric> = T extends NegativeInfinity ? never : NegativeSign<T>; // Matches values with a negative sign, including `-Infinity`. // Read the sign from the unbranded primitive, because `${T}` does not reduce for a literal intersected with an object type, but keep the original brand on accepted values. type NegativeSign<T extends _Numeric> = T extends Zero ? never : `${T extends object ? UnwrapBrandedPrimitive<T> : T}` extends `-${string}` ? T : never; /** A negative (`-∞ < x < 0`) `number` that is an integer. Equivalent to `Negative<Integer<T>>`. You can't pass a `bigint` as they are already guaranteed to be integers, instead use `Negative<T>`. Use-case: Validating and documenting parameters. @see {@link Negative} @see {@link Integer} @category Numeric */ export type NegativeInteger<T extends number> = Negative<Integer<T>>; /** A non-negative `number`/`bigint` (`0 <= x < ∞`). Use-case: Validating and documenting parameters. It does not accept `Infinity`. Note: A wide `number` or `bigint` can't be proven non-negative, so it is rejected. To accept a value that is only known at runtime, accept a branded type next to `NonNegative<T>` in the parameter type, as shown for {@link Finite}. @see {@link NonNegativeInteger} @see {@link Negative} @example ``` import type {NonNegative} from 'type-fest'; type A = NonNegative<1>; //=> 1 type B = NonNegative<-1>; //=> never type C = NonNegative<number>; //=> never ``` @example ``` import type {NonNegative} from 'type-fest'; declare function setLength<T extends number>(length: NonNegative<T>): void; ``` @category Numeric */ export type NonNegative<T extends _Numeric> = T extends NegativeSign<T> | PositiveInfinity ? never : IsNumericLiteral<T> extends true ? T : never; /** A non-negative (`0 <= x < ∞`) `number` that is an integer. Equivalent to `NonNegative<Integer<T>>`. You can't pass a `bigint` as they are already guaranteed to be integers, instead use `NonNegative<T>`. Use-case: Validating and documenting parameters. @see {@link NonNegative} @see {@link Integer} @example ``` import type {NonNegativeInteger} from 'type-fest'; declare function setLength<T extends number>(length: NonNegativeInteger<T>): void; ``` @category Numeric */ export type NonNegativeInteger<T extends number> = NonNegative<Integer<T>>; /** Returns a boolean for whether the given number is a negative number. Checks union members separately; mixed results return `boolean`. Returns `boolean` for `any`, and `false` for `never` and the widened `number` and `bigint` types. Only numeric inputs are accepted. Unlike {@link Negative}, it returns `true` for `-Infinity`, since it only checks the sign. @see {@link Negative} @example ``` import type {IsNegative, NegativeInfinity} from 'type-fest'; type A = IsNegative<-1>; //=> true type B = IsNegative<1>; //=> false type C = IsNegative<NegativeInfinity>; //=> true ``` @category Numeric */ // `any` is checked before `never`, so generic code that wraps the result keeps resolving it after instantiation. export type IsNegative<T extends _Numeric> = IsAny<T> extends true ? boolean : IsNever<T> extends true ? false : T extends NegativeSign<T> ? true : false; export {};