or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aws-sdk-integration.mdbase64.mddynamodb.mdenvironment-variables.mdindex.mdlru-cache.mdmiddy-integration.mdtype-utilities.mdutility-class.md
tile.json

tessl/npm-aws-lambda-powertools--commons

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

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

To install, run

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

index.mddocs/

Powertools for AWS Lambda (TypeScript) - Commons

Powertools for AWS Lambda Commons is a shared utility package providing reusable components for building serverless AWS Lambda functions in TypeScript. It offers runtime type-checking utilities, Base64 encoding/decoding, JSON type definitions, Lambda handler interfaces, environment variable utilities, an LRU cache implementation, DynamoDB unmarshalling utilities, and AWS SDK integration helpers.

Package Information

  • Package Name: @aws-lambda-powertools/commons
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-lambda-powertools/commons

Core Imports

// Main entry point exports
import { Utility, PT_VERSION } from '@aws-lambda-powertools/commons';
import { addUserAgentMiddleware, isSdkClient } from '@aws-lambda-powertools/commons';
import { cleanupMiddlewares } from '@aws-lambda-powertools/commons';
import {
  IDEMPOTENCY_KEY,
  LOGGER_KEY,
  METRICS_KEY,
  TRACER_KEY,
} from '@aws-lambda-powertools/commons';

// Type utilities (with type guards)
import {
  isRecord,
  isString,
  isNumber,
  isTruthy,
  getType,
} from '@aws-lambda-powertools/commons/typeutils';

// Base64 utilities
import { fromBase64 } from '@aws-lambda-powertools/commons/utils/base64';

// Environment variable utilities
import {
  getStringFromEnv,
  getNumberFromEnv,
  getBooleanFromEnv,
  isDevMode,
  getServiceName,
} from '@aws-lambda-powertools/commons/utils/env';

// LRU Cache
import { LRUCache } from '@aws-lambda-powertools/commons/utils/lru-cache';

// DynamoDB unmarshaller
import { unmarshallDynamoDB } from '@aws-lambda-powertools/commons/utils/unmarshallDynamoDB';

// Type definitions
import type {
  JSONValue,
  JSONObject,
  JSONArray,
  LambdaInterface,
  ConfigServiceInterface,
  GenericLogger,
} from '@aws-lambda-powertools/commons/types';

For CommonJS:

const { Utility, addUserAgentMiddleware } = require('@aws-lambda-powertools/commons');
const { isRecord, isString } = require('@aws-lambda-powertools/commons/typeutils');
const { fromBase64 } = require('@aws-lambda-powertools/commons/utils/base64');
const { getStringFromEnv } = require('@aws-lambda-powertools/commons/utils/env');

Basic Usage

import { isRecord, isString } from '@aws-lambda-powertools/commons/typeutils';
import { getStringFromEnv } from '@aws-lambda-powertools/commons/utils/env';
import { LRUCache } from '@aws-lambda-powertools/commons/utils/lru-cache';

// Type checking with type guards
const data: unknown = { key: 'value' };
if (isRecord(data)) {
  // TypeScript knows data is a Record here
  const value = data.key;
}

// Read environment variables with validation
const apiKey = getStringFromEnv({
  key: 'API_KEY',
  errorMessage: 'API_KEY is required',
});

// Use LRU cache for performance optimization
const cache = new LRUCache<string, number>({ maxSize: 100 });
cache.add('user:123', 42);
const value = cache.get('user:123'); // 42

Architecture

The package is organized into several independent modules accessible via subpath exports:

  • Core Utilities: Main entry point providing AWS SDK integration, Middy middleware helpers, and the base Utility class
  • Type Utilities: Runtime type checking and type guard functions
  • Base64 Utilities: Encoding and decoding for Base64 data
  • Environment Utilities: Reading and validating environment variables
  • LRU Cache: Performance optimization for repeated computations
  • DynamoDB Utilities: Unmarshalling DynamoDB AttributeValue objects
  • Type Definitions: TypeScript types for JSON, Lambda handlers, and more

Each module is designed to work independently with minimal dependencies.

Capabilities

Runtime Type Checking

Runtime type validation utilities with TypeScript type guard support. Ideal for validating unknown data from API requests, event payloads, or external sources.

function isRecord(value: unknown): value is Record<string | number, unknown>;
function isString(value: unknown): value is string;
function isNumber(value: unknown): value is number;
function isIntegerNumber(value: unknown): value is number;
function isTruthy(value: unknown): boolean;
function isNull(value: unknown): value is null;
function isNullOrUndefined(value: unknown): value is null | undefined;
function isStringUndefinedNullEmpty(value: unknown): boolean;
function isRegExp(value: unknown): value is RegExp;
function isStrictEqual(left: unknown, right: unknown): boolean;
function getType(value: unknown): string;

Type Utilities

Base64 Encoding and Decoding

Convert Base64-encoded strings to Uint8Array for processing binary data in Lambda functions.

function fromBase64(input: string, encoding?: BufferEncoding): Uint8Array;

