Koa.js explained

Koa.js is a Node.js framework from the Express.js authors. The biggest feature here is that it uses ES6 generators to elegantly fix the callback hell problem that arises in sufficiently complex Node.js apps

For those who are not familiar w/ ES6 generators, here's an illustration:

Consider an asynchronous app that does several IO operations. Using the currently standard javscript callback style, an application might look like this:

app.authenticate(function(loggedIn) {
     app.fileExists("bla.txt", function(exists) {
        app.readFile("bla.txt", function(text) {
            app.sendToClient(text, function() {
                app.log("operation successful")
            })
        })
    })
})

As you can see there's a lot of nesting once you start doing several things in sequence. As it turns out, this causes all sort of problems:

• hard to throw and catch errors effectively
  
• lots of boilerplate code
  
• even more boilerplate code when doing parallel asynchronous operations
  
• difficult to reason about non-trivial code (e.g. what is in scope where, when there are many parallel things happening?)
  

ES6 generators are basically functions that can pause and later restart from where they paused. The syntax is the same as a regular function, except that it has an asterisk before the function name, and that it allows the `yield` keyword to be used inside of it

function *myGenerator(a) {
    yield a;
}

The` yield` keyword works almost exactly like `return`, except that if you run the function again, the code will continue executing from the next statement after the yield, instead of running the whole function again. (another difference is that yield is an expression) For example:

function *countTo3() {
    console.log(1);
    yield;
    console.log(2);
    yield;
    console.log(3);
}

countTo3(); // logs 1
countTo3(); // logs 2
countTo3(); // logs 3

With this framework, we can then rewrite that nested application kinda like this:

function *myApp() {
  var loggedIn = yield app.authenticate()
  var exists = yield app.fileExists("bla.txt")
  var text = yield app.readFile("bla.txt")
  yield app.sendToClient(text)
  app.log("operation successful")
}

So basically, every time you call `yield` you're explicitly telling the app to "go away and do other stuff" while waiting for expensive IO operations, which makes it very easy to reason about the code, and comes with all the goodness of readability, proper exception stacking, etc.

Very interesting stuff.

Things that suck in AngularJS (a follow-up)

