update documentation and tests

Author: manwaring

CHANGELOG.md

@@ -4,6 +4,12 @@ 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)
 
+## [4.1.1]  (2020-10-31)
+
+### Changed
+
+- Update documentation
+
 ## [4.1.0]  (2020-10-31)
 
 ### Added
@@ -307,6 +313,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/),
 - Update older libraries
 - Now publish from Git tags instead of master pushes
 
+[4.1.1]: https://github.com/manwaring/lambda-wrapper/compare/v4.1.0...v4.1.1
 [4.1.0]: https://github.com/manwaring/lambda-wrapper/compare/v4.0.6...v4.1.0
 [4.0.6]: https://github.com/manwaring/lambda-wrapper/compare/v4.0.5...v4.0.6
 [4.0.5]: https://github.com/manwaring/lambda-wrapper/compare/v4.0.4...v4.0.5

README.md

@@ -152,6 +152,7 @@ export interface ApiSignature<T = any> {
   notAuthorized(params?: ResponseParameters): ApiResponse;
   redirect(params: RedirectParameters): ApiResponse;
   error(params?: ErrorParameters): ApiResponse;
+  custom(params: CustomParameters): ApiResponse;
 }
 ```
 
@@ -215,6 +216,22 @@ interface ErrorParameters {
 
 </details>
 
+<details>
+<summary>CustomParameters</summary>
+
+```ts
+interface CustomParameters {
+  body?: any; // response body
+  json?: boolean; // indicates if body should be JSON-stringified and content-type header set to application/json, defaults to true
+  cors?: boolean; // indicates if CORS headers should be added, defaults to true
+  statusCode: number; // status code to return
+  headers?: { [key: string]: any }; // custom headers to include
+  err?: Error; // optional Error object for automatic logging
+}
+```
+
+</details>
+
 <details>
 <summary>WebsocketRequest</summary>
 
@@ -543,7 +560,7 @@ return redirect({ url, statusCode: 308, cors: false });
   cors?: boolean,
   statusCode?: number,
   headers?: { [key: string]: any},
-  err?: Error;
+  err?: Error
 }
 ```
 
@@ -596,6 +613,65 @@ console.debug(err);
 
 </details>
 
+<details>
+<summary>Custom</summary>
+
+### Available parameters
+
+```ts
+{
+  body?: any,
+  json?: boolean,
+  cors?: boolean,
+  statusCode: number,
+  headers?: { [key: string]: any},
+  err?: Error
+}
+```
+
+### Default parameters
+
+```ts
+{
+  json: true,
+  cors: true,
+}
+```
+
+### Invocation with defaults
+
+```ts
+return custom({ statusCode: 418 });
+
+// returns
+{
+  statusCode: 418,
+  headers: {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Credentials': true,
+  }
+}
+```
+
+### Invocation overriding defaults
+
+```ts
+const body = { message: 'Custom response' };
+return custom({ body, statusCode: 418 });
+
+// returns
+{
+  body: "{\"message\": \"Custom response\"}",
+  statusCode: 418,
+  headers: {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Credentials': true,
+  }
+}
+```
+
+</details>
+
 # API Gateway HTTP API
 
 Other than the raw payload from AWS the HTTP API method signature and response functions match the API Gateway signature and functions. Hooray for wrappers! Note that you still need to provide the correct wrapper function so that the library can parse the AWS event correctly.
