Add numeric range types (#319)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: jonahsnider

index.d.ts

@@ -37,6 +37,16 @@ export {SetReturnType} from './source/set-return-type';
 export {Asyncify} from './source/asyncify';
 export {Simplify} from './source/simplify';
 export {Jsonify} from './source/jsonify';
+export {
+	PositiveInfinity,
+	NegativeInfinity,
+	Finite,
+	Integer,
+	Negative,
+	NonNegative,
+	NegativeInteger,
+	NonNegativeInteger,
+} from './source/numeric';
 
 // Template literal types
 export {CamelCase} from './source/camel-case';

readme.md

@@ -128,6 +128,14 @@ Click the type names for complete docs.
 - [`Includes`](source/includes.d.ts) - Returns a boolean for whether the given array includes the given item.
 - [`Simplify`](source/simplify.d.ts) - Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
 - [`Jsonify`](source/jsonify.d.ts) - Transform a type to one that is assignable to the `JsonValue` type.
+- [`PositiveInfinity`](source/numeric-range.d.ts) - Matches the hidden `Infinity` type.
+- [`NegativeInfinity`](source/numeric-range.d.ts) - Matches the hidden `-Infinity` type.
+- [`Finite`](source/numeric-range.d.ts) - A finite `number`.
+- [`Integer`](source/numeric-range.d.ts) - A `number` that is an integer.
+- [`Negative`](source/numeric-range.d.ts) - A negative `number`/`bigint` (`-∞ < x < 0`)
+- [`NonNegative`](source/numeric-range.d.ts) - A non-negative `number`/`bigint` (`0 <= x < ∞`).
+- [`NegativeInteger](source/numeric-range.d.ts) - A negative (`-∞ < x < 0`) `number` that is an integer.
+- [`NonNegativeInteger](source/numeric-range.d.ts) - A non-negative (`0 <= x < ∞`) `number` that is an integer.
 
 ### Template literal types
 

source/numeric.d.ts

@@ -0,0 +1,136 @@
+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 NegativeInfinity
+
+@category Basic
+*/
+// See https://github.com/microsoft/TypeScript/issues/31752
+// eslint-disable-next-line @typescript-eslint/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 PositiveInfinity
+
+@category Basic
+*/
+// See https://github.com/microsoft/TypeScript/issues/31752
+// eslint-disable-next-line @typescript-eslint/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.
+
+@example
+```
+import {Finite} from 'type-fest';
+
+declare function setScore<T extends number>(length: Finite<T>): void;
+```
+
+@category Utilities
+*/
+export type Finite<T extends number> = T extends PositiveInfinity | NegativeInfinity ? never : T;
+
+/**
+A `number` that is an integer.
+You can't pass a `bigint` as they are already guaranteed to be integers.
+
+Use-case: Validating and documenting parameters.
+
+@example
+```
+import {Integer} from 'type-fest';
+
+declare function setYear<T extends number>(length: Integer<T>): void;
+```
+
+@see NegativeInteger
+@see NonNegativeInteger
+
+@category Utilities
+*/
+// `${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 extends number> = `${T}` extends `${bigint}` ? T : never;
+
+/**
+A negative `number`/`bigint` (`-∞ < x < 0`)
+
+Use-case: Validating and documenting parameters.
+
+@see NegativeInteger
+@see NonNegative
+
+@category Utilities
+*/
+export type Negative<T extends Numeric> = T extends Zero ? never : `${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 Negative
+@see Integer
+
+@category Utilities
+*/
+export type NegativeInteger<T extends number> = Negative<Integer<T>>;
+
+/**
+A non-negative `number`/`bigint` (`0 <= x < ∞`).
+
+Use-case: Validating and documenting parameters.
+
+@see NonNegativeInteger
+@see Negative
+
+@example
+```
+import {NonNegative} from 'type-fest';
+
+declare function setLength<T extends number>(length: NonNegative<T>): void;
+```
+
+@category Utilities
+*/
+export type NonNegative<T extends Numeric> = T extends Zero ? T : Negative<T> extends never ? 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 NonNegative
+@see Integer
+
+@example
+```
+import {NonNegativeInteger} from 'type-fest';
+
+declare function setLength<T extends number>(length: NonNegativeInteger<T>): void;
+```
+
+@category Utilities
+*/
+export type NonNegativeInteger<T extends number> = NonNegative<Integer<T>>;

test-d/numeric.ts

@@ -0,0 +1,40 @@
+import {expectType} from 'tsd';
+import {Finite, Integer, Negative, NegativeInfinity, NegativeInteger, NonNegative, NonNegativeInteger, PositiveInfinity} from '../index';
+
+// Finite
+declare const infinity: Finite<PositiveInfinity | NegativeInfinity>;
+declare const infinityMixed: Finite<1 | PositiveInfinity | NegativeInfinity>;
+
+expectType<never>(infinity);
+expectType<1>(infinityMixed);
+
+// Integer
+declare const integer: Integer<1>;
+declare const integerMixed: Integer<1 | 1.5>;
+declare const nonInteger: Integer<1.5>;
+declare const infinityInteger: Integer<PositiveInfinity | NegativeInfinity>;
+
+expectType<1>(integer);
+expectType<never>(integerMixed); // This may be undesired behavior
+expectType<never>(nonInteger);
+expectType<never>(infinityInteger);
+
+// Negative
+declare const negative: Negative<-1 | -1n | 0 | 0n | 1 | 1n>;
+
+expectType<-1 | -1n>(negative);
+
+// NegativeInteger
+declare const negativeInteger: NegativeInteger<-1 | 0 | 1>;
+
+expectType<-1>(negativeInteger);
+
+// NonNegative
+declare const nonNegative: NonNegative<-1 | -1n | 0 | 0n | 1 | 1n>;
+
+expectType<0 | 0n | 1 | 1n>(nonNegative);
+
+// NonNegativeInteger
+declare const nonNegativeInteger: NonNegativeInteger<-1 | 0 | 1>;
+
+expectType<0 | 1>(nonNegativeInteger);