type-fest
Version:
A collection of essential TypeScript types
145 lines (122 loc) • 4.77 kB
TypeScript
import type {UnknownCollection} from './unknown-collection.d.ts';
import type {NonRecursiveType, SimplifyObject} from './internal/index.d.ts';
import type {ReadonlyKeysOf} from './readonly-keys-of.d.ts';
import type {KeysOfUnion} from './keys-of-union.d.ts';
import type {SharedUnionFields} from './shared-union-fields.d.ts';
import type {ValueOf} from './value-of.d.ts'; // For `@link`
import type {StringToNumber} from './string-to-number.d.ts';
import type {IsNumericLiteral} from './is-numeric-literal.d.ts';
/**
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.
- You want to merge the values of an object into one object type.
@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`.
// @ts-expect-error
console.log('animal type:', petInfo.catType ?? petInfo.dogType);
}
function displayPetInfoWithAllUnionFields(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);
}
```
Combine it with {@link ValueOf} to merge the values of an object. A key that is in every value is required, and a key that is in only some of the values is optional.
@example
```
import type {AllUnionFields, ValueOf} from 'type-fest';
const steps = {
install: {title: 'Install the app'},
login: {title: 'Log in', description: 'Use your GitHub account'},
finish: {title: 'Done'},
};
type Step = AllUnionFields<ValueOf<typeof steps>>;
//=> {title: string; description?: string}
```
Note: If one union member has a string enum key and another member has a plain string key with the same value, that field is left out of the result. Use the same spelling in every member.
@see {@link SharedUnionFields}
@category Object
@category Union
*/
export type AllUnionFields<Union> =
Extract<Union, NonRecursiveType | UnknownCollection> extends infer SkippedMembers
? NormalizeNumericKeys<Exclude<Union, SkippedMembers>> extends infer RelevantMembers
? // eslint-disable-line @stylistic/operator-linebreak
| SkippedMembers
| SimplifyObject<
// Include fields that are common in all union members
SharedUnionFields<RelevantMembers>
// Include readonly fields present in any union member
& {
readonly [P in ReadonlyKeysOf<Extract<RelevantMembers, object>>]?: FieldValue<RelevantMembers, P>
}
// Include remaining fields that are neither common nor readonly
& {
[P in Exclude<KeysOfUnion<RelevantMembers>, ReadonlyKeysOf<Extract<RelevantMembers, object>> | keyof RelevantMembers>]?: FieldValue<RelevantMembers, P>
}
>
: never
: never;
/**
Get the values of the members that have the given key. Unlike `ValueOf`, a broad key, like `string`, reads only the members whose index signatures cover it and not the named properties it covers, so each index signature of the result keeps the values of its own index domain.
*/
type FieldValue<Union, Key extends PropertyKey> =
Union extends unknown
? Key extends keyof Union ? Union[Key] : never
: never;
/**
Use an existing numeric key for its exact canonical string spelling, so merging cannot drop duplicate aliases. Leave other unions as is to preserve index signatures.
*/
type NormalizeNumericKeys<Union, AllKeys extends PropertyKey = KeysOfUnion<Union>> =
IsNumericLiteral<ExistingNumericKey<AllKeys, AllKeys>> extends true
? Union extends unknown
? {[Key in keyof Union as
ExistingNumericKey<Key, AllKeys> extends infer NumericKey extends number
? NumericKey | Exclude<Key, `${NumericKey}`>
: never
]: Union[Key]}
: never
: Union;
/**
Get the key in `AllKeys` that the numeric string spelling `Key` names. A `number` index signature covers every numeric key.
*/
type ExistingNumericKey<Key, AllKeys> =
StringToNumber<Extract<Key, `${number}`>> extends infer NumberKey
// Compare the string spellings, because `number` is assignable to a numeric enum.
? `${number}` extends `${AllKeys & number}` ? NumberKey : Extract<AllKeys, NumberKey>
: never;
export {};