ex-config

About

ex-config is an extendable configuration processor. It is used to merge multiple configurations together like babel and eslint configurations do.

Installation

npm install --save ex-config

Usage

'use strict';

const cosmiconfig = require('cosmiconfig');
const {
	/* async: */ exConfig,
	/* sync: */ exConfigSync,
} = require('ex-config');

/**
 * Example using cosmiconfig to load the base config from disk
 */
const explorer = cosmiconfig('example');
const baseConfig = await explorer.load();

/**
 * Original configs are not mutated
 *
 * all options are optional
 *
 * preprocessor, validator, processor, and postProcessor lifecycles all
 *   are given one argument object containing:
 * {
 *   value: new value
 *   current: current value, can be undefined
 *   config: current config
 *   dirname: directory where the preset was loaded from
 * }
 */
const config = await exConfig(
	/* initial config: */ baseConfig,
	/* options: */ {
		/**
		 * directory to initially resolve presets/plugins from
		 *
		 * default: process.cwd()
		 */
		baseDirectory: process.cwd(),

		/**
		 * Add an API accessible to all lifecycles/presets/plugins
		 *
		 * default: {}
		 */
		api: new (class ApiExample {
			someCustomApiExample() {
				return this;
			}
		})(),

		/**
		 * key id that extends configurations via resolve
		 * See also, overrides.presets.resolve
		 *
		 * default: 'presets'
		 * set to false to disable
		 */
		presets: 'presets',

		/**
		 * key id that resolves plugins
		 *
		 * default: 'plugins'
		 * set to false to disable
		 */
		plugins: 'plugins',

		/**
		 * Pre-process the preset before validation
		 *
		 * Whatever is returned will be the new value of the current preset
		 *
		 * Runs once with each preset
		 */
		preprocessor: async ({ value, current, config, dirname, api }) => {
			// returned value will be the updated preset value
			return value;
		},

		/**
		 * Used to validate a preset. if preset is invalid, throw with an error
		 *
		 * Runs once with each preset
		 */
		validator: async ({ value, current, config, dirname, api }) => {
			if (value !== 'valid') {
				throw new Error('value is invalid');
			}

			// does not expect a return value
			return undefined;
		},

		/**
		 * Post Processor runs once after all configurations
		 *   have been successfully processed.
		 */
		postProcessor: async ({ config, dirname, api }) => {
			// returned value will equal the final config
			return value;
		},

		/**
		 * processor runs once per key per preset
		 *
		 * used merge the value with the overall current value
		 *
		 * by default, this will deep merge any objects,
		 *   push new value onto array, or replace current value
		 *
		 * other built-in processors are:
		 * arrayPush: all values are an array that are appended
		 *   to the end of the current array
		 *
		 * arrayConcat: all values are an array that are added
		 *   to the front of the current array
		 *
		 * mergeDeep: all values are treated as an object
		 *
		 * Pass a function to use a custom processor
		 */
		processor: async ({ value, current = [], config, dirname, api }) => {
			const val = Array.isArray(value) ? value : [value];

			// returned value will be the new value of the key
			return [
				...current,
				...val,
			];
		},

		/**
		 * overrides can override/change the settings above
		 */
		overrides: {
			presets: {
				resolve: {
					/**
					 * Prefix to add to packageId
					 *
					 * example: one -> example-preset-one
					 *
					 * Optional
					 *
					 * Accepts a single or an array of prefixes
					 */
					prefix: 'example-preset',

					/**
					 * NPM Scope of organization to override prefix
					 *
					 * Optional
					 */
					org: '@example',

					/**
					 * Org prefixes
					 *
					 * example: @example/one -> @example/preset-one
					 *
					 * Optional
					 *
					 * Accepts a single or an array of prefixes
					 */
					orgPrefix: 'preset',

					/**
					 * Only allow prefixed module resolution.
					 * Explicit modules can be required by prepending module:
					 * For example, module:local-module
					 *
					 * Default: true
					 * Optional
					 */
					strict: true,
				},
			},

			files: {
				/**
				 * preprocessor override is in addition to the base preprocessor
				 */
				preprocessor: async ({
					value,
					current,
					config,
					dirname,
					api,
				}) => {
					return value;
				},

				/**
				 * validator override will validate in addition to the base validator
				 */
				validator: async ({ value, current, config, dirname, api }) => {
					if (typeof value.source !== 'string') {
						throw new Error('files source must be a string');
					}
				},

				/**
				 * processor override will override the base processor
				 */
				processor: async ({
					value,
					current = [],
					config,
					dirname,
					api,
				}) => {
					const val = Array.isArray(value) ? value : [value];

					return [
						...val,
						...current,
					];
				},
			},
		},
	},
);

Creating Presets and Plugins

A preset or plugin needs to export an object or function.

Only export default is supported when using es modules.

If a function is used it will be invoked with the following argument:

// preset-example.js
function presetExample(context) {
	// options given as second index when calling preset/plugin
	const options = context.options;
	// dirname package was found from
	const dirname = context.dirname;
	// api provided in options
	const api = context.api;

	return {
		verbose: options.verbose,
	};
}

module.exports = presetExample;

// config.js
const exampleConfig = {
	presets: [
		[
			// packageId
			'preset-example',
			// options for preset/plugin
			{ verbose: true },
		],
	],
};

module.exports = exampleConfig;

Thanks To

This package was created with the great work / lessons learned from:

• babel
• eslint