NodeJS: the beautiful callback err machine

One of the best things about NodeJS callbacks is their consistency. As in, most API calls require one and their method signature always follows the same pattern, and this is the most beautiful bit.

The first parameter of a callback is always an error object (which is null if no error occurred). This seems a little counterintuative at first. When you stop and think about it though, it really isn’t at all. My initial though was that most of the time, it isn’t going to be used, so why isn’t the result of the computation the first parameter? Well, that might be nice, but chances are you’re actually going to have to check to see if an error occurred first, before you start using your results, since if a error did occur, you probably don’t have any results anyway! Secondly, Node is cleverly reminding you that you should check for and deal with errors as they happen by ensuring you define a first parameter in order to define a second parameter to get at the stuff you want.

If the error was the second (or last) parameter the chances are you’d forget to define it, or the lazy would simply neglect to define it. This could happen because in JavaScript all parameters to functions are optional. Just because you do or don’t define parameters to a function, doesn’t mean you can’t call it with or without parameters. The function might not work in either of these cases, but nevertheless it is still possible to call it. It seems that by not coercing the programmer into defining an error parameter and dealing with it their code could become less robust.

The error parameter in the callback function is a necessity of asynchronous programming because errors cannot usually caught with a try/catch block as the execution of the callback function usually doesn’t happen in the block of code surrounded by the try/catch but instead in a later run of the event loop. I much prefer this way of dealing with errors as opposed to searching through my library code to find out if I even need to surround a function call in a try/catch by figuring out if it even does an operation that could possibly throw an error…and you know what, it’s future proof, because even if a function does no operations that could cause an error, it doesn’t mean that in a future version it won’t. By defining an error parameter from the start you can deal with a future mishap, now that is awesome.

Why you should version your Node dependencies using tilde

I’m going to assume you’re already familiar with SemVer and the NPM tilde extension. If not, get your eye holes around those links, particularly the second one.

Ever since I’ve been working on David I’ve seen a lot of version numbers for node projects. I’ve also authored a few npm packages and node projects myself. I find it hard understand why you wouldn’t use tilde to specify the versions of your dependencies. For example:

~1.0.2

This is shorthand for >= 1.0.2 < 1.1.0. It is saying: If the major or minor version increases then I need to retest my code to check it works on the new version, so don’t depend on that. Although, if there are bug fixes, I want them, and whilst I understand that a bugfix release could break my software, it isn’t meant to, so I’m willing to take the gamble.

The idea is that you’re allowing your dependencies to “self update” within a range that is safe to do so. This is really powerful and you should be using it.

I’ve seen a lot of absolute versions for dependencies, which is fine (you know who you are, you have your reasons), but I also see a lot of reckless version ranges: “>= 0.3.14″, “*”, “latest” which are just mad. How can you possibly know your code will still work as your dependencies transition between major and minor version numbers?

David, a dependency management tool for Nodejs projects

I made a thing. I noticed that there wasn’t a way to visualise which of my Nodejs project dependencies were out of date. I saw a library called police which looked pretty awesome, but I wanted to provide a bit more of a service – A quick and easy way for developers to advertise that their project was up to date, in the same way that Travis provides a “badge” that always shows the current build status for your project.

Badges are great, everyone like badges. The Travis badge is an admission by the developers who work on the project that they’re committed to keeping their code base in working order for both consumers of the software and developers alike. Travis proves that their project works by ensuring it can be built successfully and that it passes any unit or integration tests the developers have written. Consumers and developers can see the build status of the project at a glance, without having to clone or checkout the code.

The David badge shows that the project developers are committed to maintaining and improving the project, keeping it up to date, secure, efficient and (hopefully) bug free by keeping abreast of changes in the code the project depends upon.

Of course, an “out of date” David badge can be a indication of a low level of project activity and a hint at the level of support you’re likely to get should you encounter a problem (not much).

Clicking on a David badge will normally take you to the project status page, which lists project dependencies, the version required by the project and the latest version available in the NPM registry. It gives you an idea of the complexity, size and scope of a project and most importantly, it shows developers what dependencies need updating! Here’s some examples

