type-fest
Version:
A collection of essential TypeScript types
73 lines (55 loc) • 3.16 kB
TypeScript
import type {IsAny} from './is-any.d.ts';
import type {ExcludeRestElement} from './exclude-rest-element.d.ts';
import type {TupleOf} from './tuple-of.d.ts';
import type {AnyFunction} from './basic.d.ts';
import type {FunctionParameters} from './function-parameters.d.ts';
/**
Require a function to have at least the given number of required parameters.
TypeScript accepts a function with fewer parameters where a function with more parameters is expected, because a function can ignore the arguments it gets. This is usually what you want, but not when a callback is pointless without its parameters.
Use-cases:
- Require a `sort` comparator to declare both of its parameters.
- Require an async effect callback to declare its `isMounted` parameter.
The result is the given function if it has at least `Count` (default: `1`) required parameters, and `never` if not. It must wrap a type parameter that is inferred from the argument and whose constraint has at least `Count` required parameters, like `callback: RequireArity<Callback>`, because a plain function type cannot reject a function with fewer parameters. With a weaker constraint, an inline callback gets no parameter types and is rejected.
Optional parameters and rest parameters with an array type are not counted. A parameter with a default value is optional, so it is not counted either, unless a required parameter comes after it.
@example
```
import type {RequireArity} from 'type-fest';
declare function useAsyncEffect<Callback extends (isMounted: () => boolean) => Promise<void>>(callback: RequireArity<Callback>): void;
useAsyncEffect(async isMounted => {
await Promise.resolve();
if (isMounted()) {
console.log('Still mounted');
}
});
// OK
// @ts-expect-error
useAsyncEffect(async () => {
await Promise.resolve();
});
// Error: Argument of type '() => Promise<void>' is not assignable to parameter of type 'never'.
```
@example
```
import type {RequireArity} from 'type-fest';
declare function sortNumbers<Compare extends (a: number, b: number) => number>(compare: RequireArity<Compare, 2>): void;
sortNumbers((a, b) => a - b);
// OK
// @ts-expect-error
sortNumbers(a => a);
// Error: Argument of type '(a: number) => number' is not assignable to parameter of type 'never'.
```
Note:
- This only checks that the parameters are declared, not that they are used. For example, an `isMounted` parameter that is never read is accepted. Use the `noUnusedParameters` compiler option or a lint rule for that.
- An overloaded function is checked by its last signature only, due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732).
@category Function
*/
export type RequireArity<Function_ extends AnyFunction, Count extends number = 1> =
IsAny<Function_> extends true
? Function_
: FunctionParameters<Function_> extends readonly [...TupleOf<Count>, ...unknown[]]
? Function_
// Required tuple parameters after a rest element do not match a required prefix, but still contribute to the arity.
: ExcludeRestElement<FunctionParameters<Function_>> extends readonly [...TupleOf<Count>, ...unknown[]]
? Function_
: never;
export {};