type-fest 2.4.0 → 2.5.3

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.4.0",
+	"version": "2.5.3",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -35,7 +35,7 @@
 		"@sindresorhus/tsconfig": "~0.7.0",
 		"expect-type": "^0.12.0",
 		"tsd": "^0.17.0",
-		"typescript": "^4.1.3",
+		"typescript": ">=4.2",
 		"xo": "^0.43.0"
 	},
 	"types": "./index.d.ts",

package/readme.md

@@ -58,8 +58,8 @@ PR welcome for additional commonly needed types and docs improvements. Read the
 
 ## Install
 
-```
-$ npm install type-fest
+```sh
+npm install type-fest
 ```
 
 *Requires TypeScript >=4.2*
@@ -119,13 +119,15 @@ 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
@@ -166,6 +168,12 @@ Click the type names for complete docs.
 - [`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.
 
+## Alternative type names
+
+*If you know one of our types by a different name, add it here for discovery.*
+
+- `PartialBy` - See [`SetOptional`](https://github.com/sindresorhus/type-fest/blob/main/source/set-optional.d.ts)
+
 ## Tips
 
 ### Related

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/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/join.d.ts

@@ -26,4 +26,4 @@ export type Join<
 	Strings extends [string | number] ? `${Strings[0]}` :
 	// @ts-expect-error `Rest` is inferred as `unknown` here: https://github.com/microsoft/TypeScript/issues/45281
 	Strings extends [string | number, ...infer Rest] ? `${Strings[0]}${Delimiter}${Join<Rest, Delimiter>}` :
-	string | number;
+	string;

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/partial-deep.d.ts

@@ -43,7 +43,11 @@ 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;
 
 /**

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]};