type-fest
Version:
A collection of essential TypeScript types
70 lines (51 loc) • 3.79 kB
TypeScript
import type {IsEqual} from '../is-equal.d.ts';
import type {IsUnknown} from '../is-unknown.d.ts';
import type {UnknownArray} from '../unknown-array.d.ts';
/*
Internal documentation: TypeScript's overload enumeration behavior
========================================================================
Understanding how TypeScript enumerates overloads from an intersection type is essential for understanding (and correctly using) `Overloads`.
## Overload enumeration
Given an intersection of function types (e.g. `F1 & F2 & F3`), TypeScript builds an overload list by scanning left to right and **deduplicating**:
- Two overloads with the same (This, Parameters, Return) are considered duplicates. The first one wins; later ones are dropped.
- HOWEVER, if one or both of the overloads has **implicit `this`** (i.e. no `this` annotation), the comparison ignores `This` and only checks (Parameters, Return). This means an implicit-`this` overload and an explicit-`this` overload with the same params/return are considered duplicates, and whichever appears first wins.
Example (F1 = implicit this, F1wT<T> = explicit this: T, same params/return):
F1 & F1wT<1> & F1wT<2>
→ Enumerated as: [F1]
F1wT<1> has same (P,R) as F1 (implicit) → duplicate, dropped.
F1wT<2> likewise dropped.
F1wT<1> & F1 & F1wT<2>
→ Enumerated as: [F1wT<1>, F1wT<2>]
F1 has same (P,R) as F1wT<1>, and F1 is implicit → duplicate, dropped.
F1wT<2> vs F1wT<1>: both explicit, This differs → NOT duplicate, kept.
## Pattern matching: `X extends (this: T, ...args: P) => R`
TypeScript enumerates the overloads of X as above, replaces implicit `this` with `this: unknown`, then matches the **rightmost** overload satisfying the constraint on the right-hand side.
*/
declare const unique: unique symbol;
type Unique = typeof unique;
/**
Detect whether an overload with the given (This, Parameters, Return) has an explicit `this` annotation in the original function type.
Intersects `(this: Unique, ...arguments_: Parameters_) => Return` onto the function type from the right. Per TypeScript's deduplication rules (see "Overload enumeration" above), implicit `this` absorbs the sentinel (same (P,R) and one is implicit, so the first one wins), so `ThisParameterType` stays `unknown`. Explicit `this: unknown` does not absorb it (both are explicit and `This` differs, so they are not duplicates), so the sentinel becomes the last overload and `ThisParameterType` returns `Unique`.
Limitation: This does not work for generic overloads. There is no way to extract a generic overload while preserving its type parameters, so this type receives the already-instantiated (concrete) signature and cannot recover the original `this` annotation. As a result, generic overloads always appear with explicit `this: unknown` in the `Overloads` output.
*/
export type HasExplicitThis<
FunctionType extends (...arguments_: any) => any,
This,
Parameters_ extends UnknownArray,
Return,
> = IsUnknown<This> extends true
? IsEqual<ThisParameterType<FunctionType & ((this: Unique, ...arguments_: Parameters_) => Return)>, Unique>
: true;
/**
Join the given function types, in order, into one overloaded function type. `never` elements are skipped, and the result is `never` when no element remains.
The order matters, because overload resolution uses the first matching signature.
@example
```ts
type A = JoinOverloads<[(value: string) => 1, never, (value: number) => 2]>;
//=> ((value: string) => 1) & ((value: number) => 2)
```
*/
export type JoinOverloads<Functions extends UnknownArray, Result = unknown> = Functions extends readonly [infer First, ...infer Rest]
? JoinOverloads<Rest, [First] extends [never] ? Result : Result & First>
: unknown extends Result ? never : Result;
export {};