\n\n## š” Highlights\n\n- šļø Canonical SSM Contract ā Enforces a deterministic ///// model, eliminating ad-hoc parameter naming chaos across teams\n- ā” Single Recursive Load ā Fetches all parameters under // at startup into an in-memory cache, serving lookups instantly with zero runtime SSM calls\n- š”ļø Fail-Fast Validation ā Catches missing segments, empty strings, whitespace, and illegal '/' characters at boot time with explicit error messages\n- š Broad NestJS Compatibility ā Supports NestJS v8 through v11 with both register() and registerAsync() patterns, including factory, class, and existing provider injection\n\n## š Table of Contents\n- [Description](#-description)\n- [Tech Stack](#-tech-stack)\n- [Features](#-features)\n- [Architecture](#-architecture)\n- [Project Structure](#-project-structure)\n- [Prerequisites](#-prerequisites)\n- [Installation](#-installation)\n- [Usage](#-usage)\n- [Roadmap](#-roadmap)\n- [FAQ](#-faq)\n- [License](#-license)\n- [Acknowledgments](#-acknowledgments)\n\n## š Description\nManaging application configuration across multiple environments, namespaces, and deployment targets is one of the most error-prone aspects of cloud-native development. **NestJS AWS Parameter Store Config** eliminates that complexity by enforcing a single, canonical SSM path contract:\n\n```\n/////\n```\n\nThis module provides a first-class NestJS dynamic module that loads all parameters at startup into an in-memory cache, then exposes a type-safe, validated lookup API that resolves paths deterministically.\n\n### Real-World Use Cases\n\n- **Microservices on ECS/EKS**: Each service registers with its own `namespace` and `instanceName`, while sharing infrastructure parameters (database hosts, secret IDs) across namespaces.\n- **Multi-Environment Deployments**: Seamlessly switch between `local`, `development`, `staging`, and `production` without changing a single line of application code.\n- **Shared Infrastructure Metadata**: A single recursive load from `//` caches everything ā RDS connection strings, Secrets Manager references, CloudWatch config ā accessible via simple path lookups.\n- **Monorepo / Multi-Service Architectures**: Different services can override `namespace` and `instanceName` per-call, accessing any parameter in the hierarchy without re-registering the module.\n\nWith built-in enums for 90+ namespace tokens (AWS, GCP, Azure, databases, message brokers, and more), strict validation that fails fast on misconfigured paths, and support for both synchronous and async module registration, this library turns AWS Parameter Store into a structured, predictable configuration backbone for your NestJS applications.\n\n## š ļø Tech Stack\n\n| Category | Technologies |\n|----------|-------------|\n| **Language** | TypeScript |\n| **Runtime** | Node.js |\n| **Framework** | NestJS |\n| **Cloud** | AWS Systems Manager (SSM) |\n| **Build Tool** | Rollup, TypeScript Compiler |\n| **Linting** | ESLint, Prettier |\n| **CI/CD** | GitHub Actions, Semantic Release |\n| **Package Manager** | npm |\n| **Code Quality** | Husky, Commitlint, Lint-Staged |\n\n## š Features\n- āØ ****Canonical Path Contract** ā All parameter lookups resolve through a strict `/////` model, ensuring consistency across all services and environments**\n- āØ ****Recursive Parameter Loading** ā Loads all parameters under `//` at startup using paginated SSM API calls, building an in-memory cache for instant lookups**\n- āØ ****Sync & Async Module Registration** ā Supports `register()` for static config and `registerAsync()` with `useFactory`, `useClass`, and `useExisting` patterns for dynamic configuration**\n- āØ ****Per-Call Overrides** ā Override `namespace`, `instanceName`, `application`, or `environment` on any individual `get()` call while keeping module-level defaults**\n- āØ ****90+ Built-In Namespace Tokens** ā Curated `ENamespace` enum covering AWS, GCP, Azure services, databases, message brokers, observability tools, and more**\n- āØ ****Lifecycle Environment Enum** ā `EEnvironment` provides `LOCAL`, `DEVELOPMENT`, `STAGING`, `PRODUCTION`, and `TEST` tokens out of the box**\n- āØ ****Strict Input Validation** ā Fails fast with descriptive errors for missing segments, empty strings, whitespace-only values, and segments containing `/`**\n- āØ ****Dual Module Output** ā Ships both ESM and CommonJS builds with full TypeScript declarations and source maps**\n- āØ ****Secure Parameter Decryption** ā Optional `shouldDecryptParameters` flag enables transparent decryption of SecureString parameters**\n- āØ ****Verbose Logging Mode** ā Optional `isVerbose` flag enables detailed NestJS Logger output during parameter loading for debugging**\n- āØ ****Global Module** ā Registered as a `@Global()` module, making `ParameterStoreConfigService` injectable anywhere without re-importing**\n- āØ ****Zero Runtime Dependencies** ā Peer dependencies only ā `@aws-sdk/client-ssm` and `@nestjs/common` are provided by your application**\n\n## š Architecture\n\n### System Architecture\n\n```mermaid\nflowchart TD\n appModule[AppModule] -->|imports| configModule[ParameterStoreConfigModule]\n configModule -->|provides| propertiesProvider[PropertiesProvider]\n configModule -->|provides| ssmProvider[SSMClientProvider]\n configModule -->|provides| parametersProvider[ParametersProvider]\n configModule -->|provides| parameterStoreService[ParameterStoreService]\n configModule -->|exports| configService[ParameterStoreConfigService]\n ssmProvider -->|creates| ssmClient[SSMClient]\n parameterStoreService -->|uses| ssmClient\n parametersProvider -->|calls| parameterStoreService\n configService -->|reads| propertiesProvider\n configService -->|reads| parametersProvider\n anyService[Any Injectable Service] -->|injects| configService\n```\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n participant App as NestJS App\n participant Module as ConfigModule\n participant SSMProvider as SSMClientProvider\n participant ParamProvider as ParametersProvider\n participant PSService as ParameterStoreService\n participant AWS as AWS SSM API\n participant Service as Your Service\n participant ConfigSvc as ConfigService\n\n App->>Module: register() / registerAsync()\n Module->>SSMProvider: Create SSMClient with config\n SSMProvider-->>Module: SSMClient instance\n Module->>ParamProvider: Initialize parameter loading\n ParamProvider->>PSService: getParametersByPath(/app/env)\n loop Paginated Loading\n PSService->>AWS: GetParametersByPathCommand\n AWS-->>PSService: Parameters + NextToken\n end\n PSService-->>ParamProvider: All Parameter[] cached\n ParamProvider-->>Module: In-memory parameter cache ready\n Service->>ConfigSvc: get({ path, namespace?, ... })\n ConfigSvc->>ConfigSvc: buildLookupPath() + validate\n ConfigSvc->>ConfigSvc: Find in cached parameters\n ConfigSvc-->>Service: string value or null\n```\n\n## š Project Structure\n\n\nClick to expand\n\n```\nNestJS-AWS-Parameter-Store-Config/\nāāā .github/\nā āāā workflows/\nā ā āāā mirror-to-codecommit.yml\nā ā āāā qodana-quality-scan.yml\nā ā āāā release.yml\nā ā āāā snyk-security-scan.yml\nā āāā dependabot.yml\nāāā src/\nā āāā modules/\nā ā āāā aws/\nā ā āāā config/\nā āāā shared/\nā ā āāā constant/\nā ā āāā enum/\nā ā āāā interface/\nā ā āāā provider/\nā āāā index.ts\nāāā CHANGELOG.md\nāāā commitlint.config.js\nāāā eslint.config.js\nāāā LICENSE\nāāā lint-staged.config.js\nāāā nest-cli.json\nāāā package-lock.json\nāāā package.json\nāāā prettier.config.js\nāāā README.md\nāāā release.config.js\nāāā rollup.config.js\nāāā tsconfig.build.json\nāāā tsconfig.json\n```\n\n\n\n## š Prerequisites\n\n- Node.js >= 16.0.0\n- npm >= 8.0.0\n- NestJS >= 8.0.0 (supports v8, v9, v10, v11)\n- @aws-sdk/client-ssm >= 3.535.0\n- AWS credentials configured (IAM role, environment variables, or AWS CLI profile)\n- AWS SSM parameters created following the canonical path convention\n\n## š Installation\n```bash\n# Install the package and its required peer dependencies\nnpm install @elsikora/nestjs-aws-parameter-store-config @aws-sdk/client-ssm @nestjs/common\n\n# Or with Yarn\nyarn add @elsikora/nestjs-aws-parameter-store-config @aws-sdk/client-ssm @nestjs/common\n\n# Or with pnpm\npnpm add @elsikora/nestjs-aws-parameter-store-config @aws-sdk/client-ssm @nestjs/common\n\n\n### Building from Source\n\n\n# Clone the repository\ngit clone https://github.com/ElsiKora/NestJS-AWS-Parameter-Store-Config.git\ncd NestJS-AWS-Parameter-Store-Config\n\n# Install dependencies\nnpm install\n\n# Build ESM and CJS outputs\nnpm run build\n\n# Run linting\nnpm run lint:all\n\n# Type check\nnpm run lint:types\n```\n\n## š” Usage\n## Quick Start\n\n### 1. Register the Module\n\nAdd `ParameterStoreConfigModule` to your root `AppModule` with your canonical defaults:\n\n```typescript\nimport { Module } from \"@nestjs/common\";\nimport {\n EEnvironment,\n ENamespace,\n ParameterStoreConfigModule,\n} from \"@elsikora/nestjs-aws-parameter-store-config\";\n\n@Module({\n imports: [\n ParameterStoreConfigModule.register({\n application: \"gameport\",\n environment: EEnvironment.STAGING,\n namespace: ENamespace.AWS_ECS_FARGATE,\n instanceName: \"reaper-api\",\n shouldDecryptParameters: true,\n config: {\n region: \"eu-north-1\",\n },\n }),\n ],\n})\nexport class AppModule {}\n```\n\n### 2. Async Registration with ConfigService\n\nFor dynamic configuration that depends on environment variables or other providers:\n\n```typescript\nimport { Module } from \"@nestjs/common\";\nimport { ConfigModule, ConfigService } from \"@nestjs/config\";\nimport {\n EEnvironment,\n ENamespace,\n ParameterStoreConfigModule,\n} from \"@elsikora/nestjs-aws-parameter-store-config\";\n\n@Module({\n imports: [\n ConfigModule.forRoot(),\n ParameterStoreConfigModule.registerAsync({\n imports: [ConfigModule],\n inject: [ConfigService],\n useFactory: (configService: ConfigService) => ({\n application: configService.getOrThrow(\"APP_NAME\"),\n environment: configService.getOrThrow(\"NODE_ENV\"),\n namespace: ENamespace.AWS_ECS_FARGATE,\n instanceName: configService.getOrThrow(\"SERVICE_NAME\"),\n shouldDecryptParameters: true,\n shouldUseRecursiveLoading: true,\n isVerbose: configService.get(\"VERBOSE\") === \"true\",\n config: {\n region: configService.getOrThrow(\"AWS_REGION\"),\n },\n }),\n }),\n ],\n})\nexport class AppModule {}\n```\n\n### 3. Inject and Use the Service\n\nSince the module is `@Global()`, you can inject `ParameterStoreConfigService` in any provider:\n\n```typescript\nimport { Injectable } from \"@nestjs/common\";\nimport {\n ENamespace,\n ParameterStoreConfigService,\n} from \"@elsikora/nestjs-aws-parameter-store-config\";\n\n@Injectable()\nexport class DatabaseService {\n constructor(\n private readonly config: ParameterStoreConfigService,\n ) {}\n\n getDatabaseHost(): string {\n // Resolves: /gameport/staging/aws-rds/aurora-postgres/host\n return this.config.get({\n namespace: ENamespace.AWS_RDS,\n instanceName: \"aurora-postgres\",\n path: [\"host\"],\n }) ?? \"localhost\";\n }\n\n getDatabasePort(): number {\n // Resolves: /gameport/staging/aws-rds/aurora-postgres/port\n const port = this.config.get({\n namespace: ENamespace.AWS_RDS,\n instanceName: \"aurora-postgres\",\n path: [\"port\"],\n });\n return port ? parseInt(port, 10) : 5432;\n }\n}\n```\n\n### 4. Cross-Namespace Lookups\n\nAccess parameters from different namespaces without re-registering:\n\n```typescript\n@Injectable()\nexport class AppConfigService {\n constructor(\n private readonly config: ParameterStoreConfigService,\n ) {}\n\n // Uses module defaults: /gameport/staging/aws-ecs-fargate/reaper-api/api/version\n getApiVersion(): string | null {\n return this.config.get({ path: [\"api\", \"version\"] });\n }\n\n // Override namespace: /gameport/staging/aws-secrets-manager/database/secret-id\n getDatabaseSecretId(): string | null {\n return this.config.get({\n namespace: ENamespace.AWS_SECRETS_MANAGER,\n instanceName: \"database\",\n path: [\"secret-id\"],\n });\n }\n\n // Override everything: /other-app/production/aws-lambda/processor/timeout\n getExternalConfig(): string | null {\n return this.config.get({\n application: \"other-app\",\n environment: \"production\",\n namespace: ENamespace.AWS_LAMBDA,\n instanceName: \"processor\",\n path: [\"timeout\"],\n });\n }\n}\n```\n\n### 5. Custom Namespace Strings\n\nNot limited to the built-in enums ā pass any string:\n\n```typescript\nthis.config.get({\n namespace: \"custom-service\",\n instanceName: \"my-instance\",\n path: [\"some\", \"deep\", \"config\"],\n});\n// Resolves: /gameport/staging/custom-service/my-instance/some/deep/config\n```\n\n### Configuration Options Reference\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `application` | `string` | ā | ā | Product/system name (first path segment) |\n| `environment` | `EEnvironment \\| string` | ā | ā | Lifecycle environment token |\n| `namespace` | `ENamespace \\| string` | ā | ā | Default owner/runtime/resource token |\n| `instanceName` | `string` | ā | ā | Default deployable unit or resource instance |\n| `config` | `SSMClientConfig` | ā | `{}` | AWS SSM client configuration |\n| `shouldDecryptParameters` | `boolean` | ā | `false` | Decrypt SecureString parameters |\n| `shouldUseRecursiveLoading` | `boolean` | ā | `true` | Recursively load all nested parameters |\n| `isVerbose` | `boolean` | ā | `false` | Enable verbose logging during parameter loading |\n\n## š£ Roadmap\n\n\nClick to expand\n\n| Task / Feature | Status |\n|---|---|\n| Canonical SSM path contract (`/////`) | ā Done |\n| Sync and async module registration | ā Done |\n| Paginated recursive parameter loading | ā Done |\n| Per-call namespace and instance overrides | ā Done |\n| Strict input validation with fail-fast errors | ā Done |\n| Dual ESM/CJS module output with source maps | ā Done |\n| Built-in ENamespace enum (90+ tokens) | ā Done |\n| Verbose logging mode | ā Done |\n| Automated semantic releases with backmerge | ā Done |\n| TTL-based parameter cache refresh | š§ In Progress |\n| Parameter change event subscriptions | š§ In Progress |\n| Batch `getMany()` API for multi-path lookups | š§ In Progress |\n| Optional Zod/class-validator schema validation on retrieved values | š§ In Progress |\n| Unit and integration test suite | š§ In Progress |\n\n\n\n## ā FAQ\n\n\nClick to expand\n\n### ā Frequently Asked Questions\n\n**Q: Does this module make SSM API calls on every `get()` invocation?**\n\nA: No. All parameters are loaded once at module initialization (startup) into an in-memory cache. The `get()` method performs a simple array lookup against the cached parameters ā there are zero runtime SSM API calls.\n\n---\n\n**Q: How does the module handle large numbers of parameters?**\n\nA: The `ParameterStoreService` automatically handles SSM API pagination. It continues fetching pages using `NextToken` until all parameters under `//` are loaded.\n\n---\n\n**Q: Can I use custom strings instead of the built-in enums?**\n\nA: Yes! Both `environment` and `namespace` accept `string` types in addition to `EEnvironment` and `ENamespace` enums. This allows you to use custom tokens like `\"my-custom-namespace\"` when the built-in options don't fit.\n\n---\n\n**Q: Which NestJS versions are supported?**\n\nA: The module supports NestJS v8, v9, v10, and v11 through a flexible peer dependency range (`^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0`).\n\n---\n\n**Q: Do I need to import the module in every feature module?**\n\nA: No. `ParameterStoreConfigModule` is decorated with `@Global()`, so once registered in your root `AppModule`, the `ParameterStoreConfigService` is injectable in any provider across your application.\n\n---\n\n**Q: What happens if a required segment (application, environment, etc.) is missing?**\n\nA: The module throws a descriptive error immediately at startup or at lookup time. It validates that no segment is `undefined`, `null`, empty, whitespace-only, or contains `/` characters.\n\n---\n\n**Q: How do I decrypt SecureString parameters?**\n\nA: Set `shouldDecryptParameters: true` in your module registration options. This passes `WithDecryption: true` to the SSM `GetParametersByPathCommand`.\n\n---\n\n**Q: Can I access parameters from a different application or environment?**\n\nA: Yes, but with a caveat. The `get()` method accepts per-call overrides for `application` and `environment`, but the in-memory cache only contains parameters loaded from the module's configured `//` prefix. To access parameters from a different prefix, you'd need to register a second module instance or ensure those parameters exist under the loaded prefix.\n\n\n\n## š License\nThis project is licensed under **MIT**.\n\n## š Acknowledgments\n## š Acknowledgments\n\n- [NestJS](https://nestjs.com/) ā The progressive Node.js framework that makes building server-side applications a joy\n- [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) ā The modular AWS SDK powering the SSM client\n- [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) ā The secure, hierarchical configuration storage service\n- [Semantic Release](https://github.com/semantic-release/semantic-release) ā Fully automated version management and package publishing\n- [Rollup](https://rollupjs.org/) ā The module bundler enabling dual ESM/CJS output\n- [ElsiKora](https://github.com/ElsiKora) ā The team behind this module and the broader tooling ecosystem\n\n---\n\n*Built with ā¤ļø for the NestJS community*\n\n---\n\n
![\"project-logo\"](\"https://6jft62zmy9nx2oea.public.blob.vercel-storage.com/nestjs-aws-parameter-store-config-uTW0f4g5XGnXSI5q6V99uzMjWtY1EX.png\")
\n![\"ElsiKora\"](\"https://img.shields.io/badge/MADE%20BY%20ElsiKora-333333.svg?style=for-the-badge\"){kind=icon}
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-3178C6.svg?style=for-the-badge&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-339933.svg?style=for-the-badge&logo=node.js&logoColor=white\"){kind=icon}
![\"NestJS\"](\"https://img.shields.io/badge/NestJS-E0234E.svg?style=for-the-badge&logo=nestjs&logoColor=white\"){kind=icon}
![\"AWS\"](\"https://img.shields.io/badge/AWS-232F3E.svg?style=for-the-badge&logo=amazon-aws&logoColor=white\"){kind=icon}
![\"npm\"](\"https://img.shields.io/badge/npm-CB3837.svg?style=for-the-badge&logo=npm&logoColor=white\"){kind=icon}
![\"Rollup\"](\"https://img.shields.io/badge/Rollup-EC4A3F.svg?style=for-the-badge&logo=rollup&logoColor=white\"){kind=icon}
![\"ESLint\"](\"https://img.shields.io/badge/ESLint-4B32C3.svg?style=for-the-badge&logo=eslint&logoColor=white\"){kind=icon}
![\"Prettier\"](\"https://img.shields.io/badge/Prettier-F7B93E.svg?style=for-the-badge&logo=prettier&logoColor=black\"){kind=icon}
![\"GitHub](\"https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=for-the-badge&logo=github-actions&logoColor=white\"){kind=icon}
![\"Git\"](\"https://img.shields.io/badge/Git-F05032.svg?style=for-the-badge&logo=git&logoColor=white\"){kind=icon}
\n