connect: add req.originalUrl; improve API; API docs from README #40409

geekley · 2019-11-15T06:49:57Z

Please fill in this template.

Use a meaningful title for the pull request. Include the name of the package modified.
Test the change in your own code. (Compile and run.)
Add or edit tests to reflect the change. (Run with npm test.)
Follow the advice from the readme.
Avoid common mistakes.
Run npm run lint package-name (or tsc if no tslint.json is present).

Select one of these and delete the others:

If changing an existing definition:

Provide a URL to documentation or source code which provides context for the suggested changes: https://www.npmjs.com/package/connect#appuseroute-fn
If this PR brings the type definitions up to date with a new version of the JS library, update the version number in the header.
If you are making substantial changes, consider adding a tslint.json containing { "extends": "dtslint/dt.json" }. If for reason the any rule need to be disabled, disable it for that line using // tslint:disable-next-line [ruleName] and not for whole package so that the need for disabling can be reviewed.


        connect: improve API, add req.originalUrl


        connect: API docs from README, tests


        connect: tests and lint OK, bump v3.7

typescript-bot · 2019-11-15T07:00:17Z

👋 Hi there! I’ve run some quick measurements against master and your PR. These metrics should help the humans reviewing this PR gauge whether it might negatively affect compile times or editor responsiveness for users who install these typings.

Let’s review the numbers, shall we?

	master	#40409	diff
Batch compilation
Memory usage (MiB)	64.6	65.3	+1.0%
Type count	8386	8474	+1%
Assignability cache size	903	904	0%

Language service
Samples taken	89	112	+26%
Identifiers in tests	89	112	+26%
`getCompletionsAtPosition`
Mean duration (ms)	304.2	334.5	+10.0%
Mean CV	12.7%	12.4%
Worst duration (ms)	374.8	477.6	+27.4% 🔸
Worst identifier	http	use
`getQuickInfoAtPosition`
Mean duration (ms)	304.1	331.9	+9.1%
Mean CV	12.7%	11.1%	-12.1%
Worst duration (ms)	379.6	402.1	+5.9%
Worst identifier	use	createServer

Looks like there were a couple significant differences—take a look at worst-case duration for getting completions at a position to make sure everything looks ok.

typescript-bot · 2019-11-15T07:35:56Z

@geekley Thank you for submitting this PR!

🔔 @SomaticIT @EvanHahn - please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

If no reviewer appears after a week, a DefinitelyTyped maintainer will review the PR instead.

EvanHahn

IMO, too many things are happening in this pull request. It seems like there are a few distinct pieces:

Add documentation
Add connect.Request, which extends http.IncomingMessage with an originalUrl
Removes a lot of TSLint stuff

Could we split these into multiple changes to make it easier to review?

EvanHahn · 2019-11-16T21:37:34Z

types/connect/index.d.ts

+         * at the route `/foo`, the request for `/foo/bar` will invoke it with `req.url === '/bar'` and
+         * `req.originalUrl === '/foo/bar'`.
+         */
+        url: string;


This is already a property of http.IncomingMessage. Have you added this for documentation purposes?

