conf

conf

Simple config handling for your app or module

All you have to care about is what to persist. This module will handle all the dull details like where and how.

It does not support two processes writing to the same store at the same moment.
A write reads the config file first, so a change made by another process is not lost unless the two writes overlap. A whole-store write (config.store = …) replaces everything the file holds.
I initially made this tool to let command-line tools persist some data.

If you need this for Electron, check out electron-store instead.

This is not a database. The entire JSON file is read and written on every change, so it's best suited for small data like user settings that change occasionally. For large data, or for a high rate of changes, use node:sqlite or similar.

Install

npm install conf

Usage

import Conf from 'conf';

const config = new Conf({projectName: 'foo'});

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

Or create a subclass.

API

Changes are written to disk atomically, so if the process crashes during a write, it will not corrupt the existing config.

Conf(options?)

Returns a new instance.

options

Type: object

defaults

Type: object

Default values for the config items.

The values in defaults will overwrite the default key in the schema option.

The values are copied when the store is created, so changing the object you passed afterwards has no effect. A value with a toJSON method, such as a Date, is stored as what it serializes to.

A key covered by defaults cannot be deleted, since the default is written back. With dot notation, a key below it can be deleted, and .reset() puts it back.

A value must be JSON serializable, like for .set(). A key set to undefined is ignored.

schema

Type: object

JSON Schema to validate your config data.

This will be the properties object of the JSON schema. That is, define 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.

The ajv dependency may cause CSP violations. See Can I use conf with strict Content Security Policy (CSP)?.

Example:

import Conf from 'conf';

const schema = {
	foo: {
		type: 'number',
		maximum: 100,
		minimum: 1,
		default: 50
	},
	bar: {
		type: 'string',
		format: 'url'
	}
};

const config = new Conf({
	projectName: 'foo',
	schema
});

console.log(config.get('foo'));
//=> 50

config.set('foo', '1');
// [Error: Config schema violation: `foo` must be number]

The default value will be overwritten by the defaults option if set.

A default must be JSON serializable, like a .set() value. With dot notation, a schema key must be a plain property name, so describe nested keys with properties. A name inside properties can contain a dot, such as example.com. Escape the dot to read or write it, such as sites.example\.com (in JavaScript, 'sites.example\\.com').

To have get() return the right types, annotate the schema with Schema<T>:

import Conf, {type Schema} from 'conf';

type Store = {
	isEnabled: boolean;
	interval: number;
};

const schema: Schema<Store> = {
	isEnabled: {type: 'boolean'},
	interval: {type: 'number'}
};

const config = new Conf({projectName: 'foo', schema});

console.log(config.get('isEnabled'));
//=> typed as boolean

Without the annotation, TypeScript cannot tell the value types from the schema, so get() returns unknown. If you also pass defaults, the schema still wins the inference, so a key that is only in defaults is an error.

rootSchema

Type: object

Root-level JSON Schema keywords for the schema, such as additionalProperties or patternProperties.

The properties keyword comes from the schema option. Do not put properties in rootSchema, as it will throw.

Example:

import Conf from 'conf';

const store = new Conf({
	projectName: 'foo',
	schema: { /* … */ },
	rootSchema: {
		additionalProperties: false
	}
});

Example with patternProperties, for when you do not know the key names in advance:

import Conf from 'conf';

