@v4fire/config

Простой config-like конфигуратор с поддержкой параметров командной строки, переменных среды и вычисляемых опций, преобразования значений и их валидации.

Установка

npm

npm install @v4fire/config --save

yarn

yarn add @v4fire/config

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

• Создайте папку config в корне своего проекта
• Внутри этой папки создайте default.js, development.js и production.js
• Каждый из этих файлов должен экспортировать объект – @v4fire/config берет за основу default.js, и подмешивает к нему development.js или production.js -- в зависимости от NODE_ENV.

Расширенные опции

@v4fire/config предоставляет простой интерфейс для использования переменных среды, параметров командной строки и создания вычисляемых в рантайме свойств, а также их преобразования и валидации.

Options

Большинство расширенных возможностей предоставляет функция option из @v4fire/config/options. @v4fire/config Для примера возьмем случай, когда нам нужно запускать приложения на разных портах (на локальной машине на одном, на бою -- на другом):

config/default.js

const{option: o}=require('@v4fire/config/options');module.exports={port: o('port',{default: 8080,// значение по умолчаниюshort: 'p',// короткий алиас '-p' для командной строкиenv: 'PORT_TO_LISTEN',// Теперь значение этой опции можно менять через переменную окружения PORT_TO_LISTEN coerce(value){returnNumber(value);// приводим к числу},validate(value){returnvalue>0&&value<65536;// валидируем значение}})}

app.js

constconfig=require('@v4fire/config');console.log(`Application listen port ${config.port}`);

Теперь приложение можно запускать на разных портах:

$ node app --port 1717
Application listen port 1717
$ node app -p 2020
Application listen port 2020
$ export PORT=3030
$ node app
Application listen port 3030

Сomputed options

Если вам нужны в конфиге значения, которые нужно считать в рантайме (которые, скажем, зависят от других значений) -- для этого нужно использовать computedOption из @v4fire/config/options.

Пример:

config/default.js

const{option: o,computed: co}=require('@v4fire/config/options');module.exports={build: {// конфиг для сборки проекта// допустим, проект нужно собирать по-разному// для разных платформplatform: o('platform',{default: 'linux',valuesFlags: ['linux','windows','osx'],// чтобы запускать сборку сразу с флагом --windows, напримерvalidate: ['linux','windows','osx']// в качестве валидатора можно передать список возможных значений}),// какая-нибудь фича, которая должна быть // только в сборке для windowsincludeWindowsOnlyFeature: co((config)=>config.build.platform==='windows')}}

build.js

constbuildConfig=require('@v4fire/config').build;console.log(`Platform: ${buildConfig.platform}`);console.log(`Windows only feature`,buildConfig.includeWindowsOnlyFeature ? 'included' : 'not included')

Сборка:

$ node build
Platform: linux
Windows only feature not included
$ node build --platform osx
Platform: osx
Windows only feature not included
$ node build --windows
Platform: windows
Windows only feature included

API

@v4fire/config/options

option(name: string, params?: Object)

Универсальная функция для получения значения из параметров консольной строки или переменных окружения, их преобразования и валидации.

• name: string – имя опции, обязательный параметр

• params: Object – параметры:

  • default: any – значение по умолчанию.

  • argv: boolean | string – значение false отключает получение значени≤я из параметров командной строки. Строковое значение переопределяет имя параметра командной строки (по умолчанию берется name).

  • env: boolean | string - строковое значение переопределяет имя переменной окружения, из которой надо брать значение (по умолчанию берется name, приведенное к верхнему регистру и с - замененными на _, т.е., если имя равно api-url, то значение будет браться из переменной окружения API_URL). Значение false отключает получение значения из переменных окружения.

  • short: string - однобуквенный алиас для командной строки

  • type: 'boolean' | 'number' | 'json' – тип опции. Ставит значения для coerce и validate.

  • valuesFlags: Array<string> | Object – объявляет флаги командной строки, которые устанавливают для опции конкретное значение. Пример:

    option('watcher',{default: false,type: 'boolean',valuesFlags: {watch: true}});// при запуске приложения с флагом '--watch' вернет true

  • coerce: (value: string, source: string) => any – функция для преобразования значения (скажем, для перевода его из строки в число). Получает два параметра: value – значение и source – источник значения (null, если значение получено не было и дефолтное значение не задано, 'default', если установлено дефолтное значение, 'cli', если значение получено из параметров командной строки и 'env', если значение получено из переменных окружения)

  • validate: (value: string, source: string) => boolean – функция для валидации данных. Получает те же параметры, что и coerce.

Приоритет источников от меньшего к большему:

• Значение по умолчанию
• Значение из переменной окружения
• Значение из командной строки
• Значение из командной строки для короткого алиаса (short)
• Значение из командной строки для флагов значений (valuesFlags)

computedOption(handler: Function)

Вычисление значения в рантайме (например, на основании других параметров конфига). Принимает один параметр – функцию:

• handler: (config) => any – функция, которая принимает первым аргументом весь конфиг и возвращает значение.

Важно: эту функцию можно использовать только внутри объекта с конфигом. Так же важно не допускать появления кольцевых зависимостей – т.е. когда две опции зависят от значений друг друга – это приведет к переполнению стека и ошибке. Однако, одна вычисляемая опция может использовать значение другой вычисляемой опции.

@v4fire/config

Для получения конфига достаточно импортировать модуль:

constconfig=require('@v4fire/config');

Лицензия

MIT