chore(url): add jsdoc typescript checking #17014

dsifford · 2019-08-12T22:08:44Z

Description

This is the first of many PRs that seek to introduce JSDoc TypeScript type checking to packages. I chose this package as the first one because it's one of the easier ones to do and should be a good starting point for reviewers to familiarize themselves.

I'll make inline comments to some of the changes that I think are most notable. Otherwise, this should be fairly straightforward.

One final thing to note: I decided to add in a tsconfig.json file alongside the existing jsconfig.json file because the configurations as of right this moment are uniquely different and serve different purposes. Once all the packages have been updated with better JSDoc, we can either keep both of these files OR delete the tsconfig.json and merge in the changes into the jsconfig.json, whatever you all prefer.

How has this been tested?

All tests still passing.

Screenshots

Types of changes

Code quality / Documentation.

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.
I've included developer documentation if appropriate.

dsifford

Final note: a bunch of the checks are failing for whatever reason. Those are unrelated to the changes I made here as far as I can tell.

dsifford · 2019-08-12T22:18:37Z

packages/url/src/index.js

+ */
+
+/**
+ * @typedef {string|string[]|QueryArgObject} QueryArgParsed


This was added to more closely represent the possible return types of getQueryArg.

It appears that it is currently possible for the response to be an object, containing keys whose values are either string or string[] or simply a string or string[] by itself.

This definition accounts for that. There needs to be two separate definitions because they are both cyclic and recursive.

dsifford · 2019-08-12T22:18:56Z

packages/url/src/index.js

 *
 * @example
 * ```js
 * const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
 * ```
 *
- * @return {Array|string} Query arg value.
+ * @return {QueryArgParsed|undefined} Query arg value.


Note QueryArgParsed is used here.

I thought we might leverage qs types here, but parse is typed as:

function parse(str: string, options?: IParseOptions): any;

That's not very helpful, I suspect it's very difficult to type the return because it can vary based on the input and options. We control the options and can likely provide better type information as you've done.

dsifford · 2019-08-12T22:20:53Z

tsconfig.json

+		"noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */
+
+	},
+	"include": [


The include array will be changed with each new package that is added. We're skipping tests because almost universally throughout the project, incorrect partial types are fed to functions to test a specific case which is not allowed as far as TypeScript is concerned. Fixing all of those instances would require a pretty significant amount of work and there's no real benefit to doing it.

Yes, let's skip tests for now and revisit our approach once we have all packages enabled here 👍

youknowriad · 2019-08-13T10:31:52Z

packages/url/src/index.js

- * @param {?string} url  URL to which arguments should be appended. If omitted,
- *                       only the resulting querystring is returned.
- * @param {Object}  args Query arguments to apply to URL.
+ * @param {string} [url='']  URL to which arguments should be appended. If omitted,


The default value seems like a duplication for me, can't it be infered?

This is mostly important for documentation generation. Otherwise, I'm mainly just following the WordPress JSDoc standards posted here.

To answer your question: Yes, the TypeScript compiler can infer this.

youknowriad

How can we "use" these checks? Can we add a CI job to check the types or add it to the lint job?

dsifford · 2019-08-13T14:09:45Z

How can we "use" these checks? Can we add a CI job to check the types or add it to the lint job?

Yes, but I was under the impression that it was preferred that I hold off on doing that until the rest of the packages are finished. If not, I can add it into the CI flow no problem.

To run the TypeScript compiler locally yourself, it's as easy as running npx tsc from anywhere in the project.

Speaking of checks, what's going on with the checks for this PR? Lots of actions are failing.

dsifford · 2019-08-20T21:58:38Z

Ping @youknowriad -- See comments above. Is this good to merge?

youknowriad · 2019-08-21T08:52:45Z

Yes, but I was under the impression that it was preferred that I hold off on doing that until the rest of the packages are finished. If not, I can add it into the CI flow no problem.

Can we try this, fees like we can add this pretty easily to the lint job right?

dsifford · 2019-08-21T13:20:08Z

@youknowriad Done.

youknowriad · 2019-08-21T14:52:55Z

package.json

 		"lint-js": "wp-scripts lint-js",
 		"lint-js:fix": "npm run lint-js -- --fix",
 		"lint-php": "docker-compose run --rm composer run-script lint",
 		"lint-pkg-json": "wp-scripts lint-pkg-json ./packages",
 		"lint-css": "wp-scripts lint-style '**/*.scss'",
 		"lint-css:fix": "npm run lint-css -- --fix",
+		"lint-types": "tsc",


Should we install the typescript dev dependency? I think travis is failing because of it?

Whoops, sorry about that. On it now.

Should we include this command in lint-staged section of this file to have it executed as a pre-commit hook?

Not sure if we can lint only a single file at a time because type compilation generally requires knowledge of the entire project.

Also, the compiler seems to freak out if you feed it files with a .js extension by itself (regardless of whether or not they are allowed)...

$ tsc packages/autop/src/index.js error TS6054: File 'packages/autop/src/index.js' has unsupported extension. The only supported extensions are '.ts', '.tsx', '.d.ts'. Found 1 error.

So, in short, we can add it it the lint-staged flow, but it technically won't be able to lint just the staged file(s). Up to you.

We can skip it for now if it produces issues, no worries. As long as Travis is going to catch those violations, we are good 👍

youknowriad · 2019-08-22T08:13:42Z

There's one last failing, I think you should probably just rebase the branch for it to pass.

dsifford · 2019-08-23T16:11:03Z

Re: The failing step --- I think this is unrelated to this PR specifically since that same check was failing from all PRs since (IIRC) 2 days before this PR until (at least) 2 days ago.

Do you still want me to rebase anyway? If so, I'll do it on Monday. I'll be away all weekend.

gziolo · 2019-08-27T06:01:12Z

Do you still want me to rebase anyway? If so, I'll do it on Monday. I'll be away all weekend.

Yes, it would be great to rebase. Riad is off for the next two weeks, but I can help to land it :)

