Expose typed final response in WaiterResult

[everett1992]

Waiters should expose the final response in a typed value.
Waiters return WaiterResult which has reason?: any and experimentally that is the final response, but I can't find clear documentation that that's a guarantee, and don't want to cast or validate the value myself.

Seems like this should be generic WaiterResult where T is the possible reason values, or WaiterResult could be a discriminated union covering the different (state, reason) combinations.

[everett1992]

I'd like more documentation on waiters as well.

I've read the smithy docs but that doesn't explain how the javascript waiter behaves.
https://smithy.io/2.0/additional-specs/waiters.html#waiter-retries

For example it wasn't clear if a waiter would return with state TIMEOUT, ABORTED, or FAILED, or if it throws an error in each of those cases. Reading the code I realized there's waitFor* and waitUntil* the latter throws errors on != success, the former returns any state with reason: exception.

https://aws.amazon.com/blogs/developer/waiters-in-modular-aws-sdk-for-javascript/