type-fest 4.33.0 → 4.34.0

package/index.d.ts

@@ -130,6 +130,7 @@ export type {ArraySplice} from './source/array-splice';
 export type {ArrayTail} from './source/array-tail';
 export type {SetFieldType} from './source/set-field-type';
 export type {Paths} from './source/paths';
+export type {AllUnionFields} from './source/all-union-fields';
 export type {SharedUnionFields} from './source/shared-union-fields';
 export type {SharedUnionFieldsDeep} from './source/shared-union-fields-deep';
 export type {IsNull} from './source/is-null';

package/package.json

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

package/readme.md

@@ -203,6 +203,7 @@ Click the type names for complete docs.
 - [`Paths`](source/paths.d.ts) - Generate a union of all possible paths to properties in the given object.
 - [`SharedUnionFields`](source/shared-union-fields.d.ts) - Create a type with shared fields from a union of object types.
 - [`SharedUnionFieldsDeep`](source/shared-union-fields-deep.d.ts) - Create a type with shared fields from a union of object types, deeply traversing nested structures.
+- [`AllUnionFields`](source/all-union-fields.d.ts) - Create a type with all fields from a union of object types.
 - [`DistributedOmit`](source/distributed-omit.d.ts) - Omits keys from a type, distributing the operation over a union.
 - [`DistributedPick`](source/distributed-pick.d.ts) - Picks keys from a type, distributing the operation over a union.
 - [`And`](source/and.d.ts) - Returns a boolean for whether two given types are both true.

package/source/all-union-fields.d.ts

@@ -0,0 +1,88 @@
+import type {NonRecursiveType, ReadonlyKeysOfUnion, ValueOfUnion} from './internal';
+import type {KeysOfUnion} from './keys-of-union';
+import type {SharedUnionFields} from './shared-union-fields';
+import type {Simplify} from './simplify';
+import type {UnknownArray} from './unknown-array';
+
+/**
+Create a type with all fields from a union of object types.
+
+Use-cases:
+- You want a safe object type where each key exists in the union object.
+
+@example
+```
+import type {AllUnionFields} from 'type-fest';
+
+type Cat = {
+	name: string;
+	type: 'cat';
+	catType: string;
+};
+
+type Dog = {
+	name: string;
+	type: 'dog';
+	dogType: string;
+};
+
+function displayPetInfo(petInfo: Cat | Dog) {
+	// typeof petInfo =>
+	// {
+	// 	name: string;
+	// 	type: 'cat';
+	// 	catType: string;
+	// } | {
+	// 	name: string;
+	// 	type: 'dog';
+	// 	dogType: string;
+	// }
+
+	console.log('name: ', petInfo.name);
+	console.log('type: ', petInfo.type);
+
+	// TypeScript complains about `catType` and `dogType` not existing on type `Cat | Dog`.
+	console.log('animal type: ', petInfo.catType ?? petInfo.dogType);
+}
+
+function displayPetInfo(petInfo: AllUnionFields<Cat | Dog>) {
+	// typeof petInfo =>
+	// {
+	// 	name: string;
+	// 	type: 'cat' | 'dog';
+	// 	catType?: string;
+	// 	dogType?: string;
+	// }
+
+	console.log('name: ', petInfo.name);
+	console.log('type: ', petInfo.type);
+
+	// No TypeScript error.
+	console.log('animal type: ', petInfo.catType ?? petInfo.dogType);
+}
+```
+
+@see SharedUnionFields
+
+@category Object
+@category Union
+*/
+export type AllUnionFields<Union> =
+Extract<Union, NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | UnknownArray> extends infer SkippedMembers
+	? Exclude<Union, SkippedMembers> extends infer RelevantMembers
+		?
+		| SkippedMembers
+		| Simplify<
+		// Include fields that are common in all union members
+		SharedUnionFields<RelevantMembers> &
+		// Include readonly fields present in any union member
+		{
+			readonly [P in ReadonlyKeysOfUnion<RelevantMembers>]?: ValueOfUnion<RelevantMembers, P & KeysOfUnion<RelevantMembers>>
+		} &
+		// Include remaining fields that are neither common nor readonly
+		{
+			[P in Exclude<KeysOfUnion<RelevantMembers>, ReadonlyKeysOfUnion<RelevantMembers> | keyof RelevantMembers>]?: ValueOfUnion<RelevantMembers, P>
+		}
+		>
+		: never
+	: never;

