fenviee

fenviee — простая и типобезопасная утилита для работы с переменными окружения в Node.js.
Позволяет декларативно описывать структуру process.env, разделяя переменные на обязательные, необязательные и «уникальные» (с валидацией и приведением типов). На выходе вы получаете единый типизированный объект конфигурации.

Установка

npm install fenviee

Мотивация

При работе с process.env в TypeScript часто приходится вручную проверять наличие ключей, приводить типы и обрабатывать ошибки.

fenviee берёт эти задачи на себя:

• Чёткое разделение переменных по категориям.
• Автоматическая проверка обязательных ключей.
• Возможность задать значения по умолчанию для необязательных.
• Валидация и трансформация значений с помощью пользовательских функций.
• Единый механизм сбора ошибок.
• Полная типизация выходного объекта.

Концепции

required (обязательные)

Ключи, которые обязаны присутствовать в process.env. Если хотя бы одного нет — выбрасывается исключение.

partial (необязательные)

Ключи, которые могут отсутствовать. Для них можно указать значение по умолчанию в поле default. Если ключ отсутствует и нет значения по умолчанию — это считается ошибкой.

unique (уникальные)

Ключи, значения которых проходят пользовательскую валидацию и преобразование. Для каждого такого ключа вы задаёте функцию-валидатор, которая получает строку из process.env (или undefined) и возвращает значение нужного типа.
Важно: уникальные ключи не нужно дублировать в required или partial — они обрабатываются отдельно и их имена могут не пересекаться с другими категориями.

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

Базовый пример

import { Env } from 'fenviee';

// Создаём конфигурацию
const config = Env.create(process.env)({
  required: ['NODE_ENV', 'PORT'] as const,
  partial: ['LOG_LEVEL'] as const,
  default: {
    LOG_LEVEL: 'info'
  },
  unique: {
    // Пример валидации числа
    MAX_CONNECTIONS: (value) => {
      const num = Number(value);
      if (isNaN(num) || num <= 0) throw new Error('MAX_CONNECTIONS must be a positive number');
      return num;
    }
  }
});

console.log(config);
// {
//   NODE_ENV: 'development',
//   PORT: '3000',
//   LOG_LEVEL: 'info',
//   MAX_CONNECTIONS: 100
// }

Обработка ошибок

Если хотя бы одна переменная не проходит проверку, Env.create выбросит исключение с агрегированным сообщением:

Environment configuration failed:
Key NODE_ENV is not defined in env
MAX_CONNECTIONS must be a positive number

Это позволяет перехватить ошибку на старте приложения и корректно завершить работу или вывести диагностику.

Продвинутое использование: трансформация ключей

Метод transform (доступен статически) позволяет гибко обрабатывать произвольные наборы ключей. Обычно он используется внутри библиотеки, но может пригодиться и для собственных целей.

const { data, errors } = Env.transform({
  properties: ['API_URL', 'TIMEOUT'] as const,
  env: process.env,
  propertyTransformer: (key) => `APP_${key}`,
  valueTransformer: (value, key) => value ?? 'default',
  errorTransformer: ({ error }) => error
});

Встроенные валидаторы

Библиотека предоставляет набор готовых трансформеров для наиболее частых случаев. Все они находятся в пространстве имён EnvValidators (или импортируются напрямую).

import { Env, isNumber, isBoolean, isUrl, isArray } from 'fenviee';

const config = Env.create(process.env)({
  required: ['APP_NAME'],
  partial: ['LOG_LEVEL'],
  default: { LOG_LEVEL: 'info' },
  unique: {
    PORT: isPort,                    // число от 1 до 65535
    DB_POOL_SIZE: isIntegerInRange(1, 100), // целое число в диапазоне
    ENABLE_CACHE: isBoolean,          // true/false
    API_BASE_URL: isUrl,              // валидный URL
    CORS_ORIGINS: isArray(','),       // массив строк через запятую
    CONFIG_JSON: isJSON<{ key: string }> // парсинг JSON
  }
});

Список доступных валидаторов

| Функция | Описание | Возвращаемый тип | | ------- | -------- | ---------------- | | isString | Значение должно быть определено, возвращает строку | string | | isNumber | Преобразует в число (целое или дробное) | number | | isInteger | Преобразует в целое число | number | | isBoolean | Принимает 'true'/'false'/'1'/'0' (регистр не важен) | boolean | | isUrl | Проверяет, что строка является валидным URL | string | | isPort | Проверяет, что число является портом (1–65535) | number | | isEmail | Простая проверка email | string | | isJSON | Парсит строку как JSON | T (параметризуется) | | isArray(separator?) | Разделяет строку по разделителю, возвращает массив непустых строк | string[] | | isNumberInRange(min, max) | Проверяет, что число в диапазоне | number | | isIntegerInRange(min, max) | Проверяет, что целое число в диапазоне | number |

Все валидаторы выбрасывают ошибку с понятным сообщением, если значение не проходит проверку. Эти ошибки автоматически собираются и агрегируются при вызове Env.create.

API

Env.create(env)

Статический метод, принимающий объект окружения (обычно process.env).
Возвращает функцию, которая ожидает параметры инициализации и сразу возвращает результат execute().

const getConfig = Env.create(process.env);
const config = getConfig({ required: [...], partial: [...], default: {...}, unique: {...} });

Параметры инициализации (EnvInitializeData)

| Поле | Тип | Описание | | ---------- | --------------------------------------- | ----------------------------------------------------------------------------------------------- | | required | readonly string[] | Список обязательных ключей. | | partial | readonly string[] | Список необязательных ключей. | | unique | Record<string, (value?: string) => T> | Объект с валидаторами. Каждый валидатор получает значение из env и возвращает произвольный тип. | | default | Record<string, string> | Значения по умолчанию для ключей из partial. Ключи должны совпадать. |

Возвращаемое значение

Тип возвращаемого объекта вычисляется автоматически:

• Для required — строки (значения из process.env).
• Для partial — строки (либо из env, либо из default).
• Для unique — типы, возвращаемые соответствующими валидаторами.

Все ключи объединяются в один объект (пересечение типов). Если один и тот же ключ указан в нескольких категориях, поведение не определено — старайтесь избегать пересечений.

Типы

Библиотека экспортирует все используемые типы для удобства:

• EnvProperties — readonly string[]
• SomeRecord — Record<string, unknown>
• Validators<T> — тип валидаторов для unique-переменных.
• EnvInitializeData<...> — тип параметров инициализации.
• FormatterParameters<...> — параметры для метода transform.
• UnionToIntersection<Type> — утилита для преобразования объединений в пересечения.

Пример импорта типа:

import type { EnvInitializeData } from 'fenviee';

Лицензия

MIT © FOCKUSTY