type-fest 0.20.2 → 0.21.3

package/base.d.ts

@@ -3,6 +3,7 @@
 
 // Basic
 export * from './source/basic';
+export * from './source/typed-array';
 
 // Utilities
 export {Except} from './source/except';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "0.20.2",
+	"version": "0.21.3",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -14,8 +14,7 @@
 		"node": ">=10"
 	},
 	"scripts": {
-		"//test": "xo && tsd && tsc",
-		"test": "xo && tsc"
+		"test": "xo && tsd && tsc"
 	},
 	"files": [
 		"index.d.ts",
@@ -36,9 +35,10 @@
 	],
 	"devDependencies": {
 		"@sindresorhus/tsconfig": "~0.7.0",
-		"tsd": "^0.13.1",
-		"typescript": "^4.1.2",
-		"xo": "^0.35.0"
+		"expect-type": "^0.11.0",
+		"tsd": "^0.14.0",
+		"typescript": "^4.1.3",
+		"xo": "^0.36.1"
 	},
 	"types": "./index.d.ts",
 	"typesVersions": {

package/readme.md

@@ -6,15 +6,32 @@
 	<br>
 	<b>A collection of essential TypeScript types</b>
 	<br>
+	<br>
+	<br>
+	<br>
+	<div align="center">
+		<p>
+			<p>
+				<sup>
+					<a href="https://github.com/sponsors/sindresorhus">Sindre Sorhus' open source work is supported by the community</a>
+				</sup>
+			</p>
+			<sup>Special thanks to:</sup>
+			<br>
+			<br>
+			<a href="https://standardresume.co/tech">
+				<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="180"/>
+			</a>
+		</p>
+	</div>
+	<br>
 	<hr>
 </div>
 <br>
 <br>
 
 [![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://giphy.com/gifs/illustration-rainbow-unicorn-26AHG5KGFxSkUWw1i)
-<!-- Commented out until they actually show anything
 [![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents) [![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
--->
 
 Many of the types here should have been built-in. You can help by suggesting some of them to the [TypeScript project](https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md).
 
@@ -52,7 +69,7 @@ Click the type names for complete docs.
 
 - [`Primitive`](source/basic.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
 - [`Class`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
-- [`TypedArray`](source/basic.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
+- [`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`.
 - [`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.
@@ -61,7 +78,7 @@ Click the type names for complete docs.
 ### Utilities
 
 - [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type).
-- [`Mutable`](source/mutable.d.ts) - Convert an object with `readonly` keys into a mutable object. The inverse of `Readonly<T>`.
+- [`Mutable`](source/mutable.d.ts) - Create a type that strips `readonly` from all or some of an object's keys. The inverse of `Readonly<T>`.
 - [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
 - [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
 - [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
@@ -97,6 +114,7 @@ Click the type names for complete docs.
 - [`PascalCase`](ts41/pascal-case.d.ts) – Converts a string literal to pascal-case (`FooBar`)
 - [`SnakeCase`](ts41/snake-case.d.ts) – Convert a string literal to snake-case (`foo_bar`).
 - [`DelimiterCase`](ts41/delimiter-case.d.ts) – Convert a string literal to a custom string delimiter casing.
+- [`Get`](ts41/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.
 
 ### Miscellaneous
 
@@ -632,6 +650,90 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
+- [`Uppercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms every character in a string into uppercase.
+	<details>
+	<summary>
+		Example
+	</summary>
+
+	```ts
+	type T = Uppercase<'hello'>;  // 'HELLO'
+
+	type T2 = Uppercase<'foo' | 'bar'>;  // 'FOO' | 'BAR'
+
+	type T3<S extends string> = Uppercase<`aB${S}`>;
+	type T4 = T30<'xYz'>;  // 'ABXYZ'
+
+	type T5 = Uppercase<string>;  // string
+	type T6 = Uppercase<any>;  // any
+	type T7 = Uppercase<never>;  // never
+	type T8 = Uppercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
+	```
+	</details>
+
+- [`Lowercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms every character in a string into lowercase.
+	<details>
+	<summary>
+		Example
+	</summary>
+
+	```ts
+	type T = Lowercase<'HELLO'>;  // 'hello'
+
+	type T2 = Lowercase<'FOO' | 'BAR'>;  // 'foo' | 'bar'
+
+	type T3<S extends string> = Lowercase<`aB${S}`>;
+	type T4 = T32<'xYz'>;  // 'abxyz'
+
+	type T5 = Lowercase<string>;  // string
+	type T6 = Lowercase<any>;  // any
+	type T7 = Lowercase<never>;  // never
+	type T8 = Lowercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
+	```
+	</details>
+
+- [`Capitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms the first character in a string into uppercase.
+	<details>
+	<summary>
+		Example
+	</summary>
+
+	```ts
+	type T = Capitalize<'hello'>;  // 'Hello'
+
+	type T2 = Capitalize<'foo' | 'bar'>;  // 'Foo' | 'Bar'
+
+	type T3<S extends string> = Capitalize<`aB${S}`>;
+	type T4 = T32<'xYz'>;  // 'ABxYz'
+
+	type T5 = Capitalize<string>;  // string
+	type T6 = Capitalize<any>;  // any
+	type T7 = Capitalize<never>;  // never
+	type T8 = Capitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
+	```
+	</details>
+
+- [`Uncapitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms the first character in a string into lowercase.
+	<details>
+	<summary>
+		Example
+	</summary>
+
+	```ts
+	type T = Uncapitalize<'Hello'>;  // 'hello'
+
+	type T2 = Uncapitalize<'Foo' | 'Bar'>;  // 'foo' | 'bar'
+
+	type T3<S extends string> = Uncapitalize<`AB${S}`>;
+	type T4 = T30<'xYz'>;  // 'aBxYz'
+
+	type T5 = Uncapitalize<string>;  // string
+	type T6 = Uncapitalize<any>;  // any
+	type T7 = Uncapitalize<never>;  // never
+	type T8 = Uncapitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
+	```
+	</details>
+
 You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#predefined-conditional-types).
 
 ## Maintainers

package/source/basic.d.ts

@@ -1,4 +1,4 @@
-/// <reference lib="esnext"/>
+/// <reference lib="es2020.bigint"/>
 
 // TODO: This can just be `export type Primitive = not object` when the `not` keyword is out.
 /**
@@ -19,22 +19,6 @@ Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/Jav
 */
 export type Class<T = unknown, Arguments extends any[] = any[]> = new(...arguments_: Arguments) => T;
 
-/**
-Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
-*/
-export type TypedArray =
-	| Int8Array
-	| Uint8Array
-	| Uint8ClampedArray
-	| Int16Array
-	| Uint16Array
-	| Int32Array
-	| Uint32Array
-	| Float32Array
-	| Float64Array
-	| BigInt64Array
-	| BigUint64Array;
-
 /**
 Matches a JSON object.
 

package/source/entry.d.ts

@@ -44,7 +44,7 @@ const arrayEntryNumber: Entry<typeof arrayExample> = [1, 1];
 
 // Maps
 const mapExample = new Map([['a', 1]]);
-const mapEntry: Entry<typeof map> = ['a', 1];
+const mapEntry: Entry<typeof mapExample> = ['a', 1];
 
 // Sets
 const setExample = new Set(['a', 1]);

package/source/merge.d.ts

@@ -1,4 +1,7 @@
 import {Except} from './except';
+import {Simplify} from './simplify';
+
+type Merge_<FirstType, SecondType> = Except<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;
 
 /**
 Merge two types into a new type. Keys of the second type overrides keys of the first type.
@@ -19,4 +22,4 @@ type Bar = {
 const ab: Merge<Foo, Bar> = {a: 1, b: 2};
 ```
 */
-export type Merge<FirstType, SecondType> = Except<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;
+export type Merge<FirstType, SecondType> = Simplify<Merge_<FirstType, SecondType>>;

package/source/mutable.d.ts

@@ -1,7 +1,10 @@
+import {Except} from './except';
+import {Simplify} from './simplify';
+
 /**
-Convert an object with `readonly` keys into a mutable object. Inverse of `Readonly<T>`.
+Create a type that strips `readonly` from all or some of an object's keys. Inverse of `Readonly<T>`.
 
-This can be used to [store and mutate options within a class](https://github.com/sindresorhus/pageres/blob/4a5d05fca19a5fbd2f53842cbf3eb7b1b63bddd2/source/index.ts#L72), [edit `readonly` objects within tests](https://stackoverflow.com/questions/50703834), and [construct a `readonly` object within a function](https://github.com/Microsoft/TypeScript/issues/24509).
+This can be used to [store and mutate options within a class](https://github.com/sindresorhus/pageres/blob/4a5d05fca19a5fbd2f53842cbf3eb7b1b63bddd2/source/index.ts#L72), [edit `readonly` objects within tests](https://stackoverflow.com/questions/50703834), [construct a `readonly` object within a function](https://github.com/Microsoft/TypeScript/issues/24509), or to define a single model where the only thing that changes is whether or not some of the keys are mutable.
 
 @example
 ```
@@ -9,14 +12,27 @@ import {Mutable} from 'type-fest';
 
 type Foo = {
 	readonly a: number;
-	readonly b: string;
+	readonly b: readonly string[]; // To show that only the mutability status of the properties, not their values, are affected.
+	readonly c: boolean;
 };
 
-const mutableFoo: Mutable<Foo> = {a: 1, b: '2'};
+const mutableFoo: Mutable<Foo> = {a: 1, b: ['2']};
 mutableFoo.a = 3;
+mutableFoo.b[0] = 'new value'; // Will still fail as the value of property "b" is still a readonly type.
+mutableFoo.b = ['something']; // Will work as the "b" property itself is no longer readonly.
+
+type SomeMutable = Mutable<Foo, 'b' | 'c'>;
+// type SomeMutable = {
+// 	readonly a: number;
+// 	b: readonly string[]; // It's now mutable. The type of the property remains unaffected.
+// 	c: boolean; // It's now mutable.
+// }
 ```
 */
-export type Mutable<ObjectType> = {
-	// For each `Key` in the keys of `ObjectType`, make a mapped type by removing the `readonly` modifier from the key.
-	-readonly [KeyType in keyof ObjectType]: ObjectType[KeyType];
-};
+export type Mutable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
+	Simplify<
+		// Pick just the keys that are not mutable from the base type.
+		Except<BaseType, Keys> &
+        // Pick the keys that should be mutable from the base type and make them mutable by removing the `readonly` modifier from the key.
+        {-readonly [KeyType in keyof Pick<BaseType, Keys>]: Pick<BaseType, Keys>[KeyType]}
+	>;

package/source/set-optional.d.ts

@@ -1,4 +1,5 @@
 import {Except} from './except';
+import {Simplify} from './simplify';
 
 /**
 Create a type that makes the given keys optional. The remaining keys are kept as is. The sister of the `SetRequired` type.
@@ -23,12 +24,10 @@ type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
 // }
 ```
 */
-export type SetOptional<BaseType, Keys extends keyof BaseType = keyof BaseType> =
-	// Pick just the keys that are not optional from the base type.
-	Except<BaseType, Keys> &
-	// Pick the keys that should be optional from the base type and make them optional.
-	Partial<Pick<BaseType, Keys>> extends
-	// If `InferredType` extends the previous, then for each key, use the inferred type key.
-	infer InferredType
-		? {[KeyType in keyof InferredType]: InferredType[KeyType]}
-		: never;
+export type SetOptional<BaseType, Keys extends keyof BaseType> =
+	Simplify<
+		// Pick just the keys that are readonly from the base type.
+		Except<BaseType, Keys> &
+		// Pick the keys that should be mutable from the base type and make them mutable.
+		Partial<Pick<BaseType, Keys>>
+	>;

package/source/set-required.d.ts

@@ -1,4 +1,5 @@
 import {Except} from './except';
+import {Simplify} from './simplify';
 
 /**
 Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
@@ -23,12 +24,10 @@ type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
 // }
 ```
 */
-export type SetRequired<BaseType, Keys extends keyof BaseType = keyof BaseType> =
-	// Pick just the keys that are not required from the base type.
-	Except<BaseType, Keys> &
-	// Pick the keys that should be required from the base type and make them required.
-	Required<Pick<BaseType, Keys>> extends
-	// If `InferredType` extends the previous, then for each key, use the inferred type key.
-	infer InferredType
-		? {[KeyType in keyof InferredType]: InferredType[KeyType]}
-		: never;
+export type SetRequired<BaseType, Keys extends keyof BaseType> =
+	Simplify<
+		// Pick just the keys that are optional from the base type.
+		Except<BaseType, Keys> &
+		// Pick the keys that should be required from the base type and make them required.
+		Required<Pick<BaseType, Keys>>
+	>;

package/source/simplify.d.ts

@@ -0,0 +1,4 @@
+/**
+Flatten the type output to improve type hints shown in editors.
+*/
+export type Simplify<T> = {[KeyType in keyof T]: T[KeyType]};

package/source/typed-array.d.ts

@@ -0,0 +1,15 @@
+/**
+Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
+*/
+export type TypedArray =
+	| Int8Array
+	| Uint8Array
+	| Uint8ClampedArray
+	| Int16Array
+	| Uint16Array
+	| Int32Array
+	| Uint32Array
+	| Float32Array
+	| Float64Array
+	| BigInt64Array
+	| BigUint64Array;

package/source/utilities.d.ts

@@ -1,3 +1,5 @@
 export type UpperCaseCharacters = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
 
 export type WordSeparators = '-' | '_' | ' ';
+
+export type StringDigit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';

package/ts41/camel-case.d.ts

@@ -1,13 +1,5 @@
 import {WordSeparators} from '../source/utilities';
-
-/**
-Recursively split a string literal into two parts on the first occurence of the given string, returning an array literal of all the separate parts.
-*/
-export type Split<S extends string, D extends string> =
-	string extends S ? string[] :
-	S extends '' ? [] :
-	S extends `${infer T}${D}${infer U}` ? [T, ...Split<U, D>] :
-	[S];
+import {Split} from './utilities';
 
 /**
 Step by step takes the first item in an array literal, formats it and adds it to a string literal, and then recursively appends the remainder.

package/ts41/get.d.ts

@@ -0,0 +1,131 @@
+import {Split} from './utilities';
+import {StringDigit} from '../source/utilities';
+
+/**
+Like the `Get` type but receives an array of strings as a path parameter.
+*/
+type GetWithPath<BaseType, Keys extends readonly string[]> =
+	Keys extends []
+	? BaseType
+	: Keys extends [infer Head, ...infer Tail]
+	? GetWithPath<PropertyOf<BaseType, Extract<Head, string>>, Extract<Tail, string[]>>
+	: never;
+
+/**
+Splits a dot-prop style path into a tuple comprised of the properties in the path. Handles square-bracket notation.
+
+@example
+```
+ToPath<'foo.bar.baz'>
+//=> ['foo', 'bar', 'baz']
+
+ToPath<'foo[0].bar.baz'>
+//=> ['foo', '0', 'bar', 'baz']
+```
+*/
+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;
+
+/**
+Returns true if `LongString` is made up out of `Substring` repeated 0 or more times.
+
+@example
+```
+ConsistsOnlyOf<'aaa', 'a'> //=> true
+ConsistsOnlyOf<'ababab', 'ab'> //=> true
+ConsistsOnlyOf<'aBa', 'a'> //=> false
+ConsistsOnlyOf<'', 'a'> //=> true
+```
+*/
+type ConsistsOnlyOf<LongString extends string, Substring extends string> =
+	LongString extends ''
+	? true
+	: LongString extends `${Substring}${infer Tail}`
+	? ConsistsOnlyOf<Tail, Substring>
+  : false;
+
+/**
+Convert a type which may have number keys to one with string keys, making it possible to index using strings retrieved from template types.
+
+@example
+```
+type WithNumbers = {foo: string; 0: boolean};
+type WithStrings = WithStringKeys<WithNumbers>;
+
+type WithNumbersKeys = keyof WithNumbers;
+//=> 'foo' | 0
+type WithStringsKeys = keyof WithStrings;
+//=> 'foo' | '0'
+```
+*/
+type WithStringKeys<BaseType extends Record<string | number, any>> = {
+	[Key in `${Extract<keyof BaseType, string | number>}`]: BaseType[Key]
+};
+
+/**
+Get a property of an object or array. Works when indexing arrays using number-literal-strings, for example, `PropertyOf<number[], '0'> = number`, and when indexing objects with number keys.
+
+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> =
+	BaseType extends null | undefined
+	? undefined
+	: Key extends keyof BaseType
+	? BaseType[Key]
+	: BaseType extends {
+		[n: number]: infer Item;
+		length: number; // Note: This is needed to avoid being too lax with records types using number keys like `{0: string; 1: boolean}`.
+	}
+	? (
+		ConsistsOnlyOf<Key, StringDigit> extends true
+		? Item
+		: unknown
+	)
+	: Key extends keyof WithStringKeys<BaseType>
+	? WithStringKeys<BaseType>[Key]
+	: 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.
+/**
+Get a deeply-nested property from an object using a key path, like Lodash's `.get()` function.
+
+Use-case: Retrieve a property from deep inside an API response or some other complex object.
+
+@example
+```
+import {Get} from 'type-fest';
+import * as lodash from 'lodash';
+
+const get = <BaseType, Path extends string>(object: BaseType, path: Path): Get<BaseType, Path> =>
+	lodash.get(object, path);
+
+interface ApiResponse {
+	hits: {
+		hits: Array<{
+			_id: string
+			_source: {
+				name: Array<{
+					given: string[]
+					family: string
+				}>
+				birthDate: string
+			}
+		}>
+	}
+}
+
+const getName = (apiResponse: ApiResponse) =>
+	get(apiResponse, 'hits.hits[0]._source.name');
+	//=> Array<{given: string[]; family: string}>
+```
+*/
+export type Get<BaseType, Path extends string> = GetWithPath<BaseType, ToPath<Path>>;

package/ts41/index.d.ts

@@ -7,3 +7,4 @@ export {KebabCase} from './kebab-case';
 export {PascalCase} from './pascal-case';
 export {SnakeCase} from './snake-case';
 export {DelimiterCase} from './delimiter-case';
+export {Get} from './get';

package/ts41/utilities.d.ts

@@ -0,0 +1,8 @@
+/**
+Recursively split a string literal into two parts on the first occurence of the given string, returning an array literal of all the separate parts.
+*/
+export type Split<S extends string, D extends string> =
+	string extends S ? string[] :
+	S extends '' ? [] :
+	S extends `${infer T}${D}${infer U}` ? [T, ...Split<U, D>] :
+	[S];