npm i reticle


Put a scope on your gunDB data

by Jesse Gibson

0.3.0 (see all)License:(Zlib OR MIT OR Apache-2.0)TypeScript:Not Found
npm i reticle


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.

No alternatives found
No tutorials found
Add a tutorial
No dependencies found

Rate & Review

No reviews found
Be the first to rate