aws-core-utils - npm Package Compare versions

Comparing version 5.0.10 to 5.0.11

lambdas.js

@@ -21,5 +21,5 @@ 'use strict';
   getInvokedFunctionArnFunctionName: getInvokedFunctionArnFunctionName,
-  // Functions to assist with failing an AWS Lambda callback (and preserve the information of the error thrown)
-  failCallback: failCallback,
-  failCallbackForApiGateway: failCallbackForApiGateway
+
+  // Function to assist with failing the callback of an AWS Lambda (not exposed via API Gateway) and preserve the information of the error thrown
+  failCallback: failCallback
 };
@@ -123,9 +123,9 @@
 /**
- * Fails the given AWS Lambda callback with the given error, by first attempting to convert the given error into one of
- * the standard app errors (see {@linkcode core-functions/app-errors}) and then invoking the given lambdaCallback with a
- * JSON stringified version of the converted error. The given AWS context is used to add your Lambda's AWS request ID to
- * the error.
+ * Fails the given callback of an AWS Lambda, which is NOT exposed via API Gateway, with the given error, by first
+ * attempting to convert the given error into one of the standard app errors (see {@linkcode core-functions/app-errors})
+ * and then invoking the given lambdaCallback with a JSON stringified version of the converted error. The given AWS
+ * context is used to add your Lambda's AWS request ID to the error.
  *
- * Note that this function must NOT be used for any Lambda invoked by API Gateway (for these you MUST instead use
- * the failCallbackForApiGateway function below).
+ * Note that this function must NOT be used for any Lambda invoked by API Gateway - for these you MUST instead use the
+ * {@linkcode aws-core-utils/api-lambdas#failCallback} function.
  *
@@ -137,2 +137,3 @@ * @see core-functions/app-errors.js
  * @param {Object|undefined} [awsContext] - the AWS context passed as the second argument to your Lambda function on invocation
+ * @param {string|undefined} [awsContext.awsRequestId] - the AWS context's request ID
  * @param {string|undefined} [message] - an optional message; will use error's message if not specified and needed
@@ -147,25 +148,1 @@ * @param {string|undefined} [code] - an optional code; will use error's code if not specified and needed
 
-/**
- * Fails the given AWS Lambda callback with the given error, by first attempting to convert the given error into one of
- * the standard app errors (see {@linkcode core-functions/app-errors}) that will be mappable on API Gateway, and then
- * invoking the given lambdaCallback with a JSON stringified version of the converted app error. The given AWS context
- * is used to add your Lambda's AWS request ID to the error.
- *
- * @see core-functions/app-errors.js
- *
- * @param {Function} lambdaCallback - the callback function passed as the last argument to your Lambda function on invocation.
- * @param {Error} error - the error with which you need to fail your Lambda
- * @param {Object|undefined} [awsContext] - the AWS context passed as the second argument to your Lambda function on invocation
- * @param {string|undefined} [message] - an optional message (will use error's message if not specified)
- * @param {string|undefined} [code] - an optional code (will use error's code if not specified)
- * @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
- */
-function failCallbackForApiGateway(lambdaCallback, error, awsContext, message, code, allowedHttpStatusCodes) {
-  const appError = appErrors.toAppErrorForApiGateway(error, message, code, allowedHttpStatusCodes);
-  if (awsContext && !appError.awsRequestId) appError.awsRequestId = awsContext.awsRequestId;
-  lambdaCallback(JSON.stringify(appError));
-}
-

