Add Overloads, OverloadParameters, OverloadReturnType

index.d.ts

@@ -69,6 +69,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

@@ -158,8 +158,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 represents the type of an entry of a collection.
 - [`Entries`](source/entries.d.ts) - Create a type that represents the type of the entries of a collection.
-- [`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.
@@ -246,6 +244,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.
+- [`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 and inferred as `unknown`.
+- 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 — 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,110 @@
+import type {IsAny} from '../is-any.d.ts';
+import type {IsEqual} from '../is-equal.d.ts';
+import type {IsUnknown} from '../is-unknown.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 — 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 the last overload of a function type has an explicit `this` annotation.
+
+Intersects `(this: Unique, ...)` from the right. Per TypeScript's deduplication rules
+(see "Overload enumeration" above), implicit `this` absorbs the sentinel (same (P,R) →
+duplicate, first-wins), so `ThisParameterType` stays `unknown`. Explicit `this: unknown`
+does not absorb it (both explicit, different `This` → not duplicate), so
+`ThisParameterType` returns `Unique`.
+*/
+type HasExplicitThis<T extends (...args: any) => any> =
+	IsUnknown<ThisParameterType<T>> extends true
+		? IsEqual<ThisParameterType<T & ((this: Unique, ...args: Parameters<T>) => ReturnType<T>)>, Unique> extends true
+			? true
+			: false
+		: true;
+
+/**
+Extract the last overload of a function type as a standalone function,
+correctly preserving implicit `this` (omitted) vs explicit `this` (kept).
+*/
+type LastOverload<T extends (...args: any) => any> =
+	HasExplicitThis<T> extends true
+		? (this: ThisParameterType<T>, ...args: Parameters<T>) => ReturnType<T>
+		: (...args: Parameters<T>) => ReturnType<T>;
+
+/**
+Extracts TypeScript's enumerated overload list into a tuple (see "Overload enumeration" above).
+
+Uses the intersection trick: intersecting `LastOverload<AllOverloads>` onto the left
+makes TypeScript's pattern matching skip it on the next iteration, effectively advancing
+through all overloads right to left. `LastOverload` preserves implicit-vs-explicit `this`
+via `HasExplicitThis`.
+
+The termination condition (`CheckedOverloads === PreviousCheckedOverloads`) lags by one
+iteration, so the last extracted overload is always a duplicate. We compensate by dropping
+the first element of the result tuple at termination.
+
+@see https://github.com/microsoft/TypeScript/issues/32164#issuecomment-1146737709
+*/
+export type CollectOverloads<
+	AllOverloads extends (...args: any) => any,
+	CheckedOverloads = unknown,
+	PreviousCheckedOverloads = never,
+	ResultOverloads extends Array<(...args: any) => any> = [],
+> =
+	IsEqual<CheckedOverloads, PreviousCheckedOverloads> extends true
+		? ResultOverloads extends [(...args: any) => any, ...infer Rest extends Array<(...args: any) => any>] ? Rest : []
+		: CollectOverloads<
+			// Intersecting one signature with the full type makes the compiler infer a different "last overload"
+			// each iteration, effectively iterating all overloads from bottom to top.
+			LastOverload<AllOverloads> & AllOverloads,
+			LastOverload<AllOverloads> & CheckedOverloads,
+			CheckedOverloads,
+			[LastOverload<AllOverloads>, ...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 {};