executablebooks
Consider using TypeScript
Much of the Jupyter project has converted their JavaScript over to TypeScript lately. It also seems like more and more folks are familiar with TypeScript as it tends to lead to more stable, understandable codebases.
I wonder what folks think about converting thebe into TypeScript. Is that something that @minrk ever considered?
I think the main "con"s I can think of are the initial transition cost, as well as the potential that others won't know the stack and won't be able to contribute. I am curious if others think that the "pros" outweigh the "cons" here.
Based on my personal experience contributing to typescript projects, I am generally strongly against typescript for small projects like thebe, since the tooling is a lot less mature and a lot more complicated and with a lot less documentation/worldwide experience to draw from than standard javascript equivalents. The benefits of the typescript tooling really seem to show up when you have a large, interconnected project like JupyterLab, but thebe is very small and doesn't seem to have a lot to benefit from adopting TypeScript, as far as I can tell. I'd be happy to hear a contrasting view from someone with more positive typescript experience, though, since such things are always improving and my experiences may be pretty out of date at this point.
A compromise you may consider is that Typescript does not require you to convert your old code to work, it can be used incrementally as needed. So if someone wanted to write a new function or model with Typescript they could and it would be fully compatible with all of the non-typescript code in the file/library. "TypeScript’s type inference means that you don’t have to annotate your code until you want more safety."
Since you are already requiring webpack and building/compiling, it wouldn't impact your build workflow especially once webpack and babel are configured.
If you feel that trajectory for Thebe is slowed down such that no large features will need to be added, then it won't be worth the effort to enable Typescript in the config and introduce that complexity. On the other hand, if there is still room to grow and large, new features are likely then having Typescript as an option to support this complex code may be useful.
I could see the kernel management side, for example, moving into it's own file and that benefiting from TS. Over time this may even move into its own library if that makes sense?!
I have spent the last year in TS so my perspective is skewed the other way - I found I was lost a lot today and realized how much I have come to use TS to help me navigate and jump around a library, as well as not make silly compiler-caught mistakes. So a bit of a perspective from a different user group!
One of the things that is interesting about thebe is that it may actually attract more JS devs than python folks? "Bring jupyter into your <react/vue/html/etc> application using thebe!" is a pretty cool value proposition. If we start talking that communities language I could see it being quite helpful.
I certainly understand @minrk's perspective on keeping things simple. These days with VSCode, things are getting easier and easier though!
Also to @minrk's point, it may be worth thinking about the roadmap a bit for thebe as you note that the project will stay very small, and I would like to get a better sense for what you are thinking. I would also love to share how we at iooxa will likely want to use/contribute to parts of the project, and how that might influence the structure of how it is exposed (e.g. headless kernal management, with no UI). We are envisioning selectively showing/editing portions of code, and having more control over where the outputs are placed. So that would require importing the kernel parts (connecting, saving, status state, rejoin logic, etc.) and the output injection, but perhaps not the full jQuery upgrade a pre tag parts. Alternatively, that might be a different project -- I don't know -- but I do think there is significant overlap!
Looking forward to talking more. I am on vacation for a week, so (hopefully) won't respond right away.
Thanks again for your help @minrk on onboarding and pointers as I was working through stuff today.
I wanted to reactive the discussion on this one. Personally, I am heavily swayed to typescript usage.
After experience with typescript development developing in plain Javascript is immediately a more difficult experience as the code is much less readable and a developer has to reply to comments on drilling through code to understand function arguments, data structures etc... so I do think this project would benefit from a TS build, especially as it consumes jupyterlab libraries and manipulates/works with their data structures which are typed. That's personal opinion and preference.
But on a slightly separate point, currently, it would be difficult to use Thebe within a typescript project as it (I believe) provides no type definitions. So it would be down to the consumer to write their own types or bring the library in as js with no types.
If we were to add type definitions as a separate build target (we'd need to build something with types in order to get an automated test), that would be a positive step and increase potential usage even if the library itself stays JS.
One other possibility might be to consider putting types into JSDoc https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html giving both better quality comments and the ability to get type checking into tests.
Two quick thoughts:
- If we can take baby steps in the direction of TS without making the code much more complex, I am +1
- If we can document the code better in any form, I am always +1 :-)