# data-store
> Easily persist and load config data. No dependencies.
Latest version **4.0.3** (published 2019-09-13) · MIT license · 0 weekly downloads
## Install
```sh
npm install data-store
pnpm add data-store
yarn add data-store
bun add data-store
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 4.0.3 |
| Published | 2019-09-13 |
| First published | 2014-05-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8 |
| Dependencies | 2 |
| Unpacked size | 33.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 160 |
| Author | Jon Schlinkert |
| Maintainers | jonschlinkert |
| Keywords | app, cache, config, config-store, configstore, data, defaults, get, has, has-own, hash, json, kv, key-value, local, object, options, own, persist, save, set, storage, store, union, write |
## Links
- npm: https://www.npmjs.com/package/data-store
- Repository: https://github.com/jonschlinkert/data-store
- Issues: https://github.com/jonschlinkert/data-store/issues
- npm.io page: https://npm.io/package/data-store
## Dependencies (2)
- [get-value](https://npm.io/package/get-value.md) ^3.0.1
- [set-value](https://npm.io/package/set-value.md) ^3.0.1
## Alternatives
- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads
## Recent versions
- 4.0.3 (latest) — 2019-09-13
- 4.0.2 — 2019-09-13
- 4.0.1 — 2019-09-13
- 4.0.0 — 2019-09-13
- 3.1.0 — 2018-09-04
- 3.0.3 — 2018-07-01
- 3.0.2 — 2018-07-01
- 3.0.1 — 2018-06-10
- 3.0.0 — 2018-05-11
- 2.0.1 — 2018-05-01
- 2.0.0 — 2018-05-01
- 1.0.0 — 2017-05-22
- 0.16.1 — 2016-07-11
- 0.16.0 — 2016-05-19
- 0.15.5 — 2016-03-02
- … 30 more at https://npm.io/package/data-store/versions
## README
# data-store [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [](https://www.npmjs.com/package/data-store) [](https://npmjs.org/package/data-store) [](https://npmjs.org/package/data-store) [](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#L76)
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'}
```
### [.union](index.js#L113)
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#L138)
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#L164)
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#L191)
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#L212)
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#L236)
Return a clone of the `store.data` object.
* `returns` **{Object}**
**Example**
```js
console.log(store.clone());
```
### [.clear](index.js#L251)
Clear `store.data` to an empty object.
* `returns` **{undefined}**
**Example**
```js
store.clear();
```
### [.json](index.js#L269)
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#L303)
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#L320)
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** |
| --- | --- |
| 168 | [jonschlinkert](https://github.com/jonschlinkert) |
| 4 | [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 September 13, 2019._
---
_Source: https://npm.io/package/data-store · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._