yaml-dotenv

Библиотека для замены переменных окружения в YAML-конфигурации. Позволяет использовать переменные окружения в YAML файлах с синтаксисом ${VAR_NAME} и поддержкой значений по умолчанию ${VAR_NAME:-default}.

📦 Установка

npm install yaml-dotenv
# или
pnpm install yaml-dotenv
# или
yarn add yaml-dotenv

✨ Возможности

• 🔄 Замена переменных окружения в YAML-контенте
• 🎯 Поддержка значений по умолчанию ${VAR_NAME:-default}
• 🛡️ Безопасная обработка отсутствующих переменных
• 📝 Поддержка пустых переменных окружения
• 🚀 Простой и понятный API
• ✅ Полное покрытие тестами

🚀 Быстрый старт

import { YamlDotEnv } from "yaml-dotenv";

// Устанавливаем переменные окружения
process.env.DB_HOST = "localhost";
process.env.DB_PORT = "5432";

// YAML конфигурация с переменными
const yamlContent = `
database:
  host: \${DB_HOST}
  port: \${DB_PORT}
  name: \${DB_NAME:-myapp}
`;

// Заменяем переменные на их значения
const result = YamlDotEnv.convertTo(yamlContent);

console.log(result);
// Результат:
// database:
//   host: localhost
//   port: 5432
//   name: myapp

📚 Использование

Базовая замена переменных

Используйте синтаксис ${VARIABLE_NAME} для вставки значений переменных окружения:

import { YamlDotEnv } from "yaml-dotenv";

process.env.APP_PORT = "3000";
process.env.APP_HOST = "localhost";

const yaml = `
server:
  host: \${APP_HOST}
  port: \${APP_PORT}
`;

const result = YamlDotEnv.convertTo(yaml);
// server:
//   host: localhost
//   port: 3000

Значения по умолчанию

Используйте синтаксис ${VARIABLE_NAME:-default_value} для указания значения по умолчанию:

import { YamlDotEnv } from "yaml-dotenv";

// CLIENT_PORT не определена
const yaml = `
server:
  port: \${CLIENT_PORT:-8080}
`;

const result = YamlDotEnv.convertTo(yaml);
// server:
//   port: 8080

Если переменная определена, используется её значение:

process.env.CLIENT_PORT = "3000";

const yaml = `
server:
  port: \${CLIENT_PORT:-8080}
`;

const result = YamlDotEnv.convertTo(yaml);
// server:
//   port: 3000

Несколько переменных

Можно использовать несколько переменных в одной строке:

process.env.HOST = "localhost";
process.env.PORT = "8080";

const yaml = `url: \${HOST}:\${PORT}`;

const result = YamlDotEnv.convertTo(yaml);
// url: localhost:8080

Отсутствующие переменные

Если переменная не определена и нет значения по умолчанию, используется пустая строка:

// UNDEFINED_VAR не определена

const yaml = `value: \${UNDEFINED_VAR}`;

const result = YamlDotEnv.convertTo(yaml);
// value: 

Пустые переменные

Пустые переменные окружения ("") обрабатываются как определённые значения:

process.env.EMPTY_VAR = "";

const yaml = `value: \${EMPTY_VAR:-default}`;

const result = YamlDotEnv.convertTo(yaml);
// value:    (используется пустая строка, а не default)

🔧 Примеры использования

Конфигурация базы данных

import { YamlDotEnv } from "yaml-dotenv";
import { readFileSync } from "fs";

// Загружаем YAML файл
const yamlContent = readFileSync("./config/database.yaml", "utf-8");

// Устанавливаем переменные окружения
process.env.DB_HOST = "db.example.com";
process.env.DB_PORT = "5432";
process.env.DB_USER = "admin";
process.env.DB_PASSWORD = "secret123";

// Заменяем переменные
const config = YamlDotEnv.convertTo(yamlContent);

database.yaml:

database:
  host: ${DB_HOST}
  port: ${DB_PORT}
  user: ${DB_USER}
  password: ${DB_PASSWORD}
  pool_size: ${DB_POOL_SIZE:-10}
  ssl: ${DB_SSL:-true}

Конфигурация микросервисов

import { YamlDotEnv } from "yaml-dotenv";
import * as yaml from "js-yaml";
import { readFileSync } from "fs";