@@ -667,6 +743,7 @@ export interface HttpApiSignature<T = any> {
   notAuthorized(params?: ResponseParameters): ApiResponse;
   redirect(params: RedirectParameters): ApiResponse;
   error(params?: ErrorParameters): ApiResponse;
+  custom(params: CustomParameters): ApiResponse;
 }
 ```
 
@@ -730,6 +807,22 @@ interface ErrorParameters {
 
 </details>
 
+<details>
+<summary>CustomParameters</summary>
+
+```ts
+interface CustomParameters {
+  body?: any; // response body
+  json?: boolean; // indicates if body should be JSON-stringified and content-type header set to application/json, defaults to true
+  cors?: boolean; // indicates if CORS headers should be added, defaults to true
+  statusCode: number; // status code to return
+  headers?: { [key: string]: any }; // custom headers to include
+  err?: Error; // optional Error object for automatic logging
+}
+```
+
+</details>
+
 <details>
 <summary>HttpApiEvent</summary>
 
@@ -1127,6 +1220,65 @@ console.debug(err);
 
 </details>
 
+<details>
+<summary>Custom</summary>
+
+### Available parameters
+
+```ts
+{
+  body?: any,
+  json?: boolean,
+  cors?: boolean,
+  statusCode: number,
+  headers?: { [key: string]: any},
+  err?: Error
+}
+```
+
+### Default parameters
+
+```ts
+{
+  json: true,
+  cors: true,
+}
+```
+
+### Invocation with defaults
+
+```ts
+return custom({ statusCode: 418 });
+
+// returns
+{
+  statusCode: 418,
+  headers: {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Credentials': true,
+  }
+}
+```
+
+### Invocation overriding defaults
+
+```ts
+const body = { message: 'Custom response' };
+return custom({ body, statusCode: 418 });
+
+// returns
+{
+  body: "{\"message\": \"Custom response\"}",
+  statusCode: 418,
+  headers: {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Credentials': true,
+  }
+}
+```
+
+</details>
+
 # CloudFormation Custom Resource
 
 ## Sample TypeScript implementation

jest.config.js

@@ -1,4 +1,4 @@
 module.exports = {
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*index.ts'],
-  coverageThreshold: { global: { lines: 90 }}
+  coverageThreshold: { global: { lines: 90 } },
 };

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@manwaring/lambda-wrapper",
   "description": "A lambda handler wrapper to abstract common functionality and provide useful defaults",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "scripts": {
     "publish-please-dry-run": "publish-please --dry-run",
     "publish-please": "publish-please",

package.json

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-empty-function */
 import { apiGatewayEvent } from 'serverless-plugin-test-helper';
 import { api, ApiSignature } from './wrapper';
 
@@ -28,7 +29,7 @@ describe('API wrapper', () => {
   const callback = jest.fn((err, result) => (err ? new Error(err) : result));
 
   it('Has expected properties and response functions', () => {
-    function custom({
+    function customHandler({
       event,
       websocket,
       body,
@@ -43,6 +44,7 @@ describe('API wrapper', () => {
       invalid,
       redirect,
       error,
+      custom,
     }: ApiSignature) {
       expect(event).toEqual(requestEvent);
       expect(websocket.connectionId).toEqual('abc-123');
@@ -58,17 +60,18 @@ describe('API wrapper', () => {
       expect(invalid).toBeInstanceOf(Function);
       expect(redirect).toBeInstanceOf(Function);
       expect(error).toBeInstanceOf(Function);
-      success('success');
+      expect(custom).toBeInstanceOf(Function);
+      success({ body: 'success' });
     }
-    api(custom)(requestEvent, context, callback);
+    api(customHandler)(requestEvent, context, callback);
   });
 
   it('Has expected properties and response functions with optional generic type', () => {
     interface CustomType {
       Message: string;
       Id: number;
     }
-    function custom({
+    function customHandler({
       event,
       websocket,
       body,
@@ -83,6 +86,7 @@ describe('API wrapper', () => {
       invalid,
       redirect,
       error,
+      custom,
     }: ApiSignature<CustomType>) {
       expect(event).toEqual(requestEvent);
       expect(websocket.connectionId).toEqual('abc-123');
@@ -98,8 +102,9 @@ describe('API wrapper', () => {
       expect(invalid).toBeInstanceOf(Function);
       expect(redirect).toBeInstanceOf(Function);
       expect(error).toBeInstanceOf(Function);
-      success('success');
+      expect(custom).toBeInstanceOf(Function);
+      success({ body: 'success' });
     }
-    api(custom)(requestEvent, context, callback);
+    api(customHandler)(requestEvent, context, callback);
   });
 });

src/api/v1/wrapper.test.ts

@@ -12,10 +12,11 @@ import {
   ResponseParameters,
   RedirectParameters,
   ErrorParameters,
+  CustomParameters,
 } from '../shared';
 
 export function api<T = any>(
-  custom: (props: ApiSignature<T>) => any
+  customHandler: (props: ApiSignature<T>) => any
 ): (event: APIGatewayEvent, context: Context, callback: Callback) => any {
   return function handler(event: APIGatewayEvent) {
     const { body, websocket, path, query, auth, headers, testRequest } = new Request(event).getProperties();
@@ -36,7 +37,7 @@ export function api<T = any>(
       redirect,
       custom,
     };
-    return custom(signature);
+    return customHandler(signature);
   };
 }
 
@@ -55,7 +56,7 @@ export interface ApiSignature<T = any> {
   notAuthorized(params?: ResponseParameters): ApiResponse;
   redirect(params: RedirectParameters): ApiResponse;
   error(params?: ErrorParameters): ApiResponse;
-  custom(params: ResponseParameters): ApiResponse;
+  custom(params: CustomParameters): ApiResponse;
 }
 
 export interface WebsocketRequest {