sirreal

This is great, I'm excited to start leveraging all your work around TypeScript. I've left some notes and questions on the PR.

One final thing to note: I decided to add in a tsconfig.json file alongside the existing jsconfig.json file because the configurations as of right this moment are uniquely different and serve different purposes. Once all the packages have been updated with better JSDoc, we can either keep both of these files OR delete the tsconfig.json and merge in the changes into the jsconfig.json, whatever you all prefer.

This note leaves me with additional questions, can you elaborate a bit more? Particularly, it's unclear yo me how they can be "uniquely different and serve different purposes", but in the future one of them would become redundant.

sirreal · 2019-08-27T07:06:21Z

tsconfig.json

+
+		/* Strict Type-Checking Options */
+		"strict": true,                        /* Enable all strict type-checking options. */
+		"noImplicitAny": false,                /* Raise error on expressions and declarations with an implied 'any' type. */


Why do we allow implicit any?

We can decide to get stricter in the future, but adding noImplicitAny as it stands right now would require a lot of variable annotations in the code. Goal is to make the initial transition as seamless and painless as possible.

I tried disabling this and the only error was missing types for qs module. Do you expect we'll start pulling in type declarations as devDependencies?

I'm on the fence because it seems much easier to relax things when you're too strict than to become more strict when you've been too relaxed 🙂

Have you already investigated parts of the code where strictness here becomes overly cumbersome and could you provide an example?

I have not. But I'm nervous that we'd lose people who bought into this crazy idea if I told them we'd have to depend on more external types.

No specific examples I can think of off the top of my head but, as you've already alluded, the issues that arise will be almost (if not entirely) exclusive to missing type definitions for externals.

We could fix that if we pull in those defs from DefinitelyTyped, however there was some concern already about pulling in the types for this repo from DefinitelyTyped so not sure how the response to that ask would go over (see side note).

I'm all for making it as strict as possible.

Side note: Why would we be pulling in externals for this repo when we have perfectly good JSDoc here already? The answer to that is that although JSDoc provides fairly good types in comparison to native typescript, it does not allow for the inference that native typescript can produce with respect to generics or overloaded functions (yet). Also, the DefinitelyTyped definitions have all the React components strongly typed as well.

I'm nervous that we'd lose people who bought into this crazy idea if I told them we'd have to depend on more external types.

Good point 👍

packages/url/src/index.js

sirreal · 2019-08-27T07:45:05Z

packages/url/src/index.js

 *
 * @example
 * ```js
 * const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
 * ```
 *
- * @return {Array|string} Query arg value.
+ * @return {QueryArgParsed|undefined} Query arg value.


I thought we might leverage qs types here, but parse is typed as:

function parse(str: string, options?: IParseOptions): any;

That's not very helpful, I suspect it's very difficult to type the return because it can vary based on the input and options. We control the options and can likely provide better type information as you've done.

sirreal · 2019-08-27T09:30:47Z

packages/url/README.md

