feat(parameters): add adaptive types to SecretsProvider

[dreamorosi]

Description of your changes

As discussed in the linked issue, the return types for the SecretsProvider part of the Parameters utility were fairly generic and could be improved by applying some heuristics based on the method used and some of the parameters passed. In addition to that, we could also provide a way for users to explicitly set the return type when they know the shape of the values they are retrieving.

This PR introduces new adaptive types for the getSecret() function as well as its class-based corespondent SecretsProvider.get()`.

The new types use generics and modify the return type of the functions/methods based on the arguments passed to them or based on an explicitly set type.

For instance, if users pass transform: json, then we can assume that the return type should be an object (Record<K, V>). Conversely, if no transform or a binary (base64) transform is applied, the result will be a string.

Finally, if the user doesn't specify any transform then, given tht SecretsManager is able to store both SecretString and SecretBinary data types, then we can only narrow down the return type to one of string or Uint8Array.

There are however also cases in which users might know more about the values they are retrieving than the compiler does, and for those instances this PR introduces the ability to specify the return type while using either the function or method like so:

const value = getSecret<number>('my-secret', { transform: 'json' });

In the example above the value constant will have type number, this is because the user has specified a type and so this will take precedence over any type-heuristic we do behind the scenes.

Note
This PR is part of a series that covers the same topic for all Parameters providers. Once this work is done I'll open I'll add a new section to the docs that explains the behavior above.

Once merged this PR closes #1409

Related issues, RFCs

Issue number: #1409

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• I have made corresponding changes to the examples
• My changes generate no new warnings
• The code coverage hasn't decreased
• I have added tests that prove my change is effective and works
• New and existing unit tests pass locally and in Github Actions
• Any dependent changes have been merged and published
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.