So apparently my last post made it to the HN front page last night. (For the curious, it got ~35k page views in the span of one day, mostly coming from Reddit. That's roughly the same amount of traffic from all other posts in this blog since inception. Heh.)

First, I'd like to thank the people who have pointed out some factual mistakes in my previous post (specifically, the existence of $q/$q.all and $timeout.cancel). I was not aware of $q.all, so the rant ended up being useful for me to learn new things after all :)

The point I was making when I mentioned $timeout though was about orthogonality - e.g. `ng-if` not having an `ng-else` or even an `ng-if-not` counterpart to match `ng-show/ng-hide` - so hopefully my silly mistake didn't detract from the argument.

Anyways, that post is now almost 2 months old, and a lot has happened both in terms of the progress of AngularJS releases, and my own understanding of the framework/ecosystem, so I figured I should add a little update.

What is better

Documentation

In the documentation front, there's been a consistent trickle of PR pull requests on the github project to improve various areas of the documentation. Most notoriously, the directive guide is a lot more example-driven and beginner-friendly. Unfortunately, the old docs for directives are nowhere to be found now and it's now much harder to find explanations of what options are available. But it's definitely more approachable and hands-on.

Also, a variety of good 3rd party resources have been springing up. ng-newsletter.com, for example, hits the ground running with some basics and quickly ramps up to some real-world, in-the-trenches goodness.

3rd Party integration

In a similar note, there are also a growing number of projects offering support for Angular, e.g. KendoUI, the AngularCordova project, etc. This is turning Angular into a much more pragmatic pick for a vast range of projects than many of the newer slimmer frameworks in the data binding arena.

Features

The latest two releases bring a bunch of fixes and pragmatic features (e.g. $interval). On the one hand I do appreciate the new features, but on the other, these are release candidates, which by most definitions, shouldn't include scope creep or major breaking changes...

Which leads me to

What still sucks

Regressions

Regressions are still a very big weakness in AngularJS: the activity in the github issues list spiked after 1.2.rc3 was released, and many of the issues are somewhat serious integration-level problems. Their internal test suite seems to severely lack directive-interop tests, which are critical for a framework with so many interdependent components (I say they're interdependent because they all deal with $scope, often with subtle scope isolation/initialization timing related caveats). The end result is that upgrading Angular is nowhere near the plug-and-play experience of jQuery upgrades.

Other things I didn't mention before

Components

If you haven't seen this term before in the context of AngularJS, components are basically organizational directives, i.e. self-contained ng-includes. They are a mostly useful when a page hosts many loosely related, complex widgets or panels.

One weird design wrinkle is the ambiguity of directive controllers vs regular controllers. Using a directive controller in a component yields less code and clearer modularity, but it breaks the general convention of being able to find all business logic in the controllers folder and DOM stuff in directives. On the other side of the coin, using a regular controller creates more boilerplate code and makes the scoping of inputs and outputs harder to follow.

A big problem with components (and directives in general) is that they can't be used recursively to build things like tree structures. In fact, doing so hangs the browser! The only workaround for this is to use ng-include and shadow variables, which is ugly and confusing from a maintainability standpoint.

Hiring

YMMV here, but in Toronto, hiring an AngularJS developer is pretty damn hard. We've been looking for a while, but without much success (and we even have a dedicated hiring team). For comparison, another discipline where we historically had difficulty finding good candidates was for backend dev positions, and we've been able to hire 5 since the time we've started advertising for the Angular position. (and yes, we're still hiring for both positions and more).

But the bottom line is that, when the time comes to actually expand the team, the number of people with both a strong front-end background (to deal w/ Angular bugs) and the backend engineering chops to follow the AngularJS way (tm) of designing applications turns out to be surprisingly small.

Conclusion

Angular continues to improve its weak areas and gain momentum, but there are still some somewhat big technical issues and quirks that make development challenging. The unique positioning of the framework in the context of specializations within the industry also brings recruiting challenges to the table.

On a separate note, one commenter expressed interest in a post about backbone. Are people interested in analyses of other frameworks as well?

Things that suck in AngularJS

Every once in a while, I find that someone is interested in AngularJS, but not sure if they should stick to their jQuery comfort zone or make the plunge and learn the new thing. It's relatively easy to come across people singing praises to the paradigm shifts that Angular enforces, and there are plenty of tutorials out there showing how to get Angular to do cool stuff without much effort. There's also pretty good explanations out there for some of the more mysterious concepts (like $apply() and transclusions and animations).

The reason I'm writing this is not an attempt to rehash any of those. As it turns out, I've been knee deep doing some pretty neat stuff with AngularJS, RESTful web services, web sockets and other cool HTML5 techs at my job, and I think I've got enough experience to list out some very specific things that aren't that great about Angular. Don't get me wrong, it's a great tool for the stuff I'm doing, but I just feel like complaining a little :)

So, what is sucky in Angular anyways?

Documentation

Docs are a constant complaint in the community: despite being touted as a testable framework, the unit testing guide has been grossly incomplete for ages. Not only that, but most of the API documentation lacks code examples, and makes little to no effort pointing out arbitrary surprises (e.g. ng-selected takes a string instead of a boolean, .bootstrap()'s second parameter is an array, not a string, etc)

The page for directives is another (in)famous part of the docs that, despite relating to one of the most important aspects of the framework, is often derided as being overly dry, and spends more time talking about internals than how to actually create directives.

DOM integration and directives

Many common DOM actions are supported poorly, e.g setting focus on a specific element inside of a repeater, or setting the dimensions/position of an element based on the dimensions/position of another.

Directives - the blessed way of integrating to the DOM - have a lot of optional arguments that don't work well together, and others that break in subtle, hard-to-reason-about ways. For example, ngModelController.$render breaks once you add scope parameters. Transclusion also silently modifies the scope inheritance semantics if scope parameters are added.

Directives can also get stuck in infinite loops when two or more of them act on the same ng-model binding and there are change even handlers.

The problem is aggravated by compiled directives such as ng-repeat and the unstable-only ng-if, since those re-initialize child directives, and can cause event handlers to fire when things haven't really changed.

Another problem with directives nested in ng-repeats is that there's no easy way to control the lifecycle of a directive. Once a list changes (usually due to an ajax call), the redraw performance of a repeater can get unacceptably slow.

The fact that asynchrony is abstracted away in ng-include and the templateUrl argument in directives can also cause difficult to troubleshoot bugs.

I often find that I need to write large comments to explain some subtle side-effect that arises out of an $apply cycle when there are several things happening concurrently in a page.

Business Logic

In addition to the subtle errors that occasionally arise from asynchronous directives, I often run into problems with strictly business-logic ajax as well: for one thing, there's no equivalent to jQuery's $.when, which makes multi-request dependency management difficult (when you hit multiple web services to derive some conjoined information, for example).

It's even more difficult to reason about business logic when your app is big enough to contain nested controllers. You need to carefully manage when controllers are instantiated, what data is ready when, which variables hold promises and when they are resolved, and what is available where; all tied by the scope inheritance mechanism, which is unsettlingly reminiscent of global state.

Bidirectional bindings are two-edged: while they simplify some types of tasks, they make others surprising, e.g. some directives impose types on the variable bound to them, so you sometimes find yourself forced to cast booleans to strings for no seemingly good reason.

Also, I often find myself wrestling against bi-directionality conflicting w/ event-driven programming style, i.e. when calling http methods in response to user actions, as opposed to data changes. This closely relates to the infinite loop problem I mention above and it's a bit of a case of a "pure" system (in the side-effect sense) forgetting to account for the real-life need for non-idempotent actions.

Filter Caching

Repeater filters are not straightforward to cache: if I want to display the length of a filtered list, I have to either re-compute the filtered list (very expensive), or introduce assignment logic into the HTML view (untestable and ugly), or refactor the filter into the controller as part of the data initialization (not desirable for data required to compute derivative metadata).

3rd-Party integration

Calling Angular services, filters and controllers from outside of Angular is verbose and non-intuitive, making it a difficult sell for progressive adoption into a legacy codebase (read: most non-trivial codebases). More importantly, under those circumstances, it sometimes fails in inexplicable undebuggable ways (I'm looking at you, $http, and yes, I called $el.scope().$apply()).

Internal Complexity

I consider myself to be a reasonably good js developer, but the internals of AngularJS are overwhelmingly non-approachable. Even seemingly simple request changes like the ability to abort http requests require massive amounts of design discussion and implementation attempts because of all the levels of abstraction that need to be reconciled. My general feeling is that the API designers don't care much about orthogonality: several features are missing counterpart/complementary mechanisms (e.g. there's a handy `$timeout` but not a `$clearTimeout`, form.setPristine() was added in unstable, but it's not readily available in the controller and it doesn't have per-field equivalents, etc)

A lot of the complexity leaks from the abstraction prominently into developers' day-to-day: most Angular developers have seen the non-helpful "$apply() already in progress" error. Also, in my experience, bugs in AngularJS apps require a relatively intimate knowledge of several layers of abstraction simultaneously, and are much harder to debug than traditional jQuery ones.

Another semi-related note: The unstable branch is rightly named so: it introduces breaking API changes at every release, and new features often have integration problems when combined with other features. It does contain some incredibly useful features, but I'm not even sure how they plan on officially releasing this unstable stuff, since the effort required for developers to migrate from the current stable to the current unstable grows just that much more with every version increment.

Testability

There are no built-in mechanisms for testing directives.

Also, angular-mocks is incompatible with the ng-app directive (and .bootstrap(), for that matter), making in-page testing (using jasmine ConsoleReporter) impossible.

Integration testing can only be done when using ng-app, making multi-application pages untestable. This is a testability showstopper when your project involves a lot of legacy code that is ported gradually (like most legacy-laden projects are).

Parting Thoughts

This is a list of things that could be improved in AngularJS (1.2) from the point of view of someone whose full time job is pretty much to push techonology to the limit. It's not an attempt to promote Ember (which I haven't had the chance to look at) or Backbone/Knockout/jQuery/whatever, all of which have their own merits -- ok, Backbone sucks, but that's for another post :)

Floats and clears in html emails

So I was trying out a new technique (ok more like "so old no one remembers it exists") to see if I could do floating and clearing in emails.

After running a test through Litmus.com, it turns out that it does work in all the major clients (even in Outlook 2010)

The caveat is that you can only float images, but it should make life a bit easier if you develop emails.

To float left:

<img src=”theimage.png” align=”left” />

To float right:

<img src=”theimage.png” align=”right” />

To clear:

<br clear=”left” />

Putting it all together, instead of a using bunch of nested tables, the code would look like this:

<img align="left" src=" bla.png" />

Here's some text beside the image

<br clear="left" />

Here's more text below the image