data-store

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

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

$ npm install --save data-store

Usage example

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);
  }
}

API

Store

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'

.set

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

.merge

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

.union

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

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

.has

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

.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.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

.del

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); //=> {}

.clone

Return a clone of the store.data object.

returns {Object}

Example

console.log(store.clone());

.clear

Clear store.data to an empty object.

returns {undefined}

Example

store.clear();

.json

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));

.save

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();

.unlink

Delete the store from the file system.

returns {undefined}

Example

store.unlink();

Options

Option	Type	Default	Description
`debounce`	`number`	`undefined`	Disabled by default. Milliseconds to delay writing the JSON file to the file system. This can make the store more performant by preventing multiple subsequent writes after calling `.set` or setting/getting `store.data`, but comes with the potential side effect that the config file will be outdated during the timeout. To get around this, use data-store's API to (re-)load the file instead of directly reading the file (using `fs.readFile` for example).
`indent`	`number∣null`	`2`	The indent value to pass to `JSON.stringify()` when writing the file to the fs, or when .json() is called
`name`	`string`	`undefined`	The name to use for the store file stem (`name + '.json'` is the store's file name)
`home`	`string`	`process.env.XDG_CONFIG_HOME` or `path.join(os.homedir(), '.config')`	The root home directory to use
`base`	`string`	`path.join(home, 'data-store')`	The relative sub-folder to join to `home` for data-store config files.
`path`	`string`	`...`	Absolute file path for the data-store JSON file. This is created by joining `base` to `name + '.json'`. Setting this value directly will override the `name`, `home` and `base` values.

Example: setting path options

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'

About

Contributing

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

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

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

Related projects

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

Contributors

Commits	Contributor
177	jonschlinkert
7	derrell
5	doowb
3	nytamin
2	tunnckoCore
1	jamen
1	ArtskydJ

Author

Jon Schlinkert

License

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

pfandrade/data-store

data-store

Install

Usage example

API

Options

Example: setting path options

About

Related projects

Contributors

Author

License