finish adding generic types to wrappers and signatures

Author: manwaring

README.md

@@ -1,6 +1,6 @@
 <p align="center">
-  <img height="140" src="https://avatars0.githubusercontent.com/u/36457275?s=400&u=16d355f384ed7f8e0655b7ed1d70ff2e411690d8&v=4e">
-  <img height="140" src="https://user-images.githubusercontent.com/2955468/44874383-0168f780-ac69-11e8-8e51-774678cbd966.png">
+  <img height="150" src="https://d1wzvcwrgjaybe.cloudfront.net/repos/manwaring/lambda-wrapper/readme-category-icon.png">
+  <img height="150" src="https://d1wzvcwrgjaybe.cloudfront.net/repos/manwaring/lambda-wrapper/readme-repo-icon.png">
 </p>
 
 <p align="center">
@@ -86,8 +86,10 @@ All of the events bellow have a corresponding wrapper which provides a deconstru
 
 ```ts
 import { api } from '@manwaring/lambda-wrapper';
+import { CustomInterface } from './custom-interface';
 
-export const handler = api(async ({ body, path, success, error }) => {
+// By passing in CustomInterface as a generic the async method signature will correctly identify newVersions as an array of CustomInterface, making TypeScript development easier (note that the generic is not required in JavaScript projects)
+export const handler = api<CustomInterface>(async ({ body, path, success, error }) => {
   try {
     const { pathParam1, pathParam2 } = path;
     const results = await doSomething(body, pathParam1, pathParam2);
@@ -101,12 +103,12 @@ export const handler = api(async ({ body, path, success, error }) => {
 ### Properties and methods available on wrapper signature
 
 ```ts
