lambcycle

Lambcycle is a declarative lambda middleware. Its main purpose is to let you focus on the specifics of your application by providing a configuration cycle.

• Install
• Introduction
• Handler Lifecycle
• Error Handling
• Plugins
• Creating a Plugin
• Using a Plugin
• DevX
• About the project
• Contributing
• License

Install

# with npm
npm install --save lambcycle

# with yarn
yarn add lambcycle

Introduction

Lambcycle is a middleware for lambda functions. It defines a configurable life-cycle and allows you to focus on your application's logic. It has a "Feature as Plugin" approach, so you can easily create your own plugins or reuse your favorite packages with very little effort 🐑 🛵.

Checkout the following example or follow the link to 🎉 see some actual code 🎉 .

// with es6

import Joi from "joi";
import lambcycle from "lambcycle";

import pinoPlugin from './myPinoPlugin'
import joiPlugin from './myJoiPlugin'
import bodyParserPlugin from './myBodyParserPlugin'

import applicationLogic from "./mycode";

const processData = async (event, context) => {
  // beautiful application logic ...

  const manipulateData = event => {
    // ...
  };

  return await applicationLogic(manipulateData(event), context);
};

const schema = Joi.object()
  .keys({
    username: Joi.string().alphanum().min(5).required(),
    password: Joi.string().regex(/^[a-zA-Z0-9]{5,30}$/),
    email: Joi.string().email({ minDomainAtoms: 2 })
  });

const handler = lambcycle(processData).register([
  pinoPlugin,
  bodyParserPlugin,
  joiPlugin(schema)
]);

export default handler;

Handler lifecycle

The lifecycle provides a clear guideline to reason about your needs. Every step of the cycle can handle or throw errors making it easy to log, report or debug.

Error Handling

As you can see from the lifecycle graph above, the error object is a first class citizen that will stop the cycle and execute any error plugins declared in the register, it will then proceed to call the lambda handler's callback. Have a look at the Wrapper Interface to see what's available for reporting.

HINT: pretty much everything.

import lambcycle from 'lambcycle'
import notifyError from './myErrorNofifier'

const appLogic = async(event, context) => {
    const {error, data} = await amazingJob()
    if(error) {
        throw error
    }
}

const errorNotifier = {
    plugin: {
        onError: async (handler) => {
            /**
             * See IWrapper interface
            */
            await notifyError(handler.error)
        }
    }
}

const handler = lambcycle(appLogic).register([errorNotifier])

export default handler;

Plugins

• BodyParser: Parse incoming request bodies before your handler, available under the handler.event.body property.
• Joi: Object schema description language and validator for JavaScript objects. Validate requests without the pain!

Creating a plugin

A plugin is an object that can attach its hooks to one or more event cycles, it may provide its own configuration object.

type IPluginHookFunction = (
    wrapper: IWrapper,
    config: object,
    handleError?: Callback
) => void;

import * as Sentry from '@sentry/node';
import MyAwesomeIntegration from './MyAwesomeIntegration'

const sentryPlugin = (config) => {
    Sentry.init({
        dsn: `https://[e-mail]/${config.project}`,
        integrations: [new MyAwesomeIntegration()]
    });

    return {
        config,
        plugin: {
            onPreResponse: async (handlerWrapper, config) => {
                Sentry.captureMessage('some percentile log perhaps?')
            },
            onError: async (handlerWrapper, config) => {
                Sentry.captureException(handlerWrapper.error);
            }
        }
    }
}

export default sentryPlugin;

Using a plugin

Let's reuse the example above. Make sure your lambdas follow the Principle of least privilege and your secrets stay SECRET ㊙️

import lambcycle from 'lambcycle'
import sentryPlugin from './sentryPlugin'

const myApplicationLogic = async (event, context) => {
    await someLogic()
}

const handler = lambcycle(myApplicationLogic)
.register([
    sentryPlugin({
        key: process.env.SENTRY_KEY,
        project: process.env.SENTRY_PROJECT,
    })
]);

export default handler;

DevX

Lambcycle ships with type definitions, making the dev experience smoother 🚀 (VScode only).

About the project

This project has been built with lots of ❤️ and Typescript 🤣. It embraces the middleware pattern and uses types for consistency and documentation. If this approach seems familiar to you is because it was inspired by the awesome hapijs.

Contributing

As you can see the possibilities are endless when it comes to plugins! Everyone is welcome to contribute! Feel free to create issues or prs.

License

MIT License