feat(commons): environment variable helpers

[dreamorosi]

Summary

Changes

Please provide a summary of what's being changed

This PR adds new zero-dependency functional utilities to read and parse environment variables.

Customers can read and cast environment variables into string, number, and boolean using the respective helpers.

By default, the environment variable is considered required, and the function will throw an error if not present.

import { getStringFromEnv } from '@aws-lambda-powertools/commons/utils/env';

const myEnvVar = getStringFromEnv({
  key: 'MY_ENV_VAR',
});

Customers can customize the error message thrown by the helper by passing an optional errorMessage parameter.

import { getBooleanFromEnv } from '@aws-lambda-powertools/commons/utils/env';

const myEnvVar = getBooleanFromEnv({
  key: 'MY_ENV_VAR',
  errorMessage: 'MY_ENV_VAR is required for this function',
});

Alternatively, if the env variable is optional, they can also provide a default fallback value that will be used if the env variable is not present.

import { getNumberFromEnv } from '@aws-lambda-powertools/commons/utils/env';

const myEnvVar = getNumberFromEnv({
  key: 'MY_ENV_VAR',
  defaultValue: 42,
});

The PR also adds a few higher-level utilities to read slightly more complex values from environment variables.

For example, getTruthyBooleanFromEnv and getFalsyBooleanFromEnv respectively allow customers to read values like 1, y, yes, on, true, 0, n, no, off, false and cast them to their corresponding boolean values.

import {
  getTruthyBooleanFromEnv,
  getFalsyBooleanFromEnv
} from '@aws-lambda-powertools/commons/utils/env';

process.env.MY_ENV_VAR = 'on';
const myEnvVar = getTruthyBooleanFromEnv({
  key: 'MY_ENV_VAR',
});
// ^ true

process.env.MY_ENV_VAR = 'no';
const myEnvVar = getFalsyBooleanFromEnv({
  key: 'MY_ENV_VAR',
});
// ^ true

Likewise, the isDevMode helper allows customers to detect if their application is running in a development environment based on the POWERTOOLS_DEV env variable, and the getServiceName one retrieves the value of the POWERTOOLS_SERVICE_NAME one.

Finally, the getXrayTraceDataFromEnv, isRequestXRaySampled, and getXRayTraceIdFromEnv all read the _X_AMZN_TRACE_ID env variable and extract/return different kind of information from it.

While this work comes from a feature request (#3159) most of the advantage to customers will come in the form of smaller utilities over time, since we'll be able to use these helpers across other Powertools for AWS utilities and replace the existing EnvironmentVariablesService class-based model which is extremely verbose and requires props drilling if you want to access env variables deep into an inheritance stack.

For Logger, Tracer, and Metrics we'll migrate to these utilities in the next major version while for other utilities we'll evaluate on a case-by-case basis. New utilities should use these helpers since the beginning.

Please add the issue number below, if no issue is present the PR might get blocked and not be reviewed

Issue number: closes #3159

---

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.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud