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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Powertools for AWS Lambda Parameters

Name: tessl/npm-aws-lambda-powertools--parameters
Author: tessl

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:

Option	Type	Default	Description
`maxAge`	`number`	`5`	Cache TTL in seconds. Set to 0 to disable. Env: `POWERTOOLS_PARAMETERS_MAX_AGE`
`forceFetch`	`boolean`	`false`	Skip cache and fetch latest value
`transform`	`'json' \| 'binary' \| 'auto'`	`undefined`	Transform value (json=parse, binary=decode, auto=detect by suffix)
`sdkOptions`	`object`	`undefined`	AWS 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/*"]
    }
  ]
}

Workspace: tessl
Visibility: Public
Created: 4 months ago
Last updated: 2 months ago
Describes: pkg:npm/@aws-lambda-powertools/parameters@2.29.x
Publish Source: CLI
Badge