package/source/internal/object.d.ts

@@ -1,5 +1,6 @@
 import type {Simplify} from '../simplify';
 import type {UnknownArray} from '../unknown-array';
+import type {IsEqual} from '../is-equal';
 import type {KeysOfUnion} from '../keys-of-union';
 import type {FilterDefinedKeys, FilterOptionalKeys} from './keys';
 import type {NonRecursiveType} from './type';
@@ -122,3 +123,39 @@ type IndexSignature = HomomorphicPick<{[k: string]: unknown}, number>;
 export type HomomorphicPick<T, Keys extends KeysOfUnion<T>> = {
 	[P in keyof T as Extract<P, Keys>]: T[P]
 };
+
+/**
+Extract all possible values for a given key from a union of object types.
+
+@example
+```
+type Statuses = ValueOfUnion<{ id: 1, status: "open" } | { id: 2, status: "closed" }, "status">;
+//=> "open" | "closed"
+```
+*/
+export type ValueOfUnion<Union, Key extends KeysOfUnion<Union>> =
+	Union extends unknown ? Key extends keyof Union ? Union[Key] : never : never;
+
+/**
+Extract all readonly keys from a union of object types.
+
+@example
+```
+type User = {
+		readonly id: string;
+		name: string;
+};
+
+type Post = {
+		readonly id: string;
+		readonly author: string;
+		body: string;
+};
+
+type ReadonlyKeys = ReadonlyKeysOfUnion<User | Post>;
+//=> "id" | "author"
+```
+*/
+export type ReadonlyKeysOfUnion<Union> = Union extends unknown ? keyof {
+	[Key in keyof Union as IsEqual<{[K in Key]: Union[Key]}, {readonly [K in Key]: Union[Key]}> extends true ? Key : never]: never
+} : never;

package/source/omit-deep.d.ts

@@ -1,10 +1,10 @@
+import type {UnionToTuple} from 'expect-type';
 import type {ArraySplice} from './array-splice';
 import type {ExactKey, IsArrayReadonly, NonRecursiveType, SetArrayAccess, ToString} from './internal';
 import type {IsEqual} from './is-equal';
 import type {IsNever} from './is-never';
 import type {LiteralUnion} from './literal-union';
 import type {Paths} from './paths';
-import type {SharedUnionFieldsDeep} from './shared-union-fields-deep';
 import type {SimplifyDeep} from './simplify-deep';
 import type {UnknownArray} from './unknown-array';
 
@@ -92,11 +92,19 @@ type AddressInfo = OmitDeep<Info1, 'address.1.foo'>;
 */
 export type OmitDeep<T, PathUnion extends LiteralUnion<Paths<T>, string>> =
 	SimplifyDeep<
-	SharedUnionFieldsDeep<
-	{[P in PathUnion]: OmitDeepWithOnePath<T, P>}[PathUnion]
-	>,
+	OmitDeepHelper<T, UnionToTuple<PathUnion>>,
 	UnknownArray>;
 
+/**
+Internal helper for {@link OmitDeep}.
+
+Recursively transforms `T` by applying {@link OmitDeepWithOnePath} for each path in `PathTuple`.
+*/
+type OmitDeepHelper<T, PathTuple extends UnknownArray> =
+	PathTuple extends [infer Path, ...infer RestPaths]
+		? OmitDeepHelper<OmitDeepWithOnePath<T, Path & (string | number)>, RestPaths>
+		: T;
+
 /**
 Omit one path from the given object/array.
 */

