remove iopipe and epsagon, switch from callback to response/error, and update to 2.0

Author: manwaring

.npmrc

@@ -0,0 +1 @@
+loglevel=silent

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html)
 
+## [2.0.0]  (2020-01-04)
+
+### Changed
+
+- Removed references to Epsagon and IOPipe
+- Instead of callbacks, response methods use the recommended return syntax
+
+### Added
+
+- V2 of the docs
+
 ## [1.2.2]  (2019-10-14)
 
 ### Changed

README.md

@@ -9,6 +9,8 @@
 
 # AWS Lambda wrapper library
 
+### This documentation is for v2 of the library - see [old-docs/v1/README.md for the v1 documentation](old-docs/v1/README.md)
+
 1. [Overview](#overview)
 1. [Installation and setup](#installation-and-setup)
    - [Optional configuration](#optional-configuration)
@@ -31,7 +33,7 @@ This library provides custom Lambda function wrappers which expose standard, abs
 
 ### Rationale and motivation
 
-AWS Lambda supports a wide variety of event triggers, each with unique payloads and expected responses. The Lambda execution environment, however, only provides the raw events and has no included mechanisms for simplifying response object creation. For example, API Gateway events include only the raw request body, leaving it up to developers to implement parsing themselves. Similarly, the developer is responsible for creating a response object which includes the correct HTTP Status Code and headers. Given the standard nature of these kinds of concerns, this library exposes helpful abstractions like parsed HTTP bodies based on content-type headers, and success response functions which apply correct status codes and headers before invoking the Lambda callback.
+AWS Lambda supports a wide variety of event triggers, each with unique payloads and expected responses. The Lambda execution environment, however, only provides the raw events and has no included mechanisms for simplifying response object creation. For example, API Gateway events include only the raw request body, leaving it up to developers to implement parsing themselves. Similarly, the developer is responsible for creating a response object which includes the correct HTTP status code and headers. Given the standard nature of these kinds of concerns, this library exposes helpful abstractions like parsed HTTP bodies based on content-type headers, and success response functions which create response objects with the correct status codes and headers for returning.
 
 # Installation and setup
 
@@ -71,9 +73,9 @@ export const handler = api(async ({ body, path, success, error }) => {
   try {
     const { pathParam1, pathParam2 } = path;
     const results = await doSomething(body, pathParam1, pathParam2);
-    success(results);
+    return success(results);
   } catch (err) {
-    error(err);
+    return error(err);
   }
 });
 ```
@@ -89,10 +91,17 @@ interface ApiSignature {
   headers: { [name: string]: string }; // headers param payload as key-value pairs
   testRequest: boolean; // indicates if this is a test request, based on presence of headers matching 'Test-Request' or process.env.TEST_REQUEST_HEADER
   auth: any; // auth context from custom authorizer
-  success(payload?: any, replacer?: (this: any, key: string, value: any) => any): void; // returns 200 status with payload
-  invalid(errors?: string[]): void; // returns 400 status with errors
-  redirect(url: string): void; // returns 302 redirect with new url
-  error(error?: any): void; // returns 500 status with error
+  success(payload?: any, replacer?: (this: any, key: string, value: any) => any): ApiResponse; // returns 200 status with payload
+  invalid(errors?: string[]): ApiResponse; // returns 400 status with errors
+  notFound(message?: string): ApiResponse; // returns 404 status with message
+  redirect(url: string): ApiResponse; // returns 302 redirect with new url
+  error(error?: any): ApiResponse; // returns 500 status with error
+}
+
+interface ApiResponse {
+  statusCode: number;
+  headers: { [name: string]: string | boolean };
+  body?: string;
 }
 ```
 
@@ -108,9 +117,9 @@ import { cloudFormation } from '@manwaring/lambda-wrapper';
 export const handler = cloudFormation(({ event, success, failure }) => {
   try {
     const { BucketName } = event.ResourceProperties;
-    success();
+    return success();
   } catch (err) {
-    failure(err);
+    return failure(err);
   }
 });
 ```
@@ -152,8 +161,8 @@ interface DynamoDBStreamSignature {
   newVersions: any[]; // array of all unmarshalled javascript objects of new images
   oldVersions: any[]; // array of all unmarshalled javascript objects of old images
   versions: Version[]; // array of full version object (new image, old image, etc - see Version interface)
-  success(message?: any): void; // invokes lambda callback with success
-  error(error?: any): void; // invokes lambda callback with error
+  success(message?: any): any; // logs and returns the message
+  error(error?: any): void; // logs the error and throws it
 }
 
 interface Version {
@@ -180,9 +189,9 @@ export const handler = authorizer(async ({ token, valid, invalid }) => {
       return invalid('Missing token');
     }
     const jwt = await verifier.verifyAccessToken(token);
-    valid(jwt);
+    return valid(jwt);
   } catch (err) {
-    invalid(err);
+    return invalid(err);
   }
 });
 ```
@@ -193,9 +202,21 @@ export const handler = authorizer(async ({ token, valid, invalid }) => {
 interface AuthorizerSignature {
   event: CustomAuthorizerEvent; // original event
   token: string; // authorizer token from original event
-  valid(jwt: any): void; // creates AWS policy to authenticate request, and adds auth context if available
-  invalid(message?: string[]): void; // returns 401 unauthorized
-  error(error?: any): void; // records error information and returns 401 unauthorized
+  valid(jwt: any): Policy; // returns AWS policy to authenticate request, and adds auth context if available
+  invalid(message?: any): void; // records invalid information and throws 401 unauthorized
+  error(error?: any): void; // records error information and throws 401 unauthorized
+}
+
+interface Policy {
+  principalId: string;
+  policyDocument: {
+    Version: string;
+    Statement: {
+      Action: string;
+      Effect: string;
+      Resource: string;
+    }[];
+  };
 }
 ```
 
@@ -221,9 +242,9 @@ export const handler = sns(async ({ message, success, error }) => {
 ```ts
 interface SnsSignature {
   event: SNSEvent; // original event
-  message: any; // JSON-parsed message from event (or raw message if not JSON)
-  success(payload?: any): void; // invokes lambda callback with success
-  error(error?: any): void; // invokes lambda callback with error
+  message: any; // JSON-parsed message from event
+  success(message?: any): any; // logs and returns the message
+  error(error?: any): void; // logs the error and throws
 }
 ```
 
@@ -238,9 +259,9 @@ export const handler = wrapper(async ({ event, success, error }) => {
   try {
     const { value1, value2 } = event;
     const results = await doSomething(value1, value2);
-    success(results);
+    return success(results);
   } catch (err) {
-    error(err);
+    return error(err);
   }
 });
 ```
@@ -250,8 +271,8 @@ export const handler = wrapper(async ({ event, success, error }) => {
 ```ts
 interface WrapperSignature {
   event: any; // original event
-  success(payload?: any): void; // invokes lambda callback with success response
-  error(error?: any): void; // invokes lambda callback with error response
+  success(message?: any): any; // logs and returns the message
+  error(error?: any): void; // logs the error and throws
 }
 ```
 

examples/ts/app/cloudformation.ts

@@ -3,8 +3,8 @@ import 'source-map-support/register';
 
 export const handler = cloudFormation(({ event, success, failure }) => {
   try {
-    success(event.ResourceProperties.BucketName);
+    return success(event.ResourceProperties.BucketName);
   } catch (err) {
-    failure(err);
+    return failure(err);
   }
 });

examples/ts/app/generic.ts

@@ -3,8 +3,8 @@ import 'source-map-support/register';
 
 export const handler = wrapper(async ({ event, success, error }) => {
   try {
-    success(event);
+    return success(event);
   } catch (err) {
-    error(err);
+    return error(err);
   }
 });