Neolithic Populous Metropolis


    0.3.0 • Public • Published


    Put a scope on gunDB.

    npmTravis branchGitter

    What it is

    Reticle is a tool built for gunDB

    By default, gun's data is global. If you use the same key by accident on a different app, both datasets will merge into one frankensteinian nightmare. Reticle solves this by namespacing your keys under a hashed string, preventing otherwise gruesome conflicts from ever happening.

    How it works

    You can scope your databases under a name, like Todo List, and Reticle will produce a hashed string ('7b3ozc') and automatically upgrade your context to use that new namespace.



    To use Reticle in node, require('reticle') in your app. Reticle is version agnostic when it comes to gunDB, and since you may be using multiple versions of gun with node, Reticle needs an explicit reference to the constructor you want to extend.

    var Gun = require('gun')
    // reticle automatically upgrades gun


    To use Reticle in the browser, you can include it as a script tag.

    <script src="reticle.min.js"></script>

    Since Gun is exported to the global namespace, Reticle knows what version you're using and can automatically attach itself.


    Reticle exposes two methods through Gun...

    • one on the constructor: Gun.scope
    • one on each instance: gun.scope

    To set a scope for every gun instance you create, use the constructor method.

    Gun.scope('Todo List')
    // both are scoped under "Todo List"
    var list = Gun().get('list')
    var items = Gun().get('list/items')

    To scope just one instance, use the instance method.

    var gun = Gun().scope('Todo List').get('list/items');

    Once the scope has been set, it will remain the same until changed again.

    Scope names are case sensitive


    Using two instances without collision

    var fleetPlayers, tracePlayers;
    fleetPlayers = Gun().scope('battlefleet').get('players')
    tracePlayers = Gun().scope('trace').get('players')
      'Player 0': 'Bob'
      'Player 0': 'Dave'
    fleetPlayers.path('Player 0').val() // "Bob"
    tracePlayers.path('Player 0').val() // "Dave"

    Edge cases

    Reticle will try to convert input to a string so it can hash it. If the value it's given is a isn't a string, Reticle will try to convert it. If the value is falsy, gun will revert to it's global behavior. For example, if you call .scope with null or empty string "", your namespace is global. There is no prefix.

    Previous versions of gun have mixed support for the uuid option in the gun constructor. To be sure the UUIDs are scoped properly, the Gun.text.random function was overloaded. If you're using that function, you may notice the output being prepended with a scope.


    If you find any problems or know of a way to improve Reticle (or gun for that matter), send us a message on Gitter. We're almost always on that channel.


    npm i reticle

    DownloadsWeekly Downloads





    (Zlib OR MIT OR Apache-2.0)

    Last publish


    • avatar