Beebrain now in javascript; questions about tooling

Hey nerdy Beeminder fans, we (mostly @saranli) are trying to make sure all the Beebrain code – – is nice and maintainable and we’re thinking about modules and bundling and Typescript and such. But it’s quite a wild-west out there! Makes us inclined to stick to vanilla JS as we’ve been doing so far.

Status quo is we have six modules – butil, broad, beebrain, bgraph, bsandbox, btest – all implemented as UMD modules, more or less, at the moment.

Here’s a potential wishlist:

  1. Migrate these to Typescript
  2. Have a simple means of transpiling these to a browser bundle (probably browserify and tsify?)
  3. Have a simple means of transpiling to modules easily loadable from node.js for server-side tooling
  4. Be able to use jsdoc (or typedoc?) for clean and easy-to-navigate source documentation

Do you have opinions or guidance on such things? Let’s talk!


My personal (professional?) opinion is that Typescript is very valuable. Those type annotation will help you catch bugs before they go out, and help newcomers get up to speed on a project quicker.

I spent a while migrating my project over to Typescript and it definitely helped me squash a bunch of previously unnoticed errors.

Plus it looks pretty in my VSCode.


+1 to that.
You already use type “annotations” in your code comments in your javascript code. Face it: You want to use a typed variant of Javascript. And you should.
Typescript is indefinitely better than pure JS. I mean, anything is, really :stuck_out_tongue:
Seriousness aside I think Typescript is a pretty low hanging fruit in the “something better than pure js” garden. Go for it.
And it is really quite pretty in VS Code. Almost feels like a decent language :wink:


I don’t exactly know y’all’s background so chances are you all know this already. After all it’s really nothing new. So take this with a grain of… whatever your favourite spice is :slight_smile:

Speaking of low hanging fruits: Not quite as low hanging as Typescript, but even more awesome in terms of reliability, eye-opening and “how could I live without this” is elm, purescript, and the likes.
By eliminating state from the equation you reduce the mental load on your mind when reasoning about code. You no longer have to wonder “Hm, has this happened before this yet? Because then this has the value foo whereas otherwise it would be… no wait, this can’t be. Oh right it can.”.

If you ask me static typing and immutability are the bee’s sneeze when it comes to writing (and more importantly: reading) code. Also you have to write way fewer unit tests. Way fewer. Your compiler is your unit tests. Or at least a good part of them.

Speaking of which, a must read for readable code is of course Clean Code by Martin Fowler but that’s hardly news.


Not sure if this was a joke, but on the off chance you didn’t know, it’s “bee’s knees.”


Hi all;

I completely agree with all the advantages of typescript and static typing, of course, and I am eager to switch. My immediate issues relate more to the choice of tooling and build systems that enable a sufficiently simple development workflow. Since I am relatively new to javascript, and since the choice of build systems and the particular ways in which those are setup have impact on future progress, we wanted to get feedback/suggestions on that front as well.

In particular, I have been toying with using gulp as a build system, browserify for bundling and typedoc for automatic document generation. However, there is a bit of fuzziness as to how to best structure my code into typescript modules that will enable both the browser bundle, the js output for node and the typedoc output to work nicely. There are a number of different ways to do it, I am not sure which one is “best”, so to speak. Since these concepts have changed quite a bit over time for javascript, specific examples, links to “preferred” approaches or any other recommendations would be really helpful. Otherwise, I will just plunge ahead and use a structure that looks acceptable but it seems a bit irresponsible to ask those of you with much more experience than I have.


I like your thinking! In addition to this forum how about you ask on reddit for this kind of advice? I would just poke the /r/javascript subreddit with what you wrote and see what comes out.

In my experience reddit is ideal place for these “get your bearings” sort of questions.

If on some level you “want” types, then TS is pleasant to work with. (Not least because it brings in some future-JS features and then compiles them out to vanilla JS.)

The toolchain world for JS, though, is a mess. It reminds me of a fact from the biological realm. We can tell how important a gene is by how fast and widely it changes. If it never changes, or it’s common across all mammals or something, it’s probably vital. If it changes freely and all individuals have different genes, it’s non-coding junk DNA. The comparison with the constant, two-revolutions-per-year churn of the Javascript build story is unavoidable.

1 Like

I agree with your observations on the toolchain situation, which was in fact the primary reason for my inquiry. But you seem to suggest that they are all equally broken, so the choice does not matter? Keeping the code in pure-ish javascript does sidestep that to some extent, but it seems like it’s not a sufficient excuse to keep off of typescript given its current and future promise.

I will dig into reddit a bit more as was suggested above, and integrate my findings with concrete suggestions that might arrive here as well.

1 Like

Being a little more constructive, many of the projects are perfectly good at doing the job. You just need to snag one from the stream of new ones and use it ~forever.

Since the situation changes so fast, I don’t have a concrete recommendation. I’d suggest looking around at the more recent handful of build tools and choose one that’s (a) actively maintained, (b) can achieve what you need without much extra complexity.

1 Like

As @dreev suggested I’m repeating my mail reply here:

Do consider elm (as someone already suggested). Like typescript, you can do it gradually.
I really think important production code should be as statically and strongly typed as possible. I also think dynamic and weak such as vanilla js is the worst you could do in this dimension.

Since both typescript and elm can be adopted gradually, why not get a feel for them by porting a very small portion of your code for each?


Yay for elm. Also yay for open sourcing! Also JavaScript is valid Typescript since the latter is a superset of the former. But I bet you know that already.

P.S.: You should still go for elm though :upside_down_face:


replying with the word jsbrain since I kept searching for that and not finding this thread :slight_smile:

Second, my goal seems a little weird, I think. It has a turquoise thing until the akrasia horizon, above the road only. Not sure, this might be normal, but it seems a little weird.

1 Like

I’m a tech lead for a major JavaScript project, and I can tell you what we’re doing:

  1. Switching to TypeScript (as we speak I’m reviewing the first PRs)

a. TS was by far the most popular / well supported of the “alternative JS languages”
b. We thought it offered us the best balance of better cognitive load management and ease of adoption for a 150K LOC codebase.

  1. We use WebPack and Babel, and while I can’t speak to the alternatives, these serve us pretty well

Happy to answer more questions if you have them,

1 Like