or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

appconfig.mdbase.mddynamodb.mdindex.mdsecrets.mdssm.md
tile.json

tessl/npm-aws-lambda-powertools--parameters

High-level utility library for AWS Lambda functions to retrieve configuration parameters and secrets from AWS services with built-in caching and transformation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-lambda-powertools/parameters@2.29.x

To install, run

npx @tessl/cli install tessl/npm-aws-lambda-powertools--parameters@2.29.0

index.mddocs/

Powertools for AWS Lambda Parameters

High-level utility for retrieving configuration parameters and secrets from AWS services with built-in caching, automatic value transformation, and graceful error handling.

Package Information

  • Package: @aws-lambda-powertools/parameters
  • Install: npm install @aws-lambda-powertools/parameters
  • Peer Dependencies: AWS SDK v3 clients (@aws-sdk/client-ssm, @aws-sdk/client-secrets-manager, @aws-sdk/client-appconfigdata, @aws-sdk/client-dynamodb, @aws-sdk/util-dynamodb)

Quick Start

// ESM imports
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
import { clearCaches, Transform } from '@aws-lambda-powertools/parameters';

// CommonJS
const { getParameter } = require('@aws-lambda-powertools/parameters/ssm');
// Basic usage
export const handler = async () => {
  const parameter = await getParameter('/my/parameter');
  const config = await getParameter('/my/config', { transform: 'json' });
  const secret = await getSecret('my-secret');
  return { parameter, config, secret };
};

Common Options

All get* operations accept these options:

OptionTypeDefaultDescription
maxAgenumber5Cache TTL in seconds. Set to 0 to disable. Env: POWERTOOLS_PARAMETERS_MAX_AGE
forceFetchbooleanfalseSkip cache and fetch latest value
transform'json' | 'binary' | 'auto'undefinedTransform value (json=parse, binary=decode, auto=detect by suffix)
sdkOptionsobjectundefinedAWS SDK command options

Provider-specific options:

  • SSM: decrypt (boolean), recursive (boolean), throwOnTransformError (boolean)
  • Secrets: VersionId, VersionStage via sdkOptions
  • DynamoDB: Custom attribute names (keyAttr, sortAttr, valueAttr)
  • AppConfig: application, environment (required)

Caching

Automatic caching with 5-second default TTL:

  • Each provider maintains separate in-memory cache (Map-based)
  • High-level functions use singleton default provider instances
  • Cache keys include all request parameters
  • Set maxAge: 0 to disable caching
  • Use forceFetch: true to bypass cache once
  • Call clearCaches() to clear all default providers
  • Call provider.clearCache() to clear specific provider

Value Transformation

const Transform = {
  JSON: 'json',     // Parse with JSON.parse
  BINARY: 'binary', // Decode base64 to string
  AUTO: 'auto'      // Detect by suffix (.json, .binary)
} as const;

Transform behavior:

  • 'json': Parses value with JSON.parse
  • 'binary': Decodes base64 binary to string
  • 'auto': Auto-detects based on parameter name suffix
  • throwOnTransformError: false: Continue on transform errors (getMultiple only)

Providers Overview

SSM Parameter Store

Detailed docs

// High-level functions
function getParameter<T>(name: string, options?: SSMGetOptions): Promise<T | undefined>;
function getParameters<T>(path: string, options?: SSMGetMultipleOptions): Promise<Record<string, T> | undefined>;
function getParametersByName<T>(parameters: Record<string, SSMGetParametersByNameOptions>, options?: SSMGetParametersByNameOptions): Promise<SSMGetParametersByNameOutput<T>>;
function setParameter(name: string, options: SSMSetOptions): Promise<number>;

// Provider class
class SSMProvider extends BaseProvider {
  constructor(config?: SSMProviderOptions);
  get<T>(name: string, options?: SSMGetOptions): Promise<T | undefined>;
  getMultiple<T>(path: string, options?: SSMGetMultipleOptions): Promise<Record<string, T> | undefined>;
  getParametersByName<T>(parameters: Record<string, SSMGetParametersByNameOptions>, options?: SSMGetParametersByNameOptions): Promise<SSMGetParametersByNameOutput<T>>;
  set(name: string, options: SSMSetOptions): Promise<number>;
}

Quick example:

import { getParameter, getParameters, SSMProvider } from '@aws-lambda-powertools/parameters/ssm';

const param = await getParameter('/my/param', { decrypt: true });
const params = await getParameters('/my/path', { recursive: true, transform: 'auto' });
const multi = await getParametersByName({ '/p1': {}, '/p2': { transform: 'json' } });
await setParameter('/my/param', { value: 'new-value', overwrite: true });

// Provider instance for custom config
const provider = new SSMProvider({ clientConfig: { region: 'us-west-2' } });
const value = await provider.get('/my/param');

IAM: ssm:GetParameter, ssm:GetParameters, ssm:GetParametersByPath, ssm:PutParameter, kms:Decrypt

Secrets Manager

Detailed docs

// High-level function
function getSecret<T>(name: string, options?: SecretsGetOptions): Promise<T | undefined>;

// Provider class
class SecretsProvider extends BaseProvider {
  constructor(config?: SecretsProviderOptions);
  get<T>(name: string, options?: SecretsGetOptions): Promise<T | undefined>;
}

Quick example:

