Environment Variable Utilities

/**
 * Get a string from the environment variables.
 * By default, the value is trimmed and always required unless a default is provided.
 *
 * @param options - Configuration options
 * @returns The environment variable value as a trimmed string
 * @throws Error if variable not found and no default provided
 */
function getStringFromEnv(options: GetStringFromEnvOptions): string;

interface GetStringFromEnvOptions {
  /** The key of the environment variable */
  key: string;
  /** Optional default value to return if the environment variable is not set */
  defaultValue?: string;
  /** Optional error message to throw if the environment variable is not set and no default provided */
  errorMessage?: string;
}

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

// Required environment variable with custom error message
const apiKey = getStringFromEnv({
  key: 'API_KEY',
  errorMessage: 'API_KEY is required for this function',
});

// With default value
const region = getStringFromEnv({
  key: 'AWS_REGION',
  defaultValue: 'us-east-1',
});

/**
 * Get a number from the environment variables.
 * The value is trimmed before being converted to a number and always required unless a default is provided.
 *
 * @param options - Configuration options
 * @returns The environment variable value as a number
 * @throws Error if variable not found and no default provided
 * @throws TypeError if the value cannot be parsed as a number
 */
function getNumberFromEnv(options: GetNumberFromEnvOptions): number;

interface GetNumberFromEnvOptions {
  /** The key of the environment variable */
  key: string;
  /** Optional default value to return if the environment variable is not set */
  defaultValue?: number;
  /** Optional error message to throw if the environment variable is not set and no default provided */
  errorMessage?: string;
}

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

// Required number with error handling
const timeout = getNumberFromEnv({
  key: 'TIMEOUT_MS',
  errorMessage: 'TIMEOUT_MS must be set',
});

// With default value
const maxRetries = getNumberFromEnv({
  key: 'MAX_RETRIES',
  defaultValue: 3,
});

/**
 * Get a boolean from the environment variables.
 * The value is trimmed before being converted to a boolean and always required unless a default is provided.
 *
 * Standard parsing accepts 'true' and 'false'.
 * Extended parsing accepts: '1', 'y', 'yes', 't', 'true', 'on' for true
 * and '0', 'n', 'no', 'f', 'false', 'off' for false (case-insensitive).
 *
 * @param options - Configuration options
 * @returns The environment variable value as a boolean
 * @throws Error if variable not found and no default provided, or if value is not a valid boolean
 */
function getBooleanFromEnv(options: GetBooleanFromEnvOptions): boolean;

interface GetBooleanFromEnvOptions {
  /** The key of the environment variable */
  key: string;
  /** Optional default value to return if the environment variable is not set */
  defaultValue?: boolean;
  /** Optional error message to throw if the environment variable is not set and no default provided */
  errorMessage?: string;
  /** Whether to extend parsing to include common string representations ('1', 'yes', 'on', etc.) */
  extendedParsing?: boolean;
}

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

// Standard boolean parsing
const debugMode = getBooleanFromEnv({
  key: 'DEBUG_MODE',
  defaultValue: false,
});

// Extended parsing for flexible input
const isEnabled = getBooleanFromEnv({
  key: 'FEATURE_ENABLED',
  defaultValue: true,
  extendedParsing: true,
});
// Accepts: 'yes', '1', 'on', 'true', etc.

/**
 * Check if the current invocation is running in a development environment.
 * This is determined by the POWERTOOLS_DEV environment variable.
 * Returns false if the variable is not set or cannot be parsed.
 *
 * @returns Boolean indicating if running in development mode
 */
function isDevMode(): boolean;

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

if (isDevMode()) {
  console.log('Running in development mode');
  // Enable additional debugging, verbose logging, etc.
}

/**
 * Get the service name from the environment variables.
 * This is determined by the POWERTOOLS_SERVICE_NAME environment variable.
 * Returns empty string if not set.
 *
 * @returns The service name or empty string
 */
function getServiceName(): string;

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

const serviceName = getServiceName();
console.log('Service:', serviceName);

/**
 * Get the AWS X-Ray Trace data from the lambda RIC async context or the _X_AMZN_TRACE_ID environment variable.
 * Checks the async context first and if that returns undefined, falls back to the environment variable.
 * The method parses the value and returns an object with the key-value pairs.
 *
 * @returns Record containing trace data (Root, Parent, Sampled) or undefined if not available
 */
function getXrayTraceDataFromEnv(): Record<string, string> | undefined;

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

const traceData = getXrayTraceDataFromEnv();
if (traceData) {
  console.log('Trace Root:', traceData.Root);
  console.log('Parent:', traceData.Parent);
  console.log('Sampled:', traceData.Sampled);
}

/**
 * Determine if the current invocation is part of a sampled X-Ray trace.
 * The AWS X-Ray Trace data has format: 'Root=1-xxx;Parent=xxx;Sampled=1'
 * Checks the async context first and if that returns undefined, falls back to the environment variable.
 *
 * @returns Boolean indicating if the request is sampled (Sampled=1)
 */
function isRequestXRaySampled(): boolean;

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

if (isRequestXRaySampled()) {
  console.log('Request is being traced by X-Ray');
  // Add additional tracing information
}

/**
 * AWS X-Ray Trace ID from the lambda RIC async context or the _X_AMZN_TRACE_ID environment variable.
 * Checks the async context first and if that returns undefined, falls back to the environment variable.
 * The AWS X-Ray Trace data has format: 'Root=1-5759e988-bd862e3fe1be46a994272793;Parent=xxx;Sampled=1'
 * The actual Trace ID is: '1-5759e988-bd862e3fe1be46a994272793'
 *
 * @returns The X-Ray trace ID or undefined if not available
 */
function getXRayTraceIdFromEnv(): string | undefined;

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

const traceId = getXRayTraceIdFromEnv();
if (traceId) {
  console.log('Current trace ID:', traceId);
}

/**
 * Check if the AWS_LAMBDA_MAX_CONCURRENCY environment variable is set.
 * This indicates whether the invoke store should be used.
 *
 * @returns Boolean indicating if invoke store should be used
 */
function shouldUseInvokeStore(): boolean;

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

if (shouldUseInvokeStore()) {
  console.log('Using invoke store for context management');
}