David is written in JavaScript, it uses Nodejs and NPM (of course). It was built from the GRUNTEND base with the Express web application framework.

Check out David here: david-dm.org

JavaScript test for integer / string

I couldn’t find either of these functions that satisfied my edge cases or desire for simplicity so I wrote/adapted some of my own. Feel free to use, modify, distribute without attribution, but I’d be eternally grateful if you did ;)

The test for integer is adapted from this post, which is actually almost spot on, apart from their is_int([0]) returns true, as does any integer in a string.

I’m pretty sure I’ve seen this test for string a hundred times on the internet and in books. It is by far the most robust:

Please let me know if you can break it!

CoffeeScript lazy singleton class instance function

Explanation

“@instance:” allows us to attach an object/value to the Foo class instead of Foo’s prototype. Recall that “@” in CoffeeScript refers to JavaScript’s “this”.

After “@instance:” there is a function that is immediately executed. This function returns a function, closed around a variable called instance. Both these functions have their context (their “this”) bound to the Foo object using CoffeeScript’s wonderful “define and bind” operator “=>” as opposed to the normal function definition operator “->”.

When called, the function that “@instance” ends up referring to simply checks to see if the “instance” variable is empty and if so, assigns a new instance of Foo to it. Newing up a Foo is done using the “@” symbol since the function’s “this” refers to the Foo object. It then returns the instance.

Output

The CoffeeScript above compiles down to this:

Using RequireJS exports with CoffeeScript

If you are using the “exports” object in your RequireJS module definition and happen to also be using CoffeeScript then be careful to either return the exports object at the end of the function or explicitly return nothing from the function by typing “return” on the last line. Like so:

define((require, exports, module) ->
    exports.foo = 'bar'
    return
)

If you don’t return nothing or the exports object CoffeeScript will compile this:

define((require, exports, module) ->
    exports.foo = 'bar'
)

…to the following javascript:

define(function(require, exports, module) {
    return exports.foo = 'bar';
});

Where the return value will be the string ‘bar’. This is no good because if you return a value from your module definition function, RequireJs uses it instead of the exports object. So when you come to require your module, you’ll be passed a String, rather than an object with a “foo” property as you’d expect.

jQuery CDN as A Named Module In RequireJS

If you want RequireJS to fetch jQuery from a CDN, you’ll need to tell it to do so using the “paths” config:

require.config({
paths: {
"jquery": "https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"
}
});

As I understand it, if you want to use the local file fallback code a la html5bp you’re out of luck. For those of you who don’t know, the local file fallback code allows you to load jQuery from your own domain if the CDN version fails to load. It looks like this:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
<script>window.jQuery || document.write('<script src="js/vendor/jquery-1.8.2.min.js"><\/script>')</script>

Arguably, if you’re using jQuery it is likely to be a global requirement rather than a requirement for one or two modules. The same sort of thing with BackboneJS. It might be better to place these global requirements in the HTML for your pages (before the RequireJS script) to save typing ‘jquery’ and ‘backbone’ in all your module definitions.

Play Framework HTML5 input elements

The built in Play input elements are fairly restrictive in that you can’t specify the input type. I wrote a helper template that you can use to generate input elements which have HTML5 type attributes such as url, email, number, search etc. etc.

All you have to do is call the template method, passing the HTML input type as a parameter. For example:

@helper.html5.input(form("website"), '_label -> "Website:", 'type -> "url")

If you have a form field mapped as a play.api.data.Forms.email then the template will automatically infer it’s type so you don’t have to pass the type attribute in with your html attributes:

