easy-sqs

easy-sqs is a simple library for using AWS SQS service which provides most of the basic SQS functionality as well as providing an event emitting QueueReader with batch deletion capabilities.

How to install

npm install easy-sqs

Getting Started

Quick Examples

Here's some basic examples to get you started. More detailed documentation can be found further down the page here.

Send a single message

To start sending message we need to get a reference to a Queue object. This object exposes most the basic comands commands you'll need.

Here's how to send a message:

var easy = require("easy-sqs");

var awsConfig = {
	"accessKeyId": "[YourAccessKeyId]",
	"secretAccessKey": "[YourSecretAccessKey]",
	"region": "[YourRegion]"
};

var url = "https://sqs.eu-west-1.amazonaws.com/123/queueName";

var client = easy.createClient(awsConfig);

client.getQueue(url, function(err, queue){

	if(err) console.log("queue does not exist");

	//messages must be strings for now...
	var msg = JSON.stringify({body: "my message body"});

	queue.sendMessage(msg, function(err){
			if(err) console.log("send failed!");
	});

});

Monitor a queue for new messages

It is common to have an application just sit and monitor a queue, process the message when it arrives, and then to continue to wait. For this activity, use a QueueReader.

var easy = require("easy-sqs");

var awsConfig = {
	"accessKeyId": "[YourAccessKeyId]",
	"secretAccessKey": "[YourSecretAccessKey]",
	"region": "[YourRegion]"
};

var url = "https://sqs.eu-west-1.amazonaws.com/123/queueName";

var client = easy.createClient(awsConfig);
var queueReader = client.createQueueReader(url);

queueReader.on("message", function (message) {

		//process message.Body here...
		queueReader.deleteMessage(message);

});

queueReader.on("error", function (err) {

		console.log("error", err);

});

queueReader.start();

There are four classes you interact with in easy-sqs:

• Client
• Queue
• QueueReader
• Message

Before you can do anything with easy-sqs you need to configure a client with AWS configuration.

Create a Client object

var easy = require("easy-sqs");

var awsConfig = {
	"accessKeyId": "[YourAccessKeyId]",
	"secretAccessKey": "[YourSecretAccessKey]",
	"region": "[YourRegion]"
};

var client = easy.createClient(awsConfig);

The awsConfig parameter is optional. This is a standard AWS client config object.

If the argument is not provided it will default to the AWS settings in your environment. Even if you want to have your application pass in some AWS settings (like proxy settings) you can omit the Credentials as long as they are available in your environment.

The Client class exposes the following methods:

• createQueue
• createQueueReader
• getQueue
• getQueueSync

Parameters:

• queueName (string)
• options (Object)
• callback (err:Error, queue: Queue)

The options currently supported are:

• DelaySeconds (number): default = 0
• MaximumMessageSize (number): default = 262144
• MessageRetentionPeriod (number): default = 345600
• ReceiveMessageWaitTimeSeconds (number): default = 0
• VisibilityTimeout (number): default = 30

All options are optional.

Example

var options = {
	VisibilityTimeout: 60
};

//With an option
client.createQueue("myName", options, function(err, queue){
	console.log("Queue created!");
});

//Without any options
client.createQueue("myName", null, function(err, queue){
	console.log("Queue created!");
});

See here for more detail on the QueueReader class.

Parameters:

• queueUrl (string)
• batchSize (number): default = 10

The batchSize parameter is optional.

var url = "https://sqs.eu-west-1.amazonaws.com/123/queueName";
var reader = client.createQueueReader(url, 10)

Parameters:

• queueName (string)
• callback (err:Error, queue: Queue)

var url = "https://sqs.eu-west-1.amazonaws.com/123/queueName";
client.getQueue(url, function(err, queue){

});

Parameters:

• queueUrl (string)

var url = "https://sqs.eu-west-1.amazonaws.com/123/queueName";
var queue = client.getQueueSync(url);

A Queue object can be obtained by using either the getQueue() or getQueueSync() methods on the Client class.

The Queue class exposes the following methods:

• createQueueReader
• getMessage
• deleteMessage
• sendMessage
• drain

See here for more detail on the QueueReader class.

Parameters:

• batchSize (number): default = 0

batchSize is optional.

var reader = queue.createQueueReader(10);

reader.on("message", function(message){
	console.log(message.Body);
});

reader.on("error", function(error){
		console.log(error)
});

reader.start();

Gets a single message from an SQS Queue.

Parameters:

• callback (err: Error, message: Message)

queue.getMessage(function(err, message){

	console.log(message.Body);

});

Once a message has been processed, it needs to be deleted from the queue. Use this method to do that.

Parameters:

• message (Message)

queue.getMessage(function(err, message){

	//all good, delete the message

	queue.deleteMessage(message, function(err){

	});

});

Parameters:

• messageBody (string)

//messages must be strings for now...
queue.sendMessage("my message body", function(err){


});

Parameters:

• callback (err: Error): This callback is optional.

queue.drain(function(err){
	console.log("empty!");
});

It is common to have an application just sit and monitor a queue, process the message when it arrives, and then to continue to wait. For this activity, it is recommended you use a QueueReader.

The QueueReader class implements long polling and will emit a message event for every message that arrives in the queue.

Additionally, it has a built-in batch deleter that will greatly reduce the number of requests you send to AWS and, as a result, reduces the cost. The batching logic is very pessimistic and will not hold an outstanding delete request for more than a couple seconds.

If you do not want to use batch deletions then just set the batchSize = 1 when you create the QueueReader.

The QueueReader class exposes the following methods:

• start
• stop
• pause
• deleteMessage
• deleteMessages

It also emits the following events:

• message
• error
• empty
• started
• stopped

var queueReader = queue.createQueueReader();

queueReader.on("message", function (message) {

		//process msg.Body here...
		queueReader.deleteMessage(message);

});

queueReader.on("error", function (err) {

		console.log("error", err);

});

queueReader.start();

QueueReader methods

Please note: This behaviour is not the same as Queue.deleteMessage().

Parameters:

• message (Message)

var queueReader = queue.createQueueReader();

queueReader.on("message", function (message) {

		//process msg.Body here...
		queueReader.deleteMessage(message);

});

Parameters:

• messages (Message[])

QueueReader events

queueReader.on("message", function (message) {
	//process msg.Body here...
});

queueReader.on("error", function (err) {
	console.log("whoops", err);
});

queueReader.on("empty", function () {
	console.log("The queue is empty!");
});

The Message class is the same class provided by the aws-sdk. Documentation for it can be found here.

##Deprecation Notice

The previous interface with onReceipt, onEmpty, and onError will be deprecated in future versions. If you are using an older version of this library, please modify to use standard events.