RFC: waiters

[ryanblock]

AWS SDK v2 / 3 have the concept of waiters, which are custom implementations that poll an endpoint looking for a specific change. Examples (from their blog, edited for brevity):

const Bucket = 'my-bucket'

// v2
import aws from 'aws-sdk'
const v2Client = new aws.S3(options)
await v2Client.createBucket({ Bucket }).promise()
await v2Client.waitFor('bucketExists', { Bucket });

// v3
import {
  S3Client, CreateBucketCommand, waitUntilBucketExists
} from '@aws-sdk/client-s3'
const v3Client = new S3Client(options)
const command = new CreateBucketCommand({ Bucket })
await v3Client.send(command)
await waitUntilBucketExists({ client: v3Client, maxWaitTime: 60 }, { Bucket })

These are nice, but may perhaps be limiting, and (in my personal opinion) a bit of a funky API. I can imagine an alternative approach consisting of:

• Any method to wait for + parameters
• Conditions to match
• Related options (timeout, etc.)

This approach should in theory allow simple, customizable waiters. In the S3 bucket creation example, maybe it's something like this.

import awsLite from '@aws-lite/client'
const aws = await awsLite(options)
await aws.wait(
  // Method to poll
  aws.S3.HeadBucket,

  // Invocation params
  { Bucket: 'my-bucket' },
  
  // Conditions to match via statusCode, headers, payload properties
  { statusCode: 200 },
  
  // Waiter options
  {
    timeout: 30, // Fail if not completed by timeout in seconds, default 30, max 3600
    frequency: 5, // Polling frequency in seconds, default 5, min 0.1, max 10
  },
)

Then again, perhaps folks would rather just have a pre-built waiter (e.g. waitFor('bucketExists', { Bucket })) instead of specifying their own methods, criteria to match, etc.

Stoked to hear some thoughts on this!