{"id":26009968,"url":"https://github.com/byu-oit/env-ssm","last_synced_at":"2026-02-13T08:12:52.254Z","repository":{"id":36657583,"uuid":"229325804","full_name":"byu-oit/env-ssm","owner":"byu-oit","description":"Gets params from your environment first, then from the ssm paramter store.","archived":false,"fork":false,"pushed_at":"2025-03-24T20:16:33.000Z","size":853,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-07-09T21:17:07.162Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byu-oit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-12-20T19:40:11.000Z","updated_at":"2025-03-24T20:16:42.000Z","dependencies_parsed_at":"2025-03-05T22:30:00.673Z","dependency_job_id":"f179afdf-2d69-4aaa-b996-79a3a4d0a131","html_url":"https://github.com/byu-oit/env-ssm","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/byu-oit/env-ssm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fenv-ssm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fenv-ssm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fenv-ssm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fenv-ssm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byu-oit","download_url":"https://codeload.github.com/byu-oit/env-ssm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fenv-ssm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265883613,"owners_count":23843792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-05T22:26:41.639Z","updated_at":"2026-02-13T08:12:47.185Z","avatar_url":"https://github.com/byu-oit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![ npm ](https://img.shields.io/npm/v/@byu-oit/env-ssm)\n\n# env-ssm\n\nA 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.\n\n---\n\n## Table of Contents\n\n1. [Installation](#installation)\n2. [Quick Start](#quick-start)\n    - [Loading Environment Variables from SSM](#loading-environment-variables-from-ssm)\n    - [Using the Coercion API](#using-the-coercion-api)\n3. [API Reference](#api-reference)\n    - [EnvSsm Options](#envssm-options)\n    - [CoercionContainer Class](#coercioncontainer-class)\n    - [Coercion Class](#coercion-class)\n4. [Error Handling](#error-handling)\n\n---\n\n## Installation\n\nThis package has peer dependencies `@aws-sdk/client-ssm`. To install the core functionality, run:\n\n```bash\nnpm install @byu-oit/env-ssm @aws-sdk/client-ssm\n```\n\nIf you want to support loading variables from a .env file, install dotenv:\n\n```bash\nnpm install dotenv\n```\n\n---\n\n## Quick Start\n\nThe package loads environment variables from three sources, in the following order (later sources overwrite earlier ones):\n1.\tSSM Parameter Store\n2.\t`.env` file\n3.\t`process.env`\n\n### Loading Environment Variables from SSM\n\n#### Usage Examples\n\nSSM Path: `/my/app`\n\nSSM Parameters:\n- /my/app/db/user =\u003e `admin`\n- /my/app/db/pass =\u003e `ch@ng3m3`\n- /my/app/host =\u003e `https://example.com`\n\n```js\nimport EnvSsm from 'env-ssm'\n\n/**\n * Retrieves environment variables.\n * @returns { db: { user: 'admin', pass: 'ch@ng3m3' }, host: 'https://example.com' }\n */\nasync function getParams () {\n  const env = await EnvSsm('/my/app')\n  const db = env.get('db').required().asJsonObject()\n  const host = env.get('api').required().asUrlString()\n  return { db, host }\n}\n```\n\nIf your SSM parameters are spread across multiple paths or use custom delimiters, you can specify these as follows:\n\nSSM Paths:\n- /my/app\n- my.app (using `.` as a delimiter)\n\nParameters:\n\n- /my/app/db/user → admin\n- /my/app/db/pass → ch@ng3m3\n- my.app.host → example.com\n\n```js\nimport EnvSsm from 'env-ssm'\n\n/**\n * Retrieves environment variables from multiple SSM paths.\n * @returns { db: { user: 'admin', pass: 'ch@ng3m3' }, host: 'example.com' }\n */\nasync function getParams () {\n  const env = await EnvSsm([\n    '/my/app',\n    { path: 'my.app', delimiter: '.' }\n  ])\n  const db = env.get('db').required().asJsonObject()\n  const host = env.get('api').required().asString()\n  return { db, host }\n}\n```\n\n### Using the Coercion API\n\nOnce your environment variables are loaded, you can use the built-in coercion library for type-safe access. For example:\n\n```js\nimport { CoercionContainer } from '@byu-oit/env-ssm'\n\n// Define a sample environment source\nconst envSource = {\nPORT: '8080',\nDEBUG: 'true',\nCONFIG: '{\"key\": \"value\"}',\nMODE: 'production'\n}\n\n// Create a container instance with the source\nconst env = new CoercionContainer(envSource)\n\n// Retrieve and coerce variables with defaults and validations\nconst port = env.get('PORT')\n  .default(3000)\n  .asPortNumber()\n\nconst debug = env.get('DEBUG')\n  .required()\n  .asBool()\n\nconst config = env.get('CONFIG')\n  .default('{}')\n  .asJsonObject()\n\nconst mode = env.get('MODE')\n  .asEnum(['development', 'production', 'test'])\n\nconsole.log(`Server will run on port: ${port}`)\nconsole.log(`Debug mode: ${debug}`)\nconsole.log(`Configuration:`, config)\nconsole.log(`Running mode: ${mode}`)\n```\n\nIn this example:\n- **PORT** is converted into a valid port number with a default.\n- **DEBUG** is required and coerced to a boolean.\n- **CONFIG** is parsed as a JSON object.\n- **MODE** is validated against allowed values.\n\n---\n\n## API Reference\n\n### EnvSsm Options\n\n| Option        | Type                                                                                              | Description                                                                                                                                                                                                                      | Default                   |\n|:--------------|:--------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------|\n| ssm           | [SSMClient](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/index.html) | An AWS SSM client instance. The [default SSM client can be configured with environment variables](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html) or a custom instance may be provided.      | SSMClient                 |\n| paths         | [PathSsmLike](./src/path-ssm.ts) OR [PathSsmLike](./src/path-ssm.ts)[]                            | The SSM parameter store path to use. All parameters that fall under this path will be returned as properties in the environment variables object. Parameters with multiple nested children will be returned as stringified JSON. | []                        |\n| pathDelimiter | string                                                                                            | Specify a path delimiter.                                                                                                                                                                                                        | `/`                       |\n| processEnv    | boolean                                                                                           | If true, it will add process.env variables to the container.                                                                                                                                                                     | true                      |\n| dotenv        | boolean OR string                                                                                 | Adds local .env variables to the environment. Can be false, which disables `.env` support. May also be the exact path to the .env file relative to the project or package root.                                                  | `process.cwd() + '/.env'` |\n\n\u003e [TIP!]\n\u003e You can also configure options using environment variables:\n\u003e - ENV_SSM_PATHS\n\u003e - ENV_SSM_PATH_DELIMITER\n\u003e - ENV_SSM_PROCESS_ENV\n\u003e - ENV_SSM_DOTENV\n\n\u003e [NOTE!]\n\u003e 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.\n\n---\n\n### CoercionContainer Class\n\nWraps an object of environment variables and provides a method for type-safe variable access.\n\n#### Constructor\n\n```ts\nconstructor(source: T)\n```\n\n- source: An object conforming to the Source interface.\n\n#### Method: get\n\n```ts\nget(key: keyof T | string): Coercion\n```\n\n- key: The name of the environment variable.\n- Returns: A Coercion instance for chaining validation and conversion methods.\n\n### Coercion Class\n\nA 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.\n\nMethods\n\n```ts\nrequired(condition?: boolean): this\n```\n\nMarks the variable as required (default is true).\nThrows an error if the variable is missing when required.\n\n```ts\ndefault(defaultValue: unknown): this\n```\n\nSets a fallback value if the variable is absent.\n\n```ts\nasString(): string\n```\n\nConverts the variable to a string.\n\n```ts\nasBool(): boolean\n```\n\nConverts the variable to a boolean. Accepts native boolean values or the strings \"true\"/\"false\" (case-insensitive).\nThrows an error if the conversion fails.\n\n```ts\nasNumber(): number\n```\n\nConverts the variable to a number.\nThrows an error if the result is NaN.\n\n```ts\nasPortNumber(): number\n```\n\nConverts the variable to a number and validates that it falls within the range 1–65535.\nThrows an error if the port number is out of range.\n\n```ts\nasJsonObject\u003cT = any\u003e(): T\n```\n\nConverts the variable to a JSON object. If the value is a string, it is parsed as JSON.\nThrows an error if parsing fails or if the value is not a valid JSON object.\n\n```ts\nasEnum\u003cT extends string\u003e(allowed: T[]): T\n```\n\nValidates that the variable’s string value is one of the allowed values.\nThrows an error if the value is not in the allowed list.\n\n```ts\nasUrlString(): string\n```\n\nConverts the variable to a string and validates that it is a well-formed URL.\nThrows an error if the URL is invalid.\n\n```ts\nasUrlObject(): URL\n```\n\nConverts the variable to a URL object using the URL constructor.\nThrows an error if the value is not a valid URL.\n\n---\n\n## Error Handling\n\nEach coercion method checks for the presence and validity of its target variable:\n- If a variable is missing and marked as required, an error is thrown.\n- If conversion fails (e.g., an invalid number, malformed JSON, or a bad URL), a descriptive error is provided.\n\nThis helps catch configuration issues early during application startup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyu-oit%2Fenv-ssm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyu-oit%2Fenv-ssm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyu-oit%2Fenv-ssm/lists"}