Improve typings by using function overloads

The Typescript signatures are sometimes too loose and unnecessarily hard to use. Take getLocation as an example:

export default function getLocation(this: WebdriverIO.Element, prop?: 'x' | 'y'): Promise<number | {
    x: number;
    y: number;
}>;

This is hard to use because the return type is not bound to the input type. I have to do a type cast which should not be needed.

Describe the solution you’d like This could be easily solved by using overload signatures like this:

export function getLocation(this: WebdriverIO.Element): Promise<{
    x: number;
    y: number;
}>
export function getLocation(this: WebdriverIO.Element, prop: 'x' | 'y'): Promise<number>
function getLocation(this: WebdriverIO.Element, prop?: 'x' | 'y'): Promise<number | {
    x: number;
    y: number;
}> {
   // Implementation does not need to change ...
}

Additional context

This is just an example that - together with getSize - jumped me right in the face while updating our codebase to WebdriverIO 7.

[azygis]

Apparently I am also working on the same issue that @iamkenos works on and created a draft-ish PR #6555. ~I don’t really see the problem that you have - there is no need to “redeclare” the functions other than having the overloads themselves~.

I will drop my pull request later ~, but you can take a look at the code there I suppose, it does imply the correct return type based on argument type~.

Edit: nevermind, I did not see the “drop promise for sync variants”. It does indeed need the redeclare since same arguments can’t have multiple return types.

[christian-bromann]

Looks good, feel free to open a PR. Too bad this can’t be referred automatically from the file and a redeclaration is necessary but I guess we have a very special case offering an API in async and sync mode.