type-fest
Version:
A collection of essential TypeScript types
156 lines (130 loc) • 7.64 kB
TypeScript
import type {CallSignatureOf, KeyAliases, SimplifyObject} from './internal/index.d.ts';
import type {IsReadonlyArray} from './is-readonly-array.d.ts';
import type {OmitIndexSignature} from './omit-index-signature.d.ts';
import type {PickIndexSignature} from './pick-index-signature.d.ts';
import type {If} from './if.d.ts';
import type {IsEqual} from './is-equal.d.ts';
import type {IsAny} from './is-any.d.ts';
import type {ObjectMerge} from './object-merge.d.ts'; // For `@link`
import type {Spread} from './spread.d.ts'; // For `@link`
import type {MergeAll} from './merge-all.d.ts'; // For `@link`
import type {Modify} from './modify.d.ts'; // For `@link`
/**
Merge two types into a new type. Keys of the second type override keys of the first type.
This is different from the TypeScript `&` (intersection) operator. With `&`, conflicting property types are intersected, which often results in `never`. For example, `{a: string} & {a: number}` makes `a` become `string & number`, which resolves to `never`. With `Merge`, the second type's keys cleanly override the first, so `Merge<{a: string}, {a: number}>` gives `{a: number}` as expected. `Merge` also produces a flattened type (via `Simplify`), making it more readable in IDE tooltips compared to `A & B`.
@example
```
import type {Merge} from 'type-fest';
type Foo = {
a: string;
b: number;
};
type Bar = {
a: number; // Conflicts with Foo['a']
c: boolean;
};
// With `&`, `a` becomes `string & number` which is `never`. Not what you want.
type WithIntersection = (Foo & Bar)['a'];
//=> never
// With `Merge`, `a` is cleanly overridden to `number`.
type WithMerge = Merge<Foo, Bar>['a'];
//=> number
```
@example
```
import type {Merge} from 'type-fest';
type Foo = {
[x: string]: unknown;
[x: number]: unknown;
foo: string;
bar: symbol;
};
type Bar = {
[x: number]: number;
[x: symbol]: unknown;
bar: Date;
baz: boolean;
};
export type FooBar = Merge<Foo, Bar>;
//=> {
// [x: string]: unknown;
// [x: number]: number;
// [x: symbol]: unknown;
// foo: string;
// bar: Date;
// baz: boolean;
// }
```
Note: If you want a merge type that more accurately reflects the runtime behavior of object spread or `Object.assign`, refer to the {@link ObjectMerge} type.
Use {@link MergeAll} to merge more than two types.
Use {@link Modify} to also remove keys: a key of the source with the `never` type removes that key from the result.
Two tuples are combined position by position, so `Merge<[1, 2, 3], [4, 5]>` is `[4, 5, 3]`. Use {@link Spread} to append them instead.
A call signature is kept: the source's if it has one, otherwise the destination's.
Numeric keys and their string forms name the same property, so `Merge<{0: string}, {'0': number}>` is `{'0': number}`.
Known limitations:
- Inside a generic function, a value such as `{...a, ...b}` (typed as `A & B`) is not assignable to `Merge<A, B>`, because TypeScript cannot resolve `Merge` until `A` and `B` are known. Use a type assertion: `{...a, ...b} as unknown as Merge<A, B>`.
- The kept call signature is rebuilt, so an overloaded function keeps only its last signature, a generic function loses its type parameters, and a type predicate becomes `boolean`. A construct signature is dropped.
@see {@link ObjectMerge}
@see {@link MergeAll}
@category Object
*/
export type Merge<Destination, Source> =
Destination extends unknown // For distributing `Destination`
? Source extends unknown // For distributing `Source`
? If<
IsEqual<Destination, Source>,
Destination,
// Two arrays or tuples are combined position by position, see `CombineTwoArrays`.
Destination extends readonly unknown[]
? Source extends readonly unknown[]
// `any` takes both branches of an array check, so the array branch is dropped when either side is `any` to leave just the object merge. A union with `any` is `any`, so this checks both sides at once.
? IsAny<Destination | Source> extends true
? never
: CombineTwoArrays<Destination, Source>
: _Merge<Destination, Source>
: _Merge<Destination, Source>
>
: never // Should never happen
: never; // Should never happen
/**
Combines two arrays position by position: the source's elements override the destination's, and the destination's positions past the source are kept, so `Merge<[1, 2, 3], [4, 5]>` is `[4, 5, 3]`. An array of unknown length has no positions to override, so the result is an array of both element types.
Note that this is not what either built-in spread does. The array spread of `[1, 2, 3]` and `[4, 5]` appends, giving `[1, 2, 3, 4, 5]`, and the object spread of the two gives a plain object `{0: 4, 1: 5, 2: 3}` with no `length`. This follows {@link Merge}'s own rule that the source's keys override the destination's keys, applied to the index keys a tuple has. Use {@link Spread} instead when the array spread is what you want.
*/
type CombineTwoArrays<Destination extends readonly unknown[], Source extends readonly unknown[]> =
// A source with an optional element has no fixed positions to override, so it is treated like an array of unknown length.
number extends Destination['length'] | Source['length'] | (Source extends Required<Source> ? never : number)
? IsReadonlyArray<Destination> extends true
? IsReadonlyArray<Source> extends true
? ReadonlyArray<Destination[number] | Source[number]>
: Array<Destination[number] | Source[number]>
: Array<Destination[number] | Source[number]>
: IsReadonlyArray<Destination> extends true
? IsReadonlyArray<Source> extends true
? readonly [...Source, ...DropLeading<Destination, Source['length']>]
: [...Source, ...DropLeading<Destination, Source['length']>]
: [...Source, ...DropLeading<Destination, Source['length']>];
/**
The elements of an array once the given number of leading ones is removed. An optional element counts as a position too.
*/
type DropLeading<Array extends readonly unknown[], Length extends number, Dropped extends unknown[] = []> =
Dropped['length'] extends Length
? Array
: Array extends readonly []
? []
: Array extends readonly [unknown?, ...infer Rest]
? DropLeading<Rest, Length, [...Dropped, unknown]>
: [];
export type _Merge<Destination, Source> =
// The mapped types in `MergeObjects` drop call signatures, so the source's call signature, or else the destination's, is added back. Each branch has its own intersection, so that tooltips show the result rather than `_Merge`.
unknown extends CallSignatureOf<Source>
? CallSignatureOf<Destination> & MergeObjects<Destination, Source>
: CallSignatureOf<Source> & MergeObjects<Destination, Source>;
// Numeric properties, enum keys, and their string forms name the same property, so normalize the source's named keys before testing overrides.
// Merges the properties and index signatures of two objects. A key of the destination is dropped when the source overrides it: an index signature only by an index signature, and a property only by a property. The destination is read only once, because each extra read multiplies the work of nested merges, such as in `MergeAll`. The source is rebuilt with key remapping instead of intersected as is, because an intersection with an `any` source is `any`, which loses the properties of the destination.
type MergeObjects<Destination, Source> = SimplifyObject<{
[Key in keyof Destination as {} extends Record<Key, never>
? Key extends keyof PickIndexSignature<Source> ? never : Key
: Key extends KeyAliases<keyof OmitIndexSignature<Source>> ? never : Key
]: Destination[Key];
} & {[Key in keyof Source as Key]: Source[Key]}>;
export {};