@smallwins/lambda

:raised_hands::seedling: @smallwins/lambda λ

• Author your AWS Lambda functions as pure node style callbacks (aka errbacks)
• Familiar middleware pattern for composition
• Event sources like DynamoDB triggers and SNS topics too
• Helpful npm scripts lambda-create, lambda-list, lambda-deploy and lambda-invoke

:satellite::satellite::satellite: λ returning json results :mailbox:

Here is a vanilla AWS Lambda example for performing a sum. Given event.query.x = 1 it will return {count:2}.

exports.handler = function sum(event, context) {
  var errors = []
  if (typeof event.query === 'undefined') {
    errors.push(ReferenceError('missing event.query'))
  }
  if (event.query && typeof event.query != 'object') {
    errors.push(TypeError('event.query not an object'))
  }
  if (typeof event.query.x === 'undefined') {
    errors.push(ReferenceError('event.query not an object'))
  }
  if (event.query.x && typeof event.query.x != 'number') {
    errors.push(TypeError('event.query not an object'))
  }
  if (errors.length) {
    // otherwise Error would return [{}, {}, {}, {}]
    var err = errors.map(function(e) {return e.message})
    context.fail(err) 
  }
  else {
    context.succeed({count:event.query.x + 1})
  }
}

A huge amount of vanilla Lambda code is working around quirky parameter validation. API Gateway gives you control over the parameters you can expect but this still means one or more of: headers, querystring paramters, form body, or url parameters. Event source style Lambdasare not much better because you get different payloads depending on the source. In the example above we are validating one query string parameter x. Imagine a big payload! 😮

Builtin Error needs manual serialization (and you still lose the stack trace). The latter part of the code uses the funky AWS context object.

We can do better:

var validate = require('@smallwins/validate')
var lambda = require('@smallwins/lambda')

function sum(event, callback) {
  var schema = {
    'query':   {required:true, type:Object},
    'query.x': {required:true, type:Number}
  }
  var errors = validate(event, schema)
  if (errors) {
    callback(errors)
  }
  else {
    var result = {count:event.query.x + 1}
    callback(null, result)
  }
}

exports.handler = lambda(sum)

@smallwins/validate cleans up parameter validation. The callback style above enjoys symmetry with the rest of Node and will automatically serialize Errors into JSON friendly objects including any stack trace. All you need to do is wrap a vanilla Node errback function in lambda which returns your function with an AWS Lambda friendly signature.

:loop::loop::loop: easily chain dependant actions ala middleware :loop::loop::loop:

Building on this foundation we can compose multiple errbacks into a Lambda. Lets compose a Lambda that:

• Validates parameters
• Checks for an authorized account
• And then returns data safely
• Or if anything fails return JSON serialized Error array

var validate = require('@smallwins/validate')
var lambda = require('@smallwins/lambda')

function valid(event, callback) {
  var schema = {
    'body':          {required:true, type:Object},
    'body.username': {required:true, type:String},
    'body.password': {required:true, type:String}
  }
  validate(event, schema, callback)
}

function authorized(event, callback) {
  var loggedIn = event.body.username === 'sutro' && event.body.password === 'cat'
  if (!loggedIn) {
    // err first
    callback(Error('not found'))
  }
  else {
    // successful login
    event.account = {
      loggedIn: loggedIn,
      name: 'sutro furry pants'
    }
    callback(null, event)
  }
}

function safe(event, callback) {
  callback(null, {account:event.account})
}

exports.handler = lambda(valid, authorized, safe)

In the example above our functions are executed in series passing event through each invocation. valid will pass event to authorized which in turn passes it to save. Any Error returns immediately so if we make it the last function we just send back the resulting account data. Clean!

:floppy_disk: save a record from a dynamodb trigger :boom::gun:

AWS DynamoDB triggers invoke a Lambda function if anything happens to a table. The payload is usually a big array of records. @smallwins/lambda allows you to focus on processing a single record but executes the function in parallel on all the results in the Dynamo invocation. For convenience the same middleware chaining is supported.

var lambda = require('@smallwins/lambda')

function save(record, callback) {
  console.log('save a version ', record)
  callback(null, record)
}

exports.handler = lambda.sources.dynamo.save(save)

:love_letter: api :thought_balloon::sparkles:

• lambda(...fns) create a lambda that returns a serialized json result {ok:true|false}
• lambda([fns], callback) create a lambda and handle result with your own errback formatter
• lambda.local(fn, fakeEvent, (err, result)=>) run a lamda locally offline by faking the event obj
• lambda.sources.dynamo.all(...fns)
• lambda.sources.dynamo.save(...fns)
• lambda.sources.dynamo.insert(...fns)
• lambda.sources.dynamo.modify(...fns)
• lambda.sources.dynamo.remove(...fns)

A handler looks something like this

function handler(event, callback) {
  // process event, use to pass data
  var result = {ok:true, event:event}
  callback(null, result)
}

:heavy_exclamation_mark: regarding errors :x::interrobang:

Good error handling makes your programs far easier to maintain. (This is a good guide.)[https://www.joyent.com/developers/node/design/errors]. When using @smallwins/lambda always use Error type as the first parameter to callback:

function fails(event, callback) {
  callback(Error('something went wrong')
}

Or an Error array:

function fails(event, callback) {
  callback([
    Error('missing email'), 
    Error('missing password')
  ])
}

@smallwins/lambda serializes error into Slack RPC style JSON making them easy to work from API Gateway:

{
  ok: false, 
  errors: [
    {name:'Error', message:'missing email', stack'...'},
    {name:'Error', message:'missing password', stack'...'}
  ]
}

#! scripting api :memo:

@smallwins/lambda includes some helpful automation code perfect for npm scripts. If you have a project that looks like this:

project-of-lambdas/
 |-test/
 |-src/
 |  '-lambdas/
 |     |-signup/
 |     |  |-index.js
 |     |  |-test.js
 |     |  '-package.json
 |     |-login/
 |     '-logout/
 '-package.json

And a package.json like this:

{
  "name":"project-of-lambdas",
  "scripts": {
    "create":"AWS_PROFILE=smallwins lambda-create",
    "list":"AWS_PROFILE=smallwins lambda-list",
    "deploy":"AWS_PROFILE=smallwins lambda-deploy",
    "invoke":"AWS_PROFILE=smallwins lambda-invoke",
    "deps":"AWS_PROFILE=smallwins lambda-deps"
  }
}

• :point_right: npm run create src/lambdas/forgot creates a new lambda
• :point_right: npm run list lists all deployed lambdas
• :point_right: npm run deploy src/lambdas/signup brian deploys the lambda with the alias brian
• :point_right:npm run invoke src/lambdas/login brian '{"email":"[e-mail]", "pswd":"..."}' to invoke a lambda
• :point_right:npm run deps src/lambdas/* for a report of all your lambda deps

The ./scripts/invoke.js is also a module and can be useful for testing.

var invoke = require('@smallwins/lambda/scripts/invoke')

invoke('path/to/lambda', alias, payload, (err, response)=> {
  console.log(err, response)
})