type-fest 4.3.3 → 4.5.0

package/index.d.ts

@@ -5,6 +5,7 @@ export * from './source/basic';
 export * from './source/observable-like';
 
 // Utilities
+export type {KeysOfUnion} from './source/keys-of-union';
 export type {EmptyObject, IsEmptyObject} from './source/empty-object';
 export type {NonEmptyObject} from './source/non-empty-object';
 export type {UnknownRecord} from './source/unknown-record';
@@ -24,6 +25,7 @@ export type {PickIndexSignature} from './source/pick-index-signature';
 export type {PartialDeep, PartialDeepOptions} from './source/partial-deep';
 export type {RequiredDeep} from './source/required-deep';
 export type {PartialOnUndefinedDeep, PartialOnUndefinedDeepOptions} from './source/partial-on-undefined-deep';
+export type {UndefinedOnPartialDeep} from './source/undefined-on-partial-deep';
 export type {ReadonlyDeep} from './source/readonly-deep';
 export type {LiteralUnion} from './source/literal-union';
 export type {Promisable} from './source/promisable';
@@ -81,6 +83,7 @@ export type {WritableKeysOf} from './source/writable-keys-of';
 export type {HasWritableKeys} from './source/has-writable-keys';
 export type {Spread} from './source/spread';
 export type {TupleToUnion} from './source/tuple-to-union';
