Initial Commit

.eslintrc.json

@@ -0,0 +1,18 @@
+{
+    "env": {
+        "node": true,
+        "es6": true,
+        "mocha": true
+    },
+    "extends": "eslint:recommended",
+    "rules": {
+        "camelcase": ["error"],
+        "eqeqeq": ["error", "smart"],
+        "indent": ["error", 4],
+        "quotes": ["error", "single"],
+        "no-unused-vars": ["error", { "vars": "all", "args": "none" }],
+        "prefer-const": ["error", {"destructuring": "any"}],
+        "strict": ["error", "safe"],
+        "no-console": ["warn"]
+    }
+}

.gitignore

@@ -0,0 +1,41 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime Data
+pids
+*.pid
+*.seed
+
+# Dependency Directories
+node_modules
+jspm_packages
+
+# Code Coverage Directories
+lib-cov
+coverage
+
+# Other Node Stuff
+.npm
+.grunt
+.lock-wscript
+.node_repl_history
+
+# Ignore documentation
+/docs
+
+# JetBrains IDE: IntelliJ, WebStorm
+.idea/
+*.ipr
+*.iml
+*.iws
+/out
+/.idea_modules
+
+# OSX Files
+.DS_Store
+.AppleDouble
+.LSOverride
+.Spotlight-V100
+.Trashes

README.md

