type-fest 2.5.4 → 2.9.0

package/index.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "2.5.4",
+	"version": "2.9.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",

package/readme.md

@@ -88,10 +88,6 @@ Click the type names for complete docs.
 - [`Class`](source/basic.d.ts) - Matches a [`class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 - [`Constructor`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 - [`TypedArray`](source/typed-array.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
-- [`JsonPrimitive`](source/basic.d.ts) - Matches a JSON primitive.
-- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
-- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
-- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
 - [`ObservableLike`](source/observable-like.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
 
 ### Utilities
@@ -106,31 +102,65 @@ Click the type names for complete docs.
 - [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) if you only need one level deep.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.
 - [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
-- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
 - [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
 - [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
 - [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
 - [`ValueOf`](source/value-of.d.ts) - Create a union of the given object's values, and optionally specify which keys to get the values from.
-- [`PromiseValue`](source/promise-value.d.ts) - Returns the type that is wrapped inside a `Promise`.
-- [`AsyncReturnType`](source/async-return-type.d.ts) - Unwrap the return type of a function that returns a `Promise`.
 - [`ConditionalKeys`](source/conditional-keys.d.ts) - Extract keys from a shape where values extend the given `Condition` type.
 - [`ConditionalPick`](source/conditional-pick.d.ts) - Like `Pick` except it selects properties from a shape where the values extend the given `Condition` type.
 - [`ConditionalExcept`](source/conditional-except.d.ts) - Like `Omit` except it removes properties from a shape where the values extend the given `Condition` type.
 - [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
+- [`LiteralToPrimitive`](source/literal-to-primitive.d.ts) - Convert a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) to the [primitive type](source/primitive.d.ts) it belongs to.
 - [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
-- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
-- [`MultidimensionalArray`](source/multidimensional-array.d.ts) - Create a type that represents a multidimensional array of the given type and dimensions.
-- [`MultidimensionalReadonlyArray`](source/multidimensional-readonly-array.d.ts) - Create a type that represents a multidimensional readonly array of the given type and dimensions.
 - [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
 - [`Entry`](source/entry.d.ts) - Create a type that represents the type of an entry of a collection.
 - [`Entries`](source/entries.d.ts) - Create a type that represents the type of the entries of a collection.
 - [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
-- [`Asyncify`](source/asyncify.d.ts) - Create an async version of the given function type.
-- [`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.
+- [`Get`](source/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.
+
+### JSON
+
 - [`Jsonify`](source/jsonify.d.ts) - Transform a type to one that is assignable to the `JsonValue` type.
+- [`JsonPrimitive`](source/basic.d.ts) - Matches a JSON primitive.
+- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
+- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
+- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
+
+### Async
+
+- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
+- [`AsyncReturnType`](source/async-return-type.d.ts) - Unwrap the return type of a function that returns a `Promise`.
+- [`Asyncify`](source/asyncify.d.ts) - Create an async version of the given function type.
+
+### String
+
+- [`Trim`](source/trim.d.ts) - Remove leading and trailing spaces from a string.
+- [`Split`](source/split.d.ts) - Represents an array of strings split using a given character or character set.
 
-### Template literal types
+### Array
+
+- [`Includes`](source/includes.d.ts) - Returns a boolean for whether the given array includes the given item.
+- [`Join`](source/join.d.ts) - Join an array of strings and/or numbers using the given string as a delimiter.
+- [`LastArrayElement`](source/last-array-element.d.ts) - Extracts the type of the last element of an array.
+- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
+- [`MultidimensionalArray`](source/multidimensional-array.d.ts) - Create a type that represents a multidimensional array of the given type and dimensions.
+- [`MultidimensionalReadonlyArray`](source/multidimensional-readonly-array.d.ts) - Create a type that represents a multidimensional readonly array of the given type and dimensions.
+
+### Numeric
+
+- [`PositiveInfinity`](source/numeric.d.ts) - Matches the hidden `Infinity` type.
+- [`NegativeInfinity`](source/numeric.d.ts) - Matches the hidden `-Infinity` type.
+- [`Finite`](source/numeric.d.ts) - A finite `number`.
+- [`Integer`](source/numeric.d.ts) - A `number` that is an integer.
+- [`Float`](source/numeric.d.ts) - A `number` that is not an integer.
+- [`NegativeFloat`](source/numeric.d.ts) - A negative (`-∞ < x < 0`) `number` that is not an integer.
+- [`Negative`](source/numeric.d.ts) - A negative `number`/`bigint` (`-∞ < x < 0`)
+- [`NonNegative`](source/numeric.d.ts) - A non-negative `number`/`bigint` (`0 <= x < ∞`).
+- [`NegativeInteger`](source/numeric.d.ts) - A negative (`-∞ < x < 0`) `number` that is an integer.
+- [`NonNegativeInteger`](source/numeric.d.ts) - A non-negative (`0 <= x < ∞`) `number` that is an integer.
+
+### Change case
 
 - [`CamelCase`](source/camel-case.d.ts) – Convert a string literal to camel-case (`fooBar`).
 - [`CamelCasedProperties`](source/camel-cased-properties.d.ts) – Convert object properties to camel-case (`fooBar`).
@@ -148,11 +178,6 @@ Click the type names for complete docs.
 - [`DelimiterCase`](source/delimiter-case.d.ts) – Convert a string literal to a custom string delimiter casing.
 - [`DelimiterCasedProperties`](source/delimiter-cased-properties.d.ts) – Convert object properties to a custom string delimiter casing.
 - [`DelimiterCasedPropertiesDeep`](source/delimiter-cased-properties-deep.d.ts) – Convert object properties to a custom string delimiter casing recursively.
-- [`Join`](source/join.d.ts) - Join an array of strings and/or numbers using the given string as a delimiter.
-- [`Split`](source/split.d.ts) - Represents an array of strings split using a given character or character set.
-- [`Trim`](source/trim.d.ts) - Remove leading and trailing spaces from a string.
-- [`Get`](source/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.
-- [`LastArrayElement`](source/last-array-element.d.ts) - Extracts the type of the last element of an array.
 
 ### Miscellaneous
 
@@ -167,6 +192,7 @@ Click the type names for complete docs.
 - [`Dictionary`](https://github.com/sindresorhus/type-fest/issues/33) - You only save a few characters (`Dictionary<number>` vs `Record<string, number>`) from [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type), which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have `Map` in JavaScript now.
 - [`ExtractProperties` and `ExtractMethods`](https://github.com/sindresorhus/type-fest/pull/4) - The types violate the single responsibility principle. Instead, refine your types into more granular type hierarchies.
 - [`Url2Json`](https://github.com/sindresorhus/type-fest/pull/262) - Inferring search parameters from a URL string is a cute idea, but not very useful in practice, since search parameters are usually dynamic and defined separately.
+- [`Nullish`](https://github.com/sindresorhus/type-fest/pull/318) - The type only saves a couple of characters, not everyone knows what “nullish” means, and I'm also trying to [get away from `null`](https://github.com/sindresorhus/meta/discussions/7).
 
 ## Alternative type names
 

package/source/async-return-type.d.ts

@@ -20,6 +20,6 @@ async function doSomething(value: Value) {}
 asyncFunction().then(value => doSomething(value));
 ```
 
-@category Utilities
+@category Async
 */
 export type AsyncReturnType<Target extends AsyncFunction> = PromiseValue<ReturnType<Target>>;

package/source/asyncify.d.ts

@@ -28,6 +28,6 @@ const getFooAsync: AsyncifiedFooGetter = (someArg) => {
 }
 ```
 
-@category Utilities
+@category Async
 */
 export type Asyncify<Fn extends (...args: any[]) => any> = SetReturnType<Fn, Promise<PromiseValue<ReturnType<Fn>>>>;

package/source/basic.d.ts

@@ -1,14 +1,14 @@
 /**
 Matches a [`class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 
-@category Basic
+@category Class
 */
 export type Class<T, Arguments extends unknown[] = any[]> = Constructor<T, Arguments> & {prototype: T};
 
 /**
 Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 
-@category Basic
+@category Class
 */
 export type Constructor<T, Arguments extends unknown[] = any[]> = new(...arguments_: Arguments) => T;
 
@@ -17,21 +17,21 @@ Matches a JSON object.
 
 This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
 
-@category Basic
+@category JSON
 */
 export type JsonObject = {[Key in string]?: JsonValue};
 
 /**
 Matches a JSON array.
 
-@category Basic
+@category JSON
 */
 export type JsonArray = JsonValue[];
 
 /**
 Matches any valid JSON primitive value.
 
-@category Basic
+@category JSON
 */
 export type JsonPrimitive = string | number | boolean | null;
 
@@ -40,6 +40,6 @@ Matches any valid JSON value.
 
 @see `Jsonify` if you need to transform a type to one that is assignable to `JsonValue`.
 
-@category Basic
+@category JSON
 */
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;

package/source/camel-case.d.ts

@@ -67,6 +67,7 @@ const dbResult: CamelCasedProperties<RawOptions> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type CamelCase<K> = K extends string ? CamelCaseStringArray<Split<K extends Uppercase<K> ? Lowercase<K> : K, WordSeparators>> : K;

package/source/camel-cased-properties-deep.d.ts

@@ -38,7 +38,9 @@ const result: CamelCasedPropertiesDeep<UserWithFriends> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type CamelCasedPropertiesDeep<Value> = Value extends Function
 	? Value

package/source/camel-cased-properties.d.ts

@@ -21,7 +21,9 @@ const result: CamelCasedProperties<User> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type CamelCasedProperties<Value> = Value extends Function
 	? Value

package/source/conditional-except.d.ts

@@ -37,7 +37,7 @@ type NonStringKeysOnly = ConditionalExcept<Example, string>;
 //=> {b: string | number; c: () => void; d: {}}
 ```
 
-@category Utilities
+@category Object
 */
 export type ConditionalExcept<Base, Condition> = Except<
 	Base,

package/source/conditional-keys.d.ts

@@ -26,7 +26,7 @@ type StringKeysAndUndefined = ConditionalKeys<Example, string | undefined>;
 //=> 'a' | 'c'
 ```
 
-@category Utilities
+@category Object
 */
 export type ConditionalKeys<Base, Condition> = NonNullable<
 	// Wrap in `NonNullable` to strip away the `undefined` type from the produced union.

package/source/conditional-pick.d.ts

@@ -36,7 +36,7 @@ type StringKeysOnly = ConditionalPick<Example, string>;
 //=> {a: string}
 ```
 
-@category Utilities
+@category Object
 */
 export type ConditionalPick<Base, Condition> = Pick<
 	Base,

package/source/delimiter-case.d.ts

@@ -3,7 +3,7 @@ import {UpperCaseCharacters, WordSeparators} from '../source/utilities';
 /**
 Unlike a simpler split, this one includes the delimiter splitted on in the resulting array literal. This is to enable splitting on, for example, upper-case characters.
 
-@category Template Literals
+@category Template literal
 */
 export type SplitIncludingDelimiters<Source extends string, Delimiter extends string> =
 	Source extends '' ? [] :
@@ -79,7 +79,8 @@ const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type DelimiterCase<Value, Delimiter extends string> = Value extends string
 	? StringArrayToDelimiterCase<

package/source/delimiter-cased-properties-deep.d.ts

@@ -38,7 +38,9 @@ const result: DelimiterCasedPropertiesDeep<UserWithFriends, '-'> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type DelimiterCasedPropertiesDeep<
 	Value,

package/source/delimiter-cased-properties.d.ts

@@ -21,7 +21,9 @@ const result: DelimiterCasedProperties<User, '-'> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type DelimiterCasedProperties<
 	Value,

package/source/entries.d.ts

@@ -49,7 +49,10 @@ const setExample = new Set(['a', 1]);
 const setEntries: Entries<typeof setExample> = [['a', 'a'], [1, 1]];
 ```
 
-@category Utilities
+@category Object
+@category Map
+@category Set
+@category Array
 */
 export type Entries<BaseType> =
 	BaseType extends Map<unknown, unknown> ? MapEntries<BaseType>

package/source/entry.d.ts

@@ -52,7 +52,10 @@ const setEntryString: Entry<typeof setExample> = ['a', 'a'];
 const setEntryNumber: Entry<typeof setExample> = [1, 1];
 ```
 
-@category Utilities
+@category Object
+@category Map
+@category Array
+@category Set
 */
 export type Entry<BaseType> =
 	BaseType extends Map<unknown, unknown> ? MapEntry<BaseType>

package/source/except.d.ts

@@ -50,7 +50,7 @@ type FooWithoutA = Except<Foo, 'a' | 'c'>;
 //=> {b: string};
 ```
 
-@category Utilities
+@category Object
 */
 export type Except<ObjectType, KeysType extends keyof ObjectType> = {
 	[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];

package/source/fixed-length-array.d.ts

@@ -28,7 +28,7 @@ guestFencingTeam.push('Sam');
 //=> error TS2339: Property 'push' does not exist on type 'FencingTeam'
 ```
 
-@category Utilities
+@category Array
 */
 export type FixedLengthArray<Element, Length extends number, ArrayPrototype = [Element, ...Element[]]> = Pick<
 	ArrayPrototype,

package/source/get.d.ts

@@ -1,16 +1,43 @@
 import {StringDigit} from '../source/utilities';
 import {Split} from './split';
 
+type GetOptions = {
+	strict?: boolean;
+};
+
 /**
 Like the `Get` type but receives an array of strings as a path parameter.
 */
-type GetWithPath<BaseType, Keys extends readonly string[]> =
+type GetWithPath<BaseType, Keys extends readonly string[], Options extends GetOptions = {}> =
 	Keys extends []
 	? BaseType
 	: Keys extends [infer Head, ...infer Tail]
-	? GetWithPath<PropertyOf<BaseType, Extract<Head, string>>, Extract<Tail, string[]>>
+	? GetWithPath<
+		PropertyOf<BaseType, Extract<Head, string>, Options>,
+		Extract<Tail, string[]>,
+		Options
+	>
 	: never;
 
+/**
+Adds `undefined` to `Type` if `strict` is enabled.
+*/
+type Strictify<Type, Options extends GetOptions> =
+	Options['strict'] extends true ? Type | undefined : Type;
+
+/**
+If `Options['strict']` is `true`, includes `undefined` in the returned type when accessing properties on `Record<string, any>`.
+
+Known limitations:
+- Does not include `undefined` in the type on object types with an index signature (for example, `{a: string; [key: string]: string}`).
+*/
+type StrictPropertyOf<BaseType, Key extends keyof BaseType, Options extends GetOptions> =
+	Record<string, any> extends BaseType
+	? string extends keyof BaseType
+		? Strictify<BaseType[Key], Options> // Record<string, any>
+		: BaseType[Key] // Record<'a' | 'b', any> (Records with a string union as keys have required properties)
+	: BaseType[Key];
+
 /**
 Splits a dot-prop style path into a tuple comprised of the properties in the path. Handles square-bracket notation.
 
@@ -29,8 +56,12 @@ type ToPath<S extends string> = Split<FixPathSquareBrackets<S>, '.'>;
 Replaces square-bracketed dot notation with dots, for example, `foo[0].bar` -> `foo.0.bar`.
 */
 type FixPathSquareBrackets<Path extends string> =
-	Path extends `${infer Head}[${infer Middle}]${infer Tail}`
-	? `${Head}.${Middle}${FixPathSquareBrackets<Tail>}`
+	Path extends `[${infer Head}]${infer Tail}`
+	? Tail extends `[${string}`
+		? `${Head}.${FixPathSquareBrackets<Tail>}`
+		: `${Head}${FixPathSquareBrackets<Tail>}`
+	: Path extends `${infer Head}[${infer Middle}]${infer Tail}`
+	? `${Head}.${FixPathSquareBrackets<`[${Middle}]${Tail}`>}`
 	: Path;
 
 /**
@@ -76,11 +107,11 @@ Note:
 - Returns `unknown` if `Key` is not a property of `BaseType`, since TypeScript uses structural typing, and it cannot be guaranteed that extra properties unknown to the type system will exist at runtime.
 - Returns `undefined` from nullish values, to match the behaviour of most deep-key libraries like `lodash`, `dot-prop`, etc.
 */
-type PropertyOf<BaseType, Key extends string> =
+type PropertyOf<BaseType, Key extends string, Options extends GetOptions = {}> =
 	BaseType extends null | undefined
 	? undefined
 	: Key extends keyof BaseType
-	? BaseType[Key]
+	? StrictPropertyOf<BaseType, Key, Options>
 	: BaseType extends [] | [unknown, ...unknown[]]
 	? unknown // It's a tuple, but `Key` did not extend `keyof BaseType`. So the index is out of bounds.
 	: BaseType extends {
@@ -89,11 +120,11 @@ type PropertyOf<BaseType, Key extends string> =
 	}
 	? (
 		ConsistsOnlyOf<Key, StringDigit> extends true
-		? Item
+		? Strictify<Item, Options>
 		: unknown
 	)
 	: Key extends keyof WithStringKeys<BaseType>
-	? WithStringKeys<BaseType>[Key]
+	? StrictPropertyOf<WithStringKeys<BaseType>, Key, Options>
 	: unknown;
 
 // This works by first splitting the path based on `.` and `[...]` characters into a tuple of string keys. Then it recursively uses the head key to get the next property of the current object, until there are no keys left. Number keys extract the item type from arrays, or are converted to strings to extract types from tuples and dictionaries with number keys.
@@ -128,8 +159,15 @@ interface ApiResponse {
 const getName = (apiResponse: ApiResponse) =>
 	get(apiResponse, 'hits.hits[0]._source.name');
 	//=> Array<{given: string[]; family: string}>
+
+// Strict mode:
+Get<string[], '3', {strict: true}> //=> string | undefined
+Get<Record<string, string>, 'foo', {strict: true}> // => string | undefined
 ```
 
-@category Template Literals
+@category Object
+@category Array
+@category Template literal
 */
-export type Get<BaseType, Path extends string> = GetWithPath<BaseType, ToPath<Path>>;
+export type Get<BaseType, Path extends string, Options extends GetOptions = {}> =
+	GetWithPath<BaseType, ToPath<Path>, Options>;

package/source/includes.d.ts

@@ -12,7 +12,7 @@ import {Includes} from 'type-fest';
 type hasRed<array extends any[]> = Includes<array, 'red'>;
 ```
 
-@category Utilities
+@category Array
 */
 export type Includes<Value extends readonly any[], Item> =
 	IsEqual<Value[0], Item> extends true

package/source/iterable-element.d.ts

@@ -38,7 +38,7 @@ An example with an array of strings:
 type MeString = IterableElement<string[]>
 ```
 
-@category Utilities
+@category Iterable
 */
 export type IterableElement<TargetIterable> =
 	TargetIterable extends Iterable<infer ElementType> ?

package/source/join.d.ts

@@ -17,7 +17,8 @@ const path: Join<['foo', 'bar', 'baz'], '.'> = ['foo', 'bar', 'baz'].join('.');
 const path: Join<[1, 2, 3], '.'> = [1, 2, 3].join('.');
 ```
 
-@category Template Literals
+@category Array
+@category Template literal
 */
 export type Join<
 	Strings extends Array<string | number>,

package/source/jsonify.d.ts

@@ -54,7 +54,7 @@ const timeJson = JSON.parse(JSON.stringify(time)) as Jsonify<typeof time>;
 
 @link https://github.com/Microsoft/TypeScript/issues/1897#issuecomment-710744173
 
-@category Utilities
+@category JSON
 */
 type Jsonify<T> =
 	// Check if there are any non-JSONable types represented in the union.
@@ -70,6 +70,6 @@ type Jsonify<T> =
 						? (() => J) extends (() => JsonValue) // Is J assignable to JsonValue?
 							? J // Then T is Jsonable and its Jsonable value is J
 							: never // Not Jsonable because its toJSON() method does not return JsonValue
-						: {[P in keyof T]: Jsonify<T[P]>} // It's an object: recursive call for its children
+						: {[P in keyof T]: Jsonify<Required<T>[P]>} // It's an object: recursive call for its children
 					: never // Otherwise any other non-object is removed
 		: never; // Otherwise non-JSONable type union was found not empty

package/source/kebab-case.d.ts

@@ -32,6 +32,7 @@ const rawCliOptions: KebabCasedProperties<CliOptions> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type KebabCase<Value> = DelimiterCase<Value, '-'>;

package/source/kebab-cased-properties-deep.d.ts

@@ -38,6 +38,8 @@ const result: KebabCasedPropertiesDeep<UserWithFriends> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type KebabCasedPropertiesDeep<Value> = DelimiterCasedPropertiesDeep<Value, '-'>;

package/source/kebab-cased-properties.d.ts

@@ -21,6 +21,8 @@ const result: KebabCasedProperties<User> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type KebabCasedProperties<Value> = DelimiterCasedProperties<Value, '-'>;

package/source/last-array-element.d.ts

@@ -15,7 +15,8 @@ typeof lastOf(array);
 //=> number
 ```
 
-@category Template Literals
+@category Array
+@category Template literal
 */
 export type LastArrayElement<ValueType extends readonly unknown[]> =
 	ValueType extends readonly [infer ElementType]

package/source/literal-to-primitive.d.ts

@@ -0,0 +1,36 @@
+/**
+Given a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) return the {@link Primitive | primitive type} it belongs to, or `never` if it's not a primitive.
+
+Use-case: Working with generic types that may be literal types.
+
+@example
+```
+import {LiteralToPrimitive} from 'type-fest';
+
+// No overloads needed to get the correct return type
+function plus<T extends number | bigint | string>(x: T, y: T): LiteralToPrimitive<T> {
+	return x + (y as any);
+}
+
+plus('a', 'b'); // string
+plus(1, 2); // number
+plus(1n, 2n); // bigint
+```
+
+@category Type
+*/
+export type LiteralToPrimitive<T> = T extends number
+	? number
+	: T extends bigint
+	? bigint
+	: T extends string
+	? string
+	: T extends boolean
+	? boolean
+	: T extends symbol
+	? symbol
+	: T extends null
+	? null
+	: T extends undefined
+	? undefined
+	: never;

package/source/literal-union.d.ts

@@ -27,7 +27,7 @@ const pet: Pet2 = '';
 // You **will** get auto-completion for `dog` and `cat` literals.
 ```
 
-@category Utilities
+@category Type
  */
 export type LiteralUnion<
 	LiteralType,

package/source/merge-exclusive.d.ts

@@ -32,7 +32,7 @@ exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
 //=> Error
 ```
 
-@category Utilities
+@category Object
 */
 export type MergeExclusive<FirstType, SecondType> =
 	(FirstType | SecondType) extends object ?

package/source/merge.d.ts

@@ -22,6 +22,6 @@ type Bar = {
 const ab: Merge<Foo, Bar> = {a: 1, b: 2};
 ```
 
-@category Utilities
+@category Object
 */
 export type Merge<FirstType, SecondType> = Simplify<Merge_<FirstType, SecondType>>;

package/source/multidimensional-array.d.ts

@@ -34,7 +34,7 @@ const matrix = emptyMatrix(3);
 matrix[0][0][0] = 42;
 ```
 
-@category Utilities
+@category Array
 */
 export type MultidimensionalArray<Element, Dimensions extends number> = number extends Dimensions
 	? Recursive<Element>

package/source/multidimensional-readonly-array.d.ts

@@ -38,7 +38,7 @@ const matrix = emptyMatrix(3);
 const answer = matrix[0][0][0]; // 42
 ```
 
-@category Utilities
+@category Array
 */
 export type MultidimensionalReadonlyArray<Element, Dimensions extends number> = number extends Dimensions
 	? Recursive<Element>

package/source/mutable.d.ts

@@ -29,7 +29,7 @@ type SomeMutable = Mutable<Foo, 'b' | 'c'>;
 // }
 ```
 
-@category Utilities
+@category Object
 */
 export type Mutable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
 	Simplify<

package/source/numeric.d.ts

@@ -0,0 +1,168 @@
+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 Numeric
+*/
+// 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 Numeric
+*/
+// 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 Numeric
+*/
+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 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 extends number> = `${T}` extends `${bigint}` ? T : never;
+
+/**
+A `number` that is not an integer.
+You can't pass a `bigint` as they are already guaranteed to be integers.
+
+Use-case: Validating and documenting parameters.
+
+@example
+```
+import {Float} from 'type-fest';
+
+declare function setPercentage<T extends number>(length: Float<T>): void;
+```
+
+@see Integer
+
+@category Numeric
+*/
+export type Float<T extends number> = T extends Integer<T> ? never : T;
+
+/**
+A negative (`-∞ < x < 0`) `number` that is not an integer.
+Equivalent to `Negative<Float<T>>`.
+
+Use-case: Validating and documenting parameters.
+
+@see Negative
+@see Float
+
+@category Numeric
+*/
+export type NegativeFloat<T extends number> = Negative<Float<T>>;
+
+/**
+A negative `number`/`bigint` (`-∞ < x < 0`)
+
+Use-case: Validating and documenting parameters.
+
+@see NegativeInteger
+@see NonNegative
+
+@category Numeric
+*/
+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 Numeric
+*/
+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 Numeric
+*/
+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 Numeric
+*/
+export type NonNegativeInteger<T extends number> = NonNegative<Integer<T>>;

package/source/observable-like.d.ts

@@ -11,15 +11,29 @@ As well, some guideance on making an `Observable` do not include `closed` proper
 @see https://github.com/tc39/proposal-observable/blob/master/src/Observable.js#L129-L130
 @see https://github.com/staltz/xstream/blob/6c22580c1d84d69773ee4b0905df44ad464955b3/src/index.ts#L79-L85
 @see https://github.com/benlesh/symbol-observable#making-an-object-observable
+
+@category Observable
 */
 export type Unsubscribable = {
 	unsubscribe(): void;
 };
 
+/**
+@category Observable
+*/
 type OnNext<ValueType> = (value: ValueType) => void;
+/**
+@category Observable
+*/
 type OnError = (error: unknown) => void;
+/**
+@category Observable
+*/
 type OnComplete = () => void;
 
+/**
+@category Observable
+*/
 export type Observer<ValueType> = {
 	next: OnNext<ValueType>;
 	error: OnError;
@@ -40,7 +54,7 @@ But `Observable` implementations have evolved to preferring case 2 and some impl
 @see https://github.com/tc39/proposal-observable/blob/master/src/Observable.js#L246-L259
 @see https://benlesh.com/posts/learning-observable-by-building-observable/
 
-@category Basic
+@category Observable
 */
 export interface ObservableLike<ValueType = unknown> {
 	subscribe(observer?: Partial<Observer<ValueType>>): Unsubscribable;

package/source/opaque.d.ts

@@ -69,6 +69,6 @@ type Person = {
 };
 ```
 
-@category Utilities
+@category Type
 */
 export type Opaque<Type, Token = unknown> = Type & Tagged<Token>;

package/source/package-json.d.ts

@@ -635,7 +635,7 @@ declare namespace PackageJson {
 /**
 Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
 
-@category Miscellaneous
+@category File
 */
 export type PackageJson =
 PackageJson.PackageJsonStandard &

package/source/partial-deep.d.ts

@@ -28,7 +28,10 @@ const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
 settings = applySavedSettings({textEditor: {fontWeight: 500}});
 ```
 
-@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
 */
 export type PartialDeep<T> = T extends Primitive
 	? Partial<T>

package/source/pascal-case.d.ts

@@ -30,7 +30,8 @@ const dbResult: CamelCasedProperties<ModelProps> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type PascalCase<Value> = CamelCase<Value> extends string
 	? Capitalize<CamelCase<Value>>

package/source/pascal-cased-properties-deep.d.ts

@@ -38,7 +38,9 @@ const result: PascalCasedPropertiesDeep<UserWithFriends> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type PascalCasedPropertiesDeep<Value> = Value extends Function
 	? Value

package/source/pascal-cased-properties.d.ts

@@ -21,7 +21,9 @@ const result: PascalCasedProperties<User> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type PascalCasedProperties<Value> = Value extends Function
 	? Value

package/source/primitive.d.ts

@@ -1,7 +1,7 @@
 /**
 Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
 
-@category Basic
+@category Type
 */
 export type Primitive =
 	| null

package/source/promisable.d.ts

@@ -18,8 +18,8 @@ async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
 
 logger(() => 'foo');
 logger(() => Promise.resolve('bar'));
-
-@category Utilities
 ```
+
+@category Async
 */
 export type Promisable<T> = T | PromiseLike<T>;

package/source/promise-value.d.ts

@@ -1,4 +1,6 @@
 /**
+@deprecated Use the built-in [`Awaited` type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#the-awaited-type-and-promise-improvements) instead.
+
 Returns the type that is wrapped inside a `Promise` type.
 If the type is a nested Promise, it is unwrapped recursively until a non-Promise type is obtained.
 If the type is not a `Promise`, the type itself is returned.
@@ -22,6 +24,6 @@ type RecursiveAsyncData = Promise<Promise<string> >;
 let recursiveAsyncData: PromiseValue<RecursiveAsyncData> = Promise.resolve(Promise.resolve('ABC'));
 ```
 
-@category Utilities
+@category Async
 */
 export type PromiseValue<PromiseType> = PromiseType extends PromiseLike<infer Value> ? PromiseValue<Value> : PromiseType;

package/source/readonly-deep.d.ts

@@ -29,7 +29,10 @@ data.foo.push('bar');
 //=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
 ```
 
-@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
 */
 export type ReadonlyDeep<T> = T extends Primitive | ((...arguments: any[]) => unknown)
 	? T

package/source/require-all-or-none.d.ts

@@ -27,7 +27,7 @@ const responder2: RequireAllOrNone<Responder, 'text' | 'json'> = {
 };
 ```
 
-@category Utilities
+@category Object
 */
 export type RequireAllOrNone<ObjectType, KeysType extends keyof ObjectType = never> = (
 	| Required<Pick<ObjectType, KeysType>> // Require all of the given keys.

package/source/require-at-least-one.d.ts

@@ -20,7 +20,7 @@ const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
 };
 ```
 
-@category Utilities
+@category Object
 */
 export type RequireAtLeastOne<
 	ObjectType,

package/source/require-exactly-one.d.ts

@@ -25,7 +25,7 @@ const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
 };
 ```
 
-@category Utilities
+@category Object
 */
 export type RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
 	{[Key in KeysType]: (

package/source/screaming-snake-case.d.ts

@@ -23,7 +23,8 @@ import {ScreamingSnakeCase} from 'type-fest';
 const someVariable: ScreamingSnakeCase<'fooBar'> = 'FOO_BAR';
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type ScreamingSnakeCase<Value> = Value extends string
 	? IsScreamingSnakeCase<Value> extends true

package/source/set-optional.d.ts

@@ -24,7 +24,7 @@ type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
 // }
 ```
 
-@category Utilities
+@category Object
 */
 export type SetOptional<BaseType, Keys extends keyof BaseType> =
 	Simplify<

package/source/set-required.d.ts

@@ -24,7 +24,7 @@ type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
 // }
 ```
 
-@category Utilities
+@category Object
 */
 export type SetRequired<BaseType, Keys extends keyof BaseType> =
 	Simplify<

package/source/set-return-type.d.ts

@@ -17,7 +17,7 @@ type MyWrappedFunction = SetReturnType<MyFunctionThatCanThrow, SomeOtherType | u
 //=> type MyWrappedFunction = (foo: SomeType, bar: unknown) => SomeOtherType | undefined;
 ```
 
-@category Utilities
+@category Function
 */
 export type SetReturnType<Fn extends (...args: any[]) => any, TypeToReturn> =
 	// Just using `Parameters<Fn>` isn't ideal because it doesn't handle the `this` fake parameter.

package/source/simplify.d.ts

@@ -53,6 +53,6 @@ fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface`
 
 @link https://github.com/microsoft/TypeScript/issues/15300
 
-@category Utilities
+@category Object
 */
 export type Simplify<T> = {[KeyType in keyof T]: T[KeyType]};

package/source/snake-case.d.ts

@@ -32,6 +32,7 @@ const dbResult: SnakeCasedProperties<ModelProps> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type SnakeCase<Value> = DelimiterCase<Value, '_'>;

package/source/snake-cased-properties-deep.d.ts

@@ -38,6 +38,8 @@ const result: SnakeCasedPropertiesDeep<UserWithFriends> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type SnakeCasedPropertiesDeep<Value> = DelimiterCasedPropertiesDeep<Value, '_'>;

package/source/snake-cased-properties.d.ts

@@ -21,6 +21,8 @@ const result: SnakeCasedProperties<User> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type SnakeCasedProperties<Value> = DelimiterCasedProperties<Value, '_'>;

package/source/split.d.ts

@@ -16,7 +16,8 @@ let array: Item[];
 array = split(items, ',');
 ```
 
-@category Template Literals
+@category String
+@category Template literal
 */
 export type Split<
 	S extends string,

package/source/stringified.d.ts

@@ -18,6 +18,6 @@ const carForm: Stringified<Car> = {
 };
 ```
 
-@category Utilities
+@category Object
 */
 export type Stringified<ObjectType> = {[KeyType in keyof ObjectType]: string};

package/source/trim.d.ts

@@ -19,6 +19,7 @@ Trim<' foo '>
 //=> 'foo'
 ```
 
-@category Template Literals
+@category String
+@category Template literal
 */
 export type Trim<V extends string> = TrimLeft<TrimRight<V>>;

package/source/tsconfig-json.d.ts

@@ -15,6 +15,7 @@ declare namespace TsConfigJson {
 			| 'ES6'
 			| 'ES2015'
 			| 'ES2020'
+			| 'ES2022'
 			| 'ESNext'
 			| 'None'
 			// Lowercase alternatives
@@ -25,6 +26,7 @@ declare namespace TsConfigJson {
 			| 'es6'
 			| 'es2015'
 			| 'es2020'
+			| 'es2022'
 			| 'esnext'
 			| 'none';
 
@@ -1038,7 +1040,7 @@ declare namespace TsConfigJson {
 /**
 Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 3.7).
 
-@category Miscellaneous
+@category File
 */
 export interface TsConfigJson {
 	/**

package/source/typed-array.d.ts

@@ -1,7 +1,7 @@
 /**
 Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
 
-@category Basic
+@category Array
 */
 export type TypedArray =
 	| Int8Array

package/source/union-to-intersection.d.ts

@@ -41,7 +41,7 @@ type Intersection = UnionToIntersection<Union>;
 //=> {a1(): void; b1(): void; a2(argA: string): void; b2(argB: string): void}
 ```
 
-@category Utilities
+@category Type
 */
 export type UnionToIntersection<Union> = (
 	// `extends unknown` is always going to be the case and is used to convert the

package/source/value-of.d.ts

@@ -37,6 +37,6 @@ onlyBar('bar');
 //=> 2
 ```
 
-@category Utilities
+@category Object
 */
 export type ValueOf<ObjectType, ValueType extends keyof ObjectType = keyof ObjectType> = ObjectType[ValueType];