saws

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 16 Open GitHub ↗

Provides abstraction layer for core AWS application services such as DynamoDB, SNS, and SQS

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Saws

Simple AWS abstraction library for Node.

## Purpose

Provides a flexible and testable abstraction layer for core AWS application services such as DynamoDB, SNS and SQS so that your code doesn't end up as tightly coupled to the platform. Helps immensely with testability and other concerns related to maintaining a so-called hexagonal architecture. <http://alistair.cockburn.us/Hexagonal+architecture>

Perfect for Serverless architecture style. Learn more at <http://leanpub.com/serverless>

## Installing

```sh
npm install saws
```

## Usage

Initialize with the `AWS` sdk instance.

```javascript
var AWS = require('aws-sdk');
var Saws = require('saws').Saws;
var saws = new Saws(AWS);
```

or slightly shorter as:

```javascript
var AWS = require('aws-sdk');
var saws = new require('saws').Saws(AWS);
```

### Setting the Region
The AWS SDK for Node.js doesn't select the region by default. You can choose a region using AWS.config.update()

```
AWS.config.update({region:'us-east-1'});
```

### Stage Variable

Set a value for the stage variable to indicate which environment you're running in. This is useful in conjunction with frameworks such as <http://serverless.com>

```javascript
// defaults to 'development'
saws.stage = process.env.SERVERLESS_STAGE;
```

Now just instantiate saws for tables, topics and queues as needed in your code. Enjoy the simple interface.

### DynamoDB

Define table params as per Dynamo's `createTable` specification. [link](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#createTable-property)

```javascript
var STRIPE_CUSTOMERS_PARAMS = {
  TableName: "StripeCustomers",
  KeySchema: [
    {AttributeName: 'IdentityId', KeyType: 'HASH'},
  ],
  AttributeDefinitions: [
    {AttributeName: 'IdentityId', AttributeType: 'S'}
  ],
  ProvisionedThroughput: { ReadCapacityUnits: 2, WriteCapacityUnits: 1 }
};
```

Then instantiate a `saws.Table` object using the params. Note that stage name is appended to the name of the table created.

```javascript
var customers = new saws.Table(STRIPE_CUSTOMERS_PARAMS);
```

#### delete(item, cb)

Delete a record from the table instance.

```javascript
// You can simply specify the key and value:

customers.delete({
  "IdentityId": "id0000001"
}, function(err, data) {
  ...
});

// Or to use the extended parameters supported by DynamoDB.DocumentClient.delete, specify all params;

customers.delete({
  "Key": {
      "IdentityId": "id0000001"
  },
  "ReturnValues": "ALL_OLD"
}, function(err, data) {
  ...
});
```

The `delete` operation accepts [the same paremeters as `DynamoDB.DocuemntClient.delete`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#delete-property).

#### save(item, cb)

Use the table instance to save records.

```javascript
customers.save({
  "IdentityId": "id0000001",
  "StripeCustomerId": "cus_00000001"
}, function(err, data) {
  ...
});
```

The `save` operation is asynchronous. It takes an object and a callback to be invoked when the operation completes. The object parameter must contain top-level key(s) matching your `KeySchema` or the operation will fail. The object parameter may have nested object structures and they will be saved properly similar to the way that MongoDB and other document databases work.

Note: As with all Saws, creation of the underlying resource is automatic. In this case, when saving a record, if the DynamoDB table does not already exist, Saws will create it and wait for it to be available before proceeding with the operation.

#### lookup(params, cb)

Use the table instance to retrieve records.

```javascript
customers.lookup({"IdentityId": "id0000001"}, function(err, data) {
  console.log(data) // => { "IdentityId": "id0000001", "StripeCustomerId": "cus_00000001" },
});
```

The `lookup` operation is asynchronous. It takes a key parameter and a callback to be invoked when the operation completes. The `params` object must contain top-level key(s) matching your `KeySchema` or the operation will fail.

#### scan(params, cb)

A thin wrapper around `DynamoDB.DocuemntClient.scan`, accepting the [same parameters](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#scan-property).

The `TableName` should not be passed.

Returns one or more items and item attributes by accessing every item in a table or a secondary index.

```javascript
customers.scan({"Verified": false}, function(err, data) {
  console.log(data) // => [{ "IdentityId": "id0000001", "Verified": false}, { "IdentityId": "id0000004", "Verified": false}]
});
```

### SNS (Simple Notification Service)

Start by instantiating a topic object.

```javascript
var topic = new saws.Topic("NewOrders");
```

#### Automatic Topic Creation

Creating a `Topic` will automatically create an SNS Topic on AWS if it does not already exist. The value of `saws.stage` is appended to the topic name.

#### publish(payload, cb)

Send a message using `publish`. First argument is the payload, second is a callback to be invoked when publishing is done.

```javascript
topic.publish("a new order has arrived", function(err, data) { ... });
```

The callback is invoked when a response from the service is returned.  The context of the callback (`this`) is set to the response object containing error, data properties, and the original request object.

**`data`** is an object with the de-serialized data returned from the request with a ` MessageId` property corresponding to the unique identifier string identifier assigned by SNS to the published message.

#### Expects to be using JSON as payload format

Payload is automatically run through `JSON.stringify()`.

```javascript
var topic = new saws.Topic("NewOrders");
topic.publish({
  NewOrder: {
      userId: user.userId,
      deliveryAddress: user.deliveryAddress,
      stripeSource: user.stripeSource,
      preferences: user.preferences
    }
}, done);
```

#### SNSEvent

Convenience object for easily processing SNS events in Lambda functions.

Wrap the `event` provided to your Lambda's handler function in a `new SNSEvent` object for convenient handling. The SNSEvent instance provides an `eachMessage` iterator with a callback that is invoked for each SNS `Record` contained in the event. The callback gets two parameters, the whole message object itself and `JSON.parse`'d payload.

```javascript
var chck = require('chck');

// a Lambda function handling an SNS event
exports.handler = function(event, context) {
  var e = new saws.SNSEvent(event);
  e.eachMessage(function(message, order) {
    if(chck(order, {
      NewOrder: {
        userId: {$present: true}
        PaymentReceipt: {$present: true}
        FeedbackHistory: {$present: false}
      }
    })) {
      // handle the order...
    }
    else {
      context.success('failed chck guard');
    }
  });
```

### SQS (Simple Queue Service)

_coming soon_

## Debug

Set `SAWS_DEBUG` to true in your environment to enable debug output to the console.

## Testing

To test your code which uses Saws, you can pass it a stubbed AWS during initialization to ensure no callouts are actually made. For your convenience, one that stubs all services that Saws supports is available as `AWSStub`:

```javascript
var mockSaws = new require('saws').Saws(require('saws').AWSStub);
```

Now you're able to stub only the Saws methods you need to and pass this as a dependency without worrying about any accidental callouts.

saws

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README