// Загружаем и обрабатываем YAML
const yamlContent = readFileSync("./config/services.yaml", "utf-8");
const processed = YamlDotEnv.convertTo(yamlContent);

// Парсим в объект
const config = yaml.load(processed);

services.yaml:

services:
  frontend:
    host: ${FRONTEND_HOST:-localhost}
    port: ${FRONTEND_PORT:-3000}
    
  backend:
    host: ${BACKEND_HOST:-localhost}
    port: ${BACKEND_PORT:-8080}
    timeout: ${BACKEND_TIMEOUT:-30000}
    
  database:
    host: ${DB_HOST}
    port: ${DB_PORT:-5432}
    name: ${DB_NAME:-myapp}

Интеграция с dotenv

import { config } from "dotenv";
import { YamlDotEnv } from "yaml-dotenv";
import { readFileSync } from "fs";
import * as yaml from "js-yaml";

// Загружаем переменные из .env файла
config();

// Обрабатываем YAML
const yamlContent = readFileSync("./config/app.yaml", "utf-8");
const processed = YamlDotEnv.convertTo(yamlContent);
const appConfig = yaml.load(processed);

console.log(appConfig);

.env:

APP_NAME=MyApp
APP_VERSION=1.0.0
API_URL=https://api.example.com
DEBUG=true

app.yaml:

application:
  name: ${APP_NAME}
  version: ${APP_VERSION}
  api:
    url: ${API_URL}
    timeout: ${API_TIMEOUT:-5000}
  debug: ${DEBUG:-false}

Docker Compose конфигурация

import { YamlDotEnv } from "yaml-dotenv";
import { readFileSync, writeFileSync } from "fs";

// Загружаем шаблон docker-compose
const template = readFileSync("./docker-compose.template.yaml", "utf-8");

// Заменяем переменные окружения
const dockerCompose = YamlDotEnv.convertTo(template);

// Сохраняем результат
writeFileSync("./docker-compose.yaml", dockerCompose);

docker-compose.template.yaml:

version: '3.8'
services:
  app:
    image: ${APP_IMAGE:-myapp:latest}
    ports:
      - "${APP_PORT:-3000}:3000"
    environment:
      NODE_ENV: ${NODE_ENV:-production}
      DATABASE_URL: ${DATABASE_URL}
      
  db:
    image: postgres:${POSTGRES_VERSION:-14}
    environment:
      POSTGRES_USER: ${DB_USER:-postgres}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME:-myapp}

📖 API

YamlDotEnv.convertTo(content: string): string

Заменяет все вхождения переменных окружения в строке на их значения.

Параметры:

• content (string) - YAML содержимое со переменными окружения

Возвращает: string - обработанное содержимое с заменёнными переменными

Синтаксис переменных:

• ${VAR_NAME} - заменяется на значение переменной или пустую строку
• ${VAR_NAME:-default} - заменяется на значение переменной или на default

Примеры:

// Простая замена
YamlDotEnv.convertTo("port: ${PORT}");

// Со значением по умолчанию
YamlDotEnv.convertTo("port: ${PORT:-8080}");

// Несколько переменных
YamlDotEnv.convertTo("url: ${HOST}:${PORT}");

// Многострочный YAML
const yaml = `
database:
  host: \${DB_HOST}
  port: \${DB_PORT:-5432}
`;
YamlDotEnv.convertTo(yaml);

🎯 Поддерживаемые паттерны

✅ Поддерживается

# Простые переменные
value: ${VAR_NAME}

# С подчёркиваниями
value: ${MY_VAR_NAME}

# С цифрами
value: ${VAR123}

# Значения по умолчанию
value: ${VAR:-default}

