type-fest 3.2.0 → 3.4.0

package/index.d.ts

@@ -101,5 +101,6 @@ export type {Get} from './source/get';
 export type {LastArrayElement} from './source/last-array-element';
 
 // Miscellaneous
+export type {GlobalThis} from './source/global-this';
 export type {PackageJson} from './source/package-json';
 export type {TsConfigJson} from './source/tsconfig-json';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "3.2.0",
+	"version": "3.4.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -37,8 +37,8 @@
 		"@sindresorhus/tsconfig": "~0.7.0",
 		"expect-type": "^0.15.0",
 		"tsd": "^0.24.1",
-		"typescript": "^4.8.4",
-		"xo": "^0.52.4"
+		"typescript": "^4.9.3",
+		"xo": "^0.53.1"
 	},
 	"xo": {
 		"rules": {

package/readme.md

@@ -68,20 +68,6 @@
 					</sub>
 				</div>
 			</a>
-			<br>
-			<br>
-			<a href="https://sizzy.co/?utm_campaign=github_repo&utm_source=github&utm_medium=referral&utm_content=type-fest&utm_term=sindre">
-				<div>
-					<img src="https://sindresorhus.com/assets/thanks/sizzy-logo.png" width="240" alt="Sizzy">
-				</div>
-				<div>
-					<sub>
-					<b>Before Sizzy:</b> web development is stressing you out, responsive design is hard, you have an overwhelming amount of opened tabs & apps.
-					<br>
-					<b>After Sizzy:</b> all the tools you need in one place, responsive design is a breeze, no more context switching.
-					</sub>
-				</div>
-			</a>
 		</p>
 	</div>
 	<br>
@@ -250,6 +236,7 @@ Click the type names for complete docs.
 
 ### Miscellaneous
 
+- [`GlobalThis`](source/global-this.d.ts) - Declare locally scoped properties on `globalThis`.
 - [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). It also includes support for [TypeScript Declaration Files](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) and [Yarn Workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/).
 - [`TsConfigJson`](source/tsconfig-json.d.ts) - Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
@@ -637,13 +624,13 @@ There are many advanced types most users don't know about.
 		// Mutate array randomly changing its' elements indexes.
 	}
 
-	function callNTimes<Fn extends (...args: any[]) => any> (func: Fn, callCount: number) {
+	function callNTimes<Fn extends (...arguments_: any[]) => any> (func: Fn, callCount: number) {
 		// Type that represents the type of the received function parameters.
 		type FunctionParameters = Parameters<Fn>;
 
-		return function (...args: FunctionParameters) {
+		return function (...arguments_: FunctionParameters) {
 			for (let i = 0; i < callCount; i++) {
-				func(...args);
+				func(...arguments_);
 			}
 		}
 	}
@@ -670,7 +657,7 @@ There are many advanced types most users don't know about.
 		}
 	}
 
-	class InstanceCache<T extends (new (...args: any[]) => any)> {
+	class InstanceCache<T extends (new (...arguments_: any[]) => any)> {
 		private ClassConstructor: T;
 		private cache: Map<string, InstanceType<T>> = new Map();
 
@@ -678,18 +665,18 @@ There are many advanced types most users don't know about.
 			this.ClassConstructor = ctr;
 		}
 
-		getInstance (...args: ConstructorParameters<T>): InstanceType<T> {
-			const hash = this.calculateArgumentsHash(...args);
+		getInstance (...arguments_: ConstructorParameters<T>): InstanceType<T> {
+			const hash = this.calculateArgumentsHash(...arguments_);
 
 			const existingInstance = this.cache.get(hash);
 			if (existingInstance !== undefined) {
 				return existingInstance;
 			}
 
-			return new this.ClassConstructor(...args);
+			return new this.ClassConstructor(...arguments_);
 		}
 
-		private calculateArgumentsHash(...args: any[]): string {
+		private calculateArgumentsHash(...arguments_: any[]): string {
 			// Calculate hash.
 			return 'hash';
 		}
@@ -761,17 +748,17 @@ There are many advanced types most users don't know about.
 	const instanceCounter: Map<Function, number> = new Map();
 
 	interface Constructor {
-			new(...args: any[]): any;
+			new(...arguments_: any[]): any;
 	}
 
 	// Keep track how many instances of `Constr` constructor have been created.
 	function getInstance<
 			Constr extends Constructor,
-			Args extends ConstructorParameters<Constr>
-	>(constructor: Constr, ...args: Args): InstanceType<Constr> {
+			Arguments extends ConstructorParameters<Constr>
+	>(constructor: Constr, ...arguments_: Arguments): InstanceType<Constr> {
 			let count = instanceCounter.get(constructor) || 0;
 
-			const instance = new constructor(...args);
+			const instance = new constructor(...arguments_);
 
 			instanceCounter.set(constructor, count + 1);
 

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

@@ -1,4 +1,4 @@
-type AsyncFunction = (...args: any[]) => Promise<unknown>;
+type AsyncFunction = (...arguments_: any[]) => Promise<unknown>;
 
 /**
 Unwrap the return type of a function that returns a `Promise`.

package/source/asyncify.d.ts

@@ -29,4 +29,4 @@ const getFooAsync: AsyncifiedFooGetter = (someArg) => {
 
 @category Async
 */
-export type Asyncify<Fn extends (...args: any[]) => any> = SetReturnType<Fn, Promise<Awaited<ReturnType<Fn>>>>;
+export type Asyncify<Fn extends (...arguments_: any[]) => any> = SetReturnType<Fn, Promise<Awaited<ReturnType<Fn>>>>;

package/source/exact.d.ts

@@ -1,20 +1,5 @@
-import type {KeysOfUnion} from './internal';
-
-/**
-Extract the element of an array that also works for array union.
-
-Returns `never` if T is not an array.
-
-It creates a type-safe way to access the element type of `unknown` type.
-*/
-type ArrayElement<T> = T extends readonly unknown[] ? T[0] : never;
-
-/**
-Extract the object field type if T is an object and K is a key of T, return `never` otherwise.
-
-It creates a type-safe way to access the member type of `unknown` type.
-*/
-type ObjectValue<T, K> = K extends keyof T ? T[K] : never;
+import type {KeysOfUnion, ArrayElement, ObjectValue} from './internal';
+import type {Opaque} from './opaque';
 
 /**
 Create a type from `ParameterType` and `InputType` and change keys exclusive to `InputType` to `never`.
@@ -35,7 +20,7 @@ This is useful for function type-guarding to reject arguments with excess proper
 ```
 type OnlyAcceptName = {name: string};
 
-function onlyAcceptName(args: OnlyAcceptName) {}
+function onlyAcceptName(arguments_: OnlyAcceptName) {}
 
 // TypeScript complains about excess properties when an object literal is provided.
 onlyAcceptName({name: 'name', id: 1});
@@ -54,7 +39,7 @@ import {Exact} from 'type-fest';
 
 type OnlyAcceptName = {name: string};
 
-function onlyAcceptNameImproved<T extends Exact<OnlyAcceptName, T>>(args: T) {}
+function onlyAcceptNameImproved<T extends Exact<OnlyAcceptName, T>>(arguments_: T) {}
 
 const invalidInput = {name: 'name', id: 1};
 onlyAcceptNameImproved(invalidInput); // Compilation error
@@ -69,5 +54,7 @@ export type Exact<ParameterType, InputType> =
 	ParameterType extends unknown[] ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
 	// In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
 		: ParameterType extends readonly unknown[] ? ReadonlyArray<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
-			: ParameterType extends object ? ExactObject<ParameterType, InputType>
-				: ParameterType;
+			// For Opaque types, internal details are hidden from public, so let's leave it as is.
+			: ParameterType extends Opaque<infer OpaqueType, infer OpaqueToken> ? ParameterType
+				: ParameterType extends object ? ExactObject<ParameterType, InputType>
+					: ParameterType;

package/source/global-this.d.ts

@@ -0,0 +1,21 @@
+/**
+Declare locally scoped properties on `globalThis`.
+
+When defining a global variable in a declaration file is inappropriate, it can be helpful to define a `type` or `interface` (say `ExtraGlobals`) with the global variable and then cast `globalThis` via code like `globalThis as unknown as ExtraGlobals`.
+
+Instead of casting through `unknown`, you can update your `type` or `interface` to extend `GlobalThis` and then directly cast `globalThis`.
+
+@example
+```
+import type {GlobalThis} from 'type-fest';
+
+type ExtraGlobals = GlobalThis & {
+	readonly GLOBAL_TOKEN: string;
+};
+
+(globalThis as ExtraGlobals).GLOBAL_TOKEN;
+```
+
+@category Type
+*/
+export type GlobalThis = typeof globalThis;

package/source/internal.d.ts

@@ -1,4 +1,5 @@
 import type {Primitive} from './primitive';
+import type {Simplify} from './simplify';
 
 /**
 Returns a boolean for whether the two given types are equal.
@@ -94,6 +95,22 @@ Extracts the type of an array or tuple minus the first element.
 */
 export type ArrayTail<TArray extends UnknownArrayOrTuple> = TArray extends readonly [unknown, ...infer TTail] ? TTail : [];
 
+/**
+Extract the element of an array that also works for array union.
+
+Returns `never` if T is not an array.
+
+It creates a type-safe way to access the element type of `unknown` type.
+*/
+export type ArrayElement<T> = T extends readonly unknown[] ? T[0] : never;
+
+/**
+Extract the object field type if T is an object and K is a key of T, return `never` otherwise.
+
+It creates a type-safe way to access the member type of `unknown` type.
+*/
+export type ObjectValue<T, K> = K extends keyof T ? T[K] : never;
+
 /**
 Returns a boolean for whether the string is lowercased.
 */
@@ -108,3 +125,88 @@ export type IsUpperCase<T extends string> = T extends Uppercase<T> ? true : fals
 Returns a boolean for whether the string is numeric.
 */
 export type IsNumeric<T extends string> = T extends `${number}` ? true : 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.
+
+@example
+```
+type User = {
+	firstName: string;
+	lastName: string | undefined;
+};
+
+type OptionalizedUser = UndefinedToOptional<User>;
+//=> {
+// 	firstName: string;
+// 	lastName?: string;
+// }
+```
+*/
+export type UndefinedToOptional<T extends object> = Simplify<
+{
+	// Property is not a union with `undefined`, keep it as-is.
+	[Key in keyof Pick<T, FilterDefinedKeys<T>>]: T[Key];
+} & {
+	// Property _is_ a union with defined value. Set as optional (via `?`) and remove `undefined` from the union.
+	[Key in keyof Pick<T, FilterOptionalKeys<T>>]?: Exclude<T[Key], undefined>;
+}
+>;
+
+// Returns `never` if the key or property is not jsonable without testing whether the property is required or optional otherwise return the key.
+type BaseKeyFilter<Type, Key extends keyof Type> = Key extends symbol
+	? never
+	: Type[Key] extends symbol
+		? never
+		: [(...arguments_: any[]) => any] extends [Type[Key]]
+			? never
+			: Key;
+
+/**
+Returns the required keys.
+*/
+type FilterDefinedKeys<T extends object> = Exclude<
+{
+	[Key in keyof T]: IsAny<T[Key]> extends true
+		? Key
+		: undefined extends T[Key]
+			? never
+			: T[Key] extends undefined
+				? never
+				: BaseKeyFilter<T, Key>;
+}[keyof T],
+undefined
+>;
+
+/**
+Returns the optional keys.
+*/
+type FilterOptionalKeys<T extends object> = Exclude<
+{
+	[Key in keyof T]: IsAny<T[Key]> extends true
+		? never
+		: undefined extends T[Key]
+			? T[Key] extends undefined
+				? never
+				: BaseKeyFilter<T, Key>
+			: never;
+}[keyof T],
+undefined
+>;

package/source/join.d.ts

@@ -23,8 +23,13 @@ const path: Join<[1, 2, 3], '.'> = [1, 2, 3].join('.');
 export type Join<
 	Strings extends Array<string | number>,
 	Delimiter extends string,
-> = Strings extends [] ? '' :
-	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;
+> = Strings extends []
+	? ''
+	: Strings extends [string | number]
+		? `${Strings[0]}`
+		: Strings extends [
+			string | number,
+			...infer Rest extends Array<string | number>,
+		]
+			? `${Strings[0]}${Delimiter}${Join<Rest, Delimiter>}`
+			: string;

package/source/jsonify.d.ts

@@ -1,32 +1,26 @@
 import type {JsonPrimitive, JsonValue} from './basic';
 import type {EmptyObject} from './empty-object';
-import type {Merge} from './merge';
+import type {IsAny, UndefinedToOptional} from './internal';
 import type {NegativeInfinity, PositiveInfinity} from './numeric';
 import type {TypedArray} from './typed-array';
 
 // Note: The return value has to be `any` and not `unknown` so it can match `void`.
-type NotJsonable = ((...args: any[]) => any) | undefined | symbol;
-
-// Returns never if the key or property is not jsonable without testing whether the property is required or optional otherwise return the key.
-type BaseKeyFilter<Type, Key extends keyof Type> = Key extends symbol
-	? never
-	: Type[Key] extends symbol
-		? never
-		: [(...args: any[]) => any] extends [Type[Key]]
-			? never
-			: Key;
-
-// Returns never if the key or property is not jsonable or optional otherwise return the key.
-type RequiredKeyFilter<Type, Key extends keyof Type> = undefined extends Type[Key]
-	? never
-	: BaseKeyFilter<Type, Key>;
-
-// Returns never if the key or property is not jsonable or required otherwise return the key.
-type OptionalKeyFilter<Type, Key extends keyof Type> = undefined extends Type[Key]
-	? Type[Key] extends undefined
-		? never
-		: BaseKeyFilter<Type, Key>
-	: never;
+type NotJsonable = ((...arguments_: any[]) => any) | undefined | symbol;
+
+type JsonifyTuple<T extends [unknown, ...unknown[]]> = {
+	[Key in keyof T]: T[Key] extends NotJsonable ? null : Jsonify<T[Key]>;
+};
+
+type FilterJsonableKeys<T extends object> = {
+	[Key in keyof T]: T[Key] extends NotJsonable ? never : Key;
+}[keyof T];
+
+/**
+JSON serialize objects (not including arrays) and classes.
+*/
+type JsonifyObject<T extends object> = {
+	[Key in keyof Pick<T, FilterJsonableKeys<T>>]: Jsonify<T[Key]>;
+};
 
 /**
 Transform a type to one that is assignable to the `JsonValue` type.
@@ -41,7 +35,7 @@ An interface cannot be structurally compared to `JsonValue` because an interface
 
 @example
 ```
-import type {Jsonify} from 'type-fest';
+import type {Jsonify, JsonValue} from 'type-fest';
 
 interface Geometry {
 	type: 'Point' | 'Polygon';
@@ -85,29 +79,36 @@ const timeJson = JSON.parse(JSON.stringify(time)) as Jsonify<typeof time>;
 
 @category JSON
 */
-export type Jsonify<T> =
-	// Check if there are any non-JSONable types represented in the union.
-	// Note: The use of tuples in this first condition side-steps distributive conditional types
-	// (see https://github.com/microsoft/TypeScript/issues/29368#issuecomment-453529532)
-	[Extract<T, NotJsonable | bigint>] extends [never]
-		? T extends PositiveInfinity | NegativeInfinity	? null
-			: T extends JsonPrimitive ? T // Primitive is acceptable
-				: T extends object
-				// Any object with toJSON is special case
-					? T extends {toJSON(): infer J} ? (() => J) extends (() => JsonValue) // Is J assignable to JsonValue?
-						? J // Then T is Jsonable and its Jsonable value is J
-						: Jsonify<J> // Maybe if we look a level deeper we'll find a JsonValue
-					// Instanced primitives are objects
-						: T extends Number ? number
-							: T extends String ? string
-								: T extends Boolean ? boolean
-									: T extends Map<any, any> | Set<any> ? EmptyObject
-										: T extends TypedArray ? Record<string, number>
-											: T extends any[]
-												? {[I in keyof T]: T[I] extends NotJsonable ? null : Jsonify<T[I]>}
-												: Merge<
-												{[Key in keyof T as RequiredKeyFilter<T, Key>]: Jsonify<T[Key]>},
-												{[Key in keyof T as OptionalKeyFilter<T, Key>]?: Jsonify<Exclude<T[Key], undefined>>}
-												> // Recursive call for its children
-					: never // Otherwise any other non-object is removed
-		: never; // Otherwise non-JSONable type union was found not empty
+export type Jsonify<T> = IsAny<T> extends true
+	? any
+	: T extends PositiveInfinity | NegativeInfinity
+		? null
+		: T extends JsonPrimitive
+			? T
+			: // Instanced primitives are objects
+			T extends Number
+				? number
+				: T extends String
+					? string
+					: T extends Boolean
+						? boolean
+						: T extends Map<any, any> | Set<any>
+							? EmptyObject
+							: T extends TypedArray
+								? Record<string, number>
+								: T extends NotJsonable
+									? never // Non-JSONable type union was found not empty
+									: // Any object with toJSON is special case
+									T extends {toJSON(): infer J}
+										? (() => J) extends () => JsonValue // Is J assignable to JsonValue?
+											? J // Then T is Jsonable and its Jsonable value is J
+											: Jsonify<J> // Maybe if we look a level deeper we'll find a JsonValue
+										: T extends []
+											? []
+											: T extends [unknown, ...unknown[]]
+												? JsonifyTuple<T>
+												: T extends ReadonlyArray<infer U>
+													? Array<U extends NotJsonable ? null : Jsonify<U>>
+													: T extends object
+														? JsonifyObject<UndefinedToOptional<T>> // JsonifyObject recursive call for its children
+														: never; // Otherwise any other non-object is removed

package/source/set-non-nullable.d.ts

@@ -1,6 +1,3 @@
-import type {Except} from './except';
-import type {Simplify} from './simplify';
-
 /**
 Create a type that makes the given keys non-nullable, where the remaining keys are kept as is.
 
@@ -35,10 +32,8 @@ type AllNonNullable = SetNonNullable<Foo>;
 
 @category Object
 */
-export type SetNonNullable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
-	Simplify<
-	// Pick just the keys that are readonly from the base type.
-	Except<BaseType, Keys> &
-	// Pick the keys that should be non-nullable from the base type and make them non-nullable.
-	{[Key in Keys]: NonNullable<BaseType[Key]>}
-	>;
+export type SetNonNullable<BaseType, Keys extends keyof BaseType = keyof BaseType> = {
+	[Key in keyof BaseType]: Key extends Keys
+		? NonNullable<BaseType[Key]>
+		: BaseType[Key];
+};

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

@@ -1,6 +1,4 @@
-type IsAny<T> = 0 extends (1 & T) ? true : false; // https://stackoverflow.com/a/49928360/3406963
-type IsNever<T> = [T] extends [never] ? true : false;
-type IsUnknown<T> = IsNever<T> extends false ? T extends unknown ? unknown extends T ? IsAny<T> extends false ? true : false : false : false : false;
+import type {IsUnknown} from './internal';
 
 /**
 Create a function type with a return type of your choice and the same parameters as the given function type.
@@ -19,13 +17,13 @@ type MyWrappedFunction = SetReturnType<MyFunctionThatCanThrow, SomeOtherType | u
 
 @category Function
 */
-export type SetReturnType<Fn extends (...args: any[]) => any, TypeToReturn> =
+export type SetReturnType<Fn extends (...arguments_: any[]) => any, TypeToReturn> =
 	// Just using `Parameters<Fn>` isn't ideal because it doesn't handle the `this` fake parameter.
-	Fn extends (this: infer ThisArg, ...args: infer Arguments) => any ? (
+	Fn extends (this: infer ThisArg, ...arguments_: infer Arguments) => any ? (
 		// If a function did not specify the `this` fake parameter, it will be inferred to `unknown`.
 		// We want to detect this situation just to display a friendlier type upon hovering on an IntelliSense-powered IDE.
-		IsUnknown<ThisArg> extends true ? (...args: Arguments) => TypeToReturn : (this: ThisArg, ...args: Arguments) => TypeToReturn
+		IsUnknown<ThisArg> extends true ? (...arguments_: Arguments) => TypeToReturn : (this: ThisArg, ...arguments_: Arguments) => TypeToReturn
 	) : (
 		// This part should be unreachable, but we make it meaningful just in case…
-		(...args: Parameters<Fn>) => TypeToReturn
+		(...arguments_: Parameters<Fn>) => TypeToReturn
 	);