aws-core-utils - npm Package Compare versions

Comparing version 5.0.12 to 5.0.13

api-lambdas.js

@@ -5,3 +5,8 @@ 'use strict';
 const appErrors = require('core-functions/app-errors');
+const BadRequest = appErrors.BadRequest;
+const strings = require('core-functions/strings');
+const isNotBlank = strings.isNotBlank;
 
+const logging = require('logging-utils');
+
 /**
@@ -23,3 +28,5 @@ * Utilities for working with Lambdas exposed to AWS API Gateway, including functions to:
   failCallback: failCallback,
-  failCallbackForApiGateway: failCallback // Synonym for failCallback
+  failCallbackForApiGateway: failCallback, // Synonym for failCallback
+
+  generateHandlerFunction: generateHandlerFunction
 };
@@ -51,1 +58,96 @@
 }
+
+/**
+ * Generates a handler function for your API Gateway exposed Lambda.
+ *
+ * @param {StandardSettings} settings - optional settings to use to configure a standard context
+ * @param {StandardOptions} options - optional options to use to configure a standard context
+ * @param {function(event: AwsEvent, context: StandardContext)} fn - your function that must accept the AWS event
+ * and a standard context and ideally return a Promise
+ * @param {string|undefined} [logRequestResponseAtLogLevel] - an optional log level at which to log the request (i.e.
+ * AWS event) and response; if log level is undefined or invalid, then logs neither
+ * @param {number[]|undefined} [allowedHttpStatusCodes] - an optional array of HTTP status codes that are allowed to be
+ * returned directly to API Gateway (without conversion to either 400 or 500). NB: 400 and 500 CANNOT be excluded and
+ * are assumed to be present if omitted! If not defined, the app-errors module's list of supported HTTP status codes
+ * will be used as the allowed HTTP status codes
+ * @param {string|undefined} [invalidRequestMsg] - an optional message to log at warn level if your given function (fn) throws a BadRequest
+ * @param {string|undefined} [failureMsg] - an optional message to log at error level on failure
+ * @param {string|undefined} [successMsg] an optional message to log at info level on success
+ * @returns {AwsLambdaHandlerFunction} a handler function for your API Gateway exposed Lambda
+ */
+function generateHandlerFunction(settings, options, fn, logRequestResponseAtLogLevel, allowedHttpStatusCodes, invalidRequestMsg, failureMsg, successMsg) {
+  /**
+   * An API-Gateway exposed Lambda handler function.
+   * @param {Object} event - the AWS event passed to your handler
+   * @param {Object} awsContext - the AWS context passed to your handler
+   * @param {Callback} callback - the AWS Lambda callback function passed to your handler
+   */
+  function handler(event, awsContext, callback) {
+    const context = {};
+    try {
+      // Configure the context as a standard context
+      contexts.configureStandardContext(context, settings, options, event, awsContext, false);
+
+      // Optionally log the request
+      log('Request: ', event, logRequestResponseAtLogLevel, context);
+
+      // Execute the given function
+      Promise.try(() => fn(event, context))
+        .then(response => {
+          // Optionally log the response
+          log('Response: ', response, logRequestResponseAtLogLevel, context);
+
+          // Log the given success message (if any)
+          if (isNotBlank(successMsg)) context.info(successMsg);
+
+          // Succeed the Lambda callback
+          callback(null, response);
+        })
+        .catch(err => {
+          // Fail the Lambda callback
+          if (err instanceof BadRequest || appErrors.getHttpStatus(err) === 400) {
+            // Log the invalid request
+            context.warn((isNotBlank(invalidRequestMsg) ? invalidRequestMsg : 'Invalid request') + ` - ${err.message}`);
+            failCallback(callback, err, awsContext, undefined, undefined, allowedHttpStatusCodes);
+          } else {
+            // Log the error encountered
+            context.error(isNotBlank(failureMsg) ? failureMsg : 'Failed to execute Lambda', err.stack);
+            failCallback(callback, err, awsContext, undefined, undefined, allowedHttpStatusCodes);
+          }
+        });
+
+    } catch (err) {
+      (context.error ? context.error : console.error)(isNotBlank(failureMsg) ? failureMsg : 'Failed to execute Lambda', err.stack);
+      // Fail the Lambda callback
+      failCallback(callback, err, awsContext, failureMsg, failureCode, allowedHttpStatusCodes);
+    }
+  }
+
+  return handler;
+}
+
+function log(prefix, object, logLevel, context) {
+  if (isNotBlank(logLevel)) {
+    const msg = `${isNotBlank(prefix) ? prefix : ''}${JSON.stringify(object)}`;
+    switch (logLevel.toLowerCase()) {
+      case logging.INFO:
+        context.info(msg);
+        break;
+      case logging.DEBUG:
+        context.debug(msg);
+        break;
+      case logging.TRACE:
+        context.trace(msg);
+        break;
+      case logging.WARN:
+        context.warn(msg);
+        break;
+      case logging.ERROR:
+        context.error(msg);
+        break;
+      default:
+        context.warn(`Unexpected log level (${logLevel})`);
+        break;
+    }
+  }
+}

