Convert Figma logo to code with AI

amark logogun

An open source cybersecurity protocol for syncing decentralized graph data.

18,208
1,167
18,208
308

Top Related Projects

1,172

A database of unforgeable append-only feeds, optimized for efficient replication for peer to peer protocols

8,362

Peer-to-Peer Databases for the Decentralized Web

The current, performant & industrial strength version of Holochain on Rust.

22,775

Peer-to-peer hypermedia protocol

17,021

:kangaroo: - PouchDB is a pocket-sized database.

A JSON-like data structure (a CRDT) that can be modified concurrently by different users, and merged again automatically.

Quick Overview

GUN is a decentralized, real-time, graph database engine that runs in JavaScript. It's designed to be lightweight, fast, and scalable, allowing developers to build distributed and offline-first applications. GUN supports peer-to-peer synchronization and can work both in the browser and on servers.

Pros

  • Decentralized architecture, enhancing data resilience and privacy
  • Real-time synchronization across multiple peers
  • Supports offline-first development
  • Lightweight and easy to integrate into existing projects

Cons

  • Learning curve for developers unfamiliar with graph databases
  • Limited support for complex queries compared to traditional databases
  • Potential scalability issues with large datasets
  • Relatively small community compared to mainstream databases

Code Examples

  1. Basic data storage and retrieval:
const gun = Gun();

// Store data
gun.get('user').put({ name: 'Alice', age: 30 });

// Retrieve data
gun.get('user').on((data) => {
  console.log(data);
});
  1. Real-time updates:
const gun = Gun();

// Subscribe to changes
gun.get('counter').on((data) => {
  console.log('Counter value:', data);
});

// Update data
setInterval(() => {
  gun.get('counter').put(Math.floor(Math.random() * 100));
}, 1000);
  1. Working with graph relationships:
const gun = Gun();

// Create nodes and relationships
gun.get('alice').put({ name: 'Alice' });
gun.get('bob').put({ name: 'Bob' });
gun.get('alice').get('friends').set(gun.get('bob'));

// Traverse the graph
gun.get('alice').get('friends').map().on((friend) => {
  console.log('Alice\'s friend:', friend.name);
});

Getting Started

To start using GUN in your project, follow these steps:

  1. Install GUN via npm:

    npm install gun
    
  2. Import and initialize GUN in your JavaScript file:

    import Gun from 'gun';
    const gun = Gun();
    
  3. Start using GUN to store and retrieve data:

    gun.get('myData').put({ hello: 'world' });
    gun.get('myData').on((data) => console.log(data));
    

For more advanced usage and configuration options, refer to the official GUN documentation.

Competitor Comparisons

1,172

A database of unforgeable append-only feeds, optimized for efficient replication for peer to peer protocols

Pros of ssb-db

  • Designed specifically for decentralized social networking applications
  • Robust append-only log structure ensures data integrity and immutability
  • Built-in support for cryptographic signatures and verification

Cons of ssb-db

  • More complex setup and configuration compared to Gun
  • Limited real-time synchronization capabilities
  • Steeper learning curve for developers new to the Secure Scuttlebutt ecosystem

Code Comparison

ssb-db example:

const ssbClient = require('ssb-client')

ssbClient((err, sbot) => {
  sbot.publish({ type: 'post', text: 'Hello, SSB!' }, (err, msg) => {
    console.log(msg)
  })
})

Gun example:

const Gun = require('gun')
const gun = Gun()

gun.get('messages').set({ text: 'Hello, Gun!' })
gun.get('messages').on((data, key) => {
  console.log(data)
})

Both Gun and ssb-db are decentralized database solutions, but they have different focuses and architectures. Gun is designed for real-time, multi-master synchronization with a graph-based data model, while ssb-db is tailored for secure, append-only logs in social networking contexts. Gun offers easier setup and more flexible data structures, whereas ssb-db provides stronger guarantees for data integrity and cryptographic verification.

8,362

Peer-to-Peer Databases for the Decentralized Web

Pros of OrbitDB

  • Built on IPFS, providing robust decentralized storage and content addressing
  • Supports multiple database types (key-value, docs, counters, etc.)
  • More flexible and extensible architecture

Cons of OrbitDB

  • Steeper learning curve due to IPFS integration
  • Less active development and smaller community compared to Gun
  • Potentially slower performance for real-time applications

Code Comparison

OrbitDB:

const orbitdb = await OrbitDB.createInstance(ipfs)
const db = await orbitdb.keyvalue('my-database')
await db.put('key', 'value')
const value = await db.get('key')

Gun:

const gun = Gun()
const db = gun.get('my-database')
db.put({ key: 'value' })
db.get('key').once((value) => console.log(value))

