UNPKG

type-fest

Version:

A collection of essential TypeScript types

70 lines (51 loc) • 3.79 kB
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 {};