@@ -0,0 +1,113 @@
+# sqs-utils
+
+Build Amazon SQS-based applications without the boilerplate. 
+SQSUtils provides you with everything you need to poll and send messages to Amazon AWS.
+
+## Installation
+
+```bash
+npm install sqs-utils
+```
+
+## Usage
+
+Create a new `SQSUtils` instance and tell it which SQS queue to use:
+
+```js
+const SQSUtils = require('sqs-utils');
+
+const queue = new SQSUtils({
+  queueUrl: 'https://sqs.eu-west-1.amazonaws.com/account-id/queue-name'
+});
+```
+
+### Credentials
+
+By default the library will look for AWS credentials in the places [specified by the AWS SDK](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials). The simplest option is to export your credentials as environment variables:
+
+```bash
+export AWS_SECRET_ACCESS_KEY=...
+export AWS_ACCESS_KEY_ID=...
+```
+
+Alternatively you can provide your credentials upon creation of any new SQSUtils instance:
+
+```js
+const queue = new SQSUtils({
+  accessKeyId: 'AWS-ACCESS-KEY-ID',
+  secretAccessKey: 'AWS-ACCESS-KEY',
+  region: 'AWS-REGION',
+  queueUrl: 'https://sqs.eu-west-1.amazonaws.com/account-id/queue-name'
+});
+```
+
+You can also provide a pre-configured instance of the [AWS SQS](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SQS.html) client:
+
+```js
+const queue = new SQSUtils({
+  accessKeyId: 'AWS-ACCESS-KEY-ID',
+  secretAccessKey: 'AWS-ACCESS-KEY',
+  region: 'AWS-REGION',
+  queueUrl: 'https://sqs.eu-west-1.amazonaws.com/account-id/queue-name'
+});
+```
+
+### Continuous polling
+
+This uses [sqs-consumer](https://github.com/bbc/sqs-consumer) to continuously poll the queue for messages. 
+Just define a function that receives an SQS message and call a callback when the message has been processed.
+
+```js
+queue.listen({
+    visibilityTimeout: 300,
+    handleMessage: function(message, done) {
+        // Do your message handling in here
+        console.log(message);
+        // Remove the message from the queue
+        done();
+    },
+    handleError: function(err) {
+        // Handle errors
+        console.log(err);
+    }
+});
+```
+
+* The queue is polled continuously for messages using [long polling](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html).
+* Messages are deleted from the queue once `done()` is called.
+* Calling `done(err)` with an error object will cause the message to be left on the queue. An [SQS redrive policy](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/SQSDeadLetterQueue.html) can be used to move messages that cannot be processed to a dead letter queue.
+
+To stop listening for new messages simply call `.stop()`:
+
+```js
+queue.stop();
+```
+
+### Polling a single message
+
+You can also poll the single next message from the queue.
+
+```js
+queue.receiveMessage({
+    visibilityTimeout: 300
+}, function(err, data) {
+    console.log(data);
+});
+```
+
+### Sending messages
+
+To send new messages to the queue use `.sendMessage()`:
+
+```js
+queue.sendMessage({
+    message: { text: 'hello' },
+    delaySeconds: 0
+}, function(err) {
+    // Error handling here...
+});
+```
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

index.js

@@ -0,0 +1,113 @@
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+
+var AWS = require('aws-sdk');
+var Consumer = require('sqs-consumer');
+
+/**
+ * Build SQS-based micro-services without the boilerplate.
+ */
+
+class SQSUtils {
+
+    /**
+     * Create a new SQSUtils instance.
+     */
+
+    constructor(options) {
+        options = options || {};
+        this.queueUrl = options.queueUrl;
+        this.sqs = options.sqs || new AWS.SQS({
+                accessKeyId: options.accessKeyId || process.env.AWS_ACCESS_KEY_ID,
+                secretAccessKey: options.secretAccessKey || process.env.AWS_SECRET_ACCESS_KEY,
+                region: options.region || process.env.AWS_REGION || 'eu-west-1',
+            });
+        this.bot = null; // Initially do not create a sqs-consumer bot for polling
+    }
+
+    /**
+     * Continuously pull the queue for messages using long polling.
+     */
+
+    listen(options) {
+        options = options || {};
+        if(this.bot === null) {
+            // Create new sqs-consumer instance to poll messages
+            this.bot = new Consumer({
+                queueUrl: this.queueUrl,
+                sqs: this.sqs,
+                batchSize: options.batchSize || 1,
+                visibilityTimeout: options.visibilityTimeout || 300, // 5 minutes
+                handleMessage: options.handleMessage
+            });
+            this.bot.on('err', options.handleError);
+        }
+        this.bot.start();
+    }
+
+    /**
+     * Stop polling messages from the queue.
+     */
+
+    stop() {
+        // Call stop on sqs-consumer
+        this.bot.stop();
+    }
+
+    /**
+     * Send message to the queue and trigger callback.
+     */
+
+    sendMessage(options, callback) {
+        options = options || {};
+        var params = {
+            MessageBody: JSON.stringify(options.message) || '{}',
+            QueueUrl: this.queueUrl,
+            DelaySeconds: options.delaySeconds || 0
+        };
+        this.sqs.sendMessage(params, callback);
+    }
+
+    /**
+     * Pull the very next message from the queue.
+     */
+
+    receiveMessage(options, callback) {
+        options = options || {};
+        var params = {
+            QueueUrl: this.queueUrl,
+            MaxNumberOfMessages: 1, // Make sure only one message is pulled
+            VisibilityTimeout: options.visibilityTimeout || 300 // 5 minutes
+        };
+        this.sqs.receiveMessage(params, callback);
+    }
+
+    /**
+     * Delete a single message from the queue.
+     */
+
+    deleteMessage(message, callback) {
+        var params = {
+            QueueUrl: this.queueUrl,
+            ReceiptHandle: message.ReceiptHandle
+        };
+        this.sqs.deleteMessage(params, callback);
+    }
+
+    /**
+     * DANGER: Deletes all messages in the queue.
+     */
+
+    purgeQueue(callback) {
+        var params = {
+            QueueUrl: this.queueUrl
+        };
+        this.sqs.purgeQueue(params, callback);
+    }
+
+}
+
+module.exports = SQSUtils;

package.json

@@ -0,0 +1,25 @@
+{
+  "name": "sqs-utils",
+  "version": "1.0.0",
+  "description": "Amazon SQS applications without the boilerplate.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BenBestmann/sqs-utils.git"
+  },
+  "keywords": [
+    "sqs",
+    "aws",
+    "amazon",
+    "queue"
+  ],
+  "author": "Benjamin Bestmann",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/BenBestmann/sqs-utils/issues"
+  },
+  "homepage": "https://github.com/BenBestmann/sqs-utils#readme"
+}