# Значения по умолчанию с двоеточиями
url: ${URL:-http://localhost:8080}

# Значения по умолчанию с пробелами
message: ${MESSAGE:-Hello World}

# Пустые значения по умолчанию
value: ${VAR:-}

# Несколько переменных в строке
url: ${HOST}:${PORT}

❌ Не поддерживается

# Неправильный синтаксис
value: $VAR_NAME          # Нет фигурных скобок
value: {VAR_NAME}         # Нет знака доллара
value: $(VAR_NAME)        # Круглые скобки вместо фигурных
value: ${VAR NAME}        # Пробелы в имени переменной

🔍 Особенности

Приоритет значений

1. Определённая переменная окружения - всегда используется, если существует (даже если пустая)
2. Значение по умолчанию - используется только если переменная undefined
3. Пустая строка - используется если переменная не определена и нет значения по умолчанию

// Случай 1: переменная определена
process.env.VAR = "value";
YamlDotEnv.convertTo("${VAR:-default}"); // => "value"

// Случай 2: переменная пустая
process.env.VAR = "";
YamlDotEnv.convertTo("${VAR:-default}"); // => "" (не "default")

// Случай 3: переменная не определена
delete process.env.VAR;
YamlDotEnv.convertTo("${VAR:-default}"); // => "default"

// Случай 4: переменная не определена, нет значения по умолчанию
delete process.env.VAR;
YamlDotEnv.convertTo("${VAR}"); // => ""

Регулярные выражения

Библиотека использует регулярное выражение /\$\{([^}:]+)(:-[^}]*)?\}/g для поиска переменных:

• \$\{ - открывающая последовательность ${
• ([^}:]+) - имя переменной (группа 1)
• (:-[^}]*)? - опциональное значение по умолчанию (группа 2)
• \} - закрывающая скобка }

🧪 Тестирование

Проект использует Vitest с полным покрытием тестами.

# Запуск тестов
pnpm test

# Запуск тестов в режиме watch
pnpm test:watch

# Запуск тестов с покрытием
pnpm test:coverage

Покрытие тестами:

• ✅ Базовая замена переменных (4 теста)
• ✅ Значения по умолчанию (5 тестов)
• ✅ Отсутствующие переменные (2 теста)
• ✅ Пустые переменные окружения (2 теста)
• ✅ Сложные YAML структуры (3 теста)
• ✅ Граничные случаи (7 тестов)
• ✅ Реальные примеры использования (3 теста)

Всего: 26 тестов 🎉

🛠️ Разработка

# Установка зависимостей
pnpm install

# Сборка проекта
pnpm build

# Запуск тестов
pnpm test

💡 Best Practices

1. Всегда используйте значения по умолчанию

# ✅ Хорошо
server:
  port: ${PORT:-8080}
  host: ${HOST:-localhost}

# ❌ Плохо
server:
  port: ${PORT}
  host: ${HOST}

2. Используйте осмысленные имена переменных

# ✅ Хорошо
database:
  host: ${DB_HOST}
  port: ${DB_PORT}

# ❌ Плохо
database:
  host: ${H}
  port: ${P}

3. Группируйте связанные переменные

# .env
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=secret

REDIS_HOST=localhost
REDIS_PORT=6379

4. Документируйте переменные

Создайте файл .env.example:

# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=change-me

# Redis configuration
REDIS_HOST=localhost
REDIS_PORT=6379

5. Используйте с dotenv

import { config } from "dotenv";
import { YamlDotEnv } from "yaml-dotenv";

// Загружаем переменные из .env
config();

// Обрабатываем YAML
const result = YamlDotEnv.convertTo(yamlContent);

🔒 Безопасность

Храните секреты в безопасности

# ✅ Хорошо - секреты в переменных окружения
database:
  password: ${DB_PASSWORD}
  api_key: ${API_KEY}

# ❌ Плохо - секреты в файле
database:
  password: my-secret-password
  api_key: abc123xyz

Не коммитьте .env файлы

Добавьте в .gitignore:

.env
.env.local
.env.*.local

📝 Лицензия

MIT

🤝 Вклад

Вклады приветствуются! Пожалуйста, создавайте issue или pull request.

👤 Автор

letnull19A

🔗 Похожие проекты

• dotenv - загрузка переменных окружения из .env файлов
• js-yaml - парсер и сериализатор YAML для JavaScript
• envsubst - утилита для замены переменных окружения

⚡ Производительность

Библиотека использует эффективное регулярное выражение для замены переменных за один проход. Идеально подходит для обработки конфигурационных файлов любого размера.

🌟 Особенности

• 🚀 Нулевые зависимости (zero dependencies)
• 📦 Маленький размер бандла
• ⚡ Быстрая обработка
• 🔒 Типобезопасный TypeScript
• ✅ 100% покрытие тестами
• 📖 Подробная документация

📊 Статистика