Unix and Node: Command-line Arguments

01 Mar 2012 | By Alex Young | Comments | Tags node tutorials essay unix documentation

Shebang Bootcamp

Writing an executable script with Node begins with the shebang: #!, followed by the path to a Node executable. Not all Unix systems use the same file system layout, and not all users want to install Node in the same place. Since the shebang must specify an absolute path, a common way around this is to introduce a level of indirection through env:

#!/usr/bin/env node

This can be seen in many popular Node modules, and in other scripting languages too. If I try and run a script like this in my shell, I’ll get an error:

➜ ./echo.js
zsh: permission denied: ./echo.js

I have read permission on the file, but it isn’t executable:

➜ ls -l
-rw-r--r--  1 alex  wheel  21  1 Mar 17:24 echo.js
➜ chmod u+x ./echo.js 
➜ ls -l
total 8
-rwxr--r--  1 alex  wheel  21  1 Mar 17:24 echo.js

Here I’ve used chmod to set the executable flag for the user that owns the file. Most people use the octal notation for setting permissions, which looks complicated but isn’t as hard as it seems.

Argument Vector

Command-line arguments are available through the process global in an array called argv. This term comes from “argument vector”, influenced by C where it’s conventional to name the argument count and argument vector this way:

int main(int argc, char *argv[])

Technically these parameters could be named anything, but this is a strongly followed convention.

Compared to C, JavaScript’s array is a handy type for representing arguments:

#!/usr/bin/env node

console.log('Arguments:', process.argv.length);
console.log(process.argv);

Running this script with no arguments shows what the script was run with:

Arguments: 2
[ 'node', '/private/tmp/unix-node/echo.js' ]

Conversely, passing in arguments looks like this:

➜ ./echo.js --text JavaScript in the shell
Arguments: 7
[ 'node',
  '/private/tmp/unix-node/echo.js',
  '--text',
  'JavaScript',
  'in',
  'the',
  'shell' ]

Handling more complex arguments takes a little bit of work, so it’s often preferable to offload the effort to a suitable module. However, some scripts have simple requirements, so array manipulation of process.argv may suffice. This example is from Node’s cluster.js file:

