type-fest 2.3.4 → 2.5.2

package/index.d.ts

@@ -28,6 +28,8 @@ export {ConditionalPick} from './source/conditional-pick';
 export {UnionToIntersection} from './source/union-to-intersection';
 export {Stringified} from './source/stringified';
 export {FixedLengthArray} from './source/fixed-length-array';
+export {MultidimensionalArray} from './source/multidimensional-array';
+export {MultidimensionalReadonlyArray} from './source/multidimensional-readonly-array';
 export {IterableElement} from './source/iterable-element';
 export {Entry} from './source/entry';
 export {Entries} from './source/entries';

package/package.json

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

package/readme.md

@@ -48,12 +48,14 @@
 [![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
 [![Docs](https://paka.dev/badges/v0/cute.svg)](https://paka.dev/npm/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).
+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/main/CONTRIBUTING.md).
 
 Either add this package as a dependency or copy-paste the needed types. No credit required. 👌
 
 PR welcome for additional commonly needed types and docs improvements. Read the [contributing guidelines](.github/contributing.md) first.
 
+**Help wanted with reviewing [proposals](https://github.com/sindresorhus/type-fest/issues) and [pull requests](https://github.com/sindresorhus/type-fest/pulls).**
+
 ## Install
 
 ```
@@ -94,15 +96,15 @@ 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).
+- [`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/utility-types.html#omittype-keys).
 - [`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.
 - [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
 - [`RequireAllOrNone`](source/require-all-or-none.d.ts) - Create a type that requires all of the given keys or none of the given keys.
-- [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) 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://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) if you only need one level deep.
+- [`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/).
@@ -117,20 +119,22 @@ Click the type names for complete docs.
 - [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
 - [`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) - Flatten the type output to improve type hints shown in editors.
+- [`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.
 
 ### Template literal types
 
 - [`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`).
-- [`CamelCasedPropertiesDeep`](source/camel-cased-properties-deep.d.ts) – Convert object properties to camel-case recursively  (`fooBar`).
+- [`CamelCasedProperties`](source/camel-cased-properties.d.ts) – Convert object properties to camel-case (`fooBar`).
+- [`CamelCasedPropertiesDeep`](source/camel-cased-properties-deep.d.ts) – Convert object properties to camel-case recursively (`fooBar`).
 - [`KebabCase`](source/kebab-case.d.ts) – Convert a string literal to kebab-case (`foo-bar`).
 - [`KebabCasedProperties`](source/kebab-cased-properties.d.ts) – Convert a object properties to kebab-case recursively (`foo-bar`).
 - [`KebabCasedPropertiesDeep`](source/kebab-cased-properties-deep.d.ts) – Convert object properties to kebab-case (`foo-bar`).
@@ -160,8 +164,9 @@ Click the type names for complete docs.
 *If we decline a type addition, we will make sure to document the better solution here.*
 
 - [`Diff` and `Spread`](https://github.com/sindresorhus/type-fest/pull/7) - The PR author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.
-- [`Dictionary`](https://github.com/sindresorhus/type-fest/issues/33) - You only save a few characters (`Dictionary<number>` vs `Record<string, number>`) from [`Record`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434), which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have `Map` in JavaScript now.
+- [`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.
 
 ## Tips
 
@@ -173,7 +178,7 @@ Click the type names for complete docs.
 
 There are many advanced types most users don't know about.
 
-- [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) - Make all properties in `T` optional.
+- [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) - Make all properties in `T` optional.
 	<details>
 	<summary>
 			Example
@@ -220,7 +225,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Required<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1408-L1413) - Make all properties in `T` required.
+- [`Required<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredtype) - Make all properties in `T` required.
 	<details>
 	<summary>
 			Example
@@ -250,7 +255,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) - Make all properties in `T` readonly.
+- [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) - Make all properties in `T` readonly.
 	<details>
 	<summary>
 			Example
@@ -295,7 +300,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Pick<T, K>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1422-L1427) - From `T`, pick a set of properties whose keys are in the union `K`.
+- [`Pick<T, K>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys) - From `T`, pick a set of properties whose keys are in the union `K`.
 	<details>
 	<summary>
 			Example
@@ -335,7 +340,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Record<K, T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434) - Construct a type with a set of properties `K` of type `T`.
+- [`Record<K, T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) - Construct a type with a set of properties `K` of type `T`.
 	<details>
 	<summary>
 			Example
@@ -378,7 +383,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Exclude<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1436-L1439) - Exclude from `T` those types that are assignable to `U`.
+- [`Exclude<T, U>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#excludetype-excludedunion) - Exclude from `T` those types that are assignable to `U`.
 	<details>
 	<summary>
 			Example
@@ -412,7 +417,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Extract<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1441-L1444) - Extract from `T` those types that are assignable to `U`.
+- [`Extract<T, U>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union) - Extract from `T` those types that are assignable to `U`.
 	<details>
 	<summary>
 			Example
@@ -455,12 +460,12 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`NonNullable<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1446-L1449) - Exclude `null` and `undefined` from `T`.
+- [`NonNullable<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#nonnullabletype) - Exclude `null` and `undefined` from `T`.
 	<details>
 	<summary>
 			Example
 	</summary>
-	Works with <code>strictNullChecks</code> set to <code>true</code>. (Read more <a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html">here</a>)
+	Works with <a href="https://www.typescriptlang.org/tsconfig#strictNullChecks"><code>strictNullChecks</code></a> set to <code>true</code>.
 
 	[Playground](https://typescript-play.js.org/?target=6#code/C4TwDgpgBACg9gJ2AOQK4FsBGEFQLxQDOwCAlgHYDmUAPlORtrnQwDasDcAUFwPQBU-WAEMkUOADMowqAGNWwwoSgATCBIqlgpOOSjAAFsOBRSy1IQgr9cKJlSlW1mZYQA3HFH68u8xcoBlHA8EACEHJ08Aby4oKDBUTFZSWXjEFEYcAEIALihkXTR2YSSIAB54JDQsHAA+blj4xOTUsHSACkMzPKD3HHDHNQQAGjSkPMqMmoQASh7g-oihqBi4uNIpdraxPAI2VhmVxrX9AzMAOm2ppnwoAA4ABifuE4BfKAhWSyOTuK7CS7pao3AhXF5rV48E4ICDAVAIPT-cGQyG+XTEIgLMJLTx7CAAdygvRCA0iCHaMwarhJOIQjUBSHaACJHk8mYdeLwxtdcVAAOSsh58+lXdr7Dlcq7A3n3J4PEUdADMcspUE53OluAIUGVTx46oAKuAIAFZGQwCYAKIIBCILjUxaDHAMnla+iodjcIA)
 
@@ -494,7 +499,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Parameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1451-L1454) - Obtain the parameters of a function type in a tuple.
+- [`Parameters<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#parameterstype) - Obtain the parameters of a function type in a tuple.
 	<details>
 	<summary>
 			Example
@@ -522,7 +527,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`ConstructorParameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1456-L1459) - Obtain the parameters of a constructor function type in a tuple.
+- [`ConstructorParameters<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#constructorparameterstype) - Obtain the parameters of a constructor function type in a tuple.
 	<details>
 	<summary>
 			Example
@@ -570,7 +575,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`ReturnType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1461-L1464) – Obtain the return type of a function type.
+- [`ReturnType<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#returntypetype) – Obtain the return type of a function type.
 	<details>
 	<summary>
 			Example
@@ -605,7 +610,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`InstanceType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1466-L1469) – Obtain the instance type of a constructor function type.
+- [`InstanceType<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#instancetypetype) – Obtain the instance type of a constructor function type.
 	<details>
 	<summary>
 			Example
@@ -658,7 +663,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-- [`Omit<T, K>`](https://github.com/microsoft/TypeScript/blob/71af02f7459dc812e85ac31365bfe23daf14b4e4/src/lib/es5.d.ts#L1446) – Constructs a type by picking all properties from T and then removing K.
+- [`Omit<T, K>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) – Constructs a type by picking all properties from T and then removing K.
 	<details>
 	<summary>
 			Example
@@ -680,14 +685,14 @@ There are many advanced types most users don't know about.
 	type AnimalShortInfo = Omit<Animal, 'images' | 'paragraphs'>;
 
 	function renderAnimalHoverInfo (animals: AnimalShortInfo[]): HTMLElement {
-			const container =  document.createElement('div');
+			const container = document.createElement('div');
 			// Internal implementation.
 			return container;
 	}
 	```
 	</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.
+- [`Uppercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#uppercasestringtype) - Transforms every character in a string into uppercase.
 	<details>
 	<summary>
 		Example
@@ -708,7 +713,7 @@ There are many advanced types most users don't know about.
 	```
 	</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.
+- [`Lowercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#lowercasestringtype) - Transforms every character in a string into lowercase.
 	<details>
 	<summary>
 		Example
@@ -729,7 +734,7 @@ There are many advanced types most users don't know about.
 	```
 	</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.
+- [`Capitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#capitalizestringtype) - Transforms the first character in a string into uppercase.
 	<details>
 	<summary>
 		Example
@@ -750,7 +755,7 @@ There are many advanced types most users don't know about.
 	```
 	</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.
+- [`Uncapitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#uncapitalizestringtype) - Transforms the first character in a string into lowercase.
 	<details>
 	<summary>
 		Example
@@ -771,7 +776,7 @@ There are many advanced types most users don't know about.
 	```
 	</details>
 
-You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#predefined-conditional-types).
+You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/utility-types.html).
 
 ## Maintainers
 

package/source/delimiter-case.d.ts

@@ -24,8 +24,9 @@ Format a specific part of the splitted string literal that `StringArrayToDelimit
 
 @see StringArrayToDelimiterCase
 */
-type StringPartToDelimiterCase<StringPart extends string, UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
+type StringPartToDelimiterCase<StringPart extends string, Start extends boolean, UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
 	StringPart extends UsedWordSeparators ? Delimiter :
+	Start extends true ? Lowercase<StringPart> :
 	StringPart extends UsedUpperCaseCharacters ? `${Delimiter}${Lowercase<StringPart>}` :
 	StringPart;
 
@@ -36,9 +37,9 @@ It receives `UsedWordSeparators` and `UsedUpperCaseCharacters` as input to ensur
 
 @see SplitIncludingDelimiters
 */
-type StringArrayToDelimiterCase<Parts extends readonly any[], UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
+type StringArrayToDelimiterCase<Parts extends readonly any[], Start extends boolean, UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
 	Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
-		? `${StringPartToDelimiterCase<FirstPart, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}${StringArrayToDelimiterCase<RemainingParts, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}`
+		? `${StringPartToDelimiterCase<FirstPart, Start, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}${StringArrayToDelimiterCase<RemainingParts, false, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}`
 		: '';
 
 /**
@@ -81,6 +82,7 @@ const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
 export type DelimiterCase<Value, Delimiter extends string> = Value extends string
 	? StringArrayToDelimiterCase<
 		SplitIncludingDelimiters<Value, WordSeparators | UpperCaseCharacters>,
+		true,
 		WordSeparators,
 		UpperCaseCharacters,
 		Delimiter

package/source/get.d.ts

@@ -49,7 +49,7 @@ type ConsistsOnlyOf<LongString extends string, Substring extends string> =
 	? true
 	: LongString extends `${Substring}${infer Tail}`
 	? ConsistsOnlyOf<Tail, Substring>
-  : false;
+	: 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.

package/source/internal.d.ts

@@ -9,3 +9,29 @@ export type IsEqual<T, U> =
 	(<G>() => G extends U ? 1 : 2)
 		? true
 		: false;
+
+/**
+Infer the length of the given array `<T>`.
+
+@link https://itnext.io/implementing-arithmetic-within-typescripts-type-system-a1ef140a6f6f
+*/
+type TupleLength<T extends readonly unknown[]> = T extends {readonly length: infer L} ? L : never;
+
+/**
+Create a tuple type of the given length `<L>`.
+
+@link https://itnext.io/implementing-arithmetic-within-typescripts-type-system-a1ef140a6f6f
+*/
+type BuildTuple<L extends number, T extends readonly unknown[] = []> = T extends {readonly length: L}
+	? T
+	: BuildTuple<L, [...T, unknown]>;
+
+/**
+Create a tuple of length `A` and a tuple composed of two other tuples,
+the inferred tuple `U` and a tuple of length `B`, then extracts the length of tuple `U`.
+
+@link https://itnext.io/implementing-arithmetic-within-typescripts-type-system-a1ef140a6f6f
+*/
+export type Subtract<A extends number, B extends number> = BuildTuple<A> extends [...(infer U), ...BuildTuple<B>]
+	? TupleLength<U>
+	: never;

package/source/multidimensional-array.d.ts

@@ -0,0 +1,43 @@
+import {IsEqual, Subtract} from './internal';
+
+type Recursive<T> = Array<Recursive<T>>;
+
+/**
+Creates a type that represents a multidimensional array of the given type and dimension.
+
+Use-cases:
+- Return a n-dimensional array from functions.
+- Declare a n-dimensional array by defining its dimensions rather than declaring `[]` repetitively.
+- Infer the dimensions of a n-dimensional array automatically from function arguments.
+- Avoid the need to know in advance the dimensions of a n-dimensional array allowing them to be dynamic.
+
+@example
+```
+import {MultidimensionalArray} from 'type-fest';
+
+function emptyMatrix<T extends number>(dimensions: T): MultidimensionalArray<unknown, T> {
+	const matrix: unknown[] = [];
+
+	let subMatrix = matrix;
+	for (let dimension = 1; dimension < dimensions; ++dimension) {
+		console.log(`Initializing dimension #${dimension}`);
+
+		subMatrix[0] = [];
+		subMatrix = subMatrix[0] as unknown[];
+	}
+
+	return matrix as MultidimensionalArray<unknown, T>;
+}
+
+const matrix = emptyMatrix(3);
+
+matrix[0][0][0] = 42;
+```
+
+@category Utilities
+*/
+export type MultidimensionalArray<Element, Dimensions extends number> = number extends Dimensions
+	? Recursive<Element>
+	: IsEqual<Dimensions, 0> extends true
+		? Element
+		: Array<MultidimensionalArray<Element, Subtract<Dimensions, 1>>>;

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

@@ -0,0 +1,47 @@
+import {IsEqual, Subtract} from './internal';
+
+type Recursive<T> = ReadonlyArray<Recursive<T>>;
+
+/**
+Creates a type that represents a multidimensional readonly array that of the given type and dimension.
+
+Use-cases:
+- Return a n-dimensional array from functions.
+- Declare a n-dimensional array by defining its dimensions rather than declaring `[]` repetitively.
+- Infer the dimensions of a n-dimensional array automatically from function arguments.
+- Avoid the need to know in advance the dimensions of a n-dimensional array allowing them to be dynamic.
+
+@example
+```
+import {MultidimensionalReadonlyArray} from 'type-fest';
+
+function emptyMatrix<T extends number>(dimensions: T): MultidimensionalReadonlyArray<unknown, T> {
+	const matrix: unknown[] = [];
+
+	let subMatrix = matrix;
+	for (let dimension = 1; dimension < dimensions; ++dimension) {
+		console.log(`Initializing dimension #${dimension}`);
+
+		subMatrix[0] = [];
+		if (dimension < dimensions - 1) {
+			subMatrix = subMatrix[0] as unknown[];
+		} else {
+			subMatrix[0] = 42;
+		}
+	}
+
+	return matrix as MultidimensionalReadonlyArray<unknown, T>;
+}
+
+const matrix = emptyMatrix(3);
+
+const answer = matrix[0][0][0]; // 42
+```
+
+@category Utilities
+*/
+export type MultidimensionalReadonlyArray<Element, Dimensions extends number> = number extends Dimensions
+	? Recursive<Element>
+	: IsEqual<Dimensions, 0> extends true
+		? Element
+		: ReadonlyArray<MultidimensionalReadonlyArray<Element, Subtract<Dimensions, 1>>>;

package/source/mutable.d.ts

@@ -35,6 +35,6 @@ 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]}
+		// 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/observable-like.d.ts

@@ -4,12 +4,45 @@ declare global {
 	}
 }
 
+/**
+@remarks
+The TC39 observable proposal defines a `closed` property, but some implementations (such as xstream) do not as of 10/08/2021.
+As well, some guideance on making an `Observable` do not include `closed` propery.
+@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
+*/
+export type Unsubscribable = {
+	unsubscribe(): void;
+};
+
+type OnNext<ValueType> = (value: ValueType) => void;
+type OnError = (error: unknown) => void;
+type OnComplete = () => void;
+
+export type Observer<ValueType> = {
+	next: OnNext<ValueType>;
+	error: OnError;
+	complete: OnComplete;
+};
+
 /**
 Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
 
+@remarks
+The TC39 Observable proposal defines 2 forms of `subscribe()`:
+1. Three callback arguments: `subscribe(observer: OnNext<ValueType>, onError?: OnError, onComplete?: OnComplete): Unsubscribable;`
+2. A single `observer` argument: (as defined below)
+
+But `Observable` implementations have evolved to preferring case 2 and some implementations choose not to implement case 1. Therefore, an `ObservableLike` cannot be trusted to implement the first case. (xstream and hand built observerables often do not implement case 1)
+
+@see https://github.com/tc39/proposal-observable#observable
+@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
 */
 export interface ObservableLike<ValueType = unknown> {
-	subscribe(observer: (value: ValueType) => void): void;
+	subscribe(observer?: Partial<Observer<ValueType>>): Unsubscribable;
 	[Symbol.observable](): ObservableLike<ValueType>;
 }

package/source/partial-deep.d.ts

@@ -43,11 +43,15 @@ export type PartialDeep<T> = T extends Primitive
 	: T extends ((...arguments: any[]) => unknown)
 	? T | undefined
 	: T extends object
-	? PartialObjectDeep<T>
+	? T extends Array<infer ItemType> // Test for arrays/tuples, per https://github.com/microsoft/TypeScript/issues/35156
+		? ItemType[] extends T // Test for arrays (non-tuples) specifically
+			? Array<PartialDeep<ItemType | undefined>> // Recreate relevant array type to prevent eager evaluation of circular reference
+			: PartialObjectDeep<T> // Tuples behave properly
+		: PartialObjectDeep<T>
 	: unknown;
 
 /**
-Same as `PartialDeep`, but accepts only `Map`s and  as inputs. Internal helper for `PartialDeep`.
+Same as `PartialDeep`, but accepts only `Map`s and as inputs. Internal helper for `PartialDeep`.
 */
 interface PartialMapDeep<KeyType, ValueType> extends Map<PartialDeep<KeyType>, PartialDeep<ValueType>> {}
 

package/source/promisable.d.ts

@@ -12,8 +12,8 @@ Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31394)
 import {Promisable} from 'type-fest';
 
 async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
-    const entry = await getLogEntry();
-    console.log(entry);
+	const entry = await getLogEntry();
+	console.log(entry);
 }
 
 logger(() => 'foo');

package/source/simplify.d.ts

@@ -1,5 +1,5 @@
 /**
-Flatten the type output to improve type hints shown in editors.
+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.
 
 @example
 ```
@@ -19,6 +19,40 @@ type SizeProps = {
 type Props = Simplify<PositionProps & SizeProps>;
 ```
 
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+function fn(object: Record<string, unknown>): void {}
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+
 @category Utilities
 */
 export type Simplify<T> = {[KeyType in keyof T]: T[KeyType]};