@byu-oit/env-ssm v4.1.0

env-ssm

A lightweight solution to load environment variables from AWS SSM Parameter Store—with support for .env files and process.env—and seamlessly integrate with a type coercion API for safe, validated configuration.

Table of Contents

1. Installation
2. Quick Start
   • Loading Environment Variables from SSM
   • Using the Coercion API
3. API Reference
   • EnvSsm Options
   • CoercionContainer Class
   • Coercion Class
4. Error Handling

Installation

This package has peer dependencies @aws-sdk/client-ssm. To install the core functionality, run:

npm install @byu-oit/env-ssm @aws-sdk/client-ssm

If you want to support loading variables from a .env file, install dotenv:

npm install dotenv

Quick Start

The package loads environment variables from three sources, in the following order (later sources overwrite earlier ones): 1. SSM Parameter Store 2. .env file 3. process.env

Loading Environment Variables from SSM

Usage Examples

SSM Path: /my/app

SSM Parameters:

• /my/app/db/user => admin
• /my/app/db/pass => ch@ng3m3
• /my/app/host => https://example.com

import EnvSsm from 'env-ssm'

/**
 * Retrieves environment variables.
 * @returns { db: { user: 'admin', pass: 'ch@ng3m3' }, host: 'https://example.com' }
 */
async function getParams () {
  const env = await EnvSsm('/my/app')
  const db = env.get('db').required().asJsonObject()
  const host = env.get('api').required().asUrlString()
  return { db, host }
}

If your SSM parameters are spread across multiple paths or use custom delimiters, you can specify these as follows:

SSM Paths:

• /my/app
• my.app (using . as a delimiter)

Parameters:

• /my/app/db/user → admin
• /my/app/db/pass → ch@ng3m3
• my.app.host → example.com

import EnvSsm from 'env-ssm'

/**
 * Retrieves environment variables from multiple SSM paths.
 * @returns { db: { user: 'admin', pass: 'ch@ng3m3' }, host: 'example.com' }
 */
async function getParams () {
  const env = await EnvSsm([
    '/my/app',
    { path: 'my.app', delimiter: '.' }
  ])
  const db = env.get('db').required().asJsonObject()
  const host = env.get('api').required().asString()
  return { db, host }
}

Using the Coercion API

Once your environment variables are loaded, you can use the built-in coercion library for type-safe access. For example:

import { CoercionContainer } from '@byu-oit/env-ssm'

// Define a sample environment source
const envSource = {
PORT: '8080',
DEBUG: 'true',
CONFIG: '{"key": "value"}',
MODE: 'production'
}

// Create a container instance with the source
const env = new CoercionContainer(envSource)

// Retrieve and coerce variables with defaults and validations
const port = env.get('PORT')
  .default(3000)
  .asPortNumber()

const debug = env.get('DEBUG')
  .required()
  .asBool()

const config = env.get('CONFIG')
  .default('{}')
  .asJsonObject()

const mode = env.get('MODE')
  .asEnum(['development', 'production', 'test'])

console.log(`Server will run on port: ${port}`)
console.log(`Debug mode: ${debug}`)
console.log(`Configuration:`, config)
console.log(`Running mode: ${mode}`)

In this example:

• PORT is converted into a valid port number with a default.
• DEBUG is required and coerced to a boolean.
• CONFIG is parsed as a JSON object.
• MODE is validated against allowed values.

API Reference

EnvSsm Options

TIP! You can also configure options using environment variables:

• ENV_SSM_PATHS
• ENV_SSM_PATH_DELIMITER
• ENV_SSM_PROCESS_ENV
• ENV_SSM_DOTENV

NOTE! All options provided as environment variables are cast from strings to their respective types. For ENV_SSM_PATHS, you can supply a comma-delimited list (e.g. /app/dev,/app/prd) or a JSON object/array.

CoercionContainer Class

Wraps an object of environment variables and provides a method for type-safe variable access.

Constructor

constructor(source: T)

• source: An object conforming to the Source interface.

Method: get

get(key: keyof T | string): Coercion

• key: The name of the environment variable.
• Returns: A Coercion instance for chaining validation and conversion methods.

Coercion Class

A builder class for handling an individual environment variable. It allows marking a variable as required, setting default values, and converting the variable into various types.

Methods

required(condition?: boolean): this

Marks the variable as required (default is true). Throws an error if the variable is missing when required.

default(defaultValue: unknown): this

Sets a fallback value if the variable is absent.

asString(): string

Converts the variable to a string.

asBool(): boolean

Converts the variable to a boolean. Accepts native boolean values or the strings "true"/"false" (case-insensitive). Throws an error if the conversion fails.

asNumber(): number

Converts the variable to a number. Throws an error if the result is NaN.

asPortNumber(): number

Converts the variable to a number and validates that it falls within the range 1–65535. Throws an error if the port number is out of range.

asJsonObject<T = any>(): T

Converts the variable to a JSON object. If the value is a string, it is parsed as JSON. Throws an error if parsing fails or if the value is not a valid JSON object.

asEnum<T extends string>(allowed: T[]): T

Validates that the variable’s string value is one of the allowed values. Throws an error if the value is not in the allowed list.

asUrlString(): string

Converts the variable to a string and validates that it is a well-formed URL. Throws an error if the URL is invalid.

asUrlObject(): URL

Converts the variable to a URL object using the URL constructor. Throws an error if the value is not a valid URL.

Error Handling

Each coercion method checks for the presence and validity of its target variable:

• If a variable is missing and marked as required, an error is thrown.
• If conversion fails (e.g., an invalid number, malformed JSON, or a bad URL), a descriptive error is provided.

This helps catch configuration issues early during application startup.