+export type {IntRange} from './source/int-range';
 export type {IsEqual} from './source/is-equal';
 export type {
 	IsLiteral,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "4.3.3",
+	"version": "4.5.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -15,7 +15,8 @@
 		"node": ">=16"
 	},
 	"scripts": {
-		"test": "xo && tsd && tsc && node script/test/source-files-extension.js"
+		"test": "xo && tsd && tsc && npm run test:undefined-on-partial-deep && node script/test/source-files-extension.js",
+		"test:undefined-on-partial-deep": "cd test-d/undefined-on-partial-deep && tsc --project tsconfig.json"
 	},
 	"files": [
 		"index.d.ts",

package/readme.md

@@ -129,6 +129,7 @@ Click the type names for complete docs.
 - [`PickIndexSignature`](source/pick-index-signature.d.ts) - Pick only index signatures from the given object type, leaving out all explicitly defined properties.
 - [`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.
 - [`PartialOnUndefinedDeep`](source/partial-on-undefined-deep.d.ts) - Create a deep version of another type where all keys accepting `undefined` type are set to optional.
+- [`UndefinedOnPartialDeep`](source/undefined-on-partial-deep.d.ts) - Create a deep version of another type where all optional keys are set to also accept `undefined`.
 - [`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).
 - [`Tagged`](source/opaque.d.ts) - Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d) that can support [multiple tags](https://github.com/sindresorhus/type-fest/issues/665) if needed.
@@ -159,6 +160,7 @@ Click the type names for complete docs.
 - [`Schema`](source/schema.d.ts) - Create a deep version of another object type where property values are recursively replaced into a given value type.
 - [`Exact`](source/exact.d.ts) - Create a type that does not allow extra properties.
 - [`OptionalKeysOf`](source/optional-keys-of.d.ts) - Extract all optional keys from the given type.
+- [`KeysOfUnion`](source/keys-of-union.d.ts) - Create a union of all keys from a given type, even those exclusive to specific union members.
 - [`HasOptionalKeys`](source/has-optional-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any optional fields.
 - [`RequiredKeysOf`](source/required-keys-of.d.ts) - Extract all required keys from the given type.
 - [`HasRequiredKeys`](source/has-required-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any required fields.
@@ -169,6 +171,7 @@ Click the type names for complete docs.
 - [`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.
+- [`IntRange`](source/int-range.d.ts) - Generate a union of numbers.
 
 ### Type Guard
 
@@ -293,13 +296,14 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 
 *If you know one of our types by a different name, add it here for discovery.*
 
-- `Prettify`- See [`Simplify`](https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts)
-- `Expand`- See [`Simplify`](https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts)
-- `PartialBy` - See [`SetOptional`](https://github.com/sindresorhus/type-fest/blob/main/source/set-optional.d.ts)
-- `RecordDeep`- See [`Schema`](https://github.com/sindresorhus/type-fest/blob/main/source/schema.d.ts)
-- `Mutable`- See [`Writable`](https://github.com/sindresorhus/type-fest/blob/main/source/writable.d.ts)
-- `RequireOnlyOne` - See [`RequireExactlyOne`](https://github.com/sindresorhus/type-fest/blob/main/source/require-exactly-one.d.ts)
-- `AtMostOne` - See [`RequireOneOrNone`](https://github.com/sindresorhus/type-fest/blob/main/source/require-one-or-none.d.ts)
+- `Prettify`- See [`Simplify`](source/simplify.d.ts)
+- `Expand`- See [`Simplify`](source/simplify.d.ts)
+- `PartialBy` - See [`SetOptional`](source/set-optional.d.ts)
+- `RecordDeep`- See [`Schema`](source/schema.d.ts)
+- `Mutable`- See [`Writable`](source/writable.d.ts)
+- `RequireOnlyOne` - See [`RequireExactlyOne`](source/require-exactly-one.d.ts)
+- `AtMostOne` - See [`RequireOneOrNone`](source/require-one-or-none.d.ts)
+- `AllKeys` - See [`KeysOfUnion`](source/keys-of-union.d.ts)
 
 ## Tips
 

package/source/exact.d.ts

@@ -1,6 +1,7 @@
-import type {KeysOfUnion, ArrayElement, ObjectValue} from './internal';
+import type {ArrayElement, ObjectValue} from './internal';
 import type {Opaque, TagContainer} from './opaque';
 import type {IsEqual} from './is-equal';
+import type {KeysOfUnion} from './keys-of-union';
 
 /**
 Create a type from `ParameterType` and `InputType` and change keys exclusive to `InputType` to `never`.

package/source/int-range.d.ts

@@ -0,0 +1,52 @@
+import type {BuildTuple, Subtract} from './internal';
+
+/**
+Generate a union of numbers.
+
+The numbers are created from the given `Start` (inclusive) parameter to the given `End` (exclusive) parameter.
+
+You skip over numbers using the `Step` parameter (defaults to `1`). For example, `IntRange<0, 10, 2>` will create a union of `0 | 2 | 4 | 6 | 8`.
+
+Note: `Start` or `End` must smaller than `1000`.
+
+Use-cases:
+1. This can be used to define a set of valid input/output values. for example:
+	```
+	type Age = IntRange<0, 120>;
+	type FontSize = IntRange<10, 20>;
+	type EvenNumber = IntRange<0, 11, 2>; //=> 0 | 2 | 4 | 6 | 8 | 10
+	```
+2. This can be used to define random numbers in a range. For example, `type RandomNumber = IntRange<0, 100>;`
+
+@example
+```
+import type {IntRange} from 'type-fest';
+
+// Create union type `0 | 1 | ... | 9`
+type ZeroToNine = IntRange<0, 10>;
+
+// Create union type `100 | 200 | 300 | ... | 900`
+type Hundreds = IntRange<100, 901, 100>;
+```
+*/
+export type IntRange<Start extends number, End extends number, Step extends number = 1> = PrivateIntRange<Start, End, Step>;
+
+/**
+The actual implementation of `IntRange`. It's private because it has some arguments that don't need to be exposed.
+*/
+type PrivateIntRange<
+	Start extends number,
+	End extends number,
+	Step extends number,
+	Gap extends number = Subtract<Step, 1>, // The gap between each number, gap = step - 1
+	List extends unknown[] = BuildTuple<Start, never>, // The final `List` is `[...StartLengthTuple, ...[number, ...GapLengthTuple], ...[number, ...GapLengthTuple], ... ...]`, so can initialize the `List` with `[...StartLengthTuple]`
+	EndLengthTuple extends unknown[] = BuildTuple<End>,
+> = Gap extends 0 ?
+	// Handle the case that without `Step`
+	List['length'] extends End // The result of "List[length] === End"
+		? Exclude<List[number], never> // All unused elements are `never`, so exclude them
+		: PrivateIntRange<Start, End, Step, Gap, [...List, List['length'] ]>
+	// Handle the case that with `Step`
+	: List extends [...(infer U), ...EndLengthTuple] // The result of "List[length] >= End", because the `...BuildTuple<Gap, never>` maybe make `List` too long.
+		? Exclude<List[number], never>
+		: PrivateIntRange<Start, End, Step, Gap, [...List, List['length'], ...BuildTuple<Gap, never>]>;

package/source/internal.d.ts

@@ -14,13 +14,15 @@ Infer the length of the given array `<T>`.
 type TupleLength<T extends readonly unknown[]> = T extends {readonly length: infer L} ? L : never;
 
 /**
-Create a tuple type of the given length `<L>`.
+Create a tuple type of the given length `<L>` and fill it with the given type `<Fill>`.
+
+If `<Fill>` is not provided, it will default to `unknown`.
 
 @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}
+export type BuildTuple<L extends number, Fill = unknown, T extends readonly unknown[] = []> = T extends {readonly length: L}
 	? T
-	: BuildTuple<L, [...T, unknown]>;
+	: BuildTuple<L, Fill, [...T, Fill]>;
 
 /**
 Create a tuple of length `A` and a tuple composed of two other tuples,
@@ -37,15 +39,6 @@ Matches any primitive, `Date`, or `RegExp` value.
 */
 export type BuiltIns = Primitive | Date | RegExp;
 
-/**
-Gets keys from a type. Similar to `keyof` but this one also works for union types.
-
-The reason a simple `keyof Union` does not work is because `keyof` always returns the accessible keys of a type. In the case of a union, that will only be the common keys.
-
-@link https://stackoverflow.com/a/49402091
-*/
-export type KeysOfUnion<T> = T extends T ? keyof T : never;
-
 export type UpperCaseCharacters = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
 
 export type StringDigit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';

package/source/jsonify.d.ts

@@ -96,24 +96,24 @@ export type Jsonify<T> = IsAny<T> extends true
 		? 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
+			: // 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 NotJsonable
+										? never // Non-JSONable type union was found not empty
 										: T extends []
 											? []
 											: T extends unknown[]

package/source/keys-of-union.d.ts

@@ -0,0 +1,40 @@
+/**
+Create a union of all keys from a given type, even those exclusive to specific union members.
+
+Unlike the native `keyof` keyword, which returns keys present in **all** union members, this type returns keys from **any** member.
+
+@link https://stackoverflow.com/a/49402091
+
+@example
+```
+import type {KeysOfUnion} from 'type-fest';
+
+type A = {
+	common: string;
+	a: number;
+};
+
+type B = {
+	common: string;
+	b: string;
+};
+
+type C = {
+	common: string;
+	c: boolean;
+};
+
+type Union = A | B | C;
+
+type CommonKeys = keyof Union;
+//=> 'common'
+
+type AllKeys = KeysOfUnion<Union>;
+//=> 'common' | 'a' | 'b' | 'c'
+```
+
+@category Object
+*/
+export type KeysOfUnion<ObjectType> = ObjectType extends unknown
+	? keyof ObjectType
+	: never;

package/source/override-properties.d.ts

@@ -25,5 +25,12 @@ type Fizz = OverrideProperties<Foo, {b: number; c: number}>
 */
 export type OverrideProperties<
 	TOriginal,
-	TOverride extends {[Key in keyof TOverride]: Key extends keyof TOriginal ? TOverride[Key] : never},
+	// This first bit where we use `Partial` is to enable autocomplete
+	// and the second bit with the mapped type is what enforces that we don't try
+	// to override properties that doesn't exist in the original type.
+	TOverride extends Partial<Record<keyof TOriginal, unknown>> & {
+		[Key in keyof TOverride]: Key extends keyof TOriginal
+			? TOverride[Key]
+			: never;
+	},
 > = Merge<TOriginal, TOverride>;

package/source/undefined-on-partial-deep.d.ts

@@ -0,0 +1,81 @@
+import type {BuiltIns} from './internal';
+import type {Merge} from './merge';
+
+/**
+Create a deep version of another type where all optional keys are set to also accept `undefined`.
+
+Note: This is only needed when the [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) TSConfig setting is enabled.
+
+Use-cases:
+- When `exactOptionalPropertyTypes` is enabled, an object like `{a: undefined}` is not assignable to the type `{a?: number}`. You can use `UndefinedOnPartialDeep<{a?: number}>` to make it assignable.
+
+@example
+```
+import type {UndefinedOnPartialDeep} from 'type-fest';
+
+interface Settings {
+	optionA: string;
+	optionB?: number;
+	subOption: {
+		subOptionA: boolean;
+		subOptionB?: boolean;
+	}
+};
+
+const testSettingsA: Settings = {
+	optionA: 'foo',
+	optionB: undefined, // TypeScript error if `exactOptionalPropertyTypes` is true.
+	subOption: {
+		subOptionA: true,
+		subOptionB: undefined, // TypeScript error if `exactOptionalPropertyTypes` is true
+	},
+};
+
+const testSettingsB: UndefinedOnPartialDeep<Settings> = {
+	optionA: 'foo',
+	optionB: undefined, // 👉 `optionB` can be set to undefined now.
+	subOption: {
+		subOptionA: true,
+		subOptionB: undefined, // 👉 `subOptionB` can be set to undefined now.
+	},
+};
+```
+*/
+export type UndefinedOnPartialDeep<T> =
+	// Handle built-in type and function
+	T extends BuiltIns | Function
+		? T
+		// Handle tuple and array
+		: T extends readonly unknown[]
+			? UndefinedOnPartialList<T>
+			// Handle map and readonly map
+			: T extends Map<infer K, infer V>
+				? Map<K, UndefinedOnPartialDeep<V>>
+				: T extends ReadonlyMap<infer K, infer V>
+					? ReadonlyMap<K, UndefinedOnPartialDeep<V>>
+					// Handle set and readonly set
+					: T extends Set<infer K>
+						? Set<UndefinedOnPartialDeep<K>>
+						: T extends ReadonlySet<infer K>
+							? ReadonlySet<UndefinedOnPartialDeep<K>>
+							// Handle object
+							: T extends Record<any, any>
+								? {
+									[KeyType in keyof T]: undefined extends T[KeyType]
+										? UndefinedOnPartialDeep<T[KeyType]> | undefined
+										: UndefinedOnPartialDeep<T[KeyType]>
+								}
+								: T; // If T is not builtins / function / array / map / set / object, return T
+
+// Handle tuples and arrays
+type UndefinedOnPartialList<T extends readonly unknown[]> = T extends []
+	? []
+	: T extends [infer F, ...infer R]
+		? [UndefinedOnPartialDeep<F>, ...UndefinedOnPartialDeep<R>]
+		: T extends readonly [infer F, ...infer R]
+			? readonly [UndefinedOnPartialDeep<F>, ...UndefinedOnPartialDeep<R>]
+			: T extends Array<infer F>
+				? Array<UndefinedOnPartialDeep<F>>
+				: T extends ReadonlyArray<infer F>
+					? ReadonlyArray<UndefinedOnPartialDeep<F>>
+					: never;

package/source/union-to-intersection.d.ts

@@ -56,5 +56,6 @@ export type UnionToIntersection<Union> = (
 		// Infer the `Intersection` type since TypeScript represents the positional
 		// arguments of unions of functions as an intersection of the union.
 ) extends ((mergedIntersection: infer Intersection) => void)
-	? Intersection
+	// The `& Union` is to allow indexing by the resulting type
+	? Intersection & Union
 	: never;