import { getSecret, SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secret = await getSecret('my-secret');
const creds = await getSecret<{user: string, pass: string}>('db-creds', { transform: 'json' });
const versioned = await getSecret('my-secret', { sdkOptions: { VersionStage: 'AWSPREVIOUS' } });

const provider = new SecretsProvider({ clientConfig: { region: 'us-west-2' } });
const value = await provider.get('my-secret', { maxAge: 3600 });

IAM: secretsmanager:GetSecretValue, kms:Decrypt

Note: getMultiple not supported for Secrets Manager

DynamoDB Provider

Detailed docs

class DynamoDBProvider extends BaseProvider {
  constructor(config: DynamoDBProviderOptions);
  get<T>(name: string, options?: DynamoDBGetOptions): Promise<T | undefined>;
  getMultiple<T>(path: string, options?: DynamoDBGetMultipleOptions): Promise<Record<string, T> | undefined>;
}

Default schema: Partition key id, Sort key sk, Value attribute value

Quick example:

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const provider = new DynamoDBProvider({
  tableName: 'parameters-table',
  keyAttr: 'id',      // optional, default: 'id'
  sortAttr: 'sk',     // optional, default: 'sk'
  valueAttr: 'value'  // optional, default: 'value'
});

const value = await provider.get('my-param');
const values = await provider.getMultiple('my-app', { transform: 'auto' });

IAM: dynamodb:GetItem, dynamodb:Query

Note: No high-level convenience functions, use provider class directly

AppConfig

Detailed docs

// High-level function
function getAppConfig<T>(name: string, options: GetAppConfigOptions): Promise<T | undefined>;

// Provider class
class AppConfigProvider extends BaseProvider {
  constructor(config: AppConfigProviderOptions);
  get<T>(name: string, options?: AppConfigGetOptions): Promise<T | undefined>;
}

Quick example:

import { getAppConfig, AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';

const config = await getAppConfig('my-config', {
  application: 'my-app',  // or set POWERTOOLS_SERVICE_NAME env var
  environment: 'prod',
  transform: 'json'
});

const provider = new AppConfigProvider({
  application: 'my-app',
  environment: 'production'
});
const value = await provider.get('feature-flags', { transform: 'json', maxAge: 600 });

IAM: appconfig:StartConfigurationSession, appconfig:GetLatestConfiguration

Note: getMultiple not supported. Session tokens cached 23h 45m, config values per maxAge.

Base Provider and Utilities

Detailed docs

abstract class BaseProvider {
  constructor(config: BaseProviderConstructorOptions);
  get(name: string, options?: GetOptionsInterface): Promise<unknown>;
  getMultiple(path: string, options?: GetMultipleOptionsInterface): Promise<unknown>;
  addToCache(key: string, value: unknown, maxAge: number): void;
  clearCache(): void;
  hasKeyExpiredInCache(key: string): boolean;
  protected abstract _get(name: string, options?: unknown): Promise<unknown>;
  protected abstract _getMultiple(path: string, options?: unknown): Promise<Record<string, unknown> | undefined>;
}

function clearCaches(): void;  // Clears all default provider caches
const DEFAULT_PROVIDERS: Record<string, BaseProviderInterface>;

Custom provider example:

import { BaseProvider } from '@aws-lambda-powertools/parameters/base';

class CustomProvider extends BaseProvider {
  constructor(config: any) { super(config); }
  protected async _get(name: string, options?: any): Promise<unknown> {
    // Your retrieval logic - caching handled by base class
    return fetch(`https://api.example.com/params/${name}`).then(r => r.text());
  }
  protected async _getMultiple(path: string, options?: any): Promise<Record<string, unknown> | undefined> {
    // Your batch retrieval logic
    return fetch(`https://api.example.com/params?path=${path}`).then(r => r.json());
  }
}

Error Handling

class GetParameterError extends Error {
  constructor(message?: string, options?: ErrorOptions);
}

class TransformParameterError extends Error {
  constructor(transform: string, message: string);
}

Non-throwing mode:

// getParametersByName supports throwOnError: false
const result = await getParametersByName(
  { '/p1': {}, '/missing': {} },
  { throwOnError: false }
);
if (result._errors?.length > 0) {
  console.error('Errors:', result._errors);
}

Type Definitions

type TransformOptions = 'json' | 'binary' | 'auto';
type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };

interface GetOptionsInterface {
  maxAge?: number;
  forceFetch?: boolean;
  sdkOptions?: unknown;
  transform?: 'json' | 'binary';
}

interface GetMultipleOptionsInterface extends GetOptionsInterface {
  transform?: TransformOptions;
  throwOnTransformError?: boolean;
}

interface BaseProviderConstructorOptions {
  awsSdkV3Client?: unknown;
  clientConfig?: unknown;
  awsSdkV3ClientPrototype?: new (config?: unknown) => unknown;
}

Environment Variables

  • POWERTOOLS_PARAMETERS_MAX_AGE: Default cache TTL in seconds for all retrievals
  • POWERTOOLS_SERVICE_NAME: Default application name for AppConfig

IAM Permissions Summary

SSM: ssm:GetParameter, ssm:GetParameters, ssm:GetParametersByPath, ssm:PutParameter Secrets: secretsmanager:GetSecretValue DynamoDB: dynamodb:GetItem, dynamodb:Query AppConfig: appconfig:StartConfigurationSession, appconfig:GetLatestConfiguration All encrypted: kms:Decrypt (for encrypted parameters/secrets)

Example policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["ssm:GetParameter*", "secretsmanager:GetSecretValue", "dynamodb:GetItem", "dynamodb:Query", "appconfig:*Configuration*"],
      "Resource": ["arn:aws:*:region:account:*"]
    },
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt"],
      "Resource": ["arn:aws:kms:region:account:key/*"]
    }
  ]
}