package/source/paths.d.ts

@@ -50,11 +50,53 @@ export type PathsOptions = {
 	```
 	*/
 	bracketNotation?: boolean;
+
+	/**
+	Only include leaf paths in the output.
+
+	@default false
+
+	@example
+	```
+	type Post = {
+		id: number;
+		author: {
+			id: number;
+			name: {
+				first: string;
+				last: string;
+			};
+		};
+	};
+
+	type AllPaths = Paths<Post, {leavesOnly: false}>;
+	//=> 'id' | 'author' | 'author.id' | 'author.name' | 'author.name.first' | 'author.name.last'
+
+	type LeafPaths = Paths<Post, {leavesOnly: true}>;
+	//=> 'id' | 'author.id' | 'author.name.first' | 'author.name.last'
+	```
+
+	@example
+	```
+	type ArrayExample = {
+		array: Array<{foo: string}>;
+		tuple: [string, {bar: string}];
+	};
+
+	type AllPaths = Paths<ArrayExample, {leavesOnly: false}>;
+	//=> 'array' | `array.${number}` | `array.${number}.foo` | 'tuple' | 'tuple.0' | 'tuple.1' | 'tuple.1.bar'
+
+	type LeafPaths = Paths<ArrayExample, {leavesOnly: true}>;
+	//=> `array.${number}.foo` | 'tuple.0' | 'tuple.1.bar'
+	```
+	*/
+	leavesOnly?: boolean;
 };
 
 type DefaultPathsOptions = {
 	maxRecursionDepth: 10;
 	bracketNotation: false;
+	leavesOnly: false;
 };
 
 /**
@@ -103,6 +145,8 @@ export type Paths<T, Options extends PathsOptions = {}> = _Paths<T, {
 	maxRecursionDepth: Options['maxRecursionDepth'] extends number ? Options['maxRecursionDepth'] : DefaultPathsOptions['maxRecursionDepth'];
 	// Set default bracketNotation to false
 	bracketNotation: Options['bracketNotation'] extends boolean ? Options['bracketNotation'] : DefaultPathsOptions['bracketNotation'];
+	// Set default leavesOnly to false
+	leavesOnly: Options['leavesOnly'] extends boolean ? Options['leavesOnly'] : DefaultPathsOptions['leavesOnly'];
 }>;
 
 type _Paths<T, Options extends Required<PathsOptions>> =
@@ -142,11 +186,17 @@ type InternalPaths<T, Options extends Required<PathsOptions>> =
 						) extends infer TranformedKey extends string | number ?
 						// 1. If style is 'a[0].b' and 'Key' is a numberlike value like 3 or '3', transform 'Key' to `[${Key}]`, else to `${Key}` | Key
 						// 2. If style is 'a.0.b', transform 'Key' to `${Key}` | Key
-							| TranformedKey
+							| (Options['leavesOnly'] extends true
+								? MaxDepth extends 0
+									? TranformedKey
+									: T[Key] extends EmptyObject | readonly [] | NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
+										? TranformedKey
+										: never
+								: TranformedKey)
 							| (
 								// Recursively generate paths for the current key
 								GreaterThan<MaxDepth, 0> extends true // Limit the depth to prevent infinite recursion
-									? _Paths<T[Key], {bracketNotation: Options['bracketNotation']; maxRecursionDepth: Subtract<MaxDepth, 1>}> extends infer SubPath
+									? _Paths<T[Key], {bracketNotation: Options['bracketNotation']; maxRecursionDepth: Subtract<MaxDepth, 1>; leavesOnly: Options['leavesOnly']}> extends infer SubPath
 										? SubPath extends string | number
 											? (
 												Options['bracketNotation'] extends true

package/source/shared-union-fields.d.ts

@@ -59,6 +59,7 @@ function displayPetInfo(petInfo: SharedUnionFields<Cat | Dog>) {
 ```
 
 @see SharedUnionFieldsDeep
+@see AllUnionFields
 
 @category Object
 @category Union