Feedback driven development workflow

Today I spent some time working on two toy projects to get a better understanding of Typescript. My primary goal was to make a slack bot that could answer common questions on git. I decided to first make a blackjack app in Typescript because I had only briefly used it before and I wanted to have a quick refresher on the major concepts of Typescript in a domain that's very familiar (e.g. blackjack / playing cards). 

For me, learning the actual typescript type syntax hasn't been bad since I dabbled briefly in Go and I've been reading a bit on Typescript and Flow Type. There was a bit of learning curve just figuring out the dev workflow for using Typescript since it means you need to transcompile before you can run your app. I used Visual Studio Code since it offers a really nice balance of the core benefits of an IDE (e.g. intellisense + debugging) with the speed and ease of use that lightweight text editors such as Sublime offer.

Setting up Visual Studio Code

If you use Visual Studio Code to compile your typescript files, you need to create two files in your project:

  1. tsconfig.json (https://github.com/willchen90/typescript-blackjack/blob/master/tsconfig.json)
  2. .vscode/tasks.json (https://github.com/willchen90/typescript-blackjack/blob/master/.vscode/tasks.json)

Then you can run your build task within VS Code and it automatically watch - you can see the results in the bottom left corner. The two issues that I ran into is that: 1) you need to re-run the watch task when you add new file (it looks like this will be solved in Typescript 1.7.X - https://github.com/Microsoft/TypeScript/pull/5127) and 2) you don't know when it's "done" compiling since the watch task never ends, although the Typescript compiler seems to run very fast so that wasn't really an issue.

TSD - Typescript Definition Manager

The other thing I discovered is this tool called TSD (Typescript Definition manager) which is basically a package manager like Bower for typescript definitions (it seems to be a flat dependency structure, although I didn't dig in too deeply on this today). This makes it much easier to add typescript definitions as you essentially only have to manage one Typescript definition file from your application code (typings/tsd.d.ts). The main commands are "tsd init" and "tsd install lodash --save". 

Note: there seems to be a bug where if you include the flag before the package name, the command isn't executed properly. (e.g. tools like npm don't care if you do "npm install --save lodash" or "npm install lodash --save").

Starting with the Slack chatbot client

Initially I was hoping to just run the chatbot client against the actual Slack API using Slack's somewhat supported node.js client (https://github.com/slackhq/node-slack-client), however I quickly ran into the rate-limiting issue (HTTP 429 - Too Many Requests). It seems like Slack has a pretty conservative rate-limiting policy of one message per second. I'm not sure if there's a way of "pay to play" to raise the limit or Slack really dislikes automated messages. 

Making a mock "chat client"

As a workaround I used a "mock" chat client using node.js standard input and standard output interface using the readline npm module. The key to doing it was to isolate the slack client-specific code (which I had essentially copy and pasted from slack's example file) with the rest of the code I was developing.

It was actually a really simple implementation and could be reused for a variety of apps. The next issue I wanted to solve was not having to manually restart the node.js app everytime I made an update. Of course it's not that much work, but it's annoying to have to remember to do everytime so I used an npm module called nodemon. It's very popular for local development because it restarts your node app whenever it detects a file change. If you're creating a REPL-like app (e.g. a chat client), you want to make sure you set the "restartable" flag to false, otherwise nodemon will listen to stdinput and you will get undesirable behavior like repetition of stdinput. It wasn't really clear what caused this from the Readme, but I figured it out by looking at a similar GitHub issue.

Debugging!

For some reason, using the debugger seems to be pretty uncommon in node.js land. I think it's a combination of most JS developers using text editors (e.g. Sublime, Atom) without debugger support and that debugging transcompiled code (e.g. Coffeescript, Typescript) is oftentimes a pain. Luckily with source maps and new tools like Visual Studio Code, it seems like debugging is now a lot easier and actually fun to do. My recommendation for using the debugger in Visual Studio Code is to rely on using the "Attach" setting, which is essentially hook into / debug a node process that you've already started. I've included my example VS Code configuration. This is usually more straightforward than trying to launch a new node process through an IDE.

Unit testing

Eventually it just got too tedious to manually check outputs, even with the mock client. I created a small suite of unit tests using Mocha and Chai, which I was familiar with. Mocha is a very popular framework with a helpful, easy to look at website. The two tips that I have are: 1) use the watch flag (it's like nodemon for testing) and 2) using "source-map-support" npm module so your error stack traces point to your original source files, not the transcompiled .js files. For example of these two tips in action, look at my simple one-line "npm test" script.

I even launched the debugger in Mocha. Use the "--debug-brk" and not the "--debug" flag, otherwise you won't be able to attach your VS Code debugger to the Mocha test process. 

Wallaby.js - unit testing on steroids

Lastly, I want to mention Wallaby.js, which displays unit test results in your editor. It's looked very promising for a while, but I had some trouble using it in WebStorm a while ago (it seemed like the test results didn't update properly). I decided to give it another go since they just launched a Beta for Visual Studio Code (which recently open sourced their codebase and have developed an extension system). I only briefly played around with it, but it seemed quite reliable and I really enjoyed having the console.log information display at the bottom bar, and the code coverage so prominently displayed while you're coding. In essence, Wallaby.js seems like a next-generation testing tool. I'm going to spend some more time with it, and try to use it regularly at work.

To conclude: get more and faster feedback

Even though these were two really short projects (and they're incomplete), I've learned a tremendous amount just from exploring Typescript and all these other tooling that play well with Typescript. I was initially worried that using Typescript would slow me down because 1) I wasn't too familiar with it and 2) it would be time-consuming to write type annotations. In the end, I think those concerns were proven false as I was able to be very productive with Typescript in a short amount of time. Getting errors from Typescript within VS Code was a huge help, and I was able to catch silly mistakes (e.g. typos, logic errors, etc.) in a very quick cycle. I think in the future, I will always consider using Typescript if I'm starting on a new Javascript project. The only downside of Typescript is that it takes a bit of setup to get a smooth workflow and some of the tooling lags behind Javascript (ES6) (e.g. linting, style-checking). However, I think those downsides are far outweighed by the benefits you get from it, and it feels like the Typescript ecosystem is alive and well from the open and active development by Microsoft on their typescript GitHub repo to the new Angular 2 framework that is being developed in virtually all Typescript.


Link summary: 

Tools that I used today:
  • Typescript - (to install the compiler: npm install -g typescript)
  • Visual Studio Code - https://code.visualstudio.com/
  • Mocha & Chai - https://mochajs.org/
  • Nodemon - https://github.com/remy/nodemon
  • Wallaby.js - wallabyjs.com
  • Source map support - https://github.com/evanw/node-source-map-support

Toy projects:

  • Blackjack - https://github.com/willchen90/typescript-blackjack
  • Git chatbot - https://github.com/willchen90/typescript-gitbot