This article is part of the article series "Node.JS Modules You Should Know About."
<- previous article next article ->

node logoHello everyone! This is the thirteenth post in the node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers, the ninth was about redis - the best redis client API library for node, the tenth was on express - an insanely small and fast web framework for node, the eleventh was semver - a node module that takes care of versioning, the twelfth was cradle - a high-level, caching, CouchDB client for node.

This time I'll introduce you to a very awesome module called JSONStream. JSONStream is written by Dominic Tarr and it parses streaming JSON.

Here is an example. Suppose you have couchdb view like this:

{"total_rows":129,"offset":0,"rows":[
  { "id":"change1_0.6995461115147918"
  , "key":"change1_0.6995461115147918"
  , "value":{"rev":"1-e240bae28c7bb3667f02760f6398d508"}
  , "doc":{
      "_id":  "change1_0.6995461115147918"
    , "_rev": "1-e240bae28c7bb3667f02760f6398d508","hello":1}
  },
  { "id":"change2_0.6995461115147918"
  , "key":"change2_0.6995461115147918"
  , "value":{"rev":"1-13677d36b98c0c075145bb8975105153"}
  , "doc":{
      "_id":"change2_0.6995461115147918"
    , "_rev":"1-13677d36b98c0c075145bb8975105153"
    , "hello":2
    }
  },
  ...
]}

And you wish to only filter out doc values from the rows. You can do it easily with JSONStream this way:

var parser = JSONStream.parse(['rows', /./, 'doc']);

This creates a stream that parses out rows.*.doc.

Since it's a stream you have to feed it data and then have it output the data somewhere. You can do it very nicely and idiomatically in node this way:

req.pipe(parser).pipe(process.stdout);

Here is the output:

{
  _id: 'change1_0.6995461115147918',
  _rev: '1-e240bae28c7bb3667f02760f6398d508',
  hello: 1
}
{
  _id: 'change2_0.6995461115147918',
  _rev: '1-13677d36b98c0c075145bb8975105153',
  hello: 2
}

Where req is request to couchdb view and parser is the JSONStream parser, and it all gets piped to process.stdout. The output, as you can see, is only the rows.*.doc. That was a really easy way to parse a JSON stream without reading the whole JSON into memory.

You can install JSONStream through npm as always:

npm install JSONStream

JSONStream on GitHub: https://github.com/dominictarr/JSONStream.

Sponsor this blog series!

Doing a node.js company and want your ad to appear in the series? The ad will go out to 14,000 rss subscribers, 7,000 email subscribers, and it will get viewed by thousands of my blog visitors! Email me and we'll set it up!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

This article is part of the article series "Node.JS Modules You Should Know About."
<- previous article next article ->

node logoHello everyone! This is the twelfth post in the node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers, the ninth was about redis - the best redis client API library for node, the tenth was on express - an insanely small and fast web framework for node, the eleventh was semver - a node module that takes care of versioning.

Today I'll introduce you to cradle - a high-level, caching, CouchDB client for Node.js. Cradle is written by Alexis Sellier (cloudhead).

Cradle is somewhat higher-level than most other CouchDB clients, requiring a little less knowledge of CouchDB's REST API. Cradle also has built-in write-through caching, giving you an extra level of speed, and making document updates and deletion easier. Cradle was built from the love of CouchDB and Node.js, and tries to make the most out of this wonderful marriage of technologies.

Here is an example of how simple it's to use cradle:

var cradle = require('cradle');
var db = new(cradle.Connection)().database('starwars');

db.get('vader', function (err, doc) {
    doc.name; // 'Darth Vader'
    assert.equal(doc.force, 'dark');
});

db.save('skywalker', {
    force: 'light',
    name: 'Luke Skywalker'
}, function (err, res) {
    if (err) {
        // Handle error
    } else {
        // Handle success
    }
});

Cradle supports all the operations that you'd expect an API for CouchDB to support like creating a database:

var db = c.database('starwars');
db.create();

Checking if a db exists:

db.exists(function (err, exists) {
  if (err) {
    console.log('error', err);
  } else if (exists) {
    console.log('the force is with you.');
  } else {
    console.log('database does not exists.');
    db.create();
    /* populate design documents */
  }
});

Destroying a db:

db.destroy(cb);

Fetching a document:

db.get('vader', function (err, doc) {
    console.log(doc);
});

Querying a view:

db.view('characters/all', function (err, res) {
    res.forEach(function (row) {
        console.log(row.name + " is on the " +
            row.force + " side of the force.");
    });
});

Creating and updating documents:

db.save('vader', {
    name: 'darth', force: 'dark'
}, function (err, res) {
    // Handle response
});

Creating views:

db.save('_design/characters', {
    all: {
        map: function (doc) {
            if (doc.name) emit(doc.name, doc);
        }
    },
    darkside: {
        map: function (doc) {
            if (doc.name && doc.force == 'dark') {
                emit(null, doc);
            }
        }
    }
});

Deleting documents:

