Simplified Library for using AWS Simple Queuing Service (SQS)
npm install 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.
``
npm install easy-sqsGetting Started
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:
`js
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.
`js
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
`js
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
#### createQueue
This method creates a new Queue object.
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
`js
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!");
});
`
#### createQueueReader
Creates a QueueReader object to monitor an SQS Queue that will emit messages when they become available.
See here for more detail on the QueueReader class.
Parameters:
- queueUrl (string)
- batchSize (number): default = 10
The batchSize parameter is optional.
`js`
var url = "https://sqs.eu-west-1.amazonaws.com/123/queueName";
var reader = client.createQueueReader(url, 10)
#### getQueue
This method get a reference to an SQS Queue. The callback returns an error if the queue does not exist.
Parameters:
- queueName (string)
- callback (err:Error, queue: Queue)
`js
var url = "https://sqs.eu-west-1.amazonaws.com/123/queueName";
client.getQueue(url, function(err, queue){
});
`
#### getQueueSync
This method is a synchronous version of the getQueue()` method above. It will return a reference to a Queue object whether the queue exists or not.
Parameters:
- queueUrl (string)
`js`
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
#### createQueueReader
Creates a QueueReader object to monitor an SQS Queue that will emit messages when they become available.
See here for more detail on the QueueReader class.
Parameters:
- batchSize (number): default = 0
batchSize is optional.
`js
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)
`js
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)
`js
queue.getMessage(function(err, message){
//all good, delete the message
queue.deleteMessage(message, function(err){
});
});
`
#### sendMessage
This method will send a message to an SQS Queue.
Parameters:
- messageBody (string)
`js
//messages must be strings for now...
queue.sendMessage("my message body", function(err){
});
`
#### drain
This method will consume and discard all messages in an SQS Queue. Useful for testing.
Parameters:
- callback (err: Error): This callback is optional.
`js`
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
`js
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();
`
#### start
Starts long polling of an SQS queue. Emits a `started` event when it begins polling.
#### stop
Stops long polling of an SQS queue. This method will emit a `stopped` event after any outstanding messages are emitted and deleted.
#### pause
This behaves exactly the same as `stop()` but does not emit a `stopped` event.
#### deleteMessage
This method adds a message to a deletion batch. If the number of messages exceed the batch size a batch deletion is sent to the Sqs Queue.
Please note: This behaviour is not the same as `Queue.deleteMessage()`.
Parameters:
- message (Message)
`js
var queueReader = queue.createQueueReader();
queueReader.on("message", function (message) {
//process msg.Body here...
queueReader.deleteMessage(message);
});
`
#### deleteMessages
Behaves the same as above but takes an array of messages as it's input.
Parameters:
- messages (Message[])
#### on("message")
The message event is emitted for every message that is pulled from the queue.
`js`
queueReader.on("message", function (message) {
//process msg.Body here...
});
#### on("error")
Any errors that occur are emitted by the error event.
`js`
queueReader.on("error", function (err) {
console.log("whoops", err);
});
#### on("empty")
The empty is emitted any time the long polling does not return any messages.
`js`
queueReader.on("empty", function () {
console.log("The queue is empty!");
});
#### on("started")
The started event is emitted when the long polling loop commences.js`
queueReader.on("started", function () {
console.log("start polling");
});
#### on("stopped")
The stopped event will be emitted after the `stop()` method is called and once all messages which are currently in memory have been emitted and deleted. `js`
queueReader.on("stopped", function () {
console.log("stopped");
});
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.