type-fest 3.7.2 → 3.9.0

package/index.d.ts

@@ -55,6 +55,7 @@ export type {Jsonify} from './source/jsonify';
 export type {Jsonifiable} from './source/jsonifiable';
 export type {Schema} from './source/schema';
 export type {LiteralToPrimitive} from './source/literal-to-primitive';
+export type {LiteralToPrimitiveDeep} from './source/literal-to-primitive-deep';
 export type {
 	PositiveInfinity,
 	NegativeInfinity,
@@ -71,6 +72,7 @@ export type {StringKeyOf} from './source/string-key-of';
 export type {Exact} from './source/exact';
 export type {ReadonlyTuple} from './source/readonly-tuple';
 export type {OptionalKeysOf} from './source/optional-keys-of';
+export type {OverrideProperties} from './source/override-properties';
 export type {HasOptionalKeys} from './source/has-optional-keys';
 export type {RequiredKeysOf} from './source/required-keys-of';
 export type {HasRequiredKeys} from './source/has-required-keys';
@@ -84,6 +86,12 @@ export type {
 	IsBooleanLiteral,
 	IsSymbolLiteral,
 } from './source/is-literal';
+export type {IsAny} from './source/is-any';
+export type {IfAny} from './source/if-any';
+export type {IsNever} from './source/is-never';
+export type {IfNever} from './source/if-never';
+export type {IsUnknown} from './source/is-unknown';
+export type {IfUnknown} from './source/if-unknown';
 
 // Template literal types
 export type {CamelCase} from './source/camel-case';

package/package.json

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

package/readme.md

@@ -135,6 +135,7 @@ Click the type names for complete docs.
 - [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
 - [`MergeDeep`](source/merge-deep.d.ts) - Merge two objects or two arrays/tuples recursively into a new type.
 - [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
+- [`OverrideProperties`](source/override-properties.d.ts) - Override only existing properties of the given type. Similar to `Merge`, but enforces that the original type has the properties you want to override.
 - [`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.
@@ -157,6 +158,7 @@ Click the type names for complete docs.
 - [`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.
+- [`LiteralToPrimitiveDeep`](source/literal-to-primitive-deep.d.ts) - Like `LiteralToPrimitive` except it converts literal types inside an object or array deeply.
 - [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
 - [`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.
@@ -173,12 +175,43 @@ Click the type names for complete docs.
 - [`HasRequiredKeys`](source/has-required-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any required fields.
 - [`Spread`](source/spread.d.ts) - Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
 - [`IsEqual`](source/is-equal.d.ts) - Returns a boolean for whether the two given types are equal.
+- [`TaggedUnion`](source/tagged-union.d.ts) - Create a union of types that share a common discriminant property.
+
+### Type Guard
+
+#### `IsType` vs. `IfType`
+
+For every `IsT` type (e.g. `IsAny`), there is an associated `IfT` type that can help simplify conditional types. While the `IsT` types return a `boolean`, the `IfT` types act like an `If`/`Else` - they resolve to the given `TypeIfT` or `TypeIfNotT` depending on whether `IsX` is `true` or not. By default, `IfT` returns a `boolean`:
+
+```ts
+type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (
+	IsAny<T> extends true ? TypeIfAny : TypeIfNotAny
+);
+```
+
+#### Usage
+
+```ts
+import type {IsAny, IfAny} from 'type-fest';
+
+type ShouldBeTrue = IsAny<any> extends true ? true : false;
+//=> true
+
+type ShouldBeFalse = IfAny<'not any'>;
+//=> false
+
+type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
+//=> 'never'
+```
+
 - [`IsLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsStringLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `string` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsNumericLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `number` or `bigint` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsBooleanLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `true` or `false` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 - [`IsSymbolLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `symbol` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
-- [`TaggedUnion`](source/tagged-union.d.ts) - Create a union of types that share a common discriminant property.
+- [`IsAny`](source/is-any.d.ts) - Returns a boolean for whether the given type is `any`. (Conditional version: [`IfAny`](source/if-any.d.ts).)
+- [`IsNever`](source/is-never.d.ts) - Returns a boolean for whether the given type is `never`. (Conditional version: [`IfNever`](source/if-never.d.ts).)
+- [`IsUnknown`](source/is-unknown.d.ts) - Returns a boolean for whether the given type is `unknown`. (Conditional version: [`IfUnknown`](source/if-unknown.d.ts).)
 
 ### JSON
 

package/source/if-any.d.ts

@@ -0,0 +1,24 @@
+import type {IsAny} from './is-any';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `any`.
+
+@see {@link IsAny}
+
+@example
+```
+import type {IfAny} from 'type-fest';
+
+type ShouldBeTrue = IfAny<any>;
+//=> true
+
+type ShouldBeBar = IfAny<'not any', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (
+	IsAny<T> extends true ? TypeIfAny : TypeIfNotAny
+);

package/source/if-never.d.ts

@@ -0,0 +1,24 @@
+import type {IsNever} from './is-never';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `never`.
+
+@see {@link IsNever}
+
+@example
+```
+import type {IfNever} from 'type-fest';
+
+type ShouldBeTrue = IfNever<never>;
+//=> true
+
+type ShouldBeBar = IfNever<'not never', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfNever<T, TypeIfNever = true, TypeIfNotNever = false> = (
+	IsNever<T> extends true ? TypeIfNever : TypeIfNotNever
+);

package/source/if-unknown.d.ts

@@ -0,0 +1,24 @@
+import type {IsUnknown} from './is-unknown';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `unknown`.
+
+@see {@link IsUnknown}
+
+@example
+```
+import type {IfUnknown} from 'type-fest';
+
+type ShouldBeTrue = IfUnknown<unknown>;
+//=> true
+
+type ShouldBeBar = IfUnknown<'not unknown', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfUnknown<T, TypeIfUnknown = true, TypeIfNotUnknown = false> = (
+	IsUnknown<T> extends true ? TypeIfUnknown : TypeIfNotUnknown
+);

package/source/internal.d.ts

@@ -1,6 +1,7 @@
 import type {Primitive} from './primitive';
 import type {Simplify} from './simplify';
 import type {Trim} from './trim';
+import type {IsAny} from './is-any';
 
 /**
 Infer the length of the given array `<T>`.
@@ -158,23 +159,6 @@ export type IsNumeric<T extends string> = T extends `${number}`
 		: false
 	: false;
 
-/**
-Returns a boolean for whether the the type is `any`.
-
-@link https://stackoverflow.com/a/49928360/1490091
-*/
-export type IsAny<T> = 0 extends 1 & T ? true : false;
-
-/**
-Returns a boolean for whether the the type is `never`.
-*/
-export type IsNever<T> = [T] extends [never] ? true : false;
-
-/**
-Returns a boolean for whether the the type is `unknown`.
-*/
-export type IsUnknown<T> = IsNever<T> extends false ? T extends unknown ? unknown extends T ? IsAny<T> extends false ? true : false : false : false : false;
-
 /**
 For an object T, if it has any properties that are a union with `undefined`, make those into optional properties instead.
 
@@ -262,3 +246,8 @@ export type HasMultipleCallSignatures<T extends (...arguments: any[]) => unknown
 Returns a boolean for whether the given `boolean` is not `false`.
 */
 export type IsNotFalse<T extends boolean> = [T] extends [false] ? false : true;
+
+/**
+Returns a boolean for whether the given type is `null`.
+*/
+export type IsNull<T> = [T] extends [null] ? true : false;

package/source/is-any.d.ts

@@ -0,0 +1,29 @@
+/**
+Returns a boolean for whether the given type is `any`.
+
+@link https://stackoverflow.com/a/49928360/1490091
+
+Useful in type utilities, such as disallowing `any`s to be passed to a function.
+
+@example
+```
+import type {IsAny} from 'type-fest';
+
+const typedObject = {a: 1, b: 2} as const;
+const anyObject: any = {a: 1, b: 2};
+
+function get<O extends (IsAny<O> extends true ? {} : Record<string, number>), K extends keyof O = keyof O>(obj: O, key: K) {
+	return obj[key];
+}
+
+const typedA = get(typedObject, 'a');
+//=> 1
+
+const anyA = get(anyObject, 'a');
+//=> any
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsAny<T> = 0 extends 1 & T ? true : false;

package/source/is-equal.d.ts

@@ -21,6 +21,7 @@ type Includes<Value extends readonly any[], Item> =
 		: false;
 ```
 
+@category Type Guard
 @category Utilities
 */
 export type IsEqual<A, B> =

package/source/is-literal.d.ts

@@ -1,6 +1,7 @@
 import type {Primitive} from './primitive';
 import type {Numeric} from './numeric';
-import type {IsNever, IsNotFalse} from './internal';
+import type {IsNotFalse} from './internal';
+import type {IsNever} from './is-never';
 
 /**
 Returns a boolean for whether the given type `T` is the specified `LiteralType`.
@@ -77,8 +78,8 @@ const output = capitalize('hello, world!');
 //=> 'Hello, world!'
 ```
 
-@category Utilities
 @category Type Guard
+@category Utilities
 */
 export type IsStringLiteral<T> = LiteralCheck<T, string>;
 
@@ -125,8 +126,8 @@ endsWith('abc123', end);
 //=> boolean
 ```
 
-@category Utilities
 @category Type Guard
+@category Utilities
 */
 export type IsNumericLiteral<T> = LiteralChecks<T, Numeric>;
 
@@ -165,8 +166,8 @@ const eitherId = getId({asString: runtimeBoolean});
 //=> number | string
 ```
 
-@category Utilities
 @category Type Guard
+@category Utilities
 */
 export type IsBooleanLiteral<T> = LiteralCheck<T, boolean>;
 
@@ -200,8 +201,8 @@ get({[symbolValue]: 1} as const, symbolValue);
 //=> number
 ```
 
-@category Utilities
 @category Type Guard
+@category Utilities
 */
 export type IsSymbolLiteral<T> = LiteralCheck<T, symbol>;
 
@@ -246,7 +247,7 @@ stripLeading(str, 'abc');
 //=> string
 ```
 
-@category Utilities
 @category Type Guard
+@category Utilities
 */
 export type IsLiteral<T extends Primitive> = IsNotFalse<IsLiteralUnion<T>>;

package/source/is-never.d.ts

@@ -0,0 +1,49 @@
+/**
+Returns a boolean for whether the given type is `never`.
+
+@link https://github.com/microsoft/TypeScript/issues/31751#issuecomment-498526919
+@link https://stackoverflow.com/a/53984913/10292952
+@link https://www.zhenghao.io/posts/ts-never
+
+Useful in type utilities, such as checking if something does not occur.
+
+@example
+```
+import type {IsNever} from 'type-fest';
+
+type And<A, B> =
+	A extends true
+		? B extends true
+			? true
+			: false
+		: false;
+
+// https://github.com/andnp/SimplyTyped/blob/master/src/types/strings.ts
+type AreStringsEqual<A extends string, B extends string> =
+	And<
+		IsNever<Exclude<A, B>> extends true ? true : false,
+		IsNever<Exclude<B, A>> extends true ? true : false
+	>;
+
+type EndIfEqual<I extends string, O extends string> =
+	AreStringsEqual<I, O> extends true
+		? never
+		: void;
+
+function endIfEqual<I extends string, O extends string>(input: I, output: O): EndIfEqual<I, O> {
+	if (input === output) {
+		process.exit(0);
+	}
+}
+
+endIfEqual('abc', 'abc');
+//=> never
+
+endIfEqual('abc', '123');
+//=> void
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNever<T> = [T] extends [never] ? true : false;

package/source/is-unknown.d.ts

@@ -0,0 +1,52 @@
+import type {IsNull} from './internal';
+
+/**
+Returns a boolean for whether the given type is `unknown`.
+
+@link https://github.com/dsherret/conditional-type-checks/pull/16
+
+Useful in type utilities, such as when dealing with unknown data from API calls.
+
+@example
+```
+import type {IsUnknown} from 'type-fest';
+
+// https://github.com/pajecawav/tiny-global-store/blob/master/src/index.ts
+type Action<TState, TPayload = void> =
+	IsUnknown<TPayload> extends true
+		? (state: TState) => TState,
+		: (state: TState, payload: TPayload) => TState;
+
+class Store<TState> {
+	constructor(private state: TState) {}
+
+	execute<TPayload = void>(action: Action<TState, TPayload>, payload?: TPayload): TState {
+		this.state = action(this.state, payload);
+		return this.state;
+	}
+
+	// ... other methods
+}
+
+const store = new Store({value: 1});
+declare const someExternalData: unknown;
+
+store.execute(state => ({value: state.value + 1}));
+//=> `TPayload` is `void`
+
+store.execute((state, payload) => ({value: state.value + payload}), 5);
+//=> `TPayload` is `5`
+
+store.execute((state, payload) => ({value: state.value + payload}), someExternalData);
+//=> Errors: `action` is `(state: TState) => TState`
+```
+
+@category Utilities
+*/
+export type IsUnknown<T> = (
+	unknown extends T // `T` can be `unknown` or `any`
+		? IsNull<T> extends false // `any` can be `null`, but `unknown` can't be
+			? true
+			: false
+		: false
+);

package/source/join.d.ts

@@ -1,3 +1,13 @@
+// The builtin `join` method supports all these natively in the same way that typescript handles them so we can safely accept all of them.
+type JoinableItem = string | number | bigint | boolean | undefined | null;
+
+// `null` and `undefined` are treated uniquely in the built-in join method, in a way that differs from the default `toString` that would result in the type `${undefined}`. That's why we need to handle it specifically with this helper.
+// @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#description
+type NullishCoalesce<
+	Value extends JoinableItem,
+	Fallback extends string,
+> = Value extends undefined | null ? NonNullable<Value> | Fallback : Value;
+
 /**
 Join an array of strings and/or numbers using the given string as a delimiter.
 
@@ -15,21 +25,44 @@ const path: Join<['foo', 'bar', 'baz'], '.'> = ['foo', 'bar', 'baz'].join('.');
 
 // Only number items; result is: '1.2.3'
 const path: Join<[1, 2, 3], '.'> = [1, 2, 3].join('.');
+
+// Only bigint items; result is '1.2.3'
+const path: Join<[1n, 2n, 3n], '.'> = [1n, 2n, 3n].join('.');
+
+// Only boolean items; result is: 'true.false.true'
+const path: Join<[true, false, true], '.'> = [true, false, true].join('.');
+
+// Contains nullish items; result is: 'foo..baz..xyz'
+const path: Join<['foo', undefined, 'baz', null, 'xyz'], '.'> = ['foo', undefined, 'baz', null, 'xyz'].join('.');
+
+// Partial tuple shapes (rest param last); result is: `prefix.${string}`
+const path: Join<['prefix', ...string[]], '.'> = ['prefix'].join('.');
+
+// Partial tuple shapes (rest param first); result is: `${string}.suffix`
+const path: Join<[...string[], 'suffix'], '.'> = ['suffix'].join('.');
+
+// Tuples items with nullish unions; result is '.' | 'hello.' | '.world' | 'hello.world'
+const path: Join<['hello' | undefined, 'world' | null], '.'> = ['hello', 'world'].join('.');
 ```
 
 @category Array
 @category Template literal
 */
 export type Join<
-	Strings extends ReadonlyArray<string | number>,
+	Items extends readonly JoinableItem[],
 	Delimiter extends string,
-> = Strings extends []
+> = Items extends []
 	? ''
-	: Strings extends readonly [string | number]
-		? `${Strings[0]}`
-		: Strings extends readonly [
-			string | number,
-			...infer Rest extends ReadonlyArray<string | number>,
+	: Items extends readonly [JoinableItem?]
+		? `${NullishCoalesce<Items[0], ''>}`
+		: Items extends readonly [
+			infer First extends JoinableItem,
+			...infer Tail extends readonly JoinableItem[],
 		]
-			? `${Strings[0]}${Delimiter}${Join<Rest, Delimiter>}`
-			: string;
+			? `${NullishCoalesce<First, ''>}${Delimiter}${Join<Tail, Delimiter>}`
+			: Items extends readonly [
+				...infer Head extends readonly JoinableItem[],
+				infer Last extends JoinableItem,
+			]
+				? `${Join<Head, Delimiter>}${Delimiter}${NullishCoalesce<Last, ''>}`
+				: string;

package/source/jsonify.d.ts

@@ -1,8 +1,9 @@
 import type {JsonPrimitive, JsonValue} from './basic';
 import type {EmptyObject} from './empty-object';
-import type {IsAny, UndefinedToOptional} from './internal';
+import type {UndefinedToOptional} from './internal';
 import type {NegativeInfinity, PositiveInfinity} from './numeric';
 import type {TypedArray} from './typed-array';
+import type {IsAny} from './is-any';
 
 // Note: The return value has to be `any` and not `unknown` so it can match `void`.
 type NotJsonable = ((...arguments_: any[]) => any) | undefined | symbol;

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

@@ -0,0 +1,36 @@
+import type {LiteralToPrimitive} from './literal-to-primitive';
+import type {OmitIndexSignature} from './omit-index-signature';
+
+/**
+Like `LiteralToPrimitive` except it converts literal types inside an object or array deeply.
+
+For example, given a constant object, it returns a new object type with the same keys but with all the values converted to primitives.
+
+@see LiteralToPrimitive
+
+Use-case: Deal with data that is imported from a JSON file.
+
+@example
+```
+import type {LiteralToPrimitiveDeep, TsConfigJson} from 'type-fest';
+import tsconfig from 'path/to/tsconfig.json';
+
+function doSomethingWithTSConfig(config: LiteralToPrimitiveDeep<TsConfigJson>) { ... }
+
+// No casting is needed to pass the type check
+doSomethingWithTSConfig(tsconfig);
+
+// If LiteralToPrimitiveDeep is not used, you need to cast the imported data like this:
+doSomethingWithTSConfig(tsconfig as TsConfigJson);
+```
+
+@category Type
+@category Object
+*/
+export type LiteralToPrimitiveDeep<T> = T extends object
+	? T extends Array<infer U>
+		? Array<LiteralToPrimitiveDeep<U>>
+		: {
+			[K in keyof OmitIndexSignature<T>]: LiteralToPrimitiveDeep<T[K]>;
+		}
+	: LiteralToPrimitive<T>;

package/source/override-properties.d.ts

@@ -0,0 +1,26 @@
+import type {Merge} from './merge';
+
+/**
+Override existing properties of the given type. Similar to `Merge`, but enforces that the original type has the properties you want to override.
+
+This is useful when you want to override existing properties with a different type and make sure that these properties really exist in the original.
+
+@example
+```
+type Foo = {
+	a: string
+	b: string
+}
+type Bar = OverrideProperties<Foo, {b: number}>
+//=> {a: string, b: number}
+
+type Baz = OverrideProperties<Foo, {c: number}>
+// error TS2559: Type '{c: number}' has no properties in common with type 'Partial{a: unknown; b: unknown}>'.
+```
+
+@category Object
+*/
+export type OverrideProperties<
+	TOriginal,
+	TOverride extends Partial<{[key in keyof TOriginal]: unknown}>,
+> = Merge<TOriginal, TOverride>;

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

@@ -1,4 +1,4 @@
-import type {IsUnknown} from './internal';
+import type {IsUnknown} from './is-unknown';
 
 /**
 Create a function type with a return type of your choice and the same parameters as the given function type.