@gooddollarcommons/gun-flint
v0.3.1
Published
Micro-framework for building Gun adapters
Downloads
5
Readme
Gun-Flint: Easy Gun Adapters
Gun-Flint is a package that makes it easy to write adapters to connect your Gun database to various services (like databases, Pusher, etc.). Gun-Flint is not itself an adapter.
Installation
npm install gun-flint
or
yarn add gun-flint
A Key Decision: Node, Key:Value, Delta
Since Gun is a graph database, its data structure requires some special consideration. Gun-Flint attempts to provide as much flexibility for the adapter developer to store data in a format that makes sense for the storage system you are using.
Building your Gun-Flint gives you an advantage of allowing Flint to ensure that the data coming from Gun reaches your adapter in a consistent format and returns data to Gun in a format that it recognizes.
Node Storage
get
request expect to read an entire Gun node; put
requests write an entire node.
Pros:
- Easiest to implement
- Flint handles merging of existing nodes with a delta on write so little chance of data corruption during conflict resolution.
Cons:
- Slower performance (requires a read > merge for every write); this is especially problematic if your data requires large nodes (e.g., a
users
node with millions ofuser
s) - Large nodes could overwhelm memory and cause crashes; if you anticipate this, consider Key:Value storage with streaming.
When to Use: Most/all nodes are small; nodes are frequently created; optimal for document-based databases (e.g., MongoDB; Postgres)
Example: gun-mongo
Key:Value
get
request returns an array/list of nodes properties; put
requests write batch updates to specific node's key:value pairs.
Pros:
- Easy to implement
- Faster than full-node storage
- Doesn't require any additional concerns for conflict resolution
Cons:
- Every key:value pair (node property) would presumably require a separate record in storage (although not necessarily)
- Read requests require retrieval of multiple records
When to Use: Nodes are small/medium in size; some large nodes; nodes are frequently updated
Example: gun-mongo-key
Delta Storage
get
request return an entire node, formatted in a way Gun recognizes; put
requests receive a delta (diff) of node properties as well as conflict-resolution state indicators.
Pros:
- Most flexibility for how you store a delta
- High performance possibility, depending on how you implement storage.
Cons:
- Most difficult to implement, and incorrect implementation can lead to data corruption during conflict resolution.
When to Use: You need total control of storage format and one of the above formats is not sufficient.
Usage
Whichever storage method you decide, your adapter needs to only implement three methods: opt, get, put. See the documentation for each storage method as the exact API depends on the method selected.
Stripped down, the API looks like this:
const {Flint, NodeAdapter} = require('gun-flint');
const myGunAdapter = new NodeAdapter({
opt: function(context, options) {
// etc
},
get: function(key, field, done) {
// handle read
},
put: function(node, done) {
// handle write
}
});
Flint.register(myGunAdapter);
Using Your Adapter
In the end, the good users of your adapter should install it like this:
var Gun = require('gun');
// Adapter must come after requiring Gun but before `new Gun`
require('your-awesome-adapter');
// Adapters all set up? Instantiate Gun.
var gun = new Gun({
myAwesomeAdapter: {
key: "This gets passed into the `opt` call when gun is initialized. Useful for allowing those who use your adapter to pass in DB drivers of the like."
}
});
Testing Your Adapter
Flint comes packaged with an integration testing suite. See full documentation here.
Performance Profiling
Flint comes packaged with an performance suite that will run against your adapter. See full documentation here.
Troubleshooting
If your adapter's opt
function is never called, or when it is called, it doesn't have options that you passed to the constructor, here are some steps:
- Do NOT list Gun in your list of dependencies. You can list it in
peerDependencies
ordevDependencies
, especially the later if you need it for testing your adapter. - Make sure Gun is not installed globally (run
npm list -g --depth=0
to check), andnpm uninstall -g gun
if it is. - Delete your
node_modules
and install a fresh set (preferably from a lockfile)