Add Overloads, OverloadParameters, OverloadReturnType

index.d.ts

@@ -70,6 +70,7 @@ export type {Entry} from './source/entry.d.ts';
 export type {Entries} from './source/entries.d.ts';
 export type {SetReturnType} from './source/set-return-type.d.ts';
 export type {SetParameterType} from './source/set-parameter-type.d.ts';
+export type {Overloads, OverloadParameters, OverloadReturnType} from './source/function-overloads.d.ts';
 export type {Asyncify} from './source/asyncify.d.ts';
 export type {Simplify} from './source/simplify.d.ts';
 export type {SimplifyDeep} from './source/simplify-deep.d.ts';

readme.md

@@ -159,8 +159,6 @@ Click the type names for complete docs.
 - [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, `Array`, `Set`, `Map`, generator, stream, etc.
 - [`Entry`](source/entry.d.ts) - Create a type that describes a single key-value pair produced when calling a collection’s `entries` method.
 - [`Entries`](source/entries.d.ts) - Create a type that describes the key-value pairs produced when calling a collection’s `entries` method.
-- [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
-- [`SetParameterType`](source/set-parameter-type.d.ts) - Create a function that replaces some parameters with the given parameters.
 - [`Simplify`](source/simplify.d.ts) - Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
 - [`SimplifyDeep`](source/simplify-deep.d.ts) - Deeply simplifies an object type.
 - [`Get`](source/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.
@@ -247,6 +245,14 @@ Click the type names for complete docs.
 
 - [`StructuredCloneable`](source/structured-cloneable.d.ts) - Matches a value that can be losslessly cloned using `structuredClone`.
 
+### Function
+
+- [`Overloads`](source/function-overloads.d.ts) - Extract all overload signatures of the given function type as a tuple, preserving declaration order.
+- [`OverloadParameters`](source/function-overloads.d.ts) - Extract the parameter types of all overloads as a union.
+- [`OverloadReturnType`](source/function-overloads.d.ts) - Extract the return types of all overloads as a union.
+- [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
+- [`SetParameterType`](source/set-parameter-type.d.ts) - Create a function that replaces some parameters with the given parameters.
+
 ### Async
 
 - [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.

source/function-overloads.d.ts

@@ -0,0 +1,92 @@
+import type {CollectOverloads} from './internal/index.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Extract all overload signatures of the given function type as a tuple, preserving declaration order.
+
+TypeScript's built-in utility types like `Parameters` and `ReturnType` only work with the last overload signature, [by design](https://github.com/microsoft/TypeScript/issues/32164). This type extracts all overload signatures, allowing you to work with each overload individually.
+
+Use-cases:
+- Extract parameter types from specific overloads using `Extract` and `Parameters`
+- Analyze all possible function signatures in type-level code
+- Extract event handler signatures from framework APIs
+
+Known limitations:
+- Generic type parameters are lost -- they are replaced by their upper bound (e.g. `<T>` becomes `unknown`, `<T extends string>` becomes `string`). Functions with fewer than 4 generic overloads are fully extracted; when there are 4 or more generic overloads, extraction stops at the 4th-from-last generic overload and any overloads before it are omitted.
+- TypeScript deduplicates overloads that share the same parameters and return type. When one has implicit `this` (no annotation) and another has explicit `this`, they are treated as duplicates, and whichever appears first in the intersection suppresses the other. See `source/internal/function.d.ts` for details on TypeScript's overload enumeration behavior.
+
+@example
+```
+import type {Overloads} from 'type-fest';
+
+declare function request(url: string): Promise<string>;
+declare function request(url: string, options: {json: true}): Promise<unknown>;
+
+type RequestOverloads = Overloads<typeof request>;
+//=> [(url: string) => Promise<string>, (url: string, options: {
+// 	json: true;
+// }) => Promise<unknown>]
+
+// To get a union instead of a tuple, index with [number]:
+type RequestOverloadsUnion = Overloads<typeof request>[number];
+//=> ((url: string) => Promise<string>) | ((url: string, options: {
+// 	json: true;
+// }) => Promise<unknown>)
+```
+
+@see https://github.com/microsoft/TypeScript/issues/14107
+@see https://github.com/microsoft/TypeScript/issues/32164
+
+@category Function
+*/
+export type Overloads<FunctionType extends (...args: any) => any> = FunctionType extends unknown
+	? IsAny<FunctionType> extends true
+		? [(...arguments_: any[]) => any]
+		: CollectOverloads<FunctionType>
+	: never;
+
+/**
+Extract the parameter types of all overloads as a union.
+
+This is the overload-aware counterpart to the built-in `Parameters` utility type, which only extracts from the last overload.
+
+@example
+```
+import type {OverloadParameters} from 'type-fest';
+
+declare function request(url: string): Promise<string>;
+declare function request(url: string, options: {json: true}): Promise<unknown>;
+
+type AllParameters = OverloadParameters<typeof request>;
+//=> [url: string] | [url: string, options: {json: true}]
+```
+
+Known limitations are the same as {@link Overloads}.
+
+@category Function
+*/
+export type OverloadParameters<FunctionType extends (...args: any) => any> = Parameters<Overloads<FunctionType>[number]>;
+
+/**
+Extract the return types of all overloads as a union.
+
+This is the overload-aware counterpart to the built-in `ReturnType` utility type, which only extracts from the last overload.
+
+@example
+```
+import type {OverloadReturnType} from 'type-fest';
+
+declare function request(url: string): Promise<string>;
+declare function request(url: string, options: {json: true}): Promise<unknown>;
+
+type AllReturnTypes = OverloadReturnType<typeof request>;
+//=> Promise<string> | Promise<unknown>
+```
+
+Known limitations are the same as {@link Overloads}.
+
+@category Function
+*/
+export type OverloadReturnType<FunctionType extends (...args: any) => any> = ReturnType<Overloads<FunctionType>[number]>;
+
+export {};

source/internal/function.d.ts

@@ -0,0 +1,112 @@
+import type {IntRange} from '../int-range.d.ts';
+import type {IsEqual} from '../is-equal.d.ts';
+import type {IsUnknown} from '../is-unknown.d.ts';
+import type {Sum} from '../sum.d.ts';
+import type {UnknownArray} from '../unknown-array.d.ts';
+
+/**
+Obtain the parameters of a function type in a tuple.
+
+This works even when the parameters type is a readonly array.
+*/
+export type Parameters<T extends (...args: any) => any> = T extends (...args: infer P extends UnknownArray) => any ? P : never;
+
+/*
+Internal documentation: TypeScript's overload enumeration behavior
+========================================================================
+
+Understanding how TypeScript enumerates overloads from an intersection type is essential for understanding (and correctly using) `CollectOverloads`.
+
+## 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, ...args: 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), one implicit -- first-wins), so `ThisParameterType` stays `unknown`. Explicit `this: unknown` does not absorb it (both explicit, different `This` -- not duplicate), so the sentinel becomes the last overload and `ThisParameterType` returns `Unique`.
+*/
+type HasExplicitThis<
+	FunctionType extends (...args: any) => any,
+	This, Parameters_ extends UnknownArray, Return,
+> = IsUnknown<This> extends true
+	? IsEqual<ThisParameterType<FunctionType & ((this: Unique, ...args: Parameters_) => Return)>, Unique>
+	: true;
+
+type MaxOverloadPatterns = 4;
+type OverloadIndex = IntRange<0, MaxOverloadPatterns>;
+/**
+Extract the Nth-from-last (N < MaxOverloadPatterns) overload of a function type as a standalone function, correctly preserving implicit `this` (omitted) vs explicit `this` (kept).
+
+F can contain a `() => Unique` sentinel (prepended by `CollectOverloads`).
+*/
+type NthLastOverload<F extends (...args: any) => any, N extends OverloadIndex> = F extends {
+	(this: infer T3, ...args: infer P3 extends UnknownArray): infer R3;
+	(this: infer T2, ...args: infer P2 extends UnknownArray): infer R2;
+	(this: infer T1, ...args: infer P1 extends UnknownArray): infer R1;
+	(this: infer T0, ...args: infer P0 extends UnknownArray): infer R0;
+}
+	? ({
+		3: [T3, P3, R3];
+		2: [T2, P2, R2];
+		1: [T1, P1, R1];
+		0: [T0, P0, R0];
+	}[N] extends [infer T, infer P extends UnknownArray, infer R]
+		? IsEqual<R, Unique> extends true
+			? undefined // No overload at this position
+			: HasExplicitThis<F, T, P, R> extends true
+				? (this: T, ...args: P) => R
+				: (...args: P) => R
+		: never)
+	: never;
+
+/**
+Extracts TypeScript's enumerated overload list into a tuple (see "Overload enumeration" above).
+
+`AllOverloads` defaults to `(() => Unique) & F`, prepending a `() => Unique` sentinel that marks the boundary of the original overloads. Each iteration extracts `NthLastOverload<AllOverloads, N>` and then checks whether intersecting the extracted overload onto `AllOverloads` changes what position N sees:
+
+- **Effect observed** (the two differ): the intersection advanced the view. Output `ExtractedN`, intersect it onto `AllOverloads`, and continue with the same N.
+- **No effect** (they are equal): the intersection would not advance the view (e.g. aliasing generic overloads that infer to the same concrete signature). Output `ExtractedN` without intersecting, and advance N to the next position.
+- **Sentinel hit** (`NthLastOverload` returns `undefined`): no original overload at this depth. Return the accumulated result.
+
+The loop terminates when either N exceeds `OverloadIndex` or the sentinel is reached.
+
+@see https://github.com/microsoft/TypeScript/issues/32164#issuecomment-1146737709
+*/
+export type CollectOverloads<
+	F extends (...args: any) => any,
+	AllOverloads extends (...args: any) => any = (() => Unique) & F,
+	N extends OverloadIndex = 0,
+	ResultOverloads extends Array<(...args: any) => any> = [],
+> = NthLastOverload<AllOverloads, N> extends infer ExtractedN extends (...args: any) => any
+	? IsEqual<NthLastOverload<ExtractedN & AllOverloads, N>, ExtractedN> extends true
+		? Sum<N, 1> extends infer NextN extends OverloadIndex
+			? CollectOverloads<F, AllOverloads, NextN, [ExtractedN, ...ResultOverloads]>
+			: [ExtractedN, ...ResultOverloads]
+		: CollectOverloads<F, ExtractedN & AllOverloads, N, [ExtractedN, ...ResultOverloads]>
+	: ResultOverloads;
+
+export {};

source/internal/index.d.ts

@@ -7,5 +7,6 @@ export type * from './string.d.ts';
 export type * from './tuple.d.ts';
 export type * from './type.d.ts';
 export type * from './enforce-optional.d.ts';
+export type * from './function.d.ts';
 
 export {};