aws-core-utils v8.1.3
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 generating
handler
functions for and for working with AWS Lambdas that are exposed via API Gateway- For other AWS Lambdas that are NOT exposed via API Gateway, instead use the
aws-core-utils/other-lambdas
module
- For other AWS Lambdas that are NOT exposed via API Gateway, instead use the
- Utilities for generating
- other-lambdas.js
- Utilities for generating
handler
functions for and for working with "other" AWS Lambdas that are NOT exposed via API Gateway and IDEALLY NOT triggered by a Kinesis or DynamoDB stream event source mapping- For API Gateway exposed AWS Lambdas, instead use the
aws-core-utils/api-lambdas
module - For Kinesis triggered AWS Lambdas, instead consider using the
kinesis-stream-consumer
module - For DynamoDB triggered AWS Lambdas, instead consider using the
dynamodb-stream-consumer
module
- For API Gateway exposed AWS Lambdas, instead use the
- Utilities for generating
- arns.js
- Utilities for working with Amazon Resource Names (ARNs)
- aws-errors.js
- 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
- A module-scope cache of AWS.DynamoDB.DocumentClient instances by region for Lambda.
- dynamodb-doc-client-utils.js
- Utilities for working with AWS DynamoDB.DocumentClient.
- dynamodb-utils.js
- Utilities for working with AWS DynamoDB.
- kinesis-cache.js
- A module-scope cache of AWS.Kinesis instances by region for Lambda.
- kms-cache.js
- A module-scope cache of AWS.KMS instances by region for Lambda usage.
- kms-utils.js
- Utilities to simplify working with AWS.KMS instances.
- lambda-cache.js
- A module-scope cache of AWS.Lambda instances by region for use within Lambda functions.
- lambda-utils.js
- Utilities to simplify working with an AWS.Lambda instance
- lambdas.js
- 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.
- 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 configuration of stage handling.
- Configurable and default functions for generating stage-qualified stream and resource names.
- Configurable and default functions for extracting stages from stage-qualified stream and resource names.
- stream-events.js
- Utilities for extracting information from AWS Kinesis and AWS DynamoDB stream events.
This module is exported as a Node.js module.
Installation
Using npm:
$ {sudo -H} npm i -g npm$ npm i --save aws-core-utils
In Node.js:
- To use the
api-lambdas
module within your API Gateway exposed Lambda:
const apiLambdas = ;const isInstanceOf = isInstanceOf;const appErrors = ;const BadRequest = appErrorsBadRequest; const createContext = {}; // or your own pre-configured context // To configure your handler to use Lambda Proxy integration and custom default response headersconst createOptions = ; // with whatever options you want to use to configure your handler, stage handling, logging, custom settings, ... const createSettings = undefined; // or whatever settings object you want to use to configure your handler, stage handling, logging, custom settings, ... { /* ... */ } // implement and name your own function that does the actual work const opts = logRequestResponseAtLogLevel: 'INFO' invalidRequestMsg: 'Invalid request ...' failureMsg: 'Failed to ...' successMsg: 'Finished ...'; // Simplest approach - generate your API Gateway exposed Lambda's handler functionexportshandler = apiLambdas; // OR ... develop your own Lambda handler function (e.g. simplistic example below - see apiLamdas.generateHandlerFunction for a MUCH better version)exports { const opts = // logRequestResponseAtLogLevel: 'info', // invalidRequestMsg: 'Invalid request ...', // failureMsg: 'Failed to ...', // successMsg: 'Finished ...' ; // Configure a standard context let context = {}; try context = apiLambdas; // ... execute Lambda specific code passing the context to your functions as needed ; 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] context; apiLambdas; }; // ALTERNATIVE handler options for `succeedLambdaCallback` & `failLambdaCallback`: // Fail your Lambda callback: using Lambda Proxy integration; using a custom response header; and map the error to one of a specified set of HTTP status codescontexthandler = // simplistic example - should rather be set through an appropriate `context-options.json` file useLambdaProxy: true defaultHeaders: MyCustomHeader: 'MyCustomHeaderValue' allowedHttpStatusCodes: 400 404 418 500 508;apiLambdas;
- To use the AWS ARN utilities
const arns = ; const arnComponent = arns;const arnPartition = arns;const arnService = arns;const arnRegion = arns;const arnAccountId = arns;const arnResources = arns; ;
- To use the AWS errors utilities
const awsErrors = ; ;
- To use the
contexts.js
module:
// 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) // ALTERNATIVELY if you need the logic of the configureStandardContext function for custom purposesconst contexts = ;const context = {};const standardOptions = ; // 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; // If you need the logic of the configureCustomSettings function, which is used by configureStandardContext, for other purposesconst myCustomSettings = myCustomSetting1: 1 myCustomSetting2: 2 {};console;const myCustomOptions = ;contexts;console;
- To use the DynamoDB.DocumentClient cache to configure and cache an AWS DynamoDB.DocumentClient instance per region
const dynamoDBDocClientCache = ; // Preamble to create a context and configure logging on the contextconst context = {};const logging = ;logging; // or your own custom logging configuration (see logging-utils README.md) // Define the DynamoDB.DocumentClient's constructor options that you want to use, e.g.const dynamoDBDocClientOptions = // See http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#constructor-property // and http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#constructor-property maxRetries: 0 // ...; // To create and cache a new AWS DynamoDB.DocumentClient instance with the given DynamoDB.DocumentClient constructor // options for either the current region or the region specified in the given options OR reuse a previously cached // DynamoDB.DocumentClient instance (if any) that is compatible with the given optionsconst dynamoDBDocClient = dynamoDBDocClientCache; // To configure a new AWS.DynamoDB.DocumentClient instance (or re-use a cached instance) on a context dynamoDBDocClientCache;console; // To get a previously set or configured AWS DynamoDB.DocumentClient instance for the current AWS regionconst dynamoDBDocClient1 = dynamoDBDocClientCache;// ... or for a specified regionconst dynamoDBDocClient2 = dynamoDBDocClientCache; // To get the original options that were used to construct a cached AWS DynamoDB.DocumentClient instance for the current or specified AWS regionconst optionsUsed1 = dynamoDBDocClientCache;const optionsUsed2 = dynamoDBDocClientCache; // To delete and remove a cached DynamoDB.DocumentClient instance from the cacheconst deleted = dynamoDBDocClientCache; ;
- To use the Kinesis cache to configure and cache an AWS Kinesis instance per region
const kinesisCache = ; // Preamble to create a context and configure logging on the contextconst context = {};const logging = ;logging; // or your own custom logging configuration (see logging-utils README.md) // Define the Kinesis constructor options that you want to use, e.g.const kinesisOptions = // See http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Kinesis.html#constructor-property for full details maxRetries: 0 // ...; // To create and cache a new AWS Kinesis instance with the given Kinesis constructor options for either the current // region or the region specified in the given options OR reuse a previously cached Kinesis instance (if any) that is // compatible with the given optionsconst kinesis = kinesisCache; // To configure a new AWS.Kinesis instance (or re-use a cached instance) on a context kinesisCache;console; // To get a previously set or configured AWS Kinesis instance for the current AWS regionconst kinesis1 = kinesisCache;// ... or for a specified regionconst kinesis2 = kinesisCache; // To get the original options that were used to construct a cached AWS Kinesis instance for the current or specified AWS regionconst optionsUsed1 = kinesisCache;const optionsUsed2 = kinesisCache; // To delete and remove a cached Kinesis instance from the cacheconst deleted = kinesisCache; ;
- To use the KMS cache to configure and cache an AWS KMS instance per region
const kmsCache = ; // Preamble to create a context and configure logging on the contextconst context = {};const logging = ;logging; // or your own custom logging configuration (see logging-utils README.md) // Define the KMS constructor options that you want to use, e.g.const kmsOptions = // See http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/KMS.html#constructor-property for full details maxRetries: 0 // ...; // To create and cache a new AWS KMS instance with the given KMS constructor options for either the current // region or the region specified in the given options OR reuse a previously cached KMS instance (if any) that is // compatible with the given optionsconst kms = kmsCache; // To configure a new AWS.KMS instance (or re-use a cached instance) on a context kmsCache;console; // To get a previously set or configured AWS KMS instance for the current AWS regionconst kms1 = kmsCache;// ... or for a specified regionconst kms2 = kmsCache; // To get the original options that were used to construct a cached AWS KMS instance for the current or specified AWS regionconst optionsUsed1 = kmsCache;const optionsUsed2 = kmsCache; // To delete and remove a cached KMS instance from the cacheconst deleted = kmsCache; ;
- To use the AWS.KMS utilities
const kmsUtils = ; const kms = region: 'eu-west-1'; // or better yet use kms-cache module as above // Preamble to create a context and configure logging on the contextconst logging = ;const logger = logging; // or your own custom logging configuration (see logging-utils README.md) const accountId = 'XXXXXXXXXXXX'; // use your AWS account IDconst kmsKeyAlias = 'aws/lambda'; // or use your own key aliasconst keyId = `arn:aws:kms:us-west-2::alias/`; // To encrypt plaintext using KMS:const plaintext = 'Shhhhhhhhhhhhhhh'; // use your own plaintextkmsUtils ; // To decrypt ciphertext using KMS:const ciphertextBase64 = '...'; // use your own ciphertextkmsUtils ; // To encrypt plaintext using KMS:const encryptParams = KeyId: keyId Plaintext: plaintext;kmsUtils ; // To decrypt ciphertext using KMS:const decryptParams = CiphertextBlob: ciphertextBase64 'base64';kmsUtils ;
- To use the Lambda cache to configure and cache an AWS Lambda instance per region
const lambdaCache = ; // Preamble to create a context and configure logging on the contextconst context = {};const logging = ;logging; // or your own custom logging configuration (see logging-utils README.md) // Define the Lambda constructor options that you want to use, e.g.const lambdaOptions = // See http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Lambda.html#constructor-property for full details maxRetries: 0 // ...; // To create and cache a new AWS Lambda instance with the given Lambda constructor options for either the current // region or the region specified in the given options OR reuse a previously cached Lambda instance (if any) that is // compatible with the given optionsconst lambda = lambdaCache; // To configure a new AWS.Lambda instance (or re-use a cached instance) on a context lambdaCache;console; // To get a previously set or configured AWS Lambda instance for the current AWS regionconst lambda1 = lambdaCache;// ... or for a specified regionconst lambda2 = lambdaCache; // To get the original options that were used to construct a cached AWS Lambda instance for the current or specified AWS regionconst optionsUsed1 = lambdaCache;const optionsUsed2 = lambdaCache; // To delete and remove a cached Lambda instance from the cacheconst deleted = lambdaCache; ;
- To use the AWS.Lambda utilities
const lambdaUtils = ; const lambda = region: 'eu-west-1'; // or better yet use lambda-cache module as above // To list the event source mappings on your Lambda functionconst params = FunctionName: 'my-lambda-function';lambdaUtils ; // To update an event source mapping on your Lambda functionconst params2 = FunctionName: 'my-lambda-function' UUID: uuid BatchSize: 99;lambdaUtils ; // To disable an event source mapping on your Lambda functionlambdaUtils ;
- To use the Lambda utilities
const lambdas = ; // To resolve the Lambda alias from an AWS Lambda contextconst alias = lambdas; // To extract other details from an AWS Lambda contextconst functionName = lambdas;const functionVersion = lambdas;const functionNameVersionAndAlias = lambdas;const invokedFunctionArn = lambdas;const invokedFunctionArnFunctionName = lambdas; ;
- To get the current AWS region & configure it on a context
const regions = ; // To get the current AWS region of your Lambdaconst region = regions; // To configure a context with the current AWS regionconst context = {};const failFast = true;regions;;
- To use the stage utilities
// To configure stage-handling, which determines the behaviour of the functions numbered 1 to 6 belowconst stages = ;const settings = undefined; // ... or your own custom settingsconst options = ; // ... or your own custom options // ... EITHER using the default stage handling configuration and default logging configuration stages; // ... OR using the default stage handling configuration and default logging configuration partially customised via stageHandlingOptions, otherSettings & otherOptionsconst stageHandlingOptions = stageHandlingOptions; // example ONLY - use your own custom stage handling options if neededconst otherSettings = undefined; // or to configure your own underlying logger use: const otherSettings = {loggingSettings: {underlyingLogger: myCustomLogger}};const otherOptions = ; // example ONLY - use your own custom standard options fileconst forceConfiguration = false;stages; // ... OR using your own custom stage-handling configurationconst stageHandlingSettings = stages;// Optionally override the default stage handling functions with your own custom functions// stageHandlingSettings.customToStage = undefined;// stageHandlingSettings.convertAliasToStage = stages.DEFAULTS.convertAliasToStage;// stageHandlingSettings.injectStageIntoStreamName = stages.DEFAULTS.toStageSuffixedStreamName;// stageHandlingSettings.extractStageFromStreamName = stages.DEFAULTS.extractStageFromSuffixedStreamName;// stageHandlingSettings.injectStageIntoResourceName = stages.DEFAULTS.toStageSuffixedResourceName;// stageHandlingSettings.extractStageFromResourceName = stages.DEFAULTS.extractStageFromSuffixedResourceName;stages; // ... OR using completely customised stage handling settingsconst stageHandlingSettings2 = envStageName: myEnvStageName customToStage: myCustomToStageFunction // or undefined if not needed convertAliasToStage: myConvertAliasToStageFunction // or undefined to knockout using AWS aliases as stages injectStageIntoStreamName: myInjectStageIntoStreamNameFunction extractStageFromStreamName: myExtractStageFromStreamNameFunction streamNameStageSeparator: myStreamNameStageSeparator injectStageIntoResourceName: myInjectStageIntoResourceNameFunction extractStageFromResourceName: myExtractStageFromResourceNameFunction resourceNameStageSeparator: myResourceNameStageSeparator injectInCase: myInjectInCase extractInCase: myExtractInCase defaultStage: myDefaultStage // or undefined;stages; // ... OR using custom stage handling settings and/or options and configuring dependencies at the same timestages; // To check if stage handling is configuredconst configured = stages; // To look up stage handling settings and functionsconst settingName = 'injectInCase'; // example stage handling setting nameconst setting = stages; const functionSettingName = 'convertAliasToStage'; // example stage handling function nameconst fn = stages; // 1. To resolve / derive a stage from an AWS eventconst context = {};const stage = stages; // 2. To configure a context with a resolved stage (uses resolveStage)const failFast = true;stages;; // 3. To extract a stage from a qualified stream nameconst qualifiedStreamName = 'TestStream_PROD';const stage2 = stages;; // assuming default stage handling configuration // 4. To qualify an unqualified stream name with a stageconst unqualifiedStreamName = 'TestStream';const stageQualifiedStreamName = stages;; // assuming default stage handling configuration // 5. To extract a stage from a qualified resource nameconst qualifiedTableName = 'TestTable_QA';const stage3 = stages;; // assuming default stage handling configuration // 6. To qualify an unqualified resource name with a stageconst unqualifiedTableName = 'TestTable';const stageQualifiedResourceName = stages;; // assuming default stage handling configuration
- To use the stream event utilities
const streamEvents = ; // To extract event soure ARNs from AWS events const eventSourceARNs = streamEvents; // To extract Kinesis stream names from AWS events and event recordsconst eventSourceStreamNames = streamEvents;const eventSourceStreamName = streamEvents; // To extract DynamoDB table names from DynamoDB stream event recordsconst dynamoDBEventSourceTableName = streamEvents; // To extract DynamoDB table names and stream timestamps/suffixes from DynamoDB stream event recordsconst tableNameAndStreamTimestamp = streamEvents;const dynamoDBEventSourceTableName1 = tableNameAndStreamTimestamp0;const dynamoDBEventSourceStreamTimestamp = tableNameAndStreamTimestamp1; // Simple checks to validate existance of some of the properties of Kinesis & DynamoDB stream event recordstry streamEvents; streamEvents; streamEvents; catch err // ...
Unit tests
This module's unit tests were developed with and must be run with tape. The unit tests have been tested on Node.js v6.10.3.
Install tape globally if you want to run multiple tests at once:
$ npm install tape -g
Run all unit tests with:
$ npm test
or with tape:
$ tape test/*.js
See the package source for more details.
Changes
See CHANGES.md