@helper.html5.input(form("email"), '_label -> "Email:")

If your field has the required constraint, e.g. it is a “nonEmptyText” then the template will add the HTML5 “required” attribute to the field as well.

You can get the source code here.

Stringly Typed Booleans

I’m getting rather hacked off seeing boolean properties typed as strings. Stringly typed is a phrase I learnt off a post from the excellent Coding Horror blog and it describes a phenomena whereby properties that are of a specific type, e.g. Boolean, Date, int, are stored needlessly as strings.

I’m working on a website that communicates with a money laundering service to check whether an individual is “bad” or not. Individuals can pass the test, but importantly it is possible to pass the test with some warning flags raised. If any of the warning flags are raised then an email should be sent off to compliance for them to do…whatever it is they do. Fair enough right?

The warning flags are obviously booleans. There was either a warning raised or there wasn’t – there are no two ways about it (no pun intended). In the serialized response, the warning flags are encoded as “Yes” or “No”…which is understandable. Now, upon receiving the response, it is parsed and turned into an internal representation. This is where things get really weird. The programmer that coded the object that stores the response from the service has decided to encode the warnings as strings, initialised to “”. Which is totally fucking bonkers.

Why?

Well, now our boolean warnings aren’t really booleans – they have WAY more than two possible values and the meaning of these values is subjective. One may consider “”, null, “No” as false, but could conceivably also consider “false” or “0″. We get the same sort of problem with true – “Yes”, “1″, “true” and then we get a whole load of unknown values which is every other possible string in the world. Which might be considered to be true.

So how the hell can any number of programmers work on this piece of code without introducing errors because of differing definitions of truthy and falsey values? Well, they can’t. To illustrate the problem further, even loosely typed languages differ in their boolean coercion, for example JavaScript and PHP:

<script>
if("0") alert('Opposite day!');
</script>

<?php
if("0") echo 'Opposite day!';
?>

JavaScript considers “0″ true but PHP considers it false. Personally I think JavaScript is “right” here, but as I said before, it is totally subjective.

The icing on the cake is of course the extra code you have to write to check the truthy or falsey string values. Something along the lines of “if x is not null and not empty and not the word No then it is probably true…probably”, which would otherwise have been coded as “if x then true” if x was a boolean – which is orders of magnitude shorter.

Of course, there are some bat shit crazy strongly typed languages that allow you to assign null to a Boolean, but that is a different story altogether.

High level overview of the workflow you’ll probably grow to know and love whilst using Git and GitHub

First of all, read this to gain an understanding of the concepts involved in version control:
http://guides.beanstalkapp.com/version-control/intro-to-version-control.html

Having read the above, you should now understand that Git is s distributed VCS (version control system). You should understand that each project you work on is stored in a repository, and that everyone working on a project will have a copy of the repository (Git calls these clones) on their local computer. There is also a copy of the repository on the GitHub website.

When you begin working on a project you’ll usually use the GitHub website to create a git repository and then CLONE that repository onto your computer. Alternatively you can create a repository and then PUSH it up to the GitHub website.

If you begin working on an existing project you’ll simply CLONE the repository onto your local computer.

Either way, you’ll now have a local repository that you can use to work on the project.

Once you have made changes to files, you need to COMMIT them to your local repository. You should commit often, with a message explaining the changes you’ve made. This’ll be useful should you need to revert a change at a later date as you’ll be able to find the commit easier. It also helps others understand the reasons behind the changes you’ve made.

When you are ready for other people working on the project to see your changes you need to copy them back up to GitHub. Git calls this PUSH. So, in other words you need to PUSH your commits to GitHub.

Once you have PUSHed, others can then copy them from GitHub into their own copy of the repository. This is called PULL.

So, what happens if someone PUSHes changes to a file you’re already working on? Well, when you come to PUSH, Git won’t allow you to do so and will ask you to PULL changes from the server so that your files can be merged together. When you next PULL you’ll be prompted to MERGE the two files and then COMMIT the merge result. You’ll then be able to PUSH to GitHub.

Lastly, if you’re likely to be working on the site for an extended period of time (like a couple of days or weeks) and don’t want your changes to be put onto the example.com site, you should still use the COMMIT and PUSH workflow, but you should create a BRANCH first. This means that your code is still being backed up to a secure location and you won’t lose your work should your computer get stolen or blow up or something. It also means the main line of development (called MASTER) remains untouched until you MERGE your BRANCH.