reticle
v0.3.0
Published
Scope your gunDB apps
Downloads
15
Readme
Reticle
Put a scope on gunDB.
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.
Including
Node.js
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
require('reticle')
Browser
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.
API
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
Examples
Using two instances without collision
var fleetPlayers, tracePlayers;
fleetPlayers = Gun().scope('battlefleet').get('players')
tracePlayers = Gun().scope('trace').get('players')
fleetPlayers.put({
'Player 0': 'Bob'
})
tracePlayers.put({
'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.
Support
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.