@@ -30,7 +30,7 @@ const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://g

 _Parameters_

-   _url_ `?string`: URL to which arguments should be appended. If omitted, only the resulting querystring is returned.
+-   _url_ `[string]`: URL to which arguments should be appended. If omitted, only the resulting querystring is returned.


I find the [string] syntax strange. Where does it come from?

I assume it means "optional parameter with a default value", but that only seems to vaguely align with jsdoc, where [square brackets] are used on the parameter or property names to indicate they're optional, not around the type.

To add to the confusion, in TypeScript [ string ] would mean a one-tuple of strings, or an array with a single string member, e.g. [ "foo" ] but never [] or [ "foo", "bar" ].

Yeah, as it stands, the way that the JSDoc is being parsed definitely results in clunky markdown for this particular case.

In JSDoc, it's pretty easy to tell the difference between optional types and single-tuple types because they are written differently.

// optional string type /** * @param {string} [foo] */ // single tuple string type /** * @param {[string]} foo */

So I think that you've definitely raised a valid concern with respect to how the docs are being generated.

(PS: syntax comes from here)

sirreal · 2019-08-27T10:01:28Z

packages/url/src/index.js

@@ -50,7 +58,7 @@ export function isEmail( email ) {
 * const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'
 * ```
 *
- * @return {?string} The protocol part of the URL.
+ * @return {string|void} The protocol part of the URL.


Regarding the return types here in general, it's been bothering me a bit that some are SomeType | void and another is SomeType | undefined…

It appears that type void = undefined | null or with strictNullChecks it's type void = undefined (our case). However, when I think of functions that return void, I tend to think of side-effects. Using void in a union with another type to indicate we may or may not get a value seems like something better expressed by SomeType | undefined.

As far as I can tell and for our purposes, void and undefined are type aliases, so this is very much a stylistic preference, but is this something you considered and do you have thoughts on it?

This is a good observation and for all intents and purposes void and undefined are functionally equivalent when strict checking is enabled.

....however.

The TypeScript parser treats the following functions differently...

// returns `void` function foo() { return; } // returns `undefined` function bar() { return undefined; } // returns `void` function baz() {} // returns `number | void` *see note function qux(thing) { if (thing) { return 123; } }

Actually, when writing those test cases above, I threw them at the typescript compiler just to make sure I wasn't mistaken and the last case technically returns number | undefined. I think this is because it does sometimes return a value, the void is just turned into undefined.

So, for the case you point out, you're right. This should be string|undefined here. 👍

Ah, this is why I did it the way I did it....

I noticed that in the TypeScript playground, a return statement —even empty return;— is required to return undefined instead of void. Viewed from this perspective and accustomed to JavaScript's implicit undefined return, that seems like a strange decision 🤷‍♂

It's tempting to go add empty returns to the functions that are returning string | void, but TypeScript should be supporting us and not the other way around.

These are fine to leave, thanks for your thoughts 👍

My only worry is that we will have to update all occurrences where the return value is optional. It might be quite a huge number of lines. For what it's worth, it's at list very explicit.

Co-Authored-By: Jon Surrell <[email protected]>

dsifford · 2019-08-27T12:44:15Z

@sirreal

This note leaves me with additional questions, can you elaborate a bit more? Particularly, it's unclear yo me how they can be "uniquely different and serve different purposes", but in the future one of them would become redundant.

Sorry for the confusion. Right now the jsconfig's role is to provide type hints where able in editors that support it for all packages.

Conversely, the tsconfig.json is providing type hints and also compiling for errors in only the specific files that we include in the include section (gradually adding more and more packages as they are fixed). Once all the types are fixed and it compiles without issues, the two config files will essentially converge and one of them will be redundant.

dsifford · 2019-08-27T12:47:30Z

@gziolo Has this already been rebased? The travis build is passing now and it appears that these commits are ahead of the commits on master (I had to delete my local repo and re-pull to make sure I was seeing this correctly).

sirreal

This looks great to me, thanks @dsifford 🎉

There's one improvement I'd like to see for types in the generated documentation, but that's not introduced in this PR and can be addressed later.

gziolo · 2019-08-28T09:29:05Z

There's one improvement I'd like to see for types in the generated documentation, but that's not introduced in this PR and can be addressed later.

It's your call whether you want to include it in this PR or do you plan to work on a follow-up. You should be able to merge yourself if you pick the first option. I trust @sirreal more than myself in the context of TypeScript 😅

gziolo · 2019-08-28T09:35:01Z

tsconfig.json

+		"./packages/url/**/*.js"
+	],
+	"exclude": [
+		"./packages/**/test/**",


At some point, you will have to include:

"./packages/**/benchmark/**",

Just saying, there are a few packages which use them :)

Good point. I'll add it in when the issue arises if that's okay with you.

dsifford · 2019-08-28T12:37:28Z

@gziolo

It's your call whether you want to include it in this PR or do you plan to work on a follow-up. You should be able to merge yourself if you pick the first option. I trust @sirreal more than myself in the context of TypeScript

We can try to get something together in this PR if you'd prefer that, but it might require a bit of work and some design input from the team to get done properly. The changes would have to occur in the package that generates the markdown documentation.

gziolo · 2019-08-28T13:06:09Z

We can try to get something together in this PR if you'd prefer that, but it might require a bit of work and some design input from the team to get done properly. The changes would have to occur in the package that generates the markdown documentation.

I don't think I can help this week, so it's totally fine to open an issue and merge it in the current shape.

gziolo · 2019-08-30T10:04:08Z

I filed a follow-up #17271 to keep track of issues raised in #17014 (review) by @sirreal.

chore(url): add jsdoc typescript checking

fe781fc

dsifford requested a review from talldan as a code owner August 12, 2019 22:08

dsifford commented Aug 12, 2019

View reviewed changes

ntwb added the [Type] Developer Documentation Documentation for developers label Aug 13, 2019

youknowriad reviewed Aug 13, 2019

View reviewed changes

add typescript checks to lint job

28d8a01

youknowriad reviewed Aug 21, 2019

View reviewed changes

add typescript as devDependency

a283b6f

gziolo added [Package] Url /packages/url [Type] Build Tooling Issues or PRs related to build tooling labels Aug 27, 2019

gziolo assigned dsifford Aug 27, 2019

gziolo mentioned this pull request Aug 27, 2019

Blocks: Try adding TypeScript type checking and improved JSDoc #16552

Closed

8 tasks

sirreal reviewed Aug 27, 2019

View reviewed changes

fix(url): improve type annotation for clarity

fa0d540

Co-Authored-By: Jon Surrell <[email protected]>

sirreal approved these changes Aug 27, 2019

View reviewed changes

gziolo reviewed Aug 28, 2019

View reviewed changes

dsifford merged commit f7e067b into master Aug 28, 2019

dsifford deleted the add/url/typescript-jsdoc-checking branch August 28, 2019 15:14

gziolo added this to the Gutenberg 6.5 milestone Aug 30, 2019

gziolo mentioned this pull request Aug 30, 2019

Documentation: Improve the way types are presented in the generated documentation #17271

Closed

aduth mentioned this pull request Nov 12, 2019

RichText: remove Editable & allow React to diff editable element #17779

Merged

5 tasks

This was referenced Nov 25, 2019

Documentation: Outline third-party developer resources (TypeScript definitions) #15027

Closed

added a Text component #18495

Merged

Testing: Add TypeScript types validation for modules #18838

Closed

aduth mentioned this pull request Dec 3, 2019

Docs: Include TypeScript type checking in Testing Overview #18879

Merged

aduth mentioned this pull request Mar 5, 2020

Build: Output package type declarations #18942

Merged

chore(url): add jsdoc typescript checking #17014

chore(url): add jsdoc typescript checking #17014

Conversation

dsifford commented Aug 12, 2019 • edited Loading

Description

How has this been tested?

Screenshots

Types of changes

Checklist:

dsifford left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad left a comment

Choose a reason for hiding this comment

dsifford commented Aug 13, 2019

dsifford commented Aug 20, 2019

youknowriad commented Aug 21, 2019

dsifford commented Aug 21, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad commented Aug 22, 2019

dsifford commented Aug 23, 2019

gziolo commented Aug 27, 2019

sirreal left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsifford Aug 27, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsifford Aug 27, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsifford Aug 27, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsifford commented Aug 27, 2019

dsifford commented Aug 27, 2019

sirreal left a comment

Choose a reason for hiding this comment

gziolo commented Aug 28, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsifford commented Aug 28, 2019

gziolo commented Aug 28, 2019

gziolo commented Aug 30, 2019

dsifford commented Aug 12, 2019 •

edited

Loading

dsifford Aug 27, 2019 •

edited

Loading

dsifford Aug 27, 2019 •

edited

Loading

dsifford Aug 27, 2019 •

edited

Loading