@rawnodes/config-loader 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RawNodes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# @rawnodes/config-loader
+
+Flexible YAML configuration loader for Node.js applications with environment overrides, Zod validation, and Docker-friendly features.
+
+## Features
+
+- **YAML Configuration** - Load config from YAML files with environment-specific overrides
+- **Environment Variables** - Replace `${VAR}` placeholders with env values
+- **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
+- **TypeScript First** - Full type safety with generics
+
+## Installation
+
+```bash
+pnpm add @rawnodes/config-loader
+# or
+npm install @rawnodes/config-loader
+```
+
+For Zod validation (optional):
+```bash
+pnpm add zod
+```
+
+## Quick Start
+
+### 1. Create config files
+
+```yaml
+# config/base.yml
+server:
+  port: 3000
+  host: localhost
+
+database:
+  host: localhost
+  port: 5432
+  name: myapp
+```
+
+```yaml
+# config/production.yml
+server:
+  host: 0.0.0.0
+
+database:
+  host: ${DATABASE_HOST}
+  password: ${DATABASE_PASSWORD}
+```
+
+### 2. Load configuration
+
+```typescript
+import { loadConfig } from '@rawnodes/config-loader';
+
+interface AppConfig {
+  server: { port: number; host: string };
+  database: { host: string; port: number; name: string; password?: string };
+}
+
+const { config } = loadConfig<AppConfig>({
+  configDir: './config',
+  dotenv: true,
+});
+
+console.log(config.server.port); // 3000
+```
+
+## Configuration Options
+
+```typescript
+interface ConfigLoaderOptions<T> {
+  // Directory with config files (default: process.cwd())
+  configDir?: string;
+
+  // Base config filename without extension (default: 'base')
+  baseFileName?: string;
+
+  // Environment name (default: process.env.NODE_ENV || 'local')
+  environment?: string;
+
+  // File extension (default: 'yml')
+  extension?: 'yml' | 'yaml';
+
+  // Custom post-processing function
+  postProcess?: (config: T) => T;
+
+  // Zod schema for validation
+  schema?: z.ZodType<T>;
+
+  // Logger callback (config will be logged with masked secrets)
+  logger?: (message: string) => void;
+
+  // Load .env file (default: false)
+  dotenv?: boolean | { path?: string };
+
+  // Directory with additional YAML files to merge (default: '/etc/app/config')
+  // Set to false to disable
+  overrideDir?: string | false;
+}
+```
+
+## Environment Variables
+
+Use `${VAR}` syntax with optional defaults:
+
+```yaml
+database:
+  host: ${DB_HOST:localhost}
+  port: ${DB_PORT:5432}
+  password: ${DB_PASSWORD}  # Required - throws if not set
+```
+
+## Zod Validation
+
+```typescript
+import { z } from 'zod';
+import { loadConfig } from '@rawnodes/config-loader';
+
+const AppConfigSchema = z.object({
+  server: z.object({
+    port: z.number().min(1).max(65535),
+    host: z.string(),
+  }),
+  database: z.object({
+    host: z.string(),
+    port: z.number(),
+    name: z.string(),
+    password: z.string().optional(),
+  }),
+});
+
+type AppConfig = z.infer<typeof AppConfigSchema>;
+
+const { config } = loadConfig<AppConfig>({
+  schema: AppConfigSchema,
+  logger: console.log,
+});
+```
+
+## Docker/Kubernetes Override
+
+Mount additional config files in `/etc/app/config/`:
+
+```yaml
+# /etc/app/config/01-secrets.yml
+database:
+  password: super-secret
+
+# /etc/app/config/02-overrides.yml
+server:
+  port: 8080
+```
+
+Files are merged in alphabetical order.
+
+## NestJS Integration
+
+```typescript
+// config.module.ts
+import { Module, Global } from '@nestjs/common';
+import { loadConfig } from '@rawnodes/config-loader';
+import { AppConfigSchema, AppConfig } from './app.config';
+
+const { config } = loadConfig<AppConfig>({
+  schema: AppConfigSchema,
+  dotenv: true,
+});
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: 'CONFIG',
+      useValue: config,
+    },
+  ],
+  exports: ['CONFIG'],
+})
+export class ConfigModule {}
+```
+
+## API
+
+### `loadConfig<T>(options?): ConfigLoaderResult<T>`
+
+Loads and merges configuration files.
+
+**Returns:**
+```typescript
+interface ConfigLoaderResult<T> {
+  config: T;           // Loaded configuration
+  environment: string; // Resolved environment name
+  configDir: string;   // Resolved config directory path
+}
+```
+
+### `maskSecrets(obj): unknown`
+
+Masks sensitive values in an object. Useful for logging.
+
+```typescript
+import { maskSecrets } from '@rawnodes/config-loader';
+
+const masked = maskSecrets({
+  user: 'admin',
+  password: 'secret123',
+  url: 'postgres://user:pass@localhost/db',
+});
+// { user: 'admin', password: 'se***23', url: 'postgres://user:***@localhost/db' }
+```
+
+### `deepMerge(base, override): object`
+
+Deep merges two objects.
+
+### `replacePlaceholders(obj): unknown`
+
+Replaces `${VAR}` placeholders with environment variable values.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { loadConfig } from './loader.js';
+export { deepMerge, replacePlaceholders, maskSecrets } from './utils/index.js';
+export type { ConfigLoaderOptions, ConfigLoaderResult, DotenvOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/E,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { loadConfig } from './loader.js';
+export { deepMerge, replacePlaceholders, maskSecrets } from './utils/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,3 @@
+import type { ConfigLoaderOptions, ConfigLoaderResult } from './types.js';
+export declare function loadConfig<T>(options?: ConfigLoaderOptions<T>): ConfigLoaderResult<T>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAW1E,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAE,mBAAmB,CAAC,CAAC,CAAM,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAuDzF"}

package/dist/loader.js

@@ -0,0 +1,100 @@
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import * as yaml from 'js-yaml';
+import * as dotenv from 'dotenv';
+import { join } from 'path';
+import { deepMerge, replacePlaceholders, maskSecrets } from './utils/index.js';
+const DEFAULT_OPTIONS = {
+    configDir: process.cwd(),
+    baseFileName: 'base',
+    environment: process.env.NODE_ENV || 'local',
+    extension: 'yml',
+    overrideDir: '/etc/app/config',
+};
+export function loadConfig(options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { configDir, baseFileName, environment, extension } = opts;
+    // Load .env if requested
+    if (options.dotenv) {
+        loadDotenv(options.dotenv, environment);
+    }
+    const resolvedConfigDir = resolveConfigDir(configDir);
+    const baseConfig = loadYamlFile(resolvedConfigDir, `${baseFileName}.${extension}`);
+    const envConfig = loadYamlFile(resolvedConfigDir, `${environment}.${extension}`);
+    let mergedConfig = deepMerge(baseConfig, envConfig);
+    // Load override files from directory
+    const overrideDir = options.overrideDir !== false ? (options.overrideDir ?? DEFAULT_OPTIONS.overrideDir) : null;
+    if (overrideDir) {
+        const overrideConfigs = loadOverrideDir(overrideDir);
+        for (const override of overrideConfigs) {
+            mergedConfig = deepMerge(mergedConfig, override);
+        }
+    }
+    let config = replacePlaceholders(mergedConfig);
+    // Post-process
+    if (options.postProcess) {
+        config = options.postProcess(config);
+    }
+    // Validate with Zod schema
+    if (options.schema) {
+        const result = options.schema.safeParse(config);
+        if (!result.success) {
+            const errors = result.error.issues
+                .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
+                .join('\n');
+            throw new Error(`Config validation failed:\n${errors}`);
+        }
+        config = result.data;
+    }
+    // Log config with masked secrets
+    if (options.logger) {
+        const maskedConfig = maskSecrets(config);
+        options.logger(`Config loaded (${environment}):\n${JSON.stringify(maskedConfig, null, 2)}`);
+    }
+    return {
+        config,
+        environment,
+        configDir: resolvedConfigDir,
+    };
+}
+function loadDotenv(dotenvOption, environment) {
+    let envPath;
+    if (typeof dotenvOption === 'object' && dotenvOption.path) {
+        envPath = dotenvOption.path;
+    }
+    else {
+        envPath = environment === 'production' ? '.env' : `.env.${environment}`;
+    }
+    dotenv.config({ path: envPath });
+}
+function resolveConfigDir(configDir) {
+    const possiblePaths = [
+        join(configDir, 'src', 'config'),
+        join(configDir, 'dist', 'config'),
+        join(configDir, 'config'),
+        configDir,
+    ];
+    for (const path of possiblePaths) {
+        if (existsSync(join(path, 'base.yml')) || existsSync(join(path, 'base.yaml'))) {
+            return path;
+        }
+    }
+    throw new Error(`Config files not found. Searched in:\n${possiblePaths.map((p) => `  - ${p}`).join('\n')}`);
+}
+function loadYamlFile(dir, filename) {
+    const filePath = join(dir, filename);
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    const content = readFileSync(filePath, 'utf8');
+    return yaml.load(content) || {};
+}
+function loadOverrideDir(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
+        .sort();
+    return files.map((file) => loadYamlFile(dir, file));
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,eAAe,GAAG;IACtB,SAAS,EAAE,OAAO,CAAC,GAAG,EAAE;IACxB,YAAY,EAAE,MAAM;IACpB,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,OAAO;IAC5C,SAAS,EAAE,KAAc;IACzB,WAAW,EAAE,iBAAiB;CAC/B,CAAC;AAEF,MAAM,UAAU,UAAU,CAAI,UAAkC,EAAE;IAChE,MAAM,IAAI,GAAG,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,EAAE,CAAC;IAChD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAEjE,yBAAyB;IACzB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAEtD,MAAM,UAAU,GAAG,YAAY,CAAC,iBAAiB,EAAE,GAAG,YAAY,IAAI,SAAS,EAAE,CAAC,CAAC;IACnF,MAAM,SAAS,GAAG,YAAY,CAAC,iBAAiB,EAAE,GAAG,WAAW,IAAI,SAAS,EAAE,CAAC,CAAC;IAEjF,IAAI,YAAY,GAAG,SAAS,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAEpD,qCAAqC;IACrC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,IAAI,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChH,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,eAAe,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;QACrD,KAAK,MAAM,QAAQ,IAAI,eAAe,EAAE,CAAC;YACvC,YAAY,GAAG,SAAS,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,IAAI,MAAM,GAAG,mBAAmB,CAAC,YAAY,CAAM,CAAC;IAEpD,eAAe;IACf,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,2BAA2B;IAC3B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;iBAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;iBACnD,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,iCAAiC;IACjC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACzC,OAAO,CAAC,MAAM,CAAC,kBAAkB,WAAW,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,OAAO;QACL,MAAM;QACN,WAAW;QACX,SAAS,EAAE,iBAAiB;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,YAAyC,EACzC,WAAmB;IAEnB,IAAI,OAAe,CAAC;IAEpB,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC;QAC1D,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC;IAC9B,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,WAAW,EAAE,CAAC;IAC1E,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,gBAAgB,CAAC,SAAiB;IACzC,MAAM,aAAa,GAAG;QACpB,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC;QAChC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC;QACzB,SAAS;KACV,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC;YAC9E,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,yCAAyC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3F,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,GAAW,EAAE,QAAgB;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAErC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,OAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,CAA6B,IAAI,EAAE,CAAC;AAC/D,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;SACxD,IAAI,EAAE,CAAC;IAEV,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AACtD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+import type { z } from 'zod';
+export interface DotenvOptions {
+    /**
+     * Path to .env file
+     * @default auto-detected based on NODE_ENV
+     */
+    path?: string;
+}
+export interface ConfigLoaderOptions<T = unknown> {
+    /**
+     * Directory where config files are located
+     * @default process.cwd()
+     */
+    configDir?: string;
+    /**
+     * Base config filename (without extension)
+     * @default 'base'
+     */
+    baseFileName?: string;
+    /**
+     * Environment name for environment-specific config
+     * @default process.env.NODE_ENV || 'local'
+     */
+    environment?: string;
+    /**
+     * File extension
+     * @default 'yml'
+     */
+    extension?: 'yml' | 'yaml';
+    /**
+     * Custom post-processing function to transform the loaded config
+     */
+    postProcess?: (config: T) => T;
+    /**
+     * Zod schema for validation
+     * If provided, config will be validated against this schema
+     */
+    schema?: z.ZodType<T>;
+    /**
+     * Logger callback for logging loaded config
+     * Config will be logged with secrets masked
+     */
+    logger?: (message: string) => void;
+    /**
+     * Load .env file before loading config
+     * - true: auto-detect .env file based on NODE_ENV
+     * - object: custom options
+     */
+    dotenv?: boolean | DotenvOptions;
+    /**
+     * Directory with additional YAML files to merge
+     * All *.yml files in this directory will be merged (sorted by filename)
+     * Useful for Docker/Kubernetes config mounts
+     * @default '/etc/app/config'
+     */
+    overrideDir?: string | false;
+}
+export interface ConfigLoaderResult<T> {
+    config: T;
+    environment: string;
+    configDir: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAE3B;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IAE/B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAEtB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAEjC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/deep-merge.d.ts

@@ -0,0 +1,4 @@
+type DeepObject = Record<string, unknown>;
+export declare function deepMerge(base: DeepObject, override: DeepObject): DeepObject;
+export {};
+//# sourceMappingURL=deep-merge.d.ts.map

package/dist/utils/deep-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-merge.d.ts","sourceRoot":"","sources":["../../src/utils/deep-merge.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,CAe5E"}

package/dist/utils/deep-merge.js

@@ -0,0 +1,18 @@
+export function deepMerge(base, override) {
+    const merged = { ...base };
+    for (const key in override) {
+        const overrideValue = override[key];
+        const baseValue = base[key];
+        if (isPlainObject(overrideValue) && isPlainObject(baseValue)) {
+            merged[key] = deepMerge(baseValue, overrideValue);
+        }
+        else {
+            merged[key] = overrideValue;
+        }
+    }
+    return merged;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=deep-merge.js.map

package/dist/utils/deep-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-merge.js","sourceRoot":"","sources":["../../src/utils/deep-merge.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,SAAS,CAAC,IAAgB,EAAE,QAAoB;IAC9D,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;IAE3B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QAE5B,IAAI,aAAa,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7D,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,SAAuB,EAAE,aAA2B,CAAC,CAAC;QAChF,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/utils/env-replacer.d.ts

@@ -0,0 +1,2 @@
+export declare function replacePlaceholders(obj: unknown): unknown;
+//# sourceMappingURL=env-replacer.d.ts.map

package/dist/utils/env-replacer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-replacer.d.ts","sourceRoot":"","sources":["../../src/utils/env-replacer.ts"],"names":[],"mappings":"AAEA,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAkBzD"}

package/dist/utils/env-replacer.js

@@ -0,0 +1,42 @@
+const ENV_PLACEHOLDER_REGEX = /\${(.*?)}/g;
+export function replacePlaceholders(obj) {
+    if (typeof obj === 'string') {
+        return replaceStringPlaceholders(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => replacePlaceholders(item));
+    }
+    if (isPlainObject(obj)) {
+        const result = {};
+        for (const key of Object.keys(obj)) {
+            result[key] = replacePlaceholders(obj[key]);
+        }
+        return result;
+    }
+    return obj;
+}
+function replaceStringPlaceholders(str) {
+    return str.replace(ENV_PLACEHOLDER_REGEX, (match, key) => {
+        const [envKey, ...rest] = key.split(':');
+        const defaultValue = rest.length > 0 ? rest.join(':') : undefined;
+        const envValue = process.env[envKey];
+        let value;
+        if (envValue !== undefined) {
+            value = envValue;
+        }
+        else if (defaultValue !== undefined) {
+            value = defaultValue;
+        }
+        else {
+            throw new Error(`Environment variable "${envKey}" is not defined and no default value provided`);
+        }
+        if (value.includes('${')) {
+            return replacePlaceholders(value);
+        }
+        return value;
+    });
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=env-replacer.js.map

package/dist/utils/env-replacer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-replacer.js","sourceRoot":"","sources":["../../src/utils/env-replacer.ts"],"names":[],"mappings":"AAAA,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAE3C,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,yBAAyB,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,yBAAyB,CAAC,GAAW;IAC5C,OAAO,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvD,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAErC,IAAI,KAAa,CAAC;QAClB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,KAAK,GAAG,QAAQ,CAAC;QACnB,CAAC;aAAM,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YACtC,KAAK,GAAG,YAAY,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,gDAAgD,CAAC,CAAC;QACnG,CAAC;QAED,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO,mBAAmB,CAAC,KAAK,CAAW,CAAC;QAC9C,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { deepMerge } from './deep-merge.js';
+export { replacePlaceholders } from './env-replacer.js';
+export { maskSecrets } from './mask-secrets.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export { deepMerge } from './deep-merge.js';
+export { replacePlaceholders } from './env-replacer.js';
+export { maskSecrets } from './mask-secrets.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/utils/mask-secrets.d.ts

@@ -0,0 +1,2 @@
+export declare function maskSecrets(obj: unknown): unknown;
+//# sourceMappingURL=mask-secrets.d.ts.map

package/dist/utils/mask-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask-secrets.d.ts","sourceRoot":"","sources":["../../src/utils/mask-secrets.ts"],"names":[],"mappings":"AAIA,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAuBjD"}

package/dist/utils/mask-secrets.js

@@ -0,0 +1,49 @@
+const SECRET_PATTERNS = ['token', 'password', 'secret', 'key', 'apikey', 'api_key', 'credential'];
+const URL_WITH_CREDENTIALS_REGEX = /^([a-z]+:\/\/)([^:]+):([^@]+)@(.+)$/i;
+export function maskSecrets(obj) {
+    if (typeof obj === 'string') {
+        return maskUrlCredentials(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => maskSecrets(item));
+    }
+    if (isPlainObject(obj)) {
+        const result = {};
+        for (const key of Object.keys(obj)) {
+            const value = obj[key];
+            if (isSecretKey(key)) {
+                result[key] = maskValue(value);
+            }
+            else {
+                result[key] = maskSecrets(value);
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+function isSecretKey(key) {
+    const lowerKey = key.toLowerCase();
+    return SECRET_PATTERNS.some((pattern) => lowerKey.includes(pattern));
+}
+function maskValue(value) {
+    if (typeof value !== 'string') {
+        return '***';
+    }
+    if (value.length <= 4) {
+        return '***';
+    }
+    return value.slice(0, 2) + '***' + value.slice(-2);
+}
+function maskUrlCredentials(url) {
+    const match = url.match(URL_WITH_CREDENTIALS_REGEX);
+    if (match) {
+        const [, protocol, user, , host] = match;
+        return `${protocol}${user}:***@${host}`;
+    }
+    return url;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=mask-secrets.js.map

package/dist/utils/mask-secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask-secrets.js","sourceRoot":"","sources":["../../src/utils/mask-secrets.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AAElG,MAAM,0BAA0B,GAAG,sCAAsC,CAAC;AAE1E,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACnC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAW;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACpD,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,AAAD,EAAG,IAAI,CAAC,GAAG,KAAK,CAAC;QACzC,OAAO,GAAG,QAAQ,GAAG,IAAI,QAAQ,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@rawnodes/config-loader",
+  "version": "1.0.0",
+  "description": "Flexible YAML config loader with environment overrides, Zod validation, and Docker-friendly features",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "config",
+    "configuration",
+    "yaml",
+    "environment",
+    "dotenv",
+    "zod",
+    "typescript",
+    "docker",
+    "kubernetes"
+  ],
+  "author": "RawNodes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rawnodes/config-loader.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "js-yaml": "^4.1.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0",
+    "zod": "^3.24.0"
+  }
+}