data-store

data-store

Easily get, set and persist config data.

You might also be interested in base-store.

Table of Contents

• Install
• Usage example
• API
• About

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save data-store

Usage example

// default cwd is `~/data-store/` (in user-home)
var store = require('data-store')('my-app');

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.

About

Related projects

• 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

Contributing

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

Contributors

Commits	Contributor
128	jonschlinkert
3	doowb
2	tunnckoCore

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

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

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

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

---

This file was generated by verb-generate-readme, v0.6.0, on May 22, 2017.

Changelog

[1.0.0] - 2017-05-22

• run update
• update deps, remove verbfile.js
• add example to readme
• allow store.path to be set directly