Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jonschlinkert/data-store

Easily get, set and persist config data. Fast. Supports dot-notation in keys. No dependencies.
https://github.com/jonschlinkert/data-store

cache conf config configstore data javascript json nodejs persist store stort

Last synced: 29 days ago
JSON representation

Easily get, set and persist config data. Fast. Supports dot-notation in keys. No dependencies.

Awesome Lists containing this project

README 

        
# data-store [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/data-store.svg?style=flat)](https://www.npmjs.com/package/data-store) [![NPM monthly downloads](https://img.shields.io/npm/dm/data-store.svg?style=flat)](https://npmjs.org/package/data-store) [![NPM total downloads](https://img.shields.io/npm/dt/data-store.svg?style=flat)](https://npmjs.org/package/data-store) [![Build Status](https://travis-ci.org/jonschlinkert/data-store.svg?branch=master)](https://travis-ci.org/jonschlinkert/data-store)



> Easily persist and load config data. No dependencies.



Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.



- [Install](#install)

- [Usage example](#usage-example)

- [API](#api)

- [Options](#options)

- [Example: setting path options](#example-setting-path-options)

- [About](#about)



_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_



## Install



Install with [npm](https://www.npmjs.com/) (requires [Node.js](https://nodejs.org/en/) >=8):



```sh

$ 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](#options).



```js

// 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:



```js

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



class MyClass extends Store {

  constructor(...args) {

    super(...args);

  }

}

```



## API



### [Store](index.js#L34)



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](#options).

* `defaults` **{object}**: An object to initialize the store with.



**Example**



```js

const store = require('data-store')('abc');

//=> '~/data-store/a.json'



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

//=> './test/fixtures/abc.json'

```



### [.set](index.js#L84)



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



```js

// key, value

store.set('a', 'b');

//=> {a: 'b'}



// extend the store with an object

store.set({a: 'b'});

//=> {a: 'b'}

```



### [.merge](index.js#L127)



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



```js

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](index.js#L154)



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



```js

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](index.js#L179)



Get the stored `value` of `key`.



**Params**



* `key` **{String}**

* `returns` **{any}**: The value to store for `key`.



**Example**



```js

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

store.get('a');

//=> {b: 'c'}



store.get();

//=> {a: {b: 'c'}}

```



### [.has](index.js#L208)



Returns `true` if the specified `key` has a value.



**Params**



* `key` **{String}**

* `returns` **{Boolean}**: Returns true if `key` has



**Example**



```js

store.set('a', 42);

store.set('c', null);



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

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

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

```



### [.hasOwn](index.js#L235)



Returns `true` if the specified `key` exists.



**Params**



* `key` **{String}**

* `returns` **{Boolean}**: Returns true if `key` exists



**Example**



```js

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](index.js#L256)



Delete one or more properties from the store.



**Params**



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



**Example**



```js

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](index.js#L282)



Return a clone of the `store.data` object.



* `returns` **{Object}**



**Example**



```js

console.log(store.clone());

```



### [.clear](index.js#L297)



Clear `store.data` to an empty object.



* `returns` **{undefined}**



**Example**



```js

store.clear();

```



### [.json](index.js#L315)



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



```js

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

```



### [.save](index.js#L349)



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



* `returns` **{undefined}**



**Example**



```js

store.save();

```



### [.unlink](index.js#L370)



Delete the store from the file system.



* `returns` **{undefined}**



**Example**



```js

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](#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()](#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`:



```js

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:



```js

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](../../issues/new).



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:



```sh

$ npm install && npm test

```



Building docs



_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_



To generate the readme, run the following command:



```sh

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

```



### Related projects



You might also be interested in these projects:



* [get-value](https://www.npmjs.com/package/get-value): Use property paths like 'a.b.c' to get a nested value from an object. Even works… [more](https://github.com/jonschlinkert/get-value) | [homepage](https://github.com/jonschlinkert/get-value "Use property paths like 'a.b.c' to get a nested value from an object. Even works when keys have dots in them (no other dot-prop library can do this!).")

* [has-value](https://www.npmjs.com/package/has-value): Returns true if a value exists, false if empty. Works with deeply nested values using… [more](https://github.com/jonschlinkert/has-value) | [homepage](https://github.com/jonschlinkert/has-value "Returns true if a value exists, false if empty. Works with deeply nested values using object paths.")

* [set-value](https://www.npmjs.com/package/set-value): Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths. | [homepage](https://github.com/jonschlinkert/set-value "Create nested values and any intermediaries using dot notation (`'a.b.c'`) paths.")

* [write](https://www.npmjs.com/package/write): Write data to a file, replacing the file if it already exists and creating any… [more](https://github.com/jonschlinkert/write) | [homepage](https://github.com/jonschlinkert/write "Write data to a file, replacing the file if it already exists and creating any intermediate directories if they don't already exist. Thin wrapper around node's native fs methods.")



### Contributors



| **Commits** | **Contributor** |  

| --- | --- |  

| 177 | [jonschlinkert](https://github.com/jonschlinkert) |  

| 7   | [derrell](https://github.com/derrell) |  

| 5   | [doowb](https://github.com/doowb) |  

| 3   | [nytamin](https://github.com/nytamin) |  

| 2   | [tunnckoCore](https://github.com/tunnckoCore) |  

| 1   | [jamen](https://github.com/jamen) |  

| 1   | [ArtskydJ](https://github.com/ArtskydJ) |  



### Author



**Jon Schlinkert**



* [GitHub Profile](https://github.com/jonschlinkert)

* [Twitter Profile](https://twitter.com/jonschlinkert)

* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)



### License



Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).

Released under the [MIT License](LICENSE).



***



_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on November 12, 2019._