@alexshelkov/lambda v1.7.3

Type-safe middleware for AWS Lambda

Leveraging the power of Typescript to build middleware-like request handlers for lambda functions with type-based dependency checking.

An example

A service which parse request body as JSON, get a and b from it, check if both are valid numbers, then adds them and return result.

import { Err, ok, fail } from '@alexshelkov/result';
import { MiddlewareCreator, Handler, JsonBodyService, creator, addService, jsonBodyService } from '@alexshelkov/lambda';

type NumberService = { a: number; b: number };
type NumberErrNaN = Err<'NaA'>;
type NumberDependencies = JsonBodyService;

const numbers: MiddlewareCreator<{}, NumberService, NumberErrNaN, NumberDependencies> = () => {
  return async (request) => {
    const body = request.service.jsonBody;

    if (!(Number.isFinite(body.a) && Number.isFinite(body.b))) {
      return fail<NumberErrNaN>('NaA');
    }

    const service = body as NumberService;

    return addService(request, service);
  };
};

type Options = { acceptFloat: boolean };
type AdderService = { add: (a: number, b: number) => number };
type AdderErrNoFloats = Err<'Float'>;

const adder: MiddlewareCreator<Options, AdderService, AdderErrNoFloats> = (options, { throws }) => {
  return async (request) => {
    const service: AdderService = {
      add: (a: number, b: number) => {
        if (!options.acceptFloat && !(Number.isInteger(a) && Number.isInteger(b))) {
          throws<AdderErrNoFloats>('Float');
        }

        return a + b;
      },
    };

    return addService(request, service);
  };
};

const handler: Handler<AdderService & NumberService, number, never> = async ({
  service: { a, b, add },
}) => {
  return ok(add(a, b));
};

const lambda = creator(jsonBodyService).srv(numbers).srv(adder).ok(handler);

API

Services

MiddlewareCreator

Type used for creating new services.

Params:

• Options
• Service
• Errors
• ServiceDeps
• Event

import { Err } from '@alexshelkov/result';
import { MiddlewareCreator, addService } from '@alexshelkov/lambda';

type Options = { };
type Service = { add: (a: number, b: number) => number };
type Errors = never;

const service: MiddlewareCreator<Options, Service, Errors> = () => {
  return async (request) => {
    return addService(request, {
      add: (a: number, b: number) => {
        return a + b;
      },
    });
  };
};

creator

Starts the creation of the lambda chain.

Params:

• creator: MiddlewareCreator

import { creator, empty } from '@alexshelkov/lambda';

const res = creator(empty); // now you can use other methods, for example: .srv 

srv

Adds a new service.

Params:

• creator: MiddlewareCreator

import { MiddlewareCreator, creator, empty, addService } from '@alexshelkov/lambda';

const service: MiddlewareCreator<{}, {}, never> = () => {
  return async (request) => {
    return addService(request, {});
  }
};

const res = creator(empty).srv(service); 

opt

Set the options.

Params:

• options

Handlers

ok

Adds a handler which will be run if all middleware creators executed successfully.

Params:

• handler: Handler

import { ok } from '@alexshelkov/result';
import { creator, empty } from '@alexshelkov/lambda';

const res = creator(empty).ok(async () => {
  return ok('success'); // can be used in onOk
});

fail

Adds a handler which runs on middleware failure.

Params:

• handler: HandlerError

import { ok } from '@alexshelkov/result';
import { creator, empty } from '@alexshelkov/lambda';

const res = creator(empty).fail(async () => {
  // this handler will not runs because 
  // empty middleware not fails
  
  return ok('success'); // can be used in onFail
});

fatal

Adds an unknown exception handler.

Params:

• handler: HandlerException

import { ok } from '@alexshelkov/result';
import { creator, empty } from '@alexshelkov/lambda';

const res = creator(empty).fatal(async () => {
  // this handler will not runs because 
  // empty middleware won't throw fatal errors
  
  return ok('success'); // can be used in onFatal
});

Transforms

onOk

Sets the result transformation of ok handler.

Params:

• transform: Transform

import { ok } from '@alexshelkov/result';
import { creator, empty } from '@alexshelkov/lambda';

const res = creator(empty).ok(async () => {
  return ok('success');
}).onOk(async (result) => {
  return result; // result equals to 'success'
});

onFail

Sets the result transformation of fail handler.

Params:

• transform: TransformError

import { ok } from '@alexshelkov/result';
import { creator, empty } from '@alexshelkov/lambda';

const res = creator(empty).fail(async () => {
  return ok('fail');
}).onFail(async (result) => {
  return result; // result equals to 'fail'
});

onFatal

Sets the result transformation of fatal handler.

Params:

• transform: TransformError

import { ok } from '@alexshelkov/result';
import { creator, empty } from '@alexshelkov/lambda';

const res = creator(empty).fatal(async () => {
  return ok('fatal');
}).onFatal(async (result) => {
  return result; // result equals to 'fatal'
});

on

Same as calling onOk, onFail and onFatal.

req

Returns AWS Lambda handler.