Merge pull request #70 from jeremydaly/v0.9.0

v0.9.0

Author: jeremydaly

Diff for: README.md

@@ -94,10 +94,13 @@ Whatever you decide is best for your use case, **Lambda API** is there to suppor
 - [Middleware](#middleware)
 - [Clean Up](#clean-up)
 - [Error Handling](#error-handling)
+  - [Error Types](#error-types)
+  - [Error Logging](#error-logging)
 - [Namespaces](#namespaces)
 - [CORS Support](#cors-support)
 - [Lambda Proxy Integration](#lambda-proxy-integration)
 - [Configuring Routes in API Gateway](#configuring-routes-in-api-gateway)
+- [TypeScript Support](#typescript-support)
 - [Contributions](#contributions)
 
 ## Installation
@@ -118,6 +121,7 @@ Require the `lambda-api` module into your Lambda handler script and instantiate
 | callbackName | `String` | Override the default callback query parameter name for JSONP calls |
 | logger | `boolean` or `object` | Enables default [logging](#logging) or allows for configuration through a [Logging Configuration](#logging-configuration) object. |
 | mimeTypes | `Object` | Name/value pairs of additional MIME types to be supported by the `type()`. The key should be the file extension (without the `.`) and the value should be the expected MIME type, e.g. `application/json` |
+| serializer  | `Function` | Optional object serializer function. This function receives the `body` of a response and must return a string. Defaults to `JSON.stringify` |
 | version  | `String` | Version number accessible via the `REQUEST` object |
 
 
@@ -129,6 +133,9 @@ const api = require('lambda-api')({ version: 'v1.0', base: 'v1' });
 ## Recent Updates
 For detailed release notes see [Releases](https://github.com/jeremydaly/lambda-api/releases).
 
+### v0.9: New error types, custom serializers, and TypeScript support
+Lambda API now generates typed errors for easier parsing in middleware. You can also supply your own custom serializer for formatting output rather than using the default `JSON.stringify`. And thanks to @hassankhan, a TypeScript declaration file is now available.
+
 ### v0.8: Logging Support with Sampling
 Lambda API has added a powerful (and customizable) logging engine that utilizes native JSON support for CloudWatch Logs. Log entries can be manually added using standard severities like `info` and `warn`. In addition, "access logs" can be automatically generated with detailed information about each requests. See [Logging](#logging) for more information about logging and auto sampling for request tracing.
 
@@ -390,6 +397,9 @@ The `REQUEST` object contains a parsed and normalized request from API Gateway.
 - `rawBody`: If the `isBase64Encoded` flag is `true`, this is a copy of the original, base64 encoded body
 - `route`: The matched route of the request
 - `requestContext`: The `requestContext` passed from the API Gateway
+- `pathParameters`: The `pathParameters` passed from the API Gateway
+- `stageVariables`: The `stageVariables` passed from the API Gateway
+- `isBase64Encoded`: The `isBase64Encoded` boolean passed from the API Gateway
 - `auth`: An object containing the `type` and `value` of an authorization header. Currently supports `Bearer`, `Basic`, `OAuth`, and `Digest` schemas. For the `Basic` schema, the object is extended with additional fields for username/password. For the `OAuth` schema, the object is extended with key/value pairs of the supplied OAuth 1.0 values.
 - `namespace` or `ns`: A reference to modules added to the app's namespace (see [namespaces](#namespaces))
 - `cookies`: An object containing cookies sent from the browser (see the [cookie](#cookiename-value-options) `RESPONSE` method)
@@ -950,7 +960,7 @@ const api = require('lambda-api')({
 })
 ```
 
-Additional rules can be added by specify a `rules` parameter in the `sampling` configuration object. The `rules` should contain an `array` of "rule" objects with the following properties:
+Additional rules can be added by specifying a `rules` parameter in the `sampling` configuration object. The `rules` should contain an `array` of "rule" objects with the following properties:
 
 | Property | Type | Description | Default | Required |
 | -------- | ---- | ----------- | ------- | -------- |
@@ -1123,7 +1133,23 @@ api.use(errorHandler1,errorHandler2)
 **NOTE:** Error handling middleware runs on *ALL* paths. If paths are passed in as the first parameter, they will be ignored by the error handling middleware.
 
 ### Error Types
-Error logs are generate using either the `error` or `fatal` logging level. Errors can be triggered from within routes and middleware by calling the `error()` method on the `RESPONSE` object. If provided a `string` as an error message, this will generate an `error` level log entry. If you supply a JavaScript `Error` object, or you `throw` an error, a `fatal` log entry will be generated.
+Lambda API provides several different types of errors that can be used by your application. `RouteError`, `MethodError`, `ResponseError`, and `FileError` will all be passed to your error middleware. `ConfigurationError`s will throw an exception when you attempt to `.run()` your route and can be caught in a `try/catch` block. Most error types contain additional properties that further detail the issue.
+
+```javascript
+const errorHandler = (err,req,res,next) => {
+
+  if (err.name === 'RouteError') {
+    // do something with route error
+  } else if (err.name === 'FileError') {
+    // do something with file error
+  }
+  // continue
+  next()
+})
+```
+
+### Error Logging
+Error logs are generated using either the `error` or `fatal` logging level. Errors can be triggered from within routes and middleware by calling the `error()` method on the `RESPONSE` object. If provided a `string` as an error message, this will generate an `error` level log entry. If you supply a JavaScript `Error` object, or you `throw` an error, a `fatal` log entry will be generated.
 
 ```javascript
 api.get('/somePath', (res,req) => {
@@ -1271,6 +1297,14 @@ Simply create a `{proxy+}` route that uses the `ANY` method and all requests wil
 ## Reusing Persistent Connections
 If you are using persistent connections in your function routes (such as AWS RDS or Elasticache), be sure to set `context.callbackWaitsForEmptyEventLoop = false;` in your main handler. This will allow the freezing of connections and will prevent Lambda from hanging on open connections. See [here](https://www.jeremydaly.com/reuse-database-connections-aws-lambda/) for more information.
 
+## TypeScript Support
+An `index.d.ts` declaration file has been included for use with your TypeScript projects (thanks @hassankhan). Please feel free to make suggestions and contributions to keep this up-to-date with future releases.
+
+```javascript
+// import Lambda API and TypeScript declarations
+import API from 'lambda-api'
+```
+
 ## Contributions
 Contributions, ideas and bug reports are welcome and greatly appreciated. Please add  [issues](https://github.com/jeremydaly/lambda-api/issues) for suggestions and bug reports or create a pull request.
 

Diff for: index.d.ts

@@ -5,41 +5,42 @@ import {
 } from 'aws-lambda';
 
 declare interface CookieOptions {
-  domain: string;
-  expires: Date;
-  httpOnly: boolean;
-  maxAge: number;
-  path: string;
-  secure: boolean;
-  sameSite: boolean | 'Strict' | 'Lax';
+  domain?: string;
+  expires?: Date;
+  httpOnly?: boolean;
+  maxAge?: number;
+  path?: string;
+  secure?: boolean;
+  sameSite?: boolean | 'Strict' | 'Lax';
 }
 
 declare interface CorsOptions {
-  credentials: boolean;
-  exposeHeaders: string;
-  headers: string;
-  maxAge: number;
-  methods: string;
-  origin: string;
+  credentials?: boolean;
+  exposeHeaders?: string;
+  headers?: string;
+  maxAge?: number;
+  methods?: string;
+  origin?: string;
 }
 
 declare interface FileOptions {
-  maxAge: number;
-  root: string;
-  lastModified: boolean | string;
-  headers: {};
-  cacheControl: boolean | string;
-  private: boolean;
+  maxAge?: number;
+  root?: string;
+  lastModified?: boolean | string;
+  headers?: {};
+  cacheControl?: boolean | string;
+  private?: boolean;
 }
 
 declare interface App {
   [namespace: string]: HandlerFunction;
 }
 declare type ErrorCallback = (error?: Error) => void;
-declare type HandlerFunction = (req: Request, res) => void | {} | Promise<{}>;
+declare type HandlerFunction = (req: Request, res: Response) => void | {} | Promise<{}>;
 declare type LoggerFunction = (message: string) => void;
 declare type NextFunction = () => void;
 declare type TimestampFunction = () => string;
+declare type SerializerFunction = (body: object) => string;
 declare type FinallyFunction = (req: Request, res: Response) => void;
 
 declare type METHODS = 'GET'
@@ -52,44 +53,45 @@ declare type METHODS = 'GET'
   | 'ANY';
 
 declare interface SamplingOptions {
-  route: string;
-  target: number;
-  rate: number
-  period: number;
-  method: string | string[];
+  route?: string;
+  target?: number;
+  rate?: number
+  period?: number;
+  method?: string | string[];
 }
 
 declare interface LoggerOptions {
-  access: boolean | string;
-  customKey: string;
-  detail: boolean;
-  level: string;
-  levels: {
+  access?: boolean | string;
+  customKey?: string;
+  detail?: boolean;
+  level?: string;
+  levels?: {
     [key: string]: string;
   };
-  messageKey: string;
-  nested: boolean;
-  timestamp: boolean | TimestampFunction;
-  sampling: {
-    target: number;
-    rate: number;
-    period: number;
-    rules: SamplingOptions[];
+  messageKey?: string;
+  nested?: boolean;
+  timestamp?: boolean | TimestampFunction;
+  sampling?: {
+    target?: number;
+    rate?: number;
+    period?: number;
+    rules?: SamplingOptions[];
   };
-  serializers: {
+  serializers?: {
     [name: string]: (req: Request) => {};
   };
-  stack: boolean;
+  stack?: boolean;
 }
 
 declare interface Options {
-  base: string;
-  callbackName: string;
-  logger: boolean | LoggerOptions;
-  mimeTypes: {
+  base?: string;
+  callbackName?: string;
+  logger?: boolean | LoggerOptions;
+  mimeTypes?: {
     [key: string]: string;
   };
-  version: string;
+  serializer?: SerializerFunction;
+  version?: string;
 }
 
 declare class Request {
@@ -110,6 +112,9 @@ declare class Request {
   rawBody: string;
   route: '';
   requestContext: APIGatewayEventRequestContext;
+  isBase64Encoded: boolean;
+  pathParameters: { [name: string]: string } | null;
+  stageVariables: { [name: string]: string } | null;
   auth: {
     [key: string]: any;
     type: 'Bearer' | 'Basic' | 'OAuth' | 'Digest';

Diff for: index.js

@@ -3,15 +3,16 @@
 /**
  * Lightweight web framework for your serverless applications
  * @author Jeremy Daly <[email protected]>
- * @version 0.8.1
+ * @version 0.9.0
  * @license MIT
  */
 
-const REQUEST = require('./lib/request.js') // Resquest object
-const RESPONSE = require('./lib/response.js') // Response object
-const UTILS = require('./lib/utils.js') // Require utils library
-const LOGGER = require('./lib/logger.js') // Require logger library
+const REQUEST = require('./lib/request') // Resquest object
+const RESPONSE = require('./lib/response') // Response object
+const UTILS = require('./lib/utils') // Require utils library
+const LOGGER = require('./lib/logger') // Require logger library
 const prettyPrint = require('./lib/prettyPrint') // Pretty print for debugging
+const { ConfigurationError } = require('./lib/errors') // Require custom errors
 
 // Create the API class
 class API {
@@ -24,6 +25,7 @@ class API {
     this._base = props && props.base && typeof props.base === 'string' ? props.base.trim() : ''
     this._callbackName = props && props.callback ? props.callback.trim() : 'callback'
     this._mimeTypes = props && props.mimeTypes && typeof props.mimeTypes === 'object' ? props.mimeTypes : {}
+    this._serializer = props && props.serializer && typeof props.serializer === 'function' ? props.serializer : JSON.stringify
 
     // Set sampling info
     this._sampleCounts = {}
@@ -90,7 +92,7 @@ class API {
   METHOD(method, path, handler) {
 
     if (typeof handler !== 'function') {
-      throw new Error(`No route handler specified for ${method} method on ${path} route.`)
+      throw new ConfigurationError(`No route handler specified for ${method} method on ${path} route.`)
     }
 
     // Ensure method is an array
@@ -147,7 +149,7 @@ class API {
   async run(event,context,cb) {
 
     // Set the event, context and callback
-    this._event = event
+    this._event = event || {}
     this._context = this.context = typeof context === 'object' ? context : {}
     this._cb = cb ? cb : undefined
 
@@ -212,6 +214,8 @@ class API {
   // Catch all async/sync errors
   async catchErrors(e,response,code,detail) {
 
+    // console.log('\n\n------------------------\n',e,'\n------------------------\n\n');
+
     // Error messages should never be base64 encoded
     response._isBase64 = false
 
@@ -306,7 +310,7 @@ class API {
         } else if (arguments[arg].length === 4) {
           this._errors.push(arguments[arg])
         } else {
-          throw new Error('Middleware must have 3 or 4 parameters')
+          throw new ConfigurationError('Middleware must have 3 or 4 parameters')
         }
       }
     }

Diff for: lib/errors.js

@@ -0,0 +1,58 @@
+'use strict'
+
+/**
+ * Lightweight web framework for your serverless applications
+ * @author Jeremy Daly <[email protected]>
+ * @license MIT
+ */
+
+// Custom error types
+
+class RouteError extends Error {
+  constructor(message,path) {
+    super(message)
+    this.name = this.constructor.name
+    this.path = path
+  }
+}
+
+class MethodError extends Error {
+  constructor(message,method,path) {
+    super(message)
+    this.name = this.constructor.name
+    this.method = method
+    this.path = path
+  }
+}
+
+class ConfigurationError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+
+class ResponseError extends Error {
+  constructor(message,code) {
+    super(message)
+    this.name = this.constructor.name
+    this.code = code
+  }
+}
+
+class FileError extends Error {
+  constructor(message,err) {
+    super(message)
+    this.name = this.constructor.name
+    for (let e in err) this[e] = err[e]
+  }
+}
+
+// Export the response object
+module.exports = {
+  RouteError,
+  MethodError,
+  ConfigurationError,
+  ResponseError,
+  FileError
+}

Diff for: lib/logger.js

@@ -11,6 +11,7 @@
 // https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#context-variable-reference
 
 const UTILS = require('./utils') // Require utils library
+const { ConfigurationError } = require('./errors') // Require custom errors
 
 // Config logger
 exports.config = (config,levels) => {
@@ -21,7 +22,7 @@ exports.config = (config,levels) => {
   if (cfg.levels && typeof cfg.levels === 'object') {
     for (let lvl in cfg.levels) {
       if (!/^[A-Za-z_]\w*$/.test(lvl) || isNaN(cfg.levels[lvl])) {
-        throw new Error('Invalid level configuration')
+        throw new ConfigurationError('Invalid level configuration')
       }
     }
     levels = Object.assign(levels,cfg.levels)
@@ -225,7 +226,7 @@ const parseSamplerConfig = (config,levels) => {
   let cfg = typeof config === 'object' ? config : config === true ? {} : false
 
   // Error on invalid config
-  if (cfg === false) throw new Error('Invalid sampler configuration')
+  if (cfg === false) throw new ConfigurationError('Invalid sampler configuration')
 
   // Create rule default
   let defaults = (inputs) => {
@@ -244,7 +245,7 @@ const parseSamplerConfig = (config,levels) => {
   let rules = Array.isArray(cfg.rules) ? cfg.rules.map((rule,i) => {
     // Error if missing route or not a string
     if (!rule.route || typeof rule.route !== 'string')
-      throw new Error('Invalid route specified in rule')
+      throw new ConfigurationError('Invalid route specified in rule')
 
     // Parse methods into array (if not already)
     let methods = (Array.isArray(rule.method) ? rule.method :