uservit

uservit

This library is used throught the switch_paas project to server its microservices through ServerLess. It provides a thin layer over the Lambda API interface for:

• Supporting Promises.
• You can also return a regular value instead of a promise.
• Allows to return custom headers and HTTP status codes from your handlers in a unified way.
• Creates a special case for bad requests (client errors) and returns HTTP status code 400.
• As above, but for unexpected errors, it returns HTTP status code 500.
• Returns the result of your handlers always in the same way by providing a result field in the response.
• Adds CORS headers by default.

Installing

Add this library to your package.json configuration:

  "dependencies": {
    "uservit": "latest"
  }

Using it

Some examples follow, but more examples can be found in the tests.

Let's say you want to handle a request with the function users.get (that would be the function get inside the module users), you would write your ServerLess service handler like this:

  'use strict';
  var uservit = require('uservit');

  exports.hello = function (event, context, callback) {
    return uservit.handle(event, context, callback, 'users', 'get');
  };

That's it! In your service (the function users.get) you can then do:

  'use strict';
  var promise = require('promise');

  exports.get = function (event, context) {
    return promise.resolve().
    then(function () {
      //
    }).
    then(function () {
      //
    }).
    catch(function (err) {
      // ...
    });
  };

Returning successful responses

Just return a body field with what you want, like:

{
  body: {
    success: true
  }
}

And the HTTP client will see a payload like:

{
  "result": {
    "success": true
  }
}

Returning custom HTTP status codes and Headers

{
  statusCode: 999,
  headers: {
    'custom-header': 'a value'
  }
}

Returning client errors

You can fail your promise and return something like this:

  return promise.reject({
    clientError: true,
    message: 'some_client_error'
  });

And the HTTP client will see an HTTP status code of 400 with a payload like:

{
  "message": "some_client_error"
}

Unexpected errors

When something in your code fails, your promises will also be rejected and your client will see an HTTP status code 500 with a payload like:

{
  "message": "internal_error"
}

Developers

This project uses standard npm scripts. Current tasks include:

• test: Runs Mocha tests.
• jsdoc: Runs JSDoc3.
• eslint: Runs ESLint.
• coverage: Runs the tests and then Instanbul to get a coverage report.
• build: This is the default task, and will run all the other tasks.

Running an npm task

To run a task, just do:

npm run build

Contributing

To contribute:

• Make sure you open a concise and short pull request.
• Throw in any needed unit tests to accomodate the new code or the changes involved.
• Run npm run build and make sure everything is ok before submitting the pull request (make eslint happy).
• Your code must comply with the Javascript Standard Style, ESLint should take care of that.

License

The source code is released under Apache 2 License.

Check LICENSE file for more information.