style: Begin migration to TypeScript

[seanpoulter]

Proposed Changes

• Add TypeScript to check JavaScript
• Add nyc to check code coverage (to see what I can change with confidence)
• Add "build" script that can fail in the pipeline
• Add JSDoc comments to refine types
• Minor / low risk code changes

Notes

• I've pushed my WIP so there isn't a huge PR to review.
• There are still 16 problems reported by TypeScript.
• The type definitions could probably be extracted into a better spot. 🤔

Next Steps

• Add tests before changing the untested code
• Research how to resolve this issue with _handle not being defined. I'm not sure what to replace that with. 🤷

  test/only-driver-tests.js:97:21 - error TS2339: Property '_handle' does not exist on type 'ChildProcess'.
  assert(process1._handle);
  

[christian-bromann]

One comment, otherwise LGTM 👍

[christian-bromann]

Can we update this or remove?

[seanpoulter]

Of course! What direction would you like to take?

I found this function is the hardest part. Here's how it is used in start and install:

selenium-standalone/lib/install.js

Lines 34 to 37 in 57e1eb1

	async function install(_opts) {
	const opts = checkArgs('Install API', _opts);

Given an optional _opts, when we call checkArgs('...', _opts) we want to return that type (or Partial). I got stuck here with the Partial<T>:

/**
 * @template T
 * @param {string} fnName
 * @param {T} opts
 * @returns {Partial<T>}
 */
const checkArgs = (fnName, opts = {}) => {
//                         ^^^^^^^^^
// Type '{}' is not assignable to type 'T'.
//  'T' could be instantiated with an arbitrary type which could be unrelated to '{}'.ts(2322)

[christian-bromann]

oh .. not sure how to do that with JSDoc, in TS this would look like:

const checkArgs<T extends object> = (fnName: string, opts: T = {}): T => {
  debug(fnName + ' called with', opts);

  return { ...opts };
};

[seanpoulter]

Yea, I wanted to work in JS so I could work in smaller steps. Would you be OK with the change knowing that it only changes what is logged in the debug call from {} to undefined? I added tests before I gave up on JSDoc. 😆

--

I following microsoft/TypeScript#41768 which says that:

<T extends object>

would become

 * @template {object} T

but TS infers it as unknown:

/**
 * @template {object} T
 * @param {string} fnName
 * @param {T} [opts]
 * @returns {T}
 */
const checkArgs = (fnName, opts = {}) => {
//                         ^^^^^^^^^
// Type '{}' is not assignable to type 'T'.
//  '{}' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint 'unknown'.ts(2322)

It is similar with @template {object} T but you get {} instead of unknown:

Type '{}' is not assignable to type 'T'.
  '{}' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint '{}'.ts(2322)

That's where I gave up, added a test, and removed = {}. We could also inline the method to remove the problem.

[christian-bromann]

Yeah, this should not blocking us from moving forward.