ngl
ngl copied to clipboard
nglviewer
TypeScript Definition File
This project is really impressive - I especially love the generated documentation!
I noticed ngl 2.x.x is using TypeScript - Is there a plan to provide a type definition file for other developers wishing to integrate ngl into their application? Either directly as part of the repo, or as part of the @types repository?
I'm currently writing some up now for work as part of HCA, but would be thrilled to submit a PR if it'd be beneficial!
Is it really necessary to create an extra type definition file since most of NGL is now in TS?
When working within the NGL repo, it is perfectly fine as is!
However, when pulling in the repo as a dependency, all of the type information is unavailable.
The 2 routes I spent some time on last month were:
- Generating them via the
--declarationtsc flag. - Creating handwritten type definitions based on the existing documentation.
For route 1, I was unable to get any .d.ts files generated due to the existing .js files - perhaps there's a setting I'm not aware of that could remedy that. For route 2, my current WIP can be found here: https://github.com/cBioCenter/chell-viz/tree/master/types/ngl
I absolutely would love to help the effort, whether it be by making a PR with finalized/formal type definitions, or doing some more .js -> .ts conversion!
As a VS code user, I really appreciate the possibility offered by type declarations in the libraries I use. Given the extent of NGL library, I have no doubt this would be very useful to me!
I have just tried the route 1 (which seems more maintainable): tsc -d to auto-generate the type declaration file.
hundreds of errors have been reported, mostly related to types being private because their declarations are not exported.
@MercifulCode have you encountered the same problem and fixed it already?
@ppillot I believe I encountered that, yes - following the trail of needing to export various types led to needing to convert more .js files to .ts, or at least do a bit of refactoring.
However, that was about a month ago, which is a few versions behind master - I plan to make some time this week to take another swing at using the auto-generation compilation flag!
@MercifulCode then we should aim at finishing the JS -> TS conversion. @arose, I'd be glad to help.
+1. We're also interested in having type files to integrate ngl in our codebase; can we (Cyrus Biotechnology) somehow aid in the transition from JS to TS?
I've just finished converting the source code to typescript (except for the polyfills) #524 . I've tried again the tsc -d command and it reports hundreds of errors, mainly due to type declaration private to modules (no export). One last stretch and it may be working!
I've completed the aforementioned PR #524 with various adjustments related to TS declarations.
Some seem to me as quirks (see comment on the PR) but I could not figure a better way.
In the end, I've realized that tsc -d produces a declaration file for each module, i.e. tens of declaration files. I used the command tsc -d --outFile "ngl.js" --module "system" to generate a single js file and its accompanying single declaration file.
I manually copied this file in the ngl folder in node_modules in my application folder, opened VS code and got this intellisense of magic:
When I open the declaration file in my editor, hundreds of errors are reported as relative path had been made to external dependencies (for example Vector3 objects coming from three).
So, it apparently works really well (I didn't expect to have the JSDoc comments appearing, but it's great to have them). It still needs some testing, especially to get a proper a build workflow, and make sure that the d.ts file produced provides all the relevant informations.
So what is needed to make such a d.ts file part of the distribution? I read that there is no direct support in tsc -d to include external type defs but there see to be tools out there to do that. Does anyone have experience with this?
For the first part of your questions, technically the npm package should ship with 1 or many d.ts files.
If we manage to have only 1 proper d.ts file for ngl, then this ngl.d.ts file could sit in the dist folder with the 2 library files present there. a reference to this file in package.json under the property types is better, but not mandatory in that case for finding the declaration.
If we have many d.ts files, then they would preferably be in a separate folder, for example types and the package.json property should be set accordingly.
Regarding external dependencies such as three, chroma, signals and node, I've read that it is recommended to add their types as dependencies to package.json and not dev-dependencies so that the end user get these typings when she downloads the package.
Bumping this. Using ngl (installed via npm) in our project and not having types definitely hurts the development experience.
Hi there is any update in that regard? I've found that in the node_modules/dist there is a folder full of the typescript, can we use those definitions? Do you know a way to use it?
Hi there is any update in that regard? I've found that in the node_modules/dist there is a folder full of the typescript, can we use those definitions? Do you know a way to use it?
Yes, types have been fully integrated into the distribution for a couple of years. I use VS-code and the type imports are suggested as I type (similarly to the screenshot above). There is nothing specific to do for me to make it work. Note that I use esm imports, so this might be a difference from your system if, for example, you are using the minimified version if the library. In that case, you may have to specify the type imports manually.