-export interface ApiSignature {
+export interface ApiSignature<T> {
   event: APIGatewayEvent; // original event
-  body: any; // JSON parsed body payload if exists (otherwise null)
-  path: { [name: string]: string }; // path param payload as key-value pairs if exists (otherwise null)
-  query: { [name: string]: string }; // query param payload as key-value pairs if exists (otherwise null)
-  headers: { [name: string]: string }; // header payload as key-value pairs if exists (otherwise null)
+  body: T; // JSON parsed body payload if exists (otherwise undefined)
+  path: { [name: string]: string }; // path param payload as key-value pairs if exists (otherwise undefined)
+  query: { [name: string]: string }; // query param payload as key-value pairs if exists (otherwise undefined)
+  headers: { [name: string]: string }; // header payload as key-value pairs if exists (otherwise undefined)
   testRequest: boolean; // indicates if this is a test request - looks for a header matching process.env.TEST_REQUEST_HEADER (dynamic from application) or 'Test-Request' (default)
   auth: any; // auth context from custom authorizer if exists (otherwise null)
   success(payload?: any, replacer?: (this: any, key: string, value: any) => any): ApiResponse; // returns 200 status code with optional payload as body
@@ -161,6 +163,7 @@ interface CloudFormationSignature {
 
 ```ts
 import { dynamodbStream } from '@manwaring/lambda-wrapper';
+import { CustomInterface } from './custom-interface';
 
 // By passing in CustomInterface as a generic the async method signature will correctly identify newVersions as an array of CustomInterface, making TypeScript development easier (note that the generic is not required in JavaScript projects)
 export const handler = dynamodbStream<CustomInterface>(async ({ newVersions, success, error }) => {
@@ -251,8 +254,10 @@ interface Policy {
 
 ```ts
 import { sns } from '@manwaring/lambda-wrapper';
+import { CustomInterface } from './custom-interface';
 
-export const handler = sns(async ({ message, success, error }) => {
+// By passing in CustomInterface as a generic the async method signature will correctly identify newVersions as an array of CustomInterface, making TypeScript development easier (note that the generic is not required in JavaScript projects)
+export const handler = sns<CustomInterface>(async ({ message, success, error }) => {
   try {
     console.log(message);
     return success();
@@ -279,8 +284,10 @@ interface SnsSignature {
 
 ```ts
 import { wrapper } from '@manwaring/lambda-wrapper';
+import { CustomInterface } from './custom-interface';
 
-export const handler = wrapper(async ({ event, success, error }) => {
+// By passing in CustomInterface as a generic the async method signature will correctly identify newVersions as an array of CustomInterface, making TypeScript development easier (note that the generic is not required in JavaScript projects)
+export const handler = wrapper<CustomInterface>(async ({ event, success, error }) => {
   try {
     const { value1, value2 } = event;
     const results = await doSomething(value1, value2);
@@ -294,8 +301,8 @@ export const handler = wrapper(async ({ event, success, error }) => {
 ### Properties and methods available on wrapper signature
 
 ```ts
-interface WrapperSignature {
-  event: any; // original event
+interface WrapperSignature<T> {
+  event: T; // original event
   success(message?: any): any; // logs and returns the message
   error(error?: any): void; // logs the error and throws
 }

src/api/wrapper.test.ts

@@ -6,7 +6,7 @@ describe('API wrapper', () => {
     body: JSON.stringify({ hello: 'world' }),
     pathParameters: { proxy: 'not today' },
     queryStringParameters: { name: 'a test' },
-    headers: { 'content-type': 'application/json', 'Test-Request': 'true' }
+    headers: { 'content-type': 'application/json', 'Test-Request': 'true' },
   });
   const context = {
     callbackWaitsForEmptyEventLoop: false,
@@ -20,11 +20,12 @@ describe('API wrapper', () => {
     getRemainingTimeInMillis: () => 2,
     done: () => {},
     fail: () => {},
-    succeed: () => {}
+    succeed: () => {},
   };
   const callback = jest.fn((err, result) => (err ? new Error(err) : result));
 
   it('Has expected properties and response functions', () => {
+    // @ts-ignore
     function custom({
       event,
       body,
@@ -38,7 +39,7 @@ describe('API wrapper', () => {
       notAuthorized,
       invalid,
       redirect,
-      error
+      error,
     }: ApiSignature) {
       expect(event).toEqual(requestEvent);
       expect(body).toEqual({ hello: 'world' });
@@ -57,4 +58,42 @@ describe('API wrapper', () => {
     }
     api(custom)(requestEvent, context, callback);
   });
+
+  it('Has expected properties and response functions with optional generic type', () => {
+    interface CustomType {
+      Message: string;
+      Id: number;
+    }
+    function custom<CustomType>({
+      event,
+      body,
+      path,
+      query,
+      headers,
+      testRequest,
+      auth,
+      success,
+      notFound,
+      notAuthorized,
+      invalid,
+      redirect,
+      error,
+    }: ApiSignature<CustomType>) {
+      expect(event).toEqual(requestEvent);
+      expect(body).toEqual({ hello: 'world' });
+      expect(path).toEqual({ proxy: 'not today' });
+      expect(query).toEqual({ name: 'a test' });
+      expect(headers['content-type']).toEqual('application/json');
+      expect(testRequest).toEqual(true);
+      expect(auth).toBeFalsy();
+      expect(success).toBeInstanceOf(Function);
+      expect(notFound).toBeInstanceOf(Function);
+      expect(notAuthorized).toBeInstanceOf(Function);
+      expect(invalid).toBeInstanceOf(Function);
+      expect(redirect).toBeInstanceOf(Function);
+      expect(error).toBeInstanceOf(Function);
+      success('success');
+    }
+    api(custom)(requestEvent, context, callback);
+  });
 });

src/api/wrapper.ts

@@ -2,12 +2,12 @@ import { APIGatewayEvent, Context, Callback } from 'aws-lambda';
 import { Request } from './parser';
 import { success, invalid, notFound, notAuthorized, error, redirect, ApiResponse } from './responses';
 
-export function api(
-  custom: (props: ApiSignature) => any
+export function api<T>(
+  custom: (props: ApiSignature<T>) => any
 ): (event: APIGatewayEvent, context: Context, callback: Callback) => any {
   return function handler(event: APIGatewayEvent) {
     const { body, path, query, auth, headers, testRequest } = new Request(event).getProperties();
-    const signature: ApiSignature = {
+    const signature: ApiSignature<T> = {
       event,
       body,
       path,
@@ -20,20 +20,20 @@ export function api(
       notFound,
       notAuthorized,
       error,
-      redirect
+      redirect,
     };
     return custom(signature);
   };
 }
 
-export interface ApiSignature {
+export interface ApiSignature<T> {
   event: APIGatewayEvent; // original event
-  body: any; // JSON parsed body payload if exists (otherwise null)
-  path: { [name: string]: string }; // path param payload as key-value pairs if exists (otherwise null)
-  query: { [name: string]: string }; // query param payload as key-value pairs if exists (otherwise null)
-  headers: { [name: string]: string }; // header payload as key-value pairs if exists (otherwise null)
+  body: T; // JSON parsed body payload if exists (otherwise undefined)
+  path: { [name: string]: string }; // path param payload as key-value pairs if exists (otherwise undefined)
+  query: { [name: string]: string }; // query param payload as key-value pairs if exists (otherwise undefined)
+  headers: { [name: string]: string }; // header payload as key-value pairs if exists (otherwise undefined)
   testRequest: boolean; // indicates if this is a test request - looks for a header matching process.env.TEST_REQUEST_HEADER (dynamic from application) or 'Test-Request' (default)
-  auth: any; // auth context from custom authorizer if exists (otherwise null)
+  auth: any; // auth context from custom authorizer if exists (otherwise undefined)
   success(payload?: any, replacer?: (this: any, key: string, value: any) => any): ApiResponse; // returns 200 status code with optional payload as body
   invalid(errors?: string[]): ApiResponse; // returns 400 status code with optional errors as body
   notFound(message?: string): ApiResponse; // returns 404 status code with optional message as body

src/dynamodb-stream/wrapper.test.ts

@@ -5,7 +5,8 @@ describe('DynamoDB Stream wrapper', () => {
   const requestEvent = dynamoDBStreamEvent();
   const callback = jest.fn((err, result) => (err ? new Error(err) : result));
 
-  it('Has expected properties and response function without optional types', () => {
+  it('Has expected properties and response function', () => {
+    // @ts-ignore
     function custom({ event, newVersions, oldVersions, versions, success, error }: DynamoDBStreamSignature) {
       expect(event).toEqual(requestEvent);
       expect(newVersions).toEqual([{ Message: 'This item has changed', Id: 101 }]);
@@ -27,7 +28,7 @@ describe('DynamoDB Stream wrapper', () => {
     dynamodbStream(custom)(requestEvent, context, callback);
   });
 
-  it('Has expected properties and response function with optional types', () => {
+  it('Has expected properties and response function with optional type generics', () => {
     interface CustomType {
       Message: string;
       Id: number;

src/generic/wrapper.test.ts

@@ -14,11 +14,12 @@ describe('Stream wrapper', () => {
     getRemainingTimeInMillis: () => 2,
     done: () => {},
     fail: () => {},
-    succeed: () => {}
+    succeed: () => {},
   };
   const callback = jest.fn((err, result) => (err ? new Error(err) : result));
 
   it('Has expected properties and response funtions', () => {
+    // @ts-ignore
     function custom({ event, success, error }: WrapperSignature) {
       expect(event).toEqual(requestEvent);
       expect(success).toBeInstanceOf(Function);
@@ -28,4 +29,19 @@ describe('Stream wrapper', () => {
 
     wrapper(custom)(requestEvent, context, callback);
   });
+
+  it('Has expected properties and response funtions with generic types', () => {
+    interface CustomType {
+      Message: string;
+      Id: Number;
+    }
+    function custom<CustomType>({ event, success, error }: WrapperSignature<CustomType>) {
+      expect(event).toEqual(requestEvent);
+      expect(success).toBeInstanceOf(Function);
+      expect(error).toBeInstanceOf(Function);
+      success('success');
+    }
+
+    wrapper(custom)(requestEvent, context, callback);
+  });
 });

src/generic/wrapper.ts

@@ -4,17 +4,17 @@ import { success, error } from './responses';
 
 const metrics = new Metrics('Generic');
 
-export function wrapper(
-  custom: (props: WrapperSignature) => any
+export function wrapper<T>(
+  custom: (props: WrapperSignature<T>) => any
 ): (event: any, context: Context, callback: Callback) => any {
   return function handler(event: any, context: Context, callback: Callback) {
     metrics.common(event);
     return custom({ event, success, error });
   };
 }
 
-export interface WrapperSignature {
-  event: any; // original event
+export interface WrapperSignature<T> {
+  event: T; // original event
   success(message?: any): any; // logs and returns the message
   error(error?: any): void; // logs the error and throws
 }

src/sns/parser.ts

@@ -1,13 +1,13 @@
 import { SNSEvent } from 'aws-lambda';
 
-export class SnsParser {
+export class SnsParser<T> {
   constructor(private event: SNSEvent) {}
 
-  getMessage() {
+  getMessage(): T {
     let message = this.event.Records[0].Sns.Message;
     try {
       message = JSON.parse(message);
     } catch (err) {}
-    return message;
+    return (<unknown>message) as T;
   }
 }

src/sns/wrapper.test.ts

@@ -16,11 +16,12 @@ describe('Stream wrapper', () => {
     getRemainingTimeInMillis: () => 2,
     done: () => {},
     fail: () => {},
-    succeed: () => {}
+    succeed: () => {},
   };
   const callback = jest.fn((err, result) => (err ? new Error(err) : result));
 
   it('Has expected properties and response funtions', () => {
+    // @ts-ignore
     function custom({ event, message, success, error }: SnsSignature) {
       expect(event).toEqual(requestEvent);
       expect(message).toEqual('hello world');
@@ -30,4 +31,19 @@ describe('Stream wrapper', () => {
     }
     sns(custom)(requestEvent, context, callback);
   });
+
+  it('Has expected properties and response funtions with optional type generics', () => {
+    interface CustomType {
+      Message: string;
+      Id: number;
+    }
+    function custom({ event, message, success, error }: SnsSignature<CustomType>) {
+      expect(event).toEqual(requestEvent);
+      expect(message).toEqual('hello world');
+      expect(success).toBeInstanceOf(Function);
+      expect(error).toBeInstanceOf(Function);
+      success('success');
+    }
+    sns<CustomType>(custom)(requestEvent, context, callback);
+  });
 });

src/sns/wrapper.ts

@@ -5,19 +5,19 @@ import { SnsParser } from './parser';
 
 const metrics = new Metrics('Sns');
 
-export function sns(
-  custom: (props: SnsSignature) => any
+export function sns<T>(
+  custom: (props: SnsSignature<T>) => any
 ): (event: SNSEvent, context: Context, callback: Callback) => any {
   return function handler(event: SNSEvent, context: Context, callback: Callback) {
-    const message = new SnsParser(event).getMessage();
+    const message = new SnsParser<T>(event).getMessage();
     metrics.common(message);
     return custom({ event, message, success, error });
   };
 }
 
-export interface SnsSignature {
+export interface SnsSignature<T> {
   event: SNSEvent; // original event
-  message: any; // JSON-parsed message from event
+  message: T; // JSON-parsed message from event
   success(message?: any): any; // logs and returns the message
   error(error?: any): void; // logs the error and throws
 }