Typescript Definition
Opened this issue · 14 comments
I've been using firmata (raw, not through J5 for Cylon) in my project for a several months now. My projects are typescript. I had to produce a typescript definition file for firmata to use firmata more effectively. I want to get those definition(s) published so they are usable by anyone. There are two methods through which I can do this, and I want input from the maintainers of this project before I choose my direction. You'll see these two methods are mentioned on the DefinitelyTyped contribution readme.
-
METHOD 1: I can bundle the typescript definition file with firmata.js itself (i.e. fork this repository, include my typescript definition file, and if the user is using Typescript, it gets linked, and if not, its ignored). I think this is the cleanest and keeps the definition with the project in question
-
METHOD 2: I can add it to the DefinitelyTyped repository so it is then installable/usable with
npm i -D @types/firmata. This means the file does not reside with firmata.js repo (though I can probably link to this repo), but is available should someone wish to use firmata within their typescript project.
Do you guys have any preference on which method is best for the direction of firmata? I know @soundanalogous is very active in this project, so I'll allow him to defer the question to others if he does not have an answer himself.
Just to clarify, I have a typescript definition file that I've been using for months, and I just want to get that out there so I'm not the only one using it (and so I can npm install it in any future projects I intend to work on). Thanks for your input!
I'll point out that DefinitelyTyped maintainers also recommend bundling, but again, I defer to firmata.js maintainer's preference (if you even have any).
I prefer method 2 since method 1 may open the door for supporting other languages that compile into JS (Dart for example) as well and that could get messy and add unnecessary dependencies. I'd also like @rwaldron to weigh in as well, but he's sorta on paternity leave from open-source work at the moment so we may not hear from him for a while.
Okay, I started on Method 1 because it was easiest at the moment, but I did so in a way that I can attempt Method 2 come Monday. I completely understand the concerns mentioned. Assuming I was doing it right, I can confirm that bundling adds 2 dependencies (one dev: @types/serialport, and one regular: @types/node). I'll keep you up to date on if I'm successful producing an @types/firmata.
Maybe another option is creating a new project called "typescript-firmata" or something like that and then include firmata.js as a submodule. That way you could provide typescript-specific instructions in the readme, etc.
I'll have to look into it, but I think publishing on @types allows you one to provide instructions.
The PR for @types/firmata is in progress: DefinitelyTyped/DefinitelyTyped#15265
I've read the PR and there are a few places you could be more specific, but I also noted that those places were marked with "TODO", so I will let you finish before I make a bunch of noisy comments.
@rwaldron You are correct. All the TODO marked items are incomplete because I never had use cases and had to generate these definitions entirely by hand. So I originally only generated type specific type definitions for items I was actively using, and it required me digging into the code for every single function to see how the arguments were used (i.e. were they expected as numbers, strings, etc.). Its a time-consuming process, and my hope is that by getting an @types/firmata out there, other people can fork and improve those type definitions.
@rwaldron @soundanalogous in fact, if you look at any of those and can provide better type-definitions than all the any-placeholders I have all over the place off the top of your head, I will definitely take them into account. Otherwise, I'm sure I or others will produce them in time by digging through the prototypes as I did.
For me, this is one small piece in a larger task at hand, so I want to get a working example up ASAP.
I will make comments in your PR for more explicit types.
Good news, guys! The pull-request was merged, and you can now npm i -D @types/firmata to start using firmata within TypeScript projects with greater ease! Thanks for all the input @rwaldron @soundanalogous!
@troywweber7 can you open a PR here, adding instructions to the readme? Thanks!
@rwaldron Sorry I never opened up that README, I'll reopen this issue so it's on my radar. I also updated the definitions with a new PR that affects @types/firmata and @types/serialport a bit because you can pass serialport options to the constructor, but this is only known by looking deep into the code. I mention it in this issue.
@rwaldron I'm pretty busy, but here is reference to the typescript usage (in the form of typescript definition tests on DefinitelyTyped) just in case someone else gets to a README addition before me.