usable-gun: Gun with best practices

The Gun database architecture is very cool, you can read about it on gun.eco.

Unfortunately, the source code for Gun is written with a lot of bad practices that make it impractical to use in a project. usable-gun is a wrapper around Gun that fixes the following problems:

How to use

See the API reference for more details.

usable-gun follows gun's structure to make it as easy as possible to port between the two libraries.

If you have a common setup like this:

import Gun from "gun";
import SEA from "gun/sea";
import radix from "gun/lib/radix.js";

const gun = new Gun({
  peers: [],
});

gun // Your Gun instance
SEA // Your SEA library

You can port it like so:

import { GunEnvironment } from "usable-gun";
import { defaultBrowserPlugin } from "usable-gun"; // Equivalent to importing "gun" in a browser
import seaPlugin from "usable-gun/sea";
import radixPlugin from "usable-gun/lib/radix.js";

const gunEnvironment = new GunEnvironment({
  environmentHint: "browser",
});
await gunEnvironment.usePlugins([
  defaultBrowserPlugin,
  seaPlugin,
  radixPlugin,
]);

const gun = new gunEnvironment.library.Gun({
  peers: [],
});
const SEA = gunEnvironment.library.SEA;

gun // Your Gun instance
SEA // Your SEA library

Or if you want to run it on the server side, you can write:

import { GunEnvironment } from "usable-gun";
import serverPlugin from "usable-gun/lib/server.js"; // Equivalent to importing "gun" in a nodejs process

const gunEnvironment = new GunEnvironment({
  environmentHint: "server",
});
await gunEnvironment.usePlugins([
  serverPlugin,
]);

const gun = new gunEnvironment.exports.lib.server({
  peers: [],
});
const SEA = gunEnvironment.exports.sea;

gun // Your Gun instance
SEA // Your SEA library

You can also load Gun in a few other ways, see the API reference for more details.

How it works

If you import the original Gun code, it will immediately execute and attach itself to your window property. This is bad practice.

usable-gun's GunEnvironment is a sandbox that emulates a browser context with the window property. All Gun code is wrapped into plugins that can be executed inside the sandbox. Anything that Gun used to set on the window property is now set on GunEnvironment.library. Server-side code works slightly differently, it will export values instead, and they can be found on GunEnvironment.exports.

Original gun code also mutated common properties such as String and setTimeout. These mutations are also available as properties on GunEnvironment.library.

To read more about how the plugins work, refer to plugins.

Environment support

The primary focus of this package is to support the Gun library running in browsers. The secondary focus is to support the Gun library running on servers (Node, Deno, Bun). You can expect both of these use cases to work well.

Some of the more exotic plugins, such as plugins that render components directly in a webpage, are not a focus. It is however possible to get them to work, if you analyse which properties they are trying to access, and write a plugin that makes those properties available on GunEnvironment.library. To read more about how plugins work, refer to plugins.

Supported environments:

Deno support is through NPM.

If you want to support older environments, you can transpile your project with Babel.

FAQ

Can I use usable-gun with normal gun clients and servers?

Yes! usable-gun is designed to behave exactly like the original gun code does, so that it is fully interoperable.

How do I make [insert name] work with usable-gun?

Any code or plugin that works with Gun is probably trying to access usable-gun in the global scope, where it doesn't exist. To make the code work again, you need to write a plugin for usable-gun's GunEnvironment.

To know more about this, refer to plugins.

How do I know which version of gun and usable-gun I am using?

usable-gun combines the version from gun and usable-gun to make it clear what you are using.

The pattern is: gun version0usable-gun version.

So if you see the version 0.202003.123902, that means:

gun version is: 0.2020.1239.

usable-gun version is: 0.3.2.

When gun goes out of beta, usable-gun will also go out of beta, or better yet, won't be necessary anymore. Finger's crossed.

Is it a lot of work when a new version of gun is released?

The conversion from original gun code to usable-gun code is fully automated, so usable-gun should be able to update with fairly little work, depending on the scale of the update.

Why not commit these improvements to gun?

It has been my experience that the Gun team does not place as much value in best practices as I do. It has also been my experience that comitting something to the core Gun code can be a complicated process.

I needed something that I could control to work exactly like I wanted it to, and therefore I decided that I had to have my own code base.

If anyone on the Gun team is interested in porting some of these improvements to Gun, I would be eager to help!