db.remove('luke', '1-94B6F82', function (err, res) {
    // Handle response
});

And it also supports streaming, changes api, and many other things. See the cradle documentation to learn more.

You can install cradle through npm as always:

npm install cradle

Cradle on GitHub: https://github.com/cloudhead/cradle.

Sponsor this blog series!

Doing a node.js company and want your ad to appear in the series? The ad will go out to 14,000 rss subscribers, 7,000 email subscribers, and it will get viewed by thousands of my blog visitors! Email me and we'll set it up!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

This article is part of the article series "Node.JS Modules You Should Know About."
<- previous article next article ->

node logoHello everyone! This is the eleventh post in the node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers, the ninth was about redis - the best redis client API library for node, the tenth was on express - an insanely small and fast web framework for node.

Today I'll introduce you to a module called semver. Semver is the semantic versioner. Semver is written by Isaac Z. Schlueter, the author of npm. Semver is used in npm to handle all the node.js module versioning problems.

Here is an example of what it does:

semver.valid('1.2.3') // true
semver.valid('a.b.c') // false
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7')  // false
semver.lt('1.2.3', '9.8.7')  // true

The ordering of versions is done using the following algorithm - given two versions and asked to find the greater of the two:

  • If the majors are numerically different, then take the one with a bigger major number. For example, 2.3.4 > 1.3.4.
  • If the minors are numerically different, then take the one with the bigger minor number. For example, 2.3.4 > 2.2.4.
  • If the patches are numerically different, then take the one with the bigger patch number. For example, 2.3.4 > 2.3.3.
  • If only one of them has a build number, then take the one with the build number. For example, 2.3.4-0 > 2.3.4.
  • If they both have build numbers, and the build numbers are numerically different, then take the one with the bigger build number. For example, 2.3.4-10 > 2.3.4-9.
  • If only one of them has a tag, then take the one without the tag. For example, 2.3.4 > 2.3.4-beta.
  • If they both have tags, then take the one with the lexicographically larger tag. For example, 2.3.4-beta > 2.3.4-alpha.
  • At this point, they're equal.

Semver supports the following ranges and styles:

  • >1.2.3 means greater than a specific version.
  • <1.2.3 means less than a specific version.
  • 1.2.3 - 2.3.4 means >=1.2.3 <=2.3.4.
  • ~1.2.3 means >=1.2.3 <1.3.0.
  • ~1.2 means >=1.2.0 <2.0.0.
  • ~1 means >=1.0.0 <2.0.0.
  • 1.2.x means >=1.2.0 <1.3.0.
  • 1.x means >=1.0.0 <2.0.0.

Ranges can be joined with either a space (which implies "and") or a || (which implies "or").

Semver supports the following functions:

  • valid(v) - return the parsed version, or null if it's not valid.
  • inc(v, release) - return the version incremented by the release type (major, minor, patch, or build), or null if it's not valid.

Semver supports the following comparisons:

  • gt(v1, v2) - v1 > v2.
  • gte(v1, v2) - v1 >= v2.
  • lt(v1, v2) - v1 < v2.
  • lte(v1, v2) - v1 <= v2.
  • eq(v1, v2) - v1 == v2.
  • neq(v1, v2) - v1 != v2.
  • cmp(v1, comparator, v2) - pass in a comparison string, and it'll call the corresponding function above. "===" and "!==" do simple string comparison, but are included for completeness. Throws if an invalid comparison string is provided.
  • compare(v1, v2) - return 0 if v1 == v2, or 1 if v1 is greater, or -1 if v2 is greater. Sorts in ascending order if passed to Array.sort().
  • rcompare(v1, v2) - the reverse of compare. Sorts an array of versions in descending order when passed to Array.sort().

Semver supports the following range functions:

  • validRange(range) - Return the valid range or null if it's not valid.
  • satisfies(version, range) - return true if the version satisfies the range.
  • maxSatisfying(versions, range) - return the highest version in the list that satisfies the range, or null if none of them do.

You can install semver through npm as always:

npm install semver

Semver on GitHub: https://github.com/isaacs/node-semver.

Sponsor this blog series!

Doing a node.js company and want your ad to appear in the series? The ad will go out to 14,000 rss subscribers, 7,000 email subscribers, and it will get viewed by thousands of my blog visitors! Email me and we'll set it up!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

This article is part of the article series "Node.JS Modules You Should Know About."
<- previous article next article ->

node logoHello everyone! This is the tenth post in my new node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers, the ninth was about redis - the best redis client API library for node.

Today I'm going to introduce you to express - an insanely fast and small server-side web development framework built on connect. Express is written by TJ Holowaychuk. TJ has written 85 node.js modules so far so expect many more of his modules in this series!

Check this out:

var express = require('express');

var app = express.createServer();

app.get('/', function(req, res){
    res.send('Hello World');
});

app.listen(3000);

This creates a web server that listens on port 3000 and handles the requests to /, returning Hello World string as a response.

Express has really powerful routing system. See this:

