@rawnodes/config-loader 1.4.0 → 1.6.0

package/README.md

@@ -6,6 +6,8 @@ Flexible YAML configuration loader for Node.js applications with environment ove
 
 - **YAML Configuration** - Load config from YAML files with environment-specific overrides
 - **Environment Variables** - Replace `${VAR}` placeholders with env values
+- **HashiCorp Vault** - Read secrets from Vault using `${vault:path:field}` syntax
+- **AWS Secrets Manager** - Read secrets from AWS using `${aws:secret-name:field}` syntax
 - **Zod Validation** - Optional schema validation with detailed error messages
 - **Docker/K8s Ready** - Mount additional config files via `overrideDir`
 - **Secret Masking** - Automatic masking of sensitive values in logs
@@ -103,6 +105,21 @@ interface ConfigLoaderOptions<T> {
   // Remove empty strings and empty objects from config (default: false)
   // Useful for optional fields with ${VAR:} placeholders
   stripEmpty?: boolean;
+
+  // HashiCorp Vault options (requires loadConfigAsync)
+  vault?: {
+    endpoint: string;     // Vault server URL
+    roleId: string;       // AppRole role_id
+    secretId: string;     // AppRole secret_id
+    namespace?: string;   // Optional Vault Enterprise namespace
+  };
+
+  // AWS Secrets Manager options (requires loadConfigAsync)
+  aws?: {
+    region: string;          // AWS region
+    accessKeyId: string;     // AWS access key ID
+    secretAccessKey: string; // AWS secret access key
+  };
 }
 ```
 
@@ -161,6 +178,116 @@ const { config } = loadConfig({
 - Arrays: empty strings filtered out
 - Other falsy values (`0`, `false`, `null`) are preserved
 
+## HashiCorp Vault Integration
+
+Read secrets directly from HashiCorp Vault using AppRole authentication.
+
+### Setup
+
+```yaml
+# config/base.yml
+database:
+  host: localhost
+  password: ${vault:secret/data/api:DB_PASSWORD}
+  port: ${vault:secret/data/api:DB_PORT:5432}  # with default value
+```
+
+```typescript
+import { loadConfigAsync } from '@rawnodes/config-loader';
+
+const { config } = await loadConfigAsync({
+  configDir: './config',
+  vault: {
+    endpoint: 'https://vault.example.com',
+    roleId: process.env.VAULT_ROLE_ID!,
+    secretId: process.env.VAULT_SECRET_ID!,
+    namespace: 'optional-namespace',  // for Vault Enterprise
+  },
+});
+```
+
+### Syntax
+
+```
+${vault:PATH:FIELD}           - Required secret
+${vault:PATH:FIELD:DEFAULT}   - With default value (used if secret not found)
+```
+
+**Examples:**
+```yaml
+database:
+  # Read DB_PASSWORD from secret/data/api
+  password: ${vault:secret/data/api:DB_PASSWORD}
+
+  # With default value (supports colons in default)
+  url: ${vault:secret/data/db:URL:postgres://localhost:5432/app}
+
+  # Mix with env variables
+  host: ${DB_HOST:localhost}
+```
+
+### Notes
+
+- Use `loadConfigAsync()` instead of `loadConfig()` when using Vault
+- Secrets are cached per path during config load (multiple fields from same path = 1 API call)
+- Supports Vault KV v1 and v2 secret engines
+
+## AWS Secrets Manager Integration
+
+Read secrets from AWS Secrets Manager.
+
+### Setup
+
+```yaml
+# config/base.yml
+database:
+  password: ${aws:my-app/database:DB_PASSWORD}
+  host: ${aws:my-app/database:DB_HOST:localhost}
+api:
+  key: ${aws:my-app/api-key}  # plain string secret (no field)
+```
+
+```typescript
+import { loadConfigAsync } from '@rawnodes/config-loader';
+
+const { config } = await loadConfigAsync({
+  configDir: './config',
+  aws: {
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+```
+
+### Syntax
+
+```
+${aws:SECRET_NAME}              - Plain string secret (entire value)
+${aws:SECRET_NAME:FIELD}        - JSON secret, extract field
+${aws:SECRET_NAME:FIELD:DEFAULT} - With default value
+```
+
+**Examples:**
+```yaml
+database:
+  # JSON secret: {"DB_PASSWORD": "secret", "DB_USER": "admin"}
+  password: ${aws:my-app/database:DB_PASSWORD}
+  user: ${aws:my-app/database:DB_USER}
+
+  # Plain string secret (no field)
+  api_key: ${aws:my-app/api-key}
+
+  # With default value
+  host: ${aws:my-app/database:DB_HOST:localhost}
+```
+
+### Notes
+
+- Use `loadConfigAsync()` instead of `loadConfig()` when using AWS
+- Secrets are cached per secret name during config load
+- Supports both JSON and plain string secrets
+
 ## Zod Validation
 
 ```typescript
@@ -204,6 +331,39 @@ server:
 
 Files are merged in alphabetical order.
 
+## Environment Helpers
+
+### `env`
+
+Environment detection helpers:
+
+```typescript
+import { env } from '@rawnodes/config-loader';
+
+env.nodeEnv       // process.env.NODE_ENV || 'local'
+env.isProduction  // true if NODE_ENV === 'production'
+env.isDevelopment // true if NODE_ENV === 'development'
+env.isTest        // true if NODE_ENV === 'test'
+env.isLocal       // true if NODE_ENV is 'local' or not set
+```
+
+### Usage with Vault/AWS
+
+```typescript
+import { loadConfigAsync, env } from '@rawnodes/config-loader';
+
+const { config } = await loadConfigAsync({
+  configDir: './config',
+  vault: !env.isLocal && {
+    endpoint: process.env.VAULT_ENDPOINT,
+    roleId: process.env.VAULT_ROLE_ID,
+    secretId: process.env.VAULT_SECRET_ID,
+  },
+});
+// If any value is missing, you'll get a clear error:
+// "Vault endpoint is not set" or "Vault roleId is not set"
+```
+
 ## NestJS Integration
 
 ```typescript
@@ -234,7 +394,7 @@ export class ConfigModule {}
 
 ### `loadConfig<T>(options?): ConfigLoaderResult<T>`
 
-Loads and merges configuration files.
+Loads and merges configuration files synchronously.
 
 **Returns:**
 ```typescript
@@ -245,6 +405,21 @@ interface ConfigLoaderResult<T> {
 }
 ```
 
+### `loadConfigAsync<T>(options?): Promise<ConfigLoaderResult<T>>`
+
+Async version with Vault support. Required when using `vault` option.
+
+```typescript
+const { config } = await loadConfigAsync({
+  configDir: './config',
+  vault: {
+    endpoint: 'https://vault.example.com',
+    roleId: 'role-id',
+    secretId: 'secret-id',
+  },
+});
+```
+
 ### `maskSecrets(obj): unknown`
 
 Masks sensitive values in an object. Useful for logging.

package/dist/index.d.mts

@@ -1,5 +1,39 @@
 import { z } from 'zod';
 
+interface VaultOptions {
+    /**
+     * Vault server endpoint URL
+     * @example 'https://vault.example.com'
+     */
+    endpoint: string;
+    /**
+     * AppRole role_id for authentication
+     */
+    roleId: string;
+    /**
+     * AppRole secret_id for authentication
+     */
+    secretId: string;
+    /**
+     * Optional namespace for Vault Enterprise
+     */
+    namespace?: string;
+}
+interface AwsSecretsOptions {
+    /**
+     * AWS region
+     * @example 'us-east-1'
+     */
+    region: string;
+    /**
+     * AWS access key ID
+     */
+    accessKeyId: string;
+    /**
+     * AWS secret access key
+     */
+    secretAccessKey: string;
+}
 interface DotenvOptions {
     /**
      * Path to .env file
@@ -63,6 +97,18 @@ interface ConfigLoaderOptions<T = unknown> {
      * @default false
      */
     stripEmpty?: boolean;
+    /**
+     * HashiCorp Vault options for secret retrieval
+     * If provided, ${vault:path:field} placeholders will be resolved
+     * Requires using loadConfigAsync() instead of loadConfig()
+     */
+    vault?: VaultOptions;
+    /**
+     * AWS Secrets Manager options for secret retrieval
+     * If provided, ${aws:secret-name:field} placeholders will be resolved
+     * Requires using loadConfigAsync() instead of loadConfig()
+     */
+    aws?: AwsSecretsOptions;
 }
 interface ConfigLoaderResult<T> {
     config: T;
@@ -71,14 +117,48 @@ interface ConfigLoaderResult<T> {
 }
 
 declare function loadConfig<T>(options?: ConfigLoaderOptions<T>): ConfigLoaderResult<T>;
+declare function loadConfigAsync<T>(options?: ConfigLoaderOptions<T>): Promise<ConfigLoaderResult<T>>;
 
 type DeepObject = Record<string, unknown>;
 declare function deepMerge(base: DeepObject, override: DeepObject): DeepObject;
 
-declare function replacePlaceholders(obj: unknown): unknown;
+interface VaultSecretCache {
+    [path: string]: Record<string, unknown>;
+}
+interface VaultClient {
+    fetchSecrets(obj: unknown): Promise<VaultSecretCache>;
+    getSecret(path: string, field: string): unknown;
+}
+declare function createVaultClient(options: VaultOptions): Promise<VaultClient>;
+
+interface AwsSecretsCache {
+    [secretName: string]: string | Record<string, unknown>;
+}
+interface AwsSecretsClient {
+    fetchSecrets(obj: unknown): Promise<AwsSecretsCache>;
+    getSecret(secretName: string, field?: string): unknown;
+}
+declare function createAwsSecretsClient(options: AwsSecretsOptions): Promise<AwsSecretsClient>;
+
+interface ReplacePlaceholdersOptions {
+    vaultClient?: VaultClient;
+    awsClient?: AwsSecretsClient;
+}
+declare function replacePlaceholders(obj: unknown, options?: ReplacePlaceholdersOptions): unknown;
 
 declare function maskSecrets(obj: unknown): unknown;
 
 declare function stripEmpty(obj: unknown): unknown;
 
-export { type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, deepMerge, loadConfig, maskSecrets, replacePlaceholders, stripEmpty };
+/**
+ * Environment helpers
+ */
+declare const env: {
+    readonly nodeEnv: string;
+    readonly isProduction: boolean;
+    readonly isDevelopment: boolean;
+    readonly isTest: boolean;
+    readonly isLocal: boolean;
+};
+
+export { type AwsSecretsCache, type AwsSecretsClient, type AwsSecretsOptions, type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, type VaultClient, type VaultOptions, type VaultSecretCache, createAwsSecretsClient, createVaultClient, deepMerge, env, loadConfig, loadConfigAsync, maskSecrets, replacePlaceholders, stripEmpty };

package/dist/index.d.ts

@@ -1,5 +1,39 @@
 import { z } from 'zod';
 
+interface VaultOptions {
+    /**
+     * Vault server endpoint URL
+     * @example 'https://vault.example.com'
+     */
+    endpoint: string;
+    /**
+     * AppRole role_id for authentication
+     */
+    roleId: string;
+    /**
+     * AppRole secret_id for authentication
+     */
+    secretId: string;
+    /**
+     * Optional namespace for Vault Enterprise
+     */
+    namespace?: string;
+}
+interface AwsSecretsOptions {
+    /**
+     * AWS region
+     * @example 'us-east-1'
+     */
+    region: string;
+    /**
+     * AWS access key ID
+     */
+    accessKeyId: string;
+    /**
+     * AWS secret access key
+     */
+    secretAccessKey: string;
+}
 interface DotenvOptions {
     /**
      * Path to .env file
@@ -63,6 +97,18 @@ interface ConfigLoaderOptions<T = unknown> {
      * @default false
      */
     stripEmpty?: boolean;
+    /**
+     * HashiCorp Vault options for secret retrieval
+     * If provided, ${vault:path:field} placeholders will be resolved
+     * Requires using loadConfigAsync() instead of loadConfig()
+     */
+    vault?: VaultOptions;
+    /**
+     * AWS Secrets Manager options for secret retrieval
+     * If provided, ${aws:secret-name:field} placeholders will be resolved
+     * Requires using loadConfigAsync() instead of loadConfig()
+     */
+    aws?: AwsSecretsOptions;
 }
 interface ConfigLoaderResult<T> {
     config: T;
@@ -71,14 +117,48 @@ interface ConfigLoaderResult<T> {
 }
 
 declare function loadConfig<T>(options?: ConfigLoaderOptions<T>): ConfigLoaderResult<T>;
+declare function loadConfigAsync<T>(options?: ConfigLoaderOptions<T>): Promise<ConfigLoaderResult<T>>;
 
 type DeepObject = Record<string, unknown>;
 declare function deepMerge(base: DeepObject, override: DeepObject): DeepObject;
 
-declare function replacePlaceholders(obj: unknown): unknown;
+interface VaultSecretCache {
+    [path: string]: Record<string, unknown>;
+}
+interface VaultClient {
+    fetchSecrets(obj: unknown): Promise<VaultSecretCache>;
+    getSecret(path: string, field: string): unknown;
+}
+declare function createVaultClient(options: VaultOptions): Promise<VaultClient>;
+
+interface AwsSecretsCache {
+    [secretName: string]: string | Record<string, unknown>;
+}
+interface AwsSecretsClient {
+    fetchSecrets(obj: unknown): Promise<AwsSecretsCache>;
+    getSecret(secretName: string, field?: string): unknown;
+}
+declare function createAwsSecretsClient(options: AwsSecretsOptions): Promise<AwsSecretsClient>;
+
+interface ReplacePlaceholdersOptions {
+    vaultClient?: VaultClient;
+    awsClient?: AwsSecretsClient;
+}
+declare function replacePlaceholders(obj: unknown, options?: ReplacePlaceholdersOptions): unknown;
 
 declare function maskSecrets(obj: unknown): unknown;
 
 declare function stripEmpty(obj: unknown): unknown;
 
-export { type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, deepMerge, loadConfig, maskSecrets, replacePlaceholders, stripEmpty };
+/**
+ * Environment helpers
+ */
+declare const env: {
+    readonly nodeEnv: string;
+    readonly isProduction: boolean;
+    readonly isDevelopment: boolean;
+    readonly isTest: boolean;
+    readonly isLocal: boolean;
+};
+
+export { type AwsSecretsCache, type AwsSecretsClient, type AwsSecretsOptions, type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, type VaultClient, type VaultOptions, type VaultSecretCache, createAwsSecretsClient, createVaultClient, deepMerge, env, loadConfig, loadConfigAsync, maskSecrets, replacePlaceholders, stripEmpty };