Both projects aim to provide decentralized database solutions, but they differ in their approach and underlying technologies. OrbitDB leverages IPFS for data storage and distribution, offering a more comprehensive decentralized architecture. Gun, on the other hand, focuses on simplicity and real-time synchronization, making it easier to get started but potentially less scalable for complex use cases.

While OrbitDB provides more database types and flexibility, Gun excels in ease of use and real-time capabilities. Developers should consider their specific requirements and the trade-offs between these two options when choosing a decentralized database solution for their projects.

The current, performant & industrial strength version of Holochain on Rust.

Pros of Holochain

  • More scalable architecture for distributed applications
  • Built-in support for data validation and integrity
  • Stronger focus on privacy and user control

Cons of Holochain

  • Steeper learning curve due to complex architecture
  • Smaller community and ecosystem compared to Gun
  • Less mature, still in active development

Code Comparison

Holochain (Rust):

#[hdk_extern]
pub fn create_entry(entry: Entry) -> ExternResult<HeaderHash> {
    create_entry(&entry)
}

Gun (JavaScript):

gun.get('key').put({
  data: 'value'
}, (ack) => {
  console.log('Data saved:', ack);
});

Key Differences

  • Holochain uses Rust for core development, while Gun is primarily JavaScript-based
  • Holochain employs a agent-centric model, whereas Gun focuses on a graph-based data structure
  • Holochain offers more built-in security features and data validation mechanisms
  • Gun provides easier integration with web applications and real-time synchronization

Both projects aim to create decentralized, peer-to-peer networks, but they differ in their approach to data storage, validation, and application architecture. Holochain offers a more comprehensive framework for building distributed applications, while Gun provides a simpler, more flexible solution for real-time data synchronization.

22,775

Peer-to-peer hypermedia protocol

Pros of IPFS

  • More mature and widely adopted project with a larger community and ecosystem
  • Content-addressed storage provides better data integrity and deduplication
  • Supports a wider range of use cases beyond just real-time data synchronization

Cons of IPFS

  • Higher complexity and steeper learning curve for developers
  • Requires more resources and infrastructure to run effectively
  • Less focus on real-time updates and conflict resolution

Code Comparison

IPFS (JavaScript HTTP client):

import { create } from 'ipfs-http-client'

const ipfs = create('http://localhost:5001')
const { cid } = await ipfs.add('Hello world')
console.log(cid.toString())

Gun:

import Gun from 'gun'

const gun = Gun()
gun.get('greetings').put({ message: 'Hello world' })
gun.get('greetings').on((data) => console.log(data.message))

Key Differences

  • IPFS focuses on content-addressed storage and distribution, while Gun emphasizes real-time data synchronization
  • IPFS uses a distributed hash table (DHT) for content discovery, whereas Gun relies on a peer-to-peer mesh network
  • Gun provides built-in conflict resolution and eventual consistency, which IPFS leaves to higher-level applications
  • IPFS has a more modular architecture with separate components for storage, networking, and naming, while Gun integrates these features more tightly
17,021

:kangaroo: - PouchDB is a pocket-sized database.

Pros of PouchDB

  • Better documentation and more extensive API
  • Stronger focus on data synchronization with CouchDB
  • Larger community and more widespread adoption

Cons of PouchDB

  • Heavier and more complex than Gun
  • Primarily designed for document-based data, less flexible for graph-like structures

Code Comparison

PouchDB:

var db = new PouchDB('mydb');
db.put({
  _id: 'dave@gmail.com',
  name: 'David',
  age: 69
});
db.changes().on('change', function() {
  console.log('Ch-ch-changes');
});

Gun:

var gun = Gun();
gun.get('user').put({
  name: 'David',
  age: 69
});
gun.get('user').on(function(data, key) {
  console.log('Update:', data);
});

Both PouchDB and Gun are JavaScript databases for web and mobile applications. PouchDB excels in CouchDB synchronization and has more extensive documentation, while Gun offers a lighter-weight solution with real-time synchronization capabilities. PouchDB is better suited for document-based data structures, whereas Gun provides more flexibility for graph-like data. The code examples demonstrate basic data storage and change detection in both libraries, highlighting their different approaches to handling data and updates.

A JSON-like data structure (a CRDT) that can be modified concurrently by different users, and merged again automatically.

Pros of Automerge

  • Designed specifically for collaborative editing, with built-in conflict resolution
  • Supports a wider range of data types, including text, lists, and nested objects
  • More actively maintained with regular updates and improvements

Cons of Automerge

  • Generally slower performance compared to Gun, especially for large datasets
  • Requires more setup and configuration for complex use cases
  • Less flexible for real-time applications outside of collaborative editing

Code Comparison

Automerge example:

import * as Automerge from 'automerge'

let doc1 = Automerge.init()
doc1 = Automerge.change(doc1, doc => {
  doc.list = ['item1']
})

Gun example:

import Gun from 'gun'

