API Reference
    Preparing search index...

    Class AppConfigProvider

    The Parameters utility provides an AppConfigProvider that allows to retrieve configuration profiles from AWS AppConfig.

    This utility supports AWS SDK v3 for JavaScript only (@aws-sdk/client-appconfigdata). This allows the utility to be modular, and you to install only the SDK packages you need and keep your bundle size small.

    Basic usage

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

    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
    });

    export const handler = async (): Promise<void> => {
      // Retrieve a configuration profile
      const encodedConfig = await configProvider.get('my-config');
      const config = new TextDecoder('utf-8').decode(encodedConfig);
    };

    If you want to retrieve configs without customizing the provider, you can use the getAppConfig function instead.

    Caching

    By default, the provider will cache parameters retrieved in-memory for 5 seconds. You can adjust how long values should be kept in cache by using the maxAge parameter.

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

    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
    });

    export const handler = async (): Promise<void> => {
      // Retrieve a configuration profile and cache it for 10 seconds
      const encodedConfig = await configProvider.get('my-config', { maxAge: 10 });
      const config = new TextDecoder('utf-8').decode(encodedConfig);
    };

    If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the forceFetch parameter.

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

    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
    });

    export const handler = async (): Promise<void> => {
      // Retrieve a config and always fetch the latest value
      const config = await configProvider.get('my-config', { forceFetch: true });
      const config = new TextDecoder('utf-8').decode(encodedConfig);
    };

    Transformations

    For configurations stored as freeform JSON, Freature Flag, you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.

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

    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
    });

    export const handler = async (): Promise<void> => {
      // Retrieve a JSON config or Feature Flag and parse it as JSON
      const config = await configProvider.get('my-config', { transform: 'json' });
    };

    For configurations that are instead stored as base64-encoded binary data, you can use the transform argument set to binary for decoding. This will return a decoded string.

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

    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
    });

    export const handler = async (): Promise<void> => {
      // Retrieve a base64-encoded string and decode it
      const config = await configProvider.get('my-config', { transform: 'binary' });
    };

    Extra SDK options

    When retrieving a configuration profile, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter.

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

    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
    });

    export const handler = async (): Promise<void> => {
      // Retrieve a config and pass extra options to the AWS SDK v3 for JavaScript client
      const config = await configProvider.get('my-config', {
        sdkOptions: {
          RequiredMinimumPollIntervalInSeconds: 60,
        },
      });
      const config = new TextDecoder('utf-8').decode(encodedConfig);
    };

    This object accepts the same options as the AWS SDK v3 for JavaScript AppConfigData client.

    Customize AWS SDK v3 for JavaScript client

    By default, the provider will create a new AppConfigData client using the default configuration.

    You can customize the client by passing a custom configuration object to the provider.

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

    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
      clientConfig: { region: 'eu-west-1' },
    });

    This object accepts the same options as the AWS SDK v3 for JavaScript AppConfig Data client.

    Otherwise, if you want to use a custom client altogether, you can pass it to the provider.

    import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
    import { AppConfigDataClient } from '@aws-sdk/client-appconfigdata';

    const client = new AppConfigDataClient({ region: 'eu-west-1' });
    const configProvider = new AppConfigProvider({
      application: 'my-app',
      environment: 'prod',
      awsSdkV3Client: client,
    });

    This object must be an instance of the AWS SDK v3 for JavaScript AppConfig Data client.

    For more usage examples, see our documentation.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    client configurationTokenStore store valueStore

    Methods

    _get _getMultiple addToCache clearCache get getMultiple hasKeyExpiredInCache

    Constructors

    Properties

    client: AppConfigDataClient
    configurationTokenStore: Map<string, { expiration: number; value: string }> = ...
    store: Map<string, ExpirableValue>
    valueStore: Map<string, Uint8Array<ArrayBufferLike>> = ...

    Methods

    Protected_get

    • _get(
          name: string,
          options?: NonNullable<AppConfigGetOptions>,
      ): Promise<Uint8Array<ArrayBufferLike> | undefined>

      Retrieve a configuration from AWS AppConfig.

      First we start the session and after that we retrieve the configuration from AppSync. When starting a session, the service returns a token that can be used to poll for changes for up to 24hrs, so we cache it for later use together with the expiration date.

      The value of the configuration is also cached internally because AppConfig returns an empty value if the configuration has not changed since the last poll. This way even if your code polls the configuration multiple times, we return the most recent value by returning the cached one if an empty response is returned by AppConfig.

      Parameters

      • name: string

        Name of the configuration or its ID

      • Optionaloptions: NonNullable<AppConfigGetOptions>

        SDK options to propagate to StartConfigurationSession API call

        • maxAge

          Maximum age of the value in the cache, in seconds.

        • forceFetch

          Force fetch the value from the parameter store, ignoring the cache.

        • sdkOptions

          Additional options to pass to the AWS SDK v3 client. Supports all options from StartConfigurationSessionCommandInput except ApplicationIdentifier, EnvironmentIdentifier, and ConfigurationProfileIdentifier.

        • transform

          Optional transform to be applied, can be 'json' or 'binary'.

      Returns Promise<Uint8Array<ArrayBufferLike> | undefined>

    Protected_getMultiple

    • _getMultiple(
          _path: string,
          _sdkOptions?: unknown,
      ): Promise<Record<string, unknown> | undefined>

      Retrieving multiple configurations is not supported by AWS AppConfig.

      Parameters

      • _path: string
      • Optional_sdkOptions: unknown

      Returns Promise<Record<string, unknown> | undefined>

      Not Implemented Error.

    • Add a value to the cache.

      Parameters

      • key: string

        Key of the cached value

      • value: unknown

        Value to be cached

      • maxAge: number

        Maximum age in seconds for the value to be cached

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods