Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(parameters): stronger types for SSM getParameter #1387

Merged
merged 5 commits into from
Apr 5, 2023

Conversation

dreamorosi
Copy link
Contributor

@dreamorosi dreamorosi commented Mar 28, 2023

Description of your changes

Note
To aid with the review I have prepared this TypeScript playground that contains a simplified (but equivalent) version of the changes included in this PR. Use it to see the concepts described below applied to code & understand how the return types behave.

As discussed in the linked issue, the return types for the SSMProvider part of the Parameters utility are 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 types types for the getParameter(), getParameters(), and getParametersByName() functions as well as their class-based corespondents (i.e. SSMProvider.get(), etc.).

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 always be a string.

We can apply a similar logic to both single and multiple values retrieval, with the only difference that in the latter case the return type will always be nested inside an object: i.e. getParameters('/my/path') (aka no transform) will always yield an object that has strings as both keys and values (Record<string, string>):

{
  'my/path/a': 'foo',
  'my/path/b': 'bar',
}

In the case of objects (transform: 'json'), I have opted to use unknown over any, in an effort to nudge users to not typecast indiscriminately but instead use type guards like:

const isObjectWNumbers = (
    obj: Record<string, unknown> | unknown
): obj is Record<string, number> => obj ? Object.values(obj).every((el) => typeof el === 'number') : false;

which can help TypeScript to narrow down types, like:

async function getParametersObjectsNumbers(path: string): Promise<Record<string, number>> {
    const values = await getParameter('my/param', { transform: 'json' });
    if (isObjectWNumbers(values)) return values;
    else throw new Error('❌');
}

There are however still 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 any of the SSM methods like so:

const value = getParameter<number>('my/param', { transform: 'json' });
// OR
const objValue = getParameters<Record<string, number>>('my/path', { transform: 'json' });

In the first 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.

Likewise, in the second example, the objValue constant will have Record<string, Record<string, number>>, i.e.:

{
  'my/path/a': {
    foo: 1,
  },
  'my/path/b': {
    bar: 2
  },
}

Notice that in the second case we are not passing the full Record<string, xxx>> but only the inner type. This is because in the case of getParameters we are always returning an object that has keys (of type string) that correspond to the name/path of the parameter and as values the actual values. This allows users to specify only the type of the actual value and avoid unnecessary boilerplate.

Once merged this PR closes #1386

Note
If this PR is merged as-is, I'll open a series of issues to apply similar changes to all Parameters providers as well as adding a new section to the docs that explains the behavior above.

Related issues, RFCs

Issue number: #1386

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.

@dreamorosi dreamorosi self-assigned this Mar 28, 2023
@dreamorosi dreamorosi linked an issue Mar 28, 2023 that may be closed by this pull request
2 tasks
@pull-request-size pull-request-size bot added the size/M PR between 30-99 LOC label Mar 28, 2023
@github-actions github-actions bot added the feature PRs that introduce new features or minor changes label Mar 28, 2023
@pull-request-size pull-request-size bot added size/L PRs between 100-499 LOC and removed size/M PR between 30-99 LOC labels Mar 29, 2023
@dreamorosi dreamorosi force-pushed the 1386-improve-return-types-for-ssm-parameters branch from 514abf8 to e87c89f Compare March 29, 2023 21:16
@dreamorosi dreamorosi marked this pull request as ready for review March 30, 2023 17:08
@dreamorosi dreamorosi requested a review from am29d March 30, 2023 17:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature PRs that introduce new features or minor changes size/L PRs between 100-499 LOC
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Feature request: improve return types for SSM Parameters
2 participants