const store = new Conf({
	projectName: 'foo',
	rootSchema: {
		patternProperties: {
			'^.*
ajvOptions
Type: object
Options passed to AJV.
Under the hood, the JSON Schema validator ajv is used to validate your config. We use JSON Schema draft-2020-12 and support all validation keywords and formats.
By default, allErrors and useDefaults are both set to true, but can be overridden.

Example:
import Conf from 'conf';

const store = new Conf({
	projectName: 'foo',
	schema: { /* … */ },
	rootSchema: {
		additionalProperties: false
	},
	ajvOptions: {
		removeAdditional: true
	}
});
migrations
Type: object
Important: I cannot provide support for this feature. It has some known bugs. I have no plans to work on it, but pull requests are welcome.
You can use migrations to perform operations to the store whenever a project version is upgraded.
The migrations object should consist of key-value pairs of 'version': handler. The version can also be a semver range. Migrations run in version order, whatever order they are defined in.
A migration must not create another Conf instance with migrations for the same config file.
A migration sees the keys the config file holds and the values of the defaults option. The default values of the schema option are added after the migrations have run, since a migration may repair a value the schema rejects.
The store keeps its migration bookkeeping in the config file under a reserved __internal__ key. It is not exposed through .store, .get(), .has() or iteration, and .set() and .delete() reject it.
The recorded version never moves backwards, so running an older projectVersion than the store was migrated with does not run those migrations again.
Migrations do not run for a config file that does not exist yet. There is no old data to migrate, so the store starts at the current project version. A config file that exists but has no recorded version is still migrated, which covers an app that shipped before it had migrations.
Example:
import Conf from 'conf';

const store = new Conf({
	projectName: 'foo',
	projectVersion: '2.0.0',
	migrations: {
		'0.0.1': store => {
			store.set('debugPhase', true);
		},
		'1.0.0': store => {
			store.delete('debugPhase');
			store.set('phase', '1.0.0');
		},
		'1.0.2': store => {
			store.set('phase', '1.0.2');
		},
		'>=2.0.0': store => {
			store.set('phase', '>=2.0.0');
		}
	}
});
The migration versions are compared with the projectVersion option.

If a migration throws, the changes it made are rolled back, and an error that includes its message is thrown. The migrations before it are kept.
beforeEachMigration
Type: Function
Default: undefined
The given callback function will be called before each migration step.
The function receives the store as the first argument and a context object as the second argument with the following properties:

fromVersion - The version the migration step is being migrated from.
toVersion - The version the migration step is being migrated to. For a range, this is the version it runs at.
finalVersion - The final version after all the migrations are applied.
versions - The versions that will run in this migration pass.

This can be useful for logging purposes, preparing migration data, etc.
Example:
import Conf from 'conf';

console.log = someLogger.log;

// Migrations do not run for a config file that does not exist yet, so these log for an app that has run before.

const mainConfig = new Conf({
	projectName: 'foo1',
	projectVersion: '0.4.0',
	beforeEachMigration: (store, context) => {
		console.log(`[main-config] migrate from ${context.fromVersion} → ${context.toVersion}`);
	},
	migrations: {
		'0.4.0': store => {
			store.set('debugPhase', true);
		},
	}
});

const secondConfig = new Conf({
	projectName: 'foo2',
	projectVersion: '1.0.1',
	beforeEachMigration: (store, context) => {
		console.log(`[second-config] migrate from ${context.fromVersion} → ${context.toVersion}`);
	},
	migrations: {
		'1.0.1': store => {
			store.set('debugPhase', true);
		},
	}
});
configName
Type: string
Default: 'config'
Name of the config file (without extension).
It may include a subdirectory of cwd, such as sub/config, but it must not point outside cwd.
Useful if you need multiple config files for your app or module. For example, different config files between two major versions.
projectName
Type: string
Required unless you specify the cwd option.
You can fetch the name field from package.json:
import Conf from 'conf';
import packageJson from './package.json' with {type: 'json'};

const config = new Conf({projectName: packageJson.name});
projectVersion
Type: string
Required if you specify the migrations option.
You can fetch the version field from package.json.
With migrations, it must be a full semantic version, such as 1.0.0.
cwd
Type: string
Default: System default user config directory
You most likely don't need this. Please don't use it unless you really have to. By default, it will pick the optimal location by adhering to system conventions. You are very likely to get this wrong and annoy users.
Overrides projectName.
By default the config is stored in the system user's config directory; running under another user reads a different store. Set cwd to share across users.
The only use case I can think of is having the config located in the app directory or on some external storage.
encryptionKey
Type: string | Uint8Array | TypedArray | DataView
Default: undefined
This is not intended for security purposes, since the encryption key would be easily found inside a plaintext 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.
When using aes-256-gcm, the config file is authenticated. If the file is changed in any way, the decryption will fail. With aes-256-cbc and aes-256-ctr, tampering can go undetected.
When specified, the store will be encrypted using the encryptionAlgorithm option (defaults to aes-256-cbc). An empty string is refused.
encryptionAlgorithm
Type: 'aes-256-cbc' | 'aes-256-gcm' | 'aes-256-ctr'
Default: 'aes-256-cbc'
Encryption algorithm to use when encryptionKey is set.
Use aes-256-gcm if you want authentication, otherwise use aes-256-cbc or aes-256-ctr.
Changing encryptionAlgorithm will make existing encrypted data unreadable.
When using aes-256-gcm or aes-256-ctr, existing plaintext config files are not supported. Delete the config file or migrate it before enabling encryption. With aes-256-cbc, existing plaintext config files are still readable for backward compatibility.
fileExtension
Type: string
Default: 'json'
Extension of the config file.
You would usually not need this, but it 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.
clearInvalidConfig
Type: boolean
Default: false
The config is cleared if reading the config file causes a SyntaxError (malformed JSON, also when thrown by your own deserialize), a schema validation error when using the schema option, or a decryption failure when using encryptionKey, and the cleared store is written over the file. This is a good behavior for unimportant data, 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.
A decryption failure includes a changed encryptionKey or encryptionAlgorithm, and a plaintext config file read with the aes-256-gcm or aes-256-ctr algorithm (for example, after adding encryption to an existing store). With your own deserialize and the aes-256-cbc or aes-256-ctr algorithm, a changed encryptionKey or encryptionAlgorithm is cleared only when your deserialize throws a SyntaxError for the data it cannot read, since those algorithms cannot tell a wrong key apart from damaged data. Any other error thrown by your own deserialize is thrown as is.
serialize
Type: Function
Default: value => JSON.stringify(value, null, '\t')
Function to serialize the config object to a UTF-8 string, or to a Uint8Array, 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.
deserialize
Type: Function
Default: JSON.parse, ignoring a leading byte order mark
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.
projectSuffix
Type: string
Default: 'nodejs'
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.
accessPropertiesByDotNotation
Type: boolean
Default: true
Access nested properties by dot notation. For example:
import Conf from 'conf';

const config = new Conf({projectName: 'foo'});

config.set({
	foo: {
		bar: {
			foobar: '🦄'
		}
	}
});

console.log(config.get('foo.bar.foobar'));
//=> '🦄'
Alternatively, you can set this option to false so the whole string is treated as one key.
import Conf from 'conf';

const config = new Conf({
	projectName: 'foo',
	accessPropertiesByDotNotation: false
});

config.set({
	'foo.bar.foobar': '🦄'
});

console.log(config.get('foo.bar.foobar'));
//=> '🦄'
With this option on, __proto__, constructor and prototype cannot be used in a key: .set() ignores such a key, .get() returns the default value for it, and the defaults and schema options throw for it. Set this option to false to use them as keys.
A key that is not a valid path, such as a[x, throws a TypeError.
watch
Type: boolean
Default: false
Watch for any changes in the config file and call the callback for onDidChange or onDidAnyChange if set. This is useful if there are multiple processes changing the same config file.
If the config file is a symlink, the file it points to when the store is created is watched.
cache
Type: boolean
Default: false
Keep the store in memory, so reading a value does not read and parse the config file each time. This makes reads much faster, in particular when the config file is large.
The cache is dropped on every write and whenever the watch option reports a change to the config file. Writes read the config file first, so changes made by another process are not lost, but reads only see them when watch is enabled or after a write.
The objects returned by .store, .get() and iteration, and the values passed to the onDidChange and onDidAnyChange callbacks, are the cache itself, so the plain objects and arrays in them are frozen. Changing one throws a TypeError. Use .set() and .delete() to write, and copy a value first if you want to change it, for example with structuredClone().
configFileMode
Type: number
Default: 0o666, reduced by the process umask
The mode used when creating the config file.
The mode is modified by the process umask, whether it is the default or given by this option. With the typical umask of 0o022, the default results in 0o644. Config files are also stored in a location that is typically protected already, so the default is usually fine.
When this option is given, the mode is also applied to an existing config file on every write. Otherwise, an existing config file keeps its mode. A mode given by this option that, after the umask, leaves the file unreadable by its owner throws.
You would usually not need this, but it could be useful if you use a custom cwd. Setting 0o600 would make the file only readable by the owner.
Setting restrictive permissions can cause problems if different users need to read the file. A common problem is a user running your tool with and without sudo and then not being able to access the config the second time.

Instance
You can use dot-notation in a key to access nested properties. A number addresses an element of an array. Setting an index past the end fills the gap with null, and .delete() removes the element, so the later elements move down.
The instance is iterable so you can use it directly in a for…of loop.
.set(key, value)
Set an item.
The value must be JSON serializable. Trying to set a value of type undefined, function, or symbol will result in a TypeError, and so will a bigint unless you use a custom serialize.
.set(object)
Set multiple items at once.
Each key replaces the whole value it names, so a nested object is not merged into the one the store holds. With dot notation, a key can be a path, such as {'foo.bar': 1}, which sets only that nested property.
.get(key, defaultValue?)
Get an item or defaultValue if the item does not exist.
Tip: To get all items, see .store.
.reset(...keys)
Reset items to their default values, as defined by the defaults or schema option. The default values of the schema option are not used when ajvOptions.useDefaults is false.
With dot notation, schema defaults below an optional object with no default of its own are unavailable to reset() when a parent default omits that object. Include the object in the parent default to reset its descendants individually.
Use .clear() to reset all items.
.has(key)
Check if an item exists.
.appendToArray(key, value)
Append an item to an array.
If the key doesn't exist, it will be created as an array. If the key exists and is not an array, a TypeError will be thrown.
The value must be JSON serializable. Trying to set a value of type undefined, function, or symbol will result in a TypeError, and so will a bigint unless you use a custom serialize.
config.set('items', [{name: 'foo'}]);
config.appendToArray('items', {name: 'bar'});
console.log(config.get('items'));
//=> [{name: 'foo'}, {name: 'bar'}]

// Creates array if key doesn't exist
config.appendToArray('newItems', 'first');
console.log(config.get('newItems'));
//=> ['first']
.delete(key)
Delete an item.
.clear()
Delete all items.
This resets known items to their default values, if defined by the defaults or schema option. The default values of the schema option are not used when ajvOptions.useDefaults is false.
.onDidChange(key, callback)
callback: (newValue, oldValue) => {}
Watches the given key, calling callback on any changes.
A change noticed while the config file cannot be read, for example while another process is writing it, is not reported.
When a key is first set, oldValue will be undefined, and when a key is deleted, newValue will be undefined.
Returns a function that unsubscribes when called:
const unsubscribe = config.onDidChange(key, callback);

unsubscribe();
.onDidAnyChange(callback)
callback: (newValue, oldValue) => {}
Watches the whole config object, calling callback on any changes.
A change noticed while the config file cannot be read, for example while another process is writing it, is not reported.
oldValue and newValue will be the config object before and after the change, respectively. You must compare oldValue to newValue to find out what changed.
Returns a function that unsubscribes when called:
const unsubscribe = config.onDidAnyChange(callback);

unsubscribe();
.events
An EventTarget that dispatches a change event on every write of this instance, and when the watch option reports a change to the config file. This is what .onDidChange() and .onDidAnyChange() listen on, and it is there if you want to listen directly:
config.events.addEventListener('change', () => {
	console.log('The config changed');
});
.size
Get the item count.
.store
Get all the config as an object or replace the current config with an object:
console.log(config.store);
//=> [Object: null prototype] {name: 'John', age: 30}
Unlike .set(), a whole-store write drops a function or a symbol, like JSON.stringify does, instead of throwing. A bigint still throws, unless you use a custom serialize.
config.store = {
	hello: 'world'
};
.path
Get the path to the config file.
FAQ
How is this different from configstore?
I'm also the author of configstore. While it's pretty good, I did make some mistakes early on that are hard to change at this point. This module is the result of everything I learned from making configstore. Mainly where the config is stored. In configstore, the config is stored in ~/.config (which is mainly a Linux convention) on all systems, while conf stores config in the system default user config directory. The ~/.config directory, it turns out, often has incorrect permissions on macOS and Windows, which has caused a lot of grief for users.
Can I use YAML or another serialization format?
The serialize and deserialize options can be used to customize the format of the config file, as long as the representation is compatible with UTF-8.
Example using YAML:
import Conf from 'conf';
import yaml from 'js-yaml';

const config = new Conf({
	projectName: 'foo',
	fileExtension: 'yaml',
	serialize: yaml.dump,
	deserialize: yaml.load
});
Can I use conf with strict Content Security Policy (CSP)?
conf depends on ajv for the schema option, which uses unsafe-eval. Even without using the schema option, ajv is still bundled and may cause CSP errors. As a workaround, you could configure your bundler to replace ajv with a stub:
// webpack.config.js
module.exports = {
	resolve: {
		alias: {
			'ajv': false,
			'ajv-formats': false
		}
	}
};
Can I use async operations in migrations?
Conf is synchronous by design, so this is not possible. As a workaround, you could use make-synchronous to convert asynchronous functions to synchronous (with caveats):
import Conf from 'conf';
import makeSynchronous from 'make-synchronous';

const config = new Conf({
	projectName: 'foo',
	projectVersion: '0.0.1',
	migrations: {
		'0.0.1': store => {
			const syncAsyncFunction = makeSynchronous(asyncFunction);
			const result = syncAsyncFunction();
			store.set('migrated', result);
		}
	}
});
Related

electron-store - Simple data persistence for your Electron app or module
cache-conf - Simple cache config handling for your app or module

: {
				type: 'object',
				properties: {
					schedule: {type: 'string'}
				}
			}
		}
	}
});

ajvOptions

Type: __INLINE_CODE_42__

Options passed to AJV.

Under the hood, the JSON Schema validator ajv is used to validate your config. We use JSON Schema draft-2020-12 and support all validation keywords and formats.

By default, __INLINE_CODE_43__ and __INLINE_CODE_44__ are both set to __INLINE_CODE_45__, but can be overridden.

Example:

__CODE_BLOCK_6__

migrations

Type: __INLINE_CODE_46__

Important: I cannot provide support for this feature. It has some known bugs. I have no plans to work on it, but pull requests are welcome.

You can use migrations to perform operations to the store whenever a project version is upgraded.

The __INLINE_CODE_47__ object should consist of key-value pairs of __INLINE_CODE_48__. The __INLINE_CODE_49__ can also be a semver range. Migrations run in version order, whatever order they are defined in.

A migration must not create another __INLINE_CODE_50__ instance with __INLINE_CODE_51__ for the same config file.

A migration sees the keys the config file holds and the values of the __INLINE_CODE_52__ option. The __INLINE_CODE_53__ values of the __INLINE_CODE_54__ option are added after the migrations have run, since a migration may repair a value the schema rejects.

The store keeps its migration bookkeeping in the config file under a reserved __INLINE_CODE_55__ key. It is not exposed through __INLINE_CODE_56__, __INLINE_CODE_57__, __INLINE_CODE_58__ or iteration, and __INLINE_CODE_59__ and __INLINE_CODE_60__ reject it.

The recorded version never moves backwards, so running an older __INLINE_CODE_61__ than the store was migrated with does not run those migrations again.

Migrations do not run for a config file that does not exist yet. There is no old data to migrate, so the store starts at the current project version. A config file that exists but has no recorded version is still migrated, which covers an app that shipped before it had migrations.

Example:

__CODE_BLOCK_7__

The migration versions are compared with the __INLINE_CODE_62__ option.

If a migration throws, the changes it made are rolled back, and an error that includes its message is thrown. The migrations before it are kept.

beforeEachMigration

Type: __INLINE_CODE_63__
Default: __INLINE_CODE_64__

The given callback function will be called before each migration step.

The function receives the store as the first argument and a context object as the second argument with the following properties:

• __INLINE_CODE_65__ - The version the migration step is being migrated from.
• __INLINE_CODE_66__ - The version the migration step is being migrated to. For a range, this is the version it runs at.
• __INLINE_CODE_67__ - The final version after all the migrations are applied.
• __INLINE_CODE_68__ - The versions that will run in this migration pass.

This can be useful for logging purposes, preparing migration data, etc.

Example:

__CODE_BLOCK_8__

configName

Type: __INLINE_CODE_69__
Default: __INLINE_CODE_70__

Name of the config file (without extension).

It may include a subdirectory of __INLINE_CODE_71__, such as __INLINE_CODE_72__, but it must not point outside __INLINE_CODE_73__.

Useful if you need multiple config files for your app or module. For example, different config files between two major versions.

projectName

Type: __INLINE_CODE_74__

Required unless you specify the __INLINE_CODE_75__ option.

You can fetch the __INLINE_CODE_76__ field from package.json:

__CODE_BLOCK_9__

projectVersion

Type: __INLINE_CODE_77__

Required if you specify the __INLINE_CODE_78__ option.

You can fetch the __INLINE_CODE_79__ field from package.json.

With __INLINE_CODE_80__, it must be a full semantic version, such as __INLINE_CODE_81__.

cwd

Type: __INLINE_CODE_82__
Default: System default user config directory

You most likely don't need this. Please don't use it unless you really have to. By default, it will pick the optimal location by adhering to system conventions. You are very likely to get this wrong and annoy users.

Overrides __INLINE_CODE_83__.

By default the config is stored in the system user's config directory; running under another user reads a different store. Set __INLINE_CODE_84__ to share across users.

The only use case I can think of is having the config located in the app directory or on some external storage.

encryptionKey

Type: __INLINE_CODE_85__
Default: __INLINE_CODE_86__

This is not intended for security purposes, since the encryption key would be easily found inside a plaintext 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.

When using __INLINE_CODE_87__, the config file is authenticated. If the file is changed in any way, the decryption will fail. With __INLINE_CODE_88__ and __INLINE_CODE_89__, tampering can go undetected.

When specified, the store will be encrypted using the __INLINE_CODE_90__ option (defaults to __INLINE_CODE_91__). An empty string is refused.

encryptionAlgorithm

Type: __INLINE_CODE_92__
Default: __INLINE_CODE_93__

Encryption algorithm to use when __INLINE_CODE_94__ is set.

Use __INLINE_CODE_95__ if you want authentication, otherwise use __INLINE_CODE_96__ or __INLINE_CODE_97__.

Changing __INLINE_CODE_98__ will make existing encrypted data unreadable.

When using __INLINE_CODE_99__ or __INLINE_CODE_100__, existing plaintext config files are not supported. Delete the config file or migrate it before enabling encryption. With __INLINE_CODE_101__, existing plaintext config files are still readable for backward compatibility.

fileExtension

Type: __INLINE_CODE_102__
Default: __INLINE_CODE_103__

Extension of the config file.

You would usually not need this, but it 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.

clearInvalidConfig

Type: __INLINE_CODE_104__
Default: __INLINE_CODE_105__

The config is cleared if reading the config file causes a __INLINE_CODE_106__ (malformed JSON, also when thrown by your own __INLINE_CODE_107__), a schema validation error when using the __INLINE_CODE_108__ option, or a decryption failure when using __INLINE_CODE_109__, and the cleared store is written over the file. This is a good behavior for unimportant data, 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.

A decryption failure includes a changed __INLINE_CODE_110__ or __INLINE_CODE_111__, and a plaintext config file read with the __INLINE_CODE_112__ or __INLINE_CODE_113__ algorithm (for example, after adding encryption to an existing store). With your own __INLINE_CODE_114__ and the __INLINE_CODE_115__ or __INLINE_CODE_116__ algorithm, a changed __INLINE_CODE_117__ or __INLINE_CODE_118__ is cleared only when your __INLINE_CODE_119__ throws a __INLINE_CODE_120__ for the data it cannot read, since those algorithms cannot tell a wrong key apart from damaged data. Any other error thrown by your own __INLINE_CODE_121__ is thrown as is.

serialize

Type: __INLINE_CODE_122__
Default: __INLINE_CODE_123__

Function to serialize the config object to a UTF-8 string, or to a __INLINE_CODE_124__, 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.

deserialize

Type: __INLINE_CODE_125__
Default: __INLINE_CODE_126__, ignoring a leading byte order mark

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.

projectSuffix

Type: __INLINE_CODE_127__
Default: __INLINE_CODE_128__

You most likely don't need this. Please don't use it unless you really have to.

Suffix appended to __INLINE_CODE_129__ 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 __INLINE_CODE_130__ directory, where __INLINE_CODE_131__ is the __INLINE_CODE_132__.

accessPropertiesByDotNotation

Type: __INLINE_CODE_133__
Default: __INLINE_CODE_134__

Access nested properties by dot notation. For example:

__CODE_BLOCK_10__

Alternatively, you can set this option to __INLINE_CODE_135__ so the whole string is treated as one key.

__CODE_BLOCK_11__

With this option on, __INLINE_CODE_136__, __INLINE_CODE_137__ and __INLINE_CODE_138__ cannot be used in a key: __INLINE_CODE_139__ ignores such a key, __INLINE_CODE_140__ returns the default value for it, and the __INLINE_CODE_141__ and __INLINE_CODE_142__ options throw for it. Set this option to __INLINE_CODE_143__ to use them as keys.

A key that is not a valid path, such as __INLINE_CODE_144__, throws a __INLINE_CODE_145__.

watch

Type: __INLINE_CODE_146__
Default: __INLINE_CODE_147__

Watch for any changes in the config file and call the callback for __INLINE_CODE_148__ or __INLINE_CODE_149__ if set. This is useful if there are multiple processes changing the same config file.

If the config file is a symlink, the file it points to when the store is created is watched.

cache

Type: __INLINE_CODE_150__
Default: __INLINE_CODE_151__

Keep the store in memory, so reading a value does not read and parse the config file each time. This makes reads much faster, in particular when the config file is large.

The cache is dropped on every write and whenever the __INLINE_CODE_152__ option reports a change to the config file. Writes read the config file first, so changes made by another process are not lost, but reads only see them when __INLINE_CODE_153__ is enabled or after a write.

The objects returned by __INLINE_CODE_154__, __INLINE_CODE_155__ and iteration, and the values passed to the __INLINE_CODE_156__ and __INLINE_CODE_157__ callbacks, are the cache itself, so the plain objects and arrays in them are frozen. Changing one throws a __INLINE_CODE_158__. Use __INLINE_CODE_159__ and __INLINE_CODE_160__ to write, and copy a value first if you want to change it, for example with __INLINE_CODE_161__.

configFileMode

Type: __INLINE_CODE_162__
Default: __INLINE_CODE_163__, reduced by the process umask

The mode used when creating the config file.

The mode is modified by the process umask, whether it is the default or given by this option. With the typical umask of __INLINE_CODE_164__, the default results in __INLINE_CODE_165__. Config files are also stored in a location that is typically protected already, so the default is usually fine.

When this option is given, the mode is also applied to an existing config file on every write. Otherwise, an existing config file keeps its mode. A mode given by this option that, after the umask, leaves the file unreadable by its owner throws.

You would usually not need this, but it could be useful if you use a custom __INLINE_CODE_166__. Setting __INLINE_CODE_167__ would make the file only readable by the owner.

Setting restrictive permissions can cause problems if different users need to read the file. A common problem is a user running your tool with and without __INLINE_CODE_168__ and then not being able to access the config the second time.

Instance

You can use dot-notation in a __INLINE_CODE_169__ to access nested properties. A number addresses an element of an array. Setting an index past the end fills the gap with __INLINE_CODE_170__, and __INLINE_CODE_171__ removes the element, so the later elements move down.

The instance is __INLINE_CODE_172__ so you can use it directly in a __INLINE_CODE_173__ loop.

.set(key, value)

Set an item.

The __INLINE_CODE_174__ must be JSON serializable. Trying to set a value of type __INLINE_CODE_175__, __INLINE_CODE_176__, or __INLINE_CODE_177__ will result in a __INLINE_CODE_178__, and so will a __INLINE_CODE_179__ unless you use a custom __INLINE_CODE_180__.

.set(object)

Set multiple items at once.

Each key replaces the whole value it names, so a nested object is not merged into the one the store holds. With dot notation, a key can be a path, such as __INLINE_CODE_181__, which sets only that nested property.

.get(key, defaultValue?)

Get an item or __INLINE_CODE_182__ if the item does not exist.

Tip: To get all items, see __INLINE_CODE_183__.

.reset(...keys)

Reset items to their default values, as defined by the __INLINE_CODE_184__ or __INLINE_CODE_185__ option. The __INLINE_CODE_186__ values of the __INLINE_CODE_187__ option are not used when __INLINE_CODE_188__ is __INLINE_CODE_189__.

With dot notation, schema defaults below an optional object with no default of its own are unavailable to __INLINE_CODE_190__ when a parent default omits that object. Include the object in the parent default to reset its descendants individually.

Use __INLINE_CODE_191__ to reset all items.

.has(key)

Check if an item exists.

.appendToArray(key, value)

Append an item to an array.

If the key doesn't exist, it will be created as an array. If the key exists and is not an array, a __INLINE_CODE_192__ will be thrown.

The __INLINE_CODE_193__ must be JSON serializable. Trying to set a value of type __INLINE_CODE_194__, __INLINE_CODE_195__, or __INLINE_CODE_196__ will result in a __INLINE_CODE_197__, and so will a __INLINE_CODE_198__ unless you use a custom __INLINE_CODE_199__.

__CODE_BLOCK_12__

.delete(key)

Delete an item.

.clear()

Delete all items.

This resets known items to their default values, if defined by the __INLINE_CODE_200__ or __INLINE_CODE_201__ option. The __INLINE_CODE_202__ values of the __INLINE_CODE_203__ option are not used when __INLINE_CODE_204__ is __INLINE_CODE_205__.

.onDidChange(key, callback)

__INLINE_CODE_206__: __INLINE_CODE_207__

Watches the given __INLINE_CODE_208__, calling __INLINE_CODE_209__ on any changes.

A change noticed while the config file cannot be read, for example while another process is writing it, is not reported.

When a key is first set, __INLINE_CODE_210__ will be __INLINE_CODE_211__, and when a key is deleted, __INLINE_CODE_212__ will be __INLINE_CODE_213__.

Returns a function that unsubscribes when called:

__CODE_BLOCK_13__

.onDidAnyChange(callback)

__INLINE_CODE_214__: __INLINE_CODE_215__

Watches the whole config object, calling __INLINE_CODE_216__ on any changes.

A change noticed while the config file cannot be read, for example while another process is writing it, is not reported.

__INLINE_CODE_217__ and __INLINE_CODE_218__ will be the config object before and after the change, respectively. You must compare __INLINE_CODE_219__ to __INLINE_CODE_220__ to find out what changed.

Returns a function that unsubscribes when called:

__CODE_BLOCK_14__

.events

An __INLINE_CODE_221__ that dispatches a __INLINE_CODE_222__ event on every write of this instance, and when the __INLINE_CODE_223__ option reports a change to the config file. This is what __INLINE_CODE_224__ and __INLINE_CODE_225__ listen on, and it is there if you want to listen directly:

__CODE_BLOCK_15__

.size

Get the item count.

.store

Get all the config as an object or replace the current config with an object:

__CODE_BLOCK_16__

Unlike __INLINE_CODE_226__, a whole-store write drops a function or a symbol, like __INLINE_CODE_227__ does, instead of throwing. A __INLINE_CODE_228__ still throws, unless you use a custom __INLINE_CODE_229__.

__CODE_BLOCK_17__

.path

Get the path to the config file.

FAQ

How is this different from __INLINE_CODE_230__?

I'm also the author of __INLINE_CODE_231__. While it's pretty good, I did make some mistakes early on that are hard to change at this point. This module is the result of everything I learned from making __INLINE_CODE_232__. Mainly where the config is stored. In __INLINE_CODE_233__, the config is stored in __INLINE_CODE_234__ (which is mainly a Linux convention) on all systems, while __INLINE_CODE_235__ stores config in the system default user config directory. The __INLINE_CODE_236__ directory, it turns out, often has incorrect permissions on macOS and Windows, which has caused a lot of grief for users.

Can I use YAML or another serialization format?

The __INLINE_CODE_237__ and __INLINE_CODE_238__ options can be used to customize the format of the config file, as long as the representation is compatible with UTF-8.

Example using YAML:

__CODE_BLOCK_18__

Can I use __INLINE_CODE_239__ with strict Content Security Policy (CSP)?

__INLINE_CODE_240__ depends on __INLINE_CODE_241__ for the __INLINE_CODE_242__ option, which uses __INLINE_CODE_243__. Even without using the __INLINE_CODE_244__ option, __INLINE_CODE_245__ is still bundled and may cause CSP errors. As a workaround, you could configure your bundler to replace __INLINE_CODE_246__ with a stub:

__CODE_BLOCK_19__

Can I use async operations in migrations?

Conf is synchronous by design, so this is not possible. As a workaround, you could use __INLINE_CODE_247__ to convert asynchronous functions to synchronous (with caveats):

__CODE_BLOCK_20__

Related

• electron-store - Simple data persistence for your Electron app or module
• cache-conf - Simple cache config handling for your app or module