Awesome
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 :heart: and support.
(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 tokey
. 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 tokey
. 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 tokey
. 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 forkey
.
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 ifkey
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 ifkey
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
<details> <summary><strong>Contributing</strong></summary>Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
</details> <details> <summary><strong>Running Tests</strong></summary>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
</details>
<details>
<summary><strong>Building docs</strong></summary>
(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
</details>
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
Copyright © 2019, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on November 12, 2019.