ircee

ircee is a tiny modular IRC library with a stream/event-emitter based API.

Why another library?

Most of the advantages come from the stream / eventemitter API. It allows you to do things such as

• Live code reloading - connect the network connection in the parent process, pipe it to the child process which loads the actual code. Signal the master to kill and respawn the child process - the code will be reloaded without losing the connection to the IRC server.

• Browserify / use on different transports - for example, use it through websockets in the browser by piping the connection streams using shoe. Here is a complete example using browserify

The modular design allows for easy extensibility and testing.

Example

var ircee = require('ircee'),
    net = require('net');

// Create a client
var irc = ircee();

irc.on('connect', function() {
    // Load the core module. It keeps the connection alive 
    // when loaded and provides the login method.    
    var core = irc.use(require('ircee/core'));
    // use the login method to send the nickname
    core.login({
        nick: 'ircee_example',
        user: 'ircee_example',
        name: 'Look! I am online!'
    });
});

// Log all protocol lines to stdout
irc.on('event', function(e) { console.log(e.raw); });

// Connect the actual socket and pipe it to the client
var s = net.connect(6667, 'irc.freenode.net');
s.pipe(irc).pipe(s);

Modules

Modules are easy to write. Here is how the core module looks like:

module.exports = function(irc) {
    irc.on('ping', function(e) {
        irc.send('pong', e.text);
    });
    var self = {};
    self.login = function login(params) {
        irc.send('nick', params.nick);
        irc.send('user', params.user, 0, '*', params.name);
    }
    return self;
}

The module should be a function that receives the irc client as its argument. It should return the object to be exported.

Using modules

Using modules is easy. From your main program or from any other module, simply call irc.use in the following ways:

irc.use(module_function); 
irc.use(require('./path/to/module'));

You can also get the exported object:

var module = irc.use(require('path/to/module'));

If the module has already been loaded, it will not be called again. Instead, the cached exported object will simply be returned by irc.use

Connect and disconnect

If you are piping a socket (or any stream with a connect event) directly to ircee it will recognize and re-emit its 'connect' event. Otherwise, you will need to tell it when the connection has been established:

irc.emit('connect')

Disconnects arrive as close events. For example, to immediately reconnect to the server, you can do this:

irc.on('close', function() { 
    var s = net.connect(...); 
    s.pipe(irc).pipe(s);
});

Other methods

The methods shown in the examples are all the available methods:

• irc.send - sends a command to the server. The first parameter is a command string, while the rest are the command parameters. As per usual in the IRC protocol, the final parameter is allowed to have multiple words. For example:

  ```js
  irc.send('privmsg', '#channel', 'Text to send');
  irc.send('privmsg', 'nickname', 'Some text');
  irc.send('mode', '#channel', '+ov', 'nick1', 'nick2', null);
  irc.send('topic', '#channel', 'New topic text');
  ```

  Notice that the mode command does not use a multi-word parameter and therefore we must add a null argument when calling irc.send

• irc.on etc - All standard eventemitter and duplex stream methods are available.

Events

Events are lower-case strings. Here are some common events:

• privmsg - all message events, including CTCP
• notice - all notice events, including CTCP replies.
• number - all numeric events
• event - catchall for all IRC events.

Standard socket and stream events are also available

• connect - socket connection event
• close - socket closing event.
• data - raw data, line by line

Event objects

IRC events receive a single argument - the event object. It has the following properties:

• raw - the full raw event text
• source - the event source (e.g. nick!user@host)
• cmd - the command, e.g. PRIVMSG
• user - the source user (null if N/A)
  • address - nick!user@hostmask
  • nick - users nickname
  • user - users username (ident)
  • host - user's host, hostmask or IP
• params: list of command parameters
• target: event target (nickname or channel)
• text: event text (e.g. message contents)

License:

MIT