package.json

 {
   "name": "aws-core-utils",
-  "version": "5.0.10",
+  "version": "5.0.11",
   "description": "Core utilities for working with Amazon Web Services (AWS), including ARNs, regions, stages, Lambdas, AWS errors, stream events, Kinesis, DynamoDB.DocumentClients, etc.",
@@ -5,0 +5,0 @@ "author": "Byron du Preez",

README.md

@@ -1,2 +0,2 @@
-# aws-core-utils v5.0.10
+# aws-core-utils v5.0.11
 
@@ -6,6 +6,12 @@ Core utilities for working with Amazon Web Services (AWS), including ARNs, regions, stages, Lambdas, AWS errors, stream events, Kinesis, DynamoDB.DocumentClients, etc.
 Currently includes:
+- api-lambdas.js
+  - Utilities for working with Lambdas exposed to AWS API Gateway, including functions to:
+    - Configure a standard context for AWS Gateway exposed Lambdas (re-exported from contexts.js module)
+    - Fail Lambda callbacks with standard AppError errors to facilitate mapping of errors to HTTP status codes on API Gateway.
 - arns.js 
     - Utilities for working with Amazon Resource Names (ARNs)
 - aws-errors.js
-    - Utilities for working with AWS errors.
+    - Utilities for working with AWS errors
+- contexts.js
+    - Utilities for configuring contexts for AWS Gateway exposed and other types of Lambdas
 - dynamodb-doc-client-cache.js
@@ -19,8 +25,9 @@ - A module-scope cache of AWS.DynamoDB.DocumentClient instances by region for Lambda.
     - Utilities for working with AWS Lambda, which enable extraction of function names, versions and, most importantly, 
-    aliases from AWS contexts and their invoked function ARNs.
+      aliases from AWS contexts and their invoked function ARNs.
+    - Utility for failing non-API Gateway Lambda's callbacks with standard AppError errors if mapping of errors to HTTP status codes is needed
 - regions.js 
     - Utilities for resolving the AWS region from various sources (primarily for AWS Lambda usage).
 - stages.js
-    - Utilities for resolving or deriving the current stage (e.g. dev, qa, prod) from various sources (primarily for 
-    AWS Lambda usage).
+    - Utilities for resolving or deriving the current stage (e.g. dev, qa, prod) from various sources 
+      (primarily for AWS Lambda usage).
     - Utilities for configuration of stage handling.
@@ -43,2 +50,31 @@ - Configurable and default functions for generating stage-qualified stream and resource names.
 In Node.js:
+
+* To use the `api-lambdas` module within your API Gateway exposed Lambda:
+```js
+const apiLambdas = require('aws-core-utils/api-lambdas');
+
+// Example Lambda handler function
+module.exports.handler = (event, awsContext, callback) => {
+  // Configure a standard context
+  const context = {};
+  try {
+    const standardOptions = require('my-options.json'); // or whatever options you want to use to configure stage handling, logging, custom settings, ...
+    const standardSettings = {}; // or whatever settings you want to use to configure stage handling, logging, custom settings, ...
+    apiLambdas.configureStandardContext(context, standardSettings, standardOptions, event, awsContext);
+    
+    // ... execute Lambda specific code passing the context to your functions as needed
+    // executeMyLambdaFunction(arg1, arg2, ..., context);
+  
+  } catch (err) {
+    // Fail your Lambda callback and map the error to one of the default set of HTTP status codes:
+    // i.e. [400, 401, 403, 404, 408, 429, 500, 502, 503, 504]
+    apiLambdas.failCallback(callback, err, awsContext);
+  }
+}
+
+// ALTERNATIVELY: 
+// Fail your Lambda callback and map the error to one of a specified set of HTTP status codes
+apiLambdas.failCallback(callback, err, awsContext, 'My error msg', 'MyErrorCode', [400, 404, 418, 500, 508]);
+```
+
 * To use the AWS ARN utilities
@@ -61,11 +97,19 @@ ```js
 
-* To get the current AWS region & configure it on a context
+* To use the `contexts.js` module:
 ```js
-const regions = require('aws-core-utils/regions');
+// To use the configureStandardContext function, please refer to the 'To use the `api-lambdas` module' example above
+// (since the `api-lambdas.js` module simply re-exports the `contexts.js` module's configureStandardContext)
 
-// To get the current AWS region
-const region = regions.getRegion();
+// ALTERNATIVELY if you need the logic of the configureStandardContext function for custom purposes
+const contexts = require('aws-core-utils/contexts');
+const context = {};
+const standardOptions = require('my-std-options.json'); // or whatever options you want to use to configure stage handling, logging, custom settings, ...
+const standardSettings = {}; // or whatever settings you want to use to configure stage handling, logging, custom settings, ...
+contexts.configureStandardContext(context, standardSettings, standardOptions, awsEvent, awsContext);
 
-// To configure a context with the current AWS region
-regions.configureRegion(context, failFast)
+// If you need the logic of the configureCustomSettings function, which is used by configureStandardContext, for other purposes
+const myCustomSettings = {myCustomSetting1: 1, myCustomSetting2: 2, myCustomFunction: () => {}}; // 
+const myCustomOptions = require('my-custom-options.json');
+contexts.configureCustomSettings(context, myCustomSettings, myCustomOptions);
+console.log(`context.custom = ${JSON.stringify(context.custom)}`);
 ```
@@ -154,9 +198,2 @@
 
-// Fail a Lambda's callback with a standard error and preserve HTTP status codes (for non-API Gateway Lambdas) 
-// See core-functions/app-errors.js for standard errors to use
-lambdas.failCallback(lambdaCallback, error, awsContext, message, code);
-
-// Fail an API Gateway-exposed Lambda's callback with a standard error and preserve HTTP status codes
-lambdas.failCallbackForApiGateway(lambdaCallback, error, awsContext, message, code, allowedHttpStatusCodes);
-
 // To resolve the Lambda alias from an AWS Lambda context
@@ -171,4 +208,22 @@ const alias = lambdas.getAlias(awsContext);
 const invokedFunctionArnFunctionName = lambdas.getInvokedFunctionArnFunctionName(awsContext);
+
+// Fail a Lambda's callback with a standard error and preserve HTTP status codes (for non-API Gateway Lambdas) 
+// See core-functions/app-errors.js for standard errors to use
+lambdas.failCallback(lambdaCallback, error, awsContext, message, code);
 ```
 
+* To get the current AWS region & configure it on a context
+```js
+const regions = require('aws-core-utils/regions');
+
+// To get the current AWS region of your Lambda
+const region = regions.getRegion();
+
+// To configure a context with the current AWS region
+const context = {};
+const failFast = true;
+regions.configureRegion(context, failFast);
+assert(context.region && typeof context.region === 'string');
+```
+
 * To use the stage utilities
@@ -179,6 +234,12 @@ ```js
 const settings = undefined; // ... or your own custom settings
-const options = require('./stages-options.json'); // ... or your own custom options
+const options = require('aws-core-utils/stages-options.json'); // ... or your own custom options
 
-// ... EITHER using the default stage handling configuration partially customised via config.stageHandlingOptions
-stages.configureDefaultStageHandling(context, options.stageHandlingOptions, otherSettings, otherOptions, forceConfiguration); 
+// ... EITHER using the default stage handling configuration and default logging configuration 
+stages.configureDefaultStageHandling(context); 
+// ... OR using the default stage handling configuration and default logging configuration partially customised via stageHandlingOptions, otherSettings & otherOptions
+const stageHandlingOptions = require('aws-core-utils/stages-options.json').stageHandlingOptions; // example ONLY - use your own custom stage handling options if needed
+const otherSettings = undefined; // or to configure your own underlying logger use: const otherSettings = {loggingSettings: {underlyingLogger: myCustomLogger}};
+const otherOptions = require('aws-core-utils/test/std-options.json'); // example ONLY - use your own custom standard options file
+const forceConfiguration = false;
+stages.configureDefaultStageHandling(context, stageHandlingOptions, otherSettings, otherOptions, forceConfiguration); 
 
@@ -194,3 +255,3 @@ // ... OR using your own custom stage-handling configuration
 // stageHandlingSettings.extractStageFromResourceName = stages.DEFAULTS.extractStageFromSuffixedResourceName;
-stages.configureStageHandling(context, stageHandlingSettings, undefined, otherSettings, otherOptions, forceConfiguration);
+stages.configureStageHandling(context, stageHandlingSettings, stageHandlingOptions, otherSettings, otherOptions, forceConfiguration);
 
@@ -225,3 +286,6 @@ // ... OR using completely customised stage handling settings
 // To look up stage handling settings and functions
+const settingName = 'injectInCase'; // example stage handling setting name
 const setting = stages.getStageHandlingSetting(context, settingName);
+
+const functionSettingName = 'convertAliasToStage'; // example stage handling function name
 const fn = stages.getStageHandlingFunction(context, functionSettingName);
@@ -231,22 +295,28 @@
 const context = {};
-const stage = stages.resolveStage(event, awsContext, context);
+const stage = stages.resolveStage(awsEvent, awsContext, context);
 
-// 2. To configure a context with a resolved stage 
-stages.configureStage(context, event, awsContext, failFast)
+// 2. To configure a context with a resolved stage (uses resolveStage)
+const failFast = true;
+stages.configureStage(context, awsEvent, awsContext, failFast);
+assert(context.stage && typeof context.stage === 'string');
 
-// 3. To qualify an unqualified stream name with a stage
-const unqualifiedStreamName = 'TestStream';
-const stageQualifiedStreamName = stages.toStageQualifiedStreamName(unqualifiedStreamName, stage, context);
-
-// 4. To extract a stage from a qualified stream name
+// 3. To extract a stage from a qualified stream name
 const qualifiedStreamName = 'TestStream_PROD';
 const stage2 = stages.extractStageFromQualifiedStreamName(qualifiedStreamName, context);
+assert(stage2 === 'prod'); // assuming default stage handling configuration
 
-// 5. To qualify an unqualified resource name with a stage
-const unqualifiedResourceName = 'TestResource';
-const stageQualifiedResourceName = stages.toStageQualifiedResourceName(unqualifiedResourceName, stage, context);
+// 4. To qualify an unqualified stream name with a stage
+const unqualifiedStreamName = 'TestStream';
+const stageQualifiedStreamName = stages.toStageQualifiedStreamName(unqualifiedStreamName, stage2, context);
+assert(stageQualifiedStreamName === 'TestStream_PROD'); // assuming default stage handling configuration
 
-// 6. To extract a stage from a qualified resource name
-const qualifiedResourceName = 'TestResource_QA';
-const stage3 = stages.extractStageFromQualifiedResourceName(qualifiedResourceName, context);
+// 5. To extract a stage from a qualified resource name
+const qualifiedTableName = 'TestTable_QA';
+const stage3 = stages.extractStageFromQualifiedResourceName(qualifiedTableName, context);
+assert(stage3 === 'qa'); // assuming default stage handling configuration
+
+// 6. To qualify an unqualified resource name with a stage
+const unqualifiedTableName = 'TestTable';
+const stageQualifiedResourceName = stages.toStageQualifiedResourceName(unqualifiedTableName, stage3, context);
+assert(stageQualifiedResourceName === 'TestTable_QA'); // assuming default stage handling configuration
 ```
@@ -304,2 +374,17 @@
 
+### 5.0.11
+- Changes to `type-defs.js` module:
+  - Added `StandardContext`, `StandardSettings`, `StandardOptions`, `CustomAware`, `CustomSettings`, `CustomOptions`
+    and `RegionStageAWSContextAware`
+- Added new `contexts.js` module with `configureStandardContext` and `configureCustomSettings` functions
+- Added new `api-lambdas.js` module with `failCallback` (and synonym `failCallbackForApiGateway`) functions and 
+  re-exported `configureStandardContext` function from `contexts.js` to simplify imports for API Gateway exposed Lambdas
+- Changes to `lambdas.js` module:
+  - Moved `failCallbackForApiGateway` function to new `api-lambdas.js` module
+- Changes to `stages.js` module:
+  - Added new `configureRegionStageAndAwsContext` convenience function to configure current region, resolved stage and
+    AWS context on the given context
+  - Improved JsDoc type definitions on all of the configuration functions
+- Added and improved existing examples in README.md
+
 ### 5.0.10
@@ -306,0 +391,0 @@ - Fixed broken unit tests by changing incorrect imports of `node-uuid` to `uuid`

regions.js

@@ -222,4 +222,4 @@ 'use strict';
  * that determines whether the error will be raised (if failFast is explicitly true) or simply logged as a warning
+ * @returns {RegionAware} the context with its existing region or the current AWS_REGION env variable value.
  * @throws {Error} if failFast is explicitly true and an AWS_REGION env variable is needed and not available
- * @returns {RegionAware} the context with its existing region or the current AWS_REGION env variable value.
  */
@@ -226,0 +226,0 @@ function configureRegion(context, failFast) {

stages.js

@@ -31,15 +31,23 @@ 'use strict';
 module.exports = {
-  // Configuration
+  // Stage handling configuration
   isStageHandlingConfigured: isStageHandlingConfigured,
   configureStageHandling: configureStageHandling,
+  configureDefaultStageHandling: configureDefaultStageHandling,
   getDefaultStageHandlingSettings: getDefaultStageHandlingSettings,
-  configureDefaultStageHandling: configureDefaultStageHandling,
+
+  // Functions providing access to configured stage handling settings & functions by name
   getStageHandlingSetting: getStageHandlingSetting,
   getStageHandlingFunction: getStageHandlingFunction,
+
   // Stage resolution
   resolveStage: resolveStage,
+
+  // Stage resolution and configuration
   configureStage: configureStage,
+  configureRegionStageAndAwsContext: configureRegionStageAndAwsContext,
+
   // Stream name qualification
   toStageQualifiedStreamName: toStageQualifiedStreamName,
   extractStageFromQualifiedStreamName: extractStageFromQualifiedStreamName,
+
   // Resource name qualification
@@ -83,3 +91,4 @@ toStageQualifiedResourceName: toStageQualifiedResourceName,
 
-const Lambdas = require('./lambdas');
+const regions = require('./regions');
+const lambdas = require('./lambdas');
 
@@ -106,12 +115,12 @@ const Arrays = require('core-functions/arrays');
  *
- * @param {Object} context - the context onto which to configure stage handling settings
+ * @param {Object|StandardContext|StageHandling|Logging} context - the context onto which to configure stage handling settings
  * @param {StageHandlingSettings} [context.stageHandling] - previously configured stage handling settings on the context (if any)
  * @param {StageHandlingSettings} settings - the new stage handling settings to use
- * @param {Object|undefined} [otherSettings] - optional other configuration settings to use
+ * @param {Object|StandardSettings|undefined} [otherSettings] - optional other configuration settings to use
  * @param {LoggingSettings|undefined} [otherSettings.loggingSettings] - optional logging settings to use to configure logging
- * @param {Object|undefined} [otherOptions] - optional other configuration options to use if no corresponding other settings are provided
+ * @param {Object|StandardOptions|undefined} [otherOptions] - optional other configuration options to use if no corresponding other settings are provided
  * @param {LoggingOptions|undefined} [otherOptions.loggingOptions] - optional logging options to use to configure logging
  * @param {boolean|undefined} [forceConfiguration] - whether or not to force configuration of the given settings, which
  * will override any previously configured stage handling settings on the given context
- * @return {StageHandling} the context object configured with stage handling settings and logging functionality
+ * @return {StageHandling|StandardContext} the context object configured with stage handling settings and logging functionality
  */
@@ -152,12 +161,12 @@ function configureStageHandlingWithSettings(context, settings, otherSettings, otherOptions, forceConfiguration) {
  *
- * @param {Object} context - the context onto which to configure the default stage handling settings
+ * @param {Object|StandardContext|StageHandling|Logging} context - the context onto which to configure the default stage handling settings
  * @param {StageHandlingSettings} [context.stageHandling] - previously configured stage handling settings on the context (if any)
  * @param {StageHandlingOptions|undefined} [options] - optional stage handling options to use to override the default options
- * @param {Object|undefined} [otherSettings] - optional other configuration settings to use
+ * @param {Object|StandardSettings|undefined} [otherSettings] - optional other configuration settings to use
  * @param {LoggingSettings|undefined} [otherSettings.loggingSettings] - optional logging settings to use to configure logging
- * @param {Object|undefined} [otherOptions] - optional other configuration options to use if no corresponding other settings are provided
+ * @param {Object|StandardOptions|undefined} [otherOptions] - optional other configuration options to use if no corresponding other settings are provided
  * @param {LoggingOptions|undefined} [otherOptions.loggingOptions] - optional logging options to use to configure logging
  * @param {boolean|undefined} [forceConfiguration] - whether or not to force configuration of the default settings, which
  * will override any previously configured stage handling settings on the given context
- * @return {StageHandling} the context object configured with stage handling settings (either existing or defaults or
+ * @return {StageHandling|StandardContext} the context object configured with stage handling settings (either existing or defaults or
  * overrides) and logging functionality
@@ -235,3 +244,3 @@ */
  * @param {string} settingName - the name of the stage handling setting
- * @returns {*|undefined} the named function (if it's a function); otherwise undefined
+ * @returns {Function|undefined} the named function (if it's a function); otherwise undefined
  */
@@ -248,12 +257,16 @@ function getStageHandlingFunction(context, settingName) {
  *
- * @param {Object} context - the context to configure
+ * The distinction between options and settings is that options are meant to contain only non-function properties
+ * typically loaded from a JSON file, whereas settings are meant to be constructed in code and hence can contain both
+ * non-function properties and functions if needed.
+ *
+ * @param {Object|StandardContext|StageHandling|Logging} context - the context to configure
  * @param {StageHandlingSettings|undefined} [settings] - optional stage handling settings to use to configure stage handling
  * @param {StageHandlingOptions|undefined} [options] - optional stage handling options to use to override default options
- * @param {Object|undefined} [otherSettings] - optional other settings to use to configure dependencies
+ * @param {Object|StandardSettings|undefined} [otherSettings] - optional other settings to use to configure dependencies
  * @param {LoggingSettings|undefined} [otherSettings.loggingSettings] - optional logging settings to use to configure logging
- * @param {Object|undefined} [otherOptions] - optional other options to use to configure dependencies if corresponding settings are not provided
+ * @param {Object|StandardOptions|undefined} [otherOptions] - optional other options to use to configure dependencies if corresponding settings are not provided
  * @param {LoggingOptions|undefined} [otherOptions.loggingOptions] - optional logging options to use to configure logging
  * @param {boolean|undefined} [forceConfiguration] - whether or not to force configuration of the given settings, which
  * will override any previously configured stage handling settings on the given context
- * @return {StageHandling} the given context object configured with stage handling settings and logging functionality
+ * @return {StageHandling|StandardContext} the given context object configured with stage handling settings and logging functionality
  */
@@ -265,5 +278,2 @@ function configureStageHandling(context, settings, options, otherSettings, otherOptions, forceConfiguration) {
 
-  // // First configure all stage handling dependencies
-  // configureDependencies(context, otherSettings, otherOptions, false);
-
   // Check if stage handling was already configured
@@ -291,10 +301,10 @@ const stageHandlingWasConfigured = isStageHandlingConfigured(context);
  *
- * @param {Object} context - the context onto which to configure the given stage handling dependencies
- * @param {Object|undefined} [otherSettings] - optional other configuration settings to use
+ * @param {Object|StandardContext|Logging} context - the context onto which to configure the given stage handling dependencies
+ * @param {Object|StandardSettings|undefined} [otherSettings] - optional other configuration settings to use
  * @param {LoggingSettings|undefined} [otherSettings.loggingSettings] - optional logging settings to use to configure logging
- * @param {Object|undefined} [otherOptions] - optional other configuration options to use if no corresponding other settings are provided
+ * @param {Object|StandardOptions|undefined} [otherOptions] - optional other configuration options to use if no corresponding other settings are provided
  * @param {LoggingOptions|undefined} [otherOptions.loggingOptions] - optional logging options to use to configure logging
  * @param {boolean|undefined} [forceConfiguration] - whether or not to force configuration of the given settings, which
  * will override any previously configured dependencies' settings on the given context
- * @returns {Logging} the context object configured with stage handling dependencies (i.e. logging functionality)
+ * @returns {Logging|StandardContext} the context object configured with stage handling dependencies (i.e. logging functionality)
  */
@@ -406,3 +416,3 @@ function configureDependencies(context, otherSettings, otherOptions, forceConfiguration) {
     // Extract the alias
-    const alias = Lambdas.getAlias(awsContext);
+    const alias = lambdas.getAlias(awsContext);
 
@@ -748,4 +758,4 @@ // If the alias is not blank, apply the convertAliasToStage function to it to derive a stage
  * blank and which determines whether the error will be raised (if failFast is explicitly true) or logged as a warning
+ * @returns {StageAware} the given context with its existing stage or the resolved stage or an empty string stage.
  * @throws {Error} if failFast is explicitly true and a needed resolved stage is blank
- * @returns {StageAware} the given context with its existing stage or the resolved stage or an empty string stage.
  */
@@ -771,2 +781,28 @@ function configureStage(context, event, awsContext, failFast) {
   return context;
+}
+
+/**
+ * Configures the given context with the current region, the resolved stage and the given AWS context. In order to
+ * resolve the stage, stage handling settings and logging must already be configured on the given context (see
+ * {@linkcode stages#configureStageHandling} for details).
+ * @param {StageHandling|RegionStageAWSContextAware} context - the context to configure
+ * @param {Object} event - the AWS event, which was passed to your lambda
+ * @param {Object} awsContext - the AWS context, which was passed to your lambda
+ * @return {RegionStageAWSContextAware} the given context configured with a region, stage and the given AWS context
+ * @throws {Error} if no region is available in the AWS_REGION environment variable or if the resolved stage is blank
+ */
+function configureRegionStageAndAwsContext(context, event, awsContext) {
+  // Configure context.awsContext with the given AWS context, if not already configured
+  if (!context.awsContext) {
+    context.awsContext = awsContext;
+  }
+  // Configure context.region to the AWS region, if it is not already configured
+  regions.configureRegion(context, true);
+
+  // Resolve the current stage (e.g. dev, qa, prod, ...) if possible and configure context.stage with it, if it is not
+  // already configured
+  configureStage(context, event, awsContext, true);
+
+  context.info(`Using region (${context.region}) and stage (${context.stage})`);
+  return context;
 }

test/package.json

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

type-defs.js

 'use strict';
 
 /**
+ * @typedef {StageHandling} StandardContext - an object configured as a standard context with stage handling, logging,
+ * custom settings, an optional Kinesis instance and an optional DynamoDB DocumentClient instance and OPTIONALLY also
+ * with the current region, the resolved stage and the AWS context
+ * @property {CustomSettings|undefined} custom - an object configured with optional custom settings to use
+ * @property {AWS.Kinesis|undefined} [kinesis] - an optional AWS.Kinesis instance to use
+ * @property {AWS.DynamoDB.DocumentClient|undefined} [dynamoDBDocClient] - an optional AWS.DynamoDB.DocumentClient instance to use
+ * @property {string|undefined} [region] - the name of the AWS region to use
+ * @property {string|undefined} [stage] - the configured stage to use
+ * @property {Object|undefined} [awsContext] - the AWS context passed to your Lambda function on invocation
+ */
+
+/**
+ * @typedef {Object} StandardSettings - settings to be used to configure a standard context (see StandardContext)
+ * @property {LoggingSettings|undefined} [loggingSettings] - optional logging settings to use to configure logging
+ * @property {StageHandlingSettings|undefined} [stageHandlingSettings] - optional stage handling settings to use to configure stage handling
+ * @property {CustomSettings|undefined} [customSettings] - custom settings to be merged into an existing or new context.custom object
+ * @property {Object|undefined} [kinesisOptions] - optional Kinesis constructor options to use to configure an AWS.Kinesis instance
+ * @property {Object|undefined} [dynamoDBDocClientOptions] - optional DynamoDB.DocumentClient constructor options to use to configure an AWS.DynamoDB.DocumentClient instance
+ */
+
+/**
+ * @typedef {Object} StandardOptions - options to be used to configure a standard context (see StandardContext)
+ * @property {LoggingOptions|undefined} [loggingOptions] - optional logging options to use to configure logging
+ * @property {StageHandlingOptions|undefined} [stageHandlingOptions] - optional stage handling options to use to configure stage handling
+ * @property {CustomOptions|undefined} [customOptions] - custom options to be merged into an existing or new context.custom object
+ * @property {Object|undefined} [kinesisOptions] - optional Kinesis constructor options to use to configure an AWS.Kinesis instance
+ * @property {Object|undefined} [dynamoDBDocClientOptions] - optional DynamoDB.DocumentClient constructor options to use to configure an AWS.DynamoDB.DocumentClient instance
+ */
+
+/**
+ * @typedef {Object} CustomAware - a context object configured with custom settings
+ * @property {CustomSettings|undefined} custom - an object configured with optional custom settings to use
+ * Any existing context.custom settings take precedence over and will replace any same named CustomSettings settings and
+ * CustomOptions options when merged together to create the final context.custom object during configuration via
+ * {@linkcode contexts#configureCustomSettings}
+ */
+
+/**
+ * @typedef {Object} CustomSettings - optional custom settings to be merged into an existing or new context.custom object
+ * Any CustomSettings settings take precedence over and will replace any same named CustomOptions options when merged
+ * together to create the final context.custom object during configuration via {@linkcode contexts#configureCustomSettings}
+ */
+
+/**
+ * @typedef {Object} CustomOptions - optional custom options to be merged with any CustomSettings settings and then
+ * merged into an existing or new context.custom object during configuration via {@linkcode contexts#configureCustomSettings}
+ */
+
+/**
  * @typedef {Object} RegionAware - an object configured with the name of an AWS region to use, which is typically the
@@ -10,2 +59,9 @@ * current AWS region sourced from a Lambda's AWS_REGION environment variable
 /**
+ * @typedef {StageAware} RegionStageAWSContextAware - an object configured with the name of the current AWS region,
+ * the AWS context and the resolved stage, which implies pre-configured stage handling settings and logging functionality
+ * @property {string} region - the name of the AWS region to use
+ * @property {Object} awsContext - the AWS context passed to your Lambda function on invocation
+ */
+
+/**
  * @typedef {StageHandling} StageAware - an object configured with a stage, stage handling settings and logging functionality
@@ -24,8 +80,8 @@ * @property {string} stage - the configured stage to use
  * @typedef {Object} DynamoDBDocClientAware - an object configured with an AWS.DynamoDB.DocumentClient instance
- * @property {AWS.DynamoDB.DocumentClient} dynamoDBDocClient - an optional AWS.DynamoDB.DocumentClient instance to use
+ * @property {AWS.DynamoDB.DocumentClient} dynamoDBDocClient - an AWS.DynamoDB.DocumentClient instance to use
  */
 
 /**
- * @typedef {Logging} StageHandling - an object configured with stage handling settings and logging functionality
- * @property {StageHandlingSettings} stageHandling - the configured stage handling settings to use
+ * @typedef {Logging} StageHandling - an object configured with stage handling and logging functionality
+ * @property {StageHandlingSettings} stageHandling - an object configured with stage handling settings and functionality to use
  */
@@ -32,0 +88,0 @@

No alert changes

Improved metrics

Total package byte prevSize

339573

increased by11.87%

Number of package files

29

increased by16%

Lines of code

4865

increased by11.84%

Number of lines in readme file

580

increased by17.17%

Worsened metrics

Number of low supply chain risk alerts

29

increased by7.41%

No dependency changes