@handy-common-utils/aws-utils

AWS related utilities

Usage no npm install needed!

<script type="module">
  import handyCommonUtilsAwsUtils from 'https://cdn.skypack.dev/@handy-common-utils/aws-utils';
</script>

README

@handy-common-utils/aws-utils

AWS related utilities

Version Downloads/week CI

How to use

First add it as a dependency:

npm install @handy-common-utils/aws-utils

Then you can use it in the code:

import { AwsUtils } from '@handy-common-utils/aws-utils';

const domainNameObjects = await AwsUtils.repeatFetchingItemsByPosition(
  pagingParam => apig.getDomainNames({ limit: 100, ...pagingParam }).promise(),
);

You can either import and use the class as shown above, or you can import individual functions directly like below:

import { repeatFetchingItemsByNextToken, repeatFetchingItemsByMarker, parseArn } from '@handy-common-utils/aws-utils';

API

@handy-common-utils/aws-utils

@handy-common-utils/aws-utils

Table of contents

Classes

Variables

Functions

Variables

FIBONACCI_SEQUENCE

• Const FIBONACCI_SEQUENCE: number[]

FIBONACCI_SEQUENCE_BACKOFFS

• Const FIBONACCI_SEQUENCE_BACKOFFS: number[]

Classes

@handy-common-utils/aws-utils / AwsUtils

Class: AwsUtils

Table of contents

Constructors
Methods

Constructors

constructor

• new AwsUtils()

Methods

dynamodbLocalClientOptions

▸ Static dynamodbLocalClientOptions(endpoint?): Object

Build an object that can be passed into DynamoDB.DocumentClient(...) for DynamoDB Local (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html)

example


const ddbClient = new DynamoDB.DocumentClient(process.env.IS_OFFLINE === 'true' ? AwsUtils.dynamodbLocalClientOptions() : undefined);
Parameters
Name Type Default value Description
endpoint string 'http://localhost:8000' if omitted, the endpoint will be 'http://localhost:8000' which is the default
Returns

Object

the options object

Name Type
accessKeyId string
endpoint string
region string
secretAccessKey string
fibonacciRetryConfigurationOptions

▸ Static fibonacciRetryConfigurationOptions(maxRetries, base?): Pick<ConfigurationOptions, "maxRetries" | "retryDelayOptions">

Generate part of a ConfigurationOptions object having maxRetries as specified and a custom RetryDelayOptions for fibonacci sequence based retry delays.

Parameters
Name Type Default value Description
maxRetries number undefined The maximum amount of retries to perform for a service request.
base number 100 The base number of milliseconds to use in the fibonacci backoff for operation retries. Defaults to 100 ms.
Returns

Pick<ConfigurationOptions, "maxRetries" | "retryDelayOptions">

part of a ConfigurationOptions object that has maxRetries as specified and a customBackoff utilising fibonacci sequence for calculating delays

parseArn

▸ Static parseArn(arn): undefined | null | Arn & { arn: string }

Parse ARN

Parameters
Name Type Description
arn undefined | null | string the ARN string that could be null or undefined
Returns

undefined | null | Arn & { arn: string }

null or undeinfed if the input is null or undefined, or parsed ARN including the original ARN string

promiseWithRetry

▸ Static promiseWithRetry<Result, TError>(operation, backoff?, statusCodes?): Promise<Result>

Perform an AWS operation (returning a Request) with retry. The retry could happen only if the error coming from AWS has property retryable equals to true. If you don't want retryable property to be checked, use PromiseUtils.withRetry(...) directly.

Type parameters
Name Type
Result Result
TError any
Parameters
Name Type Description
operation (attempt: number, previousResult: undefined | Result, previousError: undefined | TError) => { promise: () => Promise<Result> } the AWS operation that returns a Request, such like () => apig.getBasePathMappings({ domainName, limit: 500 })
backoff? number[] | (attempt: number, previousResult: undefined | Result, previousError: undefined | TError) => undefined | number Array of retry backoff periods (unit: milliseconds) or function for calculating them. If retry is desired, before making next call to the operation the desired backoff period would be waited. If the array runs out of elements or the function returns undefined, there would be no further call to the operation. The attempt argument passed into backoff function starts from 2 because only retries need to backoff, so the first retry is the second attempt. If ommitted or undefined, a default backoff array will be used. In case AWS has retryDelay property in the returned error, the larger one between retryDelay and the backoff will be used.
statusCodes? null | (undefined | number)[] Array of status codes for which retry should be done. If ommitted or undefined, only 429 status code would result in a retry. If it is null, status code would not be looked into. If it is an empty array, retry would never happen.
Returns