exports.start = function() {
  amMaster = true;

  if (process.argv.length < 1) {
    console.error('Usage: node cluster script.js');
    process.exit(1);
  }

  var args = process.argv.slice(2);
  var scriptFilename = args.shift();

The length of process.argv is validated to ensure the expected option has been supplied, and process.exit(1) is called if validation fails. This is interesting because an argument has been supplied to process.exit. Why 1?

Exit Status

Unix and Unix-like systems use a convention that a non-zero exit status from a program is an error. In C, EXIT_FAILURE is a macro that can be used to denote this, and on POSIX systems this value is 1. Changing the previous example to return a non-zero exit code looks like this:

#!/usr/bin/env node

console.log('Arguments:', process.argv.length);
console.log(process.argv);

if (process.argv.length < 3) {
  process.exit(1);
}

Running this script with no arguments should return 1. However, look what happens:

➜ ./echo.js 
Arguments: 2
[ 'node', '/private/tmp/unix-node/echo.js' ]

… nothing? There’s no error message or anything! This is actually a good thing – think back to the philosophies behind Unix, in particular Doug McIlroy’s quote:

Write programs to handle text streams, because that is a universal interface.

In a world based around text streams, we don’t want default behaviour that’s too noisy. If someone built upon this script, they’d rather deal with a concrete error status. This value can be obtained in most shells by reading $?:

➜ echo $?
1

Option Parsing Libraries

The two most popular option parsing libraries for Node are Optimist (License: MIT/X11, npm: optimist) and Commander.js (GitHub: visionmedia / commander.js, License: MIT, npm: commander) by TJ Holowaychuk. These are both well-maintained libraries by active members of the Node community.

Optimist has its own argv object that can deal with grouped, long, and short options, and can even display usage:

#!/usr/bin/env node
var argv = require('optimist')
    .usage('Usage: $0 -x [num] -y [num]')
    .demand(['x','y'])
    .argv;

console.log(argv.x / argv.y);

Commander.js has a chainable API that’s like a DSL for option processing:

#!/usr/bin/env node

var program = require('commander');

program
  .version('0.0.1')
  .option('-p, --peppers', 'Add peppers')
  .option('-P, --pineapple', 'Add pineapple')
  .option('-b, --bbq', 'Add bbq sauce')
  .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
  .parse(process.argv);

console.log('you ordered a pizza with:');
if (program.peppers) console.log('  - peppers');
if (program.pineapple) console.log('  - pineappe');
if (program.bbq) console.log('  - bbq');
console.log('  - %s cheese', program.cheese);

The program’s usage is automatically generated.

Conclusion

In Node, powerful option parsing is only an npm install away. The built-in process.argv array is also convenient and easy to manage for simple situations. Just remember to exit programs with conventional status codes, or angry shell scripters may fill up your GitHub issues before you know it!

Node Roundup: Shrinkwrap, Connect 2.0, ClientSide, Pretty-Data, Clusterhub, Introspect

29 Feb 2012 | By Alex Young | Comments | Tags node modules connect npm scaling
You can send in your Node projects for review through our contact form or @dailyjs.

Shrinkwrap

As of version 1.1.2, npm has a new feature called shrinkwrap. This allows dependencies to be locked down across the full module hierarchy. Running npm shrinkwrap will generate a npm-shrinkwrap.json file that contains the exact version of everything installed in node_modules/.

This makes deploying Node apps easier to manage, because new releases of installed modules can (and probably will) be released during development.

Dave Pacheco had some interesting things to say about how Joyent use Node as part of this feature’s announcement:

It’s not exactly news that Joyent is heavy on Node. Node is the heart of our SmartDataCenter (SDC) product, whose public-facing web portal, public API, Cloud Analytics, provisioning, billing, heartbeating, and other services are all implemented in Node. That’s why it’s so important to us to have robust components (like logging and REST) and tools for understanding production failures post mortem, profile Node apps in production, and now managing Node dependencies.

Connect 2.0

TJ Holowaychuk has announced the release of Connect 2.0 (GitHub: senchalabs / connect, License: MIT, npm: connect). The Connect documentation is now much improved, and tests have been rewritten to use Mocha.

New features include:

  • cookieSession() middleware for cookie-only sessions
  • compress() middleware for gzip / deflate support
  • json() middleware for parsing application/json

One major change is connect(), which replaces connect.createServer():

var connect = require('connect')
  , http = require('http')
  , https = require('https');

var app = connect()
  .use(connect.logger('dev'))
  .use(connect.static('public'))
  .use(function(req, res){
    res.end('hello world\n');
  })

http.createServer(app).listen(80);
https.createServer(tlsOptions, app).listen(443);

TJ notes that previous versions of Connect used a connect.Server object that inherited from net.Server. The newer connect() method simply returns a Function, which can be used with http.createServer() or https.createServer(), thereby simplifying supporting both HTTP and HTTPS.

ClientSide

ClientSide (GitHub: jgallen23 / clientside, npm: clientside) by Greg Allen is a command-line tool for packaging client-side code from scripts that use CommonJS modules. It can read a package.json to determine how your library is structured.

The author is planning to write Connect middleware, and has shipped the project with thorough Mocha/Chai tests.

Pretty-Data

Pretty-Data (GitHub: vkiryukhin / pretty-data, License: MIT/GPL, npm: pretty-data) by Vadim Kiryukhin can beautify or minify JSON, CSS, and XML. Rather than using existing libraries, the author has opted to use his own regular expression-based parsing. This reduces the module’s dependencies, so if you’re looking for something lightweight, it might fit the bill.

The project’s site also has live demos that show off the library’s main features with data from sources like Yahoo! Weather and Google’s minified CSS.

Clusterhub

Clusterhub (License: MIT, npm: clusterhub) by Roly Fentanes is a bit like interprocess communication for Node:

var cluster = require('cluster')
  , numCPUs = require('os').cpus().length
  , hub = require('clusterhub');

if (cluster.isMaster) {
  // Fork workers
  for (var i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

} else {
  hub.on('event', function(data) {
    // Do something with `data`
  });

  // Emit event to all workers
  hub.emit('event', { foo: 'bar' });
}

Each hub has an in-memory EventVat key/value store. Roly has written some example apps, including clusterchat.

If you’re looking to get more out of a CPU by running several Node processes, then this looks like a simple but potentially fast option. The author notes that the project is still experimental, but given that he’s written some Mocha tests it should be relatively hackable.

Introspect

Introspect (License: MIT, npm: introspect) by Kilian Ciuffolo provides Function introspection:

var introspect = require('introspect');

function fn(foo, bar, callback) {
  // function body
}

var arguments = introspect(fn);
console.log(arguments);
// [ 'foo', 'bar', 'callback' ]

Kilian has included benchmarks, tests written with Vows, and provided instructions on how to run them.

jQuery Roundup: TOC, Curtain.js, Griffin.editor, imgg

28 Feb 2012 | By Alex Young | Comments | Tags jquery plugins ui effects editors
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

TOC

TOC (GitHub: jgallen23 / toc, License: MIT) by Greg Allen will generate a table of contents for a page, and automatically highlight the current section. Basic usage is simply $('#toc').toc();, but it supports some configuration options as well:

$('#toc').toc({
  'selectors': 'h1,h2,h3',   // elements to use as headings
  'container': 'body',       // element to find all selectors in
  'smoothScrolling': true,   // enable or disable smooth scrolling on click
  'prefix': 'toc',           // prefix for anchor tags and class names
  'highlightOnScroll': true, // add class to heading that is currently in focus
  'highlightOffset': 100     //offset to trigger the next headline
});

The design of the plugin allows multiple tables of contents to be used on a page, and the author is planning to add support for Zepto and Ender.

Curtain.js

Curtain.js (GitHub: Victa / curtain.js, License: MIT) by Victor Coulon and submitted by Hirvesh displays pages using an effect similar to a slide show. It supports keyboard shortcuts and conventional scrolling. The panels that make up the page will automatically resize to fill the window.

The plugin is invoked by $('.curtains').curtain() and expects an ordered list:

<ol class="curtains">
  <li class="cover">your content</li>
  <li>
    <div class="fixed"> <!-- if you need a "fixed" content -->
      Fixed content
    </div>
  </li>
</ol>

Panels can also be added dynamically using $('.curtains').data('plugin_curtain').insert().

Griffin.editor

Griffin.editor (GitHub: jgauffin / griffin.editor, License: MPL) by Jonas Gauffin is a jQuery-enhanced, zero configuration, textarea. It supports markdown, but the author notes other formats are easily supported, access keys, and syntax highlighting. It uses jQuery UI, and is easily set up with a call to $('.editor').griffinEditor() and suitable HTML.

The griffin.editor / Demos folder contains examples of how to use the plugin.

imgg

imgg (GitHub: bugzu / imgg, License: MIT) by Gaurav Sharma displays images using an animated mosaic effect. It’s used by passing an array of image locations to $().imgg:

$('#gallery').imgg({
  images: ['images/img11.png', 'images/img22.jpg', 'images/img33.jpg']
});

The author has provided sample images and CSS.

Chaplin, KinectJS, Inject, Minion

27 Feb 2012 | By Alex Young | Comments | Tags kinect backbone.js oo modules commonjs

Chaplin

Chaplin (License: MIT) from Moviepilot and 9elements is an example architecture using Backbone.js. It features lazy loading through RequireJS, module inter-communication using the mediator and publish/subscribe patterns, controllers for managing UI views, Rails-style routes, and strict memory management and object disposal.

While developing web applications like moviepilot.com and salon.io, we felt the need for conventions on how to structure Backbone applications. While Backbone is fine […], it’s not a framework for single-page applications.

All Chaplin needs is a web server to serve the client-side code. The example app, “Facebook Likes Browser”, even includes client-side OAuth 2.0, thereby demonstrating client-side authentication.

KinectJS

KinectJS (License: MIT) aims to bring Kinect controls to HTML5. The author has created some KinectJS demos and KinectJS YouTube videos, so with the required hardware it should be possible to try it out.

The client-side JavaScript is only one part of the implementation – the other is an Adobe AIR application that provides the bridge to the Kinect drivers. The AIR application isn’t currently open source, but the JavaScript code is MIT licensed.

Inject

Inject (License: Apache 2.0, GitHub: linkedin / inject) from LinkedIn is a library agnostic dependency manager. It adds CommonJS support to the browser, and the authors have created a Inject/CommonJS compatibility document to show what exactly is supported. Resources can be loaded cross-domain, and the AMD API is also supported. Inject also has a lot of unit tests, written with QUnit.

Once Inject is loaded, it’ll find and load dependencies automatically:

<script type="text/javascript" src="/js/inject.js"></script>
<script type="text/javascript">
  require.setModuleRoot('http://example.com/js/modules');
  require.run('program');
</script>

Now if program.js looked liked this:

var hello = require('hello').hello;
alert(hello());

Then Inject will load the hello module.

Inject finds the dependencies automatically and loads them asynchronously. If a developer changes some downstream dependency - for example, changes hello.js to depend on new-name-module.js instead of name.js - your code will keep working because Inject will automatically find and download the new dependencies on the next page load.

MinionJS

MinionJS (License: MIT/X11, npm: minion) by Taka Kojima is a small library that provides classical inheritance for Node and browsers:

minion.require('example.Example', function(Example) {
  var instance = new Example();
      instance.doSomething();
});

Minion also includes a publish/subscribe implementation. All classes have subscribe and publish methods which can be used to bind callbacks to notifications.

Finally, Minion has a build script that can be used to package classes for client-side deployment.

Ender Roundup: Radio.js, one.color, Hypher

You can send in your Ender-related projects for review through our contact form or @dailyjs. Be sure to also update the Ender package list page on the Ender wiki.

Radio.js

Radio.js (GitHub: uxder/Radio, Licence: MIT, npm / Ender: radio) by Scott Murphy is a simple publish / subscribe library with a well-designed chainable API. Radio.js operates through the $.radio() method from within Ender.

//create topic called changeTabEvent and subscribe myFunction
$.radio('changeTabEvent').subscribe(myfunction);
//publish to the topic changeTabEvent
$.radio('changeTabEvent').broadcast(data);
//unsubscribe myFunction from the topic changeTabEvent
$.radio('changeTabEvent').unsubscribe(myFunction);
//do all of the above in one line via chaining
$.radio('changeTabEvent').subscribe(myFunction).broadcast(data).unsubscribe(myFunction);

Event “channels” are created by the main radio() method. You can then use the three main API calls to interact with the channels: subscribe(), broadcast() and unsubscribe(), each able to take different types and numbers of arguments.

Radio.js will also work as a stand-alone browser library and in node.js.

one.color

one.color (GitHub: One-com/one-color, Licence: BSD, npm / Ender: onecolor) by Peter Müller and One.com is an amazingly comprehensive color toolkit. It implicitly converts between RGB, HSV, HSL and CMYK color spaces with or without alpha transparency. Its API is chainable for composing, adjusting, and serializing color values. A demo page gives you some idea of the potential of one.color.

one.color

$.color('rgb(102, 76, 230)'). // Can parse CSS color strings
    lightness(+.2, true).     // Implicit conversion to HSL
    red(-.1).                 // Implicit conversion back to RGB
    hex();                    // "#00a6f2"

one.color will also work as a stand-alone browser library and in node.js.

Hypher

Hypher (GitHub: bramstein/hypher, Licence: BSD, npm / Ender: hypher) by Bram Stein is a small hyphenation engine compatible with Hyphenation.js language objects.

Hypher adds soft hyphens to text strings (Unicode: U+00AD, HTML: &#173; or &shy;) according to language rules as defined in the patterns objects. Modern browsers then use these soft hyphens to break words where wrapping is required, otherwise they are invisible.

Hypher comes with a large number of language patterns which are also available in the npm repository as hyphenation.lang (e.g. hyphenation.en-us or hyphenation.fr). Simply include hypher and at least one language pattern in your Ender build.

// generates 'Hy|phen|ation is use|ful when cen|ter jus|ti|fy|ing a text.'
// where `|` is a soft hyphen
$('<p>Hyphenation is useful when center justifying a text.</p>')
  .appendTo('body')
  .hyphenate('en-us');

Hypher is also available as a jQuery plugin and will work as a stand-alone browser library and in node.js.

Tidbits and updates

Some minor notable items since the last Roundup:

Bonzo goes 1.0.0

Bonzo, the DOM manipulation library included in The Jeesh, has received a lot of minor fixes this week and its test suite has been significantly expanded, so much that a bump to 1.0.0 seemed appropriate.

Minor Qwery update

Qwery, the selector engine included in The Jeesh had some minor performance improvements, particularly for IE8, and can now be configured to turn off use of native querySelectorAll if required: $.configure({ useNativeQSA: false }).

Bean does better delegation

Bean, the event manager included in The Jeesh, has received some delegation-love, fixing bugs related to clone() and erroneous event.currentTarget values.

Bean is also likely to see a change in the implementation of on() that will make it (mostly) compatible with the implementations in Prototype, jQuery and Zepto. Further details are available on GitHub.

Ender via CDN

After the flurry of recent activity on core Ender modules, Dustin Diaz has updated the The Jeesh and a more bulky Ender build on S3 this week, so is these builds suit your needs then point your script tag to one of these CloudFront URLs:

The Jeesh (Qwery, Bonzo, Bean, domReady)

http://cdn.enderjs.com/jeesh.js
http://cdn.enderjs.com/jeesh.min.js

Jeesh++ (Qwery, Bonzo, Bean, domReady, Reqwest, Morpheus, Valentine, Bowser, $script.js)

http://cdn.enderjs.com/ender.js
http://cdn.enderjs.com/ender.min.js

Twitter’s Bootstrap for Ender

Along with the release of Bootstrap v2, an Ender compatible version is now available on npm. Unlike the v1.x port, this new version makes each plugin available separately so you only need to include the ones you intend to use in your Ender build.

With all plugins installed, a minimal Ender build for full Bootstrap functionality comes in at a little under half the size of the equivalent jQuery Bootstrap.

Further details available on the new ender-bootstrap repository.

Getting Started with the Chai Assertion Library

23 Feb 2012 | By Jake Luer | Comments | Tags testing node tutorials

Jake Luer is a Node developer and consultant focused on helping to shape the next-generation of mobile and web applications. He is logicalparadox on GitHub and @jakeluer on Twitter.

Chai (GitHub: logicalparadox / chai, npm: chai, License: MIT) is a BDD / TDD assertion library for Node and the browser that can be delightfully paired with any JavaScript testing framework.

Chai aims to be an expressive and easily approachable way to write assertions for JavaScript project testing. Developers have already started expanding on Chai’s available language through plugins such as spies, mocks/stubs, and jQuery support. Starting out, however, I think you will find Chai’s language easy to pick up and powerful enough for even the most unruly of testing scenarios.

The motivation for Chai came about with the release of Mocha, TJ Holowaychuk’s incredible testing framework that can also be used with both Node and browsers. At the time, there was no apparent assertion library to pair with it that would allow for the same assertions to be used on both server and client with the inherent simplicity that Mocha provides.

The Basics

To get started in Node, add chai to your package.json under devDependacies. Or, if using in the browser, include the script in your page:

<script src="http://chaijs.com/chai.js" type="text/javascript"></script>

Chai currently supports all modern browsers: IE 9+, Chrome 7+, FireFox 4+, Safari 5+.

Assertion Styles

Chai comes packaged with three different assertion styles: expect, should, and assert. The expect and should interfaces are similar in that they are based on self descriptive language chains. The assert interface is similar to Node’s assert module but includes many more assertions.

For our examples we will assume the following:

var chai = require('chai')
  , foo = 'bar'
  , beverages = { tea: [ 'rooibos', 'matcha', 'oolong' ] };

First up is the BDD styles: expect and should:

var expect = chai.expect;
expect(foo).to.be.a('string').and.equal('bar');
expect(beverages).to.have.property('tea').with.length(3);

As you can see, the expect interface provides a function as a starting point for chaining your language assertions. Alternatively, the should interface extends Object.prototype with the single getter should as the starting point:

var should = chai.should();
foo.should.be.a('string').and.equal('bar');
beverages.should.have.property('tea').with.length(3);

Finally, the TDD style is exposed through the assert interface. This features the classic assert.test notation.

var assert = chai.assert;
assert.equal(foo, 'bar', 'Foo equal bar');
assert.length(beverages.tea, 3, 'We have three types of tea');

A few assertions that are also available are deep equality, exception testing, and instanceof. The full API documentation is available for all styles on Chaijs.com.

Extending Chai with Plugins

Though Chai provides all the basics of testing, we all know there can be much more to it. Chai can easily be extended through plugins that can add-on or modify Chai’s Assertion prototype. One example of this is logicalparadox/chai-spies, a basic function spying implementation.

Here is a simple example to assert that events have been emitted using chai-spies:

var chai = require('chai')
  , spies = require('chai-spies');

chai.use(spies);

var should = chai.should()
  , myspy = chai.spy(originalFn); // originalFn not required

eventemitter.on('some event', myspy);
// ... testing
myspy.should.have.been.called.twice;

The plugin approach makes it easy to use Chai for complex testing scenarios. Chai-spies is also a good resource for developers looking to build plugins that work for both Node and the browser.

These awesome developers have already started to build on Chai:

chai-jquery (License: MIT) by John Firebaugh provides deep jQuery integration with Chai’s `should` and `expect` styles.
$('#header').should.have.class('foo');
expect($('#title')).to.have.html('Chai Tea');
sinon-chai (License: WTFPL) by Domenic Denicola extends Chai with assertions for use with the Sinon.js mocking framework.
mySpy.should.have.been.calledWith('foo');
expect(mySpy).to.have.been.calledWith('foo');
jack (License: MIT) by Veselin Todorov is a mock/stub library that can be used as a stand-alone utility or with Chai.
mockedMethod.should.have.been.called.twice;
expect(mockedMethod).to.have.been.called.twice;

Node Roundup: Mongorito, Memcacher, Restify, Versionator, FeedSub

22 Feb 2012 | By Alex Young | Comments | Tags node modules mongo rss feeds express

Mongorito

Mongorito (License: MIT, npm: mongorito) by Vadim Demedes is a new MongoDB ODM with some interesting features: it has built-in caching using Memcacher (another module by the same author), and a small codebase by building on Mongolian. Automatic caching can even be set up, simply by setting a Memcached host using Mongorito.cache.

Mongorito has a model class, and the author gives examples in both JavaScript and CoffeeScript:

var Post = (function(){
  function Post() {
    Post.__super__.constructor.call(this, 'posts');
  }

  Post.prototype.validateTitle = function(callback) {
    if (!this.title) {
      callback(false);
    } else {
      callback(true);
    }
  }
})();

Post = Mongorito.bake(Post);

Post.find(function(err, posts){
  var length = posts.length;
  for (var i = 0; i < length; i++) {
    // posts[i] is an instance of the Post class
    posts[i].remove(function() {
    });
  }
});

The model definitions offer an alternative to Mongoose, and may appeal to those working on CoffeeScript-based projects:

class Post
  constructor: ->
    super 'posts'

Post = Mongorito.bake Post

post = new Post
post.title = 'About Mongorito'

post.save (err) ->
  # saved!

Despite being a new library, the author says the code is being used in production software, and he’s written some Mocha unit tests.

Memcacher

Memcacher (License: MIT, npm: memcacher) also by Vadim Demedes adds additional functionality to the Memcached module by Arnout Kazemier, in the form of tags and chainable methods:

Client
  .set('test-key', 'value', 2592000, ['some-tag'])
  .get('test-key', function(err, value) {
    // This callback intentionally left blank
  });

It’s a small but significant addition that should help those working with Memcached.

Restify

Restify (GitHub: mcavage / node-restify, License: MIT, npm: restify) by Mark Cavage is a new Express-inspired framework for building REST APIs. It includes both client and server support, so it’ll consume REST services as well as serve them.

Creating a basic server and setting up middleware looks just like Express:

var server = restify.createServer({
  name: 'myapp',
  version: '1.0.0'
});

server.listen(8080, function() {
  console.log('%s listening at %s', server.name, server.url);
});

It made me wonder if it’s Connect middleware compatible, because setting up routes looks the same as Express as well:

server.get('/echo/:name', function(req, res, next) {
  res.send(req.params);
  return next();
});

There are a healthy amount of unit tests (built with the tap module), detailed documentation, and a demo app.

Versionator

Versionator (GitHub: serby / versionator, License: New BSD, npm: versionator) by Paul Serby is Connect middleware for managing static asset caching. The basic middleware allows a global application version to be set, and adds an extra path to asset URLs so they’ll effectively be expired when the app version changes:

app.version = '0.1.0';
var basic = require('versionator').createBasic(app.version);

app.configure(function() {
  app.use(basic.middleware('v' + app.version))
    .use(express.static(__dirname + '/public', { maxAge: 2592000000 }));
});

Assuming a client-side script is at /js/app.js, it’ll now be available from /js/v0.1.0/app.js. There’s a Jade helper so the original URL can be referenced in templates.

There’s also ‘mapped’ middleware, which will only change resource locations when the files have changed.

FeedSub

FeedSub (License: MIT, npm: feedsub) by Roly Fentanes is an event-based feed downloader, that works the way a Node developer would expect:

var FeedSub = require('feedsub');

reader = new FeedSub('http://feeds.feedburner.com/dailyjs', {
  interval: 10 // check feed every 10 minutes
});

reader.on('item', function(item) {
  console.log('Got item!');
  console.dir(item);
});

reader.start();

It’ll also do a conditional GET based on the last modified headers:

// check headers for conditional get
if (res.headers['last-modified']) {
  self.getOpts['If-Modified-Since'] = res.headers['last-modified'];
}
if (res.headers.etag) {
  self.getOpts['If-None-Match'] = res.headers.etag;
}

jQuery Roundup: Auto-geocoder, Jade for jQuery, Swipe

21 Feb 2012 | By Alex Young | Comments | Tags jquery plugins ui mobile geo
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

jQuery Auto-geocoder

jQuery Auto-geocoder

jQuery Auto-geocoder (GitHub: tristandunn / jquery-auto-geocoder, License: MIT) by Tristan Dunn enables incremental search for Google Maps. A text input is displayed, and the results of a location search on Google’s geocoding API are displayed in the map view.

$(function() {
  $('#location').autoGeocoder();
});

The autoGeocoder method also accepts options – for example, delay can be used to control how often locations will be geocoded, and initial contains the options used to create the map.

One thing I wanted to do when testing this plugin was allowing the marker to be dragged. As far as I can tell, there’s no direct support for manipulating the resulting marker position. However, it’s possible to bind to the events used by the plugin, then the listener will be in the right context to access the marker:

$('#location').autoGeocoder({
  initial: {
    zoom: 1
  , center: [34, 0]
  , draggable: true
  , mapTypeId: google.maps.MapTypeId.ROADMAP
  , mapTypeControl: false
  }
}).bind('auto-geocoder.onGeocodeResult', function() {
  this.marker.draggable = true;
});

I had to write a similar interface widget once that allowed people to search for a location, then fine-tune the position.

Jade for jQuery

Jade for jQuery (License: MIT/GPL v2) by Jeremy Martin is a lightweight jQuery wrapper for Jade. Seeing as both of these technologies are all about CSS selectors, I’ve always felt like it makes sense to use them together. In my own work, Jade has formed the server-side templates. How does this look for a client-side template solution?

<script id='my-template' type='text/x-jade'>
h1 Hello #{name}!
</script>

<script type="text/javascript">
$('#my-template').jade({ name: 'World' }).appendTo('body');
</script>

It’s also possible to render string templates with $.jade(template, data).

Swipe

Swipe screenshot

Hirvesh sent in Swipe (GitHub: bradbirdsall / Swipe, License: MIT/GPL) by Brad Birdsall:

Swipe is a lightweight mobile slider with 1:1 touch movement, resistant bounds, scroll prevention, and completely library agnostic.

It works with a series of elements inside a container, and the author recommends using it with a feature detection library like Modernizr:

if (Modernizr.csstransforms) {
  window.mySwipe = new Swipe(
    document.getElementById('slider')
  );
}

One of the nice features in Swipe is scroll prevention – it’ll detect if a swipe was intended to scroll the screen down, or slide content horizontally.

New Control Flow Libraries

20 Feb 2012 | By Alex Young | Comments | Tags node libraries async

There are a lot of control flow libraries for Node. Most libraries seek to wrap more complex patterns like promises with a simpler API, and others place a unique emphasis on a particular aspect of control flow. Some are the result of extracting generic functionality from another project, and others purport to be the next great ‘async micro-framework’.

Here are some interesting new control flow libraries that I’ve been looking at recently.

Nue

Nue (License: MIT, npm: nue) by Toshihiro Nakamura supports serial execution, nesting, error handling, and sharing data between functions through this.data:

var flow = require('nue').flow
  , fs = require('fs')
  , myFlow;

myFlow = flow(
  function(file1, file2) {
    this.data.file1 = file1;
    this.data.file2 = file2;
    fs.readFile(file1, 'utf8', this.async());
    fs.readFile(file2, 'utf8', this.async());
  },
  function(data1, data2) {
    this.next(data1 + data2);
  },
  function(data) {
    if (this.err) throw this.err;
    console.log(data);
    console.log(this.data.file1 ' and ' + this.data.file2 ' are concatenated.');
    this.next();
  }
);

myFlow('file1', 'file2');

I liked the way the author’s examples made each ‘flow’ a reusable function, rather than simply demonstrating that arbitrary asynchronous functions can be executed in series. The API for Nue uses this quite a lot – for example, this.async is used to accept the parameters for the next function and return a suitable callback.

The author has also written Mocha tests.

 Batch

Batch (License: MIT, npm: batch) by TJ Holowaychuk makes it easier to collect groups of results from asynchronous operations:

var Batch = require('batch')
  , batch = new Batch;

ids.forEach(function(id) {
  batch.push(function(done) {
    User.get(id, done);
  });
});

batch.end(function(err, users) {
  // `users` now has all of the users that were loaded
});

Rather than using a promise, or enhancing forEach, TJ has opted to use an event-based API that should be familiar to Node developers.

Cascade

Cascade (License: MIT, npm: cascade) by Scott Rabin allows nested callbacks to be flattened by passing an array of functions and their arguments to the cascade function:

// Standard code
fs.rename('/tmp/hello', '/tmp/world', function(err) {
  if (err) throw err;
  fs.stat('/tmp/world', function(err, stats) {
    if (err) throw err;
    console.log('stats: ' + JSON.stringify(stats));
  });
});

// Cascade
cascade('/tmp/hello', '/tmp/world',
  cascade.chain(fs.rename),
  cascade.raise(null, 2),
  fs.stat,
  cascade.raise,
  function(stats) {
     console.log('stats: ' + JSON.stringify(stats));
  }
);

The API has lots of helpers for working with arguments, like filter, join, and map:

cascade(1, 2, 3, 4, 5, 6,
  cascade.map(function(i) {
     return (i % 2 === 0 ? 'even' : 'odd');
  }),
  callout
);

// "callout" receives these arguments:
// 'odd', 'even', 'odd', 'even', 'odd', 'even'

The author has written detailed tests using Vows.

 Pattern

Pattern (License: Apache v2.0, npm: p) by Nuno Job uses patterns to manage asynchronous iteration:

var insert_all = require('p')(), _;

// Simulate an asynchronous operation
function insert_element(data, callback) {
  setTimeout(function() { callback(data); },
    Math.ceil(Math.random() * 100));
}

insert_all([], _, function stop(l,cb) { cb(); });
insert_all(_, _, function catchall(l, cb) {
  insert_element(l.shift(), function elem_cb(elem) {
    console.log(elem + ' inserted');
    insert_all(l, cb);
  });
});

insert_all([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 
  function done() { console.error('done'); });

This is by the same developer who made Clarinet, an evented SAX parser. There’s a blog post about the library here: Pattern Matching in JavaScript for Asynchronous Iteration.

Invoke

Invoke (License: MIT, npm: invoke) by Steve Lloyd combines chainable methods with an API that looks inspired by promises:

invoke(function(data, callback) {
  // Async operation
}).and(function(data, callback) {
  // Parallel operation
}).then(function(data, callback) {
  // Runs after the first two
}).rescue(function(err) {
  // Error handler
}).end(initialData, function(data) {
  // Done
});

Notice how .then implies serial execution, while .and is used for parallel invocations.

This library has some nodeunit tests, and a full example (in examples / simple.js).

More

As I was researching this post I built up metadata from GitHub and npm to figure out what the newest modules were. For modules that I didn’t cover, have a look at New Control Flow Libraries.

tQuery, Catchall, Geometry.js

17 Feb 2012 | By Alex Young | Comments | Tags webgl errors games mathematics

tQuery Valentine’s Day Card

Jerome Etienne, WebGL experimenter and author of the Learning Three.js blog, recently published a WebGL Valentine’s Day card tutorial which demonstrates his new library, tQuery (License: MIT). While development on tQuery is still ongoing, it provides a friendly alternative API for WebGL based around chainable calls:

tQuery.createText('tQuery is fun!').addTo(world);

tQuery.createShape()
  .moveTo(0, 0)
  .lineTo(1, 1)
  .lineTo(-1, 1)
  .lineTo(0, 0);

As a JavaScript developer, this API appeals to me and results in some surprisingly concise code. The tutorial also includes a screencast which covers the methods used by the Valentine’s Day card example in detail.

Catchall

Catchall (License: MIT) by Craig Condon is an alternative to window.onerror created to aid development by catching all exceptions. To do this, all functions are wrapped, which is why the author recommends using it during development and testing only.

Connect middleware is also included, which allows arbitrary scripts to be wrapped by the catchall module. The project’s API allows strings of code to be wrapped by using catchall.wrap, and catchall.load can be called on a source file URL or file system path:

catchall.load('http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.js', function(err, result) {
    //do something
});

catchall.load('/from/fs', function(err, result) {
    //do something
});

Geometry.js

Geometry.js (License: AOL) by Nijiko Yonskai is a collection of geometry classes used by the author for game development. The following classes are included: Circle, Direction, Rectangle, Vec2d. The vector class in particular seems like something I’ve found myself writing and rewriting for various WebGL and game-related experiments.

The library includes a rich set of methods, and even aliases mathematical operators:

var v1 = new Vec2d(10, 20)
  , v2 = new Vec2d(33, 10);

v1['+'](v2).x;
// 43
v1.add(v2).x;
// 43
v2.toArray();
// [33, 10]
Vec2d.Zero().toArray();
// [0, 0]

Unix and Node: Manual Pages

16 Feb 2012 | By Alex Young | Comments | Tags node tutorials essay unix documentation

If you’re familiar with npm’s documentation you’ll have noticed that it comes with a lot of manual pages. I don’t think I could have published an npm module without reading man npm-json several times first. To this day I still bring it up to search for the correct properties for the more obscure features.

Let’s look at npm to see how Isaac did this, then generalise it a little bit so you can publish your own manual pages.

Background

npm man page

The now ubiquitous npm makes use of man pages for its documentation. This isn’t the only way to view these files, but it’s my preferred way to read them. The way npm generates documentation is clever – Isaac has chosen to write files in Markdown, which has a positive side-effect of allowing GitHub to render them. These files are then converted to a markup language that man will understand.

This markup language is derived from early typesetting tools, known as the roff system. If you’re interested in writing manual pages by hand, take a look at man groff. To learn about the history of these tools, man roff is an interesting read.

Converting a Markdown document to something roff-like was solved rather well by ronn by Ryan Tomayko. Ronn is a Ruby program, so Isaac has used his own fork of ronnjs to generate his manual pages for npm.

To make this work, npm’s makefile will run scripts/doc-build.sh:

man/man1/%.1: doc/cli/%.md scripts/doc-build.sh package.json
  @[ -d man/man1 ] || mkdir -p man/man1
  scripts/doc-build.sh $< $@

The doc-build.sh script uses bash, sed, and perl to replace values in the Markdown files:

./node_modules/.bin/ronn --roff $src \
| sed "s|@VERSION@|$version|g" \
| perl -pi -e 's/npm\\-([^\(]*)\(1\)/npm help \1/g' \
| perl -pi -e 's/npm\\-([^\(]*)\(3\)/npm apihelp \1/g' \
| perl -pi -e 's/npm\(1\)/npm help npm/g' \
| perl -pi -e 's/npm\(3\)/npm apihelp npm/g' \
> $dest

Another option for manual page generation is the mantastic web service, mentioned by TJ Holowaychuk in the comments on HelsinkiJS February, Todo, Testing Backbone.js.

Therefore, a general pattern for generating manual pages in Node apps is as follows:

  • Create files for documentation using your preferred markup language
  • Use a suitable tool to generate something similar to the groff language
  • The resulting manual pages can be distributed when publishing to npm, (Node includes node.1 in its source)

An alternative would just be to write the manual pages using the groff language to begin with. It’s surprisingly easy to pick up, although it’s not as friendly as Markdown and doesn’t have the advantage of being easily read without formatting.

Installing Manual Pages

When a module is installed with npm, it’ll actually copy man pages to {prefix}/share/man if they’re available. To do this, tell npm where the man pages are in the directories property:

"directories": {
  "man": "./doc/man"
}

If this module is installed as a global module, then npm will copy the manual pages from ./doc/man to {prefix}/share/man.

Conclusion

When writing a general purpose tool with Node, consider writing a manual page using groff, or converting your Markdown documentation. The command-line jockeys amongst us will appreciate it, and it’ll bring your application a little bit closer to feeling like a true part of a Unix system.

Node Roundup: Gumroad, Functools, Asyncblock, Geddy, Lemmy

15 Feb 2012 | By Alex Young | Comments | Tags node modules async fibers frameworks

 Gumroad

Gumroad logo

Gumroad is a new payment service aimed at digital goods sales that works in over 190 countries. As someone who builds small web applications with subscription fees, I can honestly say that receiving payments is the least fun part of development. It’s fun getting paid, but dealing with payment provider APIs can be stressful to say the least. So I read with interest when Vadim Demedes sent us his Node Gumroad client (License: MIT, GitHub: vdemedes / node-gumroad, npm: gumroad).

The client is a class that is instantiated with a Gumroad username and password. After calling an authentication method, item links can be created and managed. For more about Gumroad’s links, take a look at How does Gumroad work?

Functools

Functools (License: WTFPL, GitHub: azer / functools, npm: functools) by E. Azer Koçulu has continued to evolve since we featured it last year. Using languages like Clojure and Python for inspiration, Azer has created a small API of familiar flow control functionality. A compose method can be used to call functions in sequence, and asynchronous functions are also supported. There’s also a curry method.

In Avoiding Nested Callbacks in JavaScript, the author discusses Functools, along with more detailed examples than supplied in the README.

Asyncblock

Asyncblock (License: MIT, GitHub: scriby / asyncblock, npm: asyncblock) is another flow control related library that we’ve previously featured on DailyJS. Now version 2.0 has been released, which includes on-the-fly source transformation:

Note that when V8 supports generators, which is currently planned, the source transformation functionality of asyncblock will be able to transform most of the asyncblock code to be based on generators instead of fibers with no change to the original source. This helps reduce risk as it provides a path forward for asyncblock even if support for fibers became impossible in the future.

The examples in the README show how using asyncblock with source transformation can result in very succinct code.

GeddyJS

Meanwhile, Daniel Erickson let us know via Twitter that GeddyJS (License: Apache 2, GitHub: mde / geddy, npm: geddy) 0.3 is out. This Node web framework now has a new Bootstrap website, compete with a detailed tutorial and a list of the major features.

If you’re new to Geddy, it’s a full stack framework. Pretty much everything you need to build a web app is included. If you’ve seen Geddy before, then version 0.3 seems to have changed a lot since the 0.1 days. The only parts of the API that seem to have remained the same are models.

Lemmy

Lemmy is an Express boilerplate generator inspired by Motörhead’s Lemmy. And why not? There was an Amiga Motörhead game in the early 90s, so why not an Express generator? Anyway, it can be used to create a JavaScript or CoffeeScript application with Mocha tests.

Lemmy uses commands to generate lots of useful stubs, like middleware, routes, and models. And the author writes a mean README.

jQuery Roundup: jQuery-Paging, Pomodoro Timer App, SAP HTML5 Toolkit

14 Feb 2012 | By Alex Young | Comments | Tags jquery pagination apps productivity

 jQuery-Paging

We’ve seen a lot of pagination plugins on DailyJS recently, but diversity is good so I’ll keep collecting them until somebody convinces me not to! jQuery-Paging (License: MIT/GPL, GitHub: infusion / jQuery-Paging) by Robert Eisele is another take on client-side pagination. Usage centres around the number of items to paginate:

$(selector).paging(itemCount, options);

The plugin will generate a list of links, and clicking a link will cause the onSelect method to fire, which is one of the plugin’s many options. Formatting is handled in a relatively unique way – a format string and formatting callback are used:

$('#pagination').paging(itemCount, {
  format: '[< ncnnn >]',

  onFormat: function(type) {
    switch (type) {
      case 'block': // n and c
        return '<a>' + this.value + '</a>';
      case 'next': // >
        return '<a>&gt;</a>';
      case 'prev': // <
        return '<a>&lt;</a>';
      case 'first': // [
        return '<a>first</a>';
      case 'last': // ]
        return '<a>last</a>';
    }
  }
});

This is an interesting solution to handling formatting in pagination plugins.

Robert has lots of other jQuery and HTML5 projects listed on his site, here: xarg.org/projects/.

 Pomodoro Timer App

Pomodoro Timer screenshot

Pomodoro Timer (GitHub: oivoodoo / pomodoro-app) by Alexander Korsak is designed to manage time using the Pomodoro Technique. It’s implemented using Backbone.js and jQuery Mobile. It comes with a little wrapper that allows it to run on Heroku.

The Backbone.js code is carefully organised into collections, models, routers, and views. It serves as a good example of a self-contained Backbone.js application, particularly in terms of code organisation.

SAP’s HTML5 UI Toolkit

That’s right, you’re seeing something made by SAP on DailyJS. I was initially sceptical when I saw their new HTML5 UI toolkit, and the tutorials are PDFs, which didn’t help. However, when I saw the jQuery-style API I started to read more:

$(document).ready(function() {
  $('#uiArea').sapui('Button', 'btn', {
     text: 'Hello World!',
     press: function() { $('#btn').fadeOut(); }
  });
});

DailyJS reader Stefan sent this in, and he had a few comments about it that I thought I’d share:

Interesting side note: Their primary target for this is first tablets, then mobile then PCs and they will only support HTML5 (no fallbacks for older IEs).

From what I can gather, SAPUI5 uses jQuery, so it seems like the sapui method in the example is a plugin they’ve implemented for convenience. Unfortunately, downloading the beta requires an account, and even with a hastily created free account I couldn’t get it to download. Regardless, I expect jQuery can now include SAP in their “who’s using jQuery” list.

Mote.js, Resizer, o_O, JLS

13 Feb 2012 | By Alex Young | Comments | Tags libraries templates responsive frameworks

Mote.js

Mote.js (License: MIT, GitHub: satchmorun / mote, npm: mote) by “satchmorun” is a Mustache implementation with some impressive benchmarks. It runs in both Node and browsers, and usage should look familiar to users of existing Mustache engines:

var normal = mote.compile('escaped: ')
  , triple = mote.compile('triple: }')
  , ampersand = mote.compile('ampersand: ')
  , data = {data: '& " < >'};

normal(data);    //=> 'escaped: &amp; &quot; &lt; &gt;'
triple(data);    //=> 'triple: & " < >'
ampersand(data); //=> 'ampersand: & " < >'

Mote passes the Mustache spec, except for the optional lambda functionality:

var keyFn = mote.compile('Hello, .')
  , data = {
      name: 'Arthur Dent',
      lambda: function(fn) {
        return fn() + ' ' + fn().toUpperCase();
      }
    };

keyFn(data); //=> 'Hello, Arthur Dent. HELLO, ARTHUR DENT.'

Resizer

Resizer logo

Resizer (GitHub: egdelwonk / Resizer) by William Golden is a bookmarklet designed to aid responsive design. Popular resolutions for mobile devices are included so it’s easy to switch a page between a tablet view, desktop, and mobile. The current page can also be reloaded or reset.

There’s even a Resizer Chrome Extension, for those of us who prefer buttons to the extra screen real estate added by bookmark bars.

o_O

o_O (License: MIT) by Jonah Fox is a new HTML binding library that draws on the simplicity of Backbone.js’s collections, and the bindings of Ember and Knockout. The main methods provided by the library are property, bind, and collection:

var name = o_O.property('John');
o_O.bind(name, '#person');

// HTML text is now 'John'
name('Bob')

// HTML text is now 'Bob'

It ships with Mocha tests, and has been tested in IE 7,8,9, Chrome 16, Firefox 4 and Safari 5.

JLS Updates

JLS (License: LGPL) is a JavaScript platform that we’ve featured previously on DailyJS in Gestures, Scopeleaks, Wink, JLS, JavaScript Blogs. The authors have been working on it over the last year, and have recently released a whole load of new features:

  • More Web Browser GUI support: button, edit, table, etc.
  • Native image manipulation: subsampling, convolution, EXIF support
  • Simple XML Exchange (SXE) support for native, web browser and PHP
  • SQL support since 0.4 (for MySQL)
  • AMD is now used for defining and loading the framework’s classes

Mystik Map Editor, Outcome.js, TypedJS

10 Feb 2012 | By Alex Young | Comments | Tags games language errors jison parsing

Mystik Map Editor

Mystik Map Editor

So, you want to build the next Ultima in JavaScript? As well as a game engine tools are required. Mystik Map Editor (GitHub: UrbanTwitch / Mystik-Map-Editor) is an open source tile map editor. The client-side code is built with jQuery and jQuery UI. It supports a few drawing operations, like “brush” tile placement and a line tool, and will display if a tile is walkable or not.

Pressing “Create Map” will output a JSON representation of the current map. To see an example of a game built with this tile editor, visit mystikrpg.com. Technically, the tile editor could be forked, hacked, and used for anything, so if you do build the next Ultima with server-side JavaScript, get in touch!

Outcome.js

Outcome.js (npm: outcome) by Craig Condon is a flow control library that focuses on error handling. Any functions with the signature .callback(err, result) can be wrapped, allowing error-related code to be grouped together.

It’s quite hard to visualise the library without looking at Craig’s example in the outcome.js README. Notice that rather than wrapping if statements around the errors returned in callbacks, on.success( is used to control execution.

 TypedJS

TypedJS (License: MIT, GitHub: Proxino / TypedJS) by Ethan Fast allows functions to be annotated with type signatures. The library will then output useful logging during execution, allowing any mismatched types to be detected and potentially fixed.

To do this, comments and tests are used. Given a function with a suitable annotation:

MyObj = {
  //+ MyObj.test_fun :: Number -> Number -> Number
  test_fun:function(num1, num2){
    return num1 + num2;
  }
}

Then the function can be tested using TypedJS.run_tests(). If TypedJS.run_tests(true) is used, TypedJS will wrap functions to actually check for type violations. This is currently aimed at client-side development and requires jQuery, but the author notes that it’s early days for the library, so hopefully it’ll be extended to run elsewhere.

Interestingly, this is built using Jison. For those interested in Jison grammars, check out typedjs_parser.jison.

Unix and Node

09 Feb 2012 | By Alex Young | Comments | Tags node tutorials essay unix

Recently, Node has received a huge amount of development effort to improve its Windows support. However, most of us probably run Node on some flavour of Unix – whether it be a Linux, Mac OS, Solaris, or a non-fruit BSD.

As JavaScript enthusiasts we can do a lot in Unix with just a little bit of Node. This new essay series is a collection of tips and observations I’ve made about Unix and Node. If you’re interested in writing command-line tools or networking daemons, Node is a good choice, and you’ll see why over the next few weeks.

Folklore and Tradition

If you’re a solid programmer but lack fundamental Unix knowledge, I won’t hold it against you. The important thing to realise is learning Unix requires knowledge of traditions and philosophies. As stated by Eric S. Raymond in The Art of UNIX Programming:

If you are not a programmer, or you are a programmer who has had little contact with the Unix world, this may seem strange. But Unix has a culture; it has a distinctive art of programming; and it carries with it a powerful design philosophy. Understanding these traditions will help you build better software, even if you’re developing for a non-Unix platform.

This means learning to write Unix programs that behave the way seasoned Unix users expect isn’t always a case of looking up standards and best practices. One of the most famous comments on the philosophy of Unix is by Doug McIlroy:

Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface.

Does that sound familiar? Try changing the word “program” to “module”:

  • Write modules that do one thing and do it well.
  • Write modules that work together.
  • Write modules that handle events and streams.

In The Art of UNIX Programming, Raymond summarises many of these ideas and philosophies into a set of design rules that are readily available on Wikipedia: Unix philosophy.

Rule of Diversity: Distrust all claims for “one true way”.

Coming to Unix development from a web developer’s background requires a change in thinking. When working as a client-side developer, one may regularly refer to W3C specifications. However, when writing Node software for Unix, it’s likely that the philosophy of Unix developers will shape the application more than standards and specifications. To see why we need to take a look at Node’s relationship to POSIX.

POSIX

The family of standards that helps us write portable code is known as POSIX. This covers the C Standard Library, process creation and control, signals, pipes, and a lot more. In addition, the core Node developers have their own philosophy and concerns. For example, Node has to maintain portability with Windows. Certain aspects of POSIX don’t necessarily fit in with Node’s philosophy, hinted at here by Ryan Dahl while discussing the possibility of a Node POSIX library:

dup, dup2, fork are out of the question and will never be added. They do not coincide node’s philosophy. chroot is not useful but is a posix thing. The posix module I suggested was to support random user/permissions stuff like getpwnam(). I’d rather not have that if we can get away with it.

Ryan Dahl on an official POSIX library

This comment by Isaac Schlueter is also interesting:

So far, in any of the cases where we’d thought we’d need to split out a posix library, we’ve been able to find sane approaches for both Windows and Unix. Who knows if that’ll continue, but it’d be nice to not have to do require(“posix”) ever.

Isaac Schlueter on an official POSIX library

How does this affect us as developers interested in writing Unix software? The implications are that Node provides an opaque API layer that sits on top of the operating system, but this isn’t quite true. Differences in Node’s API between Windows and other operating systems are documented in Node’s API documentation. One example is path.join, which will correctly use backslashes in Windows and forward slashes elsewhere.

Design Principles

Extrapolating Raymond’s principles to Node development is an inspirational way to look at Node development. In my experience, writing monolithic applications with Node isn’t a sound architectural approach. I’ve found breaking applications down into small modules and binaries that do one thing well is a good idea. Remember that npm modules don’t have to be publicly released: set that private property to true in your package.json to ensure it isn’t published.

I’d add another rule to Eric’s list:

  • Rule of Sharing: Make supporting documentation, licensing, and tests clear and easy to find. Tests should be easy to run.

To allow people to easily run tests, include a "scripts": { "test": "make test" } so npm test can be used. Also, clearly license Node modules by adding something like this to package.json:

"licenses": [
  {
    "type": "MIT +no-false-attribs",
    "url": "http://github.com/isaacs/npm/raw/master/LICENSE"
  }
]

– From npm’s package.json

The Twelve-Factor App

Unix philosophy reminds me of The Twelve-Factor App by Adam Wiggins. This methodology is inspired by working on Heroku’s platform, which runs hundreds of thousands of applications. Remember how I mentioned POSIX defines signals? Well, knowledge of signals comes in handy when writing applications that behave correctly on a platform like Heroku:

Processes shut down gracefully when they receive a SIGTERM signal from the process manager. For a web process, graceful shutdown is achieved by ceasing to listen on the service port (thereby refusing any new requests), allowing any current requests to finish, and then exiting.

– From Disposability, The Twelve-Factor App

Running software “in the cloud” ultimately means running it on a platform with some level of POSIX compliance.

Conclusion

Unix might have its own culture and principles, but its philosophies can make us better Node developers. Write your next command-line application or daemon with Node, and you might be pleasantly surprised.

Node Roundup: 0.6.10, 0.7.3, Backbone.IO, Notes

08 Feb 2012 | By Alex Young | Comments | Tags node modules fibers backbone.js
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

0.6.10, 0.7.3

Node 0.6.10 was released last week. Of interest to Windows users is the following:

  • Add npm msysgit bash shim to msi installer
  • dgram: Implement udp multicast methods on Windows

Node 0.7.3 has also been released. This reverts support for isolates:

It was decided that the performance benefits that isolates offer (faster spin-up times for worker processes, faster inter-worker communication, possibly a lower memory footprint) are not actual bottlenecks for most people and do not outweigh the potential stability issues and intrusive changes to the code base that first-class support for isolates requires.

Ben Noordhuis finishes the commit message with “Good bye, isolates. We hardly knew ye”. I couldn’t find any discussions about this in the nodejs-dev group, but I noticed David Herron mention it here: Good bye isolates, Node.js hardly knew ye.

Backbone.IO

Backbone.IO (License: MIT, npm: backbone.io) by Scott Nelson is a Backbone.js module that can synchronise multiple clients. When a model is synced, the server-side code will trigger events on collections across multiple clients.

The server-side code uses a Connect-inspired middleware API. Notice the familiar signature:

var backend = backboneio.createBackend();

backend.use(function(req, res, next) {
    console.log(req.backend);
    console.log(req.method);
    console.log(JSON.stringify(req.model));
    next();
});

backend.use(backboneio.middleware.memoryStore());

Scott has included tests as well, which are built using Mocha and Sinon.

Notes

Notes by Oleg Podsechin is an example app built using his Common Node and Mongo Sync libraries. This is an effort to bring traditional declarative synchronous code to Node through node-fibers.

Here’s a taster:

// Get an array of notes
mongo.db('notes').getCollection('notes').find().toArray();

// Save a note
mongo.db('notes').getCollection('notes').save({ name: request.params.name });

jQuery Roundup: 1.7.2, Super Labels, jquery.textntags

07 Feb 2012 | By Alex Young | Comments | Tags jquery plugins forms
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

jQuery 1.7.2

jQuery 1.7.2 Beta 1 has been released. There are a lot of bug fixes, and some interesting API tweaks:

  • #5571: Allow chaining when passing undefined to any setter in jQuery
  • #8498: Animate hooks
  • #11119: The curCSS function needs only 2 arguments
  • #10931: Unit tests shouldn’t require Internet access

That last one is particularly useful if you need to run jQuery’s unit tests. Tests shouldn’t need a connection!

jQuery Super Labels

jQuery Super Labels (License: MIT) by Rémy Bach is a form field overlay plugin that hides labels when an input gains focus. It’ll work automatically with most text fields simply by calling $('form').superLabels(). If the label needs to be displayed in a different location, suitable options can be provided with labelLeft and labelTop.

Super Labels has advanced options for controlling animation easing and duration.

Another interesting plugin by the same author is jQuery Slash Search which will focus on a search field when / is typed.

jquery.textntags

textntags screenshot

jquery.textntags (License: MIT, GitHub: daniel-zahariev / jquery-textntags) by Daniel Zahariev is another @name input enhancement tool. A full example of it using Ajax to search looks like this:

$('textarea.tagged_text_ex2').textntags({
  onDataRequest: function(mode, query, triggerChar, callback) {
    $.getJSON('assets/data.json', function(responseData) {
      query = query.toLowerCase();
      responseData = _.filter(responseData, function(item) { return item.name.toLowerCase().indexOf(query) > -1; });
      callback.call(this, responseData);
    });
  }
});

This is an early version of the library, so the author doesn’t make any promises in terms of browser support. However, the documentation is solid and it ships with CSS, so it’s easy to drop into a project.

UIKit, Expect-dom, Patio

06 Feb 2012 | By Alex Young | Comments | Tags node testing jquery

UIKit

UIKit banner

TJ Holowaychuk’s latest project is UIKit (License: MIT, GitHub: visionmedia / uikit, npm: uikit). It’s a small library of decoupled components for creating web interfaces. Simple, structural markup and modular JavaScript is used to create widgets like a “card” that uses 3D transforms, dialogs, notification messages, and more.

UIKit reminded me of Nib, TJ’s library of Stylus mixins, utilities, and components. TJ stresses that UIKit isn’t a CSS framework like Bootstrap, but neither is it written with Stylus and Jade. Instead it functions as a loosely-knit set of components that can be built on.

Expect-dom

Expect-dom (License: MIT) by Kevin Dente is a set of DOM-related assertions for expect.js. Various assertions can be made, including attr, id, and html:

expect($('<div title="some title"></div>')).to.have.attr("title");
expect($(theEl)).to.have.html("<span>content</span>");

The author has adapted code from jasmine-jquery to create this library.

Patio

Patio (License: MIT, GitHub: Pollenware / patio, npm: patio) from Pollenware is an SQL library inspired by Sequel. It supports schema creation, migrations, queries, models, and associations. It even includes handy flow control related methods like then, removing the need to heavily nest certain asynchronous operations:

User.findById(1).then(function(user) {
  // SELECT * FROM user WHERE id = 1 
});

Patio also has some handy JavaScript-friendly utility methods:

User.toHash('id', 'name').then(function(nameIdMap) {
  // SELECT * FROM user 
  //{"1":"Bob Yukon"}
});

Full API documentation is also available: Patio API documentation.

The project still only has 11 GitHub followers, but it’s got an incredible amount of functionality already – check it out and give the authors some feedback!

StackHack, Ducks, Remote-Tilt, Simplify.js

03 Feb 2012 | By Alex Young | Comments | Tags node webgl testing games mobile

StackHack

StackHack screenshot

StackHack by Philip Deschaine and from PubNub is a WebGL demo that uses PubNub to create a massively multiplayer interactive block stacking game. The technical details are discussed in StackHack: A Massively-Multiplayer Mashup of PubNub and Three.js.

Let’s start with the server. I used Node.js with express to serve up our HTML, CSS, JavaScript. When a client connects, we generate a UUID, append some stuff and listen on that channel. Why do it this way? Why not just use a generic PubNub channel? Excellent question I wanted what’s known as an authoritative server.

The article includes more details behind both the client-side and server-side code.

Ducks, a WebGL Demo

Ducks screenshot

Ducks (GitHub: statico / webgl-demos / ducks) by Ian Langworth is a simple game demo that uses WebGL and sound, complete with animated models and reflections. The GLGE WebGL framework has been used, along with models from the COLLADA Basic Samples collection.

The game logic, in ducks / logic.js, is relatively clear and easy to follow, so it works as a great example of a small, manageable example of a WebGL game.

Remote-Tilt

Remote-Tilt (License: MIT, GitHub: remy / remote-tilt) by Remy Sharp can help test motion events without fooling around with a mobile device:

Testing motion events was never going to be easy task. You have two options, both of which suck. That’s where Remote-Tilt comes in. By including a single line of JavaScript you can emulate device motion events in your test page which can either be a regular browser or even a mobile emulator.

By including the Remote-Tilt polyfill on a page a popup will appear that allows motion events to be simulated:

Remote-Tilt motion emulator

Simplify.js

Simplify.js demo screenshot

Simplify.js (License: BSD, GitHub: mourner / simplify-js, npm: simplify-js) by Vladimir Agafonkin is a library for fast 2D/3D polyline simplification:

It is very useful when you deal with lines consisting of many tens of thousands of points, e.g. when you need to quickly render a 50k-points line on the browser (for charts, map routes, etc.).

The demo on the Simplify.js homepage shows how impressive the performance is, easily throwing around 50,000 points like it’s child’s play! The source for this project has been extracted from another of Vladimir’s interesting libraries, Leaflet, which is also worth checking out.