const gun = Gun()
gun.get('list').put(['item1'])

Both Gun and Automerge are open-source JavaScript libraries for building distributed/decentralized applications, but they have different focuses and strengths. Gun is more general-purpose and optimized for real-time applications, while Automerge specializes in collaborative editing with strong consistency guarantees. The choice between them depends on the specific requirements of your project, such as data types, performance needs, and the level of conflict resolution required.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Build Gitter

GUN is an ecosystem of tools that let you build community run and encrypted applications - like an Open Source Firebase or a Decentralized Dropbox.

The Internet Archive and 100s of other apps run GUN in-production.

  • Multiplayer by default with realtime p2p state synchronization!
  • Graph data lets you use key/value, tables, documents, videos, & more!
  • Local-first, offline, and decentralized with end-to-end encryption.

Decentralized alternatives to Zoom, Reddit, Instagram, Slack, YouTube, Stripe, Wikipedia, Facebook Horizon and more have already pushed terabytes of daily P2P traffic on GUN. We are a friendly community creating a free fun future for freedom:

Quickstart

GUN is super easy to get started with:

  • Try the interactive tutorial in the browser (5min ~ average developer).
  • Or npm install gun and run the examples with cd node_modules/gun && npm start (5min ~ average developer).

Note: If you don't have node or npm, read this first. If the npm command line didn't work, you may need to mkdir node_modules first or use sudo.

<script src="https://cdn.jsdelivr.net/npm/gun/gun.js"></script>
<script>
// import GUN from 'gun'; // in ESM
// GUN = require('gun'); // in NodeJS
// GUN = require('gun/gun'); // in React
gun = GUN();

gun.get('mark').put({
  name: "Mark",
  email: "mark@gun.eco",
});

gun.get('mark').on((data, key) => {
  console.log("realtime updates:", data);
});

setInterval(() => { gun.get('mark').get('live').put(Math.random()) }, 9);
</script>
  • Or try something mind blowing, like saving circular references to a table of documents! (play)
cat = {name: "Fluffy", species: "kitty"};
mark = {boss: cat};
cat.slave = mark;

// partial updates merge with existing data!
gun.get('mark').put(mark);

// access the data as if it is a document.
gun.get('mark').get('boss').get('name').once(function(data, key){
  // `once` grabs the data once, no subscriptions.
  console.log("Mark's boss is", data);
});

// traverse a graph of circular references!
gun.get('mark').get('boss').get('slave').once(function(data, key){
  console.log("Mark is the cat's slave!", data);
});

// add both of them to a table!
gun.get('list').set(gun.get('mark').get('boss'));
gun.get('list').set(gun.get('mark'));

// grab each item once from the table, continuously:
gun.get('list').map().once(function(data, key){
  console.log("Item:", data);
});

// live update the table!
gun.get('list').set({type: "cucumber", goal: "jumping cat"});

Want to keep building more? Jump to THE DOCUMENTATION!

About

First & foremost, GUN is a community of the nicest and most helpful people out there. So I want to invite you to come tell us about what you are working on & wanting to build (new or old school alike! Just be nice as well.) and ask us your questions directly. :)


Watch the 100 second intro!

The GUN ecosystem stack is a collection of independent and modular tools covering everything from CRDT conflict resolution, cryptographic security & encryption, radix storage serialization, mesh networking & routing algorithms, to distributed systems correctness & load testing, CPU scheduled JSON parser to prevent UI lag, and more!

On that note, let's get some official shout outs covered first:

Support

Thanks to:

              

Robert Heessels, Lorenzo Mangani, NLnet Foundation, Sam Liu, Daniel Dombrowsky, Vincent Woo, AJ ONeal, Bill Ottman, Mike Lange, Sean Matheson, Alan Mimms, Dário Freire, John Williamson, Robin Bron, Elie Makhoul, Mike Staub, Bradley Matusiak, Jeff Cook, Nico, Aaron Artille, Tim Robinson, Fabian Stamm, Mike Staub, Hunter Owens, Jacob Millner, Gerrit Balindt, Gabriel Lemon, Murage Martin, Jason Stallings

History

GUN was created by Mark Nadal in 2014 after he had spent 4 years trying to get his collaborative web app to scale up with traditional databases.

After he realized Master-Slave database architecture causes one big bottleneck, he (as a complete newbie outsider) naively decided to question the status quo and shake things up with controversial, heretical, and contrarian experiments:

The NoDB - no master, no servers, no "single source of truth", not built with a real programming language or real hardware, no DevOps, no locking, not just SQL or NoSQL but both (all - graphs, documents, tables, key/value).

The goal was to build a P2P database that could survive living inside any browser, and could correctly sync data between any device after assuming any offline-first activity.