Promise<Result>

result coming out from the last attempt

repeatFetchingItemsByMarker

▸ Static repeatFetchingItemsByMarker<T>(itemsFieldName, fetchItemsByMarker): Promise<T[]>

Fetch items by Marker repeatedly. This function is useful for client side pagination when the response from AWS API contains NextMarker fields.

example


const topics = await AwsUtils.repeatFetchingItemsByNextToken<SNS.Topic>('Topics',
  pagingParam => sns.listTopics({...pagingParam}).promise(),
);
Type parameters
Name Description
T type of the items returned by AWS API
Parameters
Name Type Description
itemsFieldName string name of the field containing returned items in AWS API response
fetchItemsByMarker (parameter: { Marker?: string }) => Promise<Object> the function for fetching items by Marker
Returns

Promise<T[]>

all items fetched

repeatFetchingItemsByNextToken

▸ Static repeatFetchingItemsByNextToken<T>(itemsFieldName, fetchItemsByNextToken): Promise<T[]>

Fetch items by NextToken repeatedly. This function is useful for client side pagination when the response from AWS API contains NextToken fields.

example


const topics = await AwsUtils.repeatFetchingItemsByNextToken<SNS.Topic>('Topics',
  pagingParam => sns.listTopics({...pagingParam}).promise(),
);
Type parameters
Name Description
T type of the items returned by AWS API
Parameters
Name Type Description
itemsFieldName string name of the field containing returned items in AWS API response
fetchItemsByNextToken (parameter: { NextToken?: string }) => Promise<Object> the function for fetching items by NextToken
Returns

Promise<T[]>

all items fetched

repeatFetchingItemsByPosition

▸ Static repeatFetchingItemsByPosition<T>(fetchItemsByPosition): Promise<T[]>

Fetch items by position repeatedly. This function is useful for client side pagination when the response from AWS API contains position and items fields.

example


const domainNameObjects = await AwsUtils.repeatFetchingItemsByPosition(
  pagingParam => apig.getDomainNames({limit: 500, ...pagingParam}).promise(),
);
Type parameters
Name Description
T type of the items returned by AWS API
Parameters
Name Type Description
fetchItemsByPosition (parameter: { position?: string }) => Promise<Object> the function for fetching items by position
Returns

Promise<T[]>

all items fetched

withRetry

▸ Static withRetry<Result, TError>(operation, backoff?, statusCodes?): Promise<Result>

Perform an AWS operation (returning a Promise) with retry. The retry could happen only if the error coming from AWS has property retryable equals to true. If you don't want retryable property to be checked, use PromiseUtils.withRetry(...) directly.

Type parameters
Name Type
Result Result
TError any
Parameters
Name Type Description
operation (attempt: number, previousResult: undefined | Result, previousError: undefined | TError) => Promise<Result> the AWS operation that returns a Promise, such like () => apig.getBasePathMappings({ domainName, limit: 500 }).promise()
backoff number[] | (attempt: number, previousResult: undefined | Result, previousError: undefined | TError) => undefined | number Array of retry backoff periods (unit: milliseconds) or function for calculating them. If retry is desired, before making next call to the operation the desired backoff period would be waited. If the array runs out of elements or the function returns undefined or either the array or the function returns a negative number, there would be no further call to the operation. The attempt argument passed into backoff function starts from 2 because only retries need to backoff, so the first retry is the second attempt. If ommitted or undefined, a default backoff array will be used. In case AWS has retryDelay property in the returned error, the larger one between retryDelay and the backoff will be used.
statusCodes null | (undefined | number)[] Array of status codes for which retry should be done. If ommitted or undefined, only 429 status code would result in a retry. If it is null, status code would not be looked into. If it is an empty array, retry would never happen.
Returns

Promise<Result>

result coming out from the last attempt