Middleware type definitions don’t match actual API

[Jaid]

It’s currently not that easy to write middlewares in TypeScript, because the actual API and exported types seem to be out of sync.

---

This is a legitimate Yargs middleware:

type MiddlewareFunction = (args: ArgumentsCamelCase, yargs: YargsInstance) => Record<string, unknown>

Which can be verified by looking directly at the API code.

yargs/lib/middleware.ts

Lines 111 to 114 in e517318

	const result = middleware(acc, yargs);
	return isPromise(result)
	? result.then(middlewareObj => Object.assign(acc, middlewareObj))
	: Object.assign(acc, result);

However, this is the corresponding type definition I am consuming:

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/3a6d407361cc6025d136ae5eb3c3e3e24ada5009/types/yargs/v16/index.d.ts#L838

---

The problems with that:

• The second parameter of MiddlewareFunction is not documented.
• Type YargsInstance doesn’t seem to be accessible.
• The callback return type is void, but the API user can actually decide between modifying the original args (args.foo = 'bar'; return) and letting Yargs do the merging (const changes = {}; changes.foo = 'bar'; return changes).

[shadowspawn]

The types available for client use are from DefinitelyTyped, and maintained separately. You might want to open an issue/discussion over there too.

For comparison, the definition used internally in yargs is:

yargs/lib/middleware.ts

Lines 121 to 125 in e517318

	export interface MiddlewareCallback {
	(argv: Arguments, yargs: YargsInstance):
	| Partial<Arguments>
	| Promise<Partial<Arguments>>;
	}

And for interest related to the internal typings: #1751