@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.55.0 (2022-03-21)

Bug Fixes

• middleware-serde: mark error entry non-enumerable (#3426) (c7cceb5)
• property-provider: copy error properties to ProviderError in from() (#3440) (4377e44)
• property-provider: manually adjust the prototype of *ProviderError (#3445) (134f769)
• scripts: update typescript version in generate-clients (#3454) (f90992a)
• types: remove @internal jsdoc tag from profile types (#3452) (2d7c151)

Features

• clients: update clients as of 03/21/2022 (#3455) (7cd40a5)
• property-provider: memoize() supports force refresh (#3413) (a79f962)
• util-middleware: add normalizeProvider (#3456) (e15b0f5)