Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/atjn/usable-gun

Gun with best practices
https://github.com/atjn/usable-gun

gun gundb

Last synced: 3 months ago
JSON representation

Gun with best practices

Awesome Lists containing this project

README 

        
# `usable-gun`: Gun with best practices

The Gun database architecture is very cool, you can read about it on [gun.eco](https://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](./docs/api.md) 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:



```js

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:



```js

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:



```js

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](./docs/api.md) 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](./docs/plugins.md).



# 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](./docs/plugins.md).



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](https://babeljs.io/).



# 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](./docs/plugins.md).



## 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 version`0`usable-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!