data-store

Easily get, set and persist config data.

TOC

• Install
• Usage example
• API
• Related projects
• Contributing
• Building docs
• Running tests
• Author
• License

Install

Install with npm:

$ npm install data-store --save

Usage example

// default cwd is `~/data-store/`
var store = require('data-store')('app', {cwd: 'actual'});

store
  .set('a', 'b')
  .set({c: 'd'})
  .set('e.f', 'g')

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'}}

API

Store

Initialize a new Store with the given name and options.

Params

• name {String}: Store name to use for the basename of the .json file.
• options {Object}
• options.cwd {String}: Current working directory for storage. If not defined, the user home directory is used, based on OS. This is the only option currently, other may be added in the future.
• options.indent {Number}: Number passed to JSON.stringify when saving the data. Defaults to 2 if null or undefined

Example

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

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

.create

Create a namespaced "sub-store" that persists data to its file in a sub-folder of the same directory as the "parent" store.

Params

• name {String}: The name of the sub-store.
• options {Object}
• returns {Object}: Returns the sub-store instance.

Example

store.create('foo');
store.foo.set('a', 'b');
console.log(store.foo.get('a'));
//=> 'b'

.set

Assign value to key and save to disk. Can be a key-value pair 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'}

// extend the the given value
store.set('a', {b: 'c'});
store.set('a', {d: 'e'}, true);
//=> {a: {b 'c', d: 'e'}}

// overwrite the the given value
store.set('a', {b: 'c'});
store.set('a', {d: 'e'});
//=> {d: 'e'}

.union

Add or append an array of unique values to the given key.

Params

• key {String}
• returns {any}: The array to add or append for key.

Example

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

.get

Get the stored value of key, or return the entire store if no key is defined.

Params

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

Example

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

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

.has

Returns true if the specified key has truthy value.

Params

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

Example

store.set('a', 'b');
store.set('c', null);
store.has('a'); //=> true
store.has('c'); //=> false
store.has('d'); //=> false

.hasOwn

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.hasOwn('a'); //=> true
store.hasOwn('b'); //=> true
store.hasOwn('c'); //=> true
store.hasOwn('d'); //=> true
store.hasOwn('foo'); //=> false

.save

Persist the store to disk.

Params

• dest {String}: Optionally define an alternate destination file path.

Example

store.save();

.clear

Clear in-memory cache.

Example

store.clear();

.del

Delete keys from the store, or delete the entire store if no keys are passed. A del event is also emitted for each key deleted.

Note that to delete the entire store you must pass {force: true}

Params

• keys {String|Array|Object}: Keys to remove, or options.
• options {Object}

Example

store.del();

// to delete paths outside cwd
store.del({force: true});

.define

Define a non-enumerable property on the instance.

Params

• key {String}
• value {any}
• returns {Object}: Returns the instance for chaining.

Related projects

• base: base is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting… more | homepage
• base-store: Plugin for getting and persisting config values with your base-methods application. Adds a 'store' object… more | homepage
• cache-base: Basic object cache with get, set, del, and has methods for node.js/javascript projects. | homepage
• get-value: Use property paths ( a.b.c) to get a nested value from an object. | homepage
• set-value: Create nested values and any intermediaries using dot notation ('a.b.c') paths. | homepage
• union-value: Set an array of unique values as the property of an object. Supports setting deeply… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

Generate readme and API documentation with verb:

$ npm install verb && npm run docs

Or, if verb is installed globally:

$ verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016 Jon Schlinkert Released under the MIT license.

This file was generated by verb, v0.9.0, on February 27, 2016.