Newly Potted Mandrakes

    gun-level

    6.0.4 • Public • Published

    gun-level

    Travis npm Gitter

    LevelDB is awesome. It's awesomer with gun.

    Overview

    GunDB is a graph database engine with real-time sync and offline-editing. Although gun comes with storage and sync out of the box, it's design is pluggable, so you can still use your favorite storage backend or transport layer by using an adapter.

    LevelDB operates on a similar paradigm. It ships with an interface called LevelUP that gives all the methods you'd expect from a storage engine (like get, put, batch, etc.) and forwards those to a lower-level database (it uses LevelDOWN by default).

    Arguably the most valuable aspect of level is it's ecosystem. There are tons are plugins, backends, dashboards, and utilities made specifically for level. It's kinda like a database buffet.

    Here, check out their list of modules!

    If you're feeling stressed, don't worry. LevelDB comes out of the box as a quite capable database, and if you don't want to dabble with plugins and configs, there's no need.

    So what happens when you combine Level with GunDB? You get the power and control of level right alongside the ease of gun.

    That's what this library does.

    Usage

    To get started, you'll first need to install gun-level.

    If you're unfamiliar with npm, you can get started here

    $ npm install --save gun-level gun

    Now require them from your node project.

    // Import the `Gun` library
    const Gun = require('gun')
     
    // Imported for side effects, adds level adapters.
    // MUST be required after Gun to work
    require('gun-level')

    Once they're imported you can create a new Gun database:

    const gun = new Gun({
        // We'll put options here in a moment.
    })

    Sweet, you're set up! However, gun-level won't do anything unless you pass it a levelDB instance through the Gun constructor. For that, you'll need to download the Node levelup package.

    There are some differences between levelup v1 and v2 so be sure to note which version you're using.

    levelup v1

    $ npm install --save levelup leveldown

    If you get a build error at this step, replace all examples of leveldown with jsondown.

    // Import the two libraries
    const levelup = require('levelup')
    const leveldown = require('leveldown')
     
    // Create a new level instance which saves
    // to the `data/` folder.
    const levelDB = levelup('data', {
        db: leveldown,
    })

    levelup >v2

    Note that Levelup v2 only supports Node >6.

    $ npm install --save levelup leveldown encoding-down
    // Import the required libraries
    const levelup = require('levelup')
    const encode = require('encoding-down')
    const leveldown = require('leveldown')
     
    // Create a new level instance which saves
    // to the `data/` folder.
    const levelDB = levelup(
        encode(
            leveldown('data'),
            { valueEncoding: 'json' }
        )
    )

    Instantiating Gun with Level

    Now we can pass our new levelDB instance to the Gun constructor.

    const Gun = require('gun')
    require('gun-level')
     
    // ... instantiate LevelDB per above
     
    // Pass LevelDB instance into Gun
    const gun = new Gun({
        level: levelDB
    })

    Done! Now your gun database will store it's graph in your Level DB!

    Let's try a few things...

    const bob = gun.get('bob').put({ name: 'Bob' })
    const dave = gun.get('dave').put({ name: 'Dave' })
     
    // Write a fun circular reference.
    bob.get('friend').put(dave)
    dave.get('friend').put(bob)
     
    // Print the data!
    bob.get('friend').val(friend => {
        console.log(friend.name) // Dave
    });
     
    // Now with a circular reference
    bob.get('friend').get('friend').val(friend => {
        console.log(friend.name) // Bob
    });

    That's pretty much all there is to the gun-level API. If you're unfamiliar with gun's API, here's a good reference.

    Advanced Levelry

    You've seen the basics, but it's not enough. You crave more power.

    To exchange backends with level, like Riak, Mongo, IndexedDB, etc., you can find the official list of storage backends here. Usually it's just a matter of passing the module as the db option to levelup. Here's an example with MongoDB using mongodown:

    const levelup = require('levelup')
    const mongoDown = require('mongodown')
     
    // Initialize Level
    const levelDB = levelup('localhost:27017/YOUR_COLLECTION_NAME', {
        db: mongoDown,
    })
     
    // Initialize Gun
    const gun = new Gun({
        level: levelDB,
        file: false,
    })

    Even if you're content with the default levelDB setup, I really recommend you scan this list of plugins. It's inspiring what the community has built.

    gun-level will try to read and write values as json. If you're having trouble getting a plugin to work, or keep seeing "[object Object]", make sure it's using the json value encoding.

    Getting Support

    If you're running into problems, feel free to either post an issue on GitHub or chat with us humans in the Gitter channel.

    Installing from Source

    Clone the repo and install the dependencies:

    $ git clone https://github.com/PsychoLlama/gun-level.git
    cd gun-level
    $ npm install

    Running Tests

    # In directory `gun-level` 
    $ npm test

    Building

    $ npm run build
    # Compiles to folder `dist/` 

    Contributors

    • Project owner @PsychoLlama
    • Code contributor @swhgoon
    • The friendly @greenkeeperio-bot

    Sponsored by the fabulous people at GunDB.

    Install

    npm i gun-level

    DownloadsWeekly Downloads

    15

    Version

    6.0.4

    License

    MIT

    Last publish

    Collaborators

    • psychollama