Narcissistic Preening Monarch

    lambda-promise-interop
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    lambda-promise-interop

    Have you ever found yourself wishing you could use the async/await syntax in the unit tests of your Lambda handlers? Or wished there was a way to just write a Lambda handler as an async function that takes in an event & context and returns some result? Well now you can.

    This package offers two tiny functions for transforming traditional handler functions to promisified async ones and vice versa. Type definitions for TypeScript users are included as well.

    Installation

    npm install --save lambda-promise-interop
    

    API

    handlerifyAsyncFn<E, R>

    Input:

    • fn: (event: E, context: Context) => Promise<R>

    Output:

    • Handler<E, R>

    Description:

    Transforms simple (Event, Context) => Promise<Result> functions into functions that are compatible with the Handler type that AWS Lambda expects. This lets you write a simple function signature that is easily testable and fits neatly with the async/await model.

    promisifyHandler<E, R>

    Input:

    • handler: Handler<E, R>

    Output:

    • (event: E, context: Context) => Promise<R>

    Description:

    Transforms lambda handler functions into functions that take in an event input object E and return a promise of type R. This is useful for unit-testing of traditionally written lambda handlers, as it makes it much easier to just write tests using async/await syntax.

    Usage

    Importing

    import { handlerifyAsyncFn, promisifyHandler } from 'lambda-promise-interop'

    TypeScript users may also find it helpful to take a devDependency on @types/aws-lambda, since that includes many useful type definitions.

    Turning Async Functions into Lambda Handlers

    You have to point Lambda do a function that matches a signature of <T, R>(T, Context, Callback<R>) => void. It'd be preferable to just return a Promise or write an async function instead of invoking a callback and making sure you account for both synchronous and asynchronous errors. That would make code more readable and easier to test.

    JavaScript example:

    import { handlerifyAsyncFn } from 'lambda-promise-interop'
    import { someAsyncThing, ClientError } from './lib/example'
     
    // Our easily testable and readable async function
    const myApi = async (event, context) => {
      let body, statusCode
      try {
        body = await someAsyncThing(event.body)
        statusCode = 200
      } catch (err) {
        body = err.message
        statusCode = (err instanceof ClientError) ? 400 : 500
      }
      return { body, statusCode }
    }
     
    // A handler function in the signature that Lambda expects
    const handler = handlerifyAsyncFn(myApi)
     
    // We export `myApi` just for ease of testing and export `handler` for Lambda to
    // actually use.
    export { handler, myApi }

    TypeScript example:

    import { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda'
    import { handlerifyAsyncFn } from 'lambda-promise-interop'
    import { someAsyncThing, ClientError } from './lib/example'
     
    // Our easily testable and readable async function
    const myApi = async (event: APIGatewayProxyEvent, context: Context): APIGatewayProxyResult => {
      let body: string
      let statusCode: number
      try {
        body = await someAsyncThing(event.body)
        statusCode = 200
      } catch (err) {
        body = err.message
        statusCode = (err instanceof ClientError) ? 400 : 500
      }
      return { body, statusCode }
    }
     
    // A handler function in the signature that Lambda expects
    const handler = handlerifyAsyncFn(myApi)
     
    // We export `myApi` just for ease of testing and export `handler` for Lambda to
    // actually use.
    export { handler, myApi }

    Promisifying Normal Lambda Handlers

    If you already have Lambda handler functions written, you may have noticed that it's somewhat painful to test them. JS testing frameworks like Jest support async functions, but Lambda handlers force you back into Callback Hell if you want to run any assertions before your test is done.

    You're stuck writing something like this:

    // Example spec
     
    import { handler } from '../index'
    import mockContext from 'aws-lambda-mock-context'
     
    describe('My Lambda Handler', () => {
      it('does something', (done) => {
        handler({someInput: 'foo'}, mockContext(), (err, res) => {
          expect(err).toBeFalsy()
          expect(res.someValue).toEqual(something)
          done(undefined, res)
        })
      })
    })

    With this library, you can instead write that same test as:

    // Example spec
     
    import { handler } from '../index'
    import mockContext from 'aws-lambda-mock-context'
    import { promisifyHandler } from 'lambda-promise-interop'
     
    const asyncHandler = promisifyHandler(handler)
     
    describe('My Lambda Handler', () => {
      it('does something', async () => {
        const res = await asyncHandler({someInput: 'foo'}, mockContext())
        expect(res.someValue).toEqual(something)
      })
    })

    License

    MIT

    Install

    npm i lambda-promise-interop

    DownloadsWeekly Downloads

    26

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    12.4 kB

    Total Files

    6

    Last publish

    Collaborators

    • bilalq