assert: change callTracker.calls and callTracker.callsWith to use an object param instead of positional params

[ErickWendel]

What is the problem this feature will solve?

I've been implementing some features on the assert module see #43133 and I figured that it's a bit confusing for users to use the signature:

callTracker.calls()
callTracker.calls(1)
callTracker.calls(fn)
callTracker.calls(fn, 1)

callTracker.callsWith(['arg1'])
callTracker.callsWith(fn, ['arg1'])
callTracker.callsWith(fn, ['arg1'], 1)

When looking at the intelliSense, it's also confusing because the calls signature is calls(fn, exact = 1) however nether fn or exact are required fields so we have to check every positional argument see

node/lib/internal/assert/calltracker.js

Lines 38 to 57 in 71fc444

	// When calls([arg1, arg2], ?1)
	if (ArrayIsArray(fn)) {
	exact = typeof withArgs === 'number' ? withArgs : exact;
	withArgs = fn;
	fn = noop;
	}
	// When calls(1)
	if (typeof fn === 'number') {
	exact = fn;
	fn = noop;
	}
	// When calls()
	if (fn === undefined) {
	fn = noop;
	}
	// Else calls(fn, 1, [])
	validateUint32(exact, 'exact', true);

What is the feature you are proposing to solve the problem?

I'd like to propose that we use object destructuring for those function signatures as it could improve the editor's intelliSense and readability:

callTracker.calls({
  exact: 1,
  fn: myFn
})

callTracker.callsWith({
  withArgs: ['arg1']
})

What alternatives have you considered?

No response

[Trott]

@nodejs/assert @nodejs/testing

[Trott]

I'm not super-familiar with this API, but the suggestion for calls() to be calls(options) makes sense to me. For callsWith(), I wonder if we want callsWith(args, options).

[ErickWendel]

I'm not super-familiar with this API, but the suggestion for calls() to be calls(options) makes sense to me. For callsWith(), I wonder if we want callsWith(args, options).

I liked it! both calls(options) and callsWith(args, options) 🤩

Should I implement it?

[ErickWendel]

Should I? 😬

[jasnell]

I'd say go ahead