type-fest 2.5.1 → 2.6.0

package/license

@@ -1,9 +1 @@
-MIT License
-
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+SPDX-License-Identifier: (MIT OR CC0-1.0)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "2.5.1",
+	"version": "2.6.0",
 	"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*
@@ -111,7 +111,6 @@ Click the type names for complete docs.
 - [`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.
@@ -127,7 +126,7 @@ Click the type names for complete docs.
 - [`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
@@ -168,6 +167,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
@@ -787,7 +792,7 @@ You can find some examples in the [TypeScript docs](https://www.typescriptlang.o
 
 ## License
 
-(MIT OR CC0-1.0)
+SPDX-License-Identifier: (MIT OR CC0-1.0)
 
 ---
 

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,11 @@ 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>}`
+		: Parts extends [string]
+		? string
 		: '';
 
 /**
@@ -81,6 +84,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/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/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.

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

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';