@rawnodes/config-loader 1.3.0 → 1.5.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
@@ -99,6 +101,25 @@ interface ConfigLoaderOptions<T> {
   // Directory with additional YAML files to merge (default: '/etc/app/config')
   // Set to false to disable
   overrideDir?: string | false;
+
+  // 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
+  };
 }
 ```
 
@@ -113,6 +134,160 @@ database:
   password: ${DB_PASSWORD}  # Required - throws if not set
 ```
 
+## Optional Fields
+
+Use `${VAR:}` (empty default) with `stripEmpty: true` to support optional fields:
+
+```yaml
+# config/base.yml
+server:
+  port: 3000
+
+monitoring:
+  serviceId: ${MONITORING_SERVICE_ID:}
+  apiKey: ${MONITORING_API_KEY:}
+  healthcheckUrls:
+    cleanup: ${MONITORING_CLEANUP_URL:}
+    sync: ${MONITORING_SYNC_URL:}
+```
+
+```typescript
+const schema = z.object({
+  server: z.object({ port: z.number() }),
+  monitoring: z.object({
+    serviceId: z.string(),
+    apiKey: z.string(),
+    healthcheckUrls: z.object({
+      cleanup: z.string().url().optional(),
+      sync: z.string().url().optional(),
+    }).optional(),
+  }).optional(),
+});
+
+const { config } = loadConfig({
+  schema,
+  stripEmpty: true,  // Empty strings → undefined, empty objects removed
+});
+
+// If no MONITORING_* env vars are set, config.monitoring will be undefined
+```
+
+**How `stripEmpty` works:**
+- `""` (empty string) → `undefined`
+- Objects with all `undefined` values → removed
+- 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
@@ -186,7 +361,7 @@ export class ConfigModule {}
 
 ### `loadConfig<T>(options?): ConfigLoaderResult<T>`
 
-Loads and merges configuration files.
+Loads and merges configuration files synchronously.
 
 **Returns:**
 ```typescript
@@ -197,6 +372,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.
@@ -220,6 +410,20 @@ Deep merges two objects.
 
 Replaces `${VAR}` placeholders with environment variable values.
 
+### `stripEmpty(obj): unknown`
+
+Removes empty strings and empty objects recursively. Useful for cleaning up config before validation.
+
+```typescript
+import { stripEmpty } from '@rawnodes/config-loader';
+
+const cleaned = stripEmpty({
+  server: { port: 3000 },
+  optional: { url: '', name: '' },
+});
+// { server: { port: 3000 } }
+```
+
 ## License
 
 MIT

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
@@ -55,6 +89,26 @@ interface ConfigLoaderOptions<T = unknown> {
      * @default '/etc/app/config'
      */
     overrideDir?: string | false;
+    /**
+     * Remove empty strings and empty objects from config
+     * Useful for optional fields with ${VAR:} placeholders
+     * - Empty strings "" become undefined
+     * - Objects with all undefined values are removed
+     * @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;
@@ -63,12 +117,37 @@ 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;
 
-export { type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, deepMerge, loadConfig, maskSecrets, replacePlaceholders };
+declare function stripEmpty(obj: unknown): unknown;
+
+export { type AwsSecretsCache, type AwsSecretsClient, type AwsSecretsOptions, type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, type VaultClient, type VaultOptions, type VaultSecretCache, createAwsSecretsClient, createVaultClient, deepMerge, 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
@@ -55,6 +89,26 @@ interface ConfigLoaderOptions<T = unknown> {
      * @default '/etc/app/config'
      */
     overrideDir?: string | false;
+    /**
+     * Remove empty strings and empty objects from config
+     * Useful for optional fields with ${VAR:} placeholders
+     * - Empty strings "" become undefined
+     * - Objects with all undefined values are removed
+     * @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;
@@ -63,12 +117,37 @@ 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;
 
-export { type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, deepMerge, loadConfig, maskSecrets, replacePlaceholders };
+declare function stripEmpty(obj: unknown): unknown;
+
+export { type AwsSecretsCache, type AwsSecretsClient, type AwsSecretsOptions, type ConfigLoaderOptions, type ConfigLoaderResult, type DotenvOptions, type VaultClient, type VaultOptions, type VaultSecretCache, createAwsSecretsClient, createVaultClient, deepMerge, loadConfig, loadConfigAsync, maskSecrets, replacePlaceholders, stripEmpty };