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 |
|
✅ Yes. Code can run in Workers and multiple instances can run in the same context |
Mutates global objects |
|
✅ Yes. Code runs in isolated modules |
Makes heavy use of sideeffects |
|
🟡 Partial. Sideeffects cannot be eliminated, but code is transformed to make it clear when they are used |
Poor support for ES6 modules |
|
✅ Yes. Code is transformed to run in ES6 modules |
Uses a custom, undocumented bundler |
|
✅ Yes. Code is "unbundled" into standard ES6 modules |
Uses Math.random for some cryptographic operations |
|
🟡 Almost. Code uses a much safer strategy, but cannot be perfectly fixed without changes to Gun's behavior |
Logs messages directly to console |
|
✅ Yes. Code logs to a debugger provided by the developer |
Uses unnecessary polyfills |
|
✅ Yes. Polyfills are replaced with native calls |
Does not use modern Javascript features (ES6+) |
|
🟡 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 |
|
🟡 Partial. Code is transformed to follow a more readable syntax, and some variables are renamed to make their purpose clear |
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.
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.
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.
Yes! usable-gun
is designed to behave exactly like the original gun
code does, so that it is fully interoperable.
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.
usable-gun
combines the version from gun
and usable-gun
to make it clear what you are using.
The pattern is: gun version
0usable-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.
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.
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!