Add TypeScript declarations and generate docs

[AlexTolmachev]

Because of native nature of your library it's impossible for IDEs to list methods of req and res objects. Also it's impossible to get methods and properties of this objects via Object.enties or Object.keys.

So the question is where to find an uWS's HTTP API reference?

[xxzefgh]

If you understand a little bit of C++, you can explore wrapper headers. From a quick look, I can tell that HttpRequest has following methods:

getHeader
getParameter
getUrl
getMethod
getQuery

and HttpResponse:

writeStatus
end
tryEnd
write
writeHeader
close
getWriteOffset
onWritable
onAborted
onData

[ghost]

What happens if you print res.prototype? Or res.prototype.entries etc?

[AlexTolmachev]

My bad, forgot to take a look at the res's prototype 🧐

Anyway, I already used method described by @xxzefgh.

But I think, that for some js-developers it can be hard to even look at c++ source code :) So docs would be great addition to such a cool library 🤓

Thank you, guys!

[ghost]

Printing res should print also the proto? Or? It would be nice.

[ghost]

Adding typescript declarations would probably help a lot both documenting (TypeDoc) and for IDEs. How do I add that? I don't want third parties involved who cannot keep up

[ghost]

I'm talking about definitelytyped - they don't care about quality just quantity

[ghost]

Where do I put my d.ts file for best effect? Can I just ship it in the NPM package and be done?

[ghost]

Oh I just create uws.d.ts and put types field in package.json and boom! Now the project is TypeScript wow.

A smart IDE will pick up that declaration file and apply to JavaScript as well yes?

[xxzefgh]

@alexhultman yes, either [filename].d.ts or index.d.ts will work.

[xxzefgh]

if you provide types or typings field in package.json, than anything will work I think

[ghost]

Oh wow it works. Visual Studio Code did pick up on the index.d.ts in node_modules right away and shows exactly what is what. I love solutions like these, one file, compatible with JS, adds documentation too. 👍

[ghost]

interface TemplatedApp {
z: number;
}

export function App(): TemplatedApp;

I want TemplateApp to have functions how do I achieve such a dream

[ghost]

interface TemplatedApp {
listen(host: string, port: number): TemplatedApp;
}

export function App(): TemplatedApp;

There's no integer type?

[ghost]

There are now documentation generated from decl file: https://github.com/uNetworking/uWebSockets.js/blob/master/docs/index.d.ts

WIP, but looks very beautiful!

[ghost]

Documentation is pretty much done now, just need to have a release include that index.d.ts.

[olivier65]

Please do consider uploading this stub to the DefinitelyTyped repository as well: https://github.com/DefinitelyTyped/DefinitelyTyped. That is where, e.g., the JetBrains IDEs look for them.

[ghost]

You don't need to upload them to third party, definitions are shipped with the module. Visual studio code pick up on them

[olivier65]

If you prefer to include the definitions with the module then you should include a "types": "./index.d.ts" entry in your package.json to tell tools where to look for it. These are the only two standard ways to publish your definitions: see here.

It's possible VS Code goes beyond the call of duty and additionally looks for index.d.ts under the root but you can't expect every IDE to emulate VS Code.

[mikeandtherest]

Hi Alex.

I'm on VS Code using node 12+ with TS, but for some reason the IDE does not see the type definitions. I tried to manually reference them via /// <reference path="../node_modules/uWebSockets.js/index.d.ts" />, to no avail.

So I can confirm the need of what olivier65 and xxzefgh suggested, i.e. add the "types": "./index.d.ts" entry to the package.json file of the lib. I'm sure a lot of use would appreciate that. Thanks!

[ghost]

If that helps can you PR it I forgot this issue

[ghost]

uWebSockets.js/package.json

Line 5 in a1d30bb

"types": "./index.d.ts"

I added that line if it helps

[ghost]

Is ./index.d.ts really Windows-compatible?

[ghost]

I tested an older release on Windows / Visual Studio Code and it picked up on the type docs perfectly. According to the docs for package.json it should default to index.d.ts anyways.