aws-core-utils - npm Package Compare versions

Comparing version 6.0.2 to 6.0.3

contexts.js

 'use strict';
 
+const regions = require('./regions');
 const stages = require('./stages');
@@ -46,6 +47,5 @@ const kinesisCache = require('./kinesis-cache');
  *
- * Note that if either the given event or AWS context are undefined, then everything other than the region, stage and
- * AWS context will be configured. This missing configuration can be configured at a later point in your code by
- * invoking {@linkcode stages#configureRegionStageAndAwsContext}. This separation of configuration is primarily useful
- * for unit testing.
+ * Note that if either the given event or AWS context are undefined, then everything other than the stage and AWS
+ * context will be configured. This missing configuration can be configured at a later point in your code by invoking
+ * {@linkcode stages#configureStageAndAwsContext}. This separation of configuration is primarily useful for unit testing.
  *
@@ -67,2 +67,5 @@ * @param {Object|StandardContext} context - the context to configure as a standard context
 
+  // Configure the region after configuring logging (failing fast if process.env.AWS_REGION is blank)
+  regions.configureRegion(context, true);
+
   // Configure the given context with any custom settings and/or custom options
@@ -89,4 +92,4 @@ configureCustomSettings(context, settings ? settings.customSettings : undefined, options ? options.customOptions : undefined);
   if (event && awsContext) {
-    // Configure the given context with the current region, resolved stage and AWS context
-    stages.configureRegionStageAndAwsContext(context, event, awsContext);
+    // Configure the given context with the resolved stage and AWS context
+    stages.configureStageAndAwsContext(context, event, awsContext);
   }
@@ -93,0 +96,0 @@ return context;

package.json

 {
   "name": "aws-core-utils",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "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 v6.0.2
+# aws-core-utils v6.0.3
 
@@ -391,2 +391,19 @@ Core utilities for working with Amazon Web Services (AWS), including ARNs, regions, stages, Lambdas, AWS errors, stream events, Kinesis, DynamoDB.DocumentClients, etc.
 
+### 6.0.3
+- Changes to `regions` module:
+  - Changed `getRegion` function to treat "undefined" or "null" regions as undefined 
+  - Added `setRegion` function
+  - Changed `setRegionIfNotSet` function to use `setRegion`
+  - Deprecated `setRegionIfNotSet` function
+  - Changed `configureRegion` function to fallback to using `console.log` if `context.info` is not configured yet 
+- Changes to `stages` module:
+  - Added `configureStageAndAwsContext` convenience function to configure resolved stage and AWS context on the given context
+  - Deprecated old `configureRegionStageAndAwsContext` convenience function
+- Changes to `contexts` module:
+  - Changed `configureStandardContext` function to invoke `regions.configureRegion` as early in the function as possible
+    & to invoke `stages.configureStageAndAwsContext` instead of `stages.configureRegionStageAndAwsContext`
+- Changes to `type-defs` module:
+   - Added `StageAndAWSContextAware` type definition
+   - Added `DynamoDBGetItemOpts`, `DynamoDBGetItemResult`, `DynamoDBQueryOpts`, `DynamoDBQueryResult` & `ConsumedCapacity` type definitions
+
 ### 6.0.2
@@ -393,0 +410,0 @@ - Upgraded to Node 6.10.3

regions.js

@@ -10,2 +10,3 @@ 'use strict';
   getRegion: getRegion,
+  setRegion: setRegion,
   getDefaultRegion: getDefaultRegion,
@@ -32,25 +33,22 @@ //getRegionOrDefault: getRegionOrDefault,
 const arns = require('./arns');
-// const getArnComponent = arns.getArnComponent;
-// const getArnPartition = arns.getArnPartition;
-// const getArnService = arns.getArnService;
 const getArnRegion = arns.getArnRegion;
-// const getArnAccountId = arns.getArnAccountId;
-// const getArnResources = arns.getArnResources;
 
 /**
- * Gets the region in which this function is running from the AWS_REGION environment variable (if it exists, which
- * should always be true for a live AWS Lambda); otherwise logs a warning and returns an empty string.
+ * Gets the region in which this function is running from the `AWS_REGION` environment variable and returns it as is if
+ * it's neither "undefined" nor "null"; otherwise logs a warning and returns undefined if it's "undefined" or "null" (or
+ * undefined).
  *
- * This is the best option to use to get the region within AWS Lambda code (and the only option to use at module-level
- * scope), since these environment variables will be set by AWS Lambda.
+ * The `AWS_REGION` environment variable is the best option to use to get the region within AWS Lambda code (and the
+ * only option to use at module-level scope), since these environment variables will be set by AWS Lambda.
  *
- * An optional hidden 'failFast' boolean argument, which defaults to false, can be passed as true to raise an error if
- * the AWS_REGION env variable is not available
+ * An optional "hidden" 'failFast' boolean argument, which defaults to false, can be passed as true to raise an error if
+ * the AWS_REGION env variable is not available or unusable
  *
- * @returns {string} the AWS region (if it exists); otherwise an empty string.
+ * @returns {string|undefined} the AWS region (if it exists); otherwise undefined.
  */
 function getRegion() {
-  const region = trimOrEmpty(process.env.AWS_REGION);
+  const awsRegion = trim(process.env.AWS_REGION);
+  const region = awsRegion !== "undefined" && awsRegion !== "null" ? awsRegion : undefined;
   if (!region) {
-    const errorMsg = 'Failed to get AWS_REGION from env - for unit testing either call setRegionIfNotBlank(...) in your tests or set your AWS_REGION env variable';
+    const errorMsg = `Failed to get usable region from AWS_REGION env variable (${awsRegion}) - for unit testing call setRegion beforehand`;
     const failFast = arguments.length > 0 && arguments[0] === true;
@@ -67,2 +65,21 @@ if (failFast) {
 /**
+ * Sets the `AWS_REGION` environment variable to the given region (if it's NOT undefined, "undefined", null or "null");
+ * otherwise deletes `process.env.AWS_REGION`, which effectively "sets" it to undefined. NB: `delete` is used to avoid
+ * the undesirable behaviour where setting `process.env.AWS_REGION` to undefined or null results in it containing the
+ * string "undefined" or "null" respectively. NB: This only sets the region temporarily on the current process and
+ * should largely only be used for testing purposes.
+ * @param {string|undefined|null} awsRegion - the region to set on or delete from process.env.AWS_REGION
+ */
+function setRegion(awsRegion) {
+  const region = trim(awsRegion);
+  if (region === undefined || region === null || region === 'undefined' || region === 'null') {
+    // If the given region is undefined or null, then must delete process.env.AWS_REGION rather than setting it to
+    // undefined or null, which incorrectly sets it to the strings "undefined" or "null" respectively
+    delete process.env.AWS_REGION;
+  } else {
+    process.env.AWS_REGION = region;
+  }
+}
+
+/**
  * Gets the region from the AWS_DEFAULT_REGION environment variable; otherwise returns an empty string.
@@ -78,7 +95,7 @@ * @returns {string} the AWS default region (if it exists); otherwise an empty string
  * NB: This only sets the region temporarily on the current process and should probably only be used for testing purposes.
+ * @deprecated use `setRegion` instead
  * @returns {boolean} true if set; false otherwise.
  */
 function setRegionIfNotSet(awsRegion) {
-  // Replaces an undefined or null awsRegion with '', otherwise it will become 'undefined' or 'null' on process.env
-  const newRegion = trimOrEmpty(awsRegion);
+  const newRegion = trim(awsRegion);
 
@@ -88,14 +105,8 @@ // Check if AWS region is already set or not
   if (isBlank(region)) {
-    // Attempt to set the AWS_REGION
-    try {
-      process.env.AWS_REGION = newRegion;
-      return true;
-    } catch (err) {
-      console.error(`Failed to set AWS_REGION env variable to (${newRegion}) - ${err}`, err.stack);
-    }
-  } else {
-    if (process.env.AWS_REGION !== newRegion) {
-      console.log(`Ignoring attempt to change ALREADY set AWS_REGION env variable (${process.env.AWS_REGION}) to (${newRegion})`);
-    }
+    setRegion(newRegion);
+    return true;
   }
+  if (process.env.AWS_REGION !== newRegion) {
+    console.log(`Ignoring attempt to change ALREADY set AWS_REGION env variable (${process.env.AWS_REGION}) to (${newRegion})`);
+  }
   return false;
@@ -143,54 +154,2 @@ }
 
-// /**
-//  * Extracts a region from the following resources in the following order:
-//  * 1. Using {@linkcode getRegion}
-//  * 2. The region extracted from the given AWS context's invokedFunctionArn (if any)
-//  * 3. The first non-blank awsRegion (if any) extracted from the event's records
-//  * 4. The first non-blank eventSourceARN region (if any) extracted from the event's records
-//  *
-//  * The detailed process followed is as follows:
-//  * 1. Attempts to get the region using {@linkcode getRegion} (i.e. from AWS-specific environment variables).
-//  *
-//  * 2. Extracts and returns the region from the given awsContext's invokedFunctionArn, if it contains an
-//  *    invokedFunctionArn in the form of "arn:aws:lambda:<region>:<accountId>:function:<functionName>[:functionAlias]".
-//  *
-//  * 3. Returns the first non-blank awsRegion (if any) extracted from the event's records, if any of them contain an awsRegion property.
-//  *
-//  * 4. Returns the first non-blank eventSourceARN region (if any) extracted from the event's records, if any of them contain an
-//  *
-//  * Extracts and returns the region from the given event's eventSourceARN, if it contains an eventSourceARN
-//  *    in the form of "arn:aws:kinesis:<region>:<accountId>:stream/<streamName>".
-//  *
-//  * 5. Gives up and returns an empty string.
-//  *
-//  * @param {Object} event the Kinesis event to be checked
-//  * @param {Object} awsContext the AWS context
-//  * @return {string} the region if found; otherwise an empty string
-//  */
-// function resolveRegion(event, awsContext) {
-//   // Attempt 1
-//   let region = getRegion();
-//   if (isNotBlank(region)) {
-//     return region;
-//   }
-//   // Attempt 2
-//   region = getInvokedFunctionArnRegion(awsContext);
-//   if (isNotBlank(region)) {
-//     return region;
-//   }
-//   // Attempt 3
-//   region = getEventAwsRegions(event).find(r => isNotBlank(r));
-//   if (isNotBlank(region)) {
-//     return region;
-//   }
-//   // Attempt 4
-//   region = getEventSourceArnRegions(event).find(r => isNotBlank(r));
-//   if (isNotBlank(region)) {
-//     return region;
-//   }
-//   // Give up
-//   return '';
-// }
-
-
 /**
@@ -222,5 +181,6 @@ * Gets the region in which this function is running from the AWS_REGION environment variable (if it exists); otherwise
 /**
- * Returns the context.region if it is already configured on the given context, otherwise gets the current AWS_REGION
- * and then, if its not blank, sets it on the context as context.region; otherwise either raises an error if failFast is
- * explicitly true or logs a warning.
+ * Keeps context.region as is if it's already configured on the given context, otherwise gets the current region from
+ * process.env.AWS_REGION and if it's not blank, sets it on the context as context.region; otherwise either throws an
+ * error if failFast is explicitly true.
+ * @deprecated simply use `getRegion` directly instead when the region is required
  * @param {Object|RegionAware} context - a context on which to set the region
@@ -237,4 +197,4 @@ * @param {boolean|undefined} [failFast] - an optional flag that is only used when AWS_REGION is needed and blank and
   }
+  (context.info ? context.info : console.log)(`Using region (${getRegion()}) + context.region (${context.region})`);
   return context;
-}
-
+}

stages.js

@@ -50,2 +50,4 @@ 'use strict';
   configureStage: configureStage,
+  configureStageAndAwsContext: configureStageAndAwsContext,
+  /** @deprecated Use configureStageAndAwsContext instead & either regions.getRegion or regions.configureRegion */
   configureRegionStageAndAwsContext: configureRegionStageAndAwsContext,
@@ -909,5 +911,30 @@
 /**
+ * Configures the given context with 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|StageAndAWSContextAware} 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 {StageAndAWSContextAware} the given context configured with a stage and the given AWS context
+ * @throws {Error} if the resolved stage is blank
+ */
+function configureStageAndAwsContext(context, event, awsContext) {
+  // Configure context.awsContext with the given AWS context, if not already configured
+  if (!context.awsContext) {
+    context.awsContext = awsContext;
+  }
+
+  // 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 stage (${context.stage})`);
+  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).
+ * @deprecated Use configureStageAndAwsContext instead & either regions.getRegion or regions.configureRegion
  * @param {StageHandling|RegionStageAWSContextAware} context - the context to configure
@@ -931,4 +958,4 @@ * @param {Object} event - the AWS event, which was passed to your lambda
 
-  context.info(`Using region (${context.region}) and stage (${context.stage})`);
+  context.info(`Using region (${regions.getRegion()}) + context.region (${context.region}) and stage (${context.stage})`);
   return context;
 }

test/contexts.test.js

@@ -5,2 +5,4 @@ 'use strict';
 
+const awsRegion = 'us-west-1';
+
 // Test subject
@@ -247,2 +249,3 @@ const contexts = require('../contexts');
 
+  regions.setRegion(awsRegion);
   contexts.configureStandardContext(context, undefined, undefined, undefined, undefined, false);
@@ -261,3 +264,3 @@
   t.notOk(context.dynamoDBDocClient, 'context.dynamoDBDocClient must not be defined');
-  t.notOk(context.region, 'context.region must not be defined');
+  t.equal(context.region, awsRegion, `context.region must not be ${awsRegion}`);
   t.notOk(context.stage, 'context.stage must not be defined');
@@ -275,2 +278,3 @@ t.notOk(context.awsContext, 'context.awsContext must not be defined');
 
+  regions.setRegion(awsRegion);
   contexts.configureStandardContext(context, undefined, standardOptions, undefined, undefined, false);
@@ -292,3 +296,3 @@
   t.ok(context.dynamoDBDocClient, 'context.dynamoDBDocClient must be defined');
-  t.notOk(context.region, 'context.region must not be defined');
+  t.equal(context.region, awsRegion, `context.region must not be ${awsRegion}`);
   t.notOk(context.stage, 'context.stage must not be defined');
@@ -306,2 +310,3 @@ t.notOk(context.awsContext, 'context.awsContext must not be defined');
 
+  regions.setRegion(awsRegion);
   contexts.configureStandardContext(context, standardSettings, undefined, undefined, undefined, false);
@@ -326,3 +331,3 @@
   t.ok(context.dynamoDBDocClient, 'context.dynamoDBDocClient must be defined');
-  t.notOk(context.region, 'context.region must not be defined');
+  t.equal(context.region, awsRegion, `context.region must not be ${awsRegion}`);
   t.notOk(context.stage, 'context.stage must not be defined');
@@ -340,2 +345,3 @@ t.notOk(context.awsContext, 'context.awsContext must not be defined');
 
+  regions.setRegion(awsRegion);
   contexts.configureStandardContext(context, standardSettings, standardOptions, undefined, undefined, false);
@@ -360,3 +366,3 @@
   t.ok(context.dynamoDBDocClient, 'context.dynamoDBDocClient must be defined');
-  t.notOk(context.region, 'context.region must not be defined');
+  t.equal(context.region, awsRegion, `context.region must not be ${awsRegion}`);
   t.notOk(context.stage, 'context.stage must not be defined');
@@ -363,0 +369,0 @@ t.notOk(context.awsContext, 'context.awsContext must not be defined');

test/package.json

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

test/regions.test.js

@@ -15,5 +15,5 @@ 'use strict';
 const getRegion = regions.getRegion;
+const setRegion = regions.setRegion;
+
 const getRegionRaw = regions.ONLY_FOR_TESTING.getRegionRaw;
-// const getDefaultRegion = regions.getDefaultRegion;
-// const resolveRegion = regions.resolveRegion;
 const setRegionIfNotSet = regions.ONLY_FOR_TESTING.setRegionIfNotSet;
@@ -23,11 +23,8 @@
 const isBlank = Strings.isBlank;
-// const isNotBlank = Strings.isNotBlank;
-// const trim = Strings.trim;
-// const trimOrEmpty = Strings.trimOrEmpty;
 
 // =====================================================================================================================
-// Tests for getRegion
+// Tests for getRegion & setRegion
 // =====================================================================================================================
 
-test('getRegion and setRegionIfNotSet', t => {
+test('getRegion and setRegion', t => {
 
@@ -38,39 +35,42 @@ // Attempt to preserve the original AWS_REGION setting (unfortunately cannot preserve undefined or null)
   // check orig
-  if (isBlank(origRegion)) {
+  if (origRegion === undefined) {
     t.equal(origRegion, process.env.AWS_REGION, `original raw must be '${process.env.AWS_REGION}'`);
-    t.equal(getRegion(), '', `original must be empty string '${process.env.AWS_REGION}'`);
+    t.equal(getRegion(), undefined, `original must be empty string '${process.env.AWS_REGION}'`);
+  } else if (isBlank(origRegion)) {
+    t.equal(origRegion, process.env.AWS_REGION, `original raw must be '${process.env.AWS_REGION}'`);
+    t.equal(getRegion(), '', `original must be undefined '${process.env.AWS_REGION}'`);
   }
 
-  // Must use empty string to "clear" property.env variable - undefined & null don't work (e.g. it sets it to 'undefined' or 'null')
-  const unset = '';
-
+  // Must use delete to "clear" property.env variable - since setting to undefined & null don't work as intended
   try {
-    // "Clear" AWS_REGION to empty string
-    //console.log(`BEFORE reset process.env.AWS_REGION = (${process.env.AWS_REGION})`);
-    process.env.AWS_REGION = unset;
-    //console.log(`AFTER reset process.env.AWS_REGION = '${process.env.AWS_REGION}' (orig was ${origRegion})`);
-    t.equal(process.env.AWS_REGION, unset, `process.env.AWS_REGION must be '${unset}' after reset`);
+    // Clear AWS_REGION to undefined (by deleting it)
+    delete process.env.AWS_REGION;
+    t.equal(process.env.AWS_REGION, undefined, `process.env.AWS_REGION must be '${undefined}' after delete`);
 
     // check get when not set
-    t.equal(getRegion(), unset, `must be '${unset}'`);
+    t.equal(getRegion(), undefined, `getRegion() must be '${undefined}'`);
+    t.throws(() => getRegion(true), undefined, `getRegion(true) must throw'`);
 
     // check will set, when not set
     const expected = 'TEST_REGION_1';
-    t.ok(setRegionIfNotSet(expected), `must set successfully`);
-    t.equal(getRegion(), expected, `must be ${expected}`);
+    setRegion(expected);
+    t.equal(getRegion(), expected, `setRegion('TEST_REGION_1') then getRegion() must be ${expected}`);
+    t.equal(process.env.AWS_REGION, expected, `process.env.AWS_REGION must be ${expected}`);
 
-    // check was NOT set, when already set set
-    t.notOk(setRegionIfNotSet('TEST_REGION_3'), `must NOT set successfully`);
-    t.equal(getRegion(), expected, `must still be ${expected}`);
+    // check changed, when another set
+    const expected2 = 'TEST_REGION_3';
+    setRegion(expected2);
+    t.equal(getRegion(), expected2, `setRegion('TEST_REGION_3') then getRegion() must now be ${expected2}`);
+    t.equal(process.env.AWS_REGION, expected2, `process.env.AWS_REGION must be ${expected2}`);
 
   } finally {
     // "Restore" original aws region
-    //console.log(`BEFORE restore process.env.AWS_REGION = '${process.env.AWS_REGION}' (orig was ${origRegion})`);
-    process.env.AWS_REGION = isBlank(origRegion) ? unset : origRegion;
-    //console.log(`AFTER restore process.env.AWS_REGION = '${process.env.AWS_REGION}' (orig was ${origRegion})`);
+    setRegion(origRegion);
     // Check "restore" worked
-    if (isBlank(origRegion)) {
-      t.equal(getRegion(), unset, `must be "restored" to '${unset}' (orig was ${origRegion})`);
+    if (origRegion === undefined) {
+      t.equal(getRegion(), undefined, `getRegion() must be "restored" to undefined' (orig was ${origRegion})`);
+    } else if (isBlank(origRegion)) {
+      t.equal(getRegion(), '', `getRegion() must be "restored" to empty string (orig was '${origRegion}')`);
     } else {
-      t.equal(getRegion(), origRegion, `must be restored to ${origRegion}`);
+      t.equal(getRegion(), origRegion, `getRegion() must be restored to ${origRegion}`);
     }
@@ -81,33 +81,53 @@ t.end();
 
-//TODO add tests for other methods
 // =====================================================================================================================
-// Tests for resolveRegion
+// Tests for getRegion and setRegionIfNotSet
 // =====================================================================================================================
 
-// test('resolveRegion with event.awsRegion defined and no event.eventSourceArn and no awsContext.invokedFunctionArn', t => {
-//   // Create an event
-//   const streamName = sampleStreamName('', '');
-//   ;
-//   // Configure different regions to each of the 3 sources
-//   // const eventSourceArnRegion = 'ES_ARN_REGION';
-//   // const eventAwsRegion = 'EVENT_AWS_REGION';
-//   // const invokedFunctionArnRegion = 'IF_ARN_REGION';
-//
-//   const eventSourceArn = sampleEventSourceArn(streamName); //, eventSourceArnRegion);
-//   //const record = sampleKinesisRecord(... eventSourceArn, eventAwsRegion);
-//   //const event = sampleKinesisEventWithRecord(record);
-//   const event = sampleKinesisEventWithSampleRecord(... eventSourceArn); //, eventAwsRegion);
-//
-//   // Create an AWS context
-//   const functionName = sampleFunctionName;
-//   const functionVersion = latestFunctionVersion;
-//
-//   const functionAlias = '';
-//   const invokedFunctionArn = sampleInvokedFunctionArn(sampleFunctionName, functionAlias); //, invokedFunctionArnRegion);
-//   const awsContext = sampleAwsContext(invokedFunctionArn, functionName, functionVersion);
-//
-//   const region = regions.resolveRegion(event, awsContext);
-//   t.equal(region, EVENT_AWS_REGION);
-//
-//   t.end();
-// });
+test('getRegion and setRegionIfNotSet', t => {
+
+  // Attempt to preserve the original AWS_REGION setting (unfortunately cannot preserve undefined or null)
+  const origRegion = getRegionRaw();
+
+  // check orig
+  if (origRegion === undefined) {
+    t.equal(origRegion, process.env.AWS_REGION, `original raw must be '${process.env.AWS_REGION}'`);
+    t.equal(getRegion(), undefined, `original must be empty string '${process.env.AWS_REGION}'`);
+  } else if (isBlank(origRegion)) {
+    t.equal(origRegion, process.env.AWS_REGION, `original raw must be '${process.env.AWS_REGION}'`);
+    t.equal(getRegion(), '', `original must be undefined '${process.env.AWS_REGION}'`);
+  }
+
+  // Must use delete to "clear" property.env variable - since setting to undefined & null don't work as intended
+  try {
+    // Clear AWS_REGION to undefined (by deleting it)
+    delete process.env.AWS_REGION;
+    t.equal(process.env.AWS_REGION, undefined, `process.env.AWS_REGION must be '${undefined}' after delete`);
+
+    // check get when not set
+    t.equal(getRegion(), undefined, `getRegion() must be '${undefined}'`);
+    t.throws(() => getRegion(true), undefined, `getRegion(true) must throw'`);
+
+    // check will set, when not set
+    const expected = 'TEST_REGION_1';
+    t.ok(setRegionIfNotSet(expected), `setRegionIfNotSet('TEST_REGION_1') must set successfully`);
+    t.equal(getRegion(), expected, `getRegion() must be ${expected}`);
+    t.equal(process.env.AWS_REGION, expected, `process.env.AWS_REGION must be ${expected}`);
+
+    // check was NOT set, when already set set
+    t.notOk(setRegionIfNotSet('TEST_REGION_3'), `setRegionIfNotSet('TEST_REGION_3') must NOT set successfully`);
+    t.equal(getRegion(), expected, `getRegion() must still be ${expected}`);
+
+  } finally {
+    // "Restore" original aws region
+    setRegion(origRegion);
+    // Check "restore" worked
+    if (origRegion === undefined) {
+      t.equal(getRegion(), undefined, `getRegion() must be "restored" to undefined' (orig was ${origRegion})`);
+    } else if (isBlank(origRegion)) {
+      t.equal(getRegion(), '', `getRegion() must be "restored" to empty string (orig was '${origRegion}')`);
+    } else {
+      t.equal(getRegion(), origRegion, `getRegion() must be restored to ${origRegion}`);
+    }
+    t.end();
+  }
+});

type-defs.js

@@ -74,6 +74,11 @@ 'use strict';
 /**
- * @typedef {StageAware} RegionStageAWSContextAware - an object configured with the name of the current AWS region,
+ * @typedef {StageAware} StageAndAWSContextAware - an object configured with the AWS context and the resolved stage, which
+ * implies pre-configured stage handling settings and logging functionality
+ * @property {AWSContext} awsContext - the AWS context passed to your Lambda function on invocation
+ */
+
+/**
+ * @typedef {StageAndAWSContextAware} 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 {AWSContext} awsContext - the AWS context passed to your Lambda function on invocation
  */
@@ -367,1 +372,41 @@
  */
+
+/**
+ * @typedef {Object} DynamoDBGetItemOpts - a selection of DynamoDB Query options to use (other than TableName & Key & legacy parameters)
+ * @property {boolean|undefined} [ConsistentRead] - whether to do a consistent read to obtain a strongly consistent result or not (NB: GSIs ONLY support eventually consistent reads)
+ * @property {string|undefined} [ProjectionExpression] - an optional string that identifies one or more attributes to retrieve from the table
+ * @property {Object|undefined} [ExpressionAttributeNames] - optional one or more substitution tokens for attribute names in an expression
+ * @property {'NONE'|'INDEXES'|'TOTAL'|undefined} [ReturnConsumedCapacity] - determines the level of detail about provisioned throughput consumption that is returned in the response
+ */
+/**
+ * @typedef {Object} DynamoDBGetItemResult.<T> - a DynamoDB getItem result
+ * @property {T|undefined} [Item] - the returned item (if found) or undefined (if not)
+ * @property {ConsumedCapacity|undefined} [ConsumedCapacity] - the capacity units consumed by the getItem operation (if requested)
+ */
+
+/**
+ * @typedef {Object} DynamoDBQueryOpts - a selection of DynamoDB Query options to use (other than TableName, [IndexName], KeyConditionExpression, ProjectionExpression, FilterExpression, ExpressionAttributeNames, ExpressionAttributeValues & legacy parameters)
+ * @property {Object|undefined} [ExclusiveStartKey] - the optional exclusive start key from which to continue a previous query
+ * @property {number|undefined} [Limit] - the optional number of results to which to limit the query
+ * @property {boolean|undefined} [ConsistentRead] - whether to do a consistent read to obtain a strongly consistent result or not (NB: GSIs ONLY support eventually consistent reads)
+ * @property {boolean|undefined} [ReturnConsumedCapacity] - whether to return consumed capacity or not
+ * @property {boolean|undefined} [ScanIndexForward] - use this to get results in forward or reverse order, by sort key
+ * @property {'ALL_ATTRIBUTES'|'ALL_PROJECTED_ATTRIBUTES'|'SPECIFIC_ATTRIBUTES'|'COUNT'|undefined} [Select] - the selected type of result(s) to return
+ */
+// * @property {string|undefined} [ProjectionExpression] - an optional string that identifies one or more attributes to retrieve from the table
+// * @property {string|undefined} [FilterExpression] - an optional string that contains conditions that DynamoDB applies after the Query operation, but before the data is returned
+// * @property {Object|undefined} [ExpressionAttributeNames] - optional one or more substitution tokens for attribute names in an expression
+// * @property {Object|undefined} [ExpressionAttributeValues] - optional one or more substitution tokens for attribute names in an expression
+
+/**
+ * @typedef {Object} DynamoDBQueryResult.<T> - a DynamoDB query result
+ * @property {Array.<T>} Items - the returned items
+ * @property {number} Count - the number of items returned
+ * @property {number} ScannedCount - the number of items scanned before applying any filter
+ * @property {Object|undefined} [LastEvaluatedKey] - the last evaluated key (if any) to be used to get next "page"
+ * @property {ConsumedCapacity|undefined} [ConsumedCapacity] - the capacity units consumed by the getItem operation (if requested)
+ */
+
+/**
+ * @typedef {Object} ConsumedCapacity - the capacity units consumed by an operation
+ */

No alert changes

Improved metrics

Total package byte prevSize

446088

increased by1.89%

Lines of code

6356

increased by1.15%

Number of lines in readme file

705

increased by2.47%

Worsened metrics

Number of low supply chain risk alerts

84

increased by23.53%

No dependency changes