keyvalue v1.0.0

keyvalue

Simple key/value manager suitable for configuration data.

Supports loading and saving YAML and JSON formatted files. Format can be implicitely detected based on the filename, or explicitly given as an option to the .load() and .save() methods.

• Getting a value that does not exist will return null.
• Setting a value that is not a valid JSON type will throw an exception.
• Setting a value to null or undefined removes it.

Installation

npm install keyvalue --save

Example

var KeyValue = require('keyvalue');

// Create a new KeyValue instance that saves formatted data with 4 space indents
// and does NOT use atomic saving.
var instance = new KeyValue({
	indent: 4,
	atomic: false
});

// Load data from './filename.yaml' implicitly parsed as YAML based on the
// yaml/yml extension.
instance.load('./filename.yaml');

// Replace or add the value of 'key'.
instance.set('key', value);

// Only set the value of 'key' if it's set.
instance.setIfMissing('key', value);

// Only set the value of 'key' if it's NOT set.
instance.setIfExists('key', value);

// May log 'null' if 'key' is not set.
console.log(instance.get('key'));

// Log the value of 'key' or the string "key was not set" if it's not set.
console.log(instance.getOrDefault('key', "key was not set"));

// Save data to './filename' explicitly formatted as YAML, indented 8 spaces,
// and using the atomic file write method. The indent and atomic options
// override those set when the KeyValue instance was created.
instance.save('./filename', {
	format: 'yaml',
	indent: 8,
	atomic: true
});

API

new KeyValue([options])

Create a new KeyValue instance.

The options argument is optional.

options

• indent number|String Default value: 2 Number values indicate the number of spaces to indent formatted data. * String values are interpreted as numbers for YAML, and as the literal indent string for JSON.
• atomic boolean Default value: true If this option is not present or true, a temporary file will be used for saving, and then moved to replace the destination file. This is a safer way to write files than simply replacing the contents in place, but it may confuse some filesystem watchers. * If this option is false, the file contents will be overwritten in place and no temporary file will be used.

.load(filename, [options])

Read JSON or YAML formatted data from a file.

If the KeyValue instance already has keys that do not exist in the file, they will NOT be deleted by loading. Loading only adds or replaces keys in the instance.

The options argument is optional.

This method is synchronous.

Returns the KeyValue instance.

options

• format String Valid values: 'json', 'yaml', null Default value: null * If this option is not set or null, then the filename extension will be used to determine the format. It will default to JSON if the filename does not end with '.yaml' or '.yml'.

.set(key, [subkey1, subkey2, ...], value)

Set a value in the KeyValue instance. If the key or any intermediate subkey does not exist or is null, it will be replaced with an object. If any parent value is a non-object, it will be auto-boxed.

If the value to be set is null or undefined, then the value will be deleted.

Using the set method will never throw an exception, unlike accessing the subkeys directly. If any parent values are not set, then plain objects will be automatically inserted.

Returns the previous value or null.

.setIfMissing(key, [subkey1, subkey2, ...], value)

Identical to the .set() method, except that if the value is already set, then this is a no-op and the value will not be changed.

Returns the previous value or null.

.setIfExists(key, [subkey1, subkey2, ...], value)

Identical to the .set() method, except that if the value is NOT set, then this is a no-op and the value will not be changed.

Returns the previous value or null.

.get(key, [subkey1, subkey2, ...])

Get a value from the KeyValue instance. If the value for any key does not exist, null will be returned.

Using the .get() method will never throw an exception, unlike accessing the subkeys directly. If any parent values are not set, then null will be returned.

Returns the value or null.

.getOrDefault(key, [subkey1, subkey2, ...], defaultValue)

Identical to the .get() method, except that if null would be returned, then defaultValue is returned instead.

Returns the value or the default value if the actual value is unset.

.save(filename, [options])

Write JSON or YAML formatted data to a file.

The options argument is optional.

This method is synchronous.

Returns this KeyValue instance.

options

• format String Valid values: 'json', 'yaml', null Default value: null * If this option is not set or null, then the filename extension will be used to determine the format. It will default to JSON if the filename does not end with '.yaml' or '.yml'.
• indent number|String * Overrides the constructor indent option.
• atomic boolean * Overrides the constructor atomic option.