@laconia/core

@laconia/core

🛡️ Laconia Core — Micro dependency injection framework.

An AWS Lambda handler function is a single entry point for both injecting dependencies and function execution. In non-serverless development, you can and will normally only focus on the latter. This brings a unique challenge to AWS Lambda development as it is very difficult to test a handler function when it is responsible for doing both the object creations and the application run. @laconia/core is a simple dependency injection framework for your Lambda code, hence solving this problem for you.

Laconia explicitly splits the responsibility of the object creations and Lambda function execution. Laconia also provides a simple way for you to execute your Lambda function so that your unit tests will not execute the code that instantiates your Lambda dependencies.

FAQ

Check out FAQ

Features

• Dependency injection
• Caching for heavy instance creation
• Reduce boilerplate code
• Avoid common Lambda programming error

One of the problem in AWS Lambda is the UnhandledPromiseRejectionWarning problem where you can't throw an error out of your handler function. By simply using laconia, you will avoid this common problem.

Install

npm install --save @laconia/core

Dependency Injection

To fully understand how Laconia's Dependency Injection works, let's have a look into an example below. This is not a running code as there are a lot of code that have been trimmed down, full example can be found in the acceptance test: src and unit test.

Lambda handler code:

// Objects creation, a function that returns an object
const instances = ({ env }) => ({
  orderRepository: new DynamoDbOrderRepository(env.ORDER_TABLE_NAME),
  idGenerator: new UuidIdGenerator()
});

// Handler function, which do not have any object instantiations
module.exports.handler = laconia(
  // Instances made available via destructuring
  async ({ event, orderRepository, idGenerator }) => {
    await orderRepository.save(order);
  }
).register(instances);

Unit test code:

const handler = require("../src/place-order").handler;

// Creates a mock Laconia context
beforeEach(() => {
  lc = {
    orderRepository: {
      save: jest.fn().mockReturnValue(Promise.resolve())
    }
  };
});

// Runs handler function without worrying about the objects creation
it("should store order to order table", async () => {
  await handler.run(lc);

  expect(lc.orderRepository.save).toBeCalledWith(
    expect.objectContaining(order)
  );
});

Note that as you have seen so far, Laconia is not aiming to become a comprehensive DI framework hence the need of you handle the instantiation of all of the objects by yourself. It should theoretically be possible to integrate Laconia to other more comprehensive NodeJS DI framework but it has not been tested.

LaconiaContext

Laconia provides a one stop location to get all of the information you need for your Lambda function execution via LaconiaContext. In a nutshell, LaconiaContext is just an object that contains all of those information by using object property keys, hence you can destructure it to get just the information you need.

AWS Event and Context

When Laconia is adopted, the handler function signature will change. Without Laconia, your handler signature would be event, context, callback. With Laconia, your handler signature would be laconiaContext. The event and context are always available in LaconiaContext. callback is not made available as this should not be necessary anymore when you are using Node 8, just return the value that you want to return to the caller inside the handler function.

Example:

laconia(({ event, context }) => true);

Environment Variables

It is very common to set environment variables for your Lambda functions. This is normally accessed via process.env. Unit testing a Lambda function that uses process.env is awkward, as you have to modify the process global variable and remember to remove your change so that it doesn't affect other test.

For better unit testability, LaconiaContext contains the environment variables with key env.

Example:

laconia(({ env }) => true);

Cache

When #register is called, all of the instances returned by the function specified will be cached by default and will expire every 5 minutes. It is therefore a good practice to offload some of the heavy operations that don't change on every Lambda run to LaconiaContext. This feature can be turned off, see API section.

API

laconia(fn)

• fn(laconiaContext)
  • This Function is called when your Lambda is invoked
  • Will be called with laconiaContext object, which can be destructured to {event, context}

Example:

// Simple return value
laconia(() => "value");

// Return a promise and 'value' will be returned to the Lambda caller
laconia(() => Promise.resolve("value"));

register(factoryFn, options)

Registers objects into LaconiaContext. Objects registered here will be made available in the Lambda function execution.

• factoryFn(laconiaContext)
  • This Function is called when your Lambda is invoked
  • An object which contains the instances to be registered must be returned
• options:
  • cache
    • enabled = true
      • Set to false to turn off caching
    • maxAge = 300000
      • Your factoryFn will be called when the cache has reached its maximum age specified by this option

Example:

// Register an object with key 'service'
laconia(({ service }) => service.call()).register(() => ({
  service: new SomeService()
}));

// Reduce maxAge
const handler = () => {};
laconia(handler).register(
  async () => (
    {
      /* heavy operations */
    },
    {
      cache: {
        maxAge: 1000
      }
    }
  )
);

run(laconiaContext)

Runs Lambda handler function with the specified laconiaContext and bypasses the LaconiaContext registration step. This function should only be used in a unit test.

• laconiaContext
  • A plain object that should represent the LaconiaContext to be used in the function execution

// Runs a handler function with a LaconiaContext that contains a mock service object.
// `SomeService` will not be instantiated
laconia(({ service }) => service.call())
  .register(() => ({
    service: new SomeService()
  }))
  .run({
    service: jest.mock()
  });