@aws-sdk/util-waiter

What is @aws-sdk/util-waiter?

@aws-sdk/util-waiter is a utility package in the AWS SDK for JavaScript that provides functionality to wait for a resource to reach a desired state. This is particularly useful for operations that are asynchronous and may take some time to complete, such as creating or deleting AWS resources.

What are @aws-sdk/util-waiter's main functionalities?

Wait for a resource to reach a desired state

This feature allows you to wait until a DynamoDB table exists. The `waitUntilTableExists` function polls the `DescribeTableCommand` until the table reaches the 'ACTIVE' state or the maximum wait time is reached.

const { DynamoDBClient, DescribeTableCommand } = require('@aws-sdk/client-dynamodb');
const { waitUntilTableExists } = require('@aws-sdk/util-waiter');

const client = new DynamoDBClient({ region: 'us-west-2' });
const params = { TableName: 'my-table' };

const run = async () => {
  try {
    const result = await waitUntilTableExists({ client, maxWaitTime: 300 }, { TableName: 'my-table' });
    console.log('Table exists:', result);
  } catch (error) {
    console.error('Error waiting for table to exist:', error);
  }
};

run();

Custom waiters

This feature allows you to create custom waiters for any AWS resource. In this example, a custom waiter is created to wait until an EC2 instance is in the 'running' state.

const { EC2Client, DescribeInstancesCommand } = require('@aws-sdk/client-ec2');
const { createWaiter, WaiterState } = require('@aws-sdk/util-waiter');

const client = new EC2Client({ region: 'us-west-2' });

const checkInstanceRunning = async () => {
  const command = new DescribeInstancesCommand({ InstanceIds: ['i-1234567890abcdef0'] });
  const result = await client.send(command);
  const instance = result.Reservations[0].Instances[0];
  return instance.State.Name === 'running' ? { state: WaiterState.SUCCESS } : { state: WaiterState.RETRY };
};

const run = async () => {
  try {
    const result = await createWaiter({ client, maxWaitTime: 300 }, checkInstanceRunning);
    console.log('Instance is running:', result);
  } catch (error) {
    console.error('Error waiting for instance to run:', error);
  }
};

run();

Other packages similar to @aws-sdk/util-waiter

promise-retry

The `promise-retry` package provides a way to retry a function that returns a promise until it succeeds or a maximum number of retries is reached. Unlike @aws-sdk/util-waiter, it is not specific to AWS resources and can be used for any asynchronous operation.

async-retry

The `async-retry` package is another utility for retrying asynchronous operations. It allows you to specify retry strategies and is more flexible in terms of configuration compared to @aws-sdk/util-waiter, but it does not provide built-in support for AWS resource states.

README

@aws-sdk/util-waiter

An internal package

Usage

You probably shouldn't, at least directly.

Changelog

3.341.0 (2023-05-26)

Bug Fixes

• util-retry: make standard retry tokens immutable (#4755) (d666720)

Features

• client-connect: Documentation update for a new Initiation Method value in DescribeContact API (84ca849)
• client-iot-wireless: Add Multicast Group support in Network Analyzer Configuration. (0276e59)
• client-sagemaker: Added ml.p4d and ml.inf1 as supported instance type families for SageMaker Notebook Instances. (09963fb)
• clients: update client endpoints as of 2023-05-26 (c3b81bc)