Base64 Utilities

Environment Variable Utilities

Safely read and validate environment variables with type conversion and default value support.

function getStringFromEnv(options: GetStringFromEnvOptions): string;
function getNumberFromEnv(options: GetNumberFromEnvOptions): number;
function getBooleanFromEnv(options: GetBooleanFromEnvOptions): boolean;
function isDevMode(): boolean;
function getServiceName(): string;
function getXrayTraceDataFromEnv(): Record<string, string> | undefined;
function isRequestXRaySampled(): boolean;
function getXRayTraceIdFromEnv(): string | undefined;
function shouldUseInvokeStore(): boolean;

interface GetStringFromEnvOptions {
  key: string;
  defaultValue?: string;
  errorMessage?: string;
}

interface GetNumberFromEnvOptions {
  key: string;
  defaultValue?: number;
  errorMessage?: string;
}

interface GetBooleanFromEnvOptions {
  key: string;
  defaultValue?: boolean;
  errorMessage?: string;
  extendedParsing?: boolean;
}

Environment Variable Utilities

LRU Cache

Least Recently Used (LRU) cache implementation for optimizing performance-critical operations in Lambda functions.

class LRUCache<K, V> {
  constructor(config?: LRUCacheOptions);
  add(key: K, value: V): void;
  get(key: K): V | undefined;
  has(key: K): boolean;
  remove(key: K): void;
  size(): number;
}

interface LRUCacheOptions {
  maxSize?: number;
}

LRU Cache

DynamoDB Unmarshalling

Convert DynamoDB AttributeValue objects to standard JavaScript objects with automatic type handling and BigInt support for large numbers.

function unmarshallDynamoDB(
  data: AttributeValue | Record<string, AttributeValue>
): unknown;

class UnmarshallDynamoDBAttributeError extends Error {
  constructor(message: string);
}

DynamoDB Utilities

AWS SDK Integration

Add Powertools user agent middleware to AWS SDK v3 clients for usage tracking.

function addUserAgentMiddleware(client: unknown, feature: string): void;
function isSdkClient(client: unknown): client is SdkClient;

interface SdkClient {
  send: Function;
  config: object;
  middlewareStack: {
    identify: () => string[];
    addRelativeTo: (middleware: Function, options: object) => void;
  };
}

AWS SDK Integration

Middy Middleware Integration

Utilities for integrating with the Middy middleware framework, including cleanup functions for early-return scenarios.

function cleanupMiddlewares(request: MiddyLikeRequest): Promise<void>;

const IDEMPOTENCY_KEY: string;
const LOGGER_KEY: string;
const METRICS_KEY: string;
const TRACER_KEY: string;

interface MiddyLikeRequest {
  event: unknown;
  context: unknown;
  response: unknown;
  error: Error | null;
  internal: Record<string, unknown>;
}

Middy Middleware Integration

Base Utility Class

Base class providing cold start detection heuristics for Lambda function executions. Used internally by other Powertools utilities but can be extended for custom utilities.

class Utility {
  constructor();
  protected getColdStart(): boolean;
  protected getInitializationType(): 'unknown' | 'on-demand' | 'provisioned-concurrency';
  protected isValidServiceName(serviceName?: string): boolean;
}

const PT_VERSION: string;

Utility Class

Type Definitions

Common TypeScript type definitions for JSON data structures and Lambda handlers.

type JSONPrimitive = string | number | boolean | null | undefined;
type JSONValue = JSONPrimitive | JSONObject | JSONArray;
type JSONObject = { [key: number | string]: JSONValue };
type JSONArray = Array<JSONValue>;

// Note: Handler is imported from the external 'aws-lambda' package
// It represents the standard AWS Lambda handler function signature
import type { Handler } from 'aws-lambda';

interface LambdaInterface {
  handler: SyncHandler<Handler> | AsyncHandler<Handler>;
}

type AsyncHandler<T extends Handler> = (
  event: Parameters<T>[0],
  context: Parameters<T>[1]
) => Promise<NonNullable<Parameters<Parameters<T>[2]>[1]>>;

type SyncHandler<T extends Handler> = (
  event: Parameters<T>[0],
  context: Parameters<T>[1],
  callback: Parameters<T>[2]
) => void;

type HandlerMethodDecorator = (
  target: LambdaInterface,
  propertyKey: string | symbol,
  descriptor:
    | TypedPropertyDescriptor<SyncHandler<Handler>>
    | TypedPropertyDescriptor<AsyncHandler<Handler>>
) => void;

interface ConfigServiceInterface {
  get(name: string): string;
  getServiceName(): string;
  getXrayTraceId(): string | undefined;
  getXrayTraceSampled(): boolean;
  isDevMode(): boolean;
  isValueTrue(value: string): boolean;
}

interface GenericLogger {
  trace?: (...content: any[]) => void;
  debug: (...content: any[]) => void;
  info: (...content: any[]) => void;
  warn: (...content: any[]) => void;
  error: (...content: any[]) => void;
}