@aws-lambda-powertools/commons/lib/esm/envUtils.d.ts

A shared utility package for Powertools for AWS Lambda (TypeScript) libraries

import type { GetBooleanFromEnvOptions, GetNumberFromEnvOptions, GetStringFromEnvOptions } from './types/envUtils.js';
/**
 * Get a string from the environment variables.
 *
 * @example
 * ```ts
 * import { getStringFromEnv } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const myEnvVar = getStringFromEnv({
 *   key: 'MY_ENV_VAR',
 *   errorMessage: 'MY_ENV_VAR is required for this function',
 * });
 * ```
 *
 * By default, the value is trimmed and always required.
 *
 * You can also provide a default value, which will be returned if the environment variable is not set instead of throwing an error.
 *
 * @example
 * ```ts
 * import { getStringFromEnv } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const myEnvVar = getStringFromEnv({
 *   key: 'MY_ENV_VAR',
 *   defaultValue: 'defaultValue',
 * });
 * ```
 *
 * @param options - The options for getting the string.
 * @param options.key - The key of the environment variable.
 * @param options.defaultValue - Optional default value to return if the environment variable is not set.
 * @param options.errorMessage - Optional error message to throw if the environment variable is not set and no default value is provided. Defaults to `"Environment variable <key> is required"`.
 */
declare const getStringFromEnv: ({ key, defaultValue, errorMessage, }: GetStringFromEnvOptions) => string;
/**
 * Get a number from the environment variables.
 *
 * @example
 * ```ts
 * import { getNumberFromEnv } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const myEnvVar = getNumberFromEnv({
 *   key: 'MY_ENV_VAR',
 *   errorMessage: 'MY_ENV_VAR is required for this function',
 * });
 * ```
 *
 * By default, the value is trimmed before being converted to a number and always required.
 *
 * You can also provide a default value, which will be returned if the environment variable is not set instead of throwing an error.
 *
 * @example
 * ```ts
 * import { getNumberFromEnv } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const myEnvVar = getNumberFromEnv({
 *   key: 'MY_ENV_VAR',
 *   defaultValue: 42,
 * });
 * ```
 *
 * @param options - The options for getting the number.
 * @param options.key - The key of the environment variable.
 * @param options.defaultValue - The default value to return if the environment variable is not set.
 * @param options.errorMessage - Optional error message to throw if the environment variable is not set and no default value is provided. Defaults to `"Environment variable <key> is required"`.
 */
declare const getNumberFromEnv: ({ key, defaultValue, errorMessage, }: GetNumberFromEnvOptions) => number;
/**
 * Get a boolean from the environment variables.
 *
 * @example
 * ```ts
 * 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',
 * });
 * ```
 *
 * By default, the value is trimmed before being converted to a boolean and always required.
 *
 * You can also provide a default value, which will be returned if the environment variable is not set instead of throwing an error.
 *
 * @example
 * ```ts
 * import { getBooleanFromEnv } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const myEnvVar = getBooleanFromEnv({
 *   key: 'MY_ENV_VAR',
 *   defaultValue: true,
 * });
 * ```
 *
 * By default, the value is parsed as a boolean. You can also provide an option to extend the parsing of the boolean value to include common string representations.
 *
 * @example
 * ```ts
 * import { getBooleanFromEnv } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const myEnvVar = getBooleanFromEnv({
 *   key: 'MY_ENV_VAR',
 *   defaultValue: true,
 *   extendedParsing: true,
 * });
 * ```
 *
 * The following values are considered `true`:
 * - `"true"`
 * - `"1"`
 * - `"yes"`
 * - `"on"`
 * - `"y"`
 *
 * The following values are considered `false`:
 * - `"false"`
 * - `"0"`
 * - `"no"`
 * - `"off"`
 * - `"n"`
 *
 * @param options - The options for getting the boolean.
 * @param options.key - The key of the environment variable.
 * @param options.defaultValue - The default value to return if the environment variable is not set.
 * @param options.errorMessage - Optional error message to throw if the environment variable is not set and no default value is provided. Defaults to `"Environment variable <key> is required"`.
 * @param options.extendedParsing - Whether to extend the parsing of the boolean value to include common string representations like `'1'`, `'y'`, `'yes'`, `'t'`, `'true'`, `'on'` for `true` and `'0'`, `'n'`, `'no'`, `'f'`, `'false'`, `'off'` for `false`.
 */
declare const getBooleanFromEnv: ({ key, defaultValue, errorMessage, extendedParsing, }: GetBooleanFromEnvOptions) => boolean;
/**
 * Check if the current invocation is running in a development environment.
 *
 * This is determined by the `POWERTOOLS_DEV` environment variable.
 *
 * @example
 * ```ts
 * import { isDevMode } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const isDev = isDevMode();
 * ```
 */
declare const isDevMode: () => boolean;
/**
 * Get the service name from the environment variables.
 *
 * This is determined by the `POWERTOOLS_SERVICE_NAME` environment variable.
 *
 * @example
 * ```ts
 * import { getServiceName } from '@aws-lambda-powertools/commons/utils/env';
 *
 * const serviceName = getServiceName();
 * ```
 */
declare const getServiceName: () => string;
/**
 * Get the AWS X-Ray Trace data from the environment variable.
 *
 * The method parses the environment variable `_X_AMZN_TRACE_ID` and returns an object with the key-value pairs.
 */
declare const getXrayTraceDataFromEnv: () => Record<string, string> | undefined;
/**
 * Determine if the current invocation is part of a sampled X-Ray trace.
 *
 * The AWS X-Ray Trace data available in the environment variable has this format:
 * `Root=1-5759e988-bd862e3fe1be46a994272793;Parent=557abcec3ee5a047;Sampled=1`,
 */
declare const isRequestXRaySampled: () => boolean;
/**
 * Get the value of the `_X_AMZN_TRACE_ID` environment variable.
 *
 * The AWS X-Ray Trace data available in the environment variable has this format:
 * `Root=1-5759e988-bd862e3fe1be46a994272793;Parent=557abcec3ee5a047;Sampled=1`,
 *
 * The actual Trace ID is: `1-5759e988-bd862e3fe1be46a994272793`.
 */
declare const getXRayTraceIdFromEnv: () => string | undefined;
export { getStringFromEnv, getNumberFromEnv, getBooleanFromEnv, isDevMode, getServiceName, getXrayTraceDataFromEnv, isRequestXRaySampled, getXRayTraceIdFromEnv, };
//# sourceMappingURL=envUtils.d.ts.map