Technically, GUN is a graph synchronization protocol with a lightweight embedded engine, capable of doing 20M+ API ops/sec in just ~9KB gzipped size.

Documentation

API reference

Tutorials

Examples

GraphQL

Electron

React & Native

Vue

Svelte

Webcomponents

CAP Theorem Tradeoffs

How Data Sync Works

How GUN is Built

Crypto Auth

Modules

Roadmap

This would not be possible without community contributors, big shout out to:

ajmeyghani (Learn GUN Basics with Diagrams); anywhichway (Block Storage); beebase (Quasar); BrockAtkinson (brunch config); Brysgo (GraphQL); d3x0r (SQLite); forrestjt (file.js); hillct (Docker); JosePedroDias (graph visualizer); JuniperChicago (cycle.js bindings); jveres (todoMVC); kristianmandrup (edge); Lightnet (Awesome Vue User Examples & User Kitchen Sink Playground); lmangani (Cytoscape Visualizer, Cassandra, Fastify, LetsEncrypt); mhelander (SEA); omarzion (Sticky Note App); PsychoLlama (LevelDB); RangerMauve (schema); robertheessels (gun-p2p-auth); rogowski (AXE); sbeleidy; sbiaudet (C# Port); Sean Matheson (Observable/RxJS/Most.js bindings); Shadyzpop (React Native example); sjones6 (Flint); RIP Stefdv (Polymer/web components); zrrrzzt (JWT Auth); xmonader (Python Port);

I am missing many others, apologies, will be adding them soon! This list is infinitely old & way out of date, if you want to be listed in it please make a PR! :)

Testing

You will need to npm install -g mocha first. Then in the gun root folder run npm test. Tests will trigger persistent writes to the DB, so subsequent runs of the test will fail. You must clear the DB before running the tests again. This can be done by running rm -rf *data* command in the project directory.

Shims

These are only needed for NodeJS & React Native, they shim the native Browser WebCrypto API.

If you want to use SEA for User auth and security, you will need to install:

npm install @peculiar/webcrypto --save

Please see our React Native docs for installation instructions!

Then you can require SEA without an error:

GUN = require('gun/gun');
SEA = require('gun/sea');

Deploy

Note: The default examples that get auto-deployed on npm start CDN-ify all GUN files, modules, & storage.

Note: Moving forward, AXE will start to automatically cluster your peer into a shared DHT. You may want to disable this to run an isolated network.

Note: When deploying a web application using GUN on a cloud provider, you may have to set CI=false in your .env. This prevents GUN-specific warnings from being treated as errors when deploying your app. You may also resolve this by modifying your webpack config to not try to build the GUN dependencies.

To quickly spin up a GUN relay peer for your development team, utilize Heroku, Docker, or any others listed below. Or some variant thereof Dokku, K8s, etc. ! Or use all of them so your relays are decentralized too!

Linux

SSH into the home directory of a clean OS install with sudo ability. Set any environment variables you need (see below), then do:

curl -o- https://raw.githubusercontent.com/amark/gun/master/examples/install.sh | bash

Read install.sh first! If curl is not found, copy&paste the contents of install.sh into your ssh.

You can now safely CTRL+A+D to escape without stopping the peer. To stop everything killall screen or killall node.

Environment variables may need to be set like export HTTPS_CERT=~/cert.pem HTTPS_KEY=~/key.pem PORT=443. You can also look at a sample nginx config. For production deployments, you probably will want to use something like pm2 or better to keep the peer alive after machine reboots.

Dome

Deploy GUN in one-click with Dome and receive a free trial:

Deploy to Dome

Heroku

Deploy

Heroku deletes your data every 15 minutes, one way to fix this is by adding cheap storage.

Or:

git clone https://github.com/amark/gun.git
cd gun
heroku create
git push -f heroku HEAD:master

Then visit the URL in the output of the 'heroku create' step, in a browser. Make sure to set any environment config vars in the settings tab.

Zeet.co

Deploy

Then visit the URL in the output of the 'now --npm' step, in your browser.

Docker

Warning: Docker image is community contributed and may be old with missing security updates, please check version numbers to compare.

Docker Automated build Docker Pulls Docker Stars

Pull from the Docker Hub . Or:

docker run -p 8765:8765 gundb/gun

Or build the Docker image locally:

git clone https://github.com/amark/gun.git
cd gun
docker build -t myrepo/gundb:v1 .
docker run -p 8765:8765 myrepo/gundb:v1

Or, if you prefer your Docker image with metadata labels (Linux/Mac only):

npm run docker
docker run -p 8765:8765 username/gun:git

Then visit http://localhost:8765 in your browser.

License

Designed with ♥ by Mark Nadal, the GUN team, and many amazing contributors.

Openly licensed under Zlib / MIT / Apache 2.0.

FOSSA Status

YouTube . Twitter

NPM DownloadsLast 30 Days