conf - npm Package Compare versions

Comparing version 3.0.0 to 4.0.0

index.d.ts

 /// <reference types="node"/>
+import {JSONSchema} from 'json-schema-typed';
 
-export interface Options<T> {
-	/**
-	 * Config used if there are no existing config.
-	 */
-	readonly defaults?: {[key: string]: T};
+declare namespace Conf {
+	interface Options<T> {
+		/**
+		Config used if there are no existing config.
 
-	/**
-	 * Name of the config file (without extension).
-	 *
-	 * Useful if you need multiple config files for your app or module. For example, different config files between two major versions.
-	 *
-	 * @default 'config'
-	 */
-	readonly configName?: string;
+		**Note:** The values in `defaults` will overwrite the `default` key in the `schema` option.
+		*/
+		readonly defaults?: {[key: string]: T};
 
-	/**
-	 * You only need to specify this if you don't have a `package.json` file in your project. Default: The name field in the `package.json` closest to where `conf` is imported.
-	 */
-	readonly projectName?: string;
+		/**
+		[JSON Schema](https://json-schema.org) to validate your config data.
 
-	/**
-	 * **You most likely don't need this. Please don't use it unless you really have to.**
-	 *
-	 * The only use-case I can think of is having the config located in the app directory or on some external storage. Default: System default user [config directory](https://github.com/sindresorhus/env-paths#pathsconfig).
-	 */
-	readonly cwd?: string;
+		Under the hood, the JSON Schema validator [ajv](https://github.com/epoberezkin/ajv) is used to validate your config. We use [JSON Schema draft-07](http://json-schema.org/latest/json-schema-validation.html) and support all [validation keywords](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md) and [formats](https://github.com/epoberezkin/ajv#formats).
 
-	/**
-	 * Note that this is **not intended for security purposes**, since the encryption key would be easily found inside a plain-text Node.js app.
-	 *
-	 * Its main use is for obscurity. If a user looks through the config directory and finds the config file, since it's just a JSON file, they may be tempted to modify it. By providing an encryption key, the file will be obfuscated, which should hopefully deter any users from doing so.
-	 *
-	 * It also has the added bonus of ensuring the config file's integrity. If the file is changed in any way, the decryption will not work, in which case the store will just reset back to its default state.
-	 *
-	 * When specified, the store will be encrypted using the [`aes-256-cbc`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation) encryption algorithm.
-	 */
-	readonly encryptionKey?: string | Buffer | NodeJS.TypedArray | DataView;
+		You should define your schema as an object where each key is the name of your data's property and each value is a JSON schema used to validate that property. See more [here](https://json-schema.org/understanding-json-schema/reference/object.html#properties).
 
-	/**
-	 * Extension of the config file.
-	 *
-	 * You would usually not need this, but could be useful if you want to interact with a file with a custom file extension that can be associated with your app. These might be simple save/export/preference files that are intended to be shareable or saved outside of the app.
-	 *
-	 * @default 'json'
-	 */
-	readonly fileExtension?: string;
+		@example
+		```
+		import Conf = require('conf');
 
-	/**
-	 * The config is cleared if reading the config file causes a `SyntaxError`. This is a good default, as the config file is not intended to be hand-edited, so it usually means the config is corrupt and there's nothing the user can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be more useful to throw an error when the config is invalid instead of clearing. Disabling this option will make it throw a `SyntaxError` on invalid config instead of clearing.
-	 *
-	 * @default true
-	 */
-	readonly clearInvalidConfig?: boolean;
+		const schema = {
+			foo: {
+				type: 'number',
+				maximum: 100,
+				minimum: 1,
+				default: 50
+			},
+			bar: {
+				type: 'string',
+				format: 'url'
+			}
+		};
 
-	/**
-	 * Function to serialize the config object to a UTF-8 string when writing the config file.
-	 *
-	 * You would usually not need this, but it could be useful if you want to use a format other than JSON.
-	 *
-	 * @default value => JSON.stringify(value, null, '\t')
-	 */
-	readonly serialize?: (value: {[key: string]: T}) => string;
+		const config = new Conf({schema});
 
-	/**
-	 * Function to deserialize the config object from a UTF-8 string when reading the config file.
-	 *
-	 * You would usually not need this, but it could be useful if you want to use a format other than JSON.
-	 *
-	 * @default JSON.parse
-	 */
-	readonly deserialize?: (text: string) => {[key: string]: T};
+		console.log(config.get('foo'));
+		//=> 50
 
-	/**
-	 * **You most likely don't need this. Please don't use it unless you really have to.**
-	 *
-	 * Suffix appended to `projectName` during config file creation to avoid name conflicts with native apps.
-	 *
-	 * You can pass an empty string to remove the suffix.
-	 *
-	 * For example, on macOS, the config file will be stored in the `~/Library/Preferences/foo-nodejs` directory, where `foo` is the `projectName`.
-	 *
-	 * @default 'nodejs'
-	 */
-	readonly projectSuffix?: string;
+		config.set('foo', '1');
+		// [Error: Config schema violation: `foo` should be number]
+		```
+
+		**Note:** The `default` value will be overwritten by `defaults` option if set.
+		*/
+		readonly schema?: {[key: string]: JSONSchema};
+
+		/**
+		Name of the config file (without extension).
+
+		Useful if you need multiple config files for your app or module. For example, different config files between two major versions.
+
+		@default 'config'
+		*/
+		readonly configName?: string;
+
+		/**
+		You only need to specify this if you don't have a `package.json` file in your project. Default: The name field in the `package.json` closest to where `conf` is imported.
+		*/
+		readonly projectName?: string;
+
+		/**
+		__You most likely don't need this. Please don't use it unless you really have to.__
+
+		The only use-case I can think of is having the config located in the app directory or on some external storage. Default: System default user [config directory](https://github.com/sindresorhus/env-paths#pathsconfig).
+		*/
+		readonly cwd?: string;
+
+		/**
+		Note that this is __not intended for security purposes__, since the encryption key would be easily found inside a plain-text Node.js app.
+
+		Its main use is for obscurity. If a user looks through the config directory and finds the config file, since it's just a JSON file, they may be tempted to modify it. By providing an encryption key, the file will be obfuscated, which should hopefully deter any users from doing so.
+
+		It also has the added bonus of ensuring the config file's integrity. If the file is changed in any way, the decryption will not work, in which case the store will just reset back to its default state.
+
+		When specified, the store will be encrypted using the [`aes-256-cbc`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation) encryption algorithm.
+		*/
+		readonly encryptionKey?: string | Buffer | NodeJS.TypedArray | DataView;
+
+		/**
+		Extension of the config file.
+
+		You would usually not need this, but could be useful if you want to interact with a file with a custom file extension that can be associated with your app. These might be simple save/export/preference files that are intended to be shareable or saved outside of the app.
+
+		@default 'json'
+		*/
+		readonly fileExtension?: string;
+
+		/**
+		The config is cleared if reading the config file causes a `SyntaxError`. This is a good default, as the config file is not intended to be hand-edited, so it usually means the config is corrupt and there's nothing the user can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be more useful to throw an error when the config is invalid instead of clearing. Disabling this option will make it throw a `SyntaxError` on invalid config instead of clearing.
+
+		@default true
+		*/
+		readonly clearInvalidConfig?: boolean;
+
+		/**
+		Function to serialize the config object to a UTF-8 string when writing the config file.
+
+		You would usually not need this, but it could be useful if you want to use a format other than JSON.
+
+		@default value => JSON.stringify(value, null, '\t')
+		*/
+		readonly serialize?: (value: {[key: string]: T}) => string;
+
+		/**
+		Function to deserialize the config object from a UTF-8 string when reading the config file.
+
+		You would usually not need this, but it could be useful if you want to use a format other than JSON.
+
+		@default JSON.parse
+		*/
+		readonly deserialize?: (text: string) => {[key: string]: T};
+
+		/**
+		__You most likely don't need this. Please don't use it unless you really have to.__
+
+		Suffix appended to `projectName` during config file creation to avoid name conflicts with native apps.
+
+		You can pass an empty string to remove the suffix.
+
+		For example, on macOS, the config file will be stored in the `~/Library/Preferences/foo-nodejs` directory, where `foo` is the `projectName`.
+
+		@default 'nodejs'
+		*/
+		readonly projectSuffix?: string;
+	}
 }
 
 /**
- * Simple config handling for your app or module.
- */
-export default class Conf<T = unknown> implements Iterable<[string, T]> {
+Simple config handling for your app or module.
+*/
+declare class Conf<T = unknown> implements Iterable<[string, T]> {
 	store: {[key: string]: T};
@@ -97,52 +139,73 @@ readonly path: string;
 
-	constructor(options?: Options<T>);
+	/**
+	@example
+	```
+	import Conf = require('conf');
 
+	const config = new Conf();
+
+	config.set('unicorn', '🦄');
+	console.log(config.get('unicorn'));
+	//=> '🦄'
+
+	// Use dot-notation to access nested properties
+	config.set('foo.bar', true);
+	console.log(config.get('foo'));
+	//=> {bar: true}
+
+	config.delete('unicorn');
+	console.log(config.get('unicorn'));
+	//=> undefined
+	```
+	*/
+	constructor(options?: Conf.Options<T>);
+
 	/**
-	 * Set an item.
-	 *
-	 * @param key - You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a key to access nested properties.
-	 * @param value - Must be JSON serializable. Trying to set the type `undefined`, `function`, or `symbol` will result in a `TypeError`.
-	 */
+	Set an item.
+
+	@param key - You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a key to access nested properties.
+	@param value - Must be JSON serializable. Trying to set the type `undefined`, `function`, or `symbol` will result in a `TypeError`.
+	*/
 	set(key: string, value: T): void;
 
 	/**
-	 * Set multiple items at once.
-	 *
-	 * @param object - A hashmap of items to set at once.
-	 */
+	Set multiple items at once.
+
+	@param object - A hashmap of items to set at once.
+	*/
 	set(object: {[key: string]: T}): void;
 
 	/**
-	 * Get an item.
-	 *
-	 * @param key - The key of the item to get.
-	 * @param defaultValue - The default value if the item does not exist.
-	 */
+	Get an item.
+
+	@param key - The key of the item to get.
+	@param defaultValue - The default value if the item does not exist.
+	*/
 	get(key: string, defaultValue?: T): T;
 
 	/**
-	 * Check if an item exists.
-	 *
-	 * @param key - The key of the item to check.
-	 */
+	Check if an item exists.
+
+	@param key - The key of the item to check.
+	*/
 	has(key: string): boolean;
 
 	/**
-	 * Delete an item.
-	 *
-	 * @param key - The key of the item to delete.
-	 */
+	Delete an item.
+
+	@param key - The key of the item to delete.
+	*/
 	delete(key: string): void;
 
 	/**
-	 * Delete all items.
-	 */
+	Delete all items.
+	*/
 	clear(): void;
 
 	/**
-	 * Watches the given `key`, calling `callback` on any changes.
-	 *
-	 * @param key - The key wo watch.
-	 * @param callback - A callback function that is called on any changes. When a `key` is first set `oldValue` will be `undefined`, and when a key is deleted `newValue` will be `undefined`.
-	 */
+	Watches the given `key`, calling `callback` on any changes.
+
+	@param key - The key wo watch.
+	@param callback - A callback function that is called on any changes. When a `key` is first set `oldValue` will be `undefined`, and when a key is deleted `newValue` will be `undefined`.
+	*/
 	onDidChange(
@@ -155,1 +218,3 @@ key: string,
 }
+
+export = Conf;

index.js

@@ -13,2 +13,3 @@ /* eslint-disable node/no-deprecated-api */
 const writeFileAtomic = require('write-file-atomic');
+const Ajv = require('ajv');
 
@@ -37,16 +38,3 @@ const plainObject = () => Object.create(null);
 	constructor(options) {
-		const pkgPath = pkgUp.sync(parentDir);
-
 		options = {
-			// Can't use `require` because of Webpack being annoying:
-			// https://github.com/webpack/webpack/issues/196
-			projectName: pkgPath && JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name,
-			...options
-		};
-
-		if (!options.projectName && !options.cwd) {
-			throw new Error('Project name could not be inferred. Please specify the `projectName` option.');
-		}
-
-		options = {
 			configName: 'config',
@@ -62,2 +50,13 @@ fileExtension: 'json',
 		if (!options.cwd) {
+			if (!options.projectName) {
+				const pkgPath = pkgUp.sync(parentDir);
+				// Can't use `require` because of Webpack being annoying:
+				// https://github.com/webpack/webpack/issues/196
+				options.projectName = pkgPath && JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name;
+			}
+
+			if (!options.projectName) {
+				throw new Error('Project name could not be inferred. Please specify the `projectName` option.');
+			}
+
 			options.cwd = envPaths(options.projectName, {suffix: options.projectSuffix}).config;
@@ -68,2 +67,20 @@ }
 
+		if (options.schema) {
+			if (typeof options.schema !== 'object') {
+				throw new TypeError('The `schema` option must be an object.');
+			}
+
+			const ajv = new Ajv({
+				allErrors: true,
+				format: 'full',
+				useDefaults: true,
+				errorDataPath: 'property'
+			});
+			const schema = {
+				type: 'object',
+				properties: options.schema
+			};
+			this._validator = ajv.compile(schema);
+		}
+
 		this.events = new EventEmitter();
@@ -79,2 +96,3 @@ this.encryptionKey = options.encryptionKey;
 		const store = Object.assign(plainObject(), options.defaults, fileStore);
+		this._validate(store);
 		try {
@@ -87,2 +105,15 @@ assert.deepEqual(fileStore, store);
 
+	_validate(data) {
+		if (!this._validator) {
+			return;
+		}
+
+		const valid = this._validator(data);
+		if (!valid) {
+			const errors = this._validator.errors.reduce((error, {dataPath, message}) =>
+				error + ` \`${dataPath.slice(1)}\` ${message};`, '');
+			throw new Error('Config schema violation:' + errors.slice(0, -1));
+		}
+	}
+
 	get(key, defaultValue) {
@@ -177,3 +208,5 @@ return dotProp.get(this.store, key, defaultValue);
 
-			return Object.assign(plainObject(), this.deserialize(data));
+			data = this.deserialize(data);
+			this._validate(data);
+			return Object.assign(plainObject(), data);
 		} catch (error) {
@@ -198,2 +231,3 @@ if (error.code === 'ENOENT') {
 
+		this._validate(value);
 		let data = this.serialize(value);
@@ -218,2 +252,1 @@
 module.exports = Conf;
-module.exports.default = Conf;

package.json

 {
 	"name": "conf",
-	"version": "3.0.0",
+	"version": "4.0.0",
 	"description": "Simple config handling for your app or module",
@@ -16,3 +16,3 @@ "license": "MIT",
 	"scripts": {
-		"test": "xo && ava && tsd-check"
+		"test": "xo && ava && tsd"
 	},
@@ -43,17 +43,19 @@ "files": [
 	"dependencies": {
-		"dot-prop": "^4.1.0",
-		"env-paths": "^1.0.0",
-		"make-dir": "^2.0.0",
-		"pkg-up": "^2.0.0",
+		"ajv": "^6.10.0",
+		"dot-prop": "^4.2.0",
+		"env-paths": "^2.1.0",
+		"json-schema-typed": "^7.0.0",
+		"make-dir": "^3.0.0",
+		"pkg-up": "^3.0.1",
 		"write-file-atomic": "^2.4.2"
 	},
 	"devDependencies": {
-		"@types/node": "^11.10.4",
-		"ava": "^1.2.0",
-		"clear-module": "^3.0.0",
-		"del": "^4.0.0",
+		"@types/node": "^11.12.2",
+		"ava": "^1.4.0",
+		"clear-module": "^3.1.0",
+		"del": "^4.1.0",
 		"tempy": "^0.2.1",
-		"tsd-check": "^0.3.0",
+		"tsd": "^0.7.1",
 		"xo": "^0.24.0"
 	}
 }

readme.md

@@ -55,2 +55,4 @@ # conf [![Build Status](https://travis-ci.org/sindresorhus/conf.svg?branch=master)](https://travis-ci.org/sindresorhus/conf)
 
+Type: `Object`
+
 #### defaults
@@ -62,2 +64,43 @@
 
+**Note:** The values in `defaults` will overwrite the `default` key in the `schema` option.
+
+#### schema
+
+type: `Object`
+
+[JSON Schema](https://json-schema.org) to validate your config data.
+
+Under the hood, the JSON Schema validator [ajv](https://github.com/epoberezkin/ajv) is used to validate your config. We use [JSON Schema draft-07](http://json-schema.org/latest/json-schema-validation.html) and support all [validation keywords](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md) and [formats](https://github.com/epoberezkin/ajv#formats).
+
+You should define your schema as an object where each key is the name of your data's property and each value is a JSON schema used to validate that property. See more [here](https://json-schema.org/understanding-json-schema/reference/object.html#properties).
+
+Example:
+
+```js
+const Conf = require('conf');
+
+const schema = {
+	foo: {
+		type: 'number',
+		maximum: 100,
+		minimum: 1,
+		default: 50
+	},
+	bar: {
+		type: 'string',
+		format: 'url'
+	}
+};
+
+const config = new Conf({schema});
+
+console.log(config.get('foo'));
+//=> 50
+
+config.set('foo', '1');
+// [Error: Config schema violation: `foo` should be number]
+```
+
+**Note:** The `default` value will be overwritten by `defaults` option if set.
+
 #### configName
@@ -221,2 +264,3 @@
 ```js
+const Conf = require('conf');
 const yaml = require('js-yaml');
@@ -223,0 +267,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24445

increased by18.33%

Lines of code

360

increased by19.21%

Number of lines in readme file

282

increased by18.49%

Worsened metrics

Dependency count

7

increased by40%

Dependency changes

• + Addedajv@^6.10.0

• + Addedjson-schema-typed@^7.0.0

• + Addedajv@6.12.6(transitive)

• + Addedenv-paths@2.2.1(transitive)

• + Addedfast-deep-equal@3.1.3(transitive)

• + Addedfast-json-stable-stringify@2.1.0(transitive)

• + Addedfind-up@3.0.0(transitive)

• + Addedjson-schema-traverse@0.4.1(transitive)

• + Addedjson-schema-typed@7.0.3(transitive)

• + Addedlocate-path@3.0.0(transitive)

• + Addedmake-dir@3.1.0(transitive)

• + Addedp-limit@2.3.0(transitive)

• + Addedp-locate@3.0.0(transitive)

• + Addedp-try@2.2.0(transitive)

• + Addedpkg-up@3.1.0(transitive)

• + Addedpunycode@2.3.1(transitive)

• + Addedsemver@6.3.1(transitive)

• + Addeduri-js@4.4.1(transitive)

• - Removedenv-paths@1.0.0(transitive)

• - Removedfind-up@2.1.0(transitive)

• - Removedlocate-path@2.0.0(transitive)

• - Removedmake-dir@2.1.0(transitive)

• - Removedp-limit@1.3.0(transitive)

• - Removedp-locate@2.0.0(transitive)

• - Removedp-try@1.0.0(transitive)

• - Removedpify@4.0.1(transitive)

• - Removedpkg-up@2.0.0(transitive)

• - Removedsemver@5.7.2(transitive)

• Updateddot-prop@^4.2.0

• Updatedenv-paths@^2.1.0

• Updatedmake-dir@^3.0.0

• Updatedpkg-up@^3.0.1