Easily persist and load config data. No dependencies.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.

• Install
• Usage example
• API
• Options
• Example: setting path options
• About

(TOC generated by verb using markdown-toc)

Install with npm (requires Node.js >=8):

$ npm install --save data-store

By default a JSON file is created with the name of the store in the ~/.config/data-store/ directory. This is completely customizable via options.

// create a config store ("foo.json") in the current working directory
const store = require('data-store')({ path: process.cwd() + '/foo.json' });

store.set('one', 'two'); 
console.log(store.data); //=> { one: 'two' }

store.set('x.y.z', 'boom!');
store.set({ c: 'd' });

console.log(store.get('e.f'));
//=> 'g'

console.log(store.get());
//=> { name: 'app', data: { a: 'b', c: 'd', e: { f: 'g' } } }

console.log(store.data);
//=> { a: 'b', c: 'd', e: { f: 'g' } }

You may also access the Store class if you need to extend or modify the class:

const { Store } = require('data-store');

class MyClass extends Store {
  constructor(...args) {
    super(...args);
  }
}

Initialize a new Store with the given name, options and default data.

Params

• name {String}: Store name to use for the basename of the .json file.
• options {object}: See all available options.
• defaults {object}: An object to initialize the store with.

Example

const store = require('data-store')('abc');
//=> '~/data-store/a.json'

const store = require('data-store')('abc', { cwd: 'test/fixtures' });
//=> './test/fixtures/abc.json'

Assign value to key and save to the file system. Can be a key-value pair, array of objects, or an object.

Params

• key {String}
• val {any}: The value to save to key. Must be a valid JSON type: String, Number, Array or Object.
• returns {Object} Store: for chaining

Example

// key, value
store.set('a', 'b');
//=> {a: 'b'}

// extend the store with an object
store.set({a: 'b'});
//=> {a: 'b'}

Assign value to key while retaining prior members of value if value is a map. If value is not a map, overwrites like .set.

Params

• key {String}
• val {any}: The value to merge to key. Must be a valid JSON type: String, Number, Array or Object.
• returns {Object} Store: for chaining

Example

store.set('a', { b: c });
//=> {a: { b: c }}

store.merge('a', { d: e });
//=> {a: { b: c, d: e }}

store.set('a', 'b');
//=> {a: 'b'}

store.merge('a', { c : 'd' });
//=> {a: { c : 'd' }}

Add the given value to the array at key. Creates a new array if one doesn't exist, and only adds unique values to the array.

Params

• key {String}
• val {any}: The value to union to key. Must be a valid JSON type: String, Number, Array or Object.
• returns {Object} Store: for chaining

Example

store.union('a', 'b');
store.union('a', 'c');
store.union('a', 'd');
store.union('a', 'c');
console.log(store.get('a'));
//=> ['b', 'c', 'd']

Get the stored value of key.

Params

• key {String}
• returns {any}: The value to store for key.

Example

store.set('a', {b: 'c'});
store.get('a');
//=> {b: 'c'}

store.get();
//=> {a: {b: 'c'}}

Returns true if the specified key has a value.

Params

• key {String}
• returns {Boolean}: Returns true if key has

Example

store.set('a', 42);
store.set('c', null);

store.has('a'); //=> true
store.has('c'); //=> true
store.has('d'); //=> false

Returns true if the specified key exists.

Params

• key {String}
• returns {Boolean}: Returns true if key exists

Example

store.set('a', 'b');
store.set('b', false);
store.set('c', null);
store.set('d', true);
store.set('e', undefined);

store.hasOwn('a'); //=> true
store.hasOwn('b'); //=> true
store.hasOwn('c'); //=> true
store.hasOwn('d'); //=> true
store.hasOwn('e'); //=> true
store.hasOwn('foo'); //=> false

Delete one or more properties from the store.

Params

• keys {String|Array}: One or more properties to delete.

Example

store.set('foo.bar', 'baz');
console.log(store.data); //=> { foo: { bar: 'baz' } }
store.del('foo.bar');
console.log(store.data); //=> { foo: {} }
store.del('foo');
console.log(store.data); //=> {}

Return a clone of the store.data object.

• returns {Object}

Example

console.log(store.clone());

Clear store.data to an empty object.

• returns {undefined}

Example

store.clear();

Stringify the store. Takes the same arguments as JSON.stringify.

Params

• replacer {Function}: Replacer function.
• indent {String}: Indentation to use. Default is 2 spaces.
• returns {String}

Example

console.log(store.json(null, 2));

Calls .writeFile() to persist the store to the file system, after an optional debounce period. This method should probably not be called directly as it's used internally by other methods.

• returns {undefined}

Example

store.save();

Delete the store from the file system.

• returns {undefined}

Example

store.unlink();

You can set the store path using options.path:

const os = require('os');
const path = require('path');
const store = new Store({
  path: path.join(os.homedir(), '.config/my_app/settings.json')
});

console.log(store.path);
// '~/.config/my_app/settings.json'

Or you can set the path using a combination of path parts. The following is equivalent to the previous example:

const os = require('os');
const store = new Store({
  home: os.homedir(),
  base: '.config/my_app',
  name: 'settings'
});

console.log(store.path);
// '~/.config/my_app/settings.json'

$ npm install && npm test

$ npm install -g verbose/verb#dev verb-generate-readme && verb

You might also be interested in these projects:

• get-value: Use property paths like 'a.b.c' to get a nested value from an object. Even works… more | homepage
• has-value: Returns true if a value exists, false if empty. Works with deeply nested values using… more | homepage
• set-value: Create nested values and any intermediaries using dot notation ('a.b.c') paths. | homepage
• write: Write data to a file, replacing the file if it already exists and creating any… more | homepage

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

Copyright © 2019, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.8.0, on November 12, 2019.