package.json

 {
   "name": "aws-core-utils",
-  "version": "5.0.12",
+  "version": "5.0.13",
   "description": "Core utilities for working with Amazon Web Services (AWS), including ARNs, regions, stages, Lambdas, AWS errors, stream events, Kinesis, DynamoDB.DocumentClients, etc.",
@@ -14,4 +14,4 @@ "author": "Byron du Preez",
   "dependencies": {
-    "core-functions": "^2.0.11",
-    "logging-utils": "^3.0.9",
+    "core-functions": "^2.0.12",
+    "logging-utils": "^3.0.10",
     "deep-equal": "^1.0.1"
@@ -18,0 +18,0 @@ },

README.md

@@ -1,2 +0,2 @@
-# aws-core-utils v5.0.12
+# aws-core-utils v5.0.13
 
@@ -364,2 +364,8 @@ Core utilities for working with Amazon Web Services (AWS), including ARNs, regions, stages, Lambdas, AWS errors, stream events, Kinesis, DynamoDB.DocumentClients, etc.
 
+### 5.0.13
+- Added new `generateHandlerFunction` function to `api-lambdas.js` module
+- More improvements to typedefs in `type-defs.js` module
+- Updated `core-functions` dependency to version 2.0.12
+- Updated `logging-utils` dependency to version 3.0.10
+
 ### 5.0.12
@@ -366,0 +372,0 @@ - Updated `logging-utils` dependency to version 3.0.9

test/package.json

 {
   "name": "aws-core-utils-tests",
   "description": "Unit tests for aws-core-utils modules",
-  "version": "5.0.12",
+  "version": "5.0.13",
   "author": "Byron du Preez",
@@ -6,0 +6,0 @@ "license": "Apache-2.0",

type-defs.js

 'use strict';
 
 /**
+ * @typedef {function(err: *, data: *)} Callback - a standard Node-style callback function
+ */
+
+/**
+ * @typedef {Object} AwsEvent - an AWS event passed to your Lambda handler function
+ */
+
+/**
+ * @typedef {Object} AwsContext - an AWS context passed to your Lambda handler function
+ * @property {uuid} awsRequestId - a unique identifier assigned to the current invocation of your handler function by AWS Lambda
+ * @property {function(): number} getRemainingTimeInMillis - gets the remaining time to execute in milliseconds
+ */
+
+/**
+ * @typedef {function(event: AwsEvent, awsContext: AwsContext, callback: Callback)} AwsLambdaHandlerFunction - a handler
+ * function for your AWS Lambda
+ */
+
+/**
  * @typedef {StageHandling} StandardContext - an object configured as a standard context with stage handling, logging,
@@ -12,3 +31,3 @@ * custom settings, an optional Kinesis instance and an optional DynamoDB DocumentClient instance and OPTIONALLY also
  * @property {string|undefined} [stage] - the configured stage to use
- * @property {Object|undefined} [awsContext] - the AWS context passed to your Lambda function on invocation
+ * @property {AwsContext|undefined} [awsContext] - the AWS context passed to your Lambda function on invocation
  */
@@ -63,3 +82,3 @@
  * @property {string} region - the name of the AWS region to use
- * @property {Object} awsContext - the AWS context passed to your Lambda function on invocation
+ * @property {AwsContext} awsContext - the AWS context passed to your Lambda function on invocation
  */
@@ -90,28 +109,2 @@
 /**
- * Stage handling settings are used for configuring and customising stage handling behaviour. The stage handling
- * settings determine how {@linkcode stages.js#resolveStage}, {@linkcode stages.js#toStageQualifiedStreamName},
- * {@linkcode stages.js#extractStageFromQualifiedStreamName}, {@linkcode stages.js#toStageQualifiedResourceName},
- * {@linkcode stages.js#extractStageFromQualifiedStreamName} and other internal functions will behave when invoked.
- *
- * They can also be used to pass any additional custom configuration options and settings that you need through to any
- * custom stage handling functions that you develop and configure via {@linkcode stages.js#configureStageHandling}.
- *
- * @typedef {StageHandlingOptions} StageHandlingSettings
- * @property {Function|undefined} [customToStage] - an optional custom function that accepts: an AWS event; an AWS context;
- * and a context, and somehow extracts a usable stage from the AWS event and/or AWS context.
- * @property {Function|undefined} [convertAliasToStage] - an optional function that accepts: an extracted alias (if any);
- * an AWS event; an AWS context; and a context, and converts the alias into a stage
- * @property {Function|undefined} [injectStageIntoStreamName] - an optional function that accepts: an unqualified stream
- * name; a stage; and a context, and returns a stage-qualified stream name (effectively the reverse function of the
- * extractStageFromStreamName function)
- * @property {Function|undefined} [extractStageFromStreamName] - an optional function that accepts: a stage-qualified
- * stream name; and a context, and extracts a stage from the stream name
- * @property {Function|undefined} [injectStageIntoResourceName] - an optional function that accepts: an unqualified
- * resource name; a stage; and a context, and returns a stage-qualified resource name (effectively the reverse function
- * of the extractStageFromResourceName function)
- * @property {Function|undefined} [extractStageFromResourceName] - an optional function that accepts: a stage-qualified
- * resource name; and a context, and extracts a stage from the resource name
- */
-
-/**
  * Stage handling options are a subset of the full (@linkcode StageHandlingSettings}, which are used to configure ONLY
@@ -146,1 +139,54 @@ * the property (i.e. non-function) stage handling settings and which can be used to pass any additional custom
  */
+
+/**
+ * Stage handling settings are used for configuring and customising stage handling behaviour. The stage handling
+ * settings determine how {@linkcode stages.js#resolveStage}, {@linkcode stages.js#toStageQualifiedStreamName},
+ * {@linkcode stages.js#extractStageFromQualifiedStreamName}, {@linkcode stages.js#toStageQualifiedResourceName},
+ * {@linkcode stages.js#extractStageFromQualifiedStreamName} and other internal functions will behave when invoked.
+ *
+ * They can also be used to pass any additional custom configuration options and settings that you need through to any
+ * custom stage handling functions that you develop and configure via {@linkcode stages.js#configureStageHandling}.
+ *
+ * @typedef {StageHandlingOptions} StageHandlingSettings
+ * @property {CustomToStage|undefined} [customToStage] - an optional custom to stage function
+ * @property {ConvertAliasToStage|undefined} [convertAliasToStage] - an optional function that converts an alias into a stage
+ * @property {InjectStageIntoStreamName|undefined} [injectStageIntoStreamName] - an optional function that returns a stage-qualified stream name
+ * @property {ExtractStageFromStreamName|undefined} [extractStageFromStreamName] - an optional function that extracts a stage from a stage-qualified stream name
+ * @property {InjectStageIntoResourceName|undefined} [injectStageIntoResourceName] - an optional function that returns a stage-qualified resource name
+ * @property {ExtractStageFromResourceName|undefined} [extractStageFromResourceName] - an optional function that extracts a stage from a stage-qualified resource name
+ */
+
+/**
+ * @typedef {function(event: AwsEvent, awsContext: AwsContext, context: StageHandling): (string|undefined)} CustomToStage -
+ * a custom function that accepts: an AWS event; an AWS context; and a context, and somehow extracts a usable stage from
+ * the AWS event and/or AWS context.
+ */
+
+/**
+ * @typedef {function(alias: string, event: AwsEvent, awsContext: AwsContext, context: StageHandling): (string|undefined)} ConvertAliasToStage -
+ * a function that accepts: an extracted AWS Lambda alias (if any); an AWS event; an AWS context; and a context, and
+ * converts the alias into a stage
+ */
+
+/**
+ * @typedef {function(unqualifiedStreamName: string, stage: string, context: StageHandling):(string|undefined)} InjectStageIntoStreamName -
+ * a function that accepts: an unqualified stream name; a stage; and a context, and returns a stage-qualified stream
+ * name (effectively the reverse function of the ExtractStageFromStreamNameFunction)
+ */
+
+/**
+ * @typedef {function(qualifiedStreamName: string, context: StageHandling):(string|undefined)} ExtractStageFromStreamName -
+ * a function that accepts: a stage-qualified stream name; and a context, and extracts a stage from the stream name
+ */
+
+/**
+ * @typedef {function(unqualifiedResourceName: string, stage: string, context: StageHandling):(string|undefined)} InjectStageIntoResourceName -
+ * a function that accepts: an unqualified resource name; a stage; and a context, and returns a stage-qualified resource
+ * name (effectively the reverse function of the ExtractStageFromResourceNameFunction)
+ */
+
+/**
+ * @typedef {function(qualifiedResourceName: string, context: StageHandling):(string|undefined)} ExtractStageFromResourceName -
+ * a function that accepts: a stage-qualified resource name; and a context, and extracts a stage from the resource name
+ */
+

No alert changes

Improved metrics

Total package byte prevSize

361952

increased by4.67%

Number of package files

30

increased by3.45%

Lines of code

5309

increased by6.05%

Number of lines in readme file

589

increased by1.03%

Worsened metrics

Number of low supply chain risk alerts

68

increased by4.62%

Dependency changes

• Updatedcore-functions@^2.0.12

• Updatedlogging-utils@^3.0.10