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:

Bad practice	Consequences	Fixed by usable-gun?
Only runs on main thread	A website's interface can freeze while Gun is syncing You cannot run two instances of Gun simultaneously Cannot have two users logged in simultaneously Cannot sync with two servers independently No simple way to stop Gun and clean up after it	✅ Yes. Code can run in Workers and multiple instances can run in the same context
Mutates global objects	Gun can interfere with how other code works Other code can interfere with how Gun works Interference can be hard to detect Code can be hard to read and debug	✅ Yes. Code runs in isolated modules
Makes heavy use of sideeffects	Code can be hard to read and debug Standard code optimization strategies cannot be used	🟡 Partial. Sideeffects cannot be eliminated, but code is transformed to make it clear when they are used
Poor support for ES6 modules	Can be hard to import Can behave incorrectly when imported Will crash some bundlers	✅ Yes. Code is transformed to run in ES6 modules
Uses a custom, undocumented bundler	Standard code optimization strategies cannot be used Code is hard to read and debug	✅ Yes. Code is "unbundled" into standard ES6 modules
Uses Math.random for some cryptographic operations	Namespace collisions can occur Can theoretically be exploited	🟡 Almost. Code uses a much safer strategy, but cannot be perfectly fixed without changes to Gun's behavior
Logs messages directly to console	No way to disable logs for end-users No way to collect logs from end-users No way to filter logs	✅ Yes. Code logs to a debugger provided by the developer
Uses unnecessary polyfills	Bundle size is ~250% larger than necessary	✅ Yes. Polyfills are replaced with native calls
Does not use modern Javascript features (ES6+)	Code runs slower Code is hard to read and debug	🟡 Partial. Code is automatically transformed to use newer features where possible, but many new features require manual rewrites of the code
Source code is heavily truncated	Code is very hard to read and debug	🟡 Partial. Code is transformed to follow a more readable syntax, and some variables are renamed to make their purpose clear

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:

Chromium	Firefox	Safari	Node.js	Deno
✅ 89	✅ 90	✅ 15.0	✅ 20.0	✅ 1.31

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!