data-store

    4.0.3 • Public • Published

    data-store Donate NPM version NPM monthly downloads NPM total downloads Build Status

    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.

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

    .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
    168 jonschlinkert
    4 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 September 13, 2019.

    Install

    npm i data-store

    DownloadsWeekly Downloads

    35,833

    Version

    4.0.3

    License

    MIT

    Unpacked Size

    34.3 kB

    Total Files

    6

    Last publish

    Collaborators

    • jonschlinkert
    • doowb