bouillon
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.1 • Public • Published

    Bouillon

    Simple JSON storage API for working with persistent data in various types of Node applications

    NPM version Known Vulnerabilities npm NPM downloads issues license Gitter

    Bouillon is a persistant storage solution for Node that lets you manage your data as an object and when you're ready it will encrypt and write the file for you atomically to disk. You can work with your local copy of the data and save/read the stored version at any time.

    As Bouillon saves your data atomically, you know that you'll always have a good version of your data even if there was an error while saving.

    Bouillon has only one dependency and that is NPM's write-file-atomic which is used to save the data atomically.

    Installation

    Bouillon requires node 7.6.0 or greater for ES2015 and async support.

    $ npm install --save bouillon
    

    Initialization

    Like any other module, to use Bouillion in your project you have to require it. After requiring it, you have to initialize it with a set of options with at the name option set.

    The list of initialization options are as shown:

    Type Option Description Default Required
    string name Name of your project null yes
    string cwd Your project's directory or the directory where you would like to save the data Your current project's working directory. no
    boolean autosave Whether to save the data to the file automatically after setting any data false no
    string encryptionKey An aes-256 compatible key to use for encrypting saved data null no

    Note: Using an encryption key is highly recommended so the data is not saved as plain text.

    Basic Example

    To begin using Bouillion, simply require the module, setup your desired options and create a new instance of Bouillon.

    const Bouillon = require('bouillon');
     
    const options = {
      name: 'my-cool-node-app',
      encryptionKey: 'PfHJgpKNEKawuTHDCRmdTZKMyfvSZGnf',
    };
     
    let bouillon = new Bouillon(options);

    From there you're free to modify the local object and save it.

    bouillon.set('favorite.movie', 'Iron Man');
     
    bouillon.write()
        .then((data) => {
            // Do something after you write.
        });
     
    // Or write synchronously.
    bouillon.writeSync();

    API

    get(key)

    get(key) will check the local data object for the specified key and return the value if the key exists. For deep searches, you can input a key with dot notation, for example example: bouillon.get('favorite.movies.action') will instruct bouillon to search for the nested action key. If the specified key does not exist, bouillion will simply return undefined.

    Type Option Description Default
    string key The key to search for using dot notation for a nested key null

    Using the following sample storage,

    {
        hello: world,
        favorite: {
            movie: {
                action: 'Indiana Jones'
            }
        }
    }

    Getting a top level value:

    bouillon.get('hello'); 
    // => 'world'

    Getting a deep nested value

    bouillion.get('favorite.movie.action'); 
    // => 'Indiana Jones'

    set(key, value)

    set(key, value) will insert a key and value at at the specified position in the object. If you want to set a deep nested key, use dot notation to specify the path to the key like in the get().

    Type Option Description Default
    string key The key to insert or update, if nested use dot notation null
    Mixed value The value to add for the specified key null

    Using the following sample storage,

    {
        hello: world,
        favorite: {
            movie: {
                action: 'Indiana Jones'
            }
        }
    }

    Set a top level key to a different value:

    bouillon.set('hello', 'my darling!');

    Which causes the object to now look like:

    {
        hello: 'my darling!',
        favorite: {
            movie: {
                action: 'Indiana Jones'
            }
        }
    }

    If you would like to set a deep nested key, such as adding other movies to our favorite movies, use the following:

    bouillon.set('favorite.movie.comedy', ['Marley and Me', 'Bridesmaids', 'Dinner for Schmucks']);

    Which causes the object to now look like:

    {
        hello: 'my darling!',
        favorite: {
            movie: {
                action: 'Indiana Jones',
                comedy: ['Marley and Me', 'Bridesmaids', 'Dinner for Schmucks']
            }
        }
    }

    write()

    write() takes the current storage object and writes it to disk in the path specified by options.cwd or in your projects directory by default. This version of write returns a promise so you must use .then() or call it in an async function.

    Example using .then():

    bouillon.write()
        .then(() => {
            // No data is returned but you can do something after it writes if you please.
        })
        .catch((err) => {
            console.log(err);
        });

    Using it in an async fashion accomplishes the same task it just looks cleaner:

    await bouillon.write().catch((err) => console.log(err));

    writeSync()

    writeSync() is the same as write() except that it is a synchronous action.

    Example:

    bouillon.writeSync();

    read()

    read() is an asynchronous action that returns the data in a JSON parsed format as it is saved on the drive.

    Example using .then():

    bouillon.read()
        .then((data) => {
            // Do something with the data.
        })
        .catch((err) => {
            console.log(err):
        });

    Example using await:

    let data = await bouillon.read().catch((err) => console.log(err));
    // Do something with the data.

    clear()

    Clears all data from the store.

    Example using .then():

    bouillon.clear();

    store

    store simply returns the current local data object. It's the same as if you would access the store as bouillon._store.


    Running Tests

    To run the currently available Bouillon tests, simply use the command below.

    $ npm test
    

    License

    MIT

    Install

    npm i bouillon

    DownloadsWeekly Downloads

    1

    Version

    1.3.1

    License

    MIT

    Unpacked Size

    93.2 kB

    Total Files

    26

    Last publish

    Collaborators

    • robert.corponoi