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