app.get('/user/:id', function(req, res){
    res.send('user ' + req.params.id);
});

This handles requests to /user/foo and automatically sets req.params.id to foo. You can also use regular expressions to handle routes.

If you want to handle POST requests, you have to make your app use bodyParser middleware. That can be done through app.use(express.bodyParser()). BodyParser basically parses the application/x-www-form-urlencoded and application/json request bodies and sets up req.body for you. For example:

app.use(express.bodyParser());

app.get('/', function(req, res){
    console.log(req.body.foo);
    res.send('ok');
});

This echos the body variables to console and sends back ok.

There are a bunch of different middlewares that you can use with express, such as:

app.use(express.logger(...));
app.use(express.cookieParser(...));
app.use(express.session(...));
app.use(express.static(...));
app.use(express.errorHandler(...));

The logger middleware handles logging of HTTP requests, cookieParser handles cookies, session handles HTTP sessions, static for static content, such as images, css and scripts, and errorHandler for handling exceptions and errors.

See the express documentation to learn more about middlewares.

Express also integrates with various templating engines. For example, my favorite templating language is jade (also written by TJ) and here is how you'd render a jade template with express:

app.get('/', function(req, res){
    res.render('index.jade', { title: 'My Site' });
});

Template filenames take the form <name>.<engine>, where <engine> is the name of the module that will be required. For example the template layout.ejs will tell express's view system to require('ejs'). The module being loaded must export the method exports.compile(str, options), and return a Function to comply with express.

Express features:

  • Robust routing.
  • Redirection helpers.
  • Dynamic view helpers.
  • Content negotiation.
  • Focus on high performance.
  • View rendering and partials support.
  • Environment based configuration.
  • Session based flash notifications.
  • High test coverage.
  • Executable for generating applications quickly.
  • Application level view options.

As well as:

  • Session support.
  • Cache API.
  • Mime helpers.
  • ETag support.
  • Persistent flash notifications.
  • Cookie support.
  • JSON-RPC.
  • Logging.

Also see this screencast on express by TJ:

For more examples see the examples directory in express source tree. Express also has awesome documentation.

You can install express through npm as always:

npm install express

Express on GitHub: https://github.com/visionmedia/express.

Sponsor this blog series!

Doing a node.js company and want your ad to appear in the series? The ad will go out to 14,000 rss subscribers, 7,000 email subscribers, and it will get viewed by thousands of my blog visitors! Email me and we'll set it up!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!

This article is part of the article series "Node.JS Modules You Should Know About."
<- previous article next article ->

node logoHello everyone! This is the ninth post in my new node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers.

Today I'm going to introduce you to node_redis - the best node.js Redis client API library. Redis node.js module is written by Matt Ranney.

This library is a complete Redis client for node.js. It supports all Redis commands, including many recently added commands like EVAL from experimental Redis server branches.

Here is an example of using redis library:

var redis = require("redis");
var client = redis.createClient();

client.on("error", function (err) {
    console.log("Error " + err);
});

client.set("string key", "string val", redis.print);
client.hset("hash key", "hashtest 1", "some value", redis.print);
client.hset(["hash key", "hashtest 2", "some other value"], redis.print);
client.hkeys("hash key", function (err, replies) {
    console.log(replies.length + " replies:");
    replies.forEach(function (reply, i) {
        console.log("    " + i + ": " + reply);
    });
    client.quit();
});

Here is the output when you run this example:

mjr:~/work/node_redis (master)$ node example.js
Reply: OK
Reply: 0
Reply: 0
2 replies:
    0: hashtest 1
    1: hashtest 2
mjr:~/work/node_redis (master)$ 

Each Redis command is exposed as a function on the client object. All functions take either an args Array plus optional callback Function or a variable number of individual arguments followed by an optional callback.

Here is an example of passing an array of arguments and a callback:

client.mset(["key 1", "val 1"], function (err, res) {});

Here is that same call in the second style:

client.mset("key 1", "val 1", function (err, res) {});

Note that in either form the callback is optional:

client.set("some key", "some val");
client.set(["some other key", "some val"]);

For a list of Redis commands, see Redis Command Reference.

The commands can be specified in uppercase or lowercase for convenience - client.get() is the same as client.GET().

You can install redis through npm as always:

npm install redis

Redis on GitHub: https://github.com/mranney/node_redis.

Pieter Noordhuis has written a binding to the official hiredis C library, which is non-blocking and fast. It's called hiredis-node. To use hiredis, do:

npm install hiredis redis

If hiredis is installed, node_redis will use it by default. Otherwise, a pure JavaScript parser will be used.

Sponsor this blog series!

Doing a node.js company and want your ad to appear in the series? The ad will go out to 14,000 rss subscribers, 7,000 email subscribers, and it will get viewed by thousands of my blog visitors! Email me and we'll set it up!

Enjoy!

If you love these articles, subscribe to my blog for more, follow me on Twitter to find about my adventures, and watch me produce code on GitHub!