Yes, the documentation override is important because this url is conceptually different from the superclass (since it doesn't contain the route part). Also the not-null guarantee. It helps if you have strict null checking, you can do req.url without an assertion.

typescript-bot · 2019-11-16T22:23:23Z

@geekley One or more reviewers has requested changes. Please address their comments. I'll be back once they sign off or you've pushed new commits or comments. Thank you!

geekley · 2019-11-16T23:12:56Z

types/connect/index.d.ts


-    export type SimpleHandleFunction = (req: http.IncomingMessage, res: http.ServerResponse) => void;


"Optional" param next in callback was removed according to do's and dont's (it's always available to callbacks), so SimpleHandleFunction was deprecated.

geekley · 2019-11-16T23:21:25Z

types/connect/index.d.ts

+        listen(port: number, hostname?: string, backlog?: number, listeningListener?: () => void): http.Server;
+        listen(port: number, hostname?: string, listeningListener?: () => void): http.Server;
+        listen(path: string, listeningListener?: () => void): http.Server;
+        listen(handle: any, listeningListener?: () => void): http.Server;


using listeningListener?: () => void instead of Function, to match signature of Server.listen

I could have also added the other overloads of Server.listen (since it's the exact same method) but I wasn't sure if I should do that (I only looked at the latest version of Node) so I left only the ones already present.

geekley · 2019-11-16T23:33:39Z

types/connect/index.d.ts

+        /** Register a middleware. */
        use(fn: HandleFunction): Server;
+        /** Mount a middleware on the specified route. */
        use(route: string, fn: HandleFunction): Server;


I originally intended to replace them with the overloads above, with the direct explicit parameters of fn callbacks visible, because that's more practical to handle in the editor (VSCode) after autocomplete, etc. Also, that allows more accurate documentation on each specific overload.
However, I had to keep the overloads with HandleFunction to avoid breaking compatibility in the tests of other packages, which referenced HandleFunction interface directly by name. Maybe I should have added @deprecated here as well.

geekley · 2019-11-16T23:39:44Z

types/connect/index.d.ts

 */
-declare function createServer(): createServer.Server;
+declare function createServer(): connect.Server;


When hovering const connect = require("connect"); the signature here shows the namespace as "connect" instead of "createServer" beacuse of the import trick above (line 11).

geekley · 2019-11-16T23:47:07Z

types/connect/index.d.ts

-    export type NextHandleFunction = (req: http.IncomingMessage, res: http.ServerResponse, next: NextFunction) => void;
-    export type ErrorHandleFunction = (err: any, req: http.IncomingMessage, res: http.ServerResponse, next: NextFunction) => void;
-    export type HandleFunction = SimpleHandleFunction | NextHandleFunction | ErrorHandleFunction;
+    /** @deprecated `next` is always available to the handler */ export type SimpleHandleFunction = NextHandleFunction;
+    export type NextHandleFunction =
+        (req: Request | http.IncomingMessage, res: http.ServerResponse, next: NextFunction) => void;
+    export type ErrorHandleFunction =
+        (err: any, req: Request | http.IncomingMessage, res: http.ServerResponse, next: NextFunction) => void;
+    export type HandleFunction = NextHandleFunction | ErrorHandleFunction;


Param req was originally changed to be connect.Request (with originalUrl) but I had to keep http.IncomingMessage too to avoid breaking a test in another package which referenced the HandleFunction type directly by name (even though its a subtype).

geekley · 2019-11-16T23:51:16Z

types/connect/index.d.ts

-        (req: http.IncomingMessage, res: http.ServerResponse, next?: Function): void;
+        /**
+         * The `app` itself is a function. This is just an alias to `app.handle`.
+         */
+        (req: http.IncomingMessage, res: http.ServerResponse, next?: NextFunction): void;


This is the exact same as handle(req, res, out) according to code and API.

geekley · 2019-11-16T23:58:37Z

types/connect/index.d.ts

-        * Handle server requests, punting them down
-        * the middleware stack.
-        *
-        * @private
-        */
-        handle(req: http.IncomingMessage, res: http.ServerResponse, next: Function): void;
+         * Calling the function will run the middleware stack against the given Node.js http request (`req`)
+         * and response (`res`) objects. An optional function `out` can be provided that will be called if the
+         * request (or error) was not handled by the middleware stack.
+         */
+        handle(req: http.IncomingMessage, res: http.ServerResponse, out?: NextFunction): void;


An optional function out can be provided that will be called if the request (or error) was not handled by the middleware stack.

Connect code (lines 127, 151) confirms that the out param is optional and called with err as parameter.

geekley · 2019-11-17T00:23:40Z

IMO, too many things are happening in this pull request. It seems like there are a few distinct pieces

@EvanHahn I have added comments to clarify the most significant code changes. The rest is pretty much documentation (not included in the first commit). All code changes are already basically concentrated in the first commit, so it might be easier to review that one first.

EvanHahn

Thanks for doing this.

I'd still prefer this to be multiple PRs for a few reasons:

The commit message title includes some, but not all, of the things you're doing in this change. This is really a full rewrite of the package. For example, you've changed TSLint, cleaned up some of the test files, and changed the exported interface from createServer to connect. Too many things are happening to capture in the title of a single commit or PR.
Even with your helpful comments, it's still hard to review. There are lots of things I don't understand the intention behind, even if they're a good idea. For example, you added some comments to the top of the test file, but I don't know why.
Someone going through the commit history in the future will also have similar issues breaking down the change. For example, someone trying to see what happened a year from now might not be able to figure out the intention behind some change.
Large changes have a bigger chance of causing disruption to users of @types/connect. If you made a mistake and I fail to catch it in review, we're going to cause a bunch of people a lot of trouble. If the changes are smaller, that could still happen, but the issues are localized.

